@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.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 (147) hide show
  1. package/.claude/skills/urlcode-authoring/SKILL.md +17 -19
  2. package/.claude/skills/urlcode-operations/SKILL.md +9 -9
  3. package/.claude-plugin/marketplace.json +1 -1
  4. package/CONTRIBUTING.md +20 -16
  5. package/README.md +59 -64
  6. package/ROADMAP.md +66 -376
  7. package/dist/BUILD-MANIFEST.json +26 -25
  8. package/dist/agents-guide.js +6 -6
  9. package/dist/authoring.js +15 -1
  10. package/dist/build-static.js +2 -0
  11. package/dist/capability-query.js +0 -1
  12. package/dist/catalog.js +0 -1
  13. package/dist/cli.js +25 -9
  14. package/dist/config.js +1 -1
  15. package/dist/explain-cli.js +4 -2
  16. package/dist/explain.js +8 -2
  17. package/dist/extensions.js +1 -1
  18. package/dist/http-response.js +1 -1
  19. package/dist/index.js +1 -0
  20. package/dist/init-with.js +36 -11
  21. package/dist/manifest.js +8 -2
  22. package/dist/mcp-authoring.js +4 -4
  23. package/dist/mcp.js +1 -1
  24. package/dist/policies/cache.js +2 -2
  25. package/dist/policies.js +3 -1
  26. package/dist/prerender.js +4 -0
  27. package/dist/project-dependencies.js +305 -0
  28. package/dist/readiness.js +3 -0
  29. package/dist/route-diff.js +12 -5
  30. package/dist/runtime.js +1 -1
  31. package/dist/trusted-functions.js +4 -5
  32. package/dist/types/authoring.d.ts +9 -1
  33. package/dist/types/capability-query.d.ts +0 -1
  34. package/dist/types/catalog.d.ts +0 -4
  35. package/dist/types/config.d.ts +1 -9
  36. package/dist/types/explain.d.ts +6 -1
  37. package/dist/types/extensions.d.ts +1 -1
  38. package/dist/types/http-response.d.ts +0 -1
  39. package/dist/types/index.d.ts +1 -0
  40. package/dist/types/init-with.d.ts +7 -13
  41. package/dist/types/manifest.d.ts +5 -2
  42. package/dist/types/project-dependencies.d.ts +78 -0
  43. package/dist/types/readiness.d.ts +2 -0
  44. package/dist/types/trusted-functions.d.ts +1 -4
  45. package/dist/types/types.d.ts +8 -1
  46. package/dist/types.js +8 -1
  47. package/dist/typescript-authoring.js +18 -7
  48. package/docs/AI-AUTHORING.md +15 -7
  49. package/docs/ASSETS.md +2 -1
  50. package/docs/AUTH-BACKUP.md +32 -0
  51. package/docs/AWS.md +9 -0
  52. package/docs/BEST-PRACTICES.md +17 -9
  53. package/docs/CAPABILITIES.md +1 -1
  54. package/docs/CI-FOLLOWUP-2026-09-19.md +97 -0
  55. package/docs/CI-RELEASE-AUDIT-2026-09-19.md +322 -0
  56. package/docs/CI.md +8 -3
  57. package/docs/CODEBASE-AUDIT-2026-09-20.md +284 -0
  58. package/docs/COMPOSING-A-SITE.md +278 -0
  59. package/docs/DEVELOPMENT-PIPELINE.md +270 -0
  60. package/docs/EXTENSIONS.md +51 -11
  61. package/docs/FRAMEWORK.md +67 -48
  62. package/docs/FUNCTION-SECURITY.md +44 -0
  63. package/docs/INSTALL.md +13 -8
  64. package/docs/LOCAL-DEVELOPMENT.md +3 -0
  65. package/docs/MIDDLEWARE.md +10 -4
  66. package/docs/OPEN-DECISIONS.md +224 -212
  67. package/docs/OPERATIONAL-PROOF.md +3 -3
  68. package/docs/OPERATIONS.md +3 -3
  69. package/docs/POLICIES.md +13 -5
  70. package/docs/PRERENDER.md +23 -11
  71. package/docs/PROJECT-DIRECTION.md +3 -3
  72. package/docs/READINESS.md +10 -5
  73. package/docs/README.md +20 -44
  74. package/docs/RELEASE-0.4.0-alpha.3.md +50 -0
  75. package/docs/RELEASE-0.4.1.md +73 -0
  76. package/docs/RELEASE-READINESS.md +6 -6
  77. package/docs/RELEASE-SECURITY.md +96 -181
  78. package/docs/RESILIENCE.md +3 -3
  79. package/docs/ROUTING.md +3 -4
  80. package/docs/SECURITY-AUDIT.md +2 -2
  81. package/docs/SPECIFICATION.md +12 -6
  82. package/docs/SPIKE-AI-FRAMEWORK-BENCHMARK.md +6 -5
  83. package/docs/SPIKE-BUSINESS-SUITE.md +14 -6
  84. package/docs/SPIKE-CORE-LAYERING.md +49 -18
  85. package/docs/SPIKE-DEFAULT-TRUST-MODEL.md +7 -5
  86. package/docs/STARTERS.md +17 -5
  87. package/docs/STATIC.md +14 -3
  88. package/docs/TOOLING.md +10 -7
  89. package/docs/TYPESCRIPT-AUTHORING.md +6 -1
  90. package/docs/VERCEL.md +10 -2
  91. package/docs/VERSION-ALIGNMENT.md +76 -201
  92. package/docs/archive/2026-09-19/EXTENSION-IMPLEMENTATION.md +68 -0
  93. package/docs/archive/2026-09-19/MANAGEMENT-SECURITY.md +102 -0
  94. package/docs/{NEXT-PHASE-PLAN.md → archive/2026-09-19/NEXT-PHASE-PLAN.md} +15 -5
  95. package/docs/{NEXT-STEPS.md → archive/2026-09-19/NEXT-STEPS.md} +15 -3
  96. package/docs/archive/2026-09-19/OPEN-DECISIONS.md +277 -0
  97. package/docs/archive/2026-09-19/RELEASE-SECURITY.md +186 -0
  98. package/docs/archive/2026-09-19/ROADMAP.md +387 -0
  99. package/docs/{SPIKE-EXTENSION-MODEL.md → archive/2026-09-19/SPIKE-EXTENSION-MODEL.md} +11 -0
  100. package/docs/{SPIKE-EXTENSIONS.md → archive/2026-09-19/SPIKE-EXTENSIONS.md} +25 -14
  101. package/docs/archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md +365 -0
  102. package/docs/archive/2026-09-19/SPIKE-MONOREPO.md +778 -0
  103. package/docs/{USABILITY-REVIEW.md → archive/2026-09-19/USABILITY-REVIEW.md} +12 -2
  104. package/docs/archive/README.md +28 -0
  105. package/docs/policies/agents.md +1 -1
  106. package/docs/policies/compression.md +3 -2
  107. package/docs/policies/security.md +3 -2
  108. package/docs/yaml/functions.md +10 -2
  109. package/docs/yaml/middleware.md +5 -3
  110. package/examples/assets/example.yaml +1 -1
  111. package/examples/cookbook/middleware/envelope.mjs +4 -2
  112. package/examples/cookbook/route-index.json +1 -1
  113. package/examples/cookbook/routes/middleware.yaml +1 -1
  114. package/examples/prerender/README.md +14 -6
  115. package/examples/prerender/functions/page.mjs +4 -2
  116. package/examples/prerender/middleware/template.mjs +1 -1
  117. package/examples/prerender/prerender.mjs +1 -1
  118. package/examples/prerender/urlcode.yaml +8 -4
  119. package/llms-full.txt +503 -88
  120. package/llms.txt +6 -4
  121. package/package.json +27 -4
  122. package/packaging/claude-plugin/.claude-plugin/plugin.json +2 -2
  123. package/packaging/claude-plugin/skills/urlcode-authoring/SKILL.md +17 -19
  124. package/packaging/claude-plugin/skills/urlcode-operations/SKILL.md +9 -9
  125. package/recipes/authenticated-json-api/README.md +4 -3
  126. package/recipes/authenticated-json-api/functions/profile.mjs +2 -1
  127. package/recipes/authenticated-json-api/recipe.yaml +1 -1
  128. package/recipes/contact-form/functions/contact.mjs +2 -1
  129. package/recipes/contact-form/recipe.yaml +2 -2
  130. package/recipes/cors-api/README.md +2 -2
  131. package/recipes/cors-api/recipe.yaml +1 -1
  132. package/recipes/health-page/README.md +1 -1
  133. package/recipes/json-api/README.md +1 -1
  134. package/recipes/json-api/recipe.yaml +3 -3
  135. package/recipes/middleware/README.md +8 -4
  136. package/recipes/middleware/middleware/envelope.mjs +4 -2
  137. package/recipes/protected-download/README.md +1 -1
  138. package/recipes/protected-download/recipe.yaml +1 -1
  139. package/recipes/static-plus-api/README.md +2 -2
  140. package/recipes/static-plus-api/public/index.html +1 -1
  141. package/recipes/static-plus-api/recipe.yaml +1 -1
  142. package/recipes/static-plus-api/urlcode.yaml +1 -1
  143. package/recipes/typescript/recipe.yaml +4 -4
  144. package/skills/urlcode/SKILL.md +6 -6
  145. package/starters/default/AGENTS.md +6 -6
  146. package/docs/SPIKE-LAMBDA-COMPILE.md +0 -201
  147. package/docs/SPIKE-MONOREPO.md +0 -322
