@mapled/cli 0.10.0 → 0.12.0

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

@@ -1,5 +1,5 @@
 import type * as TS from "typescript";
-import { type Manifest, type ManifestBinding, type ManifestPage } from "./manifest.js";
+import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestPage } from "./manifest.js";
 import type { Schema } from "./schema.js";
 /** `mapled scan` (§19.5, §21.4 — the standalone scanner of wave 2): reads
     the site's source and writes down what the code reads from Mapled —
@@ -37,22 +37,40 @@ export type ScanResult = {
     pages: ManifestPage[];
     bindings: ManifestBinding[];
     notes: string[];
+    /** what the code says the site can do (live updates of a Next.js site); undefined keeps the manifest's */
+    capabilities?: ManifestCapabilities;
 };
 export declare const SDK_METHODS: Set<string>;
 /** The repository's TypeScript, when it has one; the CLI ships none. */
 export declare function loadTypeScript(dir: string): TypeScriptModule | null;
+export declare function listFiles(dir: string, max: number): Promise<{
+    files: string[];
+    truncated: boolean;
+}>;
 export type RouteMap = {
     pages: Map<string, string>;
     layouts: Map<string, string>;
 };
+/** Next.js App Router segments: groups and slots vanish, params keep
+    the [param] form the manifest uses. */
+export declare function appRoute(segments: string[]): string | null;
 export declare function detectRoutes(files: string[], framework: string | null): RouteMap;
+/** `nl`: a line break comes before the token — a `return` followed by one returns nothing. */
+/** `nl`: a line break stands before the token; `escaped`: a string written
+    with a backslash escape, or an identifier with a `\u` escape in its
+    name; `unclosed`: a quoted string a line break (or the end) cut off
+    before its closing quote — JSX lets an attribute run on. */
 export type Token = {
     kind: "ident" | "string" | "punct";
     value: string;
+    nl?: true;
+    escaped?: true;
+    unclosed?: true;
 };
 /** JavaScript tokens: identifiers, string literals and punctuation, with
     comments and template bodies dropped. A regex literal after an
-    operator is skipped; JSX text is read as code, so an apostrophe in
+    operator is skipped — only one that closes on its line, and never the
+    `/>` after a JSX attribute's `}`; JSX text is read as code, so an apostrophe in
     prose can swallow a stretch — a false negative, never a crash. */
 export declare function tokenize(text: string): Token[];
 export declare function routeKey(route: string): string;
@@ -65,6 +83,8 @@ export type MergeResult = {
     /** Bindings the scan didn't produce: kept (or dropped with prune). */
     kept: string[];
     dropped: string[];
+    /** the scan changed what an existing manifest says the site can do */
+    capabilitiesChanged: boolean;
 };
 /** The scan's bindings replace the ones with the same key; bindings the
     scanner can't see (an agent's, hand-written) stay unless pruned. */