Develop And Deploy Web App

Build a simple full-stack web app in the current workspace, run it locally as its own isolated process, and provide a URL that another person can open from outside the machine.

Operating Rules

• Create the generated web project under workspaces/web-apps/{sessionId}/{token}.
• Treat {token} as an 8-character random identifier made only of uppercase letters and digits.
• If sessionId is available in the runtime context, use it directly. If it is not discoverable from the environment or user request, ask the user before scaffolding.
• Do not scaffold the app at the repository root unless the user explicitly overrides the output rule.
• Treat {token} as both the folder name and the URL segment.
• Run each web app in its own isolated Node.js process. Do not rely on one shared Node.js host process to serve multiple app folders.
• Prefer a two-package layout: client/ for the React app and server/ for the Express API.
• Prefer TypeScript everywhere.
• Prefer Vite for the React frontend.
• Prefer better-sqlite3 for SQLite access unless the workspace already uses another SQLite library.
• Prefer one final HTTP service. In production mode, make Express serve the built frontend and the /api endpoints from the same server process.
• If the user does not specify a product idea, default to a simple todo or notes app with one SQLite-backed entity and a complete happy path.
• Extend an existing app when one already exists. Do not replace working user code without a strong reason.
• Follow the UI direction in references/ui-style.md when designing the frontend. Capture the visual principles from Huashu Design's web examples without copying its original assets or branded content.
• Make the app work under the subpath /{sessionId}/{token}/, not just at /.
• Assign each app a dedicated port in the inclusive range 33333-39999. Start at 33333 and increment until a free port is found.
• Treat the final external URL as http://host:{port}/{sessionId}/{token}/.
• Maintain machine-readable and human-readable records so current sessions and apps can be queried without scanning source files manually.
• Prefer the bundled Node scripts in scripts/ for app initialization, port allocation, registry maintenance, startup, shutdown, and doc synchronization instead of re-implementing those flows ad hoc.
• Keep deployment automation local and explicit. Do not add scripts that fetch remote code, manage secrets, alter unrelated system state, or attempt privilege escalation.
• Support restart recovery through registry-driven restore scripts, but do not silently install OS startup hooks or scheduled tasks.

Workflow

1. Inspect the workspace before changing anything.
2. Resolve the output directory as workspaces/web-apps/{sessionId}/{token} and create it if needed.
3. Initialize the app folder and base app documents with scripts/init-app.js.
4. Decide whether to extend an existing app in that target directory or scaffold a new one.
5. Create a minimal but complete app:
   • React frontend with a small but usable UI
   • Express backend in TypeScript
   • SQLite database with schema initialization
   • At least one CRUD flow
   • Health endpoint
6. Add root-level scripts so the app is easy to install, run, build, start, and re-run on a reassigned port.
7. Scaffold the actual project files with scripts/scaffold-app.js.
8. Sync app documentation with scripts/sync-docs.js.
9. Prefer scripts/deploy-app.js for ordered deployment. It installs dependencies, builds the app, starts it, syncs docs, and updates the registry without race conditions.
10. If deployment steps are run separately, run them in order: install-app.js -> build-app.js -> start-app.js -> sync-docs.js -> update-registry.js.
11. Use status-app.js and restart-app.js for lifecycle checks and controlled restarts.
12. Use restore-apps.js for post-reboot recovery, and bootstrap-host.js to print the command that a host-level startup mechanism should run.
13. Return the URL together with the local commands and any important caveats.

Implementation Defaults

• Use the structure and package guidance in references/stack.md.
• Use the concrete scaffold commands in references/scaffold.md when building a new app from scratch.
• Use the deployment scripts in scripts/.
• Use the minimal script contracts in references/scripts.md.
• Use the autoload compatibility rules in references/autoload.md.
• Use the frontend style guidance in references/ui-style.md.
• Default local ports:
  • frontend dev server: 5173
  • backend dev server: 3000 or 3001
  • production app server: one free port in 33333-39999
• In development, use a Vite proxy for /api.
• In production, serve client/dist from Express under the base path and keep API routes under /{sessionId}/{token}/api.
• Store the SQLite database in a project-local path such as server/data/app.db.

Platform URL Rules

• Do not stop after scaffolding files. The task is incomplete until the app is actually runnable from the generated folder and a final URL has been produced or a concrete blocker has been confirmed.
• Prefer exposing the production build, not the Vite dev server, so the final URL reflects the real integrated app.
• Compute the final URL as http://host:{port}/{sessionId}/{token}/.
• Select {port} by scanning from 33333 upward and using the first free port up to 39999.
• Ensure frontend asset URLs, router behavior, and API calls all work when mounted beneath that subpath.
• Keep each app isolated in its own process and directory. Do not multiplex multiple apps through one long-running server.
• If a dev-time preview URL is needed, treat it as secondary. The primary deliverable is the final app URL plus its recorded metadata.

Queryability Rules

• Make it easy to answer "which sessions exist?" and "which apps exist?" without launching app code.
• Maintain a root registry and per-session indices with scripts/update-registry.js.
• Keep one machine-readable app metadata file and one human-readable app notes file in every app directory, managed through scripts/init-app.js and scripts/sync-docs.js.
• Whenever the app is changed, update the corresponding metadata and notes in the same turn.
• When the user asks to inspect existing apps, answer from the registry files first and only inspect app directories when details are missing or stale.

Delivery Requirements

Always finish with:

• the generated project path
• the app summary
• the main files or folders created or updated
• install and run commands
• the final URL in the form http://host:{port}/{sessionId}/{token}/
• the assigned port
• the registry and app-doc files that were created or updated
• any limitations, such as the URL depending on the local process remaining alive

Example Requests

• "Build me a simple task tracker and give me a public URL."
• "Create a small React + Express + SQLite app for note taking and run it."
• "Set up a demo web app in this folder, start it, and share an external link."