package/docs/PRERENDER.md CHANGED
@@ -2,8 +2,10 @@
2
2
 
3
3
  Render a project's function and middleware routes once, at build time, into a
4
4
  project whose routes are all native `page` handlers. The published site answers
5
- from prevalidated byte buffers: no guest code runs to serve a request, so the
6
- sandbox, its deadline and its memory budget are not on the request path at all.
5
+ from prevalidated byte buffers: no guest code runs to serve a request at all,
6
+ so whatever execution mode the source routes used trusted by default, or
7
+ isolated QuickJS/WASM where a route declares `sandbox: true` — along with its
8
+ deadline and memory budget where sandboxed, is not on the request path.
7
9
 
8
10
  The shared orchestration ships as a build helper, `@jimhoyd/urlcode/prerender`, and the
9
11
  runnable recipe is [`examples/prerender`](../examples/prerender/README.md), which
@@ -24,7 +26,7 @@ and publish the result:
24
26
 
25
27
  ```
26
28
  function + template middleware ──render once──▶ HTML file ──▶ page route
27
- (sandbox, build time) (no sandbox)
29
+ (trusted or sandboxed, build time) (no guest code)
28
30
  ```
29
31
 
30
32
  The alternative — reading Markdown through `next().text()` on a native route —
@@ -111,9 +113,11 @@ specifically:
111
113
  instead of hanging on its worker threads.
