@mapled/cli 0.10.0 → 0.12.0

package/README.md

@@ -128,6 +128,8 @@ Scanned 2 HTML files — 2 pages, 11 bindings.
 ⚠ This path names nothing in the schema: home.tagline (index.html). A misspelled field empties its place on the page, a misspelled single leaves the page's own HTML.
 ```
 
+For a Next.js site the scan also records its live updates: `capabilities.realtime` is `true`, with the route in `releaseRoute`, when `<MapledLive />` or `watchRelease` asks — at the default path or one written in the code — a route whose exported `GET` answers with `createReleaseHandler`, and `false` otherwise — `MAPLED.md` then tells the next agent whether open tabs follow Publish. Capabilities aren't part of the integration hash; `doctor`'s Site manifest line says when the pushed ones differ.
+
 `--write` creates or updates `mapled/manifest.json`. Bindings the scan can't see (written by your AI agent, or by hand) are kept and listed; `--prune` drops them. Commit the file.
 
 ## Validate and push the manifest
@@ -193,6 +195,7 @@ Mapled doctor — Dolphin Landing
 ✓ mapled CLI           0.9.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
+✓ Live updates         app/api/mapled/release/route.ts — open tabs follow Publish (<MapledLive /> in app/layout.tsx)
 ✓ Site reads content   Last read 3m ago
 ✓ Publish webhook      Delivered 2h ago to dolphin-landing.example
 ✓ Preview on the site  Responds at https://dolphin-landing.example/api/mapled/preview
@@ -201,17 +204,65 @@ 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), 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.
+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, and its live updates — ○ «Not used» while no page mounts `<MapledLive />` or calls `watchRelease`, ✓ when the route they ask answers its `GET` with `createReleaseHandler` (`GET` is the handler, or always returns its call: every return is that call, the last statement is one, and nothing throws), ⚠ when it is missing (the tabs would poll a 404) with the file to add, when the route's `GET` isn't seen to answer with the handler (exported as `POST` they would get a 405; a `GET` that only mentions it, calls it and returns something else, or answers something else on another branch, answers without the release), or when no route can be checked against the endpoint — it is relative to the page, a full address (the tab asks it as written, and doctor can't tell it's the site's own), computed, or comes from spread props; a path from the site's root is checked against the route the App Router picks for it, dynamic and catch-all folders included, among route files with the site's page extensions (`pageExtensions` in next.config; `tsx`, `ts`, `jsx`, `js` by default) and under its `basePath`; ⚠ too when a page of either router, more specific than the route, takes that path first, when the dynamic route that answers sets `dynamicParams`, or when next.config may set `pageExtensions` or `basePath` where doctor can't read them — it reads them only as literals, once, in the object the file exports or passes to a plugin from a package. `src/app` or `src/pages` counts only when the root has no `app` or `pages`, as Next reads them. doctor reads the files, not how Next serves them at run time: middleware, rewrites, other segment config (`dynamic`, `revalidate`) and `output: "export"` aren't checked, and neither is whether a page renders the component that listens. 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.
 
-A site rendered in the visitor's browser — a React single-page app (Vite and the like), plain HTML — is checked for what it has: the package line is `@mapled/react`, Environment wants `VITE_MAPLED_KEY` and no webhook secret, and the routes and the webhook read ○ «Not needed» — such a site shows a publish on its next load and trades Mapled's preview link on the page itself. Plain HTML installs nothing: the line is `@mapled/vanilla`, read from the script tag in the pages (or from a copy of the file next to them) — ⚠ when the address has no version or an older one — and Generated types and Environment read ○: the fields are named in attributes, the delivery key sits in the page. doctor takes the framework from `mapled.json`, or works it out from `package.json` (no `package.json` and an `index.html` is plain HTML). Whatever the framework, a server key or a signing secret under a public prefix (`VITE_…`, `NEXT_PUBLIC_…`) is a ✗: it would ship to every visitor.
+A site rendered in the visitor's browser — a React single-page app (Vite and the like), plain HTML — is checked for what it has: the package line is `@mapled/react`, Environment wants `VITE_MAPLED_KEY` and no webhook secret, and the routes and the webhook read ○ «Not needed» — such a site shows a publish on its next load and trades Mapled's preview link on the page itself; Live updates reads ○ as well: `live` on `MapledProvider` or `data-mapled-live` asks Mapled directly, with no route of the site's. Plain HTML installs nothing: the line is `@mapled/vanilla`, read from the script tag in the pages (or from a copy of the file next to them) — ⚠ when the address has no version or an older one — and Generated types and Environment read ○: the fields are named in attributes, the delivery key sits in the page. doctor takes the framework from `mapled.json`, or works it out from `package.json` (no `package.json` and an `index.html` is plain HTML). Whatever the framework, a server key or a signing secret under a public prefix (`VITE_…`, `NEXT_PUBLIC_…`) is a ✗: it would ship to every visitor.
 
 Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
 
+## Read the setup report
+
+```bash
+npx @mapled/cli integration report
+```
+
+When an AI agent set the site up, Mapled keeps the run: the plan a person approved, what was applied, the agent's closing report, and the Verification checklist the server runs — the one on the run's page in Mapled. `integration report` prints the last applied run:
+
+```text
+Integration report — Dolphin Landing
+
+Setup run  Claude Code • checks failed • applied 2h ago • checked 1h ago
+Plan       “Blog with authors, a homepage and a contact form”
+
+Verification
+✓ Site reads content from Mapled        Last read 3m ago
+✗ Publish webhook works                 No deliveries since the plan was applied. Send a test ping from Integrations.
+✓ Preview route responds                Responds at /api/mapled/preview
+⚠ Field names and help texts filled in  2 of 14 fields have no help text. Editors see it under the field.
+✓ Site builds successfully              Reported by the agent
+✓ No secrets in the repository          Reported by the agent
+✓ MAPLED.md written                     Reported by the agent
+
+Collections created
+  Articles (articles)  collection • 6 fields • 12 records imported
+  Homepage (homepage)  single • 4 fields • 1 record imported
+
+Files changed
+  app/page.tsx
+  app/blog/[slug]/page.tsx
+
+Still hardcoded
+  footer copyright
+
+1 problem, 1 warning. Fix what the checks name, then `mapled integration report --verify` runs them again.
+```
+
+`--verify` runs the server checks again first, as **Run checks again** does in Mapled. A newer plan that isn't applied yet is named on its own line. The report never shows a key or a token: whatever an agent wrote into its report, anything shaped like a Mapled key is masked, and a reported preview address keeps only its page. Exit code 1 when a check is marked ✗; `--json` for scripts. A site connected without an agent has no run — `doctor` checks it from the repository.
+
+## Preview the drafts
+
+```bash
+npx @mapled/cli preview
+npx @mapled/cli preview articles hello-world
+```
+
+Prints a Preview link — the one the **Preview** button in Mapled opens: the site in draft mode, with every saved change that isn't published yet. Name a collection and a record's slug (or id) and the link lands on the record's page, the one the pushed site manifest says shows it; a collection alone opens the page that lists it, a single its page, nothing at all the home page. Mapled makes the link after checking that the site answers and mounts its preview route; it works once, for five minutes. `--open` opens it in your browser instead of printing it; `--json` prints the link with the page and when it expires.
+
 ## Options
 
 - `--api <origin>` — a Mapled API other than `https://api.mapled.io` (or set `MAPLED_API_URL`); `project link` remembers it in `mapled.json`
 - `--no-browser` — print the sign-in link instead of opening a browser
