@mapled/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "./args.js";
+import { openBrowser } from "./browser.js";
+import { doctor, generate, link, login, logout } from "./commands.js";
+import { credentialsPath } from "./credentials.js";
+import { CliError } from "./errors.js";
+/** `mapled` — sign in, link a repository to its project, generate types
+    for the content, check the integration (§31, wave 1). */
+const HELP = `mapled — the Mapled CLI
+
+Usage
+  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
+  mapled types generate [--out <file>]                Generate TypeScript types for the content
+  mapled doctor [--json]                              Check the integration end to end
+
+Options
+  --version, -v   Print the version
+  --help, -h      Show this help
+
+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.`;
+function version() {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+}
+async function choose(question, choices) {
+    if (!process.stdin.isTTY) {
+        throw new CliError(`${question} Pass --project <id> to choose without a prompt.`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (;;) {
+            console.log(question);
+            choices.forEach((c, i) => console.log(`  ${i + 1}. ${c}`));
+            const answer = (await rl.question("> ")).trim();
+            const n = Number(answer);
+            if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+                return n - 1;
+            console.log("Enter a number from the list.");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function main(argv) {
+    const { words, flags } = parseArgs(argv);
+    if (flags.version) {
+        console.log(version());
+        return 0;
+    }
+    const [group, sub] = words;
+    if (flags.help || !group) {
+        console.log(HELP);
+        return flags.help || group ? 0 : 2;
+    }
+    const ctx = {
+        cwd: process.cwd(),
+        env: process.env,
+        fetch,
+        openBrowser,
+        out: (line) => console.log(line),
+        choose,
+        version: version(),
+        credentialsFile: credentialsPath(),
+    };
+    switch (`${group} ${sub ?? ""}`.trim()) {
+        case "auth login":
+            await login(ctx, flags);
+            return 0;
+        case "auth logout":
+            await logout(ctx, flags);
+            return 0;
+        case "project link":
+            await link(ctx, flags);
+            return 0;
+        case "types generate":
+            await generate(ctx, flags);
+            return 0;
+        case "doctor":
+            return doctor(ctx, flags);
+        case "auth":
+        case "project":
+        case "types":
+            console.log(HELP);
+            return 2;
+        default:
+            throw new CliError(`Unknown command "${words.join(" ")}". Run \`mapled --help\`.`, 2);
+    }
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = err instanceof CliError ? err.exitCode : 1;
+});

package/dist/oauth.d.ts

@@ -0,0 +1,45 @@
+/** The CLI signs in as an OAuth 2.1 public client of the Mapled API —
+    the same authorization server the remote MCP uses (S-54): dynamic
+    registration, PKCE, consent on app.mapled.io, a loopback redirect
+    (RFC 8252) and rotating refresh tokens. The access token is scoped
+    to the one project picked on the consent screen. */
+export declare const CLIENT_NAME = "Mapled CLI";
+export declare const REDIRECT_PATH = "/callback";
+export declare const SCOPE = "mapled";
+export type Fetch = typeof fetch;
+export type TokenSet = {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+};
+export type AuthorizationCode = {
+    code: string;
+    verifier: string;
+    redirectUri: string;
+};
+export declare function pkce(): {
+    verifier: string;
+    challenge: string;
+};
+/** Dynamic registration (RFC 7591) of this machine's CLI as a public
+    client whose loopback redirect may use any port. */
+export declare function registerClient(api: string, f: Fetch): Promise<string>;
+/** Whether the authorization server still knows a stored client id: a
+    request with an unsupported response type is answered with a
+    redirect for a known client and 400 for an unknown one — and
+    creates nothing on the server. */
+export declare function clientKnown(api: string, clientId: string, f: Fetch): Promise<boolean>;
+export type AuthorizeDeps = {
+    openBrowser: (url: string) => Promise<boolean>;
+    log: (line: string) => void;
+    timeoutMs?: number;
+};
+/** The authorization code flow with a loopback redirect: a one-off
+    server on 127.0.0.1 receives the code once the person approves on
+    app.mapled.io. Rejects on denial, on timeout, and never on a state
+    that isn't this run's. */
+export declare function authorize(api: string, clientId: string, deps: AuthorizeDeps): Promise<AuthorizationCode>;
+export declare function exchangeCode(api: string, clientId: string, grant: AuthorizationCode, f: Fetch): Promise<TokenSet>;
+export declare function refreshTokens(api: string, clientId: string, refreshToken: string, f: Fetch): Promise<TokenSet>;
+/** Ends the connection (RFC 7009). Best effort — the local copy goes either way. */
+export declare function revokeToken(api: string, token: string, f: Fetch): Promise<void>;

package/dist/oauth.js

@@ -0,0 +1,192 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { CliError } from "./errors.js";
+/** The CLI signs in as an OAuth 2.1 public client of the Mapled API —
+    the same authorization server the remote MCP uses (S-54): dynamic
+    registration, PKCE, consent on app.mapled.io, a loopback redirect
+    (RFC 8252) and rotating refresh tokens. The access token is scoped
+    to the one project picked on the consent screen. */
+export const CLIENT_NAME = "Mapled CLI";
+export const REDIRECT_PATH = "/callback";
+export const SCOPE = "mapled";
+export function pkce() {
+    const verifier = randomBytes(48).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+function unreachable(api) {
+    return new CliError(`Couldn't reach ${api}. Check your connection and try again.`);
+}
+async function oauthPost(api, path, params, f) {
+    let res;
+    try {
+        res = await f(`${api}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams(params).toString(),
+        });
+    }
+    catch {
+        throw unreachable(api);
+    }
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new CliError(String(data.error_description ?? data.error ?? `Mapled answered ${res.status}.`));
+    }
+    return data;
+}
+/** Dynamic registration (RFC 7591) of this machine's CLI as a public
+    client whose loopback redirect may use any port. */
+export async function registerClient(api, f) {
+    let res;
+    try {
+        res = await f(`${api}/oauth/register`, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                client_name: CLIENT_NAME,
+                client_uri: "https://mapled.io",
+                redirect_uris: [`http://127.0.0.1${REDIRECT_PATH}`],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+                scope: SCOPE,
+            }),
+        });
+    }
+    catch {
+        throw unreachable(api);
+    }
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof data.client_id !== "string") {
+        throw new CliError(`Couldn't register the CLI with ${api}: ${data.error_description ?? data.error ?? `status ${res.status}`}.`);
+    }
+    return data.client_id;
+}
+/** Whether the authorization server still knows a stored client id: a
+    request with an unsupported response type is answered with a
+    redirect for a known client and 400 for an unknown one — and
+    creates nothing on the server. */
+export async function clientKnown(api, clientId, f) {
+    try {
+        const url = new URL(`${api}/oauth/authorize`);
+        url.search = new URLSearchParams({
+            client_id: clientId,
+            redirect_uri: `http://127.0.0.1${REDIRECT_PATH}`,
+            response_type: "none",
+            state: "probe",
+        }).toString();
+        const res = await f(url.toString(), { redirect: "manual" });
+        return res.status === 302;
+    }
+    catch {
+        return false;
+    }
+}
+function page(res, status, text) {
+    // Fixed strings of our own — nothing from the query string is rendered.
+    res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+    res.end(`<!doctype html><meta charset="utf-8"><title>Mapled</title>` +
+        `<p style="font:16px system-ui,sans-serif;margin:40px">${text}</p>`);
+}
+/** The authorization code flow with a loopback redirect: a one-off
+    server on 127.0.0.1 receives the code once the person approves on
+    app.mapled.io. Rejects on denial, on timeout, and never on a state
+    that isn't this run's. */
+export function authorize(api, clientId, deps) {
+    const { verifier, challenge } = pkce();
+    const state = randomBytes(16).toString("base64url");
+    return new Promise((resolve, reject) => {
+        let redirectUri = "";
+        let settled = false;
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== REDIRECT_PATH) {
+                res.writeHead(404).end();
+                return;
+            }
+            if (url.searchParams.get("state") !== state) {
+                // Not this run's redirect — keep waiting for the real one.
+                page(res, 400, "This sign-in link doesn't belong to the running command.");
+                return;
+            }
+            const error = url.searchParams.get("error");
+            if (error) {
+                page(res, 200, "Sign-in was cancelled. You can close this tab.");
+                finish(() => reject(new CliError(error === "access_denied"
+                    ? "Sign-in was denied in the browser."
+                    : `Sign-in failed: ${url.searchParams.get("error_description") ?? error}`)));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (!code) {
+                page(res, 400, "The sign-in link is missing its code.");
+                return;
+            }
+            page(res, 200, "Signed in to Mapled. You can close this tab and return to the terminal.");
+            finish(() => resolve({ code, verifier, redirectUri }));
+        });
+        const timer = setTimeout(() => finish(() => reject(new CliError("Timed out waiting for the browser. Run `mapled auth login` again."))), deps.timeoutMs ?? 5 * 60_000);
+        function finish(then) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            then();
+        }
+        server.once("error", (err) => finish(() => reject(err)));
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            redirectUri = `http://127.0.0.1:${port}${REDIRECT_PATH}`;
+            const url = new URL(`${api}/oauth/authorize`);
+            url.search = new URLSearchParams({
+                response_type: "code",
+                client_id: clientId,
+                redirect_uri: redirectUri,
+                code_challenge: challenge,
+                code_challenge_method: "S256",
+                state,
+                scope: SCOPE,
+                resource: `${api}/mcp`,
+            }).toString();
+            deps.log(`Opening your browser to sign in to Mapled. If it doesn't open, visit:\n  ${url.toString()}`);
+            deps
+                .openBrowser(url.toString())
+                .then((opened) => {
+                if (!opened)
+                    deps.log("Couldn't open a browser here — use the link above.");
+            })
+                .catch(() => { });
+        });
+    });
+}
+function toTokenSet(data) {
+    const access = data.access_token;
+    const refresh = data.refresh_token;
+    if (typeof access !== "string" || typeof refresh !== "string") {
+        throw new CliError("Mapled returned an incomplete token response. Try again.");
+    }
+    const expiresIn = Number(data.expires_in);
+    const ttl = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 3600;
+    return { accessToken: access, refreshToken: refresh, expiresAt: new Date(Date.now() + ttl * 1000).toISOString() };
+}
+export async function exchangeCode(api, clientId, grant, f) {
+    const data = await oauthPost(api, "/oauth/token", {
+        grant_type: "authorization_code",
+        code: grant.code,
+        code_verifier: grant.verifier,
+        redirect_uri: grant.redirectUri,
+        client_id: clientId,
+        resource: `${api}/mcp`,
+    }, f);
+    return toTokenSet(data);
+}
+export async function refreshTokens(api, clientId, refreshToken, f) {
+    const data = await oauthPost(api, "/oauth/token", { grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId }, f);
+    return toTokenSet(data);
+}
+/** Ends the connection (RFC 7009). Best effort — the local copy goes either way. */
+export async function revokeToken(api, token, f) {
+    await oauthPost(api, "/oauth/revoke", { token }, f).catch(() => undefined);
+}

