forgeos 0.1.0-alpha.0 → 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/.npmignore +9 -1
  2. package/AGENTS.md +6 -1
  3. package/CHANGELOG.md +15 -0
  4. package/CONTRIBUTING.md +22 -1
  5. package/README.md +12 -1
  6. package/package.json +3 -1
  7. package/packages/eslint-plugin-forge/index.ts +15 -15
  8. package/packages/eslint-plugin-forge/package.json +10 -10
  9. package/packages/eslint-plugin-forge/src/check-source.ts +95 -95
  10. package/packages/eslint-plugin-forge/src/load-artifacts.ts +24 -24
  11. package/packages/eslint-plugin-forge/src/rule-no-forge-guard-violation.ts +93 -93
  12. package/src/forge/_generated/actionSubscriptions.json +2 -2
  13. package/src/forge/_generated/actionSubscriptions.ts +3 -3
  14. package/src/forge/_generated/agentAdapterManifest.json +2 -2
  15. package/src/forge/_generated/agentAdapterManifest.ts +3 -3
  16. package/src/forge/_generated/agentContract.json +2 -2
  17. package/src/forge/_generated/agentContract.ts +6786 -2
  18. package/src/forge/_generated/agentQuickstart.md +1 -1
  19. package/src/forge/_generated/aiContext.ts +1 -1
  20. package/src/forge/_generated/aiModels.json +1 -1
  21. package/src/forge/_generated/aiModels.ts +1 -1
  22. package/src/forge/_generated/aiProviders.json +1 -1
  23. package/src/forge/_generated/aiProviders.ts +1 -1
  24. package/src/forge/_generated/aiRegistry.json +2 -2
  25. package/src/forge/_generated/aiRegistry.ts +3 -3
  26. package/src/forge/_generated/api.json +2 -2
  27. package/src/forge/_generated/api.ts +1 -1
  28. package/src/forge/_generated/appGraph.json +2 -2
  29. package/src/forge/_generated/appGraph.ts +1112 -956
  30. package/src/forge/_generated/appMap.md +1 -1
  31. package/src/forge/_generated/artifactManifest.json +2 -2
  32. package/src/forge/_generated/artifactManifest.ts +2 -2
  33. package/src/forge/_generated/authClaims.json +1 -1
  34. package/src/forge/_generated/authClaims.ts +1 -1
  35. package/src/forge/_generated/authConfig.json +1 -1
  36. package/src/forge/_generated/authConfig.ts +1 -1
  37. package/src/forge/_generated/authContext.ts +1 -1
  38. package/src/forge/_generated/authRegistry.json +1 -1
  39. package/src/forge/_generated/authRegistry.ts +1 -1
  40. package/src/forge/_generated/buildInfo.json +2 -2
  41. package/src/forge/_generated/buildInfo.ts +4 -4
  42. package/src/forge/_generated/capabilityMap.json +2 -2
  43. package/src/forge/_generated/capabilityMap.md +1 -1
  44. package/src/forge/_generated/capabilityMap.ts +2 -2
  45. package/src/forge/_generated/client.ts +1 -1
  46. package/src/forge/_generated/clientApi.ts +1 -1
  47. package/src/forge/_generated/clientManifest.json +2 -2
  48. package/src/forge/_generated/clientManifest.ts +3 -3
  49. package/src/forge/_generated/clientTypes.ts +1 -1
  50. package/src/forge/_generated/configRegistry.json +1 -1
  51. package/src/forge/_generated/configRegistry.ts +1 -1
  52. package/src/forge/_generated/dataGraph.json +2 -2
  53. package/src/forge/_generated/dataGraph.ts +3 -3
  54. package/src/forge/_generated/db.json +1 -1
  55. package/src/forge/_generated/db.ts +1 -1
  56. package/src/forge/_generated/dbSecurityManifest.json +1 -1
  57. package/src/forge/_generated/dbSecurityManifest.ts +1 -1
  58. package/src/forge/_generated/dbSessionContext.json +1 -1
  59. package/src/forge/_generated/dbSessionContext.ts +1 -1
  60. package/src/forge/_generated/deployManifest.json +2 -2
  61. package/src/forge/_generated/deployManifest.ts +7 -7
  62. package/src/forge/_generated/devManifest.json +2 -2
  63. package/src/forge/_generated/devManifest.ts +3 -3
  64. package/src/forge/_generated/envSchema.json +1 -1
  65. package/src/forge/_generated/envSchema.ts +1 -1
  66. package/src/forge/_generated/frontendGraph.json +1 -1
  67. package/src/forge/_generated/frontendGraph.ts +1 -1
  68. package/src/forge/_generated/importGuards.json +2 -2
  69. package/src/forge/_generated/importGuards.ts +35 -1
  70. package/src/forge/_generated/index.ts +1 -1
  71. package/src/forge/_generated/liveProductionManifest.json +1 -1
  72. package/src/forge/_generated/liveProductionManifest.ts +1 -1
  73. package/src/forge/_generated/liveProtocol.json +1 -1
  74. package/src/forge/_generated/liveProtocol.ts +1 -1
  75. package/src/forge/_generated/liveQueryRegistry.json +2 -2
  76. package/src/forge/_generated/liveQueryRegistry.ts +3 -3
  77. package/src/forge/_generated/liveTransportConfig.json +1 -1
  78. package/src/forge/_generated/liveTransportConfig.ts +1 -1
  79. package/src/forge/_generated/makeRegistry.json +2 -2
  80. package/src/forge/_generated/makeRegistry.ts +2 -2
  81. package/src/forge/_generated/makeTemplates.json +1 -1
  82. package/src/forge/_generated/makeTemplates.ts +1 -1
  83. package/src/forge/_generated/mockMap.json +1 -1
  84. package/src/forge/_generated/mockMap.ts +1 -1
  85. package/src/forge/_generated/operationPlaybooks.md +7 -5
  86. package/src/forge/_generated/packageGraph.json +2 -2
  87. package/src/forge/_generated/packageGraph.ts +90964 -14284
  88. package/src/forge/_generated/packageUpgradeRegistry.json +2 -2
  89. package/src/forge/_generated/packageUpgradeRegistry.ts +2 -2
  90. package/src/forge/_generated/permissionMatrix.json +2 -2
  91. package/src/forge/_generated/permissionMatrix.ts +3 -3
  92. package/src/forge/_generated/policyRegistry.json +2 -2
  93. package/src/forge/_generated/policyRegistry.ts +3 -3
  94. package/src/forge/_generated/queryRegistry.json +2 -2
  95. package/src/forge/_generated/queryRegistry.ts +3 -3
  96. package/src/forge/_generated/react.d.ts +1 -1
  97. package/src/forge/_generated/react.ts +1 -1
  98. package/src/forge/_generated/reactManifest.json +2 -2
  99. package/src/forge/_generated/reactManifest.ts +3 -3
  100. package/src/forge/_generated/releaseManifest.json +2 -2
  101. package/src/forge/_generated/releaseManifest.ts +3 -3
  102. package/src/forge/_generated/rlsPolicies.json +1 -1
  103. package/src/forge/_generated/rlsPolicies.sql +1 -1
  104. package/src/forge/_generated/rlsPolicies.ts +1 -1
  105. package/src/forge/_generated/runtimeGraph.json +2 -2
  106. package/src/forge/_generated/runtimeGraph.ts +3 -3
  107. package/src/forge/_generated/runtimeMatrix.json +2 -2
  108. package/src/forge/_generated/runtimeMatrix.ts +106177 -7917
  109. package/src/forge/_generated/runtimeRegistry.ts +1 -1
  110. package/src/forge/_generated/runtimeRules.md +1 -1
  111. package/src/forge/_generated/secretRegistry.json +1 -1
  112. package/src/forge/_generated/secretRegistry.ts +1 -1
  113. package/src/forge/_generated/secretsContext.ts +1 -1
  114. package/src/forge/_generated/serverApi.ts +1 -1
  115. package/src/forge/_generated/sourceMapManifest.json +2 -2
  116. package/src/forge/_generated/sourceMapManifest.ts +2 -2
  117. package/src/forge/_generated/sqlPlan.json +1 -1
  118. package/src/forge/_generated/sqlPlan.ts +1 -1
  119. package/src/forge/_generated/subscriptionManifest.json +2 -2
  120. package/src/forge/_generated/subscriptionManifest.ts +3 -3
  121. package/src/forge/_generated/symbolicationManifest.json +2 -2
  122. package/src/forge/_generated/symbolicationManifest.ts +2 -2
  123. package/src/forge/_generated/telemetryRegistry.json +2 -2
  124. package/src/forge/_generated/telemetryRegistry.ts +3 -3
  125. package/src/forge/_generated/telemetrySinks.json +2 -2
  126. package/src/forge/_generated/telemetrySinks.ts +2 -2
  127. package/src/forge/_generated/tenantScope.json +2 -2
  128. package/src/forge/_generated/tenantScope.ts +3 -3
  129. package/src/forge/_generated/testGraph.json +2 -2
  130. package/src/forge/_generated/testGraph.ts +75 -75
  131. package/src/forge/_generated/testPlanRegistry.json +2 -2
  132. package/src/forge/_generated/testPlanRegistry.ts +2 -2
  133. package/src/forge/_generated/uiRoutes.json +1 -1
  134. package/src/forge/_generated/uiRoutes.ts +1 -1
  135. package/src/forge/_generated/uiScenarios.json +1 -1
  136. package/src/forge/_generated/uiScenarios.ts +1 -1
  137. package/src/forge/_generated/uiTestManifest.json +2 -2
  138. package/src/forge/_generated/uiTestManifest.ts +2 -2
  139. package/src/forge/_generated/workflowRegistry.json +2 -2
  140. package/src/forge/_generated/workflowRegistry.ts +3 -3
  141. package/src/forge/_generated/workflowSubscriptions.json +2 -2
  142. package/src/forge/_generated/workflowSubscriptions.ts +3 -3
  143. package/src/forge/cli/commands.ts +861 -861
  144. package/src/forge/cli/deps.ts +178 -11
  145. package/src/forge/cli/index.ts +7 -7
  146. package/src/forge/cli/main.ts +54 -54
  147. package/src/forge/cli/output.ts +97 -97
  148. package/src/forge/cli/parse.ts +679 -673
  149. package/src/forge/cli/version.ts +1 -1
  150. package/src/forge/compiler/agent-contract/build.ts +28 -0
  151. package/src/forge/compiler/agent-contract/types.ts +16 -0
  152. package/src/forge/compiler/app-graph/build.ts +112 -112
  153. package/src/forge/compiler/app-graph/classify.ts +10 -10
  154. package/src/forge/compiler/app-graph/dup-symbol.ts +29 -29
  155. package/src/forge/compiler/app-graph/extract.ts +123 -123
  156. package/src/forge/compiler/app-graph/forge-apis.ts +29 -29
  157. package/src/forge/compiler/app-graph/index.ts +11 -11
  158. package/src/forge/compiler/app-graph/module-graph.ts +316 -316
  159. package/src/forge/compiler/app-graph/parser.ts +119 -119
  160. package/src/forge/compiler/app-graph/symbols.ts +48 -48
  161. package/src/forge/compiler/app-graph/tsconfig-hash.ts +62 -62
  162. package/src/forge/compiler/app-graph/types.ts +43 -43
  163. package/src/forge/compiler/app-graph/versions.ts +14 -14
  164. package/src/forge/compiler/cache/index.ts +17 -17
  165. package/src/forge/compiler/cache/key.ts +46 -46
  166. package/src/forge/compiler/cache/scheduler.ts +72 -72
  167. package/src/forge/compiler/cache/store.ts +78 -78
  168. package/src/forge/compiler/classifier/capabilities.ts +78 -78
  169. package/src/forge/compiler/classifier/classify.ts +113 -113
  170. package/src/forge/compiler/classifier/contexts.ts +188 -188
  171. package/src/forge/compiler/classifier/index.ts +18 -18
  172. package/src/forge/compiler/classifier/runtime-matrix.ts +45 -45
  173. package/src/forge/compiler/classifier/secrets.ts +41 -41
  174. package/src/forge/compiler/classifier/signals.ts +129 -129
  175. package/src/forge/compiler/diagnostics/codes.ts +125 -120
  176. package/src/forge/compiler/diagnostics/create.ts +87 -87
  177. package/src/forge/compiler/diagnostics/index.ts +41 -41
  178. package/src/forge/compiler/emitter/artifact-kind.ts +14 -14
  179. package/src/forge/compiler/emitter/barrel.ts +38 -38
  180. package/src/forge/compiler/emitter/constants.ts +7 -7
  181. package/src/forge/compiler/emitter/emit.ts +234 -237
  182. package/src/forge/compiler/emitter/index.ts +24 -24
  183. package/src/forge/compiler/emitter/lock.ts +61 -61
  184. package/src/forge/compiler/emitter/render.ts +73 -73
  185. package/src/forge/compiler/guards/artifacts.ts +96 -96
  186. package/src/forge/compiler/guards/check-import-guards.ts +106 -106
  187. package/src/forge/compiler/guards/index.ts +11 -11
  188. package/src/forge/compiler/guards/propagate-contexts.ts +57 -57
  189. package/src/forge/compiler/index.ts +17 -17
  190. package/src/forge/compiler/integration/add.ts +493 -493
  191. package/src/forge/compiler/integration/index.ts +17 -17
  192. package/src/forge/compiler/integration/plan.ts +279 -279
  193. package/src/forge/compiler/integration/render.ts +189 -189
  194. package/src/forge/compiler/integration/snapshot.ts +52 -52
  195. package/src/forge/compiler/orchestrator/discover.ts +214 -214
  196. package/src/forge/compiler/orchestrator/guards.ts +5 -5
  197. package/src/forge/compiler/orchestrator/index.ts +27 -27
  198. package/src/forge/compiler/orchestrator/manifest.ts +69 -69
  199. package/src/forge/compiler/orchestrator/orphans.ts +51 -51
  200. package/src/forge/compiler/orchestrator/plan.ts +804 -804
  201. package/src/forge/compiler/orchestrator/run.ts +178 -178
  202. package/src/forge/compiler/orchestrator/serialize.ts +859 -859
  203. package/src/forge/compiler/orchestrator/types.ts +23 -23
  204. package/src/forge/compiler/orchestrator/verify.ts +35 -35
  205. package/src/forge/compiler/package-graph/capabilities-stub.ts +33 -33
  206. package/src/forge/compiler/package-graph/checksum.ts +107 -97
  207. package/src/forge/compiler/package-graph/compiler.ts +444 -363
  208. package/src/forge/compiler/package-graph/constants.ts +4 -4
  209. package/src/forge/compiler/package-graph/exports-discovery.ts +91 -84
  210. package/src/forge/compiler/package-graph/extract-dts.ts +32 -32
  211. package/src/forge/compiler/package-graph/index.ts +24 -24
  212. package/src/forge/compiler/package-graph/jsdoc.ts +50 -50
  213. package/src/forge/compiler/package-graph/oracle.ts +326 -0
  214. package/src/forge/compiler/package-graph/read-file.ts +21 -21
  215. package/src/forge/compiler/package-graph/resolve.ts +131 -127
  216. package/src/forge/compiler/package-manager/adapter.ts +232 -232
  217. package/src/forge/compiler/package-manager/commands.ts +47 -47
  218. package/src/forge/compiler/package-manager/detect.ts +65 -65
  219. package/src/forge/compiler/package-manager/executor.ts +29 -29
  220. package/src/forge/compiler/package-manager/index.ts +22 -22
  221. package/src/forge/compiler/package-manager/parse-spec.ts +16 -16
  222. package/src/forge/compiler/package-manager/version.ts +20 -20
  223. package/src/forge/compiler/primitives/compare.ts +26 -26
  224. package/src/forge/compiler/primitives/hash.ts +42 -33
  225. package/src/forge/compiler/primitives/header.ts +43 -43
  226. package/src/forge/compiler/primitives/index.ts +45 -45
  227. package/src/forge/compiler/primitives/paths.ts +24 -24
  228. package/src/forge/compiler/primitives/serialize.ts +66 -66
  229. package/src/forge/compiler/primitives/sort.ts +87 -87
  230. package/src/forge/compiler/recipes/definitions.ts +269 -269
  231. package/src/forge/compiler/recipes/helpers.ts +37 -37
  232. package/src/forge/compiler/recipes/index.ts +21 -21
  233. package/src/forge/compiler/recipes/registry.ts +87 -87
  234. package/src/forge/compiler/sandbox/artifact-sanitize.ts +26 -26
  235. package/src/forge/compiler/sandbox/backends/child.ts +123 -123
  236. package/src/forge/compiler/sandbox/backends/docker.ts +173 -173
  237. package/src/forge/compiler/sandbox/index.ts +51 -51
  238. package/src/forge/compiler/sandbox/inspect.ts +143 -143
  239. package/src/forge/compiler/sandbox/inspector-entry.ts +115 -115
  240. package/src/forge/compiler/sandbox/limits.ts +31 -31
  241. package/src/forge/compiler/sandbox/scrub-env.ts +60 -60
  242. package/src/forge/compiler/sandbox/secret-scan.ts +54 -54
  243. package/src/forge/compiler/sandbox/serialize.ts +106 -106
  244. package/src/forge/compiler/sandbox/types.ts +7 -7
  245. package/src/forge/compiler/types/app-graph.ts +71 -71
  246. package/src/forge/compiler/types/capability.ts +29 -29
  247. package/src/forge/compiler/types/classification.ts +9 -9
  248. package/src/forge/compiler/types/cli.ts +85 -85
  249. package/src/forge/compiler/types/diagnostic.ts +2 -2
  250. package/src/forge/compiler/types/emit.ts +25 -25
  251. package/src/forge/compiler/types/import-guards.ts +19 -19
  252. package/src/forge/compiler/types/index.ts +98 -98
  253. package/src/forge/compiler/types/integration.ts +25 -25
  254. package/src/forge/compiler/types/json.ts +3 -3
  255. package/src/forge/compiler/types/lock.ts +37 -37
  256. package/src/forge/compiler/types/package-graph.ts +122 -77
  257. package/src/forge/compiler/types/runtime-matrix.ts +16 -16
  258. package/src/forge/compiler/types/runtime.ts +30 -30
  259. package/src/forge/compiler/types/sandbox.ts +24 -24
  260. package/src/forge/refactor/index.ts +10 -2
  261. package/src/forge/refactor/runtime-rename.ts +598 -0
  262. package/src/forge/version.ts +3 -0