112
114
 
113
115
  The helper is operator build tooling. It runs in Node with normal filesystem
114
- access because it is not guest code; nothing here gives the sandbox a filesystem,
115
- and no host-code fallback is introduced. It is a separate package export from the
116
- runtime for that reason. Review it as you review any deployment tooling.
116
+ access because it is not guest code; it does not itself widen a source route's
117
+ declared execution mode a route with `sandbox: true` still renders isolated,
118
+ with no filesystem, and no host-code fallback is introduced for it. It is a
119
+ separate package export from the runtime for that reason. Review it as you
120
+ review any deployment tooling.
117
121
 
118
122
  ## Assembling a site
119
123
 
@@ -196,8 +200,9 @@ Two consequences worth knowing:
196
200
  and their imports exceed the budgets cannot be split, and fails with the
197
201
  collector's message. That is a route to make smaller, not a pass to add.
198
202
 
199
- The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) renders
200
- 62 documentation pages this way.
203
+ The `urlcode-docs` site rendered 62 documentation pages this way. That
204
+ repository has since been deleted, so no link is given; the runnable
205
+ version of the same pattern is [`examples/prerender`](../examples/prerender/README.md).
201
206
 
202
207
  ## Larger sites: generating the source project
203
208
 
@@ -219,9 +224,8 @@ things to hold onto:
219
224
  interpolates, but content injected as raw HTML is published as written. Whatever
220
225
  produces that HTML owns its safety.
221
226
 
222
- The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) builds
223
- its site this way. That is a working integration, not a deployment or performance
224
- claim.
227
+ The `urlcode-docs` site built itself this way before that repository was
228
+ retired. It was a working integration, not a deployment or performance claim.
225
229
 
226
230
  ## What this is not
227
231
 
@@ -231,3 +235,11 @@ native bodies readable. Not a template engine — the template is ordinary
231
235
  middleware you write. Not a CLI command: prerendering is a step inside a build
232
236
  that already runs JavaScript, so the helper is a library. Content compilation,
233
237
  sanitization, search, asset assembly and deployment stay in the application.
238
+
239
+
240
+ Trusted build-time functions and middleware use ordinary Node imports, including
241
+ npm packages and dynamic imports. The pass planner applies source-graph budgets
242
+ only to `sandbox: true` routes; it does not parse trusted modules as sandbox
243
+ code. Page-count and output-byte budgets still apply to both modes. After
244
+ rendering, emit native page/file routes without middleware, then use the static
245
+ build target. Static hosting cannot execute middleware on incoming requests.
@@ -40,8 +40,8 @@ capability grants. Application data stays in the operator's systems.
40
40
 
41
41
  - **Not a URL shortener.** Core is redirects, validated responses, request
42
42
  functions, middleware, pages, static assets and downloads. Stored short
43
- links are moving to a future `urlcode-dynamic-link` extension package
44
- (mount-based, like `auth`/`admin`, not yet published), not a core handler.
43
+ links are not a core handler; the `urlcode-dynamic-link` extension package
44
+ that owned them has been retired and unpublished.
45
45
  - **Not a general Node web framework.** There is no framework code to write
46
46
  for routing, validation, middleware wiring or policies — those are declared
47
47
  in YAML and enforced by the runtime. Function/middleware code that needs
