@mapled/cli 0.16.0 → 0.17.1

package/dist/media.d.ts

@@ -0,0 +1,37 @@
+import { type Session } from "./api.js";
+import type { Fetch } from "./oauth.js";
+export type Asset = {
+    id: string;
+    url: string;
+    fileName: string;
+    mime: string;
+    sizeBytes: number;
+};
+export type Uploaded = {
+    source: string;
+    ok: true;
+    asset: Asset;
+    deduplicated: boolean;
+} | {
+    source: string;
+    ok: false;
+    error: string;
+};
+/** The file a source names in the repository: its path from the root —
+    or, written from the site's root (`/images/a.png`), under `public/`
+    or `static/` as the frameworks serve it. Never a file outside the
+    repository, links included. */
+export declare function locate(root: string, source: string): Promise<string | null>;
+/** One source into Media: a file of the repository at `root`, or a
+    public address. */
+export declare function uploadSource(session: Session, f: Fetch, root: string, source: string, runId?: string): Promise<Uploaded>;
+/** Every source, a few at a time, in the order given. */
+export declare function uploadAll(session: Session, f: Fetch, root: string, sources: string[], runId?: string): Promise<Uploaded[]>;
+/** The sources of a setup run's plan that aren't in Mapled yet. */
+export declare function pendingOf(session: Session, runId: string): Promise<{
+    status: string;
+    pending: string[];
+    total: number;
+}>;
+/** One line per upload: what it became, or why it didn't. */
+export declare function uploadLine(r: Uploaded): string;

package/dist/media.js

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { ApiError } from "./api.js";
+import { CliError } from "./errors.js";
+/** `mapled media upload` (F3): the site's images and files into the
+    project's Media. A file of the repository goes sign → PUT → complete
+    (`/v1/agent/media/*`); a public address Mapled downloads itself
+    (`import`). With a setup run, each upload is a media source of its
+    approved plan, and the apply puts the assets into the records. */
+/** The types Media takes, by extension. */
+const TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".glb": "model/gltf-binary",
+    ".gltf": "model/gltf+json",
+};
+/** What Media's upload says: "Up to 10 MB per image"; a PDF or a 3D model up to 25 MB. */
+const IMAGE_LIMIT = 10 * 1024 * 1024;
+const FILE_LIMIT = 25 * 1024 * 1024;
+/** Uploads in flight at once. */
+const PARALLEL = 4;
+const isAddress = (source) => /^https?:\/\//i.test(source);
+/** The file a source names in the repository: its path from the root —
+    or, written from the site's root (`/images/a.png`), under `public/`
+    or `static/` as the frameworks serve it. Never a file outside the
+    repository, links included. */
+export async function locate(root, source) {
+    const realRoot = await realpath(root);
+    const rel = source.replace(/^\.\//, "");
+    const tries = rel.startsWith("/")
+        ? [rel.slice(1), `public${rel}`, `static${rel}`]
+        : [rel, `public/${rel}`];
+    for (const candidate of tries) {
+        let real;
+        try {
+            real = await realpath(path.resolve(realRoot, candidate));
+        }
+        catch {
+            continue;
+        }
+        if (!real.startsWith(realRoot + path.sep))
+            continue;
+        if ((await stat(real)).isFile())
+            return real;
+    }
+    return null;
+}
+/** Why an upload failed, as Mapled said it. */
+const why = (err) => (err instanceof ApiError || err instanceof CliError ? err.message : "the upload didn't go through. Try again.");
+async function uploadFile(session, f, root, source, run) {
+    const file = await locate(root, source);
+    if (!file)
+        return { source, ok: false, error: "not found in the repository." };
+    const mime = TYPES[path.extname(file).toLowerCase()];
+    if (!mime)
+        return { source, ok: false, error: "isn't a file Media takes: PNG, JPEG, WebP, GIF, SVG, PDF, GLB or glTF." };
+    const bytes = await readFile(file);
+    const limit = mime.startsWith("image/") ? IMAGE_LIMIT : FILE_LIMIT;
+    if (bytes.length > limit)
+        return { source, ok: false, error: `is larger than ${limit / 1024 / 1024} MB. Compress it and try again.` };
+    if (bytes.length === 0)
+        return { source, ok: false, error: "is empty." };
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    try {
+        const signed = await session.send("POST", "/v1/agent/media/sign", { fileName: path.basename(file), mime, sizeBytes: bytes.length, sha256, ...run });
+        if (signed.asset)
+            return { source, ok: true, asset: signed.asset, deduplicated: true };
+        // R2's presigned address, or the API's own sink in development
+        const target = new URL(signed.uploadUrl, session.conn.api).href;
+        let put;
+        try {
+            put = await f(target, { method: "PUT", headers: signed.headers ?? { "Content-Type": mime }, body: new Uint8Array(bytes) });
+        }
+        catch {
+            return { source, ok: false, error: "the upload didn't reach storage. Check your connection and try again." };
+        }
+        if (!put.ok)
+            return { source, ok: false, error: `storage refused the upload (${put.status}). Try again.` };
+        const done = await session.send("POST", "/v1/agent/media/complete", { ticket: signed.ticket, ...run });
+        return { source, ok: true, asset: done.asset, deduplicated: done.deduplicated };
+    }
+    catch (err) {
+        return { source, ok: false, error: why(err) };
+    }
+}
+/** One source into Media: a file of the repository at `root`, or a
+    public address. */
+export async function uploadSource(session, f, root, source, runId) {
+    const run = runId ? { runId, source } : null;
+    if (!isAddress(source))
+        return uploadFile(session, f, root, source, run);
+    try {
+        const done = await session.send("POST", "/v1/agent/media/import", { url: source, ...run });
+        return { source, ok: true, asset: done.asset, deduplicated: done.deduplicated };
+    }
+    catch (err) {
+        return { source, ok: false, error: why(err) };
+    }
+}
+/** Every source, a few at a time, in the order given. */
+export async function uploadAll(session, f, root, sources, runId) {
+    const results = new Array(sources.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < sources.length) {
+            const i = next++;
+            results[i] = await uploadSource(session, f, root, sources[i], runId);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PARALLEL, sources.length) }, worker));
+    return results;
+}
+/** The sources of a setup run's plan that aren't in Mapled yet. */
+export async function pendingOf(session, runId) {
+    const answer = await session.get(`/v1/agent/runs/${encodeURIComponent(runId)}`);
+    return {
+        status: answer.run?.status ?? "",
+        pending: answer.run?.media?.pending ?? [],
+        total: answer.run?.media?.total ?? 0,
+    };
+}
+/** One line per upload: what it became, or why it didn't. */
+export function uploadLine(r) {
+    return r.ok
+        ? `✓ ${r.source} → ${r.asset.id}${r.deduplicated ? " (already in Media)" : ""}`
+        : `✗ ${r.source}: ${r.error}`;
+}