package/.npmignore CHANGED
@@ -1 +1,9 @@
1
- # Staged publish copy. Package contents are controlled by package.json files.
1
+ # Package contents are primarily controlled by package.json "files".
2
+ node_modules/
3
+ .git/
4
+ .github/
5
+ .forge/
6
+ tests/
7
+ examples/
8
+ *.tgz
9
+ npm-debug.log*
package/AGENTS.md CHANGED
@@ -1,4 +1,4 @@
1
- // @forge-generated generator=0.0.0 input=6b855b87f2f57fce3e0939076b81cc0263cccfeae7bb969d2662613867b1c8ee content=972ba64a9c3df8fb49f4e4c7cb9892d6449d7833b9a303b748d08c5717d239e3
1
+ // @forge-generated generator=0.1.0-alpha.1 input=d50515ea2f22c012d06e8794c2031206c9478d732b15ce6592aa8bf74bdaa665 content=e0bf36433d915daf5ad06ac6265b3ac6f2cd1706269c69618bbbc1cb1f44e465
2
2
  # AGENTS.md
3
3
 
4
4
  <!-- forge-generated:start -->
@@ -69,6 +69,9 @@ forge inspect app --json
69
69
  forge inspect all --json
70
70
  forge inspect frontend --json
71
71
  forge inspect capabilities --json
