@mapled/cli 0.1.0 → 0.2.0

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,12 @@ 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, 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 and the site manifest in step
+    with the code, check the integration (§31, waves 1 and 2). */
 const HELP = `mapled — the Mapled CLI
 
 Usage
@@ -15,6 +16,12 @@ 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 doctor [--json]                              Check the integration end to end
 
 Options
@@ -80,11 +87,30 @@ 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 "doctor":
             return doctor(ctx, flags);
         case "auth":
         case "project":
         case "types":
+        case "schema":
+        case "manifest":
+        case "bindings":
             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;

package/dist/manifest.js

@@ -0,0 +1,374 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.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 const MANIFEST_FILE = "mapled/manifest.json";
+export const BINDING_TARGETS = [
+    "text",
+    "rich_text",
+    "image",
+    "image_alt",
+    "link",
+    "number",
+    "date",
+    "boolean",
+    "collection",
+    "route_param",
+    "form_field",
+    "other",
+];
+export const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]{0,119}$/;
+export const LIMITS = { bindings: 500, pages: 200, notes: 20 };
+/** Field types a target renders without a transform — the API's table
+    (lib/bindings.ts), which grades each pushed binding the same way. */
+export const COMPATIBLE = {
+    text: ["short_text", "long_text", "slug", "number", "date", "datetime", "enum", "url", "email", "color"],
+    rich_text: ["rich_text", "long_text"],
+    image: ["image"],
+    image_alt: ["short_text", "long_text"],
+    link: ["short_text", "slug", "url", "email", "file"],
+    number: ["number"],
+    date: ["date", "datetime"],
+    boolean: ["boolean"],
+    route_param: ["slug", "short_text"],
+};
+/** The natural target of a field type — what `mapled scan` records when
+    the site reads the field. */
+export function targetFor(fieldType) {
+    switch (fieldType) {
+        case "rich_text":
+            return "rich_text";
+        case "image":
+            return "image";
+        case "url":
+        case "email":
+        case "file":
+            return "link";
+        case "number":
+            return "number";
+        case "date":
+        case "datetime":
+            return "date";
+        case "boolean":
+            return "boolean";
+        case "relation":
+        case "group":
+        case "json":
+        case "location":
+            return "other";
+        default:
+            return "text";
+    }
+}
+export const FIELD_TYPE_LABEL = {
+    short_text: "short text",
+    long_text: "long text",
+    rich_text: "rich text",
+    slug: "slug",
+    image: "image",
+    file: "file",
+    number: "number",
+    boolean: "boolean",
+    date: "date",
+    datetime: "date and time",
+    enum: "choice",
+    url: "URL",
+    email: "email",
+    color: "color",
+    relation: "relation",
+    group: "group",
+    json: "JSON",
+    location: "location",
+};
+export function typeLabel(type) {
+    return FIELD_TYPE_LABEL[type] ?? type;
+}
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const isText = (v, max, min = 1) => typeof v === "string" && v.length >= min && v.length <= max;
+const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes"]);
+const BINDING_KEYS = new Set(["key", "page", "component", "file", "collection", "field", "target", "required"]);
+/** 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 function parseManifest(raw, file) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${file} isn't valid JSON.`);
+    }
+    const problems = [];
+    const error = (p, message) => problems.push({ level: "error", path: p, message });
+    const warn = (p, message) => problems.push({ level: "warning", path: p, message });
+    const manifest = { bindings: [] };
+    if (!isObject(data)) {
+        error("", `${file} must be a JSON object with a "bindings" list.`);
+        return { manifest, problems };
+    }
+    for (const key of Object.keys(data)) {
+        if (!TOP_KEYS.has(key))
+            warn(key, `"${key}" isn't part of the manifest and is dropped on push.`);
+    }
+    if (data.framework !== undefined) {
+        if (isText(data.framework, 40))
+            manifest.framework = data.framework;
+        else
+            error("framework", `"framework" must be a short name (up to 40 characters).`);
+    }
+    if (data.integrationMode !== undefined) {
+        if (isText(data.integrationMode, 40))
+            manifest.integrationMode = data.integrationMode;
+        else
+            error("integrationMode", `"integrationMode" must be a short name (up to 40 characters).`);
+    }
+    if (data.pages !== undefined) {
+        if (!Array.isArray(data.pages))
+            error("pages", `"pages" must be a list of { route, file }.`);
+        else {
+            if (data.pages.length > LIMITS.pages)
+                error("pages", `"pages" has ${data.pages.length} entries — the limit is ${LIMITS.pages}.`);
+            manifest.pages = [];
+            data.pages.forEach((p, i) => {
+                const at = `pages[${i}]`;
+                if (!isObject(p))
+                    return error(at, `${at} must be an object with a "route".`);
+                if (!isText(p.route, 200))
+                    return error(`${at}.route`, `${at}.route must be the page route, e.g. "/" or "/blog/[slug]".`);
+                const page = { route: p.route };
+                if (p.file !== undefined) {
+                    if (isText(p.file, 300, 0))
+                        page.file = p.file;
+                    else
+                        return error(`${at}.file`, `${at}.file must be a path (up to 300 characters).`);
+                }
+                manifest.pages.push(page);
+            });
+        }
+    }
+    if (!Array.isArray(data.bindings)) {
+        error("bindings", `"bindings" must be a list of bindings — { key, page, collection, field, target } each.`);
+    }
+    else {
+        if (data.bindings.length > LIMITS.bindings) {
+            error("bindings", `"bindings" has ${data.bindings.length} entries — the limit is ${LIMITS.bindings}.`);
+        }
+        const seen = new Map();
+        data.bindings.forEach((b, i) => {
+            const at = `bindings[${i}]`;
+            if (!isObject(b))
+                return error(at, `${at} must be an object.`);
+            for (const key of Object.keys(b)) {
+                if (!BINDING_KEYS.has(key))
+                    warn(`${at}.${key}`, `${at}.${key} isn't part of a binding and is dropped on push.`);
+            }
+            let ok = true;
+            if (typeof b.key !== "string" || !KEY_PATTERN.test(b.key)) {
+                error(`${at}.key`, `${at}.key must be 1–120 characters — letters, digits, . _ : / [ ] and -, starting with a letter or digit.`);
+                ok = false;
+            }
+            else if (seen.has(b.key)) {
+                error(`${at}.key`, `${at}.key "${b.key}" is already used by bindings[${seen.get(b.key)}].`);
+                ok = false;
+            }
+            else
+                seen.set(b.key, i);
+            if (!isText(b.page, 200)) {
+                error(`${at}.page`, `${at}.page must name the page route, e.g. "/" or "/blog/[slug]".`);
+                ok = false;
+            }
+            if (!isText(b.collection, 120)) {
+                error(`${at}.collection`, `${at}.collection must be a collection key.`);
+                ok = false;
+            }
+            if (b.field !== undefined && !isText(b.field, 120)) {
+                error(`${at}.field`, `${at}.field must be a field key (up to 120 characters).`);
+                ok = false;
+            }
+            if (typeof b.target !== "string" || !BINDING_TARGETS.includes(b.target)) {
+                error(`${at}.target`, `${at}.target ${typeof b.target === "string" ? `"${b.target}" ` : ""}isn't one of ${BINDING_TARGETS.join(", ")}.`);
+                ok = false;
+            }
+            if (b.component !== undefined && !isText(b.component, 120, 0)) {
+                error(`${at}.component`, `${at}.component must be a name (up to 120 characters).`);
+                ok = false;
+            }
+            if (b.file !== undefined && !isText(b.file, 300, 0)) {
+                error(`${at}.file`, `${at}.file must be a path (up to 300 characters).`);
+                ok = false;
+            }
+            if (b.required !== undefined && typeof b.required !== "boolean") {
+                error(`${at}.required`, `${at}.required must be true or false.`);
+                ok = false;
+            }
+            if (!ok)
+                return;
+            const binding = {
+                key: b.key,
+                page: b.page,
+                collection: b.collection,
+                target: b.target,
+            };
+            if (typeof b.component === "string")
+                binding.component = b.component;
+            if (typeof b.file === "string")
+                binding.file = b.file;
+            if (typeof b.field === "string")
+                binding.field = b.field;
+            if (typeof b.required === "boolean")
+                binding.required = b.required;
+            manifest.bindings.push(binding);
+        });
+    }
+    if (data.notes !== undefined) {
+        if (!Array.isArray(data.notes) || data.notes.some((n) => !isText(n, 300, 0))) {
+            error("notes", `"notes" must be a list of short texts (up to 300 characters each).`);
+        }
+        else {
+            if (data.notes.length > LIMITS.notes)
+                error("notes", `"notes" has ${data.notes.length} entries — the limit is ${LIMITS.notes}.`);
+            manifest.notes = data.notes;
+        }
+    }
+    return { manifest, problems };
+}
+export function indexSchema(schema) {
+    const index = new Map();
+    for (const c of schema.collections) {
+        const fields = new Map();
+        for (const f of c.fields)
+            fields.set(f.key, { displayName: f.displayName, type: f.type });
+        index.set(c.key, { displayName: c.displayName, kind: c.kind, fields });
+    }
+    return index;
+}
+function article(word) {
+    return /^[aeiou]/i.test(word) ? "an" : "a";
+}
+/** 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 async function checkManifest(manifest, opts) {
+    const problems = [];
+    const warn = (p, message) => problems.push({ level: "warning", path: p, message });
+    const index = opts.schema ? indexSchema(opts.schema) : null;
+    const routes = new Set((manifest.pages ?? []).map((p) => p.route));
+    for (const [i, p] of (manifest.pages ?? []).entries()) {
+        if (p.file && !(await opts.fileExists(p.file))) {
+            warn(`pages[${i}].file`, `pages[${i}] (${p.route}): ${p.file} doesn't exist in the repository.`);
+        }
+    }
+    for (const [i, b] of manifest.bindings.entries()) {
+        const at = `bindings[${i}]`;
+        const who = `${at} (${b.key})`;
+        if (index) {
+            const collection = index.get(b.collection);
+            if (!collection)
+                warn(`${at}.collection`, `${who}: no collection "${b.collection}" in the schema — Mapled marks it outdated.`);
+            else if (b.field) {
+                const field = collection.fields.get(b.field);
+                if (!field) {
+                    warn(`${at}.field`, `${who}: no field "${b.field}" in "${collection.displayName}" — Mapled marks it outdated.`);
+                }
+                else {
+                    const allowed = COMPATIBLE[b.target];
+                    if (allowed && !allowed.includes(field.type)) {
+                        const label = typeLabel(field.type);
+                        warn(`${at}.target`, `${who}: "${field.displayName}" is ${article(label)} ${label} field, but the binding renders it as ${b.target.replace("_", " ")}.`);
+                    }
+                }
+            }
+        }
+        if (b.file && !(await opts.fileExists(b.file)))
+            warn(`${at}.file`, `${who}: ${b.file} doesn't exist in the repository.`);
+        if (routes.size > 0 && !routes.has(b.page))
+            warn(`${at}.page`, `${who}: page "${b.page}" isn't listed in "pages".`);
+        if (b.target === "route_param" && !/\[[^\]]+\]/.test(b.page)) {
+            warn(`${at}.target`, `${who}: route_param on "${b.page}", which has no dynamic segment like [slug].`);
+        }
+    }
+    return problems;
+}
+export function fileExistsIn(dir) {
+    return async (rel) => {
+        const target = path.resolve(dir, rel);
+        if (path.relative(dir, target).startsWith(".."))
+            return false;
+        try {
+            await access(target);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export async function readManifestFile(dir) {
+    const file = path.join(dir, MANIFEST_FILE);
+    try {
+        return { file, raw: await readFile(file, "utf8") };
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes the manifest with its keys in a stable order; bindings keep
+    the order they came in. */
+export async function writeManifestFile(dir, manifest) {
+    const file = path.join(dir, MANIFEST_FILE);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(orderManifest(manifest), null, 2) + "\n");
+    return file;
+}
+export function orderManifest(manifest) {
+    return {
+        ...(manifest.framework ? { framework: manifest.framework } : {}),
+        ...(manifest.integrationMode ? { integrationMode: manifest.integrationMode } : {}),
+        ...(manifest.pages ? { pages: manifest.pages.map((p) => ({ route: p.route, ...(p.file !== undefined ? { file: p.file } : {}) })) } : {}),
+        bindings: manifest.bindings.map(orderBinding),
+        ...(manifest.notes && manifest.notes.length > 0 ? { notes: [...manifest.notes] } : {}),
+    };
+}
+export function orderBinding(b) {
+    const out = { key: b.key, page: b.page, collection: b.collection, target: b.target };
+    if (b.field !== undefined)
+        out.field = b.field;
+    if (b.component !== undefined)
+        out.component = b.component;
+    if (b.file !== undefined)
+        out.file = b.file;
+    if (b.required !== undefined)
+        out.required = b.required;
+    return out;
+}
+export function plural(n, word, pluralWord = `${word}s`) {
+    return `${n} ${n === 1 ? word : pluralWord}`;
+}
+export function manifestSummary(manifest) {
+    const pages = new Set([...(manifest.pages ?? []).map((p) => p.route), ...manifest.bindings.map((b) => b.page)]);
+    return `${plural(manifest.bindings.length, "binding")} on ${plural(pages.size, "page")}`;
+}
+/** Bindings that mean the same thing to Mapled (what a push stores). */
+export function sameBinding(a, b) {
+    return (a.page === b.page &&
+        a.collection === b.collection &&
+        (a.field ?? null) === (b.field ?? null) &&
+        a.target === b.target &&
+        (a.required ?? true) === (b.required ?? true) &&
+        (a.component ?? null) === (b.component ?? null) &&
+        (a.file ?? null) === (b.file ?? null));
+}
+export function compareManifests(local, remote) {
+    const remoteByKey = new Map(remote.bindings.map((b) => [b.key, b]));
+    const localByKey = new Map(local.bindings.map((b) => [b.key, b]));
+    const onlyLocal = local.bindings.filter((b) => !remoteByKey.has(b.key)).map((b) => b.key);
+    const onlyRemote = remote.bindings.filter((b) => !localByKey.has(b.key)).map((b) => b.key);
+    const changed = local.bindings.filter((b) => remoteByKey.has(b.key) && !sameBinding(b, remoteByKey.get(b.key))).map((b) => b.key);
+    return { same: onlyLocal.length === 0 && onlyRemote.length === 0 && changed.length === 0, onlyLocal, onlyRemote, changed };
+}

