forgeos 0.1.0-alpha.3 → 0.1.0-alpha.30

package/.npmignore

@@ -5,5 +5,15 @@ node_modules/
 .forge/
 tests/
 examples/
+adapters/**/target/
+examples/**/target/
+*.class
+*.jar
+**/*.class
+**/*.jar
+src/forge/_generated/**
+!src/forge/_generated/
+!src/forge/_generated/releaseManifest.json
+!src/forge/_generated/releaseManifest.ts
 *.tgz
 npm-debug.log*

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.3 input=c6d07cc92a729a46f2ff02a05c005e7fe0d71a3a5800be6f670a3fca2db04d6f content=1611635edf59c122b013ba76c85bd333ab3b30b289aaea04a9074f9438782a50
+// @forge-generated generator=0.1.0-alpha.30 input=5d12d4ad2a959d692b306eb18ba706c52f22f2d148c6e4ed541bd67fd8222c84 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -7,23 +7,51 @@
 
 This is a ForgeOS application named `forgeos`.
 
+## CLI entrypoint
+
+This is the ForgeOS framework checkout. Use `node bin/forge.mjs ...` so maintainer commands run against this source tree; reserve the global `forge` command for installed-package smoke tests.
+
 ## Required workflow
 
 Before editing:
 
 ```bash
-forge do inspect --json
-forge dev --once --json
-forge inspect all --json
-forge check --json
+node bin/forge.mjs agent onboard --target codex --json
+node bin/forge.mjs status --json
+node bin/forge.mjs changed --json
+node bin/forge.mjs handoff --json
+node bin/forge.mjs do inspect --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs check --json
+```
+
+## CAIR first
+
+Before reading large files or hand-writing patches, prefer the generated CAIR guide:
+
+```bash
+node bin/forge.mjs cair snapshot
+node bin/forge.mjs cair query "Q ST"
+node bin/forge.mjs cair query "Q S name=<symbol>"
+node bin/forge.mjs cair query "Q D S#1"
+node bin/forge.mjs cair query "Q R S#1"
+node bin/forge.mjs cair query "Q I S#1"
+```
+
+Use `src/forge/_generated/agentCairGuide.md` for the full compact protocol. Plan CAIR mutations before applying them:
+
+```bash
+node bin/forge.mjs cair action --plan "A RN t=S#1 nn=<newName>"
+node bin/forge.mjs cair action "A APPLY plan=<returned-plan-path>"
 ```
 
 After editing:
 
 ```bash
-forge generate
-forge check
-forge verify --strict
+node bin/forge.mjs generate
+node bin/forge.mjs check
+node bin/forge.mjs verify framework
 ```
 
 ## Do not edit
@@ -34,7 +62,7 @@ Do not:
 - `forge.lock`
 - `deploy/docker-compose.yml`, unless changing deployment config intentionally
 
-Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to reduce visual noise. Recreate them with `forge generate` before checking, testing, or handing work off.
+Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to reduce visual noise. Recreate them with `node bin/forge.mjs generate` before checking, testing, or handing work off.
 
 ## Runtime model
 
@@ -44,14 +72,14 @@ Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to re
 - Workflows orchestrate durable steps.
 - Production liveQuery uses a durable invalidation log; polling/notify are wakeups only.
 - Production API calls use `Authorization: Bearer <JWT>` in `jwt` or `oidc` auth mode.
-- `dev-headers` auth is for `forge dev`, tests, and local agent workflows only.
+- `dev-headers` auth is for `node bin/forge.mjs dev`, tests, and local agent workflows only.
 - AI is only allowed in actions, workflows, endpoints, and server code.
 - Secrets are accessed through `ctx.secrets`.
 
 ## Runtime rules
 
 - Do not import network packages inside `command`, `query`, or `liveQuery`.
-- Do not use `process.env` directly.
+- Do not read secrets or server runtime config through `process.env` in Forge runtime code; use `ctx.secrets` or generated config context. Public frontend bridge env such as `NEXT_PUBLIC_*` and `NUXT_PUBLIC_*` is allowed in web bridge files.
 - Do not access cross-tenant data.
 - Commands must use `ctx.emit` for side effects.
 - Actions and workflows handle side effects after commit.
@@ -60,35 +88,38 @@ Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to re
 ## Useful commands
 
 ```bash
-forge do "<objective>" --json
-forge do fix --json
-forge do verify --json
-forge dev --once --json
-forge dev
-forge inspect app --json
-forge inspect all --json
-forge inspect frontend --json
-forge inspect capabilities --json
-forge inspect agent-tools --json
-forge deps inspect <package> --json
-forge deps api <package> <symbol> --json
-forge deps trace <package> --json
-forge auth check --json
-forge inspect runtime-matrix --json
-forge inspect policies --json
-forge inspect client --json
-forge inspect live-production --json
-forge live status --json
-forge doctor
-forge doctor windows --json
-forge setup windows --json
-forge agent print-context --json
-forge ai tools --json
-forge ai agents --json
-forge ai trace <traceId> --json
-forge verify --smoke
-forge verify --standard
-forge verify --strict
+node bin/forge.mjs do "<objective>" --json
+node bin/forge.mjs do fix --json
+node bin/forge.mjs do verify --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs dev
+node bin/forge.mjs handoff --json
+node bin/forge.mjs inspect app --json
+node bin/forge.mjs inspect all --json
+node bin/forge.mjs inspect all --full --json
+node bin/forge.mjs inspect frontend --json
+node bin/forge.mjs inspect capabilities --json
+node bin/forge.mjs inspect agent-tools --json
+node bin/forge.mjs deps inspect <package> --json
+node bin/forge.mjs deps api <package> <symbol> --json
+node bin/forge.mjs deps trace <package> --json
+node bin/forge.mjs auth check --json
+node bin/forge.mjs inspect runtime-matrix --json
+node bin/forge.mjs inspect policies --json
+node bin/forge.mjs inspect client --json
+node bin/forge.mjs inspect live-production --json
+node bin/forge.mjs live status --json
+node bin/forge.mjs doctor
+node bin/forge.mjs doctor windows --json
+node bin/forge.mjs setup windows --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs agent doctor --target codex --json
+node bin/forge.mjs ai tools --json
+node bin/forge.mjs ai agents --json
+node bin/forge.mjs ai trace <traceId> --json
+node bin/forge.mjs verify --smoke
+node bin/forge.mjs verify --standard
+node bin/forge.mjs verify framework
 ```
 
 ## Data
@@ -142,9 +173,9 @@ Agents:
 
 Rules:
 
-- Use the local `web/**/lib/forge.ts` bridge to generated hooks.
-- Mount `<ForgeProvider devAuth>` in local development.
-- Use `useQuery`, `useCommand`, and `useLiveQuery` instead of raw Forge endpoint fetches in React components.
+- Use the local `web/**/lib/forge.ts` or Nuxt `web/composables/forge.ts` bridge to generated bindings.
+- Mount `<ForgeProvider devAuth>` or install the Nuxt Forge plugin in local development.
+- Use `useQuery`/`useCommand`/`useLiveQuery` or `useForgeQuery`/`useForgeCommand`/`useForgeLiveQuery` instead of raw Forge endpoint fetches in components.
 - Keep frontend routes reflected in `src/forge/_generated/frontendGraph.json`.
 
 ## Common tasks
@@ -154,30 +185,31 @@ Rules:
 Use:
 
 ```bash
