@aotter/mantle 0.1.0-alpha.6 → 0.1.0-alpha.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.0-alpha.6",
-  "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling and adapter authors.",
+  "version": "0.1.0-alpha.8",
+  "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
   "repository": {
@@ -14,8 +14,8 @@
   "main": "./dist/spec.js",
   "types": "./dist/spec.d.ts",
   "bin": {
-    "mantle": "./dist/cli.js",
-    "mantle-harness": "./dist/harness-cli.js"
+    "mantle": "./dist/cli/main.js",
+    "mantle-harness": "./dist/cli/harness.js"
   },
   "publishConfig": {
     "access": "public",
@@ -27,6 +27,10 @@
       "types": "./dist/spec.d.ts",
       "import": "./dist/spec.js"
     },
+    "./provision": {
+      "types": "./dist/provision.d.ts",
+      "import": "./dist/provision.js"
+    },
     "./spec": {
       "types": "./dist/spec.d.ts",
       "import": "./dist/spec.js"
@@ -39,6 +43,30 @@
       "types": "./dist/runtime-testing.d.ts",
       "import": "./dist/runtime-testing.js"
     },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    },
+    "./admin": {
+      "types": "./dist/admin.d.ts",
+      "import": "./dist/admin.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./vercel": {
+      "types": "./dist/vercel.d.ts",
+      "import": "./dist/vercel.js"
+    },
+    "./vercel/libsql": {
+      "types": "./dist/vercel-libsql.d.ts",
+      "import": "./dist/vercel-libsql.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare.d.ts",
       "import": "./dist/cloudflare.js"
@@ -55,27 +83,69 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.6",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.6",
-    "@aotter/mantle-spec": "0.1.0-alpha.6",
-    "@aotter/mantle-runtime": "0.1.0-alpha.6"
+    "@aotter/mantle-runtime": "0.1.0-alpha.8",
+    "@aotter/mantle-spec": "0.1.0-alpha.8"
   },
   "peerDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.2",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.27",
+    "better-auth": "^1.7.1",
     "hono": "^4.12.0",
-    "zod": "^4.0.0"
+    "@libsql/client": "^0.17.4",
+    "zod": "^4.0.0",
+    "@aotter/mantle-admin": "0.1.0-alpha.8",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.8",
+    "@aotter/mantle-bun": "0.1.0-alpha.8",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.8",
+    "@aotter/mantle-vercel": "0.1.0-alpha.8",
+    "@aotter/mantle-web": "0.1.0-alpha.8"
+  },
+  "peerDependenciesMeta": {
+    "@aotter/mantle-admin": {
+      "optional": true
+    },
+    "@aotter/mantle-admin-ui": {
+      "optional": true
+    },
+    "@aotter/mantle-bun": {
+      "optional": true
+    },
+    "@aotter/mantle-cloudflare": {
+      "optional": true
+    },
+    "@aotter/mantle-vercel": {
+      "optional": true
+    },
+    "@aotter/mantle-web": {
+      "optional": true
+    },
+    "aws4fetch": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.2",
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.27",
+    "better-auth": "^1.7.1",
     "hono": "^4.12.34",
+    "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.2"
+    "zod": "^4.4.3",
+    "@aotter/mantle-admin": "0.1.0-alpha.8",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.8",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.8",
+    "@aotter/mantle-bun": "0.1.0-alpha.8",
+    "@aotter/mantle-vercel": "0.1.0-alpha.8",
+    "@aotter/mantle-web": "0.1.0-alpha.8"
   },
   "engines": {
     "node": ">=22"

package/skills/README.md

@@ -5,6 +5,7 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 | Skill | When to invoke |
 |---|---|
 | [`develop`](develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
+| [`media-gc`](media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
 | [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across starters and adapters. |
 | [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project context but does not depend on starter-owned skill semantics. |
 | [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK, starter snapshots, and plugin lockfiles. |
@@ -14,12 +15,43 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 The skills target Mantle's v0.1 grammar. The installed package version, not
 duplicated skill prose, selects the exact runtime and embedded docs.
 
+## Disclosure audit
+
+Every skill ships as one `SKILL.md` with no reference files, scripts, or
+assets, so nothing is deferred behind a second load. Progressive disclosure
+here is section routing inside one file: the agent reads the entry constraints,
+then only the section its selected path names. `scripts/check-skills.mjs`
+enforces the columns below.
+
+| Skill | Routes on | Entry-path constraints (read before acting) | Path-gated sections | Projection | Restricted because |
+|---|---|---|---|---|---|
+| `develop` | existing project; manifest, runtime, handler, adapter, or MCP work | four-atom model; adapter neutrality; no direct D1/KV/Postgres writes; no committed secrets | performance harness; local MCP client; locale rules | project, plugin | — |
+| `plugin` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project, plugin | — |
+| `theme` | brand or visual direction in a generated project | repo-owned theme and UI contracts | — | project, plugin | — |
+| `update` | drift check against SDK, starter, or plugin locks | never blindly overwrite user-owned code | — | project, plugin | — |
+| `install` | new site, or opening an existing generated one | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | create local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
+| `provision` | ship to Cloudflare and finish production auth | secrets never enter source or logs; explicit auth mode | hosted auth; self-managed auth | plugin | Platform-specific deploy that handles production secrets; opt-in only. |
+| `media-gc` | audit or remove stale uncommitted media objects | audit by default; confirm exact account, bucket, cutoff, and candidate digest; re-audit before applying; never prefix-delete; never print keys | apply | plugin | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
+
+Deliberately monolithic:
+
+- `develop` is the widest file, but its adapter, auth, and data-ownership rules
+  constrain every path through it. Splitting them behind routing would let an
+  agent reach a write path without them, which is the failure this audit
+  exists to prevent.
+- `media-gc` keeps its full audit-confirm-reapply sequence inline for the same
+  reason: each safeguard is a precondition of the delete that follows it.
+
 ## Skill authority
 
-The `mantle:*` namespace is owned by `@aotter/mantle`. Run `mantle skills` to
-project the installed package's `develop`, `plugin`, `theme`, and `update`
-skills to identical `.agent` and `.claude` paths; use `mantle skills --check`
-to fail closed on drift. The installed package and
+The `mantle:*` namespace is owned by `@aotter/mantle`. Every skill declares its
+own distribution scope in front matter: `metadata.projection: project` marks a
+skill `mantle skills` should place in a generated project, and a skill that
+withholds `project` must say why. `scripts/check-skills.mjs` holds that
+declaration and the audit table below to each other.
+
+Run `mantle skills` to project the installed package's skills into a project;
+use `mantle skills --check` to fail closed on drift. The installed package and
 `node_modules/@aotter/mantle/docs/` are the single version-matched authority.
 Starter launch files and plugin recipes are project context, not competing
 contracts.
@@ -37,9 +69,9 @@ duplicated into the npm package:
 ## Audience
 
 These are written for **AI agents acting on behalf of consumers of mantle**,
-not for agents maintaining the Mantle SDK itself. SDK maintainers use the
-repo-root `CLAUDE.md` from a source checkout; it is intentionally not shipped
-inside the npm package. Two audiences, two artifacts.
+not for contributors maintaining the Mantle SDK itself. SDK contributors use
+the repo-root `CONTRIBUTING.md`; it is intentionally not shipped inside the npm
+package. Two audiences, two artifacts.
 
 ## Discoverability
 

package/skills/develop/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/develop/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Develop
@@ -41,18 +42,19 @@ Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
 `TemplateRegistry`, and a matching `publicPathResolver` must agree on the
 exposed collections. Do not auto-publish every Schema. Generated projects list
 their mounted URL surface in their own README.
+Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
+not install public rendering by itself.
 
 ## Authoring CLI
 
-Use the project's scripts first; generated starters expose the shipping
-`mantle` authoring CLI from `@aotter/mantle-spec`:
+Use the project's scripts first; generated projects expose the shipping
+`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
+command list instead of trusting one copied into prose — the surface is
+version-matched and changes between releases:
 
 ```bash
 pnpm exec mantle --help
 pnpm validate
-pnpm introspect
-pnpm emit-openapi
-pnpm emit-types
 ```
 
 This CLI validates and derives artifacts from an existing materialized

package/skills/install/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/install/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Creates a new project; nothing to project into an existing one.
 ---
 
 # Mantle Install
@@ -33,35 +35,34 @@ hosted provider flow.
 | Blog, docs, posts, or editorial site | `publication` |
 | Catalog or order intent | `transaction` |
 | Booking or request intent | `reservation` |
-| Member or participation intent | `community` |
 
-2. Choose absolute paths for a temporary starters checkout and a target
-   directory outside both Mantle repositories. Derive a short project slug,
-   brand, one-sentence description, and locales from the user's prompt.
-   Require Node 22+ and pnpm 9+; check `node --version` and `pnpm --version`
-   before materializing.
+Community and membership types are not released; `create` refuses them. Build
+those on `blank` or the closest released type.
 
-3. Clone [`aotter/mantle-starters`](https://github.com/aotter/mantle-starters)
-   into a temporary directory and run its materializer. Use a starters ref
-   supplied by the user for branch testing. Otherwise use a tag matching the
-   requested Mantle version; use `develop` only for unreleased work. When the
-   user supplies a Mantle branch URL for a cold test, use the same branch name
-   in `mantle-starters` when that branch exists.
+2. Choose a target directory outside both Mantle repositories; its name
+   becomes the project slug. Derive a brand, one-sentence description, and
+   locales from the user's prompt. Require Node 22+ and pnpm 9+; check
+   `node --version` and `pnpm --version` before creating.
+
+3. Create the project with the Core CLI. It resolves the official immutable
+   starter tag for its own version, so no starters checkout is involved:
 
 ```bash
-git clone --depth 1 --branch <starters-ref> \
-  https://github.com/aotter/mantle-starters.git <temporary-starters-dir>
-pnpm --dir <temporary-starters-dir> materialize <type> \
-  --out <target-dir> \
-  --project-name <slug> \
+npx -y @aotter/mantle@alpha create <type> <target-dir> \
   --brand "<brand>" \
   --description "<one sentence>" \
   --locales <comma-separated-locales>
 ```
 
-The materializer writes the same precomposed `provision-bundles/<type>.json`
-used by Mantle landing. Do not manually copy `blank/`, merge overlays, or edit
-the generated bundle JSON.
+Pin an exact version (`@aotter/mantle@<version>`) when the user asked for one.
+`create` writes files and stops: it installs nothing, initializes no
+repository, configures no auth, and deploys nothing. It refuses to write into
+a path that already exists, and there is no force flag — choose a new
+directory instead.
+
+Do not clone the starters repository, copy `blank/`, merge overlays, or edit a
+provision bundle by hand. The CLI renders the same immutable bundle Mantle
+landing uses.
 
 4. For a typed launch, read `.mantle/handoff.md`, the selected overlay's
    `layout.md`, `seed-prompt.md`, and `seed.json`. Shape the first local page by
@@ -107,7 +108,9 @@ pnpm exec mantle skills --check
 
 Then read:
 
-3. Repo-local Mantle skills under `.agent/skills/` or `.claude/skills/`.
+3. Repo-local Mantle skills under `.agents/skills/` or `.claude/skills/`. A
+   project created before this layout may also carry `.agent/skills/`; read it
+   if present, but never write there and never delete it.
 4. Matching embedded docs under `node_modules/@aotter/mantle/docs/`.
 
 Use remote docs only when embedded docs are unavailable, and use a tag matching
@@ -125,14 +128,12 @@ pnpm typecheck
 ```
 
 Inspect the already composed manifest, page, and seed files before changing
-them. Use the project's scripts first; generated projects expose:
+them. Use the project's scripts first; ask the installed CLI for its command
+list rather than trusting one copied into prose:
 
 ```bash
 pnpm exec mantle --help
 pnpm validate
-pnpm introspect
-pnpm emit-openapi
-pnpm emit-types
 ```
 
 ## Production

package/skills/media-gc/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: media-gc
+description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/media-gc/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
+---
+
+# Mantle Media GC
+
+Use the connected Cloudflare API. Audit by default; delete only the exact
+objects approved by the user.
+
+## Preflight
+
+1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
+   binding, bucket name, and declared public media purpose names.
+2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
+   ask; never choose by name similarity.
+3. Use the Cloudflare OpenAPI search before execution to resolve the current
+   R2 List Objects and Delete Objects endpoints. If the connected account lacks
+   access, stop. Do not create, request, or store credentials.
+4. Stop when the project has no public R2 media binding or no declared purpose.
+
+## Audit
+
+For each declared purpose, list up to 1,000 objects per page under the exact
+`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+
+An object is a deletion candidate only when all conditions hold:
+
+- `last_modified` is more than 24 hours old;
+- `custom_metadata.committedAt` is absent or empty;
+- the key matches the exact Mantle layout
+  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+  where `<purpose>` is declared by this project and `<group>` contains only
+  letters, digits, `_`, or `-`.
+
+Skip committed, unknown-prefix, unprefixed, malformed, or ambiguous objects.
+Delete only an uncommitted variant, never its whole group.
+
+Report the account, bucket, purpose prefixes, UTC cutoff, candidate object and
+group counts, total bytes, skipped count, and a SHA-256 digest of the sorted
+`key + etag` candidate set. Do not print object keys, upload group IDs,
+filenames, public URLs, signed URLs, or secrets.
+
+## Apply
+
+1. Show the audit summary and get explicit confirmation for that exact account,
+   bucket, cutoff, count, byte total, and candidate-set digest.
+2. Re-run the complete audit with the same UTC cutoff. If the candidate count,
+   bytes, or digest changed, stop and present the new audit for confirmation.
+3. Call Delete Objects with JSON arrays of exact keys, at most 1,000 keys per
+   request. Never send the `prefix` query parameter: an empty prefix can empty
+   the bucket.
+4. Do not automatically retry failed keys. Report safe API error codes and
+   counts; a later invocation can audit and retry what remains.
+5. Re-list every inspected purpose prefix and report the remaining candidate
+   count and bytes.
+
+## Don't
+
+- Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
+- Don't use prefix deletion or empty-bucket operations.
+- Don't delete private-media buckets or objects outside declared purpose
+  prefixes.
+- Don't treat missing pagination pages, metadata, or permissions as an empty
+  result.
+
+## Diagnostics
+
+| Symptom | Action |
+|---|---|
+| Multiple matching accounts or buckets | Stop and ask the user to select the exact target. |
+| A page is truncated without a cursor | Stop; do not delete from a partial audit. |
+| A candidate has an unexpected key or metadata shape | Skip it and include it only in the aggregate skipped count. |
+| A delete request partially fails | Report safe error codes and leave the remaining objects for a later audit. |
+
+## When You're Done
+
+Return whether the run was audit-only or applied, the aggregate before/after
+counts and bytes, and any safely redacted failures.

package/skills/plugin/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/plugin/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Plugin

package/skills/provision/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/provision/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: plugin
+  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
 ---
 
 # Provision a Mantle Project

package/skills/theme/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/theme/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Theme

package/skills/update/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   source: "@aotter/mantle"
   sourcePath: skills/update/SKILL.md
   applies_to: mantle grammar v0.1
+  projection: project, plugin
 ---
 
 # Mantle Update

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;CAYhB,CAAC,CAAC;QACC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,YAAY;YACf,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;QAC7B,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,YAAY;YACf,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;QAC5B;YACE,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;YACjD,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,KAAK,CAAC,mBAAmB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/generate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAqBA,wBAAsB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6C7E"}