@mapled/cli 0.1.0 → 0.3.0

package/dist/commands.js

@@ -1,17 +1,18 @@
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { apiGet, Session } from "./api.js";
+import { ApiError, apiGet, Session } from "./api.js";
 import { stringFlag } from "./args.js";
 import { CONFIG_FILE, DEFAULT_TYPES_PATH, findConfig, resolveApi, writeConfig } from "./config.js";
 import { connectionsFor, findConnection, readCredentials, removeConnection, upsertConnection, writeCredentials, } from "./credentials.js";
 import * as dr from "./doctor.js";
 import { CliError } from "./errors.js";
+import { checkManifest, compareManifests, fileExistsIn, MANIFEST_FILE, manifestSummary, orderManifest, parseManifest, plural, readManifestFile, writeManifestFile, } from "./manifest.js";
 import { authorize, clientKnown, exchangeCode, registerClient, revokeToken } from "./oauth.js";
-import { formatChecks, summarize, useColor } from "./output.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";
-function plural(n, word) {
-    return `${n} ${word}${n === 1 ? "" : "s"}`;
-}
 /** The OAuth client id for this API — registered once per machine, and
     again when the server no longer knows it. */
 async function ensureClient(store, api, f) {
@@ -147,6 +148,349 @@ export async function generate(ctx, flags) {
     await writeFile(file, generated.text);
     ctx.out(`Wrote ${path.relative(ctx.cwd, file) || out} — ${plural(generated.collections, "collection")}, ` +
         `${plural(generated.singles, "single")} (schema ${generated.hash}).`);
+    // the pin moves with the types, so `schema diff` starts from what the site was built against
+    const existing = await readPin(found.dir);
+    if (existing && existing.pin.hash !== generated.hash) {
+        await writePin(found.dir, pinSchema(schema, found.config.project));
+        ctx.out(`Refreshed ${SCHEMA_FILE} (schema ${existing.pin.hash} → ${generated.hash}).`);
+    }
+}
+/* ---- wave 2: the schema pin ---- */
+function paintSeverity(color) {
+    return (severity, text) => paint(severity === "breaking" ? "failed" : "skipped", text, color);
+}
+export async function schemaPull(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const live = await session.get("/v1/agent/schema");
+    const pin = pinSchema(live, found.config.project);
+    const existing = await readPin(found.dir);
+    const collections = pin.collections.filter((c) => c.kind === "collection").length;
+    const singles = pin.collections.length - collections;
+    if (!existing) {
+        await writePin(found.dir, pin);
+        ctx.out(`Wrote ${SCHEMA_FILE} — ${plural(collections, "collection")}, ${plural(singles, "single")} (schema ${pin.hash}).`);
+        return;
+    }
+    if (existing.pin.hash === pin.hash) {
+        ctx.out(`${SCHEMA_FILE} is up to date (schema ${pin.hash}).`);
+        return;
+    }
+    const changes = diffSchema(existing.pin.collections, pin.collections);
+    await writePin(found.dir, pin);
+    ctx.out(`Updated ${SCHEMA_FILE} (schema ${existing.pin.hash} → ${pin.hash}): ${summarizeChanges(changes).toLowerCase()}.`);
+    ctx.out("");
+    for (const line of formatChanges(changes, paintSeverity(useColor(ctx.env))))
+        ctx.out(line);
+    const typesPath = found.config.types ?? DEFAULT_TYPES_PATH;
+    const types = await readFile(path.join(found.dir, typesPath), "utf8").catch(() => null);
+    if (types !== null) {
+        ctx.out("");
+        ctx.out(`Next: \`mapled types generate\` — ${typesPath} still describes the previous schema.`);
+    }
+}
+export async function schemaDiff(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const existing = await readPin(found.dir);
+    if (!existing) {
+        throw new CliError(`No ${SCHEMA_FILE} yet. Run \`mapled schema pull\` to record the schema this site is built against.`);
+    }
+    const live = pinSchema(await session.get("/v1/agent/schema"), found.config.project);
+    const changes = diffSchema(existing.pin.collections, live.collections);
+    if (flags.json) {
+        ctx.out(JSON.stringify({ from: existing.pin.hash, to: live.hash, changes }, null, 2));
+    }
+    else if (changes.length === 0) {
+        ctx.out(`No schema changes since ${SCHEMA_FILE} (${existing.pin.hash}).`);
+    }
+    else {
+        ctx.out(`Schema changes since ${SCHEMA_FILE} (${existing.pin.hash} → ${live.hash}):`);
+        ctx.out("");
+        for (const line of formatChanges(changes, paintSeverity(useColor(ctx.env))))
+            ctx.out(line);
+        ctx.out("");
+        const typesPath = found.config.types ?? DEFAULT_TYPES_PATH;
+        const types = await readFile(path.join(found.dir, typesPath), "utf8").catch(() => null);
+        const next = types !== null ? `\`mapled types generate\` (it refreshes ${SCHEMA_FILE} as well)` : `\`mapled schema pull\``;
+        ctx.out(`${summarizeChanges(changes)}, judged for a site that reads the content. Update the site where needed, then run ${next}.`);
+    }
+    return flags["exit-code"] && changes.length > 0 ? 1 : 0;
+}
+async function loadManifest(dir) {
+    const found = await readManifestFile(dir);
+    if (!found)
+        return null;
+    const parsed = parseManifest(found.raw, MANIFEST_FILE);
+    return { file: found.file, ...parsed };
+}
+/** The schema to check bindings against: the pin when the repository
+    keeps one, otherwise the live schema of a signed-in project. */
+async function schemaForChecks(ctx, flags, found) {
+    const pin = await readPin(found.dir);
+    if (pin)
+        return { schema: { collections: pin.pin.collections }, note: null };
+    try {
+        const { session } = await openSession(ctx, flags);
+        return { schema: await session.get("/v1/agent/schema"), note: null };
+    }
+    catch (err) {
+        return {
+            schema: null,
+            note: `Bindings weren't checked against the schema — ${err instanceof Error ? err.message.replace(/\.$/, "") : "sign in"}, or run \`mapled schema pull\`.`,
+        };
+    }
+}
+function formatProblems(problems, color) {
+    return problems.map((p) => `${paint(p.level === "error" ? "failed" : "warning", GLYPH[p.level === "error" ? "failed" : "warning"], color)} ${p.message}`);
+}
+function problemSummary(problems) {
+    const errors = problems.filter((p) => p.level === "error").length;
+    const warnings = problems.length - errors;
+    const parts = [];
+    if (errors > 0)
+        parts.push(plural(errors, "problem"));
+    if (warnings > 0)
+        parts.push(plural(warnings, "warning"));
+    return { errors, warnings, text: parts.join(", ") };
+}
+export async function manifestValidate(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    const dir = found?.dir ?? path.resolve(ctx.cwd);
+    const loaded = await loadManifest(dir);
+    if (!loaded) {
+        throw new CliError(`No ${MANIFEST_FILE} here. Run \`mapled scan --write\` to create one from the site's code, or ask your AI agent to write it.`);
+    }
+    const notes = [];
+    let schema = null;
+    if (found) {
+        const got = await schemaForChecks(ctx, flags, found);
+        schema = got.schema;
+        if (got.note)
+            notes.push(got.note);
+    }
+    else {
+        notes.push(`Bindings weren't checked against the schema — no ${CONFIG_FILE} here; run \`mapled project link\`.`);
+    }
+    const problems = [...loaded.problems, ...(await checkManifest(loaded.manifest, { schema, fileExists: fileExistsIn(dir) }))];
+    problems.sort((a, b) => (a.level === b.level ? 0 : a.level === "error" ? -1 : 1));
+    const summary = problemSummary(problems);
+    if (flags.json) {
+        ctx.out(JSON.stringify({ file: MANIFEST_FILE, bindings: loaded.manifest.bindings.length, pages: loaded.manifest.pages?.length ?? 0, problems, notes }, null, 2));
+    }
+    else {
+        if (problems.length > 0) {
+            for (const line of formatProblems(problems, useColor(ctx.env)))
+                ctx.out(line);
+            ctx.out("");
+        }
+        for (const note of notes)
+            ctx.out(note);
+        ctx.out(`${MANIFEST_FILE}: ${manifestSummary(loaded.manifest)} — ${problems.length === 0 ? "valid" : summary.text}.`);
+        if (summary.errors > 0)
+            ctx.out("Fix the problems before `mapled bindings push`.");
+    }
+    return summary.errors > 0 ? 1 : 0;
+}
+export async function bindingsPush(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const loaded = await loadManifest(found.dir);
+    if (!loaded)
+        throw new CliError(`No ${MANIFEST_FILE} here. Run \`mapled scan --write\` to create one from the site's code.`);
+    const schema = await session.get("/v1/agent/schema");
+    const problems = [...loaded.problems, ...(await checkManifest(loaded.manifest, { schema, fileExists: fileExistsIn(found.dir) }))];
+    const summary = problemSummary(problems);
+    if (summary.errors > 0) {
+        throw new CliError(`${MANIFEST_FILE} has ${plural(summary.errors, "problem")} — run \`mapled manifest validate\` and fix them first.`);
+    }
+    const color = useColor(ctx.env);
+    if (problems.length > 0)
+        for (const line of formatProblems(problems, color))
+            ctx.out(line);
+    const body = orderManifest(loaded.manifest);
+    if (flags["dry-run"]) {
+        ctx.out(`Would push ${MANIFEST_FILE} to ${session.conn.projectName} — ${manifestSummary(body)}${summary.warnings > 0 ? `, ${plural(summary.warnings, "warning")}` : ""}. Nothing was sent.`);
+        return;
+    }
+    let result;
+    try {
+        result = await session.send("POST", "/v1/agent/manifest", body);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === "BUILDER_PLAN_REQUIRED") {
+            throw new CliError("Pushing bindings changes the project's structure, which needs a builder plan — ask the project owner to upgrade.");
+        }
+        throw err;
+    }
+    const s = result.summary;
+    const graded = [`${s.healthy ?? 0} healthy`];
+    if (s.type_mismatch)
+        graded.push(`${s.type_mismatch} type mismatch${s.type_mismatch === 1 ? "" : "es"}`);
+    if (s.outdated)
+        graded.push(`${s.outdated} outdated`);
+    if (s.not_checked)
+        graded.push(`${s.not_checked} not checked`);
+    if (s.missing_on_site)
+        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(", ")}.`);
+    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) {
+        ctx.out("Open Structure → Bindings in Mapled to review them.");
+    }
+}
+export async function bindingsPull(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    let stored;
+    try {
+        stored = await session.get("/v1/agent/manifest");
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            throw new CliError(`Nothing to pull — no manifest has been pushed to ${session.conn.projectName} yet.`);
+        }
+        throw err;
+    }
+    const local = await loadManifest(found.dir);
+    if (local && !flags.force) {
+        const diff = compareManifests(local.manifest, stored.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`);
+            throw new CliError(`${MANIFEST_FILE} differs from the pushed manifest (v${stored.version}): ${parts.join(", ")}. Pass --force to overwrite it, or push yours with \`mapled bindings push\`.`);
+        }
+    }
+    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));
+    const lines = [];
+    const byPage = new Map();
+    for (const b of result.bindings) {
+        if (!byPage.has(b.page))
+            byPage.set(b.page, []);
+        byPage.get(b.page).push(b);
+    }
+    const fileOf = new Map(result.pages.map((p) => [p.route, p.file ?? ""]));
+    const routeWidth = Math.max(0, ...[...byPage.keys()].map((r) => r.length));
+    for (const [page, list] of byPage) {
+        lines.push(`${page.padEnd(routeWidth)}  ${fileOf.get(page) ?? ""}`.trimEnd());
+        const byCollection = new Map();
+        for (const b of list) {
+            if (!byCollection.has(b.collection))
+                byCollection.set(b.collection, []);
+            byCollection.get(b.collection).push(b);
+        }
+        const width = Math.max(0, ...[...byCollection.keys()].map((c) => c.length));
+        for (const [collection, bindings] of byCollection) {
+            const parts = [];
+            if (bindings.some((b) => b.target === "collection"))
+                parts.push(singles.has(collection) ? "read" : "list");
+            if (bindings.some((b) => b.target === "route_param"))
+                parts.push("by slug");
+            const fields = bindings.filter((b) => b.field && b.target !== "route_param").map((b) => b.field);
+            if (fields.length > 0)
+                parts.push(fields.join(", "));
+            lines.push(`  ${collection.padEnd(width)}  ${parts.join(" • ")}`);
+        }
+    }
+    return lines;
+}
+export async function scan(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    if (!found)
+        throw new CliError(`No ${CONFIG_FILE} here or above. Run \`mapled project link\` first.`);
+    const { schema, note } = await schemaForChecks(ctx, flags, found);
+    if (!schema) {
+        throw new CliError(`The scan needs the schema to name the fields — sign in with \`mapled auth login\` or run \`mapled schema pull\` first.`);
+    }
+    const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
+    const ts = loadTypeScript(found.dir);
+    const result = await scanRepository(found.dir, { framework, schema, ts });
+    const existing = await loadManifest(found.dir);
+    const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
+    if (flags.json) {
+        ctx.out(JSON.stringify({ parser: result.parser, files: result.files, manifest: orderManifest(merged.manifest), notes: result.notes, kept: merged.kept, dropped: merged.dropped }, null, 2));
+        if (flags.write)
+            await writeManifestFile(found.dir, merged.manifest);
+        return;
+    }
+    ctx.out(`Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
+    if (result.bindings.length > 0) {
+        ctx.out("");
+        for (const line of describeScan(result, schema))
+            ctx.out(line);
+    }
+    if (result.notes.length > 0) {
+        ctx.out("");
+        for (const n of result.notes)
+            ctx.out(`${paint("warning", GLYPH.warning, useColor(ctx.env))} ${n}`);
+    }
+    ctx.out("");
+    const keptNote = merged.kept.length > 0 ? ` Kept ${plural(merged.kept.length, "binding")} the scan didn't find (${merged.kept.slice(0, 5).join(", ")}${merged.kept.length > 5 ? ", …" : ""}) — pass --prune to drop them.` : "";
+    const droppedNote = merged.dropped.length > 0 ? ` Dropped ${plural(merged.dropped.length, "binding")} the scan didn't find (${merged.dropped.slice(0, 5).join(", ")}${merged.dropped.length > 5 ? ", …" : ""}).` : "";
+    if (flags.write) {
+        await writeManifestFile(found.dir, merged.manifest);
+        const parts = [];
+        if (merged.added.length > 0)
+            parts.push(`${merged.added.length} new`);
+        if (merged.changed.length > 0)
+            parts.push(`${merged.changed.length} changed`);
+        if (merged.unchanged.length > 0)
+            parts.push(`${merged.unchanged.length} unchanged`);
+        ctx.out(`Wrote ${MANIFEST_FILE} — ${manifestSummary(merged.manifest)}${parts.length > 0 && existing ? ` (${parts.join(", ")})` : ""}.${keptNote}${droppedNote}`);
+        ctx.out("Next: `mapled bindings push`.");
+    }
+    else if (!existing) {
+        ctx.out(`No ${MANIFEST_FILE} yet — run \`mapled scan --write\` to create it, then \`mapled bindings push\`.`);
+    }
+    else {
+        const parts = [];
+        if (merged.added.length > 0)
+            parts.push(`${merged.added.length} new`);
+        if (merged.changed.length > 0)
+            parts.push(`${merged.changed.length} changed`);
+        parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.kept.length > 0)
+            parts.push(`${merged.kept.length} not found in the code (${merged.kept.slice(0, 5).join(", ")}${merged.kept.length > 5 ? ", …" : ""})`);
+        ctx.out(`Compared with ${MANIFEST_FILE}: ${parts.join(", ")}.`);
+        if (merged.added.length > 0 || merged.changed.length > 0) {
+            ctx.out(`Run \`mapled scan --write\` to update ${MANIFEST_FILE}, then \`mapled bindings push\`.`);
+        }
+        else {
+            ctx.out(`${MANIFEST_FILE} already describes what the code reads.`);
+        }
+    }
+    if (note)
+        ctx.out(note);
 }
 export async function doctor(ctx, flags) {
     const found = await findConfig(ctx.cwd);
@@ -156,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);
@@ -166,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));
@@ -173,6 +527,22 @@ export async function doctor(ctx, flags) {
     const typesPath = found?.config.types ?? DEFAULT_TYPES_PATH;
     const existing = await readFile(path.join(dir, typesPath), "utf8").catch(() => null);
     checks.push(dr.checkTypes(existing, schema ? generateTypes(schema, { projectName: status?.project.name }) : null, typesPath));
+    const pin = found ? await readPin(dir).catch(() => null) : null;
+    const livePin = schema && found ? pinSchema(schema, found.config.project) : null;
+    const pinChanges = pin && livePin ? diffSchema(pin.pin.collections, livePin.collections) : null;
+    checks.push(dr.checkSchemaPin(pin?.pin ?? null, livePin?.hash ?? null, pinChanges));
+    const localManifest = await loadManifest(dir).catch(() => null);
+    let remoteManifest = "unknown";
+    if (conn && status && localManifest) {
+        try {
+            remoteManifest = await new Session(store, ctx.credentialsFile, conn, ctx.fetch).get("/v1/agent/manifest");
+        }
+        catch (err) {
+            remoteManifest = err instanceof ApiError && err.status === 404 ? null : "unknown";
+        }
+    }
+    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/doctor.d.ts

@@ -1,5 +1,7 @@
 import type { Connection } from "./credentials.js";
+import { type Manifest, type Problem } from "./manifest.js";
 import type { Fetch } from "./oauth.js";
+import { type SchemaChange, type SchemaPin } from "./pin.js";
 import { type Generated } from "./types.js";
 /** `mapled doctor` (§31.3, wave 1): the checks themselves are pure
     functions of what was gathered — the repository side here, the
@@ -103,4 +105,16 @@ export declare function checkPreviewOnSite(origin: string | null, previewPath: s
     status: number | null;
 } | null): Check;
 export declare function checkBindings(bindings: IntegrationStatus["bindings"]): Check;
+export declare function checkSchemaPin(pin: SchemaPin | null, liveHash: string | null, changes: SchemaChange[] | null): Check;
+/** The pushed manifest as `GET /v1/agent/manifest` answers it. */
+export type StoredManifest = {
+    version: number;
+    clientName: string;
+    createdAt: string;
+    manifest: Manifest;
+};
+export declare function checkManifestFile(local: {
+    manifest: Manifest;
+    problems: Problem[];
+} | null, remote: StoredManifest | null | "unknown"): Check;
 export declare const REMOTE_CHECKS: [string, string][];

package/dist/doctor.js

@@ -2,6 +2,8 @@ import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
+import { SCHEMA_FILE } from "./pin.js";
 import { splitGenerated } from "./types.js";
 export function ago(iso) {
     const m = Math.floor((Date.now() - new Date(iso).getTime()) / 60_000);
@@ -414,6 +416,52 @@ export function checkBindings(bindings) {
         detail: `${s.healthy ?? 0} healthy • synced ${ago(bindings.manifest.createdAt)} from ${bindings.manifest.clientName}`,
     };
 }
+export function checkSchemaPin(pin, liveHash, changes) {
+    const label = "Schema pin";
+    if (!pin)
+        return { key: "schema", label, status: "skipped", detail: `No ${SCHEMA_FILE} — run \`mapled schema pull\` to track schema changes.` };
+    if (!liveHash || !changes)
+        return { key: "schema", label, status: "skipped", detail: "Sign in to compare with the schema." };
+    if (changes.length === 0)
+        return { key: "schema", label, status: "passed", detail: `${SCHEMA_FILE} matches the schema (${pin.hash})` };
+    const breaking = changes.filter((c) => c.severity === "breaking").length;
+    const n = changes.length;
+    const detail = breaking > 0
+        ? `${n} change${n === 1 ? "" : "s"} since ${SCHEMA_FILE} (${breaking} breaking) — run \`mapled schema diff\`.`
+        : `${n} safe change${n === 1 ? "" : "s"} since ${SCHEMA_FILE} — run \`mapled schema diff\`.`;
+    return { key: "schema", label, status: "warning", detail };
+}
+export function checkManifestFile(local, remote) {
+    const label = "Site manifest";
+    if (!local) {
+        return { key: "manifest", label, status: "skipped", detail: `No ${MANIFEST_FILE} — run \`mapled scan --write\` to create one from the site's code.` };
+    }
+    const errors = local.problems.filter((p) => p.level === "error").length;
+    if (errors > 0) {
+        return { key: "manifest", label, status: "failed", detail: `${MANIFEST_FILE} has ${errors} problem${errors === 1 ? "" : "s"} — run \`mapled manifest validate\`.` };
+    }
+    if (remote === "unknown")
+        return { key: "manifest", label, status: "passed", detail: `${MANIFEST_FILE}: ${manifestSummary(local.manifest)}` };
+    if (remote === null)
+        return { key: "manifest", label, status: "warning", detail: `${MANIFEST_FILE} isn't pushed yet — run \`mapled bindings push\`.` };
+    const diff = compareManifests(local.manifest, remote.manifest);
+    if (diff.same) {
+        return { key: "manifest", label, status: "passed", detail: `${MANIFEST_FILE} is pushed as manifest v${remote.version} (${manifestSummary(local.manifest)})` };
+    }
+    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`);
+    return {
+        key: "manifest",
+        label,
+        status: "warning",
+        detail: `${MANIFEST_FILE} differs from the pushed manifest (v${remote.version}): ${parts.join(", ")} — run \`mapled bindings push\`.`,
+    };
+}
 export const REMOTE_CHECKS = [
     ["reads", "Site reads content"],
     ["webhook", "Publish webhook"],

package/dist/index.js

@@ -3,11 +3,13 @@ import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "./args.js";
 import { openBrowser } from "./browser.js";
-import { doctor, generate, link, login, logout } 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, check the integration (§31, wave 1). */
+    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
@@ -15,6 +17,13 @@ Usage
   mapled auth logout [--all]                          Revoke this machine's access to the linked project
   mapled project link [--project <id>]                Write mapled.json for this repository
   mapled types generate [--out <file>]                Generate TypeScript types for the content
+  mapled schema pull                                  Record the schema this site is built against (mapled/schema.json)
+  mapled schema diff [--json] [--exit-code]           Show what changed in Mapled since the last pull
+  mapled scan [--write] [--prune] [--json]            Find where the code reads Mapled; --write updates mapled/manifest.json
+  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
@@ -80,11 +89,34 @@ async function main(argv) {
         case "types generate":
             await generate(ctx, flags);
             return 0;
+        case "schema pull":
+            await schemaPull(ctx, flags);
+            return 0;
+        case "schema diff":
+            return schemaDiff(ctx, flags);
+        case "scan":
+            await scan(ctx, flags);
+            return 0;
+        case "manifest validate":
+            return manifestValidate(ctx, flags);
+        case "bindings push":
+            await bindingsPush(ctx, flags);
+            return 0;
+        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":
         case "project":
         case "types":
+        case "schema":
+        case "manifest":
+        case "bindings":
+        case "md":
             console.log(HELP);
             return 2;
         default:

package/dist/manifest.d.ts

@@ -0,0 +1,95 @@
+import type { Schema } from "./schema.js";
+/** mapled/manifest.json — the site manifest (§21): the pages of the site
+    and where each field is rendered (the bindings). The same shape the
+    API's POST /v1/agent/manifest accepts and the AI agent's
+    push_site_manifest tool sends; only these fields survive a push.
+    Everything in the file is content the site's authors wrote — checked
+    against the schema, never interpolated anywhere. */
+export declare const MANIFEST_FILE = "mapled/manifest.json";
+export declare const BINDING_TARGETS: readonly ["text", "rich_text", "image", "image_alt", "link", "number", "date", "boolean", "collection", "route_param", "form_field", "other"];
+export type BindingTarget = (typeof BINDING_TARGETS)[number];
+export type ManifestBinding = {
+    key: string;
+    page: string;
+    component?: string;
+    file?: string;
+    collection: string;
+    field?: string;
+    target: BindingTarget;
+    required?: boolean;
+};
+export type ManifestPage = {
+    route: string;
+    file?: string;
+};
+export type Manifest = {
+    framework?: string;
+    integrationMode?: string;
+    pages?: ManifestPage[];
+    bindings: ManifestBinding[];
+    notes?: string[];
+};
+export declare const KEY_PATTERN: RegExp;
+export declare const LIMITS: {
+    bindings: number;
+    pages: number;
+    notes: number;
+};
+/** Field types a target renders without a transform — the API's table
+    (lib/bindings.ts), which grades each pushed binding the same way. */
+export declare const COMPATIBLE: Partial<Record<BindingTarget, string[]>>;
+/** The natural target of a field type — what `mapled scan` records when
+    the site reads the field. */
+export declare function targetFor(fieldType: string | undefined): BindingTarget;
+export declare const FIELD_TYPE_LABEL: Record<string, string>;
+export declare function typeLabel(type: string): string;
+export type Problem = {
+    level: "error" | "warning";
+    path: string;
+    message: string;
+};
+/** Parses the file's text into a manifest with only the known fields,
+    reporting every shape problem the API would refuse (as errors) and the
+    parts it would silently drop (as warnings). */
+export declare function parseManifest(raw: string, file: string): {
+    manifest: Manifest;
+    problems: Problem[];
+};
+export type SchemaIndex = Map<string, {
+    displayName: string;
+    kind: string;
+    fields: Map<string, {
+        displayName: string;
+        type: string;
+    }>;
+}>;
+export declare function indexSchema(schema: Schema): SchemaIndex;
+/** What a well-formed manifest still gets wrong: bindings the schema
+    can't back (Mapled would grade them outdated or mismatched), files the
+    repository doesn't have, pages the list doesn't know. Warnings only —
+    the API accepts all of it and the Bindings screen shows the health. */
+export declare function checkManifest(manifest: Manifest, opts: {
+    schema: Schema | null;
+    fileExists: (rel: string) => Promise<boolean>;
+}): Promise<Problem[]>;
+export declare function fileExistsIn(dir: string): (rel: string) => Promise<boolean>;
+export declare function readManifestFile(dir: string): Promise<{
+    file: string;
+    raw: string;
+} | null>;
+/** Writes the manifest with its keys in a stable order; bindings keep
+    the order they came in. */
+export declare function writeManifestFile(dir: string, manifest: Manifest): Promise<string>;
+export declare function orderManifest(manifest: Manifest): Manifest;
+export declare function orderBinding(b: ManifestBinding): ManifestBinding;
+export declare function plural(n: number, word: string, pluralWord?: string): string;
+export declare function manifestSummary(manifest: Manifest): string;
+/** Bindings that mean the same thing to Mapled (what a push stores). */
+export declare function sameBinding(a: ManifestBinding, b: ManifestBinding): boolean;
+export type ManifestComparison = {
+    same: boolean;
+    onlyLocal: string[];
+    onlyRemote: string[];
+    changed: string[];
+};
+export declare function compareManifests(local: Manifest, remote: Manifest): ManifestComparison;