@mapled/cli 0.1.0

package/dist/credentials.js

@@ -0,0 +1,65 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { CliError } from "./errors.js";
+export function configDir(env = process.env) {
+    if (env.MAPLED_CONFIG_DIR)
+        return env.MAPLED_CONFIG_DIR;
+    if (process.platform === "win32" && env.APPDATA)
+        return path.join(env.APPDATA, "mapled");
+    const base = env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+    return path.join(base, "mapled");
+}
+export function credentialsPath(env = process.env) {
+    return path.join(configDir(env), "credentials.json");
+}
+export function emptyCredentials() {
+    return { version: 1, clients: {}, connections: [] };
+}
+export async function readCredentials(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return emptyCredentials();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${file} is unreadable. Delete it and run \`mapled auth login\` again.`);
+    }
+    return {
+        version: 1,
+        clients: parsed.clients && typeof parsed.clients === "object" ? parsed.clients : {},
+        connections: Array.isArray(parsed.connections) ? parsed.connections : [],
+    };
+}
+/** 0600 in a 0700 directory, through a temp file: a crash never leaves
+    a half-written store behind. */
+export async function writeCredentials(file, data) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    await chmod(tmp, 0o600).catch(() => { });
+    await rename(tmp, file);
+}
+export function findConnection(data, api, projectId) {
+    return data.connections.find((c) => c.api === api && c.projectId === projectId);
+}
+export function connectionsFor(data, api) {
+    return data.connections.filter((c) => c.api === api);
+}
+export function upsertConnection(data, conn) {
+    return {
+        ...data,
+        connections: [...data.connections.filter((c) => !(c.api === conn.api && c.projectId === conn.projectId)), conn],
+    };
+}
+export function removeConnection(data, api, projectId) {
+    return { ...data, connections: data.connections.filter((c) => !(c.api === api && c.projectId === projectId)) };
+}

package/dist/doctor.d.ts

@@ -0,0 +1,106 @@
+import type { Connection } from "./credentials.js";
+import type { Fetch } from "./oauth.js";
+import { type Generated } from "./types.js";
+/** `mapled doctor` (§31.3, wave 1): the checks themselves are pure
+    functions of what was gathered — the repository side here, the
+    Mapled side from GET /v1/agent/integration — so they test without a
+    network or a filesystem. Statuses and glyphs follow the Verification
+    checklist (S-42). */
+export type CheckStatus = "passed" | "failed" | "warning" | "skipped";
+export type Check = {
+    key: string;
+    label: string;
+    status: CheckStatus;
+    detail: string;
+};
+/** GET /v1/agent/integration */
+export type IntegrationStatus = {
+    project: {
+        id: string;
+        name: string;
+        slug: string;
+        productionDomain: string | null;
+    };
+    connection: {
+        id: string;
+        name: string;
+        createdAt: string | null;
+    };
+    delivery: {
+        lastReadAt: string | null;
+    };
+    webhook: {
+        url: string | null;
+        lastDelivery: {
+            event: string;
+            status: string;
+            at: string;
+            responseStatus: number | null;
+            error: string | null;
+        } | null;
+    };
+    bindings: {
+        manifest: {
+            version: number;
+            clientName: string;
+            createdAt: string;
+        } | null;
+        summary: Record<string, number>;
+    };
+    previewPath: string;
+    sdk: Record<string, string>;
+};
+export declare function ago(iso: string): string;
+export declare const ENV_FILES: string[];
+/** Variable NAMES defined in the repository's env files. Values stay in
+    the file — they are split off and dropped, never kept or printed. */
+export declare function envNames(dir: string): Promise<Map<string, string>>;
+export type GitFacts = {
+    inRepo: boolean;
+    trackedEnvFiles: string[];
+    filesWithSecrets: string[];
+};
+/** Server keys, agent and OAuth tokens, the webhook signing secret. The
+    delivery key (mk_live_) is public by design and not a secret. */
+export declare const SECRET_PATTERN = "(msk_live|mcp_live|mcp_oauth|mcp_refresh)_[A-Za-z0-9_-]{20,}|whsec_[0-9a-f]{16,}";
+export declare function gitFacts(dir: string): Promise<GitFacts>;
+export type PackageVersion = {
+    installed: string | null;
+    declared: string | null;
+};
+export declare function installedVersion(dir: string, pkg: string): Promise<PackageVersion>;
+export declare function detectFramework(dir: string): Promise<string | undefined>;
+/** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
+export declare function compareVersions(a: string, b: string): number;
+export type RouteKind = "revalidate" | "preview";
+export declare const ROUTE_HANDLER: Record<RouteKind, string>;
+export type RouteFile = {
+    file: string;
+    usesAdapter: boolean;
+};
+export declare function findRoute(dir: string, kind: RouteKind): Promise<RouteFile | null>;
+/** GET the site's preview route without a token — the adapter answers 400. */
+export declare function probePreview(origin: string, previewPath: string, f: Fetch): Promise<{
+    status: number | null;
+}>;
+export declare function checkLink(found: {
+    path: string;
+} | null, projectName: string | null): Check;
+export declare function checkAuth(state: {
+    conn: Connection | null;
+    status: IntegrationStatus | null;
+    error: string | null;
+}): Check;
+export declare function checkTypes(existing: string | null, generated: Generated | null, typesPath: string): Check;
+export declare function checkEnv(names: Map<string, string>, env: NodeJS.ProcessEnv): Check;
+export declare function checkSecrets(facts: GitFacts): Check;
+export declare function checkSdk(pkg: PackageVersion, latest: string | undefined): Check;
+export declare function checkCli(current: string, latest: string | undefined): Check;
+export declare function checkRoute(kind: RouteKind, found: RouteFile | null, framework: string | undefined): Check;
+export declare function checkReads(lastReadAt: string | null): Check;
+export declare function checkWebhook(webhook: IntegrationStatus["webhook"]): Check;
+export declare function checkPreviewOnSite(origin: string | null, previewPath: string, probe: {
+    status: number | null;
+} | null): Check;
+export declare function checkBindings(bindings: IntegrationStatus["bindings"]): Check;
+export declare const REMOTE_CHECKS: [string, string][];

