@mapled/cli 0.1.0 → 0.3.0

package/README.md

@@ -1,11 +1,14 @@
 # @mapled/cli
 
-The `mapled` command line for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Sign in to a project, link the repository to it, generate TypeScript types for the content your site reads, and check the whole integration in one go.
+The `mapled` command line for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Sign in to a project, link the repository to it, generate TypeScript types for the content your site reads, keep a pin of the schema and a manifest of where the code reads it, and check the whole integration in one go.
 
 ```bash
 npx @mapled/cli auth login
 npx @mapled/cli project link
 npx @mapled/cli types generate
+npx @mapled/cli scan --write
+npx @mapled/cli bindings push
+npx @mapled/cli md pull
 npx @mapled/cli doctor
 ```
 
@@ -45,18 +48,92 @@ Only public values live here — the project id, where the generated types go, t
 npx @mapled/cli types generate
 ```
 
-Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, and doc comments with the field types. Sensitive fields never reach the site and are left out.
+Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, a `MapledSchema` that ties them together, and doc comments with the field types. Sensitive fields never reach the site and are left out.
 
 ```ts
-import type { Article, MapledCollections } from "./mapled-types";
+import type { MapledSchema } from "./mapled-types";
 import { createClient } from "@mapled/next";
 
-const mapled = createClient({ key: process.env.MAPLED_KEY! });
-const { records } = await mapled.getRecords<Article>("articles");
-const home = await mapled.getSingle<MapledCollections["homepage"]>("homepage");
+const mapled = createClient<MapledSchema>({ key: process.env.MAPLED_KEY! });
+const { records } = await mapled.getRecords("articles"); // records[0].data is an Article
+const home = await mapled.getSingle("homepage");          // Homepage | null
 ```
 
-The file names the schema it came from; `mapled doctor` tells you when it is out of date. Run `types generate` again after the schema changes.
+The file names the schema it came from; `mapled doctor` tells you when it is out of date. Run `types generate` again after the schema changes — it refreshes `mapled/schema.json` too when you keep one.
+
+## Pin the schema and see what changed
+
+```bash
+npx @mapled/cli schema pull
+npx @mapled/cli schema diff
+```
+
+`schema pull` writes `mapled/schema.json` — the schema this site is built against, without ids or timestamps, so it diffs cleanly in git. Commit it. When editors or agents change the structure in Mapled, `schema diff` compares the pin with the live schema and judges every change **for a site that reads the content**:
+
+```text
+Schema changes since mapled/schema.json (3f9a1c2b4d5e → 8c1d2e3f4a5b):
+
+Articles (articles)
+  + subtitle   added — short text, optional                     safe
+  - legacy-id  removed — number                                 breaking
+  ~ author     short text → relation to Authors                 breaking
+  ~ title      required → optional (may be empty now)           breaking
+  ~ tags       option “Legacy” removed                          breaking
++ Authors (authors)  new collection — 3 fields                  safe
+
+4 breaking changes, 2 safe changes, judged for a site that reads the content. Update the site where needed, then run `mapled types generate` (it refreshes mapled/schema.json as well).
+```
+
+Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+
+## Scan the code into a manifest
+
+```bash
+npx @mapled/cli scan
+npx @mapled/cli scan --write
+```
+
+The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix) and one binding per place a collection or field is used.
+
+```text
+Scanned 42 files with TypeScript — 3 pages, 14 bindings.
+
+/              app/page.tsx
+  homepage     headline, cover, alt
+  articles     list • title, date, slug
+/blog/[slug]   app/blog/[slug]/page.tsx
+  articles     by slug • title, body
+
+No mapled/manifest.json yet — run `mapled scan --write` to create it, then `mapled bindings push`.
+```
+
+It follows `getRecords` / `getRecord` / `getRecordBySlug` / `getSingle` calls through variables, destructuring, `.map()` callbacks and into the components a record is passed to as a prop, and through helpers in `lib/` that return a read. The parser is your repository's own TypeScript; without it the scanner still finds the collections, but not the fields. Source code never leaves your machine — only the manifest does, when you push it.
+
+`--write` creates or updates `mapled/manifest.json`. Bindings the scan can't see (written by your AI agent, or by hand) are kept and listed; `--prune` drops them. Commit the file.
+
+## Validate and push the manifest
+
+```bash
+npx @mapled/cli manifest validate
+npx @mapled/cli bindings push
+npx @mapled/cli bindings pull
+```
+
+`manifest validate` checks `mapled/manifest.json` the way Mapled will: the shape and limits, duplicate keys, and — against the schema pin or the live schema — collections and fields that don't exist and targets that don't fit the field type, plus files the repository doesn't have. Problems exit 1; warnings only tell you what Mapled would grade down.
+
+`bindings push` sends the manifest to Mapled (the same call your AI agent's `push_site_manifest` makes). Mapled grades every binding — healthy, type mismatch, outdated, missing on site — and the result shows up in **Structure → Bindings**. `--dry-run` validates and stops. Pushing bindings changes structure, so it needs the builder plan.
+
+`bindings pull` writes the pushed manifest into `mapled/manifest.json` — say, after your agent pushed one from a chat and you want the repository's copy. It refuses to overwrite a local file that differs unless you pass `--force`.
+
+## Leave a guide for the next agent
+
+```bash
+npx @mapled/cli md pull
+```
+
+Writes `MAPLED.md` at the repository root — the guide Mapled renders from the project for whoever works on the site next, person or AI agent: the project and how the site reads it, the content model with every field's type, rules and help text, where each page renders which field (from the pushed manifest), the last setup run with its verification, the working rules, and the commands that verify the integration. It never contains a secret.
+
+The first line is a stamp with the schema hash and the manifest version. Everything below the `<!-- mapled:notes -->` line is yours — conventions, what stays hardcoded on purpose, things to avoid — and survives every `md pull`. A `MAPLED.md` Mapled didn't write is left alone unless you pass `--force`, which moves its content below the notes line. `mapled doctor` tells you when the file no longer matches the project; your AI agent gets the same document from the `get_mapled_md` tool.
 
 ## Check the integration
 
@@ -70,21 +147,24 @@ Mapled doctor — Dolphin Landing
 ✓ Project link         mapled.json → Dolphin Landing
 ✓ Signed in            Mapled CLI • Dolphin Landing
 ✓ Generated types      mapled-types.ts matches the schema (3f9a1c2b4d5e)
+✓ Schema pin           mapled/schema.json matches the schema (3f9a1c2b4d5e)
+✓ Site manifest        mapled/manifest.json is pushed as manifest v3 (14 bindings on 3 pages)
+✓ MAPLED.md            MAPLED.md matches the schema (3f9a1c2b4d5e) and manifest v3
 ✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
 ✓ Secrets in git       No env files or Mapled secrets are tracked.
-✓ @mapled/next         0.3.0 (current)
-✓ mapled CLI           0.1.0 (current)
+✓ @mapled/next         0.6.0 (current)
+✓ mapled CLI           0.2.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
 ✓ Site reads content   Last read 3m ago
 ✓ Publish webhook      Delivered 2h ago to dolphin-landing.example
 ✓ Preview on the site  Responds at https://dolphin-landing.example/api/mapled/preview
-✓ Bindings             12 healthy • synced 2d ago from Claude Code
+✓ Bindings             14 healthy • synced 2d ago from Mapled CLI
 
 1 warning.
 ```
 
