@mapled/cli 0.14.6 → 0.15.0

package/README.md

@@ -16,6 +16,26 @@ Node 18 or newer. No dependencies. Prefer a global install? `npm install -g @map
 
 Connecting a site without an AI agent? [Integrate by hand](https://www.npmjs.com/package/@mapled/next#integrate-by-hand) in the `@mapled/next` README walks through the whole integration — modeling the content, reading it, the publish webhook, preview, forms — and uses these commands along the way.
 
+## For AI agents
+
+Mapled is a hosted headless CMS for sites built with AI: the owner edits content in Mapled, the site reads published content through a small SDK, and you connect the two. Everything below runs from the shell of the session you are already in — no MCP server to register, no restart.
+
+```bash
+npx @mapled/cli connect --project <id>
+```
+
+The browser opens Mapled on that project and the person clicks Authorize; nothing is copied or pasted. The command writes `mapled.json` and prints Mapled's guide for agents (also at https://api.mapled.io/agents.md). Run again in a connected repository — or in a subdirectory of one — it opens no browser. The guide is read from Mapled, or from the origin you name with `--api` on that run; an origin that only `mapled.json` names never serves it, and a first sign-in there asks for `--api` too. Without `--project` the person picks the project in the browser.
+
+```bash
+npx @mapled/cli tools
+npx @mapled/cli tool get_schema
+npx @mapled/cli tool propose_setup_plan --input plan.json
+```
+
+`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.
+
+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.
+
 ## Sign in
 
 ```bash
@@ -271,7 +291,9 @@ Prints a Preview link — the one the **Preview** button in Mapled opens: the si
 
 - `--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`, `integration report`, `schema diff`, `scan`, `manifest validate`, `forms list`, `preview`)
+- `--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`)
 - `--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/api.d.ts

@@ -7,7 +7,7 @@ export declare class ApiError extends Error {
     constructor(status: number, code: string | null, message: string);
 }
 export type Method = "GET" | "POST" | "PATCH" | "DELETE";
-export declare function apiRequest<T>(api: string, method: Method, path: string, token: string, body: unknown, f: Fetch): Promise<T>;
+export declare function apiRequest<T>(api: string, method: Method, path: string, token: string, body: unknown, f: Fetch, accept?: string): Promise<T>;
 export declare function apiGet<T>(api: string, path: string, token: string, f: Fetch): Promise<T>;
 /** A signed-in connection with its store: reads refresh the access
     token when it is about to expire or when the API says it did, and
@@ -20,6 +20,10 @@ export declare class Session {
     constructor(store: CredentialsFile, file: string, conn: Connection, f: Fetch);
     get<T>(path: string): Promise<T>;
     send<T>(method: Method, path: string, body: unknown): Promise<T>;
+    /** One JSON-RPC call to the hosted MCP endpoint — the tools an agent
+        gets over MCP, from the shell (the endpoint is stateless: a call
+        needs no `initialize`). */
+    rpc<T>(method: string, params?: unknown): Promise<T>;
     private request;
     private refresh;
 }

package/dist/api.js

@@ -1,5 +1,5 @@
 import { upsertConnection, writeCredentials } from "./credentials.js";
-import { CliError } from "./errors.js";
+import { CliError, SignInNeeded } from "./errors.js";
 import { refreshTokens } from "./oauth.js";
 /** Calls to the agent API (/v1/agent/*) with a connection's bearer token. */
 export class ApiError extends Error {
@@ -12,14 +12,14 @@ export class ApiError extends Error {
         this.code = code;
     }
 }
