@mapled/cli 0.10.0 → 0.11.0

package/README.md

@@ -207,11 +207,59 @@ A site rendered in the visitor's browser — a React single-page app (Vite and t
 
 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,7 @@ 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 { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { scanHtml } from "./scanHtml.js";
 import { generateTypes } from "./types.js";
@@ -447,6 +448,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));

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

@@ -0,0 +1,127 @@
+import { type Check } from "./doctor.js";
+/** `mapled integration report` (§29.9, §31.2): the last setup run Mapled
+    holds for the project with its Verification checklist — the lines,
+    statuses and fix hints of S-42 — and what the agent reported. Nearly
+    every string here was typed by an agent or a member: it is cleaned of
+    control characters, and anything shaped like a Mapled key or token is
+    masked before it reaches the terminal or the JSON (§36.12 — the report
+    carries no secret, whatever an agent wrote into it). */
+export type RunStatus = "awaiting_approval" | "approved" | "rejected" | "applying" | "verifying" | "checks_failed" | "completed" | "completed_with_warnings" | "failed";
+/** A run as `GET /v1/agent/runs` lists it. */
+export type RunSummary = {
+    id: string;
+    clientName: string;
+    status: RunStatus;
+    summary: string;
+    createdAt: string;
+    appliedAt: string | null;
+    verifiedAt: string | null;
+    completedAt: string | null;
+};
+/** A run as `GET /v1/agent/runs/:id` shows it. */
+export type RunDetail = RunSummary & {
+    result: {
+        collections?: {
+            key: string;
+            displayName: string;
+            kind: string;
+            fieldKeys?: string[];
+            recordsCreated?: number;
+        }[];
+        warnings?: string[];
+        report?: {
+            filesChanged?: string[];
+            stillHardcoded?: string[];
+            warnings?: string[];
+            previewUrl?: string | null;
+        };
+        checks?: Check[];
+    } | null;
+};
+export type IntegrationReport = {
+    project: {
+        id: string;
+        name: string;
+    };
+    run: {
+        id: string;
+        client: string;
+        status: RunStatus;
+        summary: string;
+        createdAt: string;
+        appliedAt: string | null;
+        verifiedAt: string | null;
+    } | null;
+    /** A later plan than the one reported, not applied (yet). */
+    newer: {
+        id: string;
+        client: string;
+        status: RunStatus;
+        createdAt: string;
+    } | null;
+    checks: Check[];
+    collections: {
+        key: string;
+        displayName: string;
+        kind: string;
+        fields: number;
+        records: number;
+    }[];
+    filesChanged: string[];
+    stillHardcoded: string[];
+    warnings: string[];
+    previewUrl: string | null;
+};
+export declare const isChecked: (status: RunStatus) => boolean;
+/** Mapled's keys and tokens, with the length and alphabet of the random
+    part Mapled issues: delivery and server keys — 16 bytes in hex
+    (`lib/deliveryKeys.ts`); agent, OAuth and code tokens — 32 bytes in
+    base64url (`generateToken`); preview links, draft sessions and the
+    webhook secret — 24 bytes in hex. The webhook secret's prefix is the
+    one of Standard Webhooks, and other issuers (Polar, Svix) write it
+    before base64 of 24 bytes or more, `+`, `/` and the `=` padding
+    included: the last kind, read up to its shortest length, so a site's
+    own secret doesn't show either. Mapled doesn't issue that one, so
+    behind a prefix written wholly in look-alikes it reads as text
+    (`keyLike`). */
+export declare const KEYS: readonly (readonly [prefix: string, length: number, alphabet: "hex" | "base64url" | "base64"])[];
+/** One line of text fit for a terminal: no control, blank-looking or
+    invisible characters, nothing that reads as a Mapled key. */
+export declare function clean(text: unknown, max?: number): string;
+/** The page an agent reported as its preview, without what may carry a
+    credential: no query, no fragment, no user info. The path is shown
+    decoded, so a key written in percent escapes is masked like any other;
+    a path that doesn't decode cleanly — malformed, or still escaped after
+    one decoding (encoded twice) — is dropped, and only the origin shows. */
+export declare function reportedPage(url: unknown): string | null;
+/** The run to report: the one applied last (an older plan can be applied
+    after a newer one); before any was applied, the newest there is. The
+    newer plan is the newest one proposed after it and not applied. */
+export declare function pickRun(runs: RunSummary[]): {
+    shown: RunSummary | null;
+    newer: RunSummary | null;
+};
+export declare function buildReport(project: {
+    id: string;
+    name: string;
+}, run: RunDetail | null, newer: RunSummary | null): IntegrationReport;
+/** The closing line: what to do next. */
+export declare function reportSummary(report: IntegrationReport): string;
+export declare function formatReport(report: IntegrationReport, color: boolean): string[];
+/** What `POST /v1/agent/preview` answers. */
+export type PreviewAnswer = {
+    status: "ok";
+    url: string;
+    expiresAt?: string;
+    path: string | null;
+} | {
+    status: "not_deployed";
+    origin: string;
+    path: string | null;
+} | {
+    status: "not_set_up";
+    origin: string;
+    path: string | null;
+};
+/** "5 minutes" until the link stops working, or null when unknown. */
+export declare function linkLifetime(expiresAt: string | undefined, now?: number): string | null;