-The repository side: the link, the sign-in, the generated types, `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
+The repository side: the link, the sign-in, the generated types, the schema pin, the site manifest (and whether it matches what was pushed), `MAPLED.md` (and whether it is what Mapled would render now), `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
 
 Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
 
@@ -92,4 +172,17 @@ Exit code 1 when something is marked ✗; `--json` prints the checks for scripts
 
 - `--api <origin>` — a Mapled API other than `https://api.mapled.io` (or set `MAPLED_API_URL`); `project link` remembers it in `mapled.json`
 - `--no-browser` — print the sign-in link instead of opening a browser
+- `--json` — machine-readable output (`doctor`, `schema diff`, `scan`, `manifest validate`)
 - `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)
+
+## Files in the repository
+
+| File | Written by | Purpose |
+|---|---|---|
+| `mapled.json` | `project link` | The project id, the types path, the framework — public values only |
+| `mapled-types.ts` | `types generate` | TypeScript types of the published content, with `MapledSchema` |
+| `mapled/schema.json` | `schema pull`, `types generate` | The schema this site is built against — `schema diff` starts from it |
+| `mapled/manifest.json` | `scan --write`, `bindings pull`, your agent | Pages and bindings — where the code reads each collection and field |
+| `MAPLED.md` | `md pull`, your agent | The guide for the next agent — project, content model, bindings, working rules; your notes below the marker |
+
+Commit all five. Credentials never live in the repository.

package/dist/api.d.ts

@@ -6,6 +6,8 @@ export declare class ApiError extends Error {
     code: string | null;
     constructor(status: number, code: string | null, message: string);
 }
+export type Method = "GET" | "POST" | "PATCH" | "DELETE";
+export declare function apiRequest<T>(api: string, method: Method, path: string, token: string, body: unknown, f: Fetch): Promise<T>;
 export declare function apiGet<T>(api: string, path: string, token: string, f: Fetch): Promise<T>;
 /** A signed-in connection with its store: reads refresh the access
     token when it is about to expire or when the API says it did, and
@@ -17,5 +19,7 @@ export declare class Session {
     private readonly f;
     constructor(store: CredentialsFile, file: string, conn: Connection, f: Fetch);
     get<T>(path: string): Promise<T>;
+    send<T>(method: Method, path: string, body: unknown): Promise<T>;
+    private request;
     private refresh;
 }

package/dist/api.js

@@ -12,10 +12,18 @@ export class ApiError extends Error {
         this.code = code;
     }
 }
-export async function apiGet(api, path, token, f) {
+export async function apiRequest(api, method, path, token, body, f) {
     let res;
     try {
-        res = await f(`${api}${path}`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
+        res = await f(`${api}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
     }
     catch {
         throw new CliError(`Couldn't reach ${api}. Check your connection and try again.`);
@@ -26,6 +34,9 @@ export async function apiGet(api, path, token, f) {
     }
     return data;
 }
