@mapled/cli 0.15.0 → 0.17.0

package/README.md

@@ -30,9 +30,12 @@ The browser opens Mapled on that project and the person clicks Authorize; nothin
 npx @mapled/cli tools
 npx @mapled/cli tool get_schema
 npx @mapled/cli tool propose_setup_plan --input plan.json
+npx @mapled/cli tool get_setup_run '{"runId":"…"}' --wait
 ```
 
-`tools` lists every tool with its input (`--json` for the schemas). `tool <name>` calls one — the same tools the [MCP server](https://www.npmjs.com/package/@mapled/mcp) offers, through the same connection: the input is a JSON object, inline or in a file with `--input`; the answer is printed as Mapled worded it, and a refusal exits 1.
+`tools` lists every tool with its input (`--json` for the schemas). `tool <name>` calls one — the same tools the [MCP server](https://www.npmjs.com/package/@mapled/mcp) offers, through the same connection: the input is a JSON object, inline or in a file with `--input`; the answer is printed as Mapled worded it, and a refusal exits 1. `tool get_setup_run '{"runId":"…"}' --wait` waits while the plan is still waiting for approval and prints the run once the person has decided on the Mapled screen — the agent carries on without being asked; it waits 90 seconds by default (`--wait=<seconds>`, up to 600) and then prints the run as it stands, so the agent runs the same command again.
+
+Images are content: a setup plan names each picture in an image field (its path in the repository or its public address). Once the plan is approved, `npx @mapled/cli media upload --run <runId>` uploads every one of them into the project's Media — `tool apply_setup_plan` does it first by itself — and the records point at the files, which the owner can replace in Mapled.
 
 Do the work yourself: the person approves on Mapled screens (the connection, the plan, a destructive change) and is never sent to a terminal or to GitHub. Never ask for a token or a key in the conversation.
 
@@ -185,6 +188,15 @@ Submissions show up in Mapled under Forms.
 
 The key comes from the name; `--key <key>` chooses it (lowercase letters, digits and dashes), `--no-spam-protection` turns the honeypot off. Creating a form changes structure, so it needs the builder plan. `forms list` shows every form with the URL the site posts to (`--json` for scripts). The component that posts to it is in the [`@mapled/next` README](https://www.npmjs.com/package/@mapled/next#forms).
 
+## Upload media
+
+```bash
+npx @mapled/cli media upload public/products/hoodie.jpg https://example.com/cover.png
+npx @mapled/cli media upload --run <runId>
+```
+
+`media upload` puts images and files into the project's Media: a path is read from this repository (a path from the site's root, `/images/a.png`, is looked for under `public/` and `static/` too; nothing outside the repository is read), an address is downloaded by Mapled. PNG, JPEG, WebP, GIF and SVG up to 10 MB, PDF up to 25 MB; the same bytes uploaded twice are one file. Each line names the asset id an image or file field holds. `--run <runId>` uploads every file an approved setup plan names that isn't in Mapled yet, for `apply_setup_plan` to put into the records (`--json` for scripts); a file that didn't upload is named with the reason and the command exits 1.
+
 ## Leave a guide for the next agent
 
 ```bash
@@ -287,13 +299,26 @@ npx @mapled/cli preview articles hello-world --locale ru
 
 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. A plain HTML site whose pages are built with the content in them has no page for a record it wasn't built with: for such a record the command says so instead of printing a link — its page appears once the site is built with it. `--locale <code>` opens the page in that language — the address Mapled builds from the manifest's `locales` (a translated slug is the address in its language); a language the project doesn't have is refused. `--open` opens it in your browser instead of printing it; `--json` prints the link with the page, the language when one was asked, and when it expires.
 