72
+ forge deps inspect <package> --json
73
+ forge deps api <package> <symbol> --json
74
+ forge deps trace <package> --json
72
75
  forge auth check --json
73
76
  forge inspect runtime-matrix --json
74
77
  forge inspect policies --json
@@ -250,6 +253,8 @@ Use:
250
253
 
251
254
  ```bash
252
255
  forge deps upgrade-plan <package> --to latest
256
+ forge deps inspect <package> --json
257
+ forge deps api <package> <symbol> --json
253
258
  forge deps upgrade-apply <plan>
254
259
  forge verify --strict
255
260
  ```
package/CHANGELOG.md CHANGED
@@ -1,8 +1,23 @@
1
1
  # forgeos
2
2
 
3
+ ## 0.1.0-alpha.1
4
+
5
+ Republish alpha with the dependency/API oracle improvements:
6
+
7
+ - Added dependency API inspection commands for agents:
8
+ `forge deps api`, `forge deps trace`, and `forge deps runtime-compat`.
9
+ - Added dependency API summaries to `agentContract.json`.
10
+ - Added package resolution traces, runtime compatibility metadata, and
11
+ runtime/type mismatch diagnostics to `packageGraph`.
12
+ - Reduced package graph warning noise for `package.json` metadata exports,
13
+ declaration-file subpaths, and pattern exports.
14
+
3
15
  ## 0.1.0-alpha.0