+export function apiGet(api, path, token, f) {
+    return apiRequest(api, "GET", path, token, undefined, f);
+}
 /** A signed-in connection with its store: reads refresh the access
     token when it is about to expire or when the API says it did, and
     the rotated pair is written back before the call returns. */
@@ -40,17 +51,23 @@ export class Session {
         this.conn = conn;
         this.f = f;
     }
-    async get(path) {
+    get(path) {
+        return this.request("GET", path);
+    }
+    send(method, path, body) {
+        return this.request(method, path, body);
+    }
+    async request(method, path, body) {
         if (new Date(this.conn.expiresAt).getTime() - Date.now() < 60_000)
             await this.refresh();
         try {
-            return await apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+            return await apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
         }
         catch (err) {
             if (err instanceof ApiError && err.status === 401) {
                 if (err.code === "TOKEN_EXPIRED") {
                     await this.refresh();
-                    return apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+                    return apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
                 }
                 throw new CliError(`The connection to ${this.conn.projectName} was revoked. Run \`mapled auth login\` to sign in again.`);
             }

package/dist/commands.d.ts

@@ -2,9 +2,9 @@ import { type ParsedArgs } from "./args.js";
 import { type FoundConfig } from "./config.js";
 import { type Connection } from "./credentials.js";
 import { type Fetch } from "./oauth.js";
-/** The four wave-1 commands (§31) plus sign-out. Everything that talks
-    to the world comes in through `Ctx`, so the commands run in tests
-    against a fake API and a temp directory. */
+/** The commands of waves 1 and 2 (§31) and MAPLED.md (§21.3). Everything that talks to the
+    world comes in through `Ctx`, so the commands run in tests against a
+    fake API and a temp directory. */
 export type Ctx = {
     cwd: string;
     env: NodeJS.ProcessEnv;
@@ -23,5 +23,12 @@ export declare function login(ctx: Ctx, flags: Flags): Promise<Connection>;
 export declare function logout(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function link(ctx: Ctx, flags: Flags): Promise<FoundConfig>;
 export declare function generate(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function schemaPull(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function schemaDiff(ctx: Ctx, flags: Flags): Promise<number>;
+export declare function manifestValidate(ctx: Ctx, flags: Flags): Promise<number>;
+export declare function bindingsPush(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function bindingsPull(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function mdPull(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function scan(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function doctor(ctx: Ctx, flags: Flags): Promise<number>;
 export {};