-export async function apiRequest(api, method, path, token, body, f) {
+export async function apiRequest(api, method, path, token, body, f, accept = "application/json") {
     let res;
     try {
         res = await f(`${api}${path}`, {
             method,
             headers: {
                 authorization: `Bearer ${token}`,
-                accept: "application/json",
+                accept,
                 ...(body !== undefined ? { "content-type": "application/json" } : {}),
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
@@ -57,19 +57,29 @@ export class Session {
     send(method, path, body) {
         return this.request(method, path, body);
     }
-    async request(method, path, body) {
+    /** One JSON-RPC call to the hosted MCP endpoint — the tools an agent
+        gets over MCP, from the shell (the endpoint is stateless: a call
+        needs no `initialize`). */
+    async rpc(method, params) {
+        const answer = await this.request("POST", "/mcp", { jsonrpc: "2.0", id: 1, method, ...(params !== undefined ? { params } : {}) }, "application/json, text/event-stream");
+        if (answer?.error || answer?.result === undefined) {
+            throw new CliError(answer?.error?.message ?? "Mapled gave no answer. Try again.");
+        }
+        return answer.result;
+    }
+    async request(method, path, body, accept) {
         if (new Date(this.conn.expiresAt).getTime() - Date.now() < 60_000)
             await this.refresh();
         try {
-            return await apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
+            return await apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f, accept);
         }
         catch (err) {
             if (err instanceof ApiError && err.status === 401) {
                 if (err.code === "TOKEN_EXPIRED") {
                     await this.refresh();
-                    return apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f);
+                    return apiRequest(this.conn.api, method, path, this.conn.accessToken, body, this.f, accept);
                 }
-                throw new CliError(`The connection to ${this.conn.projectName} was revoked. Run \`mapled auth login\` to sign in again.`);
+                throw new SignInNeeded(`The connection to ${this.conn.projectName} was revoked. Run \`mapled auth login\` to sign in again.`);
             }
             throw err;
         }
@@ -80,7 +90,7 @@ export class Session {
             tokens = await refreshTokens(this.conn.api, this.conn.clientId, this.conn.refreshToken, this.f);
         }
         catch {
-            throw new CliError(`Your sign-in to ${this.conn.projectName} expired. Run \`mapled auth login\` to sign in again.`);
+            throw new SignInNeeded(`Your sign-in to ${this.conn.projectName} expired. Run \`mapled auth login\` to sign in again.`);
         }
         this.conn = { ...this.conn, ...tokens };
         this.store = upsertConnection(this.store, this.conn);

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"]);
+const VALUE_FLAGS = new Set(["api", "project", "out", "key", "locale", "input"]);
 export function parseArgs(argv) {
     const words = [];
     const flags = {};

package/dist/commands.d.ts

@@ -22,6 +22,19 @@ type Flags = ParsedArgs["flags"];
 export declare function login(ctx: Ctx, flags: Flags): Promise<Connection>;
 export declare function logout(ctx: Ctx, flags: Flags): Promise<void>;
 export declare function link(ctx: Ctx, flags: Flags): Promise<FoundConfig>;
+/** `mapled connect [--project <id>]` — everything an agent needs before
+    its first tool call, in one run: sign in through the browser (the
+    consent opens on the named project), write mapled.json, print
+    Mapled's guide for agents. A repository that is already connected
+    opens no browser. */
+export declare function connect(ctx: Ctx, flags: Flags): Promise<void>;
+/** `mapled tools [--json]` — every tool the hosted MCP endpoint offers,
+    with its description and input: what `mapled tool` can call. */
+export declare function tools(ctx: Ctx, flags: Flags): Promise<void>;
+/** `mapled tool <name> [<json> | --input <file>]` — one tool call, the
+    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>;
 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

@@ -2,10 +2,10 @@ import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { ApiError, apiGet, Session } from "./api.js";
 import { stringFlag } from "./args.js";
-import { CONFIG_FILE, DEFAULT_TYPES_PATH, findConfig, resolveApi, writeConfig } from "./config.js";
+import { CONFIG_FILE, DEFAULT_API, DEFAULT_TYPES_PATH, findConfig, resolveApi, writeConfig } from "./config.js";
 import { connectionsFor, findConnection, readCredentials, removeConnection, upsertConnection, writeCredentials, } from "./credentials.js";
 import * as dr from "./doctor.js";
-import { CliError } from "./errors.js";
+import { CliError, SignInNeeded } from "./errors.js";
 import { checkManifest, compareManifests, fileExistsIn, MANIFEST_FILE, manifestSummary, orderManifest, parseManifest, plural, readManifestFile, writeManifestFile, } from "./manifest.js";
 import { authorize, clientKnown, exchangeCode, registerClient, revokeToken } from "./oauth.js";
 import { formatChecks, GLYPH, paint, summarize, useColor } from "./output.js";
@@ -28,6 +28,14 @@ async function ensureClient(store, api, f) {
         clientId,
     };
 }
+/** `--project <id>`: a project id as Mapled writes it, or nothing. */
+function projectFlag(flags) {
+    const value = stringFlag(flags, "project")?.toLowerCase();
+    if (value !== undefined && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)) {
+        throw new CliError("--project takes a project id — the one in the prompt copied from Mapled.");
+    }
+    return value;
+}
 export async function login(ctx, flags) {
     const found = await findConfig(ctx.cwd);
     const api = resolveApi(found?.config ?? null, stringFlag(flags, "api"), ctx.env);
@@ -38,6 +46,7 @@ export async function login(ctx, flags) {
         openBrowser: flags["no-browser"] ? async () => false : ctx.openBrowser,
         log: ctx.out,
         timeoutMs: ctx.loginTimeoutMs,
+        project: projectFlag(flags),
     });
     const tokens = await exchangeCode(api, client.clientId, grant, ctx.fetch);
     const status = await apiGet(api, "/v1/agent/integration", tokens.accessToken, ctx.fetch);
@@ -51,7 +60,7 @@ export async function login(ctx, flags) {
     };
     store = upsertConnection(store, conn);
     await writeCredentials(ctx.credentialsFile, store);
-    ctx.out(`Signed in to ${conn.projectName}.`);
+    ctx.out(`Signed in to ${clean(conn.projectName, 80)}.`);
     if (!found)
         ctx.out("Next: run `mapled project link` in the site's repository.");
     else if (found.config.project !== conn.projectId) {
@@ -131,6 +140,122 @@ export async function link(ctx, flags) {
     ctx.out("Next: `mapled types generate`, then `mapled doctor`.");
     return { path: file, dir: path.resolve(ctx.cwd), config };
 }
+/** `mapled connect [--project <id>]` — everything an agent needs before
+    its first tool call, in one run: sign in through the browser (the
+    consent opens on the named project), write mapled.json, print
+    Mapled's guide for agents. A repository that is already connected
+    opens no browser. */
+export async function connect(ctx, flags) {
+    const wanted = projectFlag(flags);
+    // the nearest mapled.json, here or above: a subdirectory of a connected
+    // repository is connected
+    const linked = await findConfig(ctx.cwd);
+    const flagApi = stringFlag(flags, "api");
+    const api = resolveApi(linked?.config ?? null, flagApi, ctx.env);
+    // The guide is text an agent follows, so it comes from Mapled or from
+    // an origin the person named on this run (the flag, the environment) —
+    // never from one only a file of the repository names: mapled.json is
+    // committed, and whoever wrote it would be writing the agent's guide.
+    const guideApi = !flagApi && linked?.config.api && api !== DEFAULT_API ? DEFAULT_API : api;
+    const store = await readCredentials(ctx.credentialsFile);
+    const target = wanted ?? linked?.config.project;
+    let conn = target ? findConnection(store, api, target) : undefined;
+    if (conn) {
+        // a connection revoked in Integrations is of no use: ask the API once
+        try {
+            await new Session(store, ctx.credentialsFile, conn, ctx.fetch).get("/v1/agent/integration");
+            ctx.out(`Already connected to ${clean(conn.projectName, 80)}.`);
+        }
+        catch (err) {
+            // only a connection that is gone asks for a new sign-in: an API
+            // that can't be reached right now is said as it is
+            if (!(err instanceof SignInNeeded))
+                throw err;
+            conn = undefined;
+        }
+    }
+    if (!conn && api !== guideApi) {
+        // Signing in sends the person's browser to this origin, and what it
+        // answers is printed for the agent: an origin only the committed
+        // mapled.json names has to be named by the person too.
+        throw new CliError(`${CONFIG_FILE} here names another API, ${api}. To sign in there, run \`mapled connect --api ${api}\`.`);
+    }
+    if (!conn) {
+        // a repository linked before opens the consent on its own project
+        conn = await login(ctx, target ? { ...flags, project: target } : flags);
+        if (wanted && conn.projectId !== wanted) {
+            ctx.out(`Note: ${clean(conn.projectName, 80)} was picked in the browser — not the project the prompt named. Continuing with it.`);
+        }
+    }
+    if (!linked || linked.config.project !== conn.projectId) {
+        await link(ctx, { ...flags, project: conn.projectId });
+    }
+    ctx.out("");
+    try {
+        const res = await ctx.fetch(`${guideApi}/agents.md`);
+        if (!res.ok)
+            throw new Error();
+        for (const line of (await res.text()).split("\n"))
+            ctx.out(line);
+    }
+    catch {
+        ctx.out(`Connected. The guide for agents: ${guideApi}/agents.md`);
+    }
+}
+/** `mapled tools [--json]` — every tool the hosted MCP endpoint offers,
+    with its description and input: what `mapled tool` can call. */
+export async function tools(ctx, flags) {
+    const { session } = await openSession(ctx, flags);
+    const { tools: list } = await session.rpc("tools/list");
+    if (flags.json) {
+        ctx.out(JSON.stringify(list, null, 2));
+        return;
+    }
+    for (const tool of list) {
+        const required = new Set(tool.inputSchema?.required ?? []);
+        const input = Object.keys(tool.inputSchema?.properties ?? {}).map((k) => (required.has(k) ? k : `${k}?`));
+        ctx.out(`${tool.name}${input.length > 0 ? ` { ${input.join(", ")} }` : ""}`);
+        if (tool.description)
+            ctx.out(`  ${tool.description}`);
+        ctx.out("");
+    }
+    ctx.out("Call one: `mapled tool <name> '<json>'` or `mapled tool <name> --input <file.json>`; `mapled tools --json` shows each input's schema.");
+}
+/** `mapled tool <name> [<json> | --input <file>]` — one tool call, the
+    way an MCP client makes it: the answer is printed as Mapled worded
+    it, a refusal exits 1. */
+export async function tool(ctx, flags, words) {
+    const [name, inline] = words;
+    if (!name)
+        throw new CliError("Which tool? `mapled tools` lists them.", 2);
+    const file = stringFlag(flags, "input");
+    if (file !== undefined && inline !== undefined)
+        throw new CliError("Pass the input as JSON or with --input, not both.", 2);
+    let raw = inline ?? "{}";
+    if (file !== undefined) {
+        try {
+            raw = await readFile(path.resolve(ctx.cwd, file), "utf8");
+        }
+        catch {
+            throw new CliError(`Couldn't read ${file}.`);
+        }
+    }
+    let args;
+    try {
+        args = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("The input isn't valid JSON.");
+    }
+    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 });
+    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) {
     const found = await findConfig(ctx.cwd);
     if (!found)

package/dist/doctor.js

@@ -1082,6 +1082,15 @@ export function checkWebhook(webhook, site) {
             detail: `${host} resolves to a private address, which Mapled can't reach. Point the webhook at the public deployment.`,
         };
     }
+    if (last.responseStatus === 503) {
+        // what the SDK's route answers before the site has the signing secret (deployed first, as the README says)
+        return {
+            key: "webhook",
+            label,
+            status: "failed",
+            detail: `The last delivery to ${host} responded 503 — the route answers that while MAPLED_WEBHOOK_SECRET isn't set on the site. Set it there, redeploy, then send a test ping.`,
+        };
+    }
     const reason = last.responseStatus ? `responded ${last.responseStatus}` : (last.error ?? "failed");
     return {
         key: "webhook",

package/dist/errors.d.ts

@@ -4,3 +4,9 @@ export declare class CliError extends Error {
     exitCode: number;
     constructor(message: string, exitCode?: number);
 }
+/** The stored connection no longer works — revoked in Mapled, or its
+    refresh token spent: only a new sign-in helps. A network failure is
+    not this. */
+export declare class SignInNeeded extends CliError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -8,3 +8,12 @@ export class CliError extends Error {
         this.exitCode = exitCode;
     }
 }
+/** The stored connection no longer works — revoked in Mapled, or its
+    refresh token spent: only a new sign-in helps. A network failure is
+    not this. */
+export class SignInNeeded extends CliError {
+    constructor(message) {
+        super(message);
+        this.name = "SignInNeeded";
+    }
+}

package/dist/index.js

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "./args.js";
 import { openBrowser } from "./browser.js";
-import { bindingsPull, bindingsPush, doctor, formsCreate, formsList, generate, integrationReport, link, login, logout, manifestValidate, mdPull, preview, scan, schemaDiff, schemaPull, } from "./commands.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 { credentialsPath } from "./credentials.js";
 import { CliError } from "./errors.js";
 /** `mapled` — sign in, link a repository to its project, generate types
@@ -13,6 +13,9 @@ import { CliError } from "./errors.js";
 const HELP = `mapled — the Mapled CLI
 
 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
   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
@@ -36,6 +39,7 @@ Options
 
 Credentials stay in your user config directory, never in the repository.
 Run it as \`npx @mapled/cli <command>\`, or install it globally with \`npm install -g @mapled/cli\` to get \`mapled\` on your PATH.`;
+const ROOT_COMMANDS = new Set(["preview", "connect", "tools", "tool"]);
 function version() {
     return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 }
@@ -80,8 +84,17 @@ async function main(argv) {
         version: version(),
         credentialsFile: credentialsPath(),
     };
-    // `preview` takes the record it opens as words of its own
-    switch (group === "preview" ? group : `${group} ${sub ?? ""}`.trim()) {
+    // commands of one word: what follows them is theirs (`preview` takes the
+    // record it opens, `tool` the tool it calls)
+    switch (ROOT_COMMANDS.has(group) ? group : `${group} ${sub ?? ""}`.trim()) {
+        case "connect":
+            await connect(ctx, flags);
+            return 0;
+        case "tools":
+            await tools(ctx, flags);
+            return 0;
+        case "tool":
+            return tool(ctx, flags, words.slice(1));
         case "auth login":
             await login(ctx, flags);
             return 0;

package/dist/oauth.d.ts

@@ -30,6 +30,8 @@ export declare function registerClient(api: string, f: Fetch): Promise<string>;
     creates nothing on the server. */
 export declare function clientKnown(api: string, clientId: string, f: Fetch): Promise<boolean>;
 export type AuthorizeDeps = {
+    /** The project the consent screen opens on — a hint; the person still picks. */
+    project?: string;
     openBrowser: (url: string) => Promise<boolean>;
     log: (line: string) => void;
     timeoutMs?: number;

package/dist/oauth.js

@@ -149,6 +149,7 @@ export function authorize(api, clientId, deps) {
                 state,
                 scope: SCOPE,
                 resource: `${api}/mcp`,
+                ...(deps.project ? { project: deps.project } : {}),
             }).toString();
             deps.log(`Opening your browser to sign in to Mapled. If it doesn't open, visit:\n  ${url.toString()}`);
             deps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.14.6",
+  "version": "0.15.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",
@@ -9,6 +9,8 @@
     "cms",
     "headless-cms",
     "cli",
+    "ai-agents",
+    "mcp",
     "typescript",
     "codegen"
   ],