@mapled/cli 0.2.0 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@ 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
 ```
 
@@ -124,6 +125,16 @@ npx @mapled/cli bindings pull
 
 `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
 
 ```bash
@@ -138,6 +149,7 @@ Mapled doctor — 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.6.0 (current)
@@ -152,7 +164,7 @@ Mapled doctor — Dolphin Landing
 1 warning.
 ```
 
-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_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.
 
@@ -171,5 +183,6 @@ Exit code 1 when something is marked ✗; `--json` prints the checks for scripts
 | `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 four. Credentials never live in the repository.
+Commit all five. Credentials never live in the repository.

package/dist/commands.d.ts

@@ -2,7 +2,7 @@ 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 commands of waves 1 and 2 (§31). Everything that talks to the
+/** 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 = {
@@ -28,6 +28,7 @@ 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 {};

package/dist/commands.js

@@ -10,6 +10,7 @@ import { checkManifest, compareManifests, fileExistsIn, MANIFEST_FILE, manifestS
 import { authorize, clientKnown, exchangeCode, registerClient, revokeToken } from "./oauth.js";
 import { formatChecks, GLYPH, paint, summarize, useColor } from "./output.js";
 import { diffSchema, formatChanges, pinSchema, readPin, SCHEMA_FILE, summarizeChanges, writePin } from "./pin.js";
+import { checkMapledMd, MD_FILE, mergeMd } from "./md.js";
 import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { generateTypes } from "./types.js";
 /** The OAuth client id for this API — registered once per machine, and
@@ -367,6 +368,27 @@ export async function bindingsPull(ctx, flags) {
     await writeManifestFile(found.dir, stored.manifest);
     ctx.out(`Wrote ${MANIFEST_FILE} from manifest v${stored.version} (pushed ${dr.ago(stored.createdAt)} by ${stored.clientName}) — ${manifestSummary(stored.manifest)}.`);
 }
+/* ---- MAPLED.md ---- */
+export async function mdPull(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const fresh = await session.get("/v1/agent/mapled-md");
+    const file = path.join(found.dir, MD_FILE);
+    const existing = await readFile(file, "utf8").catch(() => null);
+    const merged = mergeMd(fresh.markdown, existing, { force: Boolean(flags.force) });
+    if (merged.kind === "unchanged") {
+        ctx.out(`${MD_FILE} is up to date (schema ${fresh.schemaHash}).`);
+        return;
+    }
+    await writeFile(file, merged.text);
+    const c = fresh.counts;
+    const summary = `${plural(c.collections, "collection")}, ${plural(c.singles, "single")}, ${plural(c.bindings, "binding")} (schema ${fresh.schemaHash})`;
+    if (merged.kind === "created")
+        ctx.out(`Wrote ${MD_FILE} — ${summary}. Commit it: the next agent reads it first.`);
+    else if (merged.kind === "replaced")
+        ctx.out(`Replaced ${MD_FILE} — ${summary}; the previous content was kept below the notes line.`);
+    else
+        ctx.out(`Updated ${MD_FILE} — ${summary}; the notes below the notes line were kept.`);
+}
 /* ---- wave 2: the scanner ---- */
 function describeScan(result, schema) {
     const singles = new Set(schema.collections.filter((c) => c.kind === "single").map((c) => c.key));
@@ -478,6 +500,7 @@ export async function doctor(ctx, flags) {
     const conn = found ? findConnection(store, api, found.config.project) : undefined;
     let status = null;
     let schema = null;
+    let guide = null;
     let authError = null;
     if (conn) {
         const session = new Session(store, ctx.credentialsFile, conn, ctx.fetch);
@@ -488,6 +511,15 @@ export async function doctor(ctx, flags) {
         catch (err) {
             authError = err instanceof Error ? err.message : String(err);
         }
+        if (status) {
+            // the guide is one more read; an API without it must not fail the sign-in line
+            try {
+                guide = await session.get("/v1/agent/mapled-md");
+            }
+            catch {
+                guide = "unavailable";
+            }
+        }
     }
     const checks = [];
     checks.push(dr.checkLink(found ? { path: path.relative(ctx.cwd, found.path) || CONFIG_FILE } : null, status?.project.name ?? conn?.projectName ?? null));
@@ -510,6 +542,7 @@ export async function doctor(ctx, flags) {
         }
     }
     checks.push(dr.checkManifestFile(localManifest ? { manifest: localManifest.manifest, problems: localManifest.problems } : null, remoteManifest));
+    checks.push(checkMapledMd(await readFile(path.join(dir, MD_FILE), "utf8").catch(() => null), guide));
     checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env));
     checks.push(dr.checkSecrets(await dr.gitFacts(dir)));
     checks.push(dr.checkSdk(await dr.installedVersion(dir, "@mapled/next"), status?.sdk["@mapled/next"]));

package/dist/index.js

@@ -3,12 +3,13 @@ import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "./args.js";
 import { openBrowser } from "./browser.js";
-import { bindingsPull, bindingsPush, doctor, generate, link, login, logout, manifestValidate, scan, schemaDiff, schemaPull, } from "./commands.js";
+import { bindingsPull, bindingsPush, doctor, generate, link, login, logout, manifestValidate, mdPull, scan, schemaDiff, schemaPull, } from "./commands.js";
 import { credentialsPath } from "./credentials.js";
 import { CliError } from "./errors.js";
 /** `mapled` — sign in, link a repository to its project, generate types
-    for the content, keep the schema pin and the site manifest in step
-    with the code, check the integration (§31, waves 1 and 2). */
+    for the content, keep the schema pin, the site manifest and MAPLED.md
+    in step with the code, check the integration (§31, waves 1 and 2;
+    §21.3). */
 const HELP = `mapled — the Mapled CLI
 
 Usage
