forgeos 0.1.0-alpha.0 → 0.1.0-alpha.2

package/.npmignore

@@ -1 +1,9 @@
-# Staged publish copy. Package contents are controlled by package.json files.
+# Package contents are primarily controlled by package.json "files".
+node_modules/
+.git/
+.github/
+.forge/
+tests/
+examples/
+*.tgz
+npm-debug.log*

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.0.0 input=6b855b87f2f57fce3e0939076b81cc0263cccfeae7bb969d2662613867b1c8ee content=972ba64a9c3df8fb49f4e4c7cb9892d6449d7833b9a303b748d08c5717d239e3
+// @forge-generated generator=0.1.0-alpha.2 input=2ce189e4d3555acfca07eb3bb3d103b22a8da52f3c26f9ac2197254f0563234f content=e0bf36433d915daf5ad06ac6265b3ac6f2cd1706269c69618bbbc1cb1f44e465
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -69,6 +69,9 @@ forge inspect app --json
 forge inspect all --json
 forge inspect frontend --json
 forge inspect capabilities --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
@@ -250,6 +253,8 @@ 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
 ```

package/CHANGELOG.md

@@ -1,8 +1,38 @@
 # forgeos
 
+## 0.1.0-alpha.2
+
+Windows and generated-app hardening:
+
+- Fixed Node ESM handler loading on Windows by importing generated app modules
+  through `file://` URLs across commands, queries, liveQueries, outbox actions,
+  workflow steps, mocks, and telemetry adapters.
+- Fixed `forge dev` SSE streaming on the Node HTTP fallback so liveQuery
+  snapshots are flushed immediately instead of buffering forever.
+- Hardened generated app scaffolding and web dev spawning on Windows.
+- Updated the B2B support template to route frontend imports through
+  `web/lib/forge.ts` and use safer handler input validation.
+- Added focused tests for Node compatibility, template scaffolding, runtime
+  imports, and streaming responses.
+
+## 0.1.0-alpha.1
+
+Republish alpha with the dependency/API oracle improvements:
+
+- Added dependency API inspection commands for agents:
+  `forge deps api`, `forge deps trace`, and `forge deps runtime-compat`.
+- Added dependency API summaries to `agentContract.json`.
+- Added package resolution traces, runtime compatibility metadata, and
+  runtime/type mismatch diagnostics to `packageGraph`.
+- Reduced package graph warning noise for `package.json` metadata exports,
+  declaration-file subpaths, and pattern exports.
+
 ## 0.1.0-alpha.0
 
 Initial alpha packaging baseline for ForgeOS.
 
 This release line is intended to validate npm installation, the `forge` CLI binary,
 template creation, generated contracts, and the agent-native local development loop.
+
+Added ReadTheDocs-ready public documentation, generator/package version alignment
+checks, and a broad generated-app field-test harness for release hardening.

package/CONTRIBUTING.md

@@ -9,8 +9,29 @@ bun run typecheck
 bun test --timeout 120000
 node ./bin/forge.mjs verify --standard --script-timeout-ms 120000
 npm run release:smoke