-forge do "<objective>" --json
-forge do fix --json
-forge do connect-ui --json
-forge do verify --json
+node bin/forge.mjs do "<objective>" --json
+node bin/forge.mjs do fix --json
+node bin/forge.mjs do connect-ui --json
+node bin/forge.mjs do verify --json
 ```
 
-`forge do` returns intent, plan, filesToInspect, filesToChange, risks, concrete commands, and nextAction. Prefer it before choosing lower-level CLI commands manually.
+`node bin/forge.mjs do` returns intent, plan, filesToInspect, filesToChange, risks, concrete commands, and nextAction. Prefer it before choosing lower-level CLI commands manually.
 
 ### Add a command
 
 1. Add file in `src/commands`.
 2. Declare `auth: can("...")`.
-3. Run `forge generate`.
-4. Run `forge verify --strict`.
+3. Run `node bin/forge.mjs generate`.
+4. Run `node bin/forge.mjs verify framework`.
 
 ### Scaffold a resource
 
 Use:
 
 ```bash
-forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
-forge make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
-forge make ui --framework vite --dry-run --json
-forge make ai-chat support --dry-run --json
+node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
+node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
+node bin/forge.mjs make ui --framework vite --dry-run --json
+node bin/forge.mjs make ui --framework nuxt --dry-run --json
+node bin/forge.mjs make ai-chat support --dry-run --json
 ```
 
 Review the plan before applying when the resource touches schema or policies.
@@ -187,22 +219,22 @@ Review the plan before applying when the resource touches schema or policies.
 Use:
 
 ```bash