package/dist/pin.d.ts

@@ -0,0 +1,41 @@
+import { type Schema, type SchemaCollection } from "./schema.js";
+/** mapled/schema.json — the repository's pin of the schema it was last
+    synced with (§21.5). `mapled schema diff` compares it with the live
+    schema and says which changes a site that READS the content must
+    care about; `schema pull` and `types generate` move the pin. The
+    file is deterministic: no timestamps, ids or counters. */
+export declare const SCHEMA_FILE = "mapled/schema.json";
+export type SchemaPin = {
+    project: string;
+    hash: string;
+    collections: SchemaCollection[];
+};
+/** The schema reduced to what the pin keeps — the live answer of
+    GET /v1/agent/schema without ids, positions and counters. */
+export declare function pinSchema(schema: Schema, project: string): SchemaPin;
+export declare function parsePin(raw: string, file: string): SchemaPin;
+export declare function readPin(dir: string): Promise<{
+    file: string;
+    pin: SchemaPin;
+} | null>;
+export declare function writePin(dir: string, pin: SchemaPin): Promise<string>;
+export type Severity = "breaking" | "safe";
+export type ChangeOp = "added" | "removed" | "changed";
+export type SchemaChange = {
+    scope: "collection" | "field" | "subfield";
+    collection: string;
+    collectionName: string;
+    /** The field key; "group.sub" for a sub-field. */
+    field?: string;
+    op: ChangeOp;
+    detail: string;
+    severity: Severity;
+};
+/** What changed between two schemas, judged for a site that reads the
+    content: anything that can make a read fail or a value disappear is
+    breaking; additions and renames of labels are safe. */
+export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[]): SchemaChange[];
+/** The diff as terminal lines: one heading per collection, one line per
+    change, the severity in the last column. */
+export declare function formatChanges(changes: SchemaChange[], paint?: (severity: Severity, text: string) => string): string[];
+export declare function summarizeChanges(changes: SchemaChange[]): string;