@mapled/cli 0.9.0 → 0.11.0

package/README.md

@@ -97,7 +97,7 @@ npx @mapled/cli scan
 npx @mapled/cli scan --write
 ```
 
-The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix) and one binding per place a collection or field is used.
+The scanner reads the site's source and writes down what it reads from Mapled: the pages (from the framework's file layout — Next.js App and Pages Router, Astro, SvelteKit, Nuxt, Remix — or a plain HTML site's `.html` files) and one binding per place a collection or field is used.
 
 ```text
 Scanned 42 files with TypeScript — 3 pages, 14 bindings.
@@ -113,6 +113,21 @@ No mapled/manifest.json yet — run `mapled scan --write` to create it, then `ma
 
 It follows `getRecords` / `getRecord` / `getRecordBySlug` / `getSingle` calls through variables, destructuring, `.map()` callbacks and into the components a record is passed to as a prop, and through helpers in `lib/` that return a read. The parser is your repository's own TypeScript; without it the scanner still finds the collections, but not the fields. Source code never leaves your machine — only the manifest does, when you push it.
 
+**A plain HTML site** (`framework` is `plain-html` in `mapled.json` — a folder with an `index.html` and no framework in `package.json`) has no reads in code: the scanner reads the `data-mapled-*` attributes of its `.html` files the way the [`@mapled/vanilla`](https://www.npmjs.com/package/@mapled/vanilla) script does, in the tree a browser builds from the file (the CLI carries the standard HTML parser, parse5, inside — nothing to install). Each file is a page where a static host serves it (`index.html` → `/`, `blog/index.html` → `/blog/`, `post.html` → `/post.html`, `public/` from the root); a record read by `data-mapled-slug-param` has its own address with that parameter in the query, so **Preview** in the record's editor opens the right page — and the scan says when Preview can't open an address. The target of a binding is what the attribute renders — `data-mapled-format="markdown"` rich text, an `<img>` an image, `data-mapled-bind-href` a link — and each different way a field is read is a binding of its own, so a field bound where it can't render shows up as a mismatch even when another element reads it well. With the schema at hand it also names the paths nothing in Mapled answers to: on the page, a misspelled field and an empty one look the same.
+
+```text
+Scanned 2 HTML files — 2 pages, 11 bindings.
+
+/                       index.html
+  home   headline, intro, tagline
+  posts  list • date, slug, title
+/post.html?slug=[slug]  post.html
+  home   headline
+  posts  by slug • body, title
+
+⚠ 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.
+```
+
 `--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
@@ -192,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,7 +11,9 @@ 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";
 /** The OAuth client id for this API — registered once per machine, and
     again when the server no longer knows it. */
@@ -446,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));
@@ -490,8 +571,8 @@ export async function scan(ctx, flags) {
         throw new CliError(`The scan needs the schema to name the fields — sign in with \`mapled auth login\` or run \`mapled schema pull\` first.`);
     }
     const framework = found.config.framework ?? (await dr.detectFramework(found.dir)) ?? null;
-    const ts = loadTypeScript(found.dir);
-    const result = await scanRepository(found.dir, { framework, schema, ts });
+    // 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) });
     const existing = await loadManifest(found.dir);
     const merged = mergeManifest(existing?.manifest ?? null, result, { prune: Boolean(flags.prune) });
     if (flags.json) {
@@ -500,7 +581,7 @@ export async function scan(ctx, flags) {
             await writeManifestFile(found.dir, merged.manifest);
         return;
     }
-    ctx.out(`Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
+    ctx.out(`${result.parser === "html" ? `Scanned ${plural(result.files, "HTML file")}` : `Scanned ${plural(result.files, "file")} with ${result.parser === "typescript" ? "TypeScript" : "the tokenizer"}`} — ${plural(result.pages.length, "page")}, ${plural(result.bindings.length, "binding")}.`);
     if (result.bindings.length > 0) {
         ctx.out("");
         for (const line of describeScan(result, schema))

package/dist/html5.d.ts

@@ -0,0 +1,66 @@
+import { type Token, type TreeAdapter, type TreeAdapterTypeMap } from "parse5";
+/** The HTML parser of `mapled scan` for a plain HTML site: parse5, the
+    WHATWG parsing algorithm — the tree a browser builds, and the one
+    jsdom builds for the runtime's tests. Tag soup decides which scope a
+    binding lands in (a <p> a <div> closes, a table's foster parent, a
+    template an end tag can't leave), so the scan can't read a tree of its
+    own. build.mjs bundles parse5 (pinned) into dist/html5.js: the CLI
+    still installs without dependencies.
+
+    What a page can make the parser do is held linear in its size — a
+    page is the site's to write, and the scan reads up to 2 MB of it:
+    - open elements: at most MAX_OPEN (Guarded.onItemPush). Every start tag
+      looks down them for a scope; 100,000 unclosed <div>s cost minutes.
+    - a tag's attributes: a set of names (Guarded, _leaveAttrName). parse5
+      compared each new one with every earlier one — 64,000 on one <div>: 4 s.
+    - the tree: children in linked lists (`linked` below), every operation
+      O(1). parse5's own tree keeps arrays, and foster parenting (text
+      before a <table>: indexOf), the adoption agency (a misnested </b>:
+      splice from the front) and repeated <html>/<body> tags (every
+      attribute so far) walk them — 160,000 "a<br>" in a table: 11 s.
+    The worst page within the cap is the depth times its start tags. */
+/** How deep elements may be open at once — Chrome's own limit of the tree it builds. */
+export declare const MAX_OPEN = 512;
+export declare class TooDeep extends Error {
+}
+export type Html5Attr = Token.Attribute;
+/** A node of the tree: an element (tagName), text, a comment, a doctype,
+    the document or a template's content — children linked both ways. Its
+    fields are named as parse5's own tree names them; `childNodes` is made
+    when asked for (the parser never asks). */
+export declare class Html5Node {
+    readonly nodeName: string;
+    tagName?: string;
+    namespaceURI?: string;
+    attrs?: Html5Attr[];
+    /** a <template>'s content: what the page's author wrote inside it */
+    content?: Html5Node;
+    parentNode: Html5Node | null;
+    firstChild: Html5Node | null;
+    lastChild: Html5Node | null;
+    previousSibling: Html5Node | null;
+    nextSibling: Html5Node | null;
+    /** a text's */
+    value?: string;
+    /** a comment's */
+    data?: string;
+    /** a doctype's */
+    name?: string;
+    publicId?: string;
+    systemId?: string;
+    /** the document's */
+    mode?: string;
+    /** the names an <html> or <body> has, as repeated tags add to them */
+    names?: Set<string>;
+    location?: Token.ElementLocation | null;
+    constructor(nodeName: string, extra?: Partial<Html5Node>);
+    /** none on a text, a comment or a doctype, as in parse5's tree */
+    get childNodes(): Html5Node[] | undefined;
+}
+type Map_ = TreeAdapterTypeMap<Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node, Html5Node>;
+/** parse5's default tree adapter, method for method, on linked children. */
+export declare const linked: TreeAdapter<Map_>;
+/** The document, with scripting on — as the runtime sees it (a <noscript>
+    is text). Throws TooDeep past MAX_OPEN open elements. */
+export declare function parseDocument(text: string): Html5Node;
+export {};