-- `--json` — machine-readable output (`doctor`, `schema diff`, `scan`, `manifest validate`, `forms list`)
+- `--json` — machine-readable output (`doctor`, `integration report`, `schema diff`, `scan`, `manifest validate`, `forms list`, `preview`)
 - `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)
 
 ## Files in the repository

package/dist/commands.d.ts

@@ -34,6 +34,15 @@ export declare function mdPull(ctx: Ctx, flags: Flags): Promise<void>;
     done by hand needs no agent for it. */
 export declare function formsCreate(ctx: Ctx, flags: Flags, words: string[]): Promise<void>;
 export declare function formsList(ctx: Ctx, flags: Flags): Promise<void>;
+/** `mapled integration report` — the Verification checklist of the last
+    applied setup run (S-42) and what the agent reported; `--verify` runs
+    the server checks again first, as "Run checks again" does. */
+export declare function integrationReport(ctx: Ctx, flags: Flags): Promise<number>;
+/** `mapled preview [<collection> [<slug>]]` — a Preview link from Mapled's
+    launcher, the one the Preview button opens: the token is Mapled's, the
+    CLI only passes it on. `--open` hands it to the browser instead of
+    printing it (the link works once). */
+export declare function preview(ctx: Ctx, flags: Flags, words: string[]): 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

@@ -11,6 +11,8 @@ import { authorize, clientKnown, exchangeCode, registerClient, revokeToken } fro
 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 { buildReport, clean, formatReport, isChecked, linkLifetime, pickRun, } from "./report.js";
+import { capabilitiesOf, findLive, liveState } from "./live.js";
 import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { scanHtml } from "./scanHtml.js";
 import { generateTypes } from "./types.js";
@@ -357,7 +359,8 @@ export async function bindingsPull(ctx, flags) {
     const local = await loadManifest(found.dir);
     if (local && !flags.force) {
         const diff = compareManifests(local.manifest, stored.manifest);
-        if (!diff.same) {
+        // capabilities a scan just recorded are as much the repository's as its bindings
+        if (!diff.same || diff.capabilitiesDiffer) {
             const parts = [];
             if (diff.onlyLocal.length > 0)
                 parts.push(`${diff.onlyLocal.length} not pushed`);
@@ -365,6 +368,8 @@ export async function bindingsPull(ctx, flags) {
                 parts.push(`${diff.changed.length} changed`);
             if (diff.onlyRemote.length > 0)
                 parts.push(`${diff.onlyRemote.length} only in Mapled`);
+            if (diff.capabilitiesDiffer)
+                parts.push("capabilities changed");
             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\`.`);
         }
     }
