@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.
- package/.claude/skills/urlcode-authoring/SKILL.md +17 -19
- package/.claude/skills/urlcode-operations/SKILL.md +9 -9
- package/.claude-plugin/marketplace.json +1 -1
- package/CONTRIBUTING.md +20 -16
- package/README.md +59 -64
- package/ROADMAP.md +66 -376
- package/dist/BUILD-MANIFEST.json +26 -25
- package/dist/agents-guide.js +6 -6
- package/dist/authoring.js +15 -1
- package/dist/build-static.js +2 -0
- package/dist/capability-query.js +0 -1
- package/dist/catalog.js +0 -1
- package/dist/cli.js +25 -9
- package/dist/config.js +1 -1
- package/dist/explain-cli.js +4 -2
- package/dist/explain.js +8 -2
- package/dist/extensions.js +1 -1
- package/dist/http-response.js +1 -1
- package/dist/index.js +1 -0
- package/dist/init-with.js +36 -11
- package/dist/manifest.js +8 -2
- package/dist/mcp-authoring.js +4 -4
- package/dist/mcp.js +1 -1
- package/dist/policies/cache.js +2 -2
- package/dist/policies.js +3 -1
- package/dist/prerender.js +4 -0
- package/dist/project-dependencies.js +305 -0
- package/dist/readiness.js +3 -0
- package/dist/route-diff.js +12 -5
- package/dist/runtime.js +1 -1
- package/dist/trusted-functions.js +4 -5
- package/dist/types/authoring.d.ts +9 -1
- package/dist/types/capability-query.d.ts +0 -1
- package/dist/types/catalog.d.ts +0 -4
- package/dist/types/config.d.ts +1 -9
- package/dist/types/explain.d.ts +6 -1
- package/dist/types/extensions.d.ts +1 -1
- package/dist/types/http-response.d.ts +0 -1
- package/dist/types/index.d.ts +1 -0
- package/dist/types/init-with.d.ts +7 -13
- package/dist/types/manifest.d.ts +5 -2
- package/dist/types/project-dependencies.d.ts +78 -0
- package/dist/types/readiness.d.ts +2 -0
- package/dist/types/trusted-functions.d.ts +1 -4
- package/dist/types/types.d.ts +8 -1
- package/dist/types.js +8 -1
- package/dist/typescript-authoring.js +18 -7
- package/docs/AI-AUTHORING.md +15 -7
- package/docs/ASSETS.md +2 -1
- package/docs/AUTH-BACKUP.md +32 -0
- package/docs/AWS.md +9 -0
- package/docs/BEST-PRACTICES.md +17 -9
- package/docs/CAPABILITIES.md +1 -1
- package/docs/CI-FOLLOWUP-2026-09-19.md +97 -0
- package/docs/CI-RELEASE-AUDIT-2026-09-19.md +322 -0
- package/docs/CI.md +8 -3
- package/docs/CODEBASE-AUDIT-2026-09-20.md +284 -0
- package/docs/COMPOSING-A-SITE.md +278 -0
- package/docs/DEVELOPMENT-PIPELINE.md +270 -0
- package/docs/EXTENSIONS.md +51 -11
- package/docs/FRAMEWORK.md +67 -48
- package/docs/FUNCTION-SECURITY.md +44 -0
- package/docs/INSTALL.md +13 -8
- package/docs/LOCAL-DEVELOPMENT.md +3 -0
- package/docs/MIDDLEWARE.md +10 -4
- package/docs/OPEN-DECISIONS.md +224 -212
- package/docs/OPERATIONAL-PROOF.md +3 -3
- package/docs/OPERATIONS.md +3 -3
- package/docs/POLICIES.md +13 -5
- package/docs/PRERENDER.md +23 -11
- package/docs/PROJECT-DIRECTION.md +3 -3
- package/docs/READINESS.md +10 -5
- package/docs/README.md +20 -44
- package/docs/RELEASE-0.4.0-alpha.3.md +50 -0
- package/docs/RELEASE-0.4.1.md +73 -0
- package/docs/RELEASE-READINESS.md +6 -6
- package/docs/RELEASE-SECURITY.md +96 -181
- package/docs/RESILIENCE.md +3 -3
- package/docs/ROUTING.md +3 -4
- package/docs/SECURITY-AUDIT.md +2 -2
- package/docs/SPECIFICATION.md +12 -6
- package/docs/SPIKE-AI-FRAMEWORK-BENCHMARK.md +6 -5
- package/docs/SPIKE-BUSINESS-SUITE.md +14 -6
- package/docs/SPIKE-CORE-LAYERING.md +49 -18
- package/docs/SPIKE-DEFAULT-TRUST-MODEL.md +7 -5
- package/docs/STARTERS.md +17 -5
- package/docs/STATIC.md +14 -3
- package/docs/TOOLING.md +10 -7
- package/docs/TYPESCRIPT-AUTHORING.md +6 -1
- package/docs/VERCEL.md +10 -2
- package/docs/VERSION-ALIGNMENT.md +76 -201
- package/docs/archive/2026-09-19/EXTENSION-IMPLEMENTATION.md +68 -0
- package/docs/archive/2026-09-19/MANAGEMENT-SECURITY.md +102 -0
- package/docs/{NEXT-PHASE-PLAN.md → archive/2026-09-19/NEXT-PHASE-PLAN.md} +15 -5
- package/docs/{NEXT-STEPS.md → archive/2026-09-19/NEXT-STEPS.md} +15 -3
- package/docs/archive/2026-09-19/OPEN-DECISIONS.md +277 -0
- package/docs/archive/2026-09-19/RELEASE-SECURITY.md +186 -0
- package/docs/archive/2026-09-19/ROADMAP.md +387 -0
- package/docs/{SPIKE-EXTENSION-MODEL.md → archive/2026-09-19/SPIKE-EXTENSION-MODEL.md} +11 -0
- package/docs/{SPIKE-EXTENSIONS.md → archive/2026-09-19/SPIKE-EXTENSIONS.md} +25 -14
- package/docs/archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md +365 -0
- package/docs/archive/2026-09-19/SPIKE-MONOREPO.md +778 -0
- package/docs/{USABILITY-REVIEW.md → archive/2026-09-19/USABILITY-REVIEW.md} +12 -2
- package/docs/archive/README.md +28 -0
- package/docs/policies/agents.md +1 -1
- package/docs/policies/compression.md +3 -2
- package/docs/policies/security.md +3 -2
- package/docs/yaml/functions.md +10 -2
- package/docs/yaml/middleware.md +5 -3
- package/examples/assets/example.yaml +1 -1
- package/examples/cookbook/middleware/envelope.mjs +4 -2
- package/examples/cookbook/route-index.json +1 -1
- package/examples/cookbook/routes/middleware.yaml +1 -1
- package/examples/prerender/README.md +14 -6
- package/examples/prerender/functions/page.mjs +4 -2
- package/examples/prerender/middleware/template.mjs +1 -1
- package/examples/prerender/prerender.mjs +1 -1
- package/examples/prerender/urlcode.yaml +8 -4
- package/llms-full.txt +503 -88
- package/llms.txt +6 -4
- package/package.json +27 -4
- package/packaging/claude-plugin/.claude-plugin/plugin.json +2 -2
- package/packaging/claude-plugin/skills/urlcode-authoring/SKILL.md +17 -19
- package/packaging/claude-plugin/skills/urlcode-operations/SKILL.md +9 -9
- package/recipes/authenticated-json-api/README.md +4 -3
- package/recipes/authenticated-json-api/functions/profile.mjs +2 -1
- package/recipes/authenticated-json-api/recipe.yaml +1 -1
- package/recipes/contact-form/functions/contact.mjs +2 -1
- package/recipes/contact-form/recipe.yaml +2 -2
- package/recipes/cors-api/README.md +2 -2
- package/recipes/cors-api/recipe.yaml +1 -1
- package/recipes/health-page/README.md +1 -1
- package/recipes/json-api/README.md +1 -1
- package/recipes/json-api/recipe.yaml +3 -3
- package/recipes/middleware/README.md +8 -4
- package/recipes/middleware/middleware/envelope.mjs +4 -2
- package/recipes/protected-download/README.md +1 -1
- package/recipes/protected-download/recipe.yaml +1 -1
- package/recipes/static-plus-api/README.md +2 -2
- package/recipes/static-plus-api/public/index.html +1 -1
- package/recipes/static-plus-api/recipe.yaml +1 -1
- package/recipes/static-plus-api/urlcode.yaml +1 -1
- package/recipes/typescript/recipe.yaml +4 -4
- package/skills/urlcode/SKILL.md +6 -6
- package/starters/default/AGENTS.md +6 -6
- package/docs/SPIKE-LAMBDA-COMPILE.md +0 -201
- 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
|
|
6
|
-
|
|
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
|
-
|
|
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;
|
|
115
|
-
|
|
116
|
-
|
|
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
|
|
200
|
-
|
|
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
|
|
223
|
-
|
|
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
|
|
44
|
-
|
|
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 [
|
|
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
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
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](
|
|
55
|
-
| Manage users, sessions, roles and audit | [urlcode-admin](
|
|
56
|
-
| Restyle every extension page and translate copy | [urlcode-ui](
|
|
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
|
|
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
|
-
##
|
|
70
|
+
## Direction and evidence
|
|
87
71
|
|
|
88
|
-
|
|
89
|
-
|
|
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
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
|
111
|
-
|
|
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
|
|
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
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|