package/dist/output.d.ts

@@ -0,0 +1,8 @@
+import type { Check, CheckStatus } from "./doctor.js";
+/** Terminal output: the glyphs of the Verification checklist (S-42),
+    colour only on a TTY that hasn't set NO_COLOR. */
+export declare const GLYPH: Record<CheckStatus, string>;
+export declare function useColor(env?: NodeJS.ProcessEnv): boolean;
+export declare function paint(status: CheckStatus, text: string, color: boolean): string;
+export declare function formatChecks(checks: Check[], color: boolean): string;
+export declare function summarize(checks: Check[]): string;

package/dist/output.js

@@ -0,0 +1,30 @@
+/** Terminal output: the glyphs of the Verification checklist (S-42),
+    colour only on a TTY that hasn't set NO_COLOR. */
+export const GLYPH = { passed: "✓", failed: "✗", warning: "⚠", skipped: "○" };
+const COLOR = { passed: "32", failed: "31", warning: "33", skipped: "2" };
+const ESC = "[";
+export function useColor(env = process.env) {
+    return Boolean(process.stdout.isTTY) && !env.NO_COLOR && env.TERM !== "dumb";
+}
+export function paint(status, text, color) {
+    return color ? `${ESC}${COLOR[status]}m${text}${ESC}0m` : text;
+}
+export function formatChecks(checks, color) {
+    const width = checks.reduce((w, c) => Math.max(w, c.label.length), 0);
+    return checks
+        .map((c) => `${paint(c.status, GLYPH[c.status], color)} ${c.label.padEnd(width)}  ${c.detail}`)
+        .join("\n");
+}
+export function summarize(checks) {
+    const failed = checks.filter((c) => c.status === "failed").length;
+    const warned = checks.filter((c) => c.status === "warning").length;
+    const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+    if (failed === 0 && warned === 0)
+        return "Everything checks out.";
+    const parts = [];
+    if (failed > 0)
+        parts.push(plural(failed, "problem"));
+    if (warned > 0)
+        parts.push(plural(warned, "warning"));
+    return `${parts.join(", ")}.${failed > 0 ? " Fix the problems and run `mapled doctor` again." : ""}`;
+}