+npm run field:test -- --dry-run --json
 ```
 
+Run a real external-app smoke before release candidates:
+
+```bash
+npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
+```
+
+Use the GitHub Actions `Field Tests` workflow for the broader OS, Node, package-manager matrix.
+
+## Documentation
+
+Public docs are built with MkDocs on ReadTheDocs. The configuration lives in:
+
+```txt
+.readthedocs.yaml
+mkdocs.yml
+docs/**
+```
+
+Keep `docs/getting-started.md`, `docs/cli.md`, and `docs/field-testing.md` current when changing install, template, or verification behavior.
+
 ## Changesets
 
 For changes that should be published, add a changeset:
@@ -36,7 +57,7 @@ Configure the npm package `forgeos` with:
 | Environment | blank |
 | Allowed action | `npm publish` |
 
-Do not configure `NPM_TOKEN` for normal releases. The publish workflow uses GitHub OIDC with `id-token: write`, Node 24, npm 11+, and provenance.
+Do not configure `NPM_TOKEN` for normal releases. The publish workflow uses GitHub OIDC with `id-token: write`, Node 24, npm 11+, and provenance. In npm package settings, prefer "Require two-factor authentication and disallow tokens"; Trusted Publishers continue to work with that stricter token setting.
 
 ## Manual Publish
 

package/README.md

@@ -2,7 +2,9 @@
 
 Agent-native application framework and compiler for building Forge apps without a mandatory dashboard. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
 
-**Status:** private MVP, implemented through H42. The core compiler, local runtime, frontend SDK, production auth, RLS compiler, repair/review loops, UI test bridge, guided intent router, full-stack capability map, clean templates, faster generated checks, showcase app, Windows-safe Bun resolution, native Windows diagnostics/setup, Node-compatible CLI/runtime paths, observable verify timeouts, multi-OS Node CI smoke, release packaging smoke, AST-aware codemods for `extract-action`, `rename field`, and `rename table`, and quieter template workspaces are present. Public release still needs deeper semantic codemods and final npm Trusted Publisher activation.
+**Status:** private/public alpha MVP, implemented through H42. The core compiler, local runtime, frontend SDK, production auth, RLS compiler, repair/review loops, UI test bridge, guided intent router, full-stack capability map, clean templates, faster generated checks, showcase app, Windows-safe Bun resolution, native Windows diagnostics/setup, Node-compatible CLI/runtime paths, observable verify timeouts, multi-OS Node CI smoke, release packaging smoke, npm alpha publishing, Trusted Publisher/OIDC release wiring, ReadTheDocs-ready public docs, package/version-aligned generator metadata, AST-aware codemods for `extract-action`, `rename field`, and `rename table`, broader field-test automation, and quieter template workspaces are present. Public release hardening is still focused on deeper semantic codemods and more real-project field reports.
+
+Public docs are configured for ReadTheDocs with `.readthedocs.yaml` and `mkdocs.yml`. The local docs entrypoint is `docs/index.md`.
 
 ## Agent-First Quickstart
 
@@ -42,6 +44,22 @@ These files describe the app surface, runtime rules, generated files, policies,
 
 ## Create a Test App
 
+Public one-command app creation:
+
+```bash
+npm create forge-app@alpha notes-app -- --template minimal-web
+cd notes-app
+npm run dev
+```
+
+Equivalent lower-level command without installing ForgeOS globally:
+
+```bash
+npm exec --package forgeos@alpha -- forge new notes-app --template minimal-web --package-manager npm
+```
+
+If ForgeOS is already installed or you are inside this repository:
+
 ```bash
 forge new notes-app --template minimal-web --package-manager npm
 cd notes-app
@@ -56,11 +74,20 @@ Templates also include workspace editor excludes for generated/runtime directori
 For release or external smoke testing, choose the Forge package source explicitly:
 
 ```bash
-forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@^0.1.0-alpha.0"
+forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@alpha"
 forge new local-app --template minimal-web --package-manager npm --local-forge
 ```
 
-`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@^0.1.0-alpha.0"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
+`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@alpha"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
+
+For broader field testing:
+
+```bash
+npm run field:test -- --dry-run --json
+npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
+```
+
+The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
 
 ## What ForgeOS Generates
 

package/bin/forge.mjs

@@ -5,15 +5,16 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const entrypoint = join(root, "src", "forge", "cli", "main.ts");
 
-let tsImport;
+let register;
 try {
-  ({ tsImport } = await import("tsx/esm/api"));
+  ({ register } = await import("tsx/esm/api"));
 } catch {
   console.error("error: Forge requires the 'tsx' package to run under Node.");
   console.error("Install dependencies with your package manager, then retry.");
   process.exit(1);
 }
 
-const module = await tsImport(pathToFileURL(entrypoint).href, import.meta.url);
+register();
+const module = await import(pathToFileURL(entrypoint).href);
 const exitCode = await module.main(process.argv.slice(2));
 process.exit(exitCode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "files": [
@@ -37,6 +37,7 @@
     "release:pack": "npm pack --dry-run",
     "release:smoke": "node scripts/smoke-packed-package.mjs",
     "release:publish-local-alpha": "node scripts/publish-local-alpha.mjs",
+    "field:test": "node scripts/field-test-forgeos.mjs",
     "forge": "node ./bin/forge.mjs",
     "forge:node": "node ./bin/forge.mjs",
     "forge:bun": "node ./bin/forge-bun.mjs src/forge/cli/main.ts",
@@ -88,6 +89,7 @@
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
     "@types/bun": "1.3.14",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.2.17",
     "@types/react-test-renderer": "^19.1.0",
     "fast-check": "^3.23.2",

package/packages/eslint-plugin-forge/index.ts

@@ -1,15 +1,15 @@
-export {
-  loadForgeGuardArtifacts,
-  type ForgeGuardArtifacts,
-} from "./src/load-artifacts.ts";
-export {
-  checkSourceForgeGuards,
-  type ForgeGuardSourceViolation,
-} from "./src/check-source.ts";
-export {
-  runForgeGuardRule,
-  forgeGuardRuleDefinition,
-  formatViolationMessage,
-  type ForgeEslintContext,
-  type ForgeEslintSettings,
-} from "./src/rule-no-forge-guard-violation.ts";
+export {
+  loadForgeGuardArtifacts,
+  type ForgeGuardArtifacts,
+} from "./src/load-artifacts.ts";
+export {
+  checkSourceForgeGuards,
+  type ForgeGuardSourceViolation,
+} from "./src/check-source.ts";
+export {
+  runForgeGuardRule,
+  forgeGuardRuleDefinition,
+  formatViolationMessage,
+  type ForgeEslintContext,
+  type ForgeEslintSettings,
+} from "./src/rule-no-forge-guard-violation.ts";

package/packages/eslint-plugin-forge/package.json

@@ -1,10 +1,10 @@
-{
-  "name": "eslint-plugin-forge",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  }
-}
+{
+  "name": "eslint-plugin-forge",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/packages/eslint-plugin-forge/src/check-source.ts

@@ -1,95 +1,95 @@
-import { lookupMatrixEntry } from "../../../src/forge/compiler/classifier/runtime-matrix.ts";
-import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
-import type { RuntimeContext } from "../../../src/forge/compiler/types/runtime.ts";
-import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
-import { parsePackageSpecifier } from "../../../src/forge/compiler/app-graph/module-graph.ts";
-
-export interface ForgeGuardSourceViolation {
-  packageName: string;
-  context: RuntimeContext;
-  rationale: string;
-  line: number;
-  column: number;
-  endColumn: number;
-}
-
-const IMPORT_PATTERN =
-  /(?:import\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?|export\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
-
-function lineColumnAtOffset(
-  source: string,
-  offset: number,
-): { line: number; column: number } {
-  const before = source.slice(0, offset);
-  const lines = before.split("\n");
-  return {
-    line: lines.length,
-    column: (lines.at(-1)?.length ?? 0) + 1,
-  };
-}
-
-function effectiveContextsForFile(
-  file: string,
-  guards: ImportGuardsArtifact,
-): RuntimeContext[] {
-  const normalized = file.replace(/\\/g, "/");
-  const entry = guards.moduleContexts.find(
-    (module) =>
-      module.file === normalized ||
-      normalized.endsWith(`/${module.file}`) ||
-      module.file.endsWith(normalized),
-  );
-  return entry?.effectiveContexts ?? [];
-}
-
-export function checkSourceForgeGuards(
-  filePath: string,
-  source: string,
-  importGuards: ImportGuardsArtifact,
-  runtimeMatrix: RuntimeMatrix,
-): ForgeGuardSourceViolation[] {
-  const effectiveContexts = effectiveContextsForFile(filePath, importGuards);
-  if (effectiveContexts.length === 0) {
-    return [];
-  }
-
-  const violations: ForgeGuardSourceViolation[] = [];
-
-  for (const match of source.matchAll(IMPORT_PATTERN)) {
-    const specifier = match[1] ?? match[2];
-    if (!specifier) {
-      continue;
-    }
-
-    const parsed = parsePackageSpecifier(specifier);
-    if (!parsed) {
-      continue;
-    }
-
-    const matrixEntry = lookupMatrixEntry(runtimeMatrix, parsed.packageName);
-    if (matrixEntry == null) {
-      continue;
-    }
-
-    const offset = match.index ?? 0;
-    const start = lineColumnAtOffset(source, offset);
-    const endColumn = start.column + match[0].length;
-
-    for (const context of effectiveContexts) {
-      if (!matrixEntry.compatible.includes(context)) {
-        violations.push({
-          packageName: parsed.packageName,
-          context,
-          rationale:
-            matrixEntry.rationale[context] ??
-            "package is incompatible with this runtime context",
-          line: start.line,
-          column: start.column,
-          endColumn,
-        });
-      }
-    }
-  }
-
-  return violations;
-}
+import { lookupMatrixEntry } from "../../../src/forge/compiler/classifier/runtime-matrix.ts";
+import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
+import type { RuntimeContext } from "../../../src/forge/compiler/types/runtime.ts";
+import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
+import { parsePackageSpecifier } from "../../../src/forge/compiler/app-graph/module-graph.ts";
+
+export interface ForgeGuardSourceViolation {
+  packageName: string;
+  context: RuntimeContext;
+  rationale: string;
+  line: number;
+  column: number;
+  endColumn: number;
+}
+
+const IMPORT_PATTERN =
+  /(?:import\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?|export\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function lineColumnAtOffset(
+  source: string,
+  offset: number,
+): { line: number; column: number } {
+  const before = source.slice(0, offset);
+  const lines = before.split("\n");
+  return {
+    line: lines.length,
+    column: (lines.at(-1)?.length ?? 0) + 1,
+  };
+}
+
+function effectiveContextsForFile(
+  file: string,
+  guards: ImportGuardsArtifact,
+): RuntimeContext[] {
+  const normalized = file.replace(/\\/g, "/");
+  const entry = guards.moduleContexts.find(
+    (module) =>
+      module.file === normalized ||
+      normalized.endsWith(`/${module.file}`) ||
+      module.file.endsWith(normalized),
+  );
+  return entry?.effectiveContexts ?? [];
+}
+
+export function checkSourceForgeGuards(
+  filePath: string,
+  source: string,
+  importGuards: ImportGuardsArtifact,
+  runtimeMatrix: RuntimeMatrix,
+): ForgeGuardSourceViolation[] {
+  const effectiveContexts = effectiveContextsForFile(filePath, importGuards);
+  if (effectiveContexts.length === 0) {
+    return [];
+  }
+
+  const violations: ForgeGuardSourceViolation[] = [];
+
+  for (const match of source.matchAll(IMPORT_PATTERN)) {
+    const specifier = match[1] ?? match[2];
+    if (!specifier) {
+      continue;
+    }
+
+    const parsed = parsePackageSpecifier(specifier);
+    if (!parsed) {
+      continue;
+    }
+
+    const matrixEntry = lookupMatrixEntry(runtimeMatrix, parsed.packageName);
+    if (matrixEntry == null) {
+      continue;
+    }
+
+    const offset = match.index ?? 0;
+    const start = lineColumnAtOffset(source, offset);
+    const endColumn = start.column + match[0].length;
+
+    for (const context of effectiveContexts) {
+      if (!matrixEntry.compatible.includes(context)) {
+        violations.push({
+          packageName: parsed.packageName,
+          context,
+          rationale:
+            matrixEntry.rationale[context] ??
+            "package is incompatible with this runtime context",
+          line: start.line,
+          column: start.column,
+          endColumn,
+        });
+      }
+    }
+  }
+
+  return violations;
+}

package/packages/eslint-plugin-forge/src/load-artifacts.ts

@@ -1,24 +1,24 @@
-import { readFileSync } from "node:fs";
-import { stripDeterministicHeader } from "../../../src/forge/compiler/primitives/header.ts";
-import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
-import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
-
-export interface ForgeGuardArtifacts {
-  importGuards: ImportGuardsArtifact;
-  runtimeMatrix: RuntimeMatrix;
-}
-
-function parseGeneratedJson<T>(path: string): T {
-  const raw = stripDeterministicHeader(readFileSync(path, "utf8"));
-  return JSON.parse(raw) as T;
-}
-
-export function loadForgeGuardArtifacts(
-  importGuardsPath: string,
-  runtimeMatrixPath: string,
-): ForgeGuardArtifacts {
-  const importGuards = parseGeneratedJson<ImportGuardsArtifact>(importGuardsPath);
-  const runtimeMatrix = parseGeneratedJson<RuntimeMatrix>(runtimeMatrixPath);
-
-  return { importGuards, runtimeMatrix };
-}
+import { readFileSync } from "node:fs";
+import { stripDeterministicHeader } from "../../../src/forge/compiler/primitives/header.ts";
+import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
+import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
+
+export interface ForgeGuardArtifacts {
+  importGuards: ImportGuardsArtifact;
+  runtimeMatrix: RuntimeMatrix;
+}
+
+function parseGeneratedJson<T>(path: string): T {
+  const raw = stripDeterministicHeader(readFileSync(path, "utf8"));
+  return JSON.parse(raw) as T;
+}
+
+export function loadForgeGuardArtifacts(
+  importGuardsPath: string,
+  runtimeMatrixPath: string,
+): ForgeGuardArtifacts {
+  const importGuards = parseGeneratedJson<ImportGuardsArtifact>(importGuardsPath);
+  const runtimeMatrix = parseGeneratedJson<RuntimeMatrix>(runtimeMatrixPath);
+
+  return { importGuards, runtimeMatrix };
+}