@mapled/cli 0.3.0 → 0.4.0

package/README.md

@@ -121,7 +121,7 @@ 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`.
 
@@ -133,7 +133,7 @@ npx @mapled/cli md pull
 
 Writes `MAPLED.md` at the repository root — the guide Mapled renders from the project for whoever works on the site next, person or AI agent: the project and how the site reads it, the content model with every field's type, rules and help text, where each page renders which field (from the pushed manifest), the last setup run with its verification, the working rules, and the commands that verify the integration. It never contains a secret.
 
-The first line is a stamp with the schema hash and the manifest version. Everything below the `<!-- mapled:notes -->` line is yours — conventions, what stays hardcoded on purpose, things to avoid — and survives every `md pull`. A `MAPLED.md` Mapled didn't write is left alone unless you pass `--force`, which moves its content below the notes line. `mapled doctor` tells you when the file no longer matches the project; your AI agent gets the same document from the `get_mapled_md` tool.
+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
 
@@ -149,6 +149,7 @@ Mapled doctor — Dolphin Landing
 ✓ Generated types      mapled-types.ts matches the schema (3f9a1c2b4d5e)
 ✓ Schema pin           mapled/schema.json matches the schema (3f9a1c2b4d5e)
 ✓ Site manifest        mapled/manifest.json is pushed as manifest v3 (14 bindings on 3 pages)
+✓ 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.
@@ -164,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.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.
+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.
 

package/dist/commands.js

@@ -332,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) {
@@ -542,6 +543,7 @@ 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)));

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/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

@@ -4,9 +4,9 @@ import type { Check } from "./doctor.js";
     GET /v1/agent/mapled-md answers and keeps everything below the notes
     marker — that part is the repository's own; `doctor` compares the
     rendered part of the local file with a fresh render. The first line
-    is a stamp (`<!-- mapled: project=… schema=… manifest=… generated=… -->`)
-    and the only line allowed to differ between a fresh file and an
-    up-to-date one. */
+    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 */
@@ -15,6 +15,8 @@ export type RenderedMd = {
     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;
@@ -29,6 +31,7 @@ export type MdStamp = {
     project: string | null;
     schema: string | null;
     manifest: string | null;
+    integration: string | null;
 };
 export type MdParts = {
     stamp: MdStamp;

package/dist/md.js

@@ -4,9 +4,9 @@ import { CliError } from "./errors.js";
     GET /v1/agent/mapled-md answers and keeps everything below the notes
     marker — that part is the repository's own; `doctor` compares the
     rendered part of the local file with a fresh render. The first line
-    is a stamp (`<!-- mapled: project=… schema=… manifest=… generated=… -->`)
-    and the only line allowed to differ between a fresh file and an
-    up-to-date one. */
+    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. */
@@ -16,14 +16,14 @@ export function splitMd(text) {
     const m = /^<!-- mapled: (.*) -->\s*$/.exec(first);
     if (!m)
         return null;
-    const stamp = { project: null, schema: null, manifest: 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")
+        if (key === "project" || key === "schema" || key === "manifest" || key === "integration")
             stamp[key] = value;
     }
     const marker = lines.indexOf(NOTES_MARKER, 1);
@@ -34,7 +34,10 @@ export function splitMd(text) {
 /** 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;
+    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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.3.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",