package/dist/schema.d.ts

@@ -0,0 +1,44 @@
+/** The project schema as GET /v1/agent/schema returns it (the subset the
+    generator reads). Everything in it is content the project's editors
+    and agents typed — names and keys are data, escaped on output. */
+export type SchemaSubField = {
+    key: string;
+    displayName: string;
+    type: string;
+    required: boolean;
+    helpText?: string | null;
+    options?: string[] | null;
+    sensitive?: boolean;
+};
+export type SchemaField = {
+    key: string;
+    displayName: string;
+    type: string;
+    required: boolean;
+    helpText: string | null;
+    options: string[] | null;
+    relation: {
+        target: string;
+        cardinality: "one" | "many";
+        onDelete?: string;
+    } | null;
+    sensitive: boolean;
+    group: {
+        fields: SchemaSubField[];
+        repeatable: boolean;
+        maxItems?: number;
+    } | null;
+};
+export type SchemaCollection = {
+    key: string;
+    displayName: string;
+    kind: "collection" | "single";
+    accessClass: string;
+    mode: string;
+    fields: SchemaField[];
+};
+export type Schema = {
+    collections: SchemaCollection[];
+};
+/** Twelve hex characters over everything the generated types depend on. */
+export declare function schemaHash(schema: Schema): string;