4
16
 
5
17
  Initial alpha packaging baseline for ForgeOS.
6
18
 
7
19
  This release line is intended to validate npm installation, the `forge` CLI binary,
8
20
  template creation, generated contracts, and the agent-native local development loop.
21
+
22
+ Added ReadTheDocs-ready public documentation, generator/package version alignment
23
+ checks, and a broad generated-app field-test harness for release hardening.
package/CONTRIBUTING.md CHANGED
@@ -9,8 +9,29 @@ bun run typecheck
9
9
  bun test --timeout 120000
10
10
  node ./bin/forge.mjs verify --standard --script-timeout-ms 120000
11
11
  npm run release:smoke
12
+ npm run field:test -- --dry-run --json
12
13
  ```
13
14
 
15
+ Run a real external-app smoke before release candidates:
16
+
17
+ ```bash
18
+ npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
19
+ ```
20
+
21
+ Use the GitHub Actions `Field Tests` workflow for the broader OS, Node, package-manager matrix.
22
+
23
+ ## Documentation
24
+
25
+ Public docs are built with MkDocs on ReadTheDocs. The configuration lives in:
26
+
27
+ ```txt
28
+ .readthedocs.yaml
29
+ mkdocs.yml
30
+ docs/**
31
+ ```
32
+
33
+ Keep `docs/getting-started.md`, `docs/cli.md`, and `docs/field-testing.md` current when changing install, template, or verification behavior.
34
+
14
35
  ## Changesets
15
36
 
16
37
  For changes that should be published, add a changeset:
@@ -36,7 +57,7 @@ Configure the npm package `forgeos` with:
36
57
  | Environment | blank |
37
58
  | Allowed action | `npm publish` |
38
59
 
39
- Do not configure `NPM_TOKEN` for normal releases. The publish workflow uses GitHub OIDC with `id-token: write`, Node 24, npm 11+, and provenance.
60
+ 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.
40
61
 
41
62
  ## Manual Publish
42
63
 
package/README.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  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.
4
4
 
5
- **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.
5
+ **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.
6
+
7
+ Public docs are configured for ReadTheDocs with `.readthedocs.yaml` and `mkdocs.yml`. The local docs entrypoint is `docs/index.md`.
6
8
 
7
9
  ## Agent-First Quickstart
8
10
 
@@ -62,6 +64,15 @@ forge new local-app --template minimal-web --package-manager npm --local-forge
62
64
 
63
65
  `--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.
64
66
 
67
+ For broader field testing:
68
+
69
+ ```bash
70
+ npm run field:test -- --dry-run --json
71
+ npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
72
+ ```
73
+
74
+ The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
75
+
65
76
  ## What ForgeOS Generates
66
77
 
67
78
  ```txt
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forgeos",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.1",
4
4
  "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
5
5
  "type": "module",
6
6
  "files": [
@@ -37,6 +37,7 @@
37
37
  "release:pack": "npm pack --dry-run",
38
38
  "release:smoke": "node scripts/smoke-packed-package.mjs",
39
39
  "release:publish-local-alpha": "node scripts/publish-local-alpha.mjs",
40
+ "field:test": "node scripts/field-test-forgeos.mjs",
40
41
  "forge": "node ./bin/forge.mjs",
41
42
  "forge:node": "node ./bin/forge.mjs",
42
43
  "forge:bun": "node ./bin/forge-bun.mjs src/forge/cli/main.ts",
@@ -88,6 +89,7 @@
88
89
  "@changesets/changelog-github": "^0.7.0",
89
90
  "@changesets/cli": "^2.31.0",
90
91
  "@types/bun": "1.3.14",
92
+ "@types/node": "^24.0.0",
91
93
  "@types/react": "^19.2.17",
92
94
  "@types/react-test-renderer": "^19.1.0",
93
95
  "fast-check": "^3.23.2",
@@ -1,15 +1,15 @@
1
- export {
2
- loadForgeGuardArtifacts,
3
- type ForgeGuardArtifacts,
4
- } from "./src/load-artifacts.ts";
5
- export {
6
- checkSourceForgeGuards,
7
- type ForgeGuardSourceViolation,
8
- } from "./src/check-source.ts";
9
- export {
10
- runForgeGuardRule,
11
- forgeGuardRuleDefinition,
12
- formatViolationMessage,
13
- type ForgeEslintContext,
14
- type ForgeEslintSettings,
15
- } from "./src/rule-no-forge-guard-violation.ts";
1
+ export {
2
+ loadForgeGuardArtifacts,
3
+ type ForgeGuardArtifacts,
4
+ } from "./src/load-artifacts.ts";
5
+ export {
6
+ checkSourceForgeGuards,
7
+ type ForgeGuardSourceViolation,
8
+ } from "./src/check-source.ts";
9
+ export {
10
+ runForgeGuardRule,
11
+ forgeGuardRuleDefinition,
12
+ formatViolationMessage,
13
+ type ForgeEslintContext,
14
+ type ForgeEslintSettings,
15
+ } from "./src/rule-no-forge-guard-violation.ts";
@@ -1,10 +1,10 @@
1
- {
2
- "name": "eslint-plugin-forge",
3
- "version": "0.0.0",
4
- "private": true,
5
- "type": "module",
6
- "main": "./index.ts",
7
- "exports": {
8
- ".": "./index.ts"
9
- }
10
- }
1
+ {
2
+ "name": "eslint-plugin-forge",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "main": "./index.ts",
7
+ "exports": {
8
+ ".": "./index.ts"
9
+ }
10
+ }
@@ -1,95 +1,95 @@
1
- import { lookupMatrixEntry } from "../../../src/forge/compiler/classifier/runtime-matrix.ts";
2
- import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
3
- import type { RuntimeContext } from "../../../src/forge/compiler/types/runtime.ts";
4
- import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
5
- import { parsePackageSpecifier } from "../../../src/forge/compiler/app-graph/module-graph.ts";
6
-
7
- export interface ForgeGuardSourceViolation {
8
- packageName: string;
9
- context: RuntimeContext;
10
- rationale: string;
11
- line: number;
12
- column: number;
13
- endColumn: number;
14
- }
15
-
16
- const IMPORT_PATTERN =
17
- /(?:import\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?|export\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
18
-
19
- function lineColumnAtOffset(
20
- source: string,
21
- offset: number,
22
- ): { line: number; column: number } {
23
- const before = source.slice(0, offset);
24
- const lines = before.split("\n");
25
- return {
26
- line: lines.length,
27
- column: (lines.at(-1)?.length ?? 0) + 1,
28
- };
29
- }
30
-
31
- function effectiveContextsForFile(
32
- file: string,
33
- guards: ImportGuardsArtifact,
34
- ): RuntimeContext[] {
35
- const normalized = file.replace(/\\/g, "/");
36
- const entry = guards.moduleContexts.find(
37
- (module) =>
38
- module.file === normalized ||
39
- normalized.endsWith(`/${module.file}`) ||
40
- module.file.endsWith(normalized),
41
- );
42
- return entry?.effectiveContexts ?? [];
43
- }
44
-
45
- export function checkSourceForgeGuards(
46
- filePath: string,
47
- source: string,
48
- importGuards: ImportGuardsArtifact,
49
- runtimeMatrix: RuntimeMatrix,
50
- ): ForgeGuardSourceViolation[] {
51
- const effectiveContexts = effectiveContextsForFile(filePath, importGuards);
52
- if (effectiveContexts.length === 0) {
53
- return [];
54
- }
55
-
56
- const violations: ForgeGuardSourceViolation[] = [];
57
-
58
- for (const match of source.matchAll(IMPORT_PATTERN)) {
59
- const specifier = match[1] ?? match[2];
60
- if (!specifier) {
61
- continue;
62
- }
63
-
64
- const parsed = parsePackageSpecifier(specifier);
65
- if (!parsed) {
66
- continue;
67
- }
68
-
69
- const matrixEntry = lookupMatrixEntry(runtimeMatrix, parsed.packageName);
70
- if (matrixEntry == null) {
71
- continue;
72
- }
73
-
74
- const offset = match.index ?? 0;
75
- const start = lineColumnAtOffset(source, offset);
76
- const endColumn = start.column + match[0].length;
77
-
78
- for (const context of effectiveContexts) {
79
- if (!matrixEntry.compatible.includes(context)) {
80
- violations.push({
81
- packageName: parsed.packageName,
82
- context,
83
- rationale:
84
- matrixEntry.rationale[context] ??
85
- "package is incompatible with this runtime context",
86
- line: start.line,
87
- column: start.column,
88
- endColumn,
89
- });
90
- }
91
- }
92
- }
93
-
94
- return violations;
95
- }
1
+ import { lookupMatrixEntry } from "../../../src/forge/compiler/classifier/runtime-matrix.ts";
2
+ import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
3
+ import type { RuntimeContext } from "../../../src/forge/compiler/types/runtime.ts";
4
+ import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
5
+ import { parsePackageSpecifier } from "../../../src/forge/compiler/app-graph/module-graph.ts";
6
+
7
+ export interface ForgeGuardSourceViolation {
8
+ packageName: string;
9
+ context: RuntimeContext;
10
+ rationale: string;
11
+ line: number;
12
+ column: number;
13
+ endColumn: number;
14
+ }
15
+
16
+ const IMPORT_PATTERN =
17
+ /(?:import\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?|export\s+(?:type\s+)?(?:[\w*{}\s,]+from\s+)?)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
18
+
19
+ function lineColumnAtOffset(
20
+ source: string,
21
+ offset: number,
22
+ ): { line: number; column: number } {
23
+ const before = source.slice(0, offset);
24
+ const lines = before.split("\n");
25
+ return {
26
+ line: lines.length,
27
+ column: (lines.at(-1)?.length ?? 0) + 1,
28
+ };
29
+ }
30
+
31
+ function effectiveContextsForFile(
32
+ file: string,
33
+ guards: ImportGuardsArtifact,
34
+ ): RuntimeContext[] {
35
+ const normalized = file.replace(/\\/g, "/");
36
+ const entry = guards.moduleContexts.find(
37
+ (module) =>
38
+ module.file === normalized ||
39
+ normalized.endsWith(`/${module.file}`) ||
40
+ module.file.endsWith(normalized),
41
+ );
42
+ return entry?.effectiveContexts ?? [];
43
+ }
44
+
45
+ export function checkSourceForgeGuards(
46
+ filePath: string,
47
+ source: string,
48
+ importGuards: ImportGuardsArtifact,
49
+ runtimeMatrix: RuntimeMatrix,
50
+ ): ForgeGuardSourceViolation[] {
51
+ const effectiveContexts = effectiveContextsForFile(filePath, importGuards);
52
+ if (effectiveContexts.length === 0) {
53
+ return [];
54
+ }
55
+
56
+ const violations: ForgeGuardSourceViolation[] = [];
57
+
58
+ for (const match of source.matchAll(IMPORT_PATTERN)) {
59
+ const specifier = match[1] ?? match[2];
60
+ if (!specifier) {
61
+ continue;
62
+ }
63
+
64
+ const parsed = parsePackageSpecifier(specifier);
65
+ if (!parsed) {
66
+ continue;
67
+ }
68
+
69
+ const matrixEntry = lookupMatrixEntry(runtimeMatrix, parsed.packageName);
70
+ if (matrixEntry == null) {
71
+ continue;
72
+ }
73
+
74
+ const offset = match.index ?? 0;
75
+ const start = lineColumnAtOffset(source, offset);
76
+ const endColumn = start.column + match[0].length;
77
+
78
+ for (const context of effectiveContexts) {
79
+ if (!matrixEntry.compatible.includes(context)) {
80
+ violations.push({
81
+ packageName: parsed.packageName,
82
+ context,
83
+ rationale:
84
+ matrixEntry.rationale[context] ??
85
+ "package is incompatible with this runtime context",
86
+ line: start.line,
87
+ column: start.column,
88
+ endColumn,
89
+ });
90
+ }
91
+ }
92
+ }
93
+
94
+ return violations;
95
+ }
@@ -1,24 +1,24 @@
1
- import { readFileSync } from "node:fs";
2
- import { stripDeterministicHeader } from "../../../src/forge/compiler/primitives/header.ts";
3
- import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
4
- import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
5
-
6
- export interface ForgeGuardArtifacts {
7
- importGuards: ImportGuardsArtifact;
8
- runtimeMatrix: RuntimeMatrix;
9
- }
10
-
11
- function parseGeneratedJson<T>(path: string): T {
12
- const raw = stripDeterministicHeader(readFileSync(path, "utf8"));
13
- return JSON.parse(raw) as T;
14
- }
15
-
16
- export function loadForgeGuardArtifacts(
17
- importGuardsPath: string,
18
- runtimeMatrixPath: string,
19
- ): ForgeGuardArtifacts {
20
- const importGuards = parseGeneratedJson<ImportGuardsArtifact>(importGuardsPath);
21
- const runtimeMatrix = parseGeneratedJson<RuntimeMatrix>(runtimeMatrixPath);
22
-
23
- return { importGuards, runtimeMatrix };
24
- }
1
+ import { readFileSync } from "node:fs";
2
+ import { stripDeterministicHeader } from "../../../src/forge/compiler/primitives/header.ts";
3
+ import type { ImportGuardsArtifact } from "../../../src/forge/compiler/types/import-guards.ts";
4
+ import type { RuntimeMatrix } from "../../../src/forge/compiler/types/runtime-matrix.ts";
5
+
6
+ export interface ForgeGuardArtifacts {
7
+ importGuards: ImportGuardsArtifact;
8
+ runtimeMatrix: RuntimeMatrix;
9
+ }
10
+
11
+ function parseGeneratedJson<T>(path: string): T {
12
+ const raw = stripDeterministicHeader(readFileSync(path, "utf8"));
13
+ return JSON.parse(raw) as T;
14
+ }
15
+
16
+ export function loadForgeGuardArtifacts(
17
+ importGuardsPath: string,
18
+ runtimeMatrixPath: string,
19
+ ): ForgeGuardArtifacts {
20
+ const importGuards = parseGeneratedJson<ImportGuardsArtifact>(importGuardsPath);
21
+ const runtimeMatrix = parseGeneratedJson<RuntimeMatrix>(runtimeMatrixPath);
22
+
23
+ return { importGuards, runtimeMatrix };
24
+ }
@@ -1,93 +1,93 @@
1
- import type { ForgeGuardArtifacts } from "./load-artifacts.ts";
2
- import { loadForgeGuardArtifacts } from "./load-artifacts.ts";
3
- import {
4
- checkSourceForgeGuards,
5
- type ForgeGuardSourceViolation,
6
- } from "./check-source.ts";
7
-
8
- export interface ForgeEslintSettings {
9
- importGuardsPath?: string;
10
- runtimeMatrixPath?: string;
11
- }
12
-
13
- export interface ForgeEslintContext {
14
- filename: string;
15
- sourceCode: string;
16
- settings?: { forge?: ForgeEslintSettings };
17
- report: (descriptor: {
18
- message: string;
19
- line: number;
20
- column: number;
21
- endColumn: number;
22
- }) => void;
23
- }
24
-
25
- let cachedArtifacts: ForgeGuardArtifacts | null = null;
26
- let cachedKey = "";
27
-
28
- function resolveArtifacts(context: ForgeEslintContext): ForgeGuardArtifacts | null {
29
- const forgeSettings = context.settings?.forge;
30
- const importGuardsPath = forgeSettings?.importGuardsPath;
31
- const runtimeMatrixPath = forgeSettings?.runtimeMatrixPath;
32
-
33
- if (!importGuardsPath || !runtimeMatrixPath) {
34
- return null;
35
- }
36
-
37
- const key = `${importGuardsPath}|${runtimeMatrixPath}`;
38
- if (cachedArtifacts && cachedKey === key) {
39
- return cachedArtifacts;
40
- }
41
-
42
- cachedArtifacts = loadForgeGuardArtifacts(importGuardsPath, runtimeMatrixPath);
43
- cachedKey = key;
44
- return cachedArtifacts;
45
- }
46
-
47
- export function runForgeGuardRule(context: ForgeEslintContext): void {
48
- const artifacts = resolveArtifacts(context);
49
- if (!artifacts) {
50
- return;
51
- }
52
-
53
- const violations = checkSourceForgeGuards(
54
- context.filename,
55
- context.sourceCode,
56
- artifacts.importGuards,
57
- artifacts.runtimeMatrix,
58
- );
59
-
60
- for (const violation of violations) {
61
- context.report({
62
- message: `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`,
63
- line: violation.line,
64
- column: violation.column,
65
- endColumn: violation.endColumn,
66
- });
67
- }
68
- }
69
-
70
- export function formatViolationMessage(violation: ForgeGuardSourceViolation): string {
71
- return `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`;
72
- }
73
-
74
- export const forgeGuardRuleDefinition = {
75
- meta: {
76
- type: "problem" as const,
77
- docs: {
78
- description:
79
- "Disallow package imports incompatible with Forge effective runtime contexts",
80
- },
81
- schema: [],
82
- messages: {
83
- violation: "{{message}}",
84
- },
85
- },
86
- create(context: ForgeEslintContext) {
87
- return {
88
- Program() {
89
- runForgeGuardRule(context);
90
- },
91
- };
92
- },
93
- };
1
+ import type { ForgeGuardArtifacts } from "./load-artifacts.ts";
2
+ import { loadForgeGuardArtifacts } from "./load-artifacts.ts";
3
+ import {
4
+ checkSourceForgeGuards,
5
+ type ForgeGuardSourceViolation,
6
+ } from "./check-source.ts";
7
+
8
+ export interface ForgeEslintSettings {
9
+ importGuardsPath?: string;
10
+ runtimeMatrixPath?: string;
11
+ }
12
+
13
+ export interface ForgeEslintContext {
14
+ filename: string;
15
+ sourceCode: string;
16
+ settings?: { forge?: ForgeEslintSettings };
17
+ report: (descriptor: {
18
+ message: string;
19
+ line: number;
20
+ column: number;
21
+ endColumn: number;
22
+ }) => void;
23
+ }
24
+
25
+ let cachedArtifacts: ForgeGuardArtifacts | null = null;
26
+ let cachedKey = "";
27
+
28
+ function resolveArtifacts(context: ForgeEslintContext): ForgeGuardArtifacts | null {
29
+ const forgeSettings = context.settings?.forge;
30
+ const importGuardsPath = forgeSettings?.importGuardsPath;
31
+ const runtimeMatrixPath = forgeSettings?.runtimeMatrixPath;
32
+
33
+ if (!importGuardsPath || !runtimeMatrixPath) {
34
+ return null;
35
+ }
36
+
37
+ const key = `${importGuardsPath}|${runtimeMatrixPath}`;
38
+ if (cachedArtifacts && cachedKey === key) {
39
+ return cachedArtifacts;
40
+ }
41
+
42
+ cachedArtifacts = loadForgeGuardArtifacts(importGuardsPath, runtimeMatrixPath);
43
+ cachedKey = key;
44
+ return cachedArtifacts;
45
+ }
46
+
47
+ export function runForgeGuardRule(context: ForgeEslintContext): void {
48
+ const artifacts = resolveArtifacts(context);
49
+ if (!artifacts) {
50
+ return;
51
+ }
52
+
53
+ const violations = checkSourceForgeGuards(
54
+ context.filename,
55
+ context.sourceCode,
56
+ artifacts.importGuards,
57
+ artifacts.runtimeMatrix,
58
+ );
59
+
60
+ for (const violation of violations) {
61
+ context.report({
62
+ message: `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`,
63
+ line: violation.line,
64
+ column: violation.column,
65
+ endColumn: violation.endColumn,
66
+ });
67
+ }
68
+ }
69
+
70
+ export function formatViolationMessage(violation: ForgeGuardSourceViolation): string {
71
+ return `'${violation.packageName}' is not allowed in '${violation.context}' context: ${violation.rationale}`;
72
+ }
73
+
74
+ export const forgeGuardRuleDefinition = {
75
+ meta: {
76
+ type: "problem" as const,
77
+ docs: {
78
+ description:
79
+ "Disallow package imports incompatible with Forge effective runtime contexts",
80
+ },
81
+ schema: [],
82
+ messages: {
83
+ violation: "{{message}}",
84
+ },
85
+ },
86
+ create(context: ForgeEslintContext) {
87
+ return {
88
+ Program() {
89
+ runForgeGuardRule(context);
90
+ },
91
+ };
92
+ },
93
+ };
@@ -1,2 +1,2 @@
1
- // @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=8b0157f6f5ada213d0614d45aea3535d310f4aa74afce62dd6144a50d90375b2
2
- {"analyzerVersion":"0.1.0","byEvent":{},"diagnostics":[],"generatorVersion":"0.0.0","inputHash":"dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568","schemaVersion":"0.1.0","subscriptions":[]}
1
+ // @forge-generated generator=0.1.0-alpha.1 input=d50515ea2f22c012d06e8794c2031206c9478d732b15ce6592aa8bf74bdaa665 content=8f488b6c983f10308f100f4cf8180d2d1d35bc3c6f4cc1ef07e601718c7919df
2
+ {"analyzerVersion":"0.1.0","byEvent":{},"diagnostics":[],"generatorVersion":"0.1.0-alpha.1","inputHash":"a07f627a67301f9fec75b77a777eaa16189a423dea394ddca4a2a04e4f4df32a","schemaVersion":"0.1.0","subscriptions":[]}
@@ -1,10 +1,10 @@
1
- // @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=3651d5984e70296e09aab8a2ece35bceb207fecb9548fc9ac3067c091188f098
1
+ // @forge-generated generator=0.1.0-alpha.1 input=d50515ea2f22c012d06e8794c2031206c9478d732b15ce6592aa8bf74bdaa665 content=40b73d563f42e079c6094c5ee02cb6a9cfee3d83e73a7e8780303f9ceb6955f9
2
2
  export const actionSubscriptions = {
3
3
  "analyzerVersion": "0.1.0",
4
4
  "byEvent": {},
5
5
  "diagnostics": [],
6
- "generatorVersion": "0.0.0",
7
- "inputHash": "dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568",
6
+ "generatorVersion": "0.1.0-alpha.1",
7
+ "inputHash": "a07f627a67301f9fec75b77a777eaa16189a423dea394ddca4a2a04e4f4df32a",
8
8
  "schemaVersion": "0.1.0",
9
9
  "subscriptions": []
10
10
  } as const;