@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/llms.txt

@@ -66,7 +66,8 @@ fields or bypass target limits or operator grants. See [the design principle](do
 - [Interchange](docs/INTERCHANGE.md), [bulk import](docs/BULK.md), [recipes](docs/RECIPES.md) (`urlcode recipes search`, `examples search`), [TypeScript guests](docs/TYPESCRIPT-AUTHORING.md).
 
 ## Extensions (accounts, administration, presentation)
-- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`. Project-level lifecycle hooks run trusted via plain `import()`, or sandboxed via `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
+- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, mounts, policies, operator registration, the shared trusted hook primitive and its machine-readable hook contracts. UI/auth/admin project hooks run trusted in-process; contract v1 rejects `sandbox: true`.
+- [Composing a site](docs/COMPOSING-A-SITE.md): what `urlcode init site --with ui,auth,admin` wires, which `--with` combinations are supported, the presentation override paths under `ui/`, and per-package lifecycle hook input, verdict, timing and failure semantics. Separates declarative configuration, project functions and the TypeScript a new extension needs.
 - [urlcode-auth](packages/auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-admin](packages/admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-ui](packages/ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt. Lives in this repository as a workspace package, not in a separate repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.0-alpha.3",
+  "version": "0.4.2",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -104,7 +104,8 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --conditions=development --test test/*.test.ts",
     "lint": "eslint .",
-    "check": "node scripts/check.ts && node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check && npm run release:check",
+    "check": "npm run check:code && npm run check:docs",
+    "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && npm run release:check",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
     "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
     "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run test:workspace-integration",
@@ -128,7 +129,7 @@
     "benchmark:sandbox-vs-trusted": "node benchmarks/sandbox-vs-trusted.ts",
     "benchmark:agent": "node benchmarks/agent/run.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts",
-    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
+    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
     "ci:plan": "node scripts/ci-plan.ts",
     "test:package:built": "node scripts/package-smoke.ts",
     "release:status": "node scripts/release.ts status",
@@ -136,10 +137,12 @@
     "release:publish": "node scripts/release.ts publish",
     "release:run": "node scripts/release-run.ts",
     "release:peers": "node scripts/release.ts peers",
-    "release:check": "node scripts/release.ts check",
+    "release:check": "node scripts/release.ts check && node scripts/release-prepare.ts --check",
     "ci:history": "node scripts/ci-history.ts",
     "ci:report": "node scripts/ci-report.ts",
-    "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts"
+    "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts",
+    "release:prepare": "node scripts/release-prepare.ts",
+    "release:template": "node scripts/release-template.ts"
   },
   "repository": {
     "type": "git",

package/packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "urlcode",
   "description": "Authoring and operating URLCode projects: the implemented YAML contract, capability limits, deployment and verification commands for the pinned runtime revision.",
-  "version": "0.4.0-alpha.3",
+  "version": "0.4.2",
   "author": {
     "name": "jimhoyd-com",
     "url": "https://github.com/jimhoyd-com"

package/packaging/claude-plugin/skills/urlcode-authoring/SKILL.md

@@ -30,6 +30,11 @@ Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
 capability, schema fragment, recipe or example relevant to the change. Use the
 read-only MCP equivalents when available. `llms.txt` is the index; read the
 matching task guide from `docs/` when a query needs more explanation.
+When the project has an operator host file, inspect `urlcode extensions
+--project <dir> --host-file <absolute-file> --json` (MCP: `get_extensions`)
+before writing extension configuration or project hooks. The report is the
+machine-readable source for config/policy schemas and hook names, purposes and
+input/output schemas.
 `docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
 questions. Archived plans are historical, not valid YAML guidance.
 
@@ -49,6 +54,11 @@ questions. Archived plans are historical, not valid YAML guidance.
 - Create every referenced module, page and asset **before** validating. All
   source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
   only `sandbox: true` modules are restricted to the relative snapshotted graph.
+- Customize installed extensions in this order: declarative configuration;
+  `urlcode-ui` copy, theme, template and CSS overrides; a hook declared by the
+  extension; a new extension only when the installed contract cannot express
+  the behavior. Extension hooks run trusted in-process and reject `sandbox:
+  true` in contract v1.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.

package/recipes/middleware/middleware/envelope.mjs

@@ -1,5 +1,7 @@
-// Wrap successful JSON function responses in a stable envelope. Native bodies are
-// opaque and pass through untouched; only readable JSON is rewritten.
+// Wrap successful JSON function responses in a stable envelope. Only a JSON body
+// this chain can actually read is rewritten; everything else passes through
+// untouched -- on a `sandbox: true` route that includes every native body, which
+// the guest cannot read at all.
 export default async function envelope(request, context, next) {
   const response = await next();
   if (!response.ok || !(response.headers.get('content-type') || '').startsWith('application/json')) return response;

package/skills/urlcode/SKILL.md

@@ -39,6 +39,10 @@ has registered the `urlcode` server, prefer its tools over reading documents:
 and `get_schema` (one capability or YAML fragment), `search_recipes`,
 `explain` (a route's effective behavior) and `get_manifest`. The server is
 read-only; `--allow-authoring` is an operator opt-in you never add yourself.
+When the MCP server was started with an operator host file, `get_extensions`
+returns installed extension configuration/policy schemas and declared project
+hook contracts. Otherwise use `urlcode extensions --project DIR --host-file
+ABSOLUTE_HOST --json` when the operator has supplied that host file.
 Without the server, run the CLI equivalents and read only the output:
 
 ```sh
@@ -65,7 +69,10 @@ need rather than reading them whole.
 
 1. If a native handler expresses the behavior (`redirect`, `respond`, `page`,
    `static`, `download`, `proxy`, `conditional`), write YAML only.
-2. Check supported extensions and their configuration before custom code. If a
+2. Check supported extensions and their configuration before custom code. For
+   an installed extension, prefer declarative config and UI copy/theme/template/
+   CSS overrides, then a hook listed in `get_extensions`. Extension hook
+   contract v1 runs trusted in-process and rejects `sandbox: true`. If a
    recipe from `recipes list` is close, `urlcode recipes add NAME --out DIR`
    and adapt the copy into the project's layout.
 3. Only then write a function or middleware: one exported handler, inputs from validated `args`,