package/dist/report.js

@@ -0,0 +1,425 @@
+import { ago } from "./doctor.js";
+import { plural } from "./manifest.js";
+import { GLYPH, paint } from "./output.js";
+const STATUS_LABEL = {
+    awaiting_approval: "waiting for approval",
+    approved: "approved, not applied yet",
+    rejected: "rejected",
+    applying: "applying",
+    verifying: "applied, checks pending",
+    checks_failed: "checks failed",
+    completed: "completed",
+    completed_with_warnings: "completed with warnings",
+    failed: "failed",
+};
+const label = (status) => STATUS_LABEL[status] ?? clean(status, 40);
+/** Applied runs: the ones the server checks (S-42). */
+const CHECKED = ["verifying", "checks_failed", "completed", "completed_with_warnings"];
+export const isChecked = (status) => CHECKED.includes(status);
+/** Mapled's keys and tokens, with the length and alphabet of the random
+    part Mapled issues: delivery and server keys — 16 bytes in hex
+    (`lib/deliveryKeys.ts`); agent, OAuth and code tokens — 32 bytes in
+    base64url (`generateToken`); preview links, draft sessions and the
+    webhook secret — 24 bytes in hex. The webhook secret's prefix is the
+    one of Standard Webhooks, and other issuers (Polar, Svix) write it
+    before base64 of 24 bytes or more, `+`, `/` and the `=` padding
+    included: the last kind, read up to its shortest length, so a site's
+    own secret doesn't show either. Mapled doesn't issue that one, so
+    behind a prefix written wholly in look-alikes it reads as text
+    (`keyLike`). */
+export const KEYS = [
+    ["mk_live_", 32, "hex"],
+    ["msk_live_", 32, "hex"],
+    ["mcp_live_", 43, "base64url"],
+    ["mcp_oauth_", 43, "base64url"],
+    ["mcp_refresh_", 43, "base64url"],
+    ["mcp_code_", 43, "base64url"],
+    ["mpv_", 48, "hex"],
+    ["mps_", 48, "hex"],
+    ["whsec_", 48, "hex"],
+    ["whsec_", 32, "base64"],
+];
+/** A prefix, read with a blank allowed between any two of its characters. */
+const PREFIX_SOURCE = [...new Set(KEYS.map(([prefix]) => prefix))].map((prefix) => [...prefix].join(" ?")).join("|");
+const PREFIX = new RegExp(PREFIX_SOURCE, "g");
+const PREFIX_HERE = new RegExp(PREFIX_SOURCE, "y");
+/** The characters of a random part: hex and base64url, and base64 with its `+`, `/` and `=`. */
+const KEY_CHAR = /[a-z0-9_-]/;
+const BASE64_CHAR = /[a-z0-9_+/=-]/;
+/** Code points a terminal draws as a blank or a line break: every control
+    character (C0, DEL, C1 — an escape sequence could rewrite the screen),
+    every Unicode space and line or paragraph separator, and the braille
+    blank. Each becomes one ordinary space: the report is one line. */
+const BLANK = /[\p{Cc}\p{White_Space}\u2800]/u;
+/** Code points a terminal draws as nothing: every format character (Cf —
+    bidirectional overrides and isolates reorder what is shown; the soft
+    hyphen, zero-width and invisible-operator characters hide inside a word),
+    every default-ignorable one (variation selectors, the combining grapheme
+    joiner, Hangul fillers, tags), unassigned code points and lone
+    surrogates. A key split by one would still read whole, so they go. */
+const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cn}\p{Cs}]/u;
+/** One line of text fit for a terminal: no control, blank-looking or
+    invisible characters, nothing that reads as a Mapled key. */
+export function clean(text, max = 300) {
+    let out = "";
+    for (const ch of String(text ?? "")) {
+        if (BLANK.test(ch))
+            out += " ";
+        else if (!INVISIBLE.test(ch))
+            out += ch;
+    }
+    const shown = [...maskKeys(out.replace(/ {2,}/g, " ").trim())];
+    return shown.length > max ? `${shown.slice(0, max - 1).join("")}…` : shown.join("");
+}
+/** Stand-ins for a character from outside ASCII that no compatibility form
+    turns into ASCII. A letter or digit of another script (Cyrillic `ѕ`,
+    Greek `ο`, Armenian `օ`) can pass for a letter or digit; a dash, a low
+    line, a modifier or a math symbol (`‐`, `ˍ`, `∨`) for any character of
+    a key. Neither stand-in can come from the line itself: `clean` has
+    turned every control character into a blank. */
+const LETTERLIKE = String.fromCharCode(1);
+const STROKELIKE = String.fromCharCode(2);
+const STROKE = /[\p{Pd}\p{Pc}\p{Sm}\p{Sk}\p{Lm}\u2017]/u;
+/** What a reader takes a character for: its compatibility form (a
+    fullwidth letter is the letter), without accents and other marks, in
+    lower case, or a stand-in when that isn't ASCII. A mark alone reads as
+    nothing; other characters (`。`, an emoji) read as themselves. */
+const skeletonOf = (ch) => {
+    if (ch === " ")
+        return " ";
+    const read = ch.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
+    if (/^[!-~]*$/.test(read))
+        return read;
+    if (STROKE.test(ch))
+        return STROKELIKE;
+    return /[\p{L}\p{N}]/u.test(ch) ? LETTERLIKE : read;
+};
+/** ASCII characters that pass for one of a prefix: 1, | and I (read in
+    lower case) for l, 0 for o, a hyphen for `_`. */
+const TWINS = { l: "1|i", o: "0", _: "-" };
+/** A prefix read with look-alikes: each letter may be itself, its ASCII
+    twin or a stand-in; `_` may be a hyphen or a stroke, never a letter; a
+    blank may stand between any two of its characters, as in `PREFIX`. */
+const likeSource = (prefix) => [...prefix].map((c) => (c === "_" ? `[${STROKELIKE}_-]` : `[${c}${TWINS[c] ?? ""}${LETTERLIKE}${STROKELIKE}]`)).join(" ?");
+const LIKE_SOURCE = [...new Set(KEYS.map(([prefix]) => prefix))].map((prefix) => `(?:${likeSource(prefix)})`).join("|");
+const LIKE_PREFIX = new RegExp(LIKE_SOURCE, "g");
+const LIKE_HERE = new RegExp(LIKE_SOURCE, "y");
+/** Each kind's prefix on its own, in the order of `KEYS`: a stand-in
+    passes for several letters, so one prefix written in them can pass
+    for more than one kind (`мсрˍӏіѵеˍ` for `msk_live_` and `mcp_live_`).
+    Each kind is tried, and the longest key read is masked. */
+const LIKE_KIND = KEYS.map(([prefix]) => new RegExp(likeSource(prefix), "y"));
+const LIKE_CHAR = new RegExp(`[a-z0-9_${LETTERLIKE}${STROKELIKE}-]`);
+const LIKE_BASE64_CHAR = new RegExp(`[a-z0-9_+/=${LETTERLIKE}${STROKELIKE}-]`);
+/** A random part read as the hex Mapled issues: digits and `a`–`f`, or a letter of another script drawn like one; blanks between pieces. */
+const HEX_READ = new RegExp(`^[0-9a-f ${LETTERLIKE}]*$`);
+/** Whether a key read with look-alikes is a key, not text of another
+    script. `random` is its random part as long as Mapled issues it — what
+    is glued on after that counts for nothing — and both tests count
+    characters, so a blank anywhere in the key changes nothing:
+    - a random part with more dashes and low lines than letters and
+      digits is not a key (`что-либо ------ see`) — Mapled's are nearly
+      all letters and digits;
+    - one with more letters of another script than ASCII letters and
+      digits is text in that script (`mpv — ещё не заполнено …`);
+    - so is a prefix without one ASCII letter or digit (`что-`, `тьи —`),
+      unless the random part is one Mapled could issue: a hex one without
+      an ASCII letter past `f` (`Статьи — see the app page …` has one), a
+      base64url one without a letter of another script. Digits or none:
+      a token may be letters only, so `что-либо — see …` followed by as
+      many ASCII letters as a token has is masked with it. The base64 of
+      another issuer's webhook secret isn't one Mapled issues: behind such
+      a prefix it reads as text, or `Статьи — see …` would be a secret. */
+const STROKES_NOT = new RegExp(`[^${STROKELIKE}_-]`, "g");
+function keyLike(prefix, random, alphabet) {
+    const ascii = random.match(/[a-z0-9]/g)?.length ?? 0;
+    const foreign = random.split(LETTERLIKE).length - 1;
+    const strokes = random.replace(STROKES_NOT, "").length;
+    if (strokes > ascii + foreign || foreign > ascii)
+        return false;
+    if (/[a-z0-9]/.test(prefix))
+        return true;
+    if (alphabet === "hex")
+        return !/[g-z]/.test(random);
+    return alphabet === "base64url" && foreign === 0;
+}
+const reading = (skeleton, char, here) => {
+    const ends = new Int32Array(skeleton.length + 1);
+    ends[skeleton.length] = skeleton.length;
+    for (let i = skeleton.length - 1; i >= 0; i--)
+        ends[i] = char.test(skeleton[i]) ? ends[i + 1] : i;
+    return { ends, here };
+};
+/** Masks every Mapled key a reader could take off the line (§36.12).
+    Matching runs on what the characters read as, so case, fullwidth forms
+    and marks don't hide a key; a blank inside the prefix doesn't either,
+    and a key wrapped or split by blanks is read on across them while its
+    pieces add up to the length Mapled issues. A key written with look-
+    alikes — another script's letters, 1 for l, 0 for o, a dash for `_` —
+    is read the same way, blanks and pieces included, when it is as long
+    as Mapled issues it and `keyLike` doesn't take it for text of another
+    script. Each key, with all the pieces, becomes `[redacted]`. A key an
+    agent re-encodes (base64, reversed, spelled out, broken up by
+    punctuation) is not something a reader takes off the line, and no mask
+    can see it. */
+function maskKeys(line) {
+    const chars = [...line];
+    let skeleton = "";
+    /** The character behind each UTF-16 unit of the skeleton — matching
+        indexes units, and an emoji reads as two. */
+    const owner = [];
+    chars.forEach((ch, i) => {
+        const read = skeletonOf(ch);
+        skeleton += read;
+        for (let unit = 0; unit < read.length; unit++)
+            owner.push(i);
+    });
+    const hidden = new Set();
+    const hide = (from, to) => {
+        let last = owner[to - 1];
+        while (last + 1 < chars.length && skeletonOf(chars[last + 1]) === "")
+            last++;
+        for (let i = owner[from]; i <= last; i++)
+            hidden.add(i);
+    };
+    /** Each alphabet's reading, found once per line: base64 reads on over
+        `+`, `/` and `=`. Where Mapled's own hex secret is read whole, another
+        issuer's base64 after the same prefix isn't, so `/x` after it in a
+        path stays; anywhere else the longest reading is masked. */
+    const plain = { narrow: reading(skeleton, KEY_CHAR, PREFIX_HERE), base64: reading(skeleton, BASE64_CHAR, PREFIX_HERE) };
+    PREFIX.lastIndex = 0;
+    for (let match = PREFIX.exec(skeleton); match; match = PREFIX.exec(skeleton)) {
+        const prefix = match[0].replaceAll(" ", "");
+        let longest = PREFIX.lastIndex;
+        for (const [p, length, alphabet] of KEYS) {
+            if (p !== prefix)
+                continue;
+            const { end, issued } = keyEnd(skeleton, PREFIX.lastIndex, length, alphabet === "base64" ? plain.base64 : plain.narrow);
+            longest = Math.max(longest, end);
+            if (issued !== null && alphabet === "hex" && HEX_READ.test(skeleton.slice(PREFIX.lastIndex, issued)))
+                break;
+        }
+        if (longest === PREFIX.lastIndex)
+            continue;
+        hide(match.index, longest);
+        PREFIX.lastIndex = longest;
+    }
+    const like = { narrow: reading(skeleton, LIKE_CHAR, LIKE_HERE), base64: reading(skeleton, LIKE_BASE64_CHAR, LIKE_HERE) };
+    LIKE_PREFIX.lastIndex = 0;
+    for (let match = LIKE_PREFIX.exec(skeleton); match; match = LIKE_PREFIX.exec(skeleton)) {
+        let longest = 0;
+        let other = 0;
+        let hex = false;
+        for (const [kind, [, length, alphabet]] of KEYS.entries()) {
+            const here = LIKE_KIND[kind];
+            here.lastIndex = match.index;
+            if (!here.test(skeleton))
+                continue;
+            const { end, issued } = keyEnd(skeleton, here.lastIndex, length, alphabet === "base64" ? like.base64 : like.narrow);
+            const random = issued === null ? "" : skeleton.slice(here.lastIndex, issued);
+            if (issued === null || !keyLike(skeleton.slice(match.index, here.lastIndex), random, alphabet))
+                continue;
+            if (alphabet === "base64")
+                other = Math.max(other, end);
+            else
+                longest = Math.max(longest, end);
+            hex ||= alphabet === "hex" && HEX_READ.test(random);
+        }
+        if (!hex)
+            longest = Math.max(longest, other);
+        if (longest > 0)
+            hide(match.index, longest);
+        LIKE_PREFIX.lastIndex = Math.max(longest, match.index + 1);
+    }
+    let out = "";
+    chars.forEach((ch, i) => {
+        if (!hidden.has(i))
+            out += ch;
+        else if (!hidden.has(i - 1))
+            out += "[redacted]";
+    });
+    return out;
+}
+/** Where the random part that starts at `start` ends (`start` itself when
+    there is none), and where it reaches the length Mapled issues (`null`
+    when it doesn't). It runs over key characters; when it stops short of
+    `length` at a blank, the pieces after it belong to the key if they
+    complete it — a piece that starts a key of its own doesn't. */
+function keyEnd(skeleton, start, length, reading) {
+    let end = reading.ends[start];
+    let read = end - start;
+    let issued = read >= length ? start + length : null;
+    for (let at = end; read < length;) {
+        let next = at;
+        while (skeleton[next] === " ")
+            next++;
+        if (next === at)
+            break;
+        reading.here.lastIndex = next;
+        const to = reading.ends[next];
+        if (to === next || reading.here.test(skeleton))
+            break;
+        if (read + (to - next) >= length) {
+            issued = next + (length - read);
+            end = to;
+        }
+        read += to - next;
+        at = to;
+    }
+    return { end, issued };
+}
+/** The page an agent reported as its preview, without what may carry a
+    credential: no query, no fragment, no user info. The path is shown
+    decoded, so a key written in percent escapes is masked like any other;
+    a path that doesn't decode cleanly — malformed, or still escaped after
+    one decoding (encoded twice) — is dropped, and only the origin shows. */
+export function reportedPage(url) {
+    if (typeof url !== "string")
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        return null;
+    const path = decodedPath(parsed.pathname);
+    return clean(path === null ? parsed.origin : `${parsed.origin}${path}`, 300) || null;
+}
+function decodedPath(path) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(path);
+    }
+    catch {
+        return null;
+    }
+    return /%[0-9a-f]{2}/i.test(decoded) ? null : decoded;
+}
+/** The run to report: the one applied last (an older plan can be applied
+    after a newer one); before any was applied, the newest there is. The
+    newer plan is the newest one proposed after it and not applied. */
+export function pickRun(runs) {
+    const appliedAt = (r) => Date.parse(r.appliedAt ?? r.createdAt);
+    const shown = runs.filter((r) => isChecked(r.status)).reduce((last, r) => (last && !(appliedAt(r) > appliedAt(last)) ? last : r), null) ??
+        runs[0] ??
+        null;
+    const newer = shown ? (runs.slice(0, runs.indexOf(shown)).find((r) => !isChecked(r.status)) ?? null) : null;
+    return { shown, newer };
+}
+const STATUSES = new Set(["passed", "failed", "warning", "skipped"]);
+const lines = (list, max = 50) => (Array.isArray(list) ? list : []).slice(0, max).map((s) => clean(s)).filter((s) => s.length > 0);
+export function buildReport(project, run, newer) {
+    const result = run?.result ?? null;
+    const report = result?.report;
+    return {
+        project: { id: clean(project.id, 64), name: clean(project.name, 120) },
+        run: run
+            ? {
+                id: clean(run.id, 64),
+                client: clean(run.clientName, 80),
+                status: run.status,
+                summary: clean(run.summary, 500),
+                createdAt: run.createdAt,
+                appliedAt: run.appliedAt,
+                verifiedAt: run.verifiedAt,
+            }
+            : null,
+        newer: newer ? { id: clean(newer.id, 64), client: clean(newer.clientName, 80), status: newer.status, createdAt: newer.createdAt } : null,
+        checks: (result?.checks ?? [])
+            .filter((c) => STATUSES.has(c.status))
+            .map((c) => ({ key: clean(c.key, 40), label: clean(c.label, 80), status: c.status, detail: clean(c.detail, 500) })),
+        collections: (result?.collections ?? []).map((c) => ({
+            key: clean(c.key, 80),
+            displayName: clean(c.displayName, 120),
+            kind: clean(c.kind, 20),
+            fields: Array.isArray(c.fieldKeys) ? c.fieldKeys.length : 0,
+            records: typeof c.recordsCreated === "number" ? c.recordsCreated : 0,
+        })),
+        filesChanged: lines(report?.filesChanged),
+        stillHardcoded: lines(report?.stillHardcoded),
+        warnings: [...lines(result?.warnings), ...lines(report?.warnings, 20)],
+        previewUrl: reportedPage(report?.previewUrl),
+    };
+}
+function runLine(r) {
+    const parts = [r.client, label(r.status)];
+    if (r.appliedAt)
+        parts.push(`applied ${ago(r.appliedAt)}`);
+    else
+        parts.push(`proposed ${ago(r.createdAt)}`);
+    if (r.verifiedAt)
+        parts.push(`checked ${ago(r.verifiedAt)}`);
+    return parts.join(" • ");
+}
+/** The closing line: what to do next. */
+export function reportSummary(report) {
+    const failed = report.checks.filter((c) => c.status === "failed").length;
+    const warned = report.checks.filter((c) => c.status === "warning").length;
+    if (!report.run)
+        return "";
+    if (report.checks.length === 0) {
+        return isChecked(report.run.status)
+            ? "The checks haven't run yet — `mapled integration report --verify` runs them."
+            : "Mapled checks the integration once the plan is applied.";
+    }
+    if (failed === 0 && warned === 0)
+        return "Integration verified. Your site is fully connected.";
+    const parts = [];
+    if (failed > 0)
+        parts.push(plural(failed, "problem"));
+    if (warned > 0)
+        parts.push(plural(warned, "warning"));
+    return `${parts.join(", ")}.${failed > 0 ? " Fix what the checks name, then `mapled integration report --verify` runs them again." : ""}`;
+}
+export function formatReport(report, color) {
+    const out = [`Integration report — ${report.project.name}`, ""];
+    if (!report.run) {
+        out.push(`No AI setup run in ${report.project.name} yet — the report comes from one. \`mapled doctor\` checks the integration from this repository.`);
+        return out;
+    }
+    out.push(`Setup run  ${runLine(report.run)}`);
+    if (report.run.summary)
+        out.push(`Plan       “${report.run.summary}”`);
+    if (report.newer) {
+        out.push(`Newer      ${report.newer.client} • ${label(report.newer.status)} • proposed ${ago(report.newer.createdAt)} — the report is of the last applied run`);
+    }
+    if (report.checks.length > 0) {
+        out.push("", "Verification");
+        const width = report.checks.reduce((w, c) => Math.max(w, c.label.length), 0);
+        for (const c of report.checks)
+            out.push(`${paint(c.status, GLYPH[c.status], color)} ${c.label.padEnd(width)}  ${c.detail}`);
+    }
+    if (report.collections.length > 0) {
+        out.push("", "Collections created");
+        const width = report.collections.reduce((w, c) => Math.max(w, `${c.displayName} (${c.key})`.length), 0);
+        for (const c of report.collections) {
+            out.push(`  ${`${c.displayName} (${c.key})`.padEnd(width)}  ${c.kind} • ${plural(c.fields, "field")} • ${plural(c.records, "record")} imported`);
+        }
+    }
+    const list = (title, items, glyph) => {
+        if (items.length === 0)
+            return;
+        out.push("", title);
+        for (const item of items)
+            out.push(glyph ? `${paint("warning", glyph, color)} ${item}` : `  ${item}`);
+    };
+    list("Files changed", report.filesChanged);
+    list("Still hardcoded", report.stillHardcoded);
+    list("Warnings", report.warnings, GLYPH.warning);
+    if (report.previewUrl)
+        out.push("", `Preview reported by the agent: ${report.previewUrl}`);
+    out.push("", reportSummary(report));
+    return out;
+}
+/** "5 minutes" until the link stops working, or null when unknown. */
+export function linkLifetime(expiresAt, now = Date.now()) {
+    if (!expiresAt)
+        return null;
+    const ms = new Date(expiresAt).getTime() - now;
+    if (!Number.isFinite(ms) || ms <= 0)
+        return null;
+    return plural(Math.max(1, Math.round(ms / 60_000)), "minute");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/cli",
-  "version": "0.10.0",
-  "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content, create forms and check the site's integration.",
+  "version": "0.11.0",
+  "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content, create forms, preview drafts and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",
   "keywords": [