+## Put the server key on the host
+
+```bash
+npx @mapled/cli env push --host vercel
+npx @mapled/cli env push --host netlify
+npx @mapled/cli env push --host cloudflare
+```
+
+Gives the site on that host a server key of its own (Live data, the Application Data API) and sets it as `MAPLED_SERVER_KEY` there, without the key passing through you or your agent. Run it from the site's repository, with the host's CLI signed in and the directory linked (`vercel link`, `netlify link`, or a `wrangler.toml`); a CLI that isn't installed runs through `npx`. The command prints a link: an owner of the project confirms the key there, in Mapled. Once they do, the command claims the key — only the process that asked can, once, within ten minutes — and hands it to the host's CLI: Vercel for production and preview, Netlify as a site variable, Cloudflare as a Worker secret (a Worker whose configuration has environments needs `--env <name>`, the one the site is deployed to). The key is never printed, logged, written to a file or included in `--json`; you see its prefix. A new key for the same host replaces the old one, which keeps working for 24 hours while the host redeploys; the project's main key and the other hosts' keep working, and an owner revokes a host's key in Mapled. Redeploy the site afterwards. `--json` prints the host, the variable, the prefix and the confirmation.
+
 ## 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
 - `--project <id>` — the project `connect` and `auth login` open the consent on, and the one `project link` links
 - `--input <file>` — `tool` only: the tool's input as a JSON file
