@mapled/cli 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @mapled/cli
+
+The `mapled` command line for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Sign in to a project, link the repository to it, generate TypeScript types for the content your site reads, and check the whole integration in one go.
+
+```bash
+npx @mapled/cli auth login
+npx @mapled/cli project link
+npx @mapled/cli types generate
+npx @mapled/cli doctor
+```
+
+Node 18 or newer. No dependencies. Prefer a global install? `npm install -g @mapled/cli` puts `mapled` on your PATH, and every command below works as `mapled …`.
+
+## Sign in
+
+```bash
+npx @mapled/cli auth login
+```
+
+Your browser opens Mapled; you pick the project and authorize. The CLI is an ordinary OAuth client of Mapled, so the connection shows up in the project's **Integrations** and can be revoked there at any time. Tokens are stored in your user config directory (`~/.config/mapled/credentials.json`, readable only by you) — never in the repository.
+
+`npx @mapled/cli auth logout` revokes the connection of the linked project (`--all` for every project on this machine).
+
+## Link the repository
+
+```bash
+npx @mapled/cli project link
+```
+
+Writes `mapled.json` next to your `package.json`:
+
+```json
+{
+  "project": "bae66c47-…",
+  "types": "mapled-types.ts",
+  "framework": "nextjs"
+}
+```
+
+Only public values live here — the project id, where the generated types go, the framework. Commit it. With more than one signed-in project, pass `--project <id>` or pick from the list.
+
+## Generate types
+
+```bash
+npx @mapled/cli types generate
+```
+
+Reads the project's schema and writes `mapled-types.ts` (the path from `mapled.json`, or `--out <file>`): one interface per collection and single, keyed maps, and doc comments with the field types. Sensitive fields never reach the site and are left out.
+
+```ts
+import type { Article, MapledCollections } from "./mapled-types";
+import { createClient } from "@mapled/next";
+
+const mapled = createClient({ key: process.env.MAPLED_KEY! });
+const { records } = await mapled.getRecords<Article>("articles");
+const home = await mapled.getSingle<MapledCollections["homepage"]>("homepage");
+```
+
+The file names the schema it came from; `mapled doctor` tells you when it is out of date. Run `types generate` again after the schema changes.
+
+## Check the integration
+
+```bash
+npx @mapled/cli doctor
+```
+
+```text
+Mapled doctor — Dolphin Landing
+
+✓ Project link         mapled.json → Dolphin Landing
+✓ Signed in            Mapled CLI • Dolphin Landing
+✓ Generated types      mapled-types.ts matches the schema (3f9a1c2b4d5e)
+✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
+✓ Secrets in git       No env files or Mapled secrets are tracked.
+✓ @mapled/next         0.3.0 (current)
+✓ mapled CLI           0.1.0 (current)
+✓ Revalidation route   app/api/mapled/revalidate/route.ts
+⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.
+✓ Site reads content   Last read 3m ago
+✓ Publish webhook      Delivered 2h ago to dolphin-landing.example
+✓ Preview on the site  Responds at https://dolphin-landing.example/api/mapled/preview
+✓ Bindings             12 healthy • synced 2d ago from Claude Code
+
+1 warning.
+```
+
+The repository side: the link, the sign-in, the generated types, `MAPLED_KEY` and `MAPLED_WEBHOOK_SECRET` in your env files (names only — values are never read out), env files or Mapled secrets tracked by git, the installed `@mapled/next` and CLI versions, the revalidation and preview routes of a Next.js site. The Mapled side, from the same status the AI agent's `check_integration` tool reads: whether the site has read content with the delivery key, the publish webhook and its last delivery, the preview route on the deployed site, the bindings health.
+
+Exit code 1 when something is marked ✗; `--json` prints the checks for scripts and agents.
+
+## 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
+- `MAPLED_CONFIG_DIR` — where credentials live (default: `$XDG_CONFIG_HOME/mapled` or `~/.config/mapled`)

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+import { type Connection, type CredentialsFile } from "./credentials.js";
+import { type Fetch } from "./oauth.js";
+/** Calls to the agent API (/v1/agent/*) with a connection's bearer token. */
+export declare class ApiError extends Error {
+    status: number;
+    code: string | null;
+    constructor(status: number, code: string | null, message: string);
+}
+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
+    the rotated pair is written back before the call returns. */
+export declare class Session {
+    store: CredentialsFile;
+    file: string;
+    conn: Connection;
+    private readonly f;
+    constructor(store: CredentialsFile, file: string, conn: Connection, f: Fetch);
+    get<T>(path: string): Promise<T>;
+    private refresh;
+}