@@ -22,6 +23,7 @@ Usage
   mapled manifest validate [--json]                   Check mapled/manifest.json before pushing it
   mapled bindings push [--dry-run]                    Push mapled/manifest.json so Mapled grades every binding
   mapled bindings pull [--force]                      Write the pushed manifest into mapled/manifest.json
+  mapled md pull [--force]                            Write MAPLED.md, the guide for the next agent, from the project
   mapled doctor [--json]                              Check the integration end to end
 
 Options
@@ -103,6 +105,9 @@ async function main(argv) {
         case "bindings pull":
             await bindingsPull(ctx, flags);
             return 0;
+        case "md pull":
+            await mdPull(ctx, flags);
+            return 0;
         case "doctor":
             return doctor(ctx, flags);
         case "auth":
@@ -111,6 +116,7 @@ async function main(argv) {
         case "schema":
         case "manifest":
         case "bindings":
+        case "md":
             console.log(HELP);
             return 2;
         default:

package/dist/md.d.ts

@@ -0,0 +1,59 @@
+import type { Check } from "./doctor.js";
+/** MAPLED.md (§21.3): Mapled renders the guide for the next agent,
+    the repository keeps it. `mapled md pull` writes what
+    GET /v1/agent/mapled-md answers and keeps everything below the notes
+    marker — that part is the repository's own; `doctor` compares the
+    rendered part of the local file with a fresh render. The first line
+    is a stamp (`<!-- mapled: project=… schema=… manifest=… generated=… -->`)
+    and the only line allowed to differ between a fresh file and an
+    up-to-date one. */
+export declare const MD_FILE = "MAPLED.md";
+export declare const NOTES_MARKER = "<!-- mapled:notes -->";
+/** GET /v1/agent/mapled-md */
+export type RenderedMd = {
+    file: string;
+    notesMarker: string;
+    markdown: string;
+    schemaHash: string;
+    manifestVersion: number | null;
+    counts: {
+        collections: number;
+        singles: number;
+        forms: number;
+        bindings: number;
+        pages: number;
+    };
+    generatedAt: string;
+};
+export type MdStamp = {
+    project: string | null;
+    schema: string | null;
+    manifest: string | null;
+};
+export type MdParts = {
+    stamp: MdStamp;
+    /** the stamp line as written */
+    stampLine: string;
+    /** everything between the stamp and the notes marker */
+    body: string;
+    /** everything after the marker line; null when the file has no marker */
+    notes: string | null;
+};
+/** Splits a MAPLED.md written by Mapled; null for any other file. */
+export declare function splitMd(text: string): MdParts | null;
+export type MergedMd = {
+    kind: "unchanged";
+} | {
+    kind: "created" | "updated" | "replaced";
+    text: string;
+};
+/** The file to write: the fresh render, with the repository's notes kept.
+    A file Mapled did not write is left alone unless forced — then its
+    whole content moves below the notes line, so nothing is lost. */
+export declare function mergeMd(fresh: string, existing: string | null, opts?: {
+    force?: boolean;
+}): MergedMd;
+/** `doctor`'s line: is the repository's guide what Mapled would render now?
+    `fresh` is null without a sign-in and "unavailable" when Mapled
+    answered the other calls but not this one (an API without the route). */
+export declare function checkMapledMd(local: string | null, fresh: RenderedMd | null | "unavailable"): Check;

package/dist/md.js

@@ -0,0 +1,110 @@
+import { CliError } from "./errors.js";
+/** MAPLED.md (§21.3): Mapled renders the guide for the next agent,
+    the repository keeps it. `mapled md pull` writes what
+    GET /v1/agent/mapled-md answers and keeps everything below the notes
+    marker — that part is the repository's own; `doctor` compares the
+    rendered part of the local file with a fresh render. The first line
+    is a stamp (`<!-- mapled: project=… schema=… manifest=… generated=… -->`)
+    and the only line allowed to differ between a fresh file and an
+    up-to-date one. */
+export const MD_FILE = "MAPLED.md";
+export const NOTES_MARKER = "<!-- mapled:notes -->";
+/** Splits a MAPLED.md written by Mapled; null for any other file. */
+export function splitMd(text) {
+    const lines = text.split("\n");
+    const first = lines[0] ?? "";
+    const m = /^<!-- mapled: (.*) -->\s*$/.exec(first);
+    if (!m)
+        return null;
+    const stamp = { project: null, schema: null, manifest: null };
+    for (const pair of m[1].split(/\s+/)) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = pair.slice(0, eq);
+        const value = pair.slice(eq + 1);
+        if (key === "project" || key === "schema" || key === "manifest")
+            stamp[key] = value;
+    }
+    const marker = lines.indexOf(NOTES_MARKER, 1);
+    const body = lines.slice(1, marker === -1 ? lines.length : marker).join("\n");
+    const notes = marker === -1 ? null : lines.slice(marker + 1).join("\n");
+    return { stamp, stampLine: first, body, notes };
+}
+/** The same render: the body and what the stamp says about it, never
+    the time it was rendered at. */
+function sameRender(a, b) {
+    return a.body === b.body && a.stamp.schema === b.stamp.schema && a.stamp.manifest === b.stamp.manifest;
+}
+/** The file to write: the fresh render, with the repository's notes kept.
+    A file Mapled did not write is left alone unless forced — then its
+    whole content moves below the notes line, so nothing is lost. */
+export function mergeMd(fresh, existing, opts = {}) {
+    const next = splitMd(fresh);
+    if (!next || next.notes === null)
+        throw new CliError("Mapled answered a guide without its stamp or notes marker — update @mapled/cli and try again.");
+    if (existing === null)
+        return { kind: "created", text: fresh };
+    const current = splitMd(existing);
+    if (!current) {
+        if (!opts.force) {
+            throw new CliError(`${MD_FILE} here wasn't written by Mapled. Pass --force to replace it — the current content moves below the notes line, nothing is lost.`);
+        }
+        const kept = existing.replace(/\s+$/, "");
+        return { kind: "replaced", text: `${next.stampLine}\n${next.body}\n${NOTES_MARKER}\n## Notes\n\n${kept}\n` };
+    }
+    if (sameRender(current, next) && current.notes !== null)
+        return { kind: "unchanged" };
+    const notes = current.notes === null || current.notes.trim() === "" ? next.notes : current.notes;
+    return { kind: "updated", text: `${next.stampLine}\n${next.body}\n${NOTES_MARKER}\n${notes}` };
+}
+/** `doctor`'s line: is the repository's guide what Mapled would render now?
+    `fresh` is null without a sign-in and "unavailable" when Mapled
+    answered the other calls but not this one (an API without the route). */
+export function checkMapledMd(local, fresh) {
+    const label = "MAPLED.md";
+    if (local === null) {
+        return { key: "mapled_md", label, status: "skipped", detail: `No ${MD_FILE} — run \`mapled md pull\` so the next agent starts from the current integration.` };
+    }
+    if (fresh === null)
+        return { key: "mapled_md", label, status: "skipped", detail: "Sign in to compare with Mapled." };
+    if (fresh === "unavailable") {
+        return { key: "mapled_md", label, status: "skipped", detail: "Mapled didn't answer with a guide — update @mapled/cli, or try again later." };
+    }
+    const current = splitMd(local);
+    if (!current) {
+        return {
+            key: "mapled_md",
+            label,
+            status: "warning",
+            detail: `${MD_FILE} wasn't written by Mapled — run \`mapled md pull --force\` to replace it (the current content moves below the notes line).`,
+        };
+    }
+    const next = splitMd(fresh.markdown);
+    const manifest = fresh.manifestVersion === null ? "none" : `v${fresh.manifestVersion}`;
+    if (next && sameRender(current, next) && current.notes !== null) {
+        return {
+            key: "mapled_md",
+            label,
+            status: "passed",
+            detail: `${MD_FILE} matches the schema (${fresh.schemaHash})${fresh.manifestVersion === null ? "" : ` and manifest ${manifest}`}`,
+        };
+    }
+    if (current.stamp.schema && current.stamp.schema !== fresh.schemaHash) {
+        return {
+            key: "mapled_md",
+            label,
+            status: "warning",
+            detail: `${MD_FILE} describes schema ${current.stamp.schema}; the schema is ${fresh.schemaHash} — run \`mapled md pull\`.`,
+        };
+    }
+    if (current.stamp.manifest && current.stamp.manifest !== manifest) {
+        return {
+            key: "mapled_md",
+            label,
+            status: "warning",
+            detail: `${MD_FILE} describes manifest ${current.stamp.manifest}; ${manifest === "none" ? "none is pushed now" : `${manifest} is pushed`} — run \`mapled md pull\`.`,
+        };
+    }
+    return { key: "mapled_md", label, status: "warning", detail: `${MD_FILE} is out of date — run \`mapled md pull\`.` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",