package/dist/schema.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+/** Twelve hex characters over everything the generated types depend on. */
+export function schemaHash(schema) {
+    const projection = schema.collections.map((c) => ({
+        key: c.key,
+        displayName: c.displayName,
+        kind: c.kind,
+        accessClass: c.accessClass,
+        mode: c.mode,
+        fields: c.fields.map((f) => ({
+            key: f.key,
+            displayName: f.displayName,
+            type: f.type,
+            required: f.required,
+            options: f.options ?? null,
+            relation: f.relation ? { target: f.relation.target, cardinality: f.relation.cardinality } : null,
+            sensitive: f.sensitive === true,
+            group: f.group
+                ? {
+                    repeatable: f.group.repeatable,
+                    maxItems: f.group.maxItems ?? null,
+                    fields: f.group.fields.map((s) => ({
+                        key: s.key,
+                        displayName: s.displayName,
+                        type: s.type,
+                        required: s.required,
+                        options: s.options ?? null,
+                        sensitive: s.sensitive === true,
+                    })),
+                }
+                : null,
+        })),
+    }));
+    return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+import { type Schema, type SchemaCollection } from "./schema.js";
+/** TypeScript types for the content a site reads through @mapled/next:
+    one interface per collection and single, plus keyed maps. Sensitive
+    fields never reach the site, so they are left out. */
+export type Generated = {
+    /** The whole file. */
+    text: string;
+    /** The file without its header — what `mapled doctor` compares. */
+    body: string;
+    hash: string;
+    collections: number;
+    singles: number;
+};
+/** A conservative singular: regular English plurals only. */
+export declare function singular(word: string): string;
+export declare function pascal(words: string[]): string;
+/** `blog-posts` → `BlogPost`; singles keep their name (`homepage` → `Homepage`). */
+export declare function typeName(key: string, kind: "collection" | "single"): string;
+/** Unique type names: the singular PascalCase of the key; the raw
+    PascalCase when two keys meet there; a numeric suffix as a last resort. */
+export declare function typeNames(collections: SchemaCollection[]): Map<string, string>;
+export declare function generateTypes(schema: Schema, opts?: {
+    projectName?: string;
+}): Generated;
+/** Splits a generated file into its header and body, with the hash the
+    header names when it has one. */
+export declare function splitGenerated(text: string): {
+    header: string;
+    body: string;
+    hash: string | null;
+};