@@ -104,7 +104,7 @@ lines an agent generated, how many are the idea and how many are plumbing. A
104
104
  traditional build might be 2,900 lines of business logic inside 18,400; the
105
105
  same application on URLCode should be the same 2,900 inside a few thousand.
106
106
  Until a reproducible benchmark shows that ratio, the thesis is a hypothesis,
107
- and [next steps](NEXT-STEPS.md) puts the benchmark before the features.
107
+ and [the roadmap](../ROADMAP.md) puts the benchmark before the features.
108
108
 
109
109
  ## License
110
110
 
package/docs/READINESS.md CHANGED
@@ -10,21 +10,26 @@ urlcode audit --project ../my-links --expect-routes 2
10
10
  urlcode benchmark --project ../my-links --requests 1000 --concurrency 2 --max-p95-ms 50
11
11
  ```
12
12
 
13
- All three activate/validate the project with the same isolated runtime and use
14
- local environment loading like `test`. Pass an external `--policy` for explicitly
15
- authorized bindings. No destination redirects are followed, credentials are not
13
+ All three activate/validate the project with the same runtime that serves it --
14
+ each route in its own declared trust mode, trusted in-process unless it declares
15
+ `sandbox: true` -- and use local environment loading like `test`. Pass an
16
+ external `--policy` for explicitly authorized bindings. No destination redirects are followed, credentials are not
16
17
  printed, and no remote load-test target is accepted.
17
18
 
18
19
  ## Inventory and count reconciliation
19
20
 
20
- `routes` reports each configured route's pattern, handler, exact allowed methods
21
+ `routes` reports each configured route's pattern, handler, exact allowed methods,
22
+ execution mode (`sandbox`, with `sandboxReason` when the route declares one)
21
23
  and active/disabled/expired state. It includes routes from YAML includes. A
22
24
  parameter pattern is one route; its possible URLs are not a finite route count.
23
25
  A static mount is one route, even when it contains many files.
24
26
 
25
27
  `routes --compare previous.json` diffs the current inventory against a saved
26
28
  `routes` report: added, removed and changed routes (handler, methods, state,
27
- middleware count, policies, generated marker and the policy description). It
29
+ execution mode and its reason, middleware count, policies, generated marker and
30
+ the policy description). A route that flips between trusted and sandboxed
31
+ execution is a change, including when its handler is native and only its
32
+ middleware runs project code. It
28
33
  prints JSON, or Markdown tables with `--format markdown`, and always exits 0;
29
34
  it reports, it does not judge. The [GitHub action](CI.md) posts this diff on
30
35
  pull requests.
package/docs/README.md CHANGED
@@ -1,15 +1,5 @@
1
1
  # URLCode documentation
2
2
 
3
- > **Public documentation is authored in a separate `urlcode-docs` repository,
4
- > not generated from this tree.** New reader-facing pages belong there; `docs/`
5
- > here keeps contributor and maintainer material (local development, CI, release
6
- > process, reviews, spikes, plans and the generated field reference). The
7
- > reader-facing pages still listed below are being migrated.
8
- >
9
- > `urlcode-docs` is currently private, so it isn't publicly browsable yet —
10
- > until it is, this file and this repository's README are the practical
11
- > reference.
12
-
13
3
  Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
14
4
  redirects to a full application, the composition contract and the rules an AI
15
5
  agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
@@ -26,8 +16,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
26
16
  | Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
27
17
  | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
28
18
  | Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
29
- | Explore a standalone application | [URLCode Short demo](https://github.com/jimhoyd-com/urlcode-short), [build retrospective](https://github.com/jimhoyd-com/urlcode-short/blob/main/docs/BUILD-RETROSPECTIVE.md) |
30
- | Explore a static docs-site integration | URLCode Docs project (private repository; not yet publicly browsable) |
31
19
  | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
32
20
  | Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
33
21
  | Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
@@ -51,10 +39,11 @@ boundary and the license. Use documentation pinned to your runtime revision;
51
39
 
52
40
  | Goal | Start here |
53
41
  |---|---|
54
- | Add accounts, sign-in and protected routes | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth#readme) |
55
- | Manage users, sessions, roles and audit | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin#readme) |
56
- | Restyle every extension page and translate copy | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
42
+ | Add accounts, sign-in and protected routes | [urlcode-auth](../packages/auth#readme), [auth security](../packages/auth/SECURITY.md) |
43
+ | Manage users, sessions, roles and audit | [urlcode-admin](../packages/admin#readme) |
44
+ | Restyle every extension page and translate copy | [urlcode-ui](../packages/ui#readme), [ui contract](../packages/ui/CONTRACT.md) |
57
45
  | Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
46
+ | Follow implementation of the auth, admin and UI extensions | [Extension implementation sequence](archive/2026-09-19/EXTENSION-IMPLEMENTATION.md) |
58
47
  | Know which core version an extension package supports, and how it says so | [Core version alignment](VERSION-ALIGNMENT.md) |
59
48
  | Add host behavior in operator code | [Plugins](PLUGINS.md) |
60
49
  | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
@@ -70,12 +59,7 @@ boundary and the license. Use documentation pinned to your runtime revision;
70
59
  | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
71
60
  | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
72
61
  | See unfinished work | [Roadmap](../ROADMAP.md) |
73
- | Read the design behind policies, plugins and templates | [Extensions spike](SPIKE-EXTENSIONS.md) |
74
- | Read the design for an authentication and authorization plugin | [Auth spike](SPIKE-AUTH.md) |
75
- | Read the design for the administration extension that manages users | [Admin spike](SPIKE-ADMIN.md) |
76
- | Read the design for the shared template kit every extension renders with | [UI kit spike](SPIKE-UI.md) |
77
- | Read the review of the extension model, its precedents and alignment | [Extension model review](SPIKE-EXTENSION-MODEL.md) |
78
- | Read the design for compiling function routes into per-route Lambdas | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) |
62
+ | Read why per-route Lambda compilation was declined | [Lambda compile spike (archived)](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md) |
79
63
  | Verify a running deployment matches the project | [Deployment checks](DEPLOYMENT-CHECKS.md) |
80
64
  | Inspect target support | [Capabilities and normalized representation](CAPABILITIES.md) |
81
65
  | Deploy to Vercel, AWS Lambda or Cloudflare Workers | [Vercel](VERCEL.md), [AWS](AWS.md), [Cloudflare](CLOUDFLARE.md), [provider verification evidence](PROVIDER-VERIFICATION.md) |
@@ -83,29 +67,21 @@ boundary and the license. Use documentation pinned to your runtime revision;
83
67
  | Estimate concurrency and memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md), [load testing](LOAD-TESTING.md) |
84
68
  | Prepare for overload, DDoS and recovery | [Resilience playbook](RESILIENCE.md) |
85
69
 
86
- ## Evidence, reviews and design records
70
+ ## Direction and evidence
87
71
 
88
- These are dated records, not guides. They say what has been checked and what
89
- has not, and why the design is the way it is.
72
+ Start with [principles and open decisions](OPEN-DECISIONS.md) for a plain-language
73
+ review and [the roadmap](../ROADMAP.md) for next work. Current behavior belongs
74
+ in the guides above and the [specification](SPECIFICATION.md).
90
75
 
91
- | Record | What it is |
92
- |---|---|
93
- | [Release readiness](RELEASE-READINESS.md) | Verified safeguards, open gates, supported scope |
94
- | [Usability review](USABILITY-REVIEW.md) | Where the framework is easier or harder than the tools it replaces, and ranked changes |
95
- | [Next steps](NEXT-STEPS.md) | The phased plan: agent discovery, context compression, retrieval, the ladder, benchmarks and the remaining proof gaps |
96
- | [AI-first framework benchmark spike](SPIKE-AI-FRAMEWORK-BENCHMARK.md) | Proposed research-first, independent-agent application and runtime benchmark with a verified issue/improvement loop |
97
- | [Next-phase implementation status](NEXT-PHASE-PLAN.md) | Source additions after 0.3.0 shipped in 0.4.0-alpha.1, and their evidence limits |
98
- | [Security review](SECURITY-AUDIT.md) | Internal findings and fixes; not an independent test |
99
- | [Standards audit](STANDARDS.md) | How the runtime conforms to the RFCs it touches |
100
- | [Sandbox review package](SANDBOX-REVIEW.md) | What an independent reviewer needs; assessment not yet performed |
101
- | [Operational drills](OPERATIONAL-PROOF.md) | Deployment acceptance drills CI runs |
102
- | [Release security](RELEASE-SECURITY.md) | Candidate signing and publication process |
103
- | [Core version alignment](VERSION-ALIGNMENT.md) | The supported core floor for each downstream repository, how it is declared, and the publish-then-raise-then-regenerate order |
104
- | [Extension model review](SPIKE-EXTENSION-MODEL.md) | Why extensions are shaped this way, with framework precedents |
105
- | [Extensions spike](SPIKE-EXTENSIONS.md) | The design behind policies and plugins; implemented |
106
- | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) | Proposal: per-route Lambdas for functions; not implemented |
107
- | Auth, admin and UI spikes | Live in their repositories: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md), [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/docs/SPIKE-ADMIN.md), [ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/docs/SPIKE-UI.md) |
108
- | [Roadmap](../ROADMAP.md) | Implemented versus planned |
76
+ - [Release readiness](RELEASE-READINESS.md), [security audit](SECURITY-AUDIT.md),
77
+ [sandbox review](SANDBOX-REVIEW.md) and [provider evidence](PROVIDER-VERIFICATION.md)
78
+ distinguish implementation from evidence still missing.
79
+ - [Version alignment](VERSION-ALIGNMENT.md) and [release security](RELEASE-SECURITY.md)
80
+ describe peer compatibility and publication.
81
+ - Open proposals: [middleware layering](SPIKE-CORE-LAYERING.md),
82
+ [agent benchmark](SPIKE-AI-FRAMEWORK-BENCHMARK.md), and
83
+ [business suite](SPIKE-BUSINESS-SUITE.md). None is an implementation promise.
84
+ - [Historical plans and reviews](archive/README.md) are archived separately.
109
85
 
110
- Examples are educational unless backed by the runnable cookbook and fixtures.
111
- Infrastructure limits are deployment settings, not fields to invent in route YAML.
86
+ Examples are educational unless backed by runnable fixtures. Infrastructure
87
+ limits are deployment settings, not fields to invent in route YAML.
@@ -0,0 +1,50 @@
1
+ # Coordinated 0.4.0-alpha.3 release
2
+
3
+ This release prepares core, UI, auth and admin at `0.4.0-alpha.3`, as explicitly
4
+ selected by the maintainer. The shared number identifies this tested package
5
+ set; it does not enable permanent fixed versioning or leave the alpha channel.
6
+ Existing versions, tags, and npm `latest` channels are preserved.
7
+
8
+ ## Included changes
9
+
10
+ Core includes the monorepo consolidation, corrected Windows npm invocation,
11
+ current trust-by-default authoring guidance, and support for a TypeScript module
12
+ shared by trusted and sandboxed routes without weakening the sandbox checks.
13
+ The CLI and MCP report the new runtime version. The runtime remains independent
14
+ of the extension implementations.
15
+
16
+ Auth includes deterministic worker cleanup on rejected initialization and
17
+ Windows backup flushing. Auth/admin refresh a lifecycle hook's entry module on
18
+ each activation; changes to the entry module's own imports still require restart.
19
+ The extension changelogs record their package-specific changes.
20
+
21
+ All four packages use the shared release coordinator, immutable release tags,
22
+ exact-commit full verification, retained retry artifacts and trusted npm
23
+ publication. The candidate rehearsal installs their tarballs together outside
24
+ the workspace and checks peers, public imports and scaffolding.
25
+
26
+ ## Installation and compatibility
27
+
28
+ Once publication has completed, install an exact, coordinated set in the
29
+ consumer application's directory:
30
+
31
+ ```sh
32
+ npm install --save-exact @jimhoyd/urlcode@0.4.0-alpha.3 @jimhoyd/urlcode-ui@0.4.0-alpha.3 @jimhoyd/urlcode-auth@0.4.0-alpha.3 @jimhoyd/urlcode-admin@0.4.0-alpha.3
33
+ ```
34
+
35
+ Applications only need the extensions they actually use; admin requires auth
36
+ and UI, and auth requires UI. Auth/admin peer floors for this release are
37
+ `>=0.4.0-alpha.3 <0.5.0`. Update their dependencies together when crossing from
38
+ the former `0.1.x` extension line. Commit the resulting lockfile and use `npm ci`
39
+ in deployment. This release changes package peer compatibility intentionally;
40
+ it does not imply all previously mixed versions are supported.
41
+
42
+ Publication order is core, UI, auth, admin. A partial release stops before the
43
+ next package; diagnose and rerun its original workflow without moving tags.
44
+ The standalone template remains an exact core consumer and is updated through
45
+ its own PR after core is published. Archived extension repositories are not
46
+ publication targets.
47
+
48
+ CI and candidate success are not independent security assessment, live-provider
49
+ acceptance, or operational recovery proof. The intermittent Windows startup
50
+ timeout remains tracked in #202.
@@ -0,0 +1,73 @@
1
+ # URLCode 0.4.1
2
+
3
+ Core, UI, auth and admin share this explicitly selected stable version. This does not enable permanent fixed versioning. Internal peer minimums advance to this version; install the coordinated set together.
4
+
5
+ ```sh
6
+ npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
7
+ ```
8
+
9
+ This coordinated release moves core, UI, auth and admin from `0.4.0-alpha.3` to stable `0.4.1`. It makes the reviewed monorepo release line available through npm `latest` and keeps the four packages' peer minimums aligned.
10
+
11
+ The runtime retains its existing trust model: project functions and middleware run trusted in Node by default; routes declaring `sandbox: true` retain QuickJS/WASM isolation. The stable label is a distribution decision, not an independent security assessment or hostile multi-tenant readiness claim.
12
+
13
+ Release preparation now supports an explicit exit from alpha. Publication promotes the exact signed candidate archives, pins their manifest digest in immutable tags, checks actual npm installability, and updates the standalone starter to the published core version. Historical alpha versions and tags remain unchanged.
14
+
15
+ ### admin-kit-only-console.md
16
+
17
+ **Breaking:** the console renders only through the urlcode-ui kit. `ui` is now a
18
+ required option of `adminExtension` and of `createAdministrationRuntime`'s
19
+ `admin` block, which is itself no longer optional.
20
+
21
+ `@jimhoyd/urlcode-ui` was already a required peer dependency, so nothing new has
22
+ to be installed. What changed is that the `ui` *extension* must now be supplied
23
+ and active: the primitive render path — the same `admin/*` templates rendered
24
+ through the shared primitives inside a console shell admin built itself — is
25
+ gone, along with the `RenderPath` seam, the `activeKit()` helper, the
26
+ `ScreenOptions.shell.sidebar` markup and `src/admin-presentation.ts`. The kit
27
+ builds the sidebar, page header and skip target from the `nav` items and account
28
+ `menu` admin supplies, so the console shell has one representation instead of
29
+ two. `ScreenOptions.preferences` is gone too: the kit layout now renders through
30
+ the same resolved presentation as the body, so the document's `lang` matches the
31
+ copy on the page.
32
+
33
+ Activation refuses up front, rather than failing per request in production, when
34
+
35
+ - `ui` is missing,
36
+ - `ui` is supplied but not active yet — declare `ui` before `admin` under
37
+ `extensions` in `urlcode.yaml`, since the runtime activates in declaration
38
+ order, and mount its assets route, or
39
+ - the kit was built without `adminUiTemplates`.
40
+
41
+ To migrate, build the extension with admin's templates and pass it:
42
+
43
+ ```js
44
+ const ui = createUiExtension({projectSha256, projectRoot, sources: [authCatalogue], extensions: [authUiTemplates, adminUiTemplates]});
45
+ adminExtension({service, csrfKey, projectSha256, ui});
46
+ ```
47
+
48
+ Scaffolding emits that wiring for you: `scaffold()`, `initAdministration` and
49
+ `urlcode init --with ui,auth,admin` compose the kit and register the admin
50
+ templates with it. `ui` is now required, and must come before `admin`; the
51
+ scaffold refuses otherwise before writing anything.
52
+
53
+ ### auth-kit-only-render.md
54
+
55
+ Breaking: the `ui` extension is now required. Every account screen renders through the `urlcode-ui` kit; the shared-primitive fallback is gone. `authExtension({ui, ...})` refuses activation when `ui` is absent or when the runtime has not activated it, naming the missing piece instead of failing per request. Declare `ui` before `auth` in `urlcode.yaml` (with its asset route) and list `ui.registration` before `authExtension` in the host: the runtime activates extensions in the order `urlcode.yaml` declares them. `@jimhoyd/urlcode-ui` was already a required peer dependency, so nothing new needs installing; what changes is that the extension must be supplied and active. `ScreenOptions.ui` is no longer optional and `screenObserver` no longer reports a render path.
56
+
57
+ Scaffolding composes the kit for you: `urlcode init --with ui,auth` and the standalone `initAuthentication` now write a project whose `urlcode.yaml` declares `ui` first and whose host passes it to `authExtension`. The scaffold refuses when `ui` is missing, or ordered after `auth`, before anything is written.
58
+
59
+ ### auth-store-startup-diagnostics.md
60
+
61
+ Report which startup phase an auth store worker reached when its 15-second bound elapses, and reject at once when the worker fails or exits before reporting readiness instead of waiting the bound out. The status and code are unchanged; the detail is attached as the error's cause for operator logs and never reaches a response.
62
+
63
+ ### pin-generated-site-dependencies.md
64
+
65
+ `urlcode-auth init` now writes a `package.json` that pins this package and each declared peer at the exact version installed beside it, instead of a manifest with no dependencies at all; `initAuthentication` returns those pins and names any peer it could not resolve. Nothing is installed: running `npm install` in the generated directory to produce a lockfile stays the operator's explicit step, and no upgrade command exists.
66
+
67
+ ### ui-scaffold-peer-registration.md
68
+
69
+ The scaffold wires kit-rendering peers into the host it generates. `scaffold()` reads the composed `names` and emits `createUiExtension({..., sources: [authCatalogue], extensions: [authUiTemplates, adminUiTemplates]})`, importing each peer it needs, so `urlcode init --with ui,auth,admin` produces a project that activates. Previously it always wrote `sources: []` and no `extensions`, which left auth and admin without their copy and templates. `ui` alone still registers nothing and imports no peer.
70
+
71
+ Name `ui` first: the runtime activates extensions in the order `urlcode.yaml` declares them, core writes that file in `--with` order, and auth and admin both refuse to activate before the kit is active.
72
+
73
+ Publish to the npm `latest` channel in core → UI → auth → admin order after exact-commit CI and candidate verification. Existing tags and the `alpha` channel stay unchanged; this stable release advances `latest`. Changesets prerelease mode is exited. Update the standalone starter's exact core pin after registry installability is verified. This preparation is not evidence of publication or an independent security assessment.
@@ -41,7 +41,7 @@ deferred to the post-merge run.
41
41
  | Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Bounded by the configured worker count; no cross-process load balancing |
42
42
  | Shutdown | New work rejects; repeated close shares completion | Existing deadlines can still fail during shutdown |
43
43
  | Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration |
44
- | Packaging | Packed installation and starter examples tested; sensitive files excluded | `0.3.0` and `0.4.0-alpha.1` are published to npm as `@jimhoyd/urlcode` (`latest` and `alpha` dist-tags respectively; dist-tags verified against the npm registry on 2026-09-19, when the repository stood at the unpublished `0.4.0-alpha.2`). Published extension packages on the same date: `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`, `@jimhoyd/urlcode-ui@0.1.0-alpha.4`, `@jimhoyd/urlcode-short@0.1.0-alpha.1`, `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1`, `@jimhoyd/urlcode-middleware@0.1.0-alpha.1`. Observed in passing: auth's dist-tags are split — `alpha` points at `0.1.0-alpha.2` while `latest` still points at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolves the older alpha. GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
44
+ | Packaging | Packed installation and starter examples tested; sensitive files excluded | `0.3.0` and `0.4.0-alpha.1` are published to npm as `@jimhoyd/urlcode` (`latest` and `alpha` dist-tags respectively; dist-tags verified against the npm registry on 2026-09-19, when the repository stood at the unpublished `0.4.0-alpha.2`). Published extension packages on the same date: `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`, `@jimhoyd/urlcode-ui@0.1.0-alpha.4`. (`@jimhoyd/urlcode-short@0.1.0-alpha.1`, `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` and `@jimhoyd/urlcode-middleware@0.1.0-alpha.2` were also published on that date, then retired and unpublished later the same day; all three repositories were deleted. Middleware's withdrawal removed no capability — per-route middleware is native to core.) Observed in passing on that date: auth's dist-tags were split — `alpha` at `0.1.0-alpha.2` while `latest` lagged at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolved a build below admin's declared floor. That is resolved: auth and admin both read `latest` = `alpha` = `0.1.0-alpha.3`. `@jimhoyd/urlcode-ui` now carries a split of its own — `alpha` = `0.1.0-alpha.6`, `latest` = `0.1.0-alpha.5` — which is deliberate rather than drift, and safe only because admin's ui floor is exactly `>=0.1.0-alpha.5`. See [VERSION-ALIGNMENT.md](VERSION-ALIGNMENT.md). GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
45
45
 
46
46
  `npm run check:downstream-skills` is a manual, advisory report worth running
47
47
  before a release: it diffs core's `.claude/skills/` copies against copies
@@ -93,7 +93,7 @@ local recipes, TypeScript authoring, bounded self-hosted proxy/signals and read-
93
93
  MCP. Local AWS/Vercel/Cloudflare adapter tests and deployment probe tooling exist,
94
94
  but actual provider deployments remain unverified. Node process/container hosting
95
95
  remains the reference execution target. Guest networking, durable signals and
96
- realtime capabilities are not provided. See [implementation status](NEXT-PHASE-PLAN.md)
96
+ realtime capabilities are not provided. See [implementation status](archive/2026-09-19/NEXT-PHASE-PLAN.md)
97
97
  and [roadmap](../ROADMAP.md); these additions do not close the operational gates above.
98
98
 
99
99
  The [internal security audit](SECURITY-AUDIT.md) records reproduced findings, fixes
@@ -107,10 +107,10 @@ compilation deadline, scoped/expiring/revocable operator credentials for host
107
107
  bindings, executable local/CI operational drills, and a main-only candidate
108
108
  signing/SBOM workflow. The loopback-only management API and its atomic SQLite
109
109
  mutation audits were part of the `link`/`dynamicLinks` store that PR #126
110
- removed from core; that functionality, and its hardening, now belongs to the
111
- `urlcode-dynamic-link` extension (docs/EXTENSIONS.md), published on npm as
112
- `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` as of 2026-09-19, not this
113
- runtime.
110
+ removed from core; that functionality moved to the `urlcode-dynamic-link`
111
+ extension (docs/EXTENSIONS.md), which was retired and unpublished on
112
+ 2026-09-19. No supported stored-link package ships today, and this runtime does
113
+ not provide one: a project needing a durable link store owns it itself.
114
114
 
115
115
  Still required: [independent review](SANDBOX-REVIEW.md), [actual deployment proof](OPERATIONAL-PROOF.md),
116
116
  and publication/support arrangements. The Apache-2.0 license and the 0.3.0 self-hosted