package/dist/api.js

@@ -0,0 +1,72 @@
+import { upsertConnection, writeCredentials } from "./credentials.js";
+import { CliError } 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 {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+export async function apiGet(api, path, token, f) {
+    let res;
+    try {
+        res = await f(`${api}${path}`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
+    }
+    catch {
+        throw new CliError(`Couldn't reach ${api}. Check your connection and try again.`);
+    }
+    const data = (await res.json().catch(() => null));
+    if (!res.ok) {
+        throw new ApiError(res.status, data?.error?.code ?? null, data?.error?.message ?? `Mapled answered ${res.status}.`);
+    }
+    return data;
+}
+/** 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
+    the rotated pair is written back before the call returns. */
+export class Session {
+    store;
+    file;
+    conn;
+    f;
+    constructor(store, file, conn, f) {
+        this.store = store;
+        this.file = file;
+        this.conn = conn;
+        this.f = f;
+    }
+    async get(path) {
+        if (new Date(this.conn.expiresAt).getTime() - Date.now() < 60_000)
+            await this.refresh();
+        try {
+            return await apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 401) {
+                if (err.code === "TOKEN_EXPIRED") {
+                    await this.refresh();
+                    return apiGet(this.conn.api, path, this.conn.accessToken, this.f);
+                }
+                throw new CliError(`The connection to ${this.conn.projectName} was revoked. Run \`mapled auth login\` to sign in again.`);
+            }
+            throw err;
+        }
+    }
+    async refresh() {
+        let tokens;
+        try {
+            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.`);
+        }
+        this.conn = { ...this.conn, ...tokens };
+        this.store = upsertConnection(this.store, this.conn);
+        await writeCredentials(this.file, this.store);
+    }
+}

package/dist/args.d.ts

@@ -0,0 +1,6 @@
+export type ParsedArgs = {
+    words: string[];
+    flags: Record<string, string | true>;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function stringFlag(flags: ParsedArgs["flags"], name: string): string | undefined;

package/dist/args.js

@@ -0,0 +1,52 @@
+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"]);
+export function parseArgs(argv) {
+    const words = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--") {
+            words.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+            if (!name)
+                throw new CliError("Unknown option: --");
+            if (eq !== -1) {
+                flags[name] = arg.slice(eq + 1);
+                continue;
+            }
+            if (VALUE_FLAGS.has(name)) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("-"))
+                    throw new CliError(`--${name} needs a value.`);
+                flags[name] = next;
+                i++;
+                continue;
+            }
+            flags[name] = true;
+            continue;
+        }
+        if (arg === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (arg === "-v") {
+            flags.version = true;
+            continue;
+        }
+        if (arg.startsWith("-") && arg.length > 1)
+            throw new CliError(`Unknown option: ${arg}`);
+        words.push(arg);
+    }
+    return { words, flags };
+}
+export function stringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+/** Opens a URL in the default browser; resolves false when that isn't
+    possible (no desktop, no opener) so the caller prints the link. */
+export declare function openBrowser(url: string): Promise<boolean>;

package/dist/browser.js

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+/** Opens a URL in the default browser; resolves false when that isn't
+    possible (no desktop, no opener) so the caller prints the link. */
+export function openBrowser(url) {
+    return new Promise((resolve) => {
+        const [cmd, args] = process.platform === "darwin"
+            ? ["open", [url]]
+            : process.platform === "win32"
+                ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]]
+                : ["xdg-open", [url]];
+        try {
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/commands.d.ts

@@ -0,0 +1,27 @@
+import { type ParsedArgs } from "./args.js";
+import { type FoundConfig } from "./config.js";
+import { type Connection } from "./credentials.js";
+import { type Fetch } from "./oauth.js";
+/** The four wave-1 commands (§31) plus sign-out. Everything that talks
+    to the world comes in through `Ctx`, so the commands run in tests
+    against a fake API and a temp directory. */
+export type Ctx = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    fetch: Fetch;
+    openBrowser: (url: string) => Promise<boolean>;
+    out: (line: string) => void;
+    /** Picks one of `choices`; rejects when there is no one to ask. */
+    choose: (question: string, choices: string[]) => Promise<number>;
+    version: string;
+    credentialsFile: string;
+    /** How long a sign-in waits for the browser (tests shorten it). */
+    loginTimeoutMs?: number;
+};
+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>;
+export declare function generate(ctx: Ctx, flags: Flags): Promise<void>;
+export declare function doctor(ctx: Ctx, flags: Flags): Promise<number>;
+export {};

package/dist/commands.js

@@ -0,0 +1,211 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { apiGet, Session } from "./api.js";
+import { stringFlag } from "./args.js";
+import { CONFIG_FILE, 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 { authorize, clientKnown, exchangeCode, registerClient, revokeToken } from "./oauth.js";
+import { formatChecks, summarize, useColor } from "./output.js";
+import { generateTypes } from "./types.js";
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+/** 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) {
+    const known = store.clients[api];
+    if (known && (await clientKnown(api, known.clientId, f)))
+        return { store, clientId: known.clientId };
+    const clientId = await registerClient(api, f);
+    return {
+        store: { ...store, clients: { ...store.clients, [api]: { clientId, registeredAt: new Date().toISOString() } } },
+        clientId,
+    };
+}
+export async function login(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    const api = resolveApi(found?.config ?? null, stringFlag(flags, "api"), ctx.env);
+    let store = await readCredentials(ctx.credentialsFile);
+    const client = await ensureClient(store, api, ctx.fetch);
+    store = client.store;
+    const grant = await authorize(api, client.clientId, {
+        openBrowser: flags["no-browser"] ? async () => false : ctx.openBrowser,
+        log: ctx.out,
+        timeoutMs: ctx.loginTimeoutMs,
+    });
+    const tokens = await exchangeCode(api, client.clientId, grant, ctx.fetch);
+    const status = await apiGet(api, "/v1/agent/integration", tokens.accessToken, ctx.fetch);
+    const conn = {
+        api,
+        projectId: status.project.id,
+        projectName: status.project.name,
+        clientId: client.clientId,
+        ...tokens,
+        createdAt: new Date().toISOString(),
+    };
+    store = upsertConnection(store, conn);
+    await writeCredentials(ctx.credentialsFile, store);
+    ctx.out(`Signed in to ${conn.projectName}.`);
+    if (!found)
+        ctx.out("Next: run `mapled project link` in the site's repository.");
+    else if (found.config.project !== conn.projectId) {
+        ctx.out(`Note: ${CONFIG_FILE} here links a different project (${found.config.project}).`);
+    }
+    return conn;
+}
+export async function logout(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    const api = resolveApi(found?.config ?? null, stringFlag(flags, "api"), ctx.env);
+    let store = await readCredentials(ctx.credentialsFile);
+    let targets;
+    if (flags.all) {
+        targets = [...store.connections];
+        if (targets.length === 0)
+            throw new CliError("Not signed in anywhere. Nothing to revoke.");
+    }
+    else if (found) {
+        const conn = findConnection(store, api, found.config.project);
+        if (!conn)
+            throw new CliError(`Not signed in to the project ${CONFIG_FILE} links. Nothing to revoke.`);
+        targets = [conn];
+    }
+    else {
+        const list = connectionsFor(store, api);
+        if (list.length === 0)
+            throw new CliError("Not signed in. Nothing to revoke.");
+        if (list.length === 1)
+            targets = list;
+        else {
+            const i = await ctx.choose("Sign out of which project?", list.map((c) => c.projectName));
+            targets = [list[i]];
+        }
+    }
+    for (const conn of targets) {
+        await revokeToken(conn.api, conn.refreshToken, ctx.fetch);
+        store = removeConnection(store, conn.api, conn.projectId);
+        ctx.out(`Signed out of ${conn.projectName}.`);
+    }
+    await writeCredentials(ctx.credentialsFile, store);
+}
+export async function link(ctx, flags) {
+    const existing = await findConfig(ctx.cwd);
+    const here = existing && existing.dir === path.resolve(ctx.cwd) ? existing : null;
+    const api = resolveApi(here?.config ?? null, stringFlag(flags, "api"), ctx.env);
+    const store = await readCredentials(ctx.credentialsFile);
+    const wanted = stringFlag(flags, "project")?.toLowerCase();
+    const list = connectionsFor(store, api);
+    let conn;
+    if (wanted) {
+        conn = list.find((c) => c.projectId === wanted);
+        if (!conn)
+            throw new CliError(`Not signed in to project ${wanted}. Run \`mapled auth login\` and pick it in the browser.`);
+    }
+    else if (list.length === 1) {
+        conn = list[0];
+    }
+    else if (list.length > 1) {
+        const i = await ctx.choose("Link this repository to which project?", list.map((c) => c.projectName));
+        conn = list[i];
+    }
+    else {
+        ctx.out("Not signed in yet — sign in first.");
+        conn = await login(ctx, flags);
+    }
+    if (!conn)
+        throw new CliError("No project chosen.");
+    const framework = here?.config.framework ?? (await dr.detectFramework(ctx.cwd));
+    const config = {
+        project: conn.projectId,
+        api,
+        types: here?.config.types ?? DEFAULT_TYPES_PATH,
+        ...(framework ? { framework } : {}),
+    };
+    const file = await writeConfig(ctx.cwd, config);
+    ctx.out(`Linked ${path.relative(ctx.cwd, file) || CONFIG_FILE} to ${conn.projectName}.`);
+    ctx.out("Next: `mapled types generate`, then `mapled doctor`.");
+    return { path: file, dir: path.resolve(ctx.cwd), config };
+}
+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.`);
+    const api = resolveApi(found.config, stringFlag(flags, "api"), ctx.env);
+    const store = await readCredentials(ctx.credentialsFile);
+    const conn = findConnection(store, api, found.config.project);
+    if (!conn)
+        throw new CliError("Not signed in to this project. Run `mapled auth login` and pick it in the browser.");
+    return { found, session: new Session(store, ctx.credentialsFile, conn, ctx.fetch) };
+}
+export async function generate(ctx, flags) {
+    const { found, session } = await openSession(ctx, flags);
+    const schema = await session.get("/v1/agent/schema");
+    const generated = generateTypes(schema, { projectName: session.conn.projectName });
+    const out = stringFlag(flags, "out") ?? found.config.types ?? DEFAULT_TYPES_PATH;
+    const file = path.resolve(found.dir, out);
+    await writeFile(file, generated.text);
+    ctx.out(`Wrote ${path.relative(ctx.cwd, file) || out} — ${plural(generated.collections, "collection")}, ` +
+        `${plural(generated.singles, "single")} (schema ${generated.hash}).`);
+}
+export async function doctor(ctx, flags) {
+    const found = await findConfig(ctx.cwd);
+    const dir = found?.dir ?? path.resolve(ctx.cwd);
+    const api = resolveApi(found?.config ?? null, stringFlag(flags, "api"), ctx.env);
+    const store = await readCredentials(ctx.credentialsFile);
+    const conn = found ? findConnection(store, api, found.config.project) : undefined;
+    let status = null;
+    let schema = null;
+    let authError = null;
+    if (conn) {
+        const session = new Session(store, ctx.credentialsFile, conn, ctx.fetch);
+        try {
+            status = await session.get("/v1/agent/integration");
+            schema = await session.get("/v1/agent/schema");
+        }
+        catch (err) {
+            authError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const checks = [];
+    checks.push(dr.checkLink(found ? { path: path.relative(ctx.cwd, found.path) || CONFIG_FILE } : null, status?.project.name ?? conn?.projectName ?? null));
+    checks.push(dr.checkAuth({ conn: conn ?? null, status, error: authError }));
+    const typesPath = found?.config.types ?? DEFAULT_TYPES_PATH;
+    const existing = await readFile(path.join(dir, typesPath), "utf8").catch(() => null);
+    checks.push(dr.checkTypes(existing, schema ? generateTypes(schema, { projectName: status?.project.name }) : null, typesPath));
+    checks.push(dr.checkEnv(await dr.envNames(dir), ctx.env));
+    checks.push(dr.checkSecrets(await dr.gitFacts(dir)));
+    checks.push(dr.checkSdk(await dr.installedVersion(dir, "@mapled/next"), status?.sdk["@mapled/next"]));
+    checks.push(dr.checkCli(ctx.version, status?.sdk["@mapled/cli"]));
+    const framework = found?.config.framework ?? (await dr.detectFramework(dir));
+    checks.push(dr.checkRoute("revalidate", await dr.findRoute(dir, "revalidate"), framework));
+    checks.push(dr.checkRoute("preview", await dr.findRoute(dir, "preview"), framework));
+    if (status) {
+        checks.push(dr.checkReads(status.delivery.lastReadAt));
+        checks.push(dr.checkWebhook(status.webhook));
+        let origin = null;
+        try {
+            origin = status.webhook.url ? new URL(status.webhook.url).origin : null;
+        }
+        catch {
+            origin = null;
+        }
+        const probe = origin ? await dr.probePreview(origin, status.previewPath, ctx.fetch) : null;
+        checks.push(dr.checkPreviewOnSite(origin, status.previewPath, probe));
+        checks.push(dr.checkBindings(status.bindings));
+    }
+    else {
+        for (const [key, label] of dr.REMOTE_CHECKS)
+            checks.push({ key, label, status: "skipped", detail: "Sign in to check." });
+    }
+    if (flags.json) {
+        ctx.out(JSON.stringify({ project: status?.project ?? (found ? { id: found.config.project } : null), checks }, null, 2));
+    }
+    else {
+        ctx.out(`Mapled doctor${status ? ` — ${status.project.name}` : ""}\n`);
+        ctx.out(formatChecks(checks, useColor(ctx.env)));
+        ctx.out("");
+        ctx.out(summarize(checks));
+    }
+    return checks.some((c) => c.status === "failed") ? 1 : 0;
+}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+/** mapled.json — the repository's link to its project. Only public,
+    non-secret values live here (§31.4): the project id, the API origin
+    when it isn't the default, the generated types path, the framework. */
+export declare const CONFIG_FILE = "mapled.json";
+export declare const DEFAULT_API = "https://api.mapled.io";
+export declare const DEFAULT_TYPES_PATH = "mapled-types.ts";
+export type ProjectConfig = {
+    project: string;
+    api?: string;
+    types?: string;
+    framework?: string;
+};
+export type FoundConfig = {
+    path: string;
+    dir: string;
+    config: ProjectConfig;
+};
+export declare function parseConfig(raw: string, file: string): ProjectConfig;
+/** The nearest mapled.json at or above `startDir`. */
+export declare function findConfig(startDir: string): Promise<FoundConfig | null>;
+export declare function writeConfig(dir: string, config: ProjectConfig): Promise<string>;
+/** Which API to talk to: the flag, then mapled.json, then the
+    environment, then the default. */
+export declare function resolveApi(config: ProjectConfig | null, flagApi: string | undefined, env: NodeJS.ProcessEnv): string;

package/dist/config.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.js";
+/** mapled.json — the repository's link to its project. Only public,
+    non-secret values live here (§31.4): the project id, the API origin
+    when it isn't the default, the generated types path, the framework. */
+export const CONFIG_FILE = "mapled.json";
+export const DEFAULT_API = "https://api.mapled.io";
+export const DEFAULT_TYPES_PATH = "mapled-types.ts";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function parseConfig(raw, file) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${file} isn't valid JSON.`);
+    }
+    const obj = data && typeof data === "object" && !Array.isArray(data) ? data : null;
+    if (!obj || typeof obj.project !== "string" || !UUID_RE.test(obj.project)) {
+        throw new CliError(`${file} has no valid "project" id. Run \`mapled project link\` to link this repository.`);
+    }
+    const config = { project: obj.project.toLowerCase() };
+    if (typeof obj.api === "string" && obj.api.trim())
+        config.api = obj.api.trim().replace(/\/+$/, "");
+    if (typeof obj.types === "string" && obj.types.trim())
+        config.types = obj.types.trim();
+    if (typeof obj.framework === "string" && obj.framework.trim())
+        config.framework = obj.framework.trim();
+    return config;
+}
+/** The nearest mapled.json at or above `startDir`. */
+export async function findConfig(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const file = path.join(dir, CONFIG_FILE);
+        let raw = null;
+        try {
+            raw = await readFile(file, "utf8");
+        }
+        catch {
+            raw = null;
+        }
+        if (raw !== null)
+            return { path: file, dir, config: parseConfig(raw, file) };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export async function writeConfig(dir, config) {
+    const file = path.join(dir, CONFIG_FILE);
+    const body = { project: config.project };
+    if (config.api && config.api !== DEFAULT_API)
+        body.api = config.api;
+    body.types = config.types ?? DEFAULT_TYPES_PATH;
+    if (config.framework)
+        body.framework = config.framework;
+    await writeFile(file, JSON.stringify(body, null, 2) + "\n");
+    return file;
+}
+/** Which API to talk to: the flag, then mapled.json, then the
+    environment, then the default. */
+export function resolveApi(config, flagApi, env) {
+    const raw = flagApi || config?.api || env.MAPLED_API_URL || DEFAULT_API;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CliError(`"${raw}" isn't a valid API origin.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new CliError(`"${raw}" isn't a valid API origin.`);
+    return url.origin;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,34 @@
+/** The machine-local credential store: one OAuth client id per API
+    origin and one connection (project-scoped access + refresh token)
+    per project. Lives outside the repository, mode 0600 — the tokens
+    never touch the project's files (§31.4). */
+export type Connection = {
+    api: string;
+    projectId: string;
+    projectName: string;
+    clientId: string;
+    accessToken: string;
+    refreshToken: string;
+    /** ISO time the access token stops working; refreshed on demand. */
+    expiresAt: string;
+    createdAt: string;
+};
+export type CredentialsFile = {
+    version: 1;
+    clients: Record<string, {
+        clientId: string;
+        registeredAt: string;
+    }>;
+    connections: Connection[];
+};
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+export declare function emptyCredentials(): CredentialsFile;
+export declare function readCredentials(file: string): Promise<CredentialsFile>;
+/** 0600 in a 0700 directory, through a temp file: a crash never leaves
+    a half-written store behind. */
+export declare function writeCredentials(file: string, data: CredentialsFile): Promise<void>;
+export declare function findConnection(data: CredentialsFile, api: string, projectId: string): Connection | undefined;
+export declare function connectionsFor(data: CredentialsFile, api: string): Connection[];
+export declare function upsertConnection(data: CredentialsFile, conn: Connection): CredentialsFile;
+export declare function removeConnection(data: CredentialsFile, api: string, projectId: string): CredentialsFile;