package/dist/oauth.d.ts

@@ -1,3 +1,4 @@
+import { type CallbackView } from "./callbackPage.js";
 /** The CLI signs in as an OAuth 2.1 public client of the Mapled API —
     the same authorization server the remote MCP uses (S-54): dynamic
     registration, PKCE, consent on app.mapled.io, a loopback redirect
@@ -17,6 +18,13 @@ export type AuthorizationCode = {
     verifier: string;
     redirectUri: string;
 };
+/** The browser tab that brought the code waits on this: the caller says
+    how the sign-in ended once it knows (the project, where to go on). */
+export type SignInTab = {
+    show: (view: CallbackView) => void;
+};
+/** How long the tab waits for `show` before it hands over on its own. */
+export declare const HOLD_MS = 30000;
 export declare function pkce(): {
     verifier: string;
     challenge: string;
@@ -39,8 +47,12 @@ export type AuthorizeDeps = {
 /** The authorization code flow with a loopback redirect: a one-off
     server on 127.0.0.1 receives the code once the person approves on
     app.mapled.io. Rejects on denial, on timeout, and never on a state
-    that isn't this run's. */
-export declare function authorize(api: string, clientId: string, deps: AuthorizeDeps): Promise<AuthorizationCode>;
+    that isn't this run's. The tab that brought the code is answered by
+    the caller through `tab.show` — after the exchange, when the project
+    is known — or, failing that, after `HOLD_MS`. */
+export declare function authorize(api: string, clientId: string, deps: AuthorizeDeps): Promise<AuthorizationCode & {
+    tab: SignInTab;
+}>;
 export declare function exchangeCode(api: string, clientId: string, grant: AuthorizationCode, f: Fetch): Promise<TokenSet>;
 export declare function refreshTokens(api: string, clientId: string, refreshToken: string, f: Fetch): Promise<TokenSet>;
 /** Ends the connection (RFC 7009). Best effort — the local copy goes either way. */

package/dist/oauth.js

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
+import { callbackPage } from "./callbackPage.js";
 import { CliError } from "./errors.js";
 /** The CLI signs in as an OAuth 2.1 public client of the Mapled API —
     the same authorization server the remote MCP uses (S-54): dynamic
@@ -9,6 +10,8 @@ import { CliError } from "./errors.js";
 export const CLIENT_NAME = "Mapled CLI";
 export const REDIRECT_PATH = "/callback";
 export const SCOPE = "mapled";
+/** How long the tab waits for `show` before it hands over on its own. */
+export const HOLD_MS = 30_000;
 export function pkce() {
     const verifier = randomBytes(48).toString("base64url");
     const challenge = createHash("sha256").update(verifier).digest("base64url");
@@ -83,16 +86,26 @@ export async function clientKnown(api, clientId, f) {
         return false;
     }
 }
-function page(res, status, text) {
-    // Fixed strings of our own — nothing from the query string is rendered.
-    res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
-    res.end(`<!doctype html><meta charset="utf-8"><title>Mapled</title>` +
-        `<p style="font:16px system-ui,sans-serif;margin:40px">${text}</p>`);
+function page(res, view) {
+    // Fixed strings of our own and the project's name, escaped — nothing
+    // from the query string is rendered.
+    const { status, html, csp } = callbackPage(view);
+    res.writeHead(status, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        "content-security-policy": csp,
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        connection: "close",
+    });
+    res.end(html);
 }
 /** The authorization code flow with a loopback redirect: a one-off
     server on 127.0.0.1 receives the code once the person approves on
     app.mapled.io. Rejects on denial, on timeout, and never on a state
-    that isn't this run's. */
+    that isn't this run's. The tab that brought the code is answered by
+    the caller through `tab.show` — after the exchange, when the project
+    is known — or, failing that, after `HOLD_MS`. */
 export function authorize(api, clientId, deps) {
     const { verifier, challenge } = pkce();
     const state = randomBytes(16).toString("base64url");
@@ -107,12 +120,12 @@ export function authorize(api, clientId, deps) {
             }
             if (url.searchParams.get("state") !== state) {
                 // Not this run's redirect — keep waiting for the real one.
-                page(res, 400, "This sign-in link doesn't belong to the running command.");
+                page(res, { kind: "expired" });
                 return;
             }
             const error = url.searchParams.get("error");
             if (error) {
-                page(res, 200, "Sign-in was cancelled. You can close this tab.");
+                page(res, { kind: "cancelled" });
                 finish(() => reject(new CliError(error === "access_denied"
                     ? "Sign-in was denied in the browser."
                     : `Sign-in failed: ${url.searchParams.get("error_description") ?? error}`)));
@@ -120,11 +133,21 @@ export function authorize(api, clientId, deps) {
             }
             const code = url.searchParams.get("code");
             if (!code) {
-                page(res, 400, "The sign-in link is missing its code.");
+                page(res, { kind: "incomplete" });
                 return;
             }
-            page(res, 200, "Signed in to Mapled. You can close this tab and return to the terminal.");
-            finish(() => resolve({ code, verifier, redirectUri }));
+            // the tab waits for the outcome; the server stops listening now
+            let shown = false;
+            const show = (view) => {
+                if (shown)
+                    return;
+                shown = true;
+                clearTimeout(hold);
+                page(res, view);
+            };
+            const hold = setTimeout(() => show({ kind: "handed-over" }), HOLD_MS);
+            hold.unref?.();
+            finish(() => resolve({ code, verifier, redirectUri, tab: { show } }));
         });
         const timer = setTimeout(() => finish(() => reject(new CliError("Timed out waiting for the browser. Run `mapled auth login` again."))), deps.timeoutMs ?? 5 * 60_000);
         function finish(then) {

package/dist/pin.js

@@ -14,6 +14,14 @@ function pinSubField(s) {
     out.helpText = s.helpText ?? null;
     out.options = s.options ?? null;
     out.sensitive = s.sensitive === true;
+    // a component type's group sub-field (§45.4) is in the schema hash: only it carries one
+    if (s.type === "group" && s.group) {
+        out.group = { repeatable: s.group.repeatable, ...(s.group.maxItems ? { maxItems: s.group.maxItems } : {}), fields: s.group.fields.map(pinSubField) };
+    }
+    // and its relation sub-field's collection (§45.4)
+    if (s.type === "relation" && s.relation) {
+        out.relation = { target: s.relation.target, cardinality: s.relation.cardinality, ...(s.relation.onDelete ? { onDelete: s.relation.onDelete } : {}) };
+    }
     return out;
 }
 function pinField(f) {
@@ -157,6 +165,47 @@ function diffCommon(before, after, names, push) {
         push("changed", "no longer sensitive — delivered to the site now", "safe");
     }
 }
+/** A group's own changes — one item or a list, its limit, its
+    sub-fields removed, changed and added — the sub-fields under
+    `under.sub`. */
+function diffGroup(before, after, under, names, push) {
+    if (before.repeatable !== after.repeatable) {
+        push(under, "changed", before.repeatable ? "repeatable → single item" : "single item → repeatable", "breaking");
+    }
+    if ((before.maxItems ?? null) !== (after.maxItems ?? null)) {
+        const limit = (n) => (n ? `up to ${n} items` : "no item limit");
+        push(under, "changed", `${limit(before.maxItems)} → ${limit(after.maxItems)}`, "safe");
+    }
+    const afterSubs = new Map(after.fields.map((s) => [s.key, s]));
+    const beforeSubs = new Map(before.fields.map((s) => [s.key, s]));
+    for (const bs of before.fields) {
+        const as = afterSubs.get(bs.key);
+        const sub = `${under}.${bs.key}`;
+        if (!as) {
+            push(sub, "removed", `removed — ${describeType(bs, names)}`, "breaking");
+            continue;
+        }
+        diffCommon(bs, as, names, (op, detail, severity) => push(sub, op, detail, severity));
+    }
+    for (const as of after.fields) {
+        if (beforeSubs.has(as.key))
+            continue;
+        push(`${under}.${as.key}`, "added", `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`, "safe");
+    }
+}
+/** A relation's own changes — a field's, or a block's relation
+    sub-field's (§45.4): where it links and how many are breaking, what a
+    delete does is safe. */
+function diffRelation(before, after, names, push) {
+    if (before.target !== after.target) {
+        push("changed", `relation to ${names.get(before.target) ?? before.target} → ${names.get(after.target) ?? after.target}`, "breaking");
+    }
+    if (before.cardinality !== after.cardinality)
+        push("changed", `${before.cardinality} → ${after.cardinality}`, "breaking");
+    if ((before.onDelete ?? null) !== (after.onDelete ?? null)) {
+        push("changed", `on delete ${before.onDelete ?? "default"} → ${after.onDelete ?? "default"}`, "safe");
+    }
+}
 function sameJson(a, b) {
     return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
 }
@@ -213,16 +262,8 @@ export function diffSchema(before, after, componentTypes = {}) {
             if ((bf.localized === true) !== (af.localized === true)) {
                 push("changed", af.localized === true ? "now translated — the site still reads the default language" : "no longer translated — the default language's value stays", "safe");
             }
-            if (bf.type === "relation" && af.type === "relation" && bf.relation && af.relation) {
-                if (bf.relation.target !== af.relation.target) {
-                    push("changed", `relation to ${names.get(bf.relation.target) ?? bf.relation.target} → ${names.get(af.relation.target) ?? af.relation.target}`, "breaking");
-                }
-                if (bf.relation.cardinality !== af.relation.cardinality)
-                    push("changed", `${bf.relation.cardinality} → ${af.relation.cardinality}`, "breaking");
-                if ((bf.relation.onDelete ?? null) !== (af.relation.onDelete ?? null)) {
-                    push("changed", `on delete ${bf.relation.onDelete ?? "default"} → ${af.relation.onDelete ?? "default"}`, "safe");
-                }
-            }
+            if (bf.type === "relation" && af.type === "relation" && bf.relation && af.relation)
+                diffRelation(bf.relation, af.relation, names, push);
             if (bf.type === "computed" && af.type === "computed" && bf.computed && af.computed) {
                 if (bf.computed.resultType !== af.computed.resultType) {
                     push("changed", `${describeType(bf, names)} → ${describeType(af, names)}`, "breaking");
@@ -232,36 +273,7 @@ export function diffSchema(before, after, componentTypes = {}) {
                 }
             }
             if (bf.type === "group" && af.type === "group" && bf.group && af.group) {
-                if (bf.group.repeatable !== af.group.repeatable) {
-                    push("changed", bf.group.repeatable ? "repeatable → single item" : "single item → repeatable", "breaking");
-                }
-                if ((bf.group.maxItems ?? null) !== (af.group.maxItems ?? null)) {
-                    const limit = (n) => (n ? `up to ${n} items` : "no item limit");
-                    push("changed", `${limit(bf.group.maxItems)} → ${limit(af.group.maxItems)}`, "safe");
-                }
-                const afterSubs = new Map(af.group.fields.map((s) => [s.key, s]));
-                const beforeSubs = new Map(bf.group.fields.map((s) => [s.key, s]));
-                for (const bs of bf.group.fields) {
-                    const as = afterSubs.get(bs.key);
-                    const sub = `${under}.${bs.key}`;
-                    if (!as) {
-                        changes.push({ ...base, scope: "subfield", field: sub, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
-                        continue;
-                    }
-                    diffCommon(bs, as, names, (op, detail, severity) => changes.push({ ...base, scope: "subfield", field: sub, op, detail, severity }));
-                }
-                for (const as of af.group.fields) {
-                    if (beforeSubs.has(as.key))
-                        continue;
-                    changes.push({
-                        ...base,
-                        scope: "subfield",
-                        field: `${under}.${as.key}`,
-                        op: "added",
-                        detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`,
-                        severity: "safe",
-                    });
-                }
+                diffGroup(bf.group, af.group, under, names, (field, op, detail, severity) => changes.push({ ...base, scope: field === under ? "field" : "subfield", field, op, detail, severity }));
             }
             // §45.4: a type the list may no longer hold leaves the site's union; a new one is an item the site doesn't render yet
             if (bf.type === "components" && af.type === "components" && bf.components && af.components) {
@@ -322,18 +334,26 @@ export function diffSchema(before, after, componentTypes = {}) {
             changes.push({ ...base, scope: "component", op: "changed", detail: `name ${q(bt.displayName)} → ${q(at.displayName)}`, severity: "safe" });
         const afterSubs = new Map(at.fields.map((s) => [s.key, s]));
         const beforeSubs = new Map(bt.fields.map((s) => [s.key, s]));
+        const push = (field, op, detail, severity) => changes.push({ ...base, scope: "component", field, op, detail, severity });
         for (const bs of bt.fields) {
             const as = afterSubs.get(bs.key);
             if (!as) {
-                changes.push({ ...base, scope: "component", field: bs.key, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
+                push(bs.key, "removed", `removed — ${describeType(bs, names)}`, "breaking");
                 continue;
             }
-            diffCommon(bs, as, names, (op, detail, severity) => changes.push({ ...base, scope: "component", field: bs.key, op, detail, severity }));
+            diffCommon(bs, as, names, (op, detail, severity) => push(bs.key, op, detail, severity));
+            // a group sub-field's items (§45.4): its own sub-fields under `tiers.name`
+            if (bs.type === "group" && as.type === "group" && bs.group && as.group)
+                diffGroup(bs.group, as.group, bs.key, names, push);
+            // a relation sub-field's collection and cardinality, as a relation field's
+            if (bs.type === "relation" && as.type === "relation" && bs.relation && as.relation) {
+                diffRelation(bs.relation, as.relation, names, (op, detail, severity) => push(bs.key, op, detail, severity));
+            }
         }
         for (const as of at.fields) {
             if (beforeSubs.has(as.key))
                 continue;
-            changes.push({ ...base, scope: "component", field: as.key, op: "added", detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`, severity: "safe" });
+            push(as.key, "added", `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`, "safe");
         }
     }
     for (const at of typesAfter) {

package/dist/scanHtml.d.ts

@@ -5,16 +5,23 @@ import type { Schema } from "./schema.js";
     `data-mapled-*` attributes declare — read the way the runtime reads
     them (packages/vanilla/src/runtime.ts, `compile`): a path starts at a
     single from the document and at the record inside a list or a record,
-    an each repeats the items of a group, a <template> counts only as the
-    first one of a list or an each, a list or a record inside a repeated
-    template is never read. The target is the sink the attribute names —
+    an each repeats the items of a group or the blocks of a components
+    field — inside a block's template, the items of its group sub-field
+    (§45.4) — a list's records and a group's items take the first <template>
+    without data-mapled-type and a block the first of its type (else that
+    one), a list or a record inside a repeated template is never read. The target is the sink the attribute names —
     `markdown` renders rich text, an <img> an image, `bind-href` a link —
-    so a field bound where it can't render shows as a mismatch. What the
+    so a field bound where it can't render shows as a mismatch; a place
+    the runtime doesn't write into (a code element, an attribute off its
+    elements, an attribute inside <svg>) binds nothing and earns a note. What the
     runtime can't tell apart — an empty field and a misspelled key — the
     scan can: it has the schema. Nothing on the page runs or leaves the
     machine; only the manifest does, on `bindings push`. */
+/** `html`: the element is in the HTML namespace — not SVG or MathML, where
+    the runtime writes no attribute (DOM rule 3). */
 export type HtmlElement = {
     name: string;
+    html: boolean;
     attrs: Map<string, string>;
     children: HtmlElement[];
 };