-- `--json` — machine-readable output (`tools`, `doctor`, `integration report`, `schema diff`, `scan`, `manifest validate`, `forms list`, `preview`)
+- `--wait[=<seconds>]` — `tool get_setup_run` only: wait while the plan awaits approval (90 seconds by default, up to 600)
+- `--host <vercel|netlify|cloudflare>` — `env push` only: the host the site runs on
+- `--env <name>` — `env push --host cloudflare` only: the Wrangler environment the Worker is deployed as
+- `--json` — machine-readable output (`tools`, `doctor`, `integration report`, `schema diff`, `scan`, `manifest validate`, `forms list`, `media upload`, `preview`, `env push`)
 - `--load-config` — `doctor` only: let the site's installed Next load a next.config doctor can't read; runs the site's code, as `next build` does
 - `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)
 

package/dist/args.js

@@ -2,7 +2,7 @@ import { CliError } from "./errors.js";
 /** Minimal argument parsing: the leading words name the command;
     `--flag`, `--flag=value` and `--flag value` (for the flags that take
     one) follow. Nothing here is user content beyond the command line. */
-const VALUE_FLAGS = new Set(["api", "project", "out", "key", "locale", "input"]);
+const VALUE_FLAGS = new Set(["api", "project", "out", "key", "locale", "input", "host", "env"]);
 export function parseArgs(argv) {
     const words = [];
     const flags = {};

package/dist/commands.d.ts

@@ -1,7 +1,9 @@
+import { Session } from "./api.js";
 import { type ParsedArgs } from "./args.js";
 import { type FoundConfig } from "./config.js";
 import { type Connection } from "./credentials.js";
 import { type Fetch } from "./oauth.js";
+import type { Runner } from "./envPush.js";
 /** The commands of waves 1 and 2 (§31), MAPLED.md (§21.3) and forms.
     Everything that talks to the world comes in through `Ctx`, so the
     commands run in tests against a fake API and a temp directory. */
@@ -17,6 +19,10 @@ export type Ctx = {
     credentialsFile: string;
     /** How long a sign-in waits for the browser (tests shorten it). */
     loginTimeoutMs?: number;
+    /** How often `tool get_setup_run --wait` asks again (tests shorten it). */
+    pollMs?: number;
+    /** Runs a host's CLI for `env push` (tests replace it). */
+    run?: Runner;
 };
 type Flags = ParsedArgs["flags"];
 export declare function login(ctx: Ctx, flags: Flags): Promise<Connection>;
@@ -35,6 +41,16 @@ export declare function tools(ctx: Ctx, flags: Flags): Promise<void>;
     way an MCP client makes it: the answer is printed as Mapled worded
     it, a refusal exits 1. */
 export declare function tool(ctx: Ctx, flags: Flags, words: string[]): Promise<number>;
+/** `mapled media upload [<path | url>…] [--run <runId>] [--json]` — files
+    of this repository or public addresses into the project's Media.
+    With --run, every media file of that approved setup plan (or the ones
+    named) is uploaded as the plan's, for apply_setup_plan to put into
+    the records. */
+export declare function mediaUpload(ctx: Ctx, flags: Flags, sources: string[]): Promise<number>;
+export declare function openSession(ctx: Ctx, flags: Flags): Promise<{
+    found: FoundConfig;
+    session: Session;
+}>;
 export declare function generate(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function schemaPull(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function schemaDiff(ctx: Ctx, flags: Flags): Promise<number>;

package/dist/commands.js

@@ -16,6 +16,7 @@ import { capabilitiesOf, findLive, liveState } from "./live.js";
 import { loadTypeScript, mergeManifest, scanRepository } from "./scan.js";
 import { scanHtml } from "./scanHtml.js";
 import { generateTypes } from "./types.js";
+import { pendingOf, uploadAll, uploadLine, uploadSource } from "./media.js";
 /** The OAuth client id for this API — registered once per machine, and
     again when the server no longer knows it. */
 async function ensureClient(store, api, f) {
@@ -249,14 +250,124 @@ export async function tool(ctx, flags, words) {
     }
     if (args === null || typeof args !== "object" || Array.isArray(args))
         throw new CliError("The input must be a JSON object.");
-    const { session } = await openSession(ctx, flags);
-    const answer = await session.rpc("tools/call", { name, arguments: args });
+    const wait = waitSeconds(flags, name);
+    const { found, session } = await openSession(ctx, flags);
+    const input = args;
+    // a file on this machine: the hosted tool can't read it, the CLI uploads it
+    if (name === "upload_media" && typeof input.path === "string" && input.url === undefined) {
+        const runId = typeof input.runId === "string" ? input.runId : undefined;
+        const done = await uploadSource(session, ctx.fetch, found.dir, typeof input.source === "string" ? input.source : input.path, runId);
+        if (!done.ok) {
+            ctx.out(`${done.source}: ${done.error}`);
+            return 1;
+        }
+        ctx.out(JSON.stringify({ asset: done.asset, deduplicated: done.deduplicated }, null, 2));
+        return 0;
+    }
+    // the plan's media goes up before the apply that puts it into the records
+    if (name === "apply_setup_plan" && typeof input.runId === "string" && input.skipMissingMedia !== true) {
+        await uploadRunMedia(ctx, session, found.dir, input.runId);
+    }
+    const deadline = Date.now() + wait * 1000;
+    let answer = await session.rpc("tools/call", { name, arguments: args });
+    // the person approves on a Mapled screen, not in the agent's chat: the
+    // agent blocks here instead of ending its turn to wait for a word that
+    // never comes
+    while (wait > 0 && !answer.isError && awaitingApproval(answer) && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, Math.min(ctx.pollMs ?? WAIT_POLL_MS, Math.max(0, deadline - Date.now()))));
+        answer = await session.rpc("tools/call", { name, arguments: args });
+    }
     for (const part of answer.content ?? [])
         if (part.type === "text" && part.text !== undefined)
             ctx.out(part.text);
     return answer.isError ? 1 : 0;
 }
-async function openSession(ctx, flags) {
+/** The media a setup run's plan names and Mapled doesn't have yet, from
+    this repository or the public addresses it names; a line per file.
+    Nothing to do unless the plan is approved. */
+async function uploadRunMedia(ctx, session, root, runId) {
+    const { status, pending } = await pendingOf(session, runId);
+    if (status !== "approved" || pending.length === 0)
+        return { failed: 0, done: 0 };
+    ctx.out(`Uploading ${plural(pending.length, "media file")} of the plan to Mapled…`);
+    const results = await uploadAll(session, ctx.fetch, root, pending, runId);
+    for (const r of results)
+        ctx.out(uploadLine(r));
+    const failed = results.filter((r) => !r.ok).length;
+    return { failed, done: results.length - failed };
+}
+/** `mapled media upload [<path | url>…] [--run <runId>] [--json]` — files
+    of this repository or public addresses into the project's Media.
+    With --run, every media file of that approved setup plan (or the ones
+    named) is uploaded as the plan's, for apply_setup_plan to put into
+    the records. */
+export async function mediaUpload(ctx, flags, sources) {
+    const runId = stringFlag(flags, "run");
+    if (runId !== undefined && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(runId)) {
+        throw new CliError("--run takes the id of a setup run — the runId propose_setup_plan answered.", 2);
+    }
+    if (runId === undefined && sources.length === 0) {
+        throw new CliError("What to upload? Name files of this repository or public addresses, or pass --run <runId> for a setup plan's media.", 2);
+    }
+    const { found, session } = await openSession(ctx, flags);
+    let list = sources;
+    if (runId !== undefined && list.length === 0) {
+        const run = await pendingOf(session, runId);
+        if (run.status !== "approved") {
+            throw new CliError(run.status === "awaiting_approval"
+                ? "The plan is still waiting for approval. Upload its media once the person approves it."
+                : "This run takes no more media: its plan isn't approved or was applied already.");
+        }
+        if (run.pending.length === 0) {
+            ctx.out(run.total === 0 ? "The plan names no media." : `Every media file of the plan is in Mapled (${run.total}). Apply the plan next.`);
+            return 0;
+        }
+        list = run.pending;
+    }
+    const results = await uploadAll(session, ctx.fetch, found.dir, list, runId);
+    if (flags.json) {
+        ctx.out(JSON.stringify(results, null, 2));
+    }
+    else {
+        for (const r of results)
+            ctx.out(uploadLine(r));
+        const failed = results.filter((r) => !r.ok).length;
+        ctx.out(failed === 0
+            ? `Uploaded ${plural(results.length, "file")} to Mapled's Media.${runId ? " Apply the plan next." : ""}`
+            : `${plural(failed, "file")} didn't upload. Fix ${failed === 1 ? "it" : "them"} and run this again${runId ? ", or apply with skipMissingMedia: true to leave those fields empty" : ""}.`);
+    }
+    return results.every((r) => r.ok) ? 0 : 1;
+}
+/** `--wait` waits this long by default: under the two minutes an agent's
+    shell gives a command unless it asks for more. */
+const WAIT_SECONDS = 90;
+const WAIT_MAX_SECONDS = 600;
+const WAIT_POLL_MS = 3000;
+/** Seconds `tool <name> --wait[=<seconds>]` may wait; 0 without it. */
+function waitSeconds(flags, name) {
+    const value = flags.wait;
+    if (value === undefined)
+        return 0;
+    if (name !== "get_setup_run")
+        throw new CliError("--wait works with get_setup_run only.", 2);
+    if (value === true)
+        return WAIT_SECONDS;
+    const seconds = Number(value);
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > WAIT_MAX_SECONDS) {
+        throw new CliError(`--wait takes whole seconds from 1 to ${WAIT_MAX_SECONDS}.`, 2);
+    }
+    return seconds;
+}
+function awaitingApproval(answer) {
+    const text = answer.content?.find((part) => part.type === "text")?.text;
+    try {
+        return JSON.parse(text ?? "").run?.status === "awaiting_approval";
+    }
+    catch {
+        return false;
+    }
+}
+export async function openSession(ctx, flags) {
     const found = await findConfig(ctx.cwd);
     if (!found)
         throw new CliError(`No ${CONFIG_FILE} here or above. Run \`mapled project link\` first.`);

package/dist/envPush.d.ts

@@ -0,0 +1,44 @@
+import { type ParsedArgs } from "./args.js";
+import { type Ctx } from "./commands.js";
+/** `mapled env push --host vercel|netlify|cloudflare` — the site's server
+    key (Live data, the Application Data API) put on its host without
+    passing through the agent that runs this. The command asks Mapled for
+    a key of that host with the SHA-256 of a verifier it keeps in memory,
+    prints the link an owner of the project confirms on (the trusted
+    screen, S-44), waits for the decision, claims the key with the
+    verifier and hands it to the host's own CLI — on stdin where the CLI
+    takes it so, as an argument only where it has no other form.
+
+    The key is never printed, logged, written to disk, put in an
+    environment or included in `--json`: the host CLI's output is kept and
+    shown only when it fails, every occurrence of the key replaced by its
+    prefix. The agent sees the link, the decision and the prefix. */
+export type Host = "vercel" | "netlify" | "cloudflare";
+export declare const ENV_NAME = "MAPLED_SERVER_KEY";
+/** A process run to its end: its exit code and what it wrote. `missing` —
+    the program isn't there to run (ENOENT). */
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+    missing?: boolean;
+};
+export type Runner = (cmd: string, args: string[], opts: {
+    cwd: string;
+    input?: string;
+}) => Promise<RunResult>;
+/** The default runner: no shell (but on Windows, where the CLIs are
+    `.cmd` shims), the parent's environment untouched, stdin closed after
+    `input`, output kept — never streamed to the terminal. */
+export declare const runProcess: Runner;
+/** Every occurrence of the key in a text, as its prefix and an ellipsis. */
+export declare function redact(text: string, key: string, prefix: string): string;
+/** The environments wrangler.toml names, in each form TOML allows:
+    `[env.<name>]` headers, keys of an `[env]` table (`<name> = {…}`) and
+    dotted keys (`env.<name>.vars = …`). `opaque` — it has an `env` this
+    reading can't name (`env = {…}` inline). */
+export declare function tomlEnvs(toml: string): {
+    names: string[];
+    opaque: boolean;
+};
+export declare function envPush(ctx: Ctx, flags: ParsedArgs["flags"], run?: Runner): Promise<number>;

