Merge pull request #3 from nick1udwig/hf/clean-up

clean up + other many improvements

Author: humanizersequel

.gitignore

@@ -1,15 +1,17 @@
 # Rust build artifacts
 /target/
 **/*.rs.bk
-Cargo.lock
 
 # Generated files
 /api/
 /target/
 
 # Package directory - IMPORTANT: This is intentionally NOT ignored
-# The pkg directory contains the compiled app and should be committed
+# The pkg directory contains compiled AND uncompiled; don't commit compiled
 # /pkg/
+/pkg/*zip
+/pkg/*wasm
+/pkg/ui
 
 # UI dependencies and build
 /ui/node_modules/
@@ -30,4 +32,4 @@ Cargo.lock
 
 # Temporary files
 *.tmp
-*~
+*~

README.md

@@ -1,17 +1,43 @@
 # Hyperware Skeleton App
 
-A minimal, well-commented skeleton application for the Hyperware platform using the Hyperapp framework. This skeleton provides a starting point for building Hyperware applications with a React/TypeScript frontend and Rust backend.
+A minimal, well-commented skeleton application for the Hyperware platform using the Hyperapp framework.
+This skeleton provides a starting point for building Hyperware applications with a React/TypeScript frontend and Rust backend.
 
-## Features
+Either prompt your favorite LLM directly with instructions on how to build your app or add them to `instructions.md`!
 
-- ✅ Minimal working Hyperware app structure
-- ✅ Well-commented code explaining key concepts
-- ✅ Basic state management with counter example
-- ✅ HTTP endpoints demonstration
-- ✅ React/TypeScript UI with Zustand state management
-- ✅ Error handling and loading states
-- ✅ Automatic WIT generation via hyperprocess macro
-- ✅ Persistent state across app restarts
+Recommended usage:
+- Clone this repo & clean up git-related stuff:
+  ```bash
+  git clone https://github.com/humanizersequel/hyperapp-skeleton.git
+  cd hyperapp-skeleton
+  rm -rf .git
+  ```
+- Write a detailed document describing what you want your app to do.
+  Save this in `instructions.md`.
+- Prompt your LLM agent (i.e. Claude Code) with something like:
+  ```
+  ## GOAL
+
+  <One-sentence description of app here>
+
+  ## Instructions
+
+  Read the README.md and follow the Instructions > Create an implementation plan
+  ```
+
+- After creating an implementation plan, clear your LLM agent's context and then prompt it again with something like:
+
+  ```
+  ## GOAL
+
+  <One-sentence description of app here>
+
+  ## Instructions
+
+  Read the README.md and follow the Instructions > Implement the plan
+  ```
+
+The rest of this document is aimed at *LLMs* not *humans*.
 
 ## Quick Start
 
@@ -23,33 +49,33 @@ A minimal, well-commented skeleton application for the Hyperware platform using
 
 ### Building
 
-   ```bash
-   kit b --hyperapp
-   ```
-
+Always build with
+```bash
+kit build --hyperapp
+```
 
 ## Project Structure
 
 ```
 hyperapp-skeleton/
-├── Cargo.toml              # Workspace configuration
-├── metadata.json           # App metadata
-├── skeleton-app/           # Main Rust process
-│   ├── Cargo.toml         # Process dependencies
+├── Cargo.toml          # Workspace configuration
+├── metadata.json       # App metadata
+├── skeleton-app/       # Main Rust process
+│   ├── Cargo.toml      # Process dependencies
 │   └── src/
-│       ├── lib.rs         # Main app logic (well-commented)
-│       └── icon           # App icon file
-├── ui/                    # Frontend application
-│   ├── package.json       # Node dependencies
-│   ├── index.html         # Entry point (includes /our.js)
-│   ├── vite.config.ts     # Build configuration
+│       ├── lib.rs      # Main app logic (well-commented)
+│       └── icon        # App icon file
+├── ui/                 # Frontend application
+│   ├── package.json    # Node dependencies
+│   ├── index.html      # Entry point (includes /our.js)
+│   ├── vite.config.ts  # Build configuration
 │   └── src/
-│       ├── App.tsx        # Main React component
-│       ├── store/         # Zustand state management
-│       ├── types/         # TypeScript type definitions
-│       └── utils/         # API utilities
-├── api/                   # Generated WIT files (after build)
-└── pkg/                   # Built package output
+│       ├── App.tsx     # Main React component
+│       ├── store/      # Zustand state management
+│       ├── types/      # TypeScript type definitions
+│       └── utils/      # API utilities
+├── api/                # Generated WIT files (after build)
+└── pkg/                # The final build product, including manifest.json, scripts.json and built package output
 ```
 
 ## Key Concepts
@@ -65,10 +91,10 @@ The `#[hyperprocess]` macro is the core of the Hyperapp framework. It provides:
 ### 2. Required Patterns
 
 #### HTTP Endpoints
-ALL HTTP endpoints MUST accept a `_request_body: String` parameter:
+ALL HTTP endpoints MUST be tagged with `#[http]`:
 ```rust
 #[http]
-async fn my_endpoint(&self, _request_body: String) -> String {
+async fn my_endpoint(&self) -> String {
     // Implementation
 }
 ```
@@ -79,7 +105,7 @@ Parameters must be sent as tuples for multi-parameter methods:
 // Single parameter
 { "MethodName": value }
 
-// Multiple parameters  
+// Multiple parameters
 { "MethodName": [param1, param2] }
 ```
 
@@ -92,9 +118,11 @@ MUST be included in index.html:
 ### 3. State Persistence
 
 Your app's state is automatically persisted based on the `save_config` option:
-- `EveryMessage`: Save after each message (safest)
-- `OnInterval(n)`: Save every n seconds
+- `OnDiff`: Save when state changes (strongly recommended)
 - `Never`: No automatic saves
+- `EveryMessage`: Save after each message (safest; slowest)
+- `EveeyNMessage(u64)`: Save every N messages received
+- `EveeyNSeconds(u64)`: Save every N seconds
 
 ## Customization Guide
 
@@ -121,7 +149,7 @@ async fn my_method(&mut self, request_body: String) -> Result<String, String> {
 
 ### 3. Add Capabilities
 
-Add system permissions in `manifest.json`:
+Add system permissions in `pkg/manifest.json`:
 ```json
 "request_capabilities": [
     "homepage:homepage:sys",
@@ -130,17 +158,24 @@ Add system permissions in `manifest.json`:
 ]
 ```
 
+These are required to message other local processes.
+They can also be granted so other local processes can message us.
+There is also a `request_networking` field that must be true to send messages over the network p2p.
+
 ### 4. Update Frontend
 
 1. Add types in `ui/src/types/skeleton.ts`
 2. Add API calls in `ui/src/utils/api.ts`
 3. Update store in `ui/src/store/skeleton.ts`
 4. Modify UI in `ui/src/App.tsx`
 
+### 5. Rename as appropriate
+
+Change names throughout from `skeleton-app` (and variants) as appropriate if user describes app name.
+
 ## Common Issues and Solutions
 
 ### "Failed to deserialize HTTP request"
-- Ensure all HTTP methods have `_request_body` parameter
 - Check parameter format (tuple vs object)
 
 ### "Node not connected"
@@ -159,31 +194,58 @@ Add system permissions in `manifest.json`:
 
 ## Testing Your App
 
-1. Run a Hyperware node:
+1. Deploy app to a Hyperware node (after building, if requested):
    ```bash
-   kit s
+   kit start-packages
    ```
-
 2. Your app will be automatically installed and available at `http://localhost:8080`
 3. Check the Hyperware homepage for your app icon
 
-## Next Steps
+## Instructions
+
+### Create an implementation plan
+
+Carefully read the prompt; look carefully at `instructions.md` (if it exists) and in the resources/ directory.
+In particular, note the example applications `resources/example-apps/sign/`, `resources/example-apps/id/`, and `resources/example-apps/file-explorer`.
+`sign` and `id` demonstrate local messaging.
+`file-explorer` demonstrates VFS interactions.
+
+Expand the prompt and/or `instructions.md` into a detailed implementation plan.
+The implementor will be starting from this existing template that exists at `skeleton-app/` and `ui/`.
+
+Note in particular that bindings for the UI will be generated when the app is built with `kit build --hyperapp`.
+As such, first design and implement the backend; the interface will be generated from the backend; finally design and implement the frontend to consume the interface.
+Subsequent changes to the interface must follow this pattern as well: start in backend, generate interface, finish in frontend
+
+Do NOT create the API.
+The API is machine generated.
+You create types that end up in the API by defining and using them in functions in the Rust backend "hyperapp"
+
+Do NOT write code: just create a detailed `IMPLEMENTATION_PLAN.md` that will be used by the implementor.
+The implementor will have access to `resources/` but will be working from `IMPLEMENTATION_PLAN.md`, so include all relevant context in the PLAN.
+You can refer the implementor to `resources/` but do not assume the implementor has read them unless you refer them there.
+
+### Implement the plan
+
+Look carefully at `IMPLEMENTATION_PLAN.md` and in the `resources/` directory, if relevant.
+In particular, note the example applications `resources/example-apps/sign/`, `resources/example-apps/id/`, and `resources/example-apps/file-explorer`.
+Use them if useful.
+
+Work from the existing template that exists at `skeleton-app/` and `ui/`.
 
-1. **Study the Code**: Read through the well-commented `lib.rs` file
-2. **Experiment**: Try modifying the counter logic or adding new endpoints
-3. **Build Features**: Add your own functionality following the patterns
-4. **Add Capabilities**: Request system permissions as needed for your features
+Note in particular that bindings for the UI will be generated when the app is built with `kit build --hyperapp`.
+As such, first design and implement the backend; the interface will be generated from the backend; finally design and implement the frontend to consume the interface.
+Subsequent changes to the interface must follow this pattern as well: start in backend, generate interface, finish in frontend
 
-## Resources
+Do NOT create the API.
+The API is machine generated.
+You create types that end up in the API by defining and using them in functions in the Rust backend "hyperapp"
 
-- **Development Guides**: See `resources/guides/` for comprehensive documentation
-  - [Manifest & Deployment](resources/guides/08-MANIFEST-AND-DEPLOYMENT.md) - Understanding manifest.json
-  - [Capabilities Guide](resources/guides/09-CAPABILITIES-GUIDE.md) - System permissions reference
-  - [Complete Guide Index](resources/guides/README.md) - All available guides
-- **Example Apps**: Check the `example-apps` folder for working implementations
-- **Hyperware Documentation**: [Coming Soon]
-- **Community**: [Coming Soon]
+Do not worry about serialization/deserialization when using `send` and `send_rmp` functions for p2p communication.
+Notice that this all happens within those functions: just take the rust types as args and return rust types as return values.
 
-## License
+If you create a GUI for the app you MUST use target/ui/caller-utils.ts for HTTP requests to the backend.
+Do NOT edit this file: it is machine generated.
+Do NOT do `fetch` or other HTTP requests manually to the backend: use the functions in this machine generated interface.
 
-[Your License Here]
+Implement the application described in the `IMPLEMENTATION_PLAN.md`.

pkg/api.zip

@@ -3,12 +3,17 @@
     "process_name": "skeleton-app",
     "process_wasm_path": "/skeleton-app.wasm",
     "on_exit": "Restart",
-    "request_networking": true,
+    "request_networking": false,
     "request_capabilities": [
       "homepage:homepage:sys",
-      "http-server:distro:sys"
+      "http-server:distro:sys",
+      "vfs:distro:sys"
     ],
-    "grant_capabilities": [],
-    "public": true
+    "grant_capabilities": [
+      "homepage:homepage:sys",
+      "http-server:distro:sys",
+      "vfs:distro:sys"
+    ],
+    "public": false
   }
-]
+]