@mapled/cli 0.2.0 → 0.4.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
 ```
 
@@ -120,10 +121,20 @@ 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 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**. The push also records the integration hash: one marker over the schema and these bindings, what the site is synced with from now on. `--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, the manifest version and the integration hash. 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,8 @@ 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)
+✓ Integration          In sync with Mapled (7c1d9e0f2a3b)
+✓ 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 +165,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), the integration hash — one line saying whether the pin and the manifest here describe the same integration Mapled holds, and if not, what moved (the schema, the bindings, or edits made in Mapled) and which command catches up — `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 +184,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
@@ -331,7 +332,8 @@ export async function bindingsPush(ctx, flags) {
         graded.push(`${s.missing_on_site} missing on site`);
     if (s.disabled)
         graded.push(`${s.disabled} disabled`);
-    ctx.out(`Pushed ${MANIFEST_FILE} to ${session.conn.projectName} — manifest v${result.manifest.version}, ${plural(body.bindings.length, "binding")}: ${graded.join(", ")}.`);
+    const recorded = result.manifest.integrationHash ? ` (integration ${result.manifest.integrationHash})` : "";
+    ctx.out(`Pushed ${MANIFEST_FILE} to ${session.conn.projectName} — manifest v${result.manifest.version}${recorded}, ${plural(body.bindings.length, "binding")}: ${graded.join(", ")}.`);
     for (const w of result.warnings)
         ctx.out(`${paint("warning", GLYPH.warning, color)} ${w}`);
     if ((s.type_mismatch ?? 0) + (s.outdated ?? 0) + (s.missing_on_site ?? 0) > 0 || result.warnings.length > 0) {
@@ -367,6 +369,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 +501,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 +512,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 +543,8 @@ export async function doctor(ctx, flags) {
         }
     }
     checks.push(dr.checkManifestFile(localManifest ? { manifest: localManifest.manifest, problems: localManifest.problems } : null, remoteManifest));
+    checks.push(dr.checkIntegration({ pin: pin?.pin ?? null, manifest: localManifest?.manifest ?? null }, conn && status ? { integration: status.integration, manifest: remoteManifest } : null));
+    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/doctor.d.ts

@@ -49,9 +49,25 @@ export type IntegrationStatus = {
         } | null;
         summary: Record<string, number>;
     };
+    /** the integration hash (§21.4); missing from an API older than the hash */
+    integration?: IntegrationState;
     previewPath: string;
     sdk: Record<string, string>;
 };
+/** Whether the site's integration still matches what Mapled holds:
+    `hash` is the live schema plus the bindings as Mapled holds them now,
+    `synced` what the last manifest push recorded. */
+export type IntegrationState = {
+    schemaHash: string;
+    hash: string | null;
+    synced: {
+        hash: string;
+        schemaHash: string;
+    } | null;
+    inSync: boolean | null;
+    schemaChanged: boolean;
+    bindingsChanged: boolean;
+};
 export declare function ago(iso: string): string;
 export declare const ENV_FILES: string[];
 /** Variable NAMES defined in the repository's env files. Values stay in
@@ -111,10 +127,26 @@ export type StoredManifest = {
     version: number;
     clientName: string;
     createdAt: string;
+    /** what the push recorded; null when it predates the integration hash, missing from an older API */
+    schemaHash?: string | null;
+    integrationHash?: string | null;
     manifest: Manifest;
 };
 export declare function checkManifestFile(local: {
     manifest: Manifest;
     problems: Problem[];
 } | null, remote: StoredManifest | null | "unknown"): Check;
+/** The one line that says whether the repository and Mapled describe the
+    same integration (§21.4): the hash over mapled/schema.json and
+    mapled/manifest.json here against the hash Mapled computes over the
+    live schema and the bindings it holds. The two lines above it say
+    what differs; this one says whether anything does, and whether the
+    last push recorded it. */
+export declare function checkIntegration(local: {
+    pin: SchemaPin | null;
+    manifest: Manifest | null;
+}, remote: {
+    integration: IntegrationState | undefined;
+    manifest: StoredManifest | null | "unknown";
+} | null): Check;
 export declare const REMOTE_CHECKS: [string, string][];

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { integrationHash } from "./integrationHash.js";
 import { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
 import { SCHEMA_FILE } from "./pin.js";
 import { splitGenerated } from "./types.js";
@@ -462,6 +463,73 @@ export function checkManifestFile(local, remote) {
         detail: `${MANIFEST_FILE} differs from the pushed manifest (v${remote.version}): ${parts.join(", ")} — run \`mapled bindings push\`.`,
     };
 }