@@ -447,6 +452,85 @@ export async function formsList(ctx, flags) {
         ctx.out(`${f.key.padEnd(keyWidth)}  ${f.displayName.padEnd(nameWidth)}  spam protection ${f.spamProtection ? "on " : "off"}  ${submitUrl(session.conn.api, f.key)}`);
     }
 }
+/* ---- the integration report and preview (§31.2) ---- */
+/** `mapled integration report` — the Verification checklist of the last
+    applied setup run (S-42) and what the agent reported; `--verify` runs
+    the server checks again first, as "Run checks again" does. */
+export async function integrationReport(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const { runs } = await session.get("/v1/agent/runs");
+    const { shown, newer } = pickRun(runs);
+    let run = null;
+    if (shown && flags.verify) {
+        if (!isChecked(shown.status)) {
+            throw new CliError(`Nothing to check yet — the plan from ${clean(shown.clientName, 80)} hasn't been applied.`);
+        }
+        run = (await session.send("POST", `/v1/agent/runs/${encodeURIComponent(shown.id)}/verify`, {})).run;
+    }
+    else if (shown) {
+        run = (await session.get(`/v1/agent/runs/${encodeURIComponent(shown.id)}`)).run;
+    }
+    const report = buildReport({ id: found.config.project, name: session.conn.projectName }, run, newer);
+    if (flags.json)
+        ctx.out(JSON.stringify(report, null, 2));
+    else
+        for (const line of formatReport(report, useColor(ctx.env)))
+            ctx.out(line);
+    return report.checks.some((c) => c.status === "failed") ? 1 : 0;
+}
+/** `mapled preview [<collection> [<slug>]]` — a Preview link from Mapled's
+    launcher, the one the Preview button opens: the token is Mapled's, the
+    CLI only passes it on. `--open` hands it to the browser instead of
+    printing it (the link works once). */
+export async function preview(ctx, flags, words) {
+    const [collection, record, ...rest] = words;
+    if (rest.length > 0) {
+        throw new CliError("Name a collection and, optionally, one record's slug: `mapled preview articles hello-world`.", 2);
+    }
+    const { session } = await openSession(ctx, flags);
+    let answer;
+    try {
+        answer = await session.send("POST", "/v1/agent/preview", {
+            ...(collection ? { collection } : {}),
+            ...(record ? { record } : {}),
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === "NO_SITE") {
+            throw new CliError("Mapled doesn't know where the site is yet — Preview opens on it. Point the publish webhook at the deployed site (Integrations → Your site); a site rendered in the browser needs its Production domain in Project settings.");
+        }
+        throw err;
+    }
+    if (answer.status === "not_deployed") {
+        throw new CliError(`${clean(answer.origin)} doesn't answer — deploy the site publicly, then try again.`);
+    }
+    if (answer.status === "not_set_up") {
+        throw new CliError(`${clean(answer.origin)} has no preview route — mount createPreviewHandler from "@mapled/next/server" at /api/mapled/preview and redeploy.`);
+    }
+    // the link is printed as it came (masking would drop the token): printable ASCII only
+    if (typeof answer.url !== "string" || !/^https?:\/\/[!-~]+$/.test(answer.url)) {
+        throw new CliError("Mapled answered with a link this CLI can't print. Update @mapled/cli and try again.");
+    }
+    if (flags.json) {
+        ctx.out(JSON.stringify({ url: answer.url, path: answer.path, expiresAt: answer.expiresAt ?? null }, null, 2));
+        return;
+    }
+    const where = answer.path ? clean(answer.path, 500) : "the site's home page";
+    const lifetime = linkLifetime(answer.expiresAt);
+    const project = clean(session.conn.projectName, 120);
+    if (flags.open && (await ctx.openBrowser(answer.url))) {
+        ctx.out(`Opened Preview of ${where} in your browser — the drafts of ${project}.`);
+    }
+    else {
+        if (flags.open)
+            ctx.out("Couldn't open a browser — open this link yourself:");
+        ctx.out(answer.url);
+        ctx.out(`Preview of ${where} with the drafts of ${project}. The link works once${lifetime ? `, for ${lifetime}` : ""}.`);
+    }
+    if (collection && !answer.path) {
+        ctx.out("Mapled doesn't know which page shows it, so the link opens the home page. Push the site manifest (`mapled scan --write`, then `mapled bindings push`) and Preview lands on its page.");
+    }
+}
 /* ---- wave 2: the scanner ---- */
 function describeScan(result, schema) {
     const singles = new Set(schema.collections.filter((c) => c.kind === "single").map((c) => c.key));
@@ -493,6 +577,13 @@ export async function scan(ctx, flags) {
     const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
     // a plain HTML site declares its reads in attributes, not in code
     const result = framework === "plain-html" ? await scanHtml(found.dir, { schema }) : await scanRepository(found.dir, { framework, schema, ts: loadTypeScript(found.dir) });
+    // live updates (§18.8) of a Next.js site: the same reading of the code as doctor's line
+    const live = framework === "nextjs" ? liveState(await findLive(found.dir)) : null;
+    if (live)
+        result.capabilities = capabilitiesOf(live);
+    if (live && live.kind !== "served" && live.kind !== "unused") {
+        result.notes.push(`${live.listener.via} in ${live.listener.file} has no route that doctor can confirm answers it, so the manifest records that the site doesn't follow Publish — \`mapled doctor\` says what to fix.`);
+    }
     const existing = await loadManifest(found.dir);
     const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
     if (flags.json) {
@@ -507,6 +598,10 @@ export async function scan(ctx, flags) {
         for (const line of describeScan(result, schema))
             ctx.out(line);
     }
+    if (live?.kind === "served") {
+        ctx.out("");
+        ctx.out(`Live updates: ${live.listener.via} in ${live.listener.file} → ${live.path} (${live.route.file})`);
+    }
     if (result.notes.length > 0) {
         ctx.out("");
         for (const n of result.notes)
@@ -524,6 +619,8 @@ export async function scan(ctx, flags) {
             parts.push(`${merged.changed.length} changed`);
         if (merged.unchanged.length > 0)
             parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.capabilitiesChanged)
+            parts.push("capabilities updated");
         ctx.out(`Wrote ${MANIFEST_FILE} — ${manifestSummary(merged.manifest)}${parts.length > 0 && existing ? ` (${parts.join(", ")})` : ""}.${keptNote}${droppedNote}`);
         ctx.out("Next: `mapled bindings push`.");
     }
@@ -537,10 +634,12 @@ export async function scan(ctx, flags) {
         if (merged.changed.length > 0)
             parts.push(`${merged.changed.length} changed`);
         parts.push(`${merged.unchanged.length} unchanged`);
+        if (merged.capabilitiesChanged)
+            parts.push("capabilities changed");
         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) {
+        if (merged.added.length > 0 || merged.changed.length > 0 || merged.capabilitiesChanged) {
             ctx.out(`Run \`mapled scan --write\` to update ${MANIFEST_FILE}, then \`mapled bindings push\`.`);
         }
         else {
@@ -613,6 +712,8 @@ export async function doctor(ctx, flags) {
     checks.push(dr.checkCli(ctx.version, status?.sdk["@mapled/cli"]));
     checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate"), framework));
     checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview"), framework));
+    // the code is read only where the check applies: a Next.js site (or one doctor can't place)
+    checks.push(dr.checkLive(!framework || framework === "nextjs" ? await findLive(dir) : null, framework));
     if (status) {
         checks.push(dr.checkReads(status.delivery.lastReadAt));
         checks.push(dr.checkWebhook(status.webhook, { local: browser, remote: status.site }));

package/dist/doctor.d.ts

@@ -1,4 +1,5 @@
 import type { Connection } from "./credentials.js";
+import { type LiveFacts } from "./live.js";
 import { type Manifest, type Problem } from "./manifest.js";
 import type { Fetch } from "./oauth.js";
 import { type SchemaChange, type SchemaPin } from "./pin.js";
@@ -145,6 +146,10 @@ export declare function checkSecrets(facts: GitFacts): Check;
 export declare function checkSdk(pkg: PackageVersion, latest: string | undefined, name?: string): Check;
 export declare function checkCli(current: string, latest: string | undefined): Check;
 export declare function checkRoute(kind: RouteKind, found: RouteFile | null, framework: string | undefined): Check;
+/** Live updates (§18.8): whether open tabs follow Publish, and when the
+    code listens, whether a route answers it. `facts` is null when the
+    code wasn't read (a stack this check doesn't cover). */
+export declare function checkLive(facts: LiveFacts | null, framework: string | undefined): Check;
 export declare function checkReads(lastReadAt: string | null): Check;
 export declare function checkWebhook(webhook: IntegrationStatus["webhook"], site?: {
     local: boolean;

package/dist/doctor.js

@@ -3,6 +3,7 @@ import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { integrationHash } from "./integrationHash.js";
+import { fullAddress, liveState, RELEASE_ROUTE, routeFileFor } from "./live.js";
 import { compareManifests, manifestSummary, MANIFEST_FILE } from "./manifest.js";
 import { SCHEMA_FILE } from "./pin.js";
 import { splitGenerated } from "./types.js";
@@ -448,6 +449,100 @@ export function checkRoute(kind, found, framework) {
     }
     return { key, label, status: "passed", detail: found.file };
 }
+/** Live updates (§18.8): whether open tabs follow Publish, and when the
+    code listens, whether a route answers it. `facts` is null when the
+    code wasn't read (a stack this check doesn't cover). */
+export function checkLive(facts, framework) {
+    const key = "live";
+    const label = "Live updates";
+    if (framework === "react-spa") {
+        return { key, label, status: "skipped", detail: "No route needed: `live` on MapledProvider (watchRelease by key) asks Mapled directly." };
+    }
+    if (framework === "plain-html") {
+        return { key, label, status: "skipped", detail: "No route needed: data-mapled-live on the script tag (watchRelease by key) asks Mapled directly." };
+    }
+    if ((framework && framework !== "nextjs") || !facts) {
+        return { key, label, status: "skipped", detail: `No live updates check for ${framework ?? "this"} site${framework ? "s" : ""} yet.` };
+    }
+    const state = liveState(facts);
+    const who = (l) => `${l.via} in ${l.file}`;
+    const handler = 'createReleaseHandler from "@mapled/next/server"';
+    switch (state.kind) {
+        case "unused":
+            return {
+                key,
+                label,
+                status: "skipped",
+                detail: state.handlerRoute
+                    ? `Not used: ${state.handlerRoute.file} is mounted, but no page listens — add <MapledLive /> to the root layout.`
+                    : "Not used: an open tab shows a publish once it is reloaded.",
+            };
+        case "served":
+            return { key, label, status: "passed", detail: `${state.route.file} — open tabs follow Publish (${who(state.listener)})` };
+        case "no_handler":
+            return { key, label, status: "warning", detail: `${state.route.file} exists but doesn't use ${handler} — ${who(state.listener)} can't read the release there.` };
+        case "not_get":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.route.file} calls ${handler}, but doctor can't see its GET always answer with the handler's response — ${who(state.listener)} asks with GET. Export the handler as GET, or end GET by returning its call, with no other return or throw.`,
+            };
+        case "unresolved":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: state.listener.endpoint === null
+                    ? `${who(state.listener)} takes its endpoint from the code (a computed value or spread props), so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`
+                    : fullAddress(state.listener.endpoint)
+                        ? `${who(state.listener)} asks ${state.listener.endpoint}, a full address — the tab asks it as written, and doctor can't tell it's this site's own, so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`
+                        : `${who(state.listener)} asks ${state.listener.endpoint}, which isn't a path from the site's root — each page resolves it against its own address, so no route can be checked. Give the route's path, like ${RELEASE_ROUTE}.`,
+            };
+        case "config":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.file} may set pageExtensions or basePath where doctor can't read them — a value or name the code builds, an object from another file or spread in — so no route can be checked for ${who(state.listener)}. Write them as literals in the object it exports, or leave them out.`,
+            };
+        case "outside":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${who(state.listener)} asks ${state.endpoint}, outside the site's basePath ${state.basePath} — Next answers nothing there. Give it the path under the basePath: ${state.basePath}${state.endpoint === "/" ? "" : state.endpoint}.`,
+            };
+        case "taken":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${who(state.listener)} asks ${state.endpoint}, which ${state.page.file} answers, not a release route. Point the listener at a path of its own, and mount ${handler} there.`,
+            };
+        case "params":
+            return {
+                key,
+                label,
+                status: "warning",
+                detail: `${state.route.file} sets dynamicParams, so it answers only the params its code lists — doctor can't tell ${state.endpoint} is one, and ${who(state.listener)} may get a 404 there. Mount ${handler} at ${routeFileFor(state.endpoint, facts)}.`,
+            };
+        case "missing":
+            return state.endpoint === null
+                ? {
+                    key,
+                    label,
+                    status: "warning",
+                    detail: `${who(state.listener)} asks a release route the code doesn't have — mount ${handler} (at ${routeFileFor(RELEASE_ROUTE, facts)} by default).`,
+                }
+                : {
+                    key,
+                    label,
+                    status: "warning",
+                    detail: `${who(state.listener)} asks ${state.endpoint}, which has no route — mount ${handler} at ${routeFileFor(state.endpoint, facts)}.`,
+                };
+    }
+}
 export function checkReads(lastReadAt) {
     const label = "Site reads content";
     if (!lastReadAt) {
@@ -606,7 +701,7 @@ export function checkManifestFile(local, remote) {
     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) {
+    if (diff.same && !diff.capabilitiesDiffer) {
         return { key: "manifest", label, status: "passed", detail: `${MANIFEST_FILE} is pushed as manifest v${remote.version} (${manifestSummary(local.manifest)})` };
     }
     const parts = [];
@@ -616,6 +711,9 @@ export function checkManifestFile(local, remote) {
         parts.push(`${diff.changed.length} changed`);
     if (diff.onlyRemote.length > 0)
         parts.push(`${diff.onlyRemote.length} only in Mapled`);
+    // capabilities aren't in the integration hash, so this is the line that notices them
+    if (diff.capabilitiesDiffer)
+        parts.push("capabilities changed");
     return {
         key: "manifest",
         label,

package/dist/index.js

@@ -3,7 +3,7 @@ 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, formsCreate, formsList, generate, link, login, logout, manifestValidate, mdPull, scan, schemaDiff, schemaPull, } from "./commands.js";
+import { bindingsPull, bindingsPush, doctor, formsCreate, formsList, generate, integrationReport, link, login, logout, manifestValidate, mdPull, preview, 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
@@ -27,6 +27,8 @@ Usage
   mapled forms create <name> [--key <key>]            Create a form the site posts submissions to (--no-spam-protection to skip the honeypot)
   mapled forms list [--json]                          List the project's forms and where the site posts to
   mapled doctor [--json]                              Check the integration end to end
+  mapled integration report [--json] [--verify]       Show the last setup run's verification checklist and report
+  mapled preview [<collection> [<slug>]] [--open]     Print a one-time Preview link that shows the drafts on the site
 
 Options
   --version, -v   Print the version
@@ -78,7 +80,8 @@ async function main(argv) {
         version: version(),
         credentialsFile: credentialsPath(),
     };
-    switch (`${group} ${sub ?? ""}`.trim()) {
+    // `preview` takes the record it opens as words of its own
+    switch (group === "preview" ? group : `${group} ${sub ?? ""}`.trim()) {
         case "auth login":
             await login(ctx, flags);
             return 0;
@@ -118,6 +121,11 @@ async function main(argv) {
             return 0;
         case "doctor":
             return doctor(ctx, flags);
+        case "integration report":
+            return integrationReport(ctx, flags);
+        case "preview":
+            await preview(ctx, flags, words.slice(1));
+            return 0;
         case "auth":
         case "project":
         case "types":
@@ -126,6 +134,7 @@ async function main(argv) {
         case "bindings":
         case "md":
         case "forms":
+        case "integration":
             console.log(HELP);
             return 2;
         default:

package/dist/live.d.ts

@@ -0,0 +1,156 @@
+/** Live updates (§18.8) as the site's code shows them. A Next.js site
+    follows Publish in open tabs with two pieces: `<MapledLive />` from
+    "@mapled/next/live" (or `watchRelease` from "@mapled/next") asks a
+    route of the site every few seconds, and that route answers with
+    `createReleaseHandler` from "@mapled/next/server". A listener without
+    the route polls a 404 forever and nothing says so — `mapled doctor`
+    reads both and says which is missing, and `mapled scan` records the
+    result in the manifest (`capabilities.realtime`, `releaseRoute`) so
+    MAPLED.md can tell the next agent. The code is read with the scanner's
+    tokenizer: comments and strings never count as a use, and neither
+    does an imported name the file binds again. */
+/** Where `<MapledLive />` and `watchRelease` ask when no endpoint is given. */
+export declare const RELEASE_ROUTE = "/api/mapled/release";
+export type LiveListener = {
+    file: string;
+    via: "<MapledLive />" | "watchRelease";
+    /** the endpoint as the code writes it; null when the code decides it —
+        a computed value, or spread props or options that may carry one */
+    endpoint: string | null;
+};
+/** An App Router route handler file and the path it answers. `handler`:
+    "GET" when the route's exported GET is seen to answer with
+    `createReleaseHandler`, "other" when the file calls it but GET isn't
+    (exported as POST or not at all — the tab's GET gets a 405 — or a GET
+    whose answer isn't the handler's), null when it doesn't call it.
+    `params`: the file sets `dynamicParams` — a dynamic route then answers
+    only the params its code lists. */
+export type RouteFile = {
+    file: string;
+    path: string;
+    handler: RouteHandler;
+    params?: true;
+};
+export type RouteHandler = "GET" | "other" | null;
+/** A page file and the path it answers: an App Router `page.<ext>`, or any
+    Pages Router file (`pages/api/…` included). It takes part in the match
+    as Next makes it — a page more specific than a route takes the path. */
+export type PageFile = {
+    file: string;
+    path: string;
+};
+/** `routeExtension`: what a route file the site lacks would end in — the
+    site's page extension, `ts` by default. `appDir`: the App Router folder
+    Next reads, when the site has one. `basePath`: what every path of the
+    site starts with (next.config). `config`: the next.config file, when it
+    may set `pageExtensions` or `basePath` where the reading can't follow —
+    then no route can be checked. */
+export type LiveFacts = {
+    listeners: LiveListener[];
+    routes: RouteFile[];
+    pages?: PageFile[];
+    routeExtension?: string;
+    appDir?: string;
+    basePath?: string;
+    config?: string;
+};
+export type LiveState = {
+    kind: "unused";
+    handlerRoute: RouteFile | null;
+} | {
+    kind: "served";
+    listener: LiveListener;
+    route: RouteFile;
+    path: string;
+} | {
+    kind: "missing";
+    listener: LiveListener;
+    endpoint: string | null;
+} | {
+    kind: "unresolved";
+    listener: LiveListener;
+} | {
+    kind: "no_handler";
+    listener: LiveListener;
+    route: RouteFile;
+} | {
+    kind: "not_get";
+    listener: LiveListener;
+    route: RouteFile;
+} | {
+    kind: "config";
+    listener: LiveListener;
+    file: string;
+} | {
+    kind: "outside";
+    listener: LiveListener;
+    endpoint: string;
+    basePath: string;
+} | {
+    kind: "taken";
+    listener: LiveListener;
+    page: PageFile;
+    endpoint: string;
+} | {
+    kind: "params";
+    listener: LiveListener;
+    route: RouteFile;
+    endpoint: string;
+};
+/** What the manifest records (§21.2). */
+export type Capabilities = {
+    realtime?: boolean;
+    releaseRoute?: string;
+};
+/** The extensions a route file may have when next.config doesn't set `pageExtensions`. */
+export declare const PAGE_EXTENSIONS: string[];
+/** The listeners one file mounts and, for a route file, whether its GET
+    serves the release. An imported name the file binds again — a
+    parameter, a declaration, destructuring — may not be the import where
+    it's used, and the reading can't tell where: none of its uses count.
+    A namespace's name the same: its members count only where `ns` itself
+    is the import. */
+export declare function liveInFile(file: string, text: string): {
+    listeners: LiveListener[];
+    handler: RouteHandler;
+    params: boolean;
+};
+/** The route files of the App Router with the path each answers. */
+export declare function routeFileOf(file: string, extensions?: string[]): string | null;
+/** The page files of both routers with the path each answers: an App
+    Router `page.<ext>`, and any Pages Router file but `_app`, `_document`
+    and `_error`, with the longest page extension its name ends in taken
+    off, as Next does, and `index` naming its folder. */
+export declare function pageFileOf(file: string, extensions?: string[]): string | null;
+/** What next.config decides about where a file answers: the page
+    extensions of route and page files, and the basePath every path of the
+    site starts with. */
+export type NextConfig = {
+    pageExtensions: string[];
+    basePath: string;
+};
+/** next.config's `pageExtensions` and `basePath`, read only where the file
+    writes them out: a literal, once, directly in the object it exports —
+    `module.exports = {…}`, `export default nextConfig`, or passed to a
+    plugin: `withMDX(nextConfig)`. Null when it may set either anywhere
+    else: a value or a name the code builds (`["page" + "Extensions"]`, an
+    escaped identifier, `Object.assign`, `defineProperty`, a prototype
+    set by `setPrototypeOf` or `__proto__`, a member in a loop's head), an object from
+    another file or spread in, a member (`config.basePath = …`), a nested
+    object, any other mention — then no route can be checked. */
+export declare function nextConfigOf(config: string | null): NextConfig | null;
+export declare function findLive(dir: string, maxFiles?: number): Promise<LiveFacts>;
+/** Whether a literal endpoint names its own origin — `https://…`, `//host/…`
+    — which the code doesn't show to be the site's: `watchRelease` fetches it
+    as written, and no route file of this site is known to answer it. */
+export declare const fullAddress: (endpoint: string) => boolean;
+/** Whether every listener has a route that answers it. The first one
+    that doesn't is the one to name. */
+export declare function liveState(facts: LiveFacts): LiveState;
+/** What `mapled scan` writes into the manifest: a listener nothing answers
+    isn't listening; the route is the path the tab asks, not a dynamic route's pattern. */
+export declare function capabilitiesOf(state: LiveState): Capabilities;
+/** Where a route answering `endpoint` goes: in the App Router folder Next
+    reads — without one, under `src/app` when the site keeps its code there
+    — and without the basePath, which Next adds itself. */
+export declare function routeFileFor(endpoint: string, facts: LiveFacts): string;