package/dist/doctor.js

@@ -0,0 +1,422 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { splitGenerated } from "./types.js";
+export function ago(iso) {
+    const m = Math.floor((Date.now() - new Date(iso).getTime()) / 60_000);
+    if (m < 1)
+        return "just now";
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/* ---- the repository side ---- */
+export const ENV_FILES = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.development.local",
+    ".env.production",
+    ".env.production.local",
+];
+const ENV_EXAMPLE = /\.(example|sample|template)$/;
+/** Variable NAMES defined in the repository's env files. Values stay in
+    the file — they are split off and dropped, never kept or printed. */
+export async function envNames(dir) {
+    const found = new Map();
+    for (const name of ENV_FILES) {
+        let text;
+        try {
+            text = await readFile(path.join(dir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split(/\r?\n/)) {
+            const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+            if (m && !found.has(m[1]))
+                found.set(m[1], name);
+        }
+    }
+    return found;
+}
+const run = promisify(execFile);
+/** Server keys, agent and OAuth tokens, the webhook signing secret. The
+    delivery key (mk_live_) is public by design and not a secret. */
+export const SECRET_PATTERN = "(msk_live|mcp_live|mcp_oauth|mcp_refresh)_[A-Za-z0-9_-]{20,}|whsec_[0-9a-f]{16,}";
+export async function gitFacts(dir) {
+    const git = async (args, okCodes = [0]) => {
+        try {
+            const { stdout } = await run("git", args, { cwd: dir, maxBuffer: 8 * 1024 * 1024 });
+            return stdout;
+        }
+        catch (err) {
+            const code = err.code;
+            return typeof code === "number" && okCodes.includes(code) ? "" : null;
+        }
+    };
+    const inside = await git(["rev-parse", "--is-inside-work-tree"]);
+    if (inside === null || inside.trim() !== "true")
+        return { inRepo: false, trackedEnvFiles: [], filesWithSecrets: [] };
+    const tracked = (await git(["ls-files", "-z", "--", ".env", ".env.*", "*/.env", "*/.env.*"])) ?? "";
+    const trackedEnvFiles = tracked.split("\0").filter((f) => f && !ENV_EXAMPLE.test(f));
+    const grep = await git(["grep", "-I", "-l", "-E", SECRET_PATTERN, "--", ".", ":(exclude)*.md", ":(exclude)*.lock", ":(exclude)*-lock.json"], [0, 1]);
+    const filesWithSecrets = (grep ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { inRepo: true, trackedEnvFiles, filesWithSecrets };
+}
+export async function installedVersion(dir, pkg) {
+    let installed = null;
+    try {
+        const raw = await readFile(path.join(dir, "node_modules", pkg, "package.json"), "utf8");
+        installed = JSON.parse(raw).version ?? null;
+    }
+    catch {
+        installed = null;
+    }
+    let declared = null;
+    try {
+        const raw = await readFile(path.join(dir, "package.json"), "utf8");
+        const p = JSON.parse(raw);
+        declared = p.dependencies?.[pkg] ?? p.devDependencies?.[pkg] ?? null;
+    }
+    catch {
+        declared = null;
+    }
+    return { installed, declared };
+}
+export async function detectFramework(dir) {
+    try {
+        const raw = await readFile(path.join(dir, "package.json"), "utf8");
+        const p = JSON.parse(raw);
+        const deps = { ...p.devDependencies, ...p.dependencies };
+        if (deps.next)
+            return "nextjs";
+        if (deps.astro)
+            return "astro";
+        if (deps.nuxt)
+            return "nuxt";
+        if (deps["@sveltejs/kit"])
+            return "sveltekit";
+        if (deps["@remix-run/react"] || deps["react-router"])
+            return "remix";
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** -1, 0 or 1 comparing dotted numeric versions; anything else compares by number. */
+export function compareVersions(a, b) {
+    const pa = a.replace(/^[^0-9]*/, "").split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.replace(/^[^0-9]*/, "").split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+const ROUTE_FILES = {
+    revalidate: [
+        "app/api/mapled/revalidate/route",
+        "src/app/api/mapled/revalidate/route",
+        "pages/api/mapled/revalidate",
+        "src/pages/api/mapled/revalidate",
+    ],
+    preview: [
+        "app/api/mapled/preview/route",
+        "src/app/api/mapled/preview/route",
+        "pages/api/mapled/preview",
+        "src/pages/api/mapled/preview",
+    ],
+};
+const ROUTE_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".jsx"];
+export const ROUTE_HANDLER = {
+    revalidate: "createRevalidateHandler",
+    preview: "createPreviewHandler",
+};
+export async function findRoute(dir, kind) {
+    for (const base of ROUTE_FILES[kind]) {
+        for (const ext of ROUTE_EXTENSIONS) {
+            const rel = base + ext;
+            let text;
+            try {
+                text = await readFile(path.join(dir, rel), "utf8");
+            }
+            catch {
+                continue;
+            }
+            return { file: rel, usesAdapter: text.includes(ROUTE_HANDLER[kind]) };
+        }
+    }
+    return null;
+}
+/** GET the site's preview route without a token — the adapter answers 400. */
+export async function probePreview(origin, previewPath, f) {
+    try {
+        const res = await f(`${origin}${previewPath}`, {
+            method: "GET",
+            redirect: "manual",
+            headers: { "user-agent": "mapled-cli/doctor" },
+            signal: AbortSignal.timeout(5000),
+        });
+        return { status: res.status };
+    }
+    catch {
+        return { status: null };
+    }
+}
+/* ---- the checks ---- */
+export function checkLink(found, projectName) {
+    const label = "Project link";
+    if (!found)
+        return { key: "link", label, status: "failed", detail: "No mapled.json here. Run `mapled project link`." };
+    return { key: "link", label, status: "passed", detail: projectName ? `${found.path} → ${projectName}` : found.path };
+}
+export function checkAuth(state) {
+    const label = "Signed in";
+    if (!state.conn) {
+        return { key: "auth", label, status: "failed", detail: "Not signed in to this project. Run `mapled auth login`." };
+    }
+    if (state.error || !state.status)
+        return { key: "auth", label, status: "failed", detail: state.error ?? "Mapled didn't answer." };
+    return {
+        key: "auth",
+        label,
+        status: "passed",
+        detail: `${state.status.connection.name} • ${state.status.project.name}`,
+    };
+}
+export function checkTypes(existing, generated, typesPath) {
+    const label = "Generated types";
+    if (!generated)
+        return { key: "types", label, status: "skipped", detail: "Sign in to compare with the schema." };
+    if (existing === null) {
+        return { key: "types", label, status: "failed", detail: `${typesPath} isn't generated yet. Run \`mapled types generate\`.` };
+    }
+    if (splitGenerated(existing).body === generated.body) {
+        return { key: "types", label, status: "passed", detail: `${typesPath} matches the schema (${generated.hash})` };
+    }
+    return { key: "types", label, status: "warning", detail: `${typesPath} is out of date — run \`mapled types generate\`.` };
+}
+export function checkEnv(names, env) {
+    const label = "Environment";
+    const where = (name) => names.get(name) ?? (env[name] ? "the environment" : null);
+    const key = where("MAPLED_KEY");
+    const secret = where("MAPLED_WEBHOOK_SECRET");
+    if (!key) {
+        return {
+            key: "env",
+            label,
+            status: "failed",
+            detail: "MAPLED_KEY isn't set. Put the delivery key (Integrations → Your site) in .env.local.",
+        };
+    }
+    if (!secret) {
+        return {
+            key: "env",
+            label,
+            status: "warning",
+            detail: `MAPLED_KEY in ${key}; MAPLED_WEBHOOK_SECRET isn't set — publishes won't refresh the site until it is.`,
+        };
+    }
+    return {
+        key: "env",
+        label,
+        status: "passed",
+        detail: `MAPLED_KEY and MAPLED_WEBHOOK_SECRET in ${key === secret ? key : `${key} and ${secret}`}`,
+    };
+}
+export function checkSecrets(facts) {
+    const label = "Secrets in git";
+    if (!facts.inRepo)
+        return { key: "secrets", label, status: "skipped", detail: "Not a git repository." };
+    if (facts.trackedEnvFiles.length > 0) {
+        return {
+            key: "secrets",
+            label,
+            status: "failed",
+            detail: `${facts.trackedEnvFiles.join(", ")} is tracked by git — untrack it (git rm --cached) and add it to .gitignore.`,
+        };
+    }
+    if (facts.filesWithSecrets.length > 0) {
+        return {
+            key: "secrets",
+            label,
+            status: "failed",
+            detail: `Mapled secrets found in ${facts.filesWithSecrets.join(", ")}. Rotate them in Integrations and remove them from the repository.`,
+        };
+    }
+    return { key: "secrets", label, status: "passed", detail: "No env files or Mapled secrets are tracked." };
+}
+export function checkSdk(pkg, latest) {
+    const label = "@mapled/next";
+    if (!pkg.installed && !pkg.declared) {
+        return { key: "sdk", label, status: "failed", detail: "Not installed. Run `npm install @mapled/next`." };
+    }
+    if (!pkg.installed) {
+        return { key: "sdk", label, status: "warning", detail: `${pkg.declared} is declared but not installed — run npm install.` };
+    }
+    if (!latest)
+        return { key: "sdk", label, status: "passed", detail: `${pkg.installed} installed` };
+    if (compareVersions(pkg.installed, latest) < 0) {
+        return {
+            key: "sdk",
+            label,
+            status: "warning",
+            detail: `${pkg.installed} installed, ${latest} available — npm install @mapled/next@latest.`,
+        };
+    }
+    return { key: "sdk", label, status: "passed", detail: `${pkg.installed} (current)` };
+}
+export function checkCli(current, latest) {
+    const label = "mapled CLI";
+    if (latest && compareVersions(current, latest) < 0) {
+        return { key: "cli", label, status: "warning", detail: `${current} running, ${latest} available — npx @mapled/cli@latest.` };
+    }
+    return { key: "cli", label, status: "passed", detail: latest ? `${current} (current)` : current };
+}
+export function checkRoute(kind, found, framework) {
+    const key = `route_${kind}`;
+    const label = kind === "revalidate" ? "Revalidation route" : "Preview route";
+    const handler = ROUTE_HANDLER[kind];
+    if (framework && framework !== "nextjs") {
+        return { key, label, status: "skipped", detail: `No ${kind} route check for ${framework} sites yet.` };
+    }
+    if (!found) {
+        return kind === "revalidate"
+            ? {
+                key,
+                label,
+                status: "failed",
+                detail: `app/api/mapled/revalidate/route.ts is missing — mount ${handler} from "@mapled/next/server".`,
+            }
+            : {
+                key,
+                label,
+                status: "warning",
+                detail: `app/api/mapled/preview/route.ts is missing — mount ${handler} from "@mapled/next/server" so Preview from Mapled works.`,
+            };
+    }
+    if (!found.usesAdapter) {
+        return { key, label, status: "warning", detail: `${found.file} exists but doesn't use ${handler} from "@mapled/next/server".` };
+    }
+    return { key, label, status: "passed", detail: found.file };
+}
+export function checkReads(lastReadAt) {
+    const label = "Site reads content";
+    if (!lastReadAt) {
+        return {
+            key: "reads",
+            label,
+            status: "warning",
+            detail: "No reads yet. Deploy the site and open a page that shows Mapled content.",
+        };
+    }
+    return { key: "reads", label, status: "passed", detail: `Last read ${ago(lastReadAt)}` };
+}
+export function checkWebhook(webhook) {
+    const label = "Publish webhook";
+    if (!webhook.url) {
+        return {
+            key: "webhook",
+            label,
+            status: "failed",
+            detail: "Not configured. Point it at https://<site>/api/mapled/revalidate in Integrations → Your site, or ask your agent.",
+        };
+    }
+    const host = hostOf(webhook.url);
+    const last = webhook.lastDelivery;
+    if (!last) {
+        return {
+            key: "webhook",
+            label,
+            status: "warning",
+            detail: `Configured (${host}), nothing delivered yet — send a test ping from Integrations.`,
+        };
+    }
+    if (last.status === "delivered") {
+        return { key: "webhook", label, status: "passed", detail: `Delivered ${ago(last.at)} to ${host}` };
+    }
+    if (last.status === "pending") {
+        return { key: "webhook", label, status: "warning", detail: `The last delivery to ${host} is still pending.` };
+    }
+    const reason = last.responseStatus ? `responded ${last.responseStatus}` : (last.error ?? "failed");
+    return {
+        key: "webhook",
+        label,
+        status: "failed",
+        detail: `The last delivery to ${host} ${reason}. Check the route and MAPLED_WEBHOOK_SECRET, then send a test ping.`,
+    };
+}
+export function checkPreviewOnSite(origin, previewPath, probe) {
+    const label = "Preview on the site";
+    if (!origin || !probe) {
+        return { key: "preview_site", label, status: "skipped", detail: "Needs the webhook URL to know where the site lives." };
+    }
+    if (probe.status === 400 || probe.status === 401) {
+        return { key: "preview_site", label, status: "passed", detail: `Responds at ${origin}${previewPath}` };
+    }
+    if (probe.status === null) {
+        return { key: "preview_site", label, status: "warning", detail: `${origin} is unreachable from here.` };
+    }
+    if (probe.status === 404) {
+        return {
+            key: "preview_site",
+            label,
+            status: "failed",
+            detail: `${previewPath} returned 404 on ${origin} — mount createPreviewHandler and redeploy.`,
+        };
+    }
+    return {
+        key: "preview_site",
+        label,
+        status: "warning",
+        detail: `${previewPath} responded with ${probe.status} — expected 400 without a token.`,
+    };
+}
+export function checkBindings(bindings) {
+    const label = "Bindings";
+    if (!bindings.manifest) {
+        return { key: "bindings", label, status: "skipped", detail: "Not synced yet — ask your AI agent to push the site manifest." };
+    }
+    const s = bindings.summary;
+    const issues = [];
+    if (s.missing_on_site)
+        issues.push(`${s.missing_on_site} missing on site`);
+    if (s.type_mismatch)
+        issues.push(`${s.type_mismatch} type mismatch${s.type_mismatch === 1 ? "" : "es"}`);
+    if (s.outdated)
+        issues.push(`${s.outdated} outdated`);
+    if (issues.length > 0) {
+        return { key: "bindings", label, status: "warning", detail: `${issues.join(", ")} — open Structure → Bindings in Mapled.` };
+    }
+    return {
+        key: "bindings",
+        label,
+        status: "passed",
+        detail: `${s.healthy ?? 0} healthy • synced ${ago(bindings.manifest.createdAt)} from ${bindings.manifest.clientName}`,
+    };
+}
+export const REMOTE_CHECKS = [
+    ["reads", "Site reads content"],
+    ["webhook", "Publish webhook"],
+    ["preview_site", "Preview on the site"],
+    ["bindings", "Bindings"],
+];

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** An error meant for the person at the terminal: printed as one line,
+    without a stack, with the exit code it asks for. */
+export declare class CliError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/** An error meant for the person at the terminal: printed as one line,
+    without a stack, with the exit code it asks for. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};