package/dist/envPush.js

@@ -0,0 +1,285 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { ApiError } from "./api.js";
+import { stringFlag } from "./args.js";
+import { openSession } from "./commands.js";
+import { CliError } from "./errors.js";
+const HOSTS = ["vercel", "netlify", "cloudflare"];
+const HOST_NAMES = { vercel: "Vercel", netlify: "Netlify", cloudflare: "Cloudflare" };
+/** The host's CLI as installed (on PATH) or through npx. */
+const HOST_CLI = {
+    vercel: { bin: "vercel", pkg: "vercel" },
+    netlify: { bin: "netlify", pkg: "netlify-cli" },
+    cloudflare: { bin: "wrangler", pkg: "wrangler" },
+};
+export const ENV_NAME = "MAPLED_SERVER_KEY";
+const RUN_TIMEOUT_MS = 180_000;
+/** The default runner: no shell (but on Windows, where the CLIs are
+    `.cmd` shims), the parent's environment untouched, stdin closed after
+    `input`, output kept — never streamed to the terminal. */
+export const runProcess = (cmd, args, opts) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(r);
+    };
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"], shell: process.platform === "win32", windowsHide: true });
+    const timer = setTimeout(() => {
+        child.kill();
+        done({ code: 124, stdout, stderr: `${stderr}\n(timed out)` });
+    }, RUN_TIMEOUT_MS);
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.on("error", (err) => done({ code: 127, stdout, stderr: err.message, missing: err.code === "ENOENT" }));
+    child.on("close", (code) => done({ code: code ?? 1, stdout, stderr }));
+    child.stdin.on("error", () => { });
+    child.stdin.end(opts.input ?? "");
+});
+/** Every occurrence of the key in a text, as its prefix and an ellipsis. */
+export function redact(text, key, prefix) {
+    return key ? text.split(key).join(`${prefix}…`) : text;
+}
+async function hostCli(ctx, run, host, cwd) {
+    const { bin, pkg } = HOST_CLI[host];
+    const probe = await run(bin, ["--version"], { cwd });
+    if (!probe.missing)
+        return { run: (args, input) => run(bin, args, { cwd, input }), shown: bin };
+    const viaNpx = await run("npx", ["-y", pkg, "--version"], { cwd });
+    if (viaNpx.missing || viaNpx.code !== 0) {
+        throw new CliError(`${HOST_NAMES[host]}'s CLI isn't installed and npx couldn't run it. Install it with \`npm install -g ${pkg}\`, then run this again.`);
+    }
+    ctx.out(`Using ${pkg} through npx.`);
+    return { run: (args, input) => run("npx", ["-y", pkg, ...args], { cwd, input }), shown: `npx ${pkg}` };
+}
+const exists = async (file) => access(file).then(() => true, () => false);
+/** The host's CLI is signed in, and this directory is the site's there. */
+async function preflight(host, cli, cwd) {
+    if (host === "vercel") {
+        if ((await cli.run(["whoami"])).code !== 0) {
+            throw new CliError(`Vercel's CLI isn't signed in. Run \`${cli.shown} login\`, then run this again.`);
+        }
+        if (!(await exists(path.join(cwd, ".vercel", "project.json")))) {
+            throw new CliError(`This directory isn't linked to a Vercel project. Run \`${cli.shown} link\` here, then run this again.`);
+        }
+        return;
+    }
+    if (host === "netlify") {
+        const status = await cli.run(["status"]);
+        if (status.code !== 0 || /not logged in|log in/i.test(`${status.stdout}\n${status.stderr}`)) {
+            throw new CliError(`Netlify's CLI isn't signed in. Run \`${cli.shown} login\`, then run this again.`);
+        }
+        if (!(await exists(path.join(cwd, ".netlify", "state.json")))) {
+            throw new CliError(`This directory isn't linked to a Netlify site. Run \`${cli.shown} link\` here, then run this again.`);
+        }
+        return;
+    }
+    const who = await cli.run(["whoami"]);
+    if (who.code !== 0 || /not authenticated/i.test(`${who.stdout}\n${who.stderr}`)) {
+        throw new CliError(`Wrangler isn't signed in to Cloudflare. Run \`${cli.shown} login\`, then run this again.`);
+    }
+    const configs = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"];
+    if (!(await Promise.all(configs.map((f) => exists(path.join(cwd, f))))).some(Boolean)) {
+        throw new CliError("No wrangler.toml here. Run this from the Worker's directory, where Wrangler finds its configuration.");
+    }
+}
+function stepsFor(host, key, workerEnv) {
+    if (host === "vercel") {
+        const steps = [];
+        // one overwrite per environment, never a remove then an add: a
+        // deployment that starts between the two would build without the key
+        for (const env of ["production", "preview"]) {
+            steps.push({ args: ["env", "add", ENV_NAME, env, "--force"], input: `${key}\n`, what: `set the ${env} value` });
+        }
+        return { steps, where: " (production, preview)" };
+    }
+    if (host === "netlify") {
+        // the Netlify CLI takes a value as an argument only
+        return { steps: [{ args: ["env:set", ENV_NAME, key], what: "set the value" }], where: "" };
+    }
+    // a named Wrangler environment is a Worker of its own: the secret goes to the one deployed
+    const args = ["secret", "put", ENV_NAME, ...(workerEnv ? ["--env", workerEnv] : [])];
+    return { steps: [{ args, input: `${key}\n`, what: "put the secret" }], where: workerEnv ? ` (Worker secret, ${workerEnv})` : " (Worker secret)" };
+}
+/** A TOML key path (`env.production`, `"env"."live"`, `env . a`) as its
+    parts; null when the text is no key path. */
+function keyPath(text) {
+    const parts = [];
+    const re = /\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|([A-Za-z0-9_-]+))\s*(\.|$)/y;
+    let at = 0;
+    while (at < text.length) {
+        re.lastIndex = at;
+        const m = re.exec(text);
+        if (!m)
+            return null;
+        parts.push(m[1] ?? m[2] ?? m[3]);
+        at = re.lastIndex;
+        if (m[4] !== ".")
+            break;
+    }
+    return at === text.length && parts.length ? parts : null;
+}
+/** The environments wrangler.toml names, in each form TOML allows:
+    `[env.<name>]` headers, keys of an `[env]` table (`<name> = {…}`) and
+    dotted keys (`env.<name>.vars = …`). `opaque` — it has an `env` this
+    reading can't name (`env = {…}` inline). */
+export function tomlEnvs(toml) {
+    const names = new Set();
+    let opaque = false;
+    let table = [];
+    for (const raw of toml.split(/\r?\n/)) {
+        // the line up to a comment that isn't inside a string
+        const line = (/^(?:[^"'#]|"(?:[^"\\]|\\.)*"|'[^']*')*/.exec(raw)?.[0] ?? "").trim();
+        const header = /^\[\[?([^\[\]]*)\]\]?$/.exec(line);
+        if (header) {
+            table = keyPath(header[1]) ?? [];
+            if (table[0] === "env" && table[1] !== undefined)
+                names.add(table[1]);
+            continue;
+        }
+        const eq = /^((?:[^="']|"(?:[^"\\]|\\.)*"|'[^']*')+)=/.exec(line);
+        const key = eq ? keyPath(eq[1].trim()) : null;
+        if (!key)
+            continue;
+        const full = [...table, ...key];
+        if (full[0] !== "env")
+            continue;
+        if (full[1] !== undefined)
+            names.add(full[1]);
+        else
+            opaque = true;
+    }
+    return { names: [...names], opaque };
+}
+/** The environments a Worker's configuration names (wrangler.toml —
+    `tomlEnvs`; `"env": {…}` in wrangler.json(c)); none when it names none
+    or can't be read. `opaque` — it has environments whose names this
+    reading doesn't get. */
+async function wranglerEnvs(cwd) {
+    const names = new Set();
+    let opaque = false;
+    const toml = await readFile(path.join(cwd, "wrangler.toml"), "utf8").catch(() => null);
+    if (toml !== null) {
+        const found = tomlEnvs(toml);
+        for (const name of found.names)
+            names.add(name);
+        opaque = found.opaque;
+    }
+    for (const file of ["wrangler.json", "wrangler.jsonc"]) {
+        const text = await readFile(path.join(cwd, file), "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        try {
+            // comments and trailing commas of jsonc, outside strings
+            const plain = text.replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? "")
+                .replace(/,(\s*[}\]])/g, "$1");
+            const env = JSON.parse(plain).env;
+            if (env && typeof env === "object" && !Array.isArray(env))
+                for (const name of Object.keys(env))
+                    names.add(name);
+        }
+        catch {
+            // unreadable: Wrangler says what is wrong when it runs
+        }
+    }
+    return { names: [...names], opaque };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Until the request is decided: applied, or a CliError saying why not. */
+async function decision(ctx, session, asked) {
+    const deadline = asked.expiresAt ? new Date(asked.expiresAt).getTime() : Date.now() + 60 * 60_000;
+    let current = asked;
+    for (;;) {
+        if (current.status === "applied")
+            return;
+        if (current.status === "denied")
+            throw new CliError("An owner denied the request in Mapled. Nothing was set.");
+        if (current.status === "expired")
+            throw new CliError("The request expired before an owner confirmed it. Run this again.");
+        if (current.status === "failed")
+            throw new CliError(current.error ?? "The request failed in Mapled. Run this again.");
+        if (Date.now() >= deadline)
+            throw new CliError("No owner confirmed the request in time. Run this again.");
+        await sleep(Math.min(ctx.pollMs ?? 2000, Math.max(0, deadline - Date.now())));
+        current = (await session.get(`/v1/agent/confirmations/${current.id}`)).confirmation;
+    }
+}
+export async function envPush(ctx, flags, run = ctx.run ?? runProcess) {
+    const host = stringFlag(flags, "host");
+    if (!host || !HOSTS.includes(host)) {
+        throw new CliError(`Name the site's host: \`mapled env push --host ${HOSTS.join("|")}\`.`, 2);
+    }
+    const which = host;
+    const name = HOST_NAMES[which];
+    const { found, session } = await openSession(ctx, flags);
+    const cwd = ctx.cwd;
+    const workerEnv = stringFlag(flags, "env") ?? null;
+    if (workerEnv !== null && (which !== "cloudflare" || !/^[A-Za-z0-9_-]+$/.test(workerEnv))) {
+        throw new CliError(which === "cloudflare" ? "--env takes the name of an environment in the Worker's configuration." : "--env names a Wrangler environment: use it with --host cloudflare.", 2);
+    }
+    const cli = await hostCli(ctx, run, which, cwd);
+    await preflight(which, cli, cwd);
+    if (which === "cloudflare") {
+        const { names: envs, opaque } = await wranglerEnvs(cwd);
+        if (workerEnv === null && (envs.length > 0 || opaque)) {
+            const listed = envs.length ? ` (${envs.join(", ")})` : "";
+            throw new CliError(`This Worker's configuration has environments${listed}. Name the one the site is deployed to: \`mapled env push --host cloudflare --env ${envs[0] ?? "<name>"}\`.`, 2);
+        }
+        if (workerEnv !== null && !opaque && !envs.includes(workerEnv)) {
+            throw new CliError(`The Worker's configuration has no environment ${workerEnv}${envs.length ? ` (it has ${envs.join(", ")})` : ""}.`, 2);
+        }
+    }
+    // the verifier stays in this process: Mapled gets its hash, the key goes only to the one who holds it
+    const verifier = randomBytes(32).toString("hex");
+    const challenge = createHash("sha256").update(verifier).digest("hex");
+    let asked;
+    try {
+        asked = await session.send("POST", "/v1/agent/server-keys", { host: which, challenge });
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            throw new CliError(err.message);
+        throw err;
+    }
+    ctx.out(`Give the person this link to confirm: ${asked.reviewUrl}`);
+    ctx.out(`Waiting for an owner of ${session.conn.projectName} to confirm in Mapled…`);
+    await decision(ctx, session, asked.confirmation);
+    let claimed;
+    try {
+        claimed = await session.send("POST", "/v1/agent/server-keys/claim", {
+            confirmationId: asked.confirmation.id,
+            verifier,
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            throw new CliError(err.message);
+        throw err;
+    }
+    const { key, prefix } = claimed;
+    const shown = `${prefix}…`;
+    const { steps, where } = stepsFor(which, key, workerEnv);
+    for (const step of steps) {
+        const result = await cli.run(step.args, step.input);
+        if (result.code === 0 || step.optional)
+            continue;
+        const output = redact(`${result.stdout}\n${result.stderr}`, key, prefix).trim();
+        if (output)
+            for (const line of output.split("\n"))
+                ctx.out(`  ${line}`);
+        throw new CliError(`${name}'s CLI couldn't ${step.what} of ${ENV_NAME} (exit ${result.code}). Mapled made the key ${shown}; run this again to make another one once the host's CLI works.`);
+    }
+    if (flags.json) {
+        ctx.out(JSON.stringify({ host: which, variable: ENV_NAME, prefix, confirmationId: asked.confirmation.id, project: found.config.project }, null, 2));
+    }
+    else {
+        ctx.out(`✓ ${ENV_NAME} set on ${name}${where} — ${shown}. Redeploy the site for it to apply.`);
+    }
+    return 0;
+}

package/dist/index.js

@@ -3,8 +3,9 @@ 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, integrationReport, link, login, logout, manifestValidate, mdPull, preview, scan, connect, tool, tools, schemaDiff, schemaPull, } from "./commands.js";
+import { bindingsPull, bindingsPush, doctor, formsCreate, formsList, generate, integrationReport, link, login, logout, manifestValidate, mdPull, mediaUpload, preview, scan, connect, tool, tools, schemaDiff, schemaPull, } from "./commands.js";
 import { credentialsPath } from "./credentials.js";
+import { envPush } from "./envPush.js";
 import { CliError } from "./errors.js";
 /** `mapled` — sign in, link a repository to its project, generate types
     for the content, keep the schema pin, the site manifest and MAPLED.md
@@ -16,6 +17,7 @@ Usage
   mapled connect [--project <id>]                    Connect this repository: sign in, write mapled.json, print the guide for AI agents
   mapled tools [--json]                               List the Mapled tools an agent can call
   mapled tool <name> [<json> | --input <file>]        Call one tool — the same ones the MCP server offers
+                                                      get_setup_run --wait[=<s>] waits (90 s by default) for the plan's approval
   mapled auth login [--api <origin>] [--no-browser]   Sign in to a project in your browser
   mapled auth logout [--all]                          Revoke this machine's access to the linked project
   mapled project link [--project <id>]                Write mapled.json for this repository
@@ -27,11 +29,13 @@ Usage
   mapled bindings push [--dry-run]                    Push mapled/manifest.json so Mapled grades every binding
   mapled bindings pull [--force]                      Write the pushed manifest into mapled/manifest.json
   mapled md pull [--force]                            Write MAPLED.md, the guide for the next agent, from the project
+  mapled media upload [<path | url>…] [--run <runId>] [--json]   Upload images and files into Media; --run uploads every one a setup plan names
   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] [--load-config]              Check the integration end to end; --load-config runs a next.config doctor can't read, as next build does
   mapled integration report [--json] [--verify]       Show the last setup run's verification checklist and report
   mapled preview [<collection> [<slug>]] [--locale <code>] [--open]   Print a one-time Preview link that shows the drafts on the site
+  mapled env push --host <vercel|netlify|cloudflare> [--env <name>] [--json]   Put the site's server key on its host once an owner confirms it in Mapled (--env: the Wrangler environment); the key is never printed
 
 Options
   --version, -v   Print the version
@@ -126,6 +130,8 @@ async function main(argv) {
         case "md pull":
             await mdPull(ctx, flags);
             return 0;
+        case "media upload":
+            return mediaUpload(ctx, flags, words.slice(2));
         case "forms create":
             await formsCreate(ctx, flags, words.slice(2));
             return 0;
@@ -139,6 +145,8 @@ async function main(argv) {
         case "preview":
             await preview(ctx, flags, words.slice(1));
             return 0;
+        case "env push":
+            return envPush(ctx, flags);
         case "auth":
         case "project":
         case "types":
@@ -147,7 +155,9 @@ async function main(argv) {
         case "bindings":
         case "md":
         case "forms":
+        case "media":
         case "integration":
+        case "env":
             console.log(HELP);
             return 2;
         default:

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,131 @@
+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",
+};
+/** What Media's upload says: "Up to 10 MB per image"; a PDF 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 or PDF." };
+    const bytes = await readFile(file);
+    const limit = mime === "application/pdf" ? FILE_LIMIT : IMAGE_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.15.0",
+  "version": "0.17.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",