-forge dev --once --json
-forge dev
-forge inspect frontend --json
-forge inspect capabilities --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs dev
+node bin/forge.mjs inspect frontend --json
+node bin/forge.mjs inspect capabilities --json
 ```
 
-`forge dev` starts the API runtime and web app together when `web/` exists. `forge dev --once --json` reports routes, components, `ForgeProvider`, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
+`node bin/forge.mjs dev` starts the API runtime and web app together when `web/` exists. `node bin/forge.mjs dev --once --json` reports routes, components, providers/plugins, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
 
 ### Apply a feature blueprint
 
 Use:
 
 ```bash
-forge feature validate .forge/blueprints/<name>.json --json
-forge feature plan .forge/blueprints/<name>.json
-forge feature apply .forge/blueprints/<name>.json --yes
+node bin/forge.mjs feature validate .forge/blueprints/<name>.json --json
+node bin/forge.mjs feature plan .forge/blueprints/<name>.json
+node bin/forge.mjs feature apply .forge/blueprints/<name>.json --yes
 ```
 
 Review high-risk plans before applying. Use `--allow-high-risk` only when intentional.
@@ -212,10 +244,10 @@ Review high-risk plans before applying. Use `--allow-high-risk` only when intent
 Use:
 
 ```bash
-forge refactor rename field tickets.priority tickets.urgency --dry-run --json
-forge refactor rename field tickets.priority tickets.urgency --yes
-forge refactor rename command createTicket openTicket --dry-run --json
-forge refactor rename command createTicket openTicket --yes
+node bin/forge.mjs refactor rename field tickets.priority tickets.urgency --dry-run --json
+node bin/forge.mjs refactor rename field tickets.priority tickets.urgency --yes
+node bin/forge.mjs refactor rename command createTicket openTicket --dry-run --json
+node bin/forge.mjs refactor rename command createTicket openTicket --yes
 ```
 
 These codemods are AST-aware for `extract-action`, `rename command`, `rename field`, and `rename table`. Command renames update runtime registries, generated client references, frontend hooks, tests, and string references where safe. Field renames are scoped to the target table, so `tickets.priority` only rewrites references linked to `tickets`.
@@ -227,21 +259,21 @@ Never edit `src/forge/_generated/**` directly. Review migration hints before app
 Use:
 
 ```bash
-forge impact --changed --json
-forge test plan --changed --json
-forge test run --changed --timeout-ms 120000 --json
-forge verify --standard
+node bin/forge.mjs impact --changed --json
+node bin/forge.mjs test plan --changed --json
+node bin/forge.mjs test run --changed --timeout-ms 120000 --json
+node bin/forge.mjs verify --standard
 ```
 
-Use `forge verify --standard` for the normal agent development loop. Finish handoffs with `forge verify --strict` when the change is ready.
+Use `node bin/forge.mjs verify --standard` for the normal agent development loop. Finish handoffs with `node bin/forge.mjs verify framework` when the change is ready.
 
 ### Repair a failing check
 
 When a Forge check fails, do not guess. Use:
 
 ```bash
-forge repair diagnose --from-last-test-run --json
-forge repair plan --from-last-test-run --write
+node bin/forge.mjs repair diagnose --from-last-test-run --json
+node bin/forge.mjs repair plan --from-last-test-run --write
 ```
 
 Apply only high-confidence deterministic repairs automatically. Review medium or low confidence repairs before changing code.
@@ -251,10 +283,11 @@ Apply only high-confidence deterministic repairs automatically. Review medium or
 Use:
 
 ```bash
-forge generate
-forge inspect all --json
-forge ai check --json
-forge ai trace <traceId> --json
+node bin/forge.mjs generate
+node bin/forge.mjs inspect ai --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs ai check --json
+node bin/forge.mjs ai trace <traceId> --json
 ```
 
 Define tools with `aiTool({ inputSchema, outputSchema, risk, needsApproval, handler })` and agents with `agent({ provider, model, instructions, tools, stopWhen })`. Execute agents with `ctx.agent.run` or `ctx.ai.runAgent` only from actions, workflows, endpoints, or server code. In dev, POST `/ai/agents/run` returns JSON for automation and POST `/ai/agents/chat` returns an AI SDK UIMessage stream for React `useChat`; both accept `agent: "<exportedAgentName>"` and use generated auto-tools from `agentTools.json`.
@@ -264,10 +297,10 @@ Define tools with `aiTool({ inputSchema, outputSchema, risk, needsApproval, hand
 Use:
 
 ```bash
-forge agent export --target generic
-forge agent export --target codex
-forge agent export --target cursor
-forge agent export --target claude
+node bin/forge.mjs agent export --target generic
+node bin/forge.mjs agent export --target codex
+node bin/forge.mjs agent export --target cursor
+node bin/forge.mjs agent export --target claude
 ```
 
 Adapter files are derived from `agentContract.json`, `appMap.md`, `runtimeRules.md`, `operationPlaybooks.md`, and this `AGENTS.md`. Do not treat Codex, Cursor, Claude, or custom adapter files as the source of truth.
@@ -277,7 +310,7 @@ Adapter files are derived from `agentContract.json`, `appMap.md`, `runtimeRules.
 Use:
 
 ```bash
-forge add <alias>
+node bin/forge.mjs add <alias>
 ```
 
 Do not install packages manually unless intentional.
@@ -287,11 +320,11 @@ Do not install packages manually unless intentional.
 Use:
 
 ```bash
-forge deps upgrade-plan <package> --to latest
-forge deps inspect <package> --json
-forge deps api <package> <symbol> --json
-forge deps upgrade-apply <plan>
-forge verify --strict
+node bin/forge.mjs deps upgrade-plan <package> --to latest
+node bin/forge.mjs deps inspect <package> --json
+node bin/forge.mjs deps api <package> <symbol> --json
+node bin/forge.mjs deps upgrade-apply <plan>
+node bin/forge.mjs verify framework
 ```
 
 Do not manually edit `package.json` for package upgrades unless necessary.
@@ -301,9 +334,9 @@ Do not manually edit `package.json` for package upgrades unless necessary.
 Use:
 
 ```bash
-forge live status --json
-forge live invalidations list --json
-forge live debug <subscriptionId> --json
+node bin/forge.mjs live status --json
+node bin/forge.mjs live invalidations list --json
+node bin/forge.mjs live debug <subscriptionId> --json
 ```
 
 Durable invalidations live in `_forge_live_invalidations`.
@@ -314,4 +347,23 @@ Durable invalidations live in `_forge_live_invalidations`.
 
 Project-specific notes can go here.
 
+## Cursor Cloud specific instructions
+
+This repo is the ForgeOS framework/compiler itself (package `forgeos`), not a generated app. The development toolchain is Node.js (>= 22.14, present) plus **Bun**, which is the repo's test runner and canonical package manager (`bun.lock`). The Cloud VM snapshot has Bun pre-installed at `~/.bun/bin/bun` (added to `PATH` via `~/.bashrc`); if `bun` is not on `PATH` in a non-login shell, use `~/.bun/bin/bun` or `export PATH="$HOME/.bun/bin:$PATH"`.
+
+Standard commands (see `package.json`, `CONTRIBUTING.md`, `.github/workflows/ci.yml`):
+
+- Install deps: `bun install --ignore-scripts` (the update script runs this). `--ignore-scripts` matches CI; native deps like `tree-sitter` are not built and tests do not need them.
+- Lint: `npm run lint` (runs `node --import tsx ./src/forge/cli/lint-forge.ts`).
+- Typecheck: `npm run typecheck` (`tsc --noEmit`).
+- Tests: `bun test` (~2 min, 650 tests). 4 tests are skipped by design unless extra tooling/env is set (`FORGE_SMOKE_REAL=1`, a real Postgres, `FORGE_MAVEN`).
+- Generate + verify: `bun run forge generate` then `bun run forge verify --standard --script-timeout-ms 120000`.
+
+Non-obvious gotchas:
+
+- `bun run forge generate` rewrites `src/forge/_generated/**`, `forge.lock`, and the `// @forge-generated` header `input=` hash in `AGENTS.md`. These regenerated diffs are environment-dependent and should NOT be committed (per "Do not edit" above). `forge verify` regenerates internally, so `generate-check` can pass even while `git status` shows these as dirty. Run `git checkout -- .` to discard them before committing unrelated work.
+- The CLI runs under Node via `tsx` (`node ./bin/forge.mjs ...` or `npm run forge -- ...`); only the test runner needs Bun.
+- To run an actual Forge app end-to-end, scaffold one from a template and run the dev servers. From a temp dir: `node /workspace/bin/forge.mjs new notes-app --template minimal-web --package-manager npm --forge-spec "file:/workspace" --install --no-git`, then `cd notes-app && npm run dev`. `forge dev` starts the API runtime (pglite, default `http://127.0.0.1:3765`) and the Vite web app (default `http://127.0.0.1:5173`); use `forge dev --api-only` for backend only.
+- Hitting the runtime directly: POST `/commands/<name>` and `/queries/<name>` with body shaped as `{ "args": { ... } }`. In `dev-headers` auth mode pass `x-forge-user-id` and `x-forge-role` (e.g. `owner`) headers; `<ForgeProvider devAuth>` defaults to user `dev-user`, tenant `dev-tenant`, role `owner`.
+
 <!-- user-notes:end -->