+/** The one line that says whether the repository and Mapled describe the
+    same integration (§21.4): the hash over mapled/schema.json and
+    mapled/manifest.json here against the hash Mapled computes over the
+    live schema and the bindings it holds. The two lines above it say
+    what differs; this one says whether anything does, and whether the
+    last push recorded it. */
+export function checkIntegration(local, remote) {
+    const key = "integration";
+    const label = "Integration";
+    if (!local.pin || !local.manifest) {
+        const missing = [
+            local.pin ? null : `${SCHEMA_FILE} (\`mapled schema pull\`)`,
+            local.manifest ? null : `${MANIFEST_FILE} (\`mapled scan --write\`)`,
+        ].filter((s) => s !== null);
+        return { key, label, status: "skipped", detail: `Needs ${missing.join(" and ")} to compute the integration hash.` };
+    }
+    if (!remote)
+        return { key, label, status: "skipped", detail: "Sign in to compare with Mapled." };
+    const theirs = remote.integration;
+    if (!theirs) {
+        return { key, label, status: "skipped", detail: "Mapled didn't answer with an integration hash — update @mapled/cli, or try again later." };
+    }
+    const mine = integrationHash(local.pin.hash, local.manifest);
+    if (theirs.hash === null) {
+        return { key, label, status: "skipped", detail: `Nothing is pushed yet — \`mapled bindings push\` records the first integration hash (${mine} here).` };
+    }
+    if (mine === theirs.hash) {
+        if (theirs.synced === null) {
+            return { key, label, status: "warning", detail: `Matches Mapled (${mine}), but the last push predates the integration hash — run \`mapled bindings push\` to record it.` };
+        }
+        if (theirs.inSync === false) {
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `Matches Mapled (${mine}), but the last push was against schema ${theirs.synced.schemaHash} — run \`mapled bindings push\` to record the sync.`,
+            };
+        }
+        return { key, label, status: "passed", detail: `In sync with Mapled (${mine})` };
+    }
+    const reasons = [];
+    const fixes = [];
+    if (local.pin.hash !== theirs.schemaHash) {
+        reasons.push(`schema ${local.pin.hash} → ${theirs.schemaHash}`);
+        fixes.push("`mapled schema diff`");
+    }
+    if (remote.manifest && remote.manifest !== "unknown") {
+        const diff = compareManifests(local.manifest, remote.manifest.manifest);
+        if (!diff.same) {
+            const parts = [];
+            if (diff.onlyLocal.length > 0)
+                parts.push(`${diff.onlyLocal.length} not pushed`);
+            if (diff.changed.length > 0)
+                parts.push(`${diff.changed.length} changed`);
+            if (diff.onlyRemote.length > 0)
+                parts.push(`${diff.onlyRemote.length} only in Mapled`);
+            reasons.push(`the manifest differs (${parts.join(", ")}${theirs.bindingsChanged ? " — edited in Mapled" : ""})`);
+            // Mapled's edits win when the repository adds nothing of its own; `pull` refuses a differing file without --force
+            fixes.push(theirs.bindingsChanged && diff.onlyLocal.length === 0 ? "`mapled bindings pull --force`" : "`mapled bindings push`");
+        }
+    }
+    if (reasons.length === 0) {
+        reasons.push(`the manifest's pages or notes differ (${mine} here, ${theirs.hash} in Mapled)`);
+        fixes.push("`mapled bindings push`");
+    }
+    return { key, label, status: "warning", detail: `Out of sync — ${reasons.join(", ")}. Run ${fixes.join(" and ")}.` };
+}
 export const REMOTE_CHECKS = [
     ["reads", "Site reads content"],
     ["webhook", "Publish webhook"],

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/integrationHash.d.ts

@@ -0,0 +1,35 @@
+/** The integration hash (§21.4): one marker over everything the site's
+    integration was written against — the schema (its hash, the twelve hex
+    characters in mapled-types.ts and mapled/schema.json) and the site
+    manifest (bindings, pages, framework, notes). Mapled records it on
+    every manifest push and computes it again on read; the repository
+    computes the same value from mapled/schema.json and
+    mapled/manifest.json, and `mapled doctor` compares the two in one
+    line. This is a literal port of apps/api/src/lib/integrationHash.ts —
+    the API's tests run both over one manifest and expect one hash.
+    Change the two together.
+
+    Bindings and pages are sorted, so the order in a file never matters;
+    optional fields take their defaults (`required: true` written or
+    omitted is the same integration, an empty component is none). */
+export type HashedBinding = {
+    key: string;
+    page: string;
+    component?: string | null;
+    file?: string | null;
+    collection: string;
+    field?: string | null;
+    target: string;
+    required?: boolean | null;
+};
+export type HashedManifest = {
+    framework?: string | null;
+    integrationMode?: string | null;
+    pages?: {
+        route: string;
+        file?: string | null;
+    }[] | null;
+    bindings: HashedBinding[];
+    notes?: string[] | null;
+};
+export declare function integrationHash(schemaHash: string, manifest: HashedManifest): string;

package/dist/integrationHash.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export function integrationHash(schemaHash, manifest) {
+    const projection = {
+        schema: schemaHash,
+        framework: manifest.framework || null,
+        integrationMode: manifest.integrationMode || null,
+        pages: (manifest.pages ?? [])
+            .map((p) => ({ route: p.route, file: p.file || null }))
+            .sort((a, b) => byText(a.route, b.route) || byText(a.file ?? "", b.file ?? "")),
+        bindings: manifest.bindings
+            .map((b) => ({
+            key: b.key,
+            page: b.page,
+            collection: b.collection,
+            field: b.field || null,
+            target: b.target,
+            required: b.required ?? true,
+            component: b.component || null,
+            file: b.file || null,
+        }))
+            .sort((a, b) => byText(a.key, b.key)),
+        notes: manifest.notes ?? [],
+    };
+    return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);
+}

package/dist/md.d.ts

@@ -0,0 +1,62 @@
+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=… integration=…
+    generated=… -->`) and the only line allowed to differ between a fresh
+    file and an up-to-date one — by its time. */
+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;
+    /** the integration hash (§21.4); missing from an API older than the hash */
+    integrationHash?: string | null;
+    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;
+    integration: 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,113 @@
+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=… integration=…
+    generated=… -->`) and the only line allowed to differ between a fresh
+    file and an up-to-date one — by its time. */
+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, integration: 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" || key === "integration")
+            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 &&
+        a.stamp.integration === b.stamp.integration);
+}
+/** 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.4.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",