@bettercms-ai/mcp 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -1,126 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-/**
- * Resolved configuration for the BetterCMS MCP server.
- *
- * A single `BETTERCMS_API_URL` (origin, no path) drives both the device-auth
- * endpoints and the Management API base the SDK targets:
- *   device:     {apiUrl}/api/v1/auth/device/*
- *   management: {apiUrl}/api/v1   (SDK appends /management/content/*)
- */
-interface McpConfig {
-    apiUrl: string;
-    deviceBaseUrl: string;
-    managementBaseUrl: string;
-    credentialsPath: string;
-    clientName: string;
-}
-declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
-
-/** Credentials cached between runs so the device flow runs only once per env. */
-interface StoredCredentials {
-    accessToken: string;
-    refreshToken: string;
-    /** Epoch ms when the access token expires. */
-    accessTokenExpiresAt: number;
-    workspaceId: string | null;
-    projectId: string | null;
-}
-/**
- * An authorization the user has been sent off to approve but hasn't yet.
- * Persisted so a later tool call can *resume* polling that same code instead of
- * minting a fresh one — this is what lets the flow survive across the
- * "return the link → user approves → retry" round-trip in clients (VS Code)
- * that never surface the server's stderr prompt.
- */
-interface PendingDevice {
-    deviceCode: string;
-    userCode: string;
-    verificationUri: string;
-    /** verification_uri with `?code=` prefilled — the link we hand the user. */
-    verificationUriComplete: string;
-    intervalSeconds: number;
-    /** Epoch ms when the device code expires. */
-    expiresAt: number;
-}
-/** Persistence boundary for credentials (file-backed in prod, in-memory in tests). */
-interface TokenStore {
-    read(): Promise<StoredCredentials | null>;
-    write(creds: StoredCredentials): Promise<void>;
-    clear(): Promise<void>;
-    /** In-progress device authorization awaiting approval, if any. */
-    readPending(): Promise<PendingDevice | null>;
-    writePending(pending: PendingDevice): Promise<void>;
-    clearPending(): Promise<void>;
-}
-
-/** Injectable seams so tests can run without real timers / network / stderr. */
-interface DeviceAuthDeps {
-    fetch?: typeof fetch;
-    sleep?: (ms: number) => Promise<void>;
-    log?: (message: string) => void;
-    now?: () => number;
-}
-/**
- * Drives the OAuth 2.0 Device Authorization Grant (RFC 8628) against the
- * BetterCMS backend and hands the SDK a valid `content:manage` access token.
- *
- * - `getAccessToken()` returns a usable token: cached if fresh, refreshed if
- *   expired, or freshly minted via the full device flow if there's nothing valid.
- * - All human-facing output goes to stderr — stdout is the MCP JSON-RPC channel.
- */
-declare class DeviceAuthClient {
-    private readonly config;
-    private readonly store;
-    private readonly fetchImpl;
-    private readonly sleep;
-    private readonly log;
-    private readonly now;
-    private inFlight;
-    private refreshInFlight;
-    /** The single live poller for the current device code (see runDeviceFlow). */
-    private pollTask;
-    constructor(config: McpConfig, store: TokenStore, deps?: DeviceAuthDeps);
-    /** Return a valid access token, doing the least work necessary. Single-flighted. */
-    getAccessToken(): Promise<string>;
-    private resolveToken;
-    /**
-     * Resume a still-live authorization if one is persisted, otherwise start a
-     * fresh one; then grace-poll. Throws {@link DeviceAuthPendingError} (carrying
-     * the activation link) if the user hasn't approved within the grace window.
-     */
-    private runDeviceFlow;
-    /** Keep redeeming this code until it expires, detached from any tool call. One per code. */
-    private pollInBackground;
-    /** Request a fresh device code, persist it as pending, and log a breadcrumb. */
-    private startDeviceFlow;
-    /**
-     * Poll the token endpoint until `deadline`. Returns the access token on
-     * approval, or null if the deadline passes while still pending. Throws
-     * {@link DeviceAuthError} on a terminal outcome (denied / expired).
-     */
-    private pollForApproval;
-    /**
-     * Exchange the stored refresh token for a new access token. Single-flighted:
-     * the device `/refresh` endpoint is single-use (it rotates the refresh token
-     * and revokes the prior access key), so a burst of concurrent 401s must NOT
-     * each fire their own refresh — the first would rotate, and the rest would
-     * send the now-stale token, get `invalid_grant`, and wipe the freshly-minted
-     * credentials. Collapsing them into one in-flight rotation keeps the session
-     * alive without a needless re-auth.
-     */
-    refresh(): Promise<string | null>;
-    /**
-     * Forget the cached credentials and start a fresh device flow. Called when the
-     * bound project was deleted server-side (a key bound to a dead project can never
-     * succeed again) — clearing lets the user re-authorize against a LIVE project.
-     * Returns a new token if approval is fast, else throws {@link DeviceAuthPendingError}
-     * carrying the activation link (the next tool call resumes into the new project).
-     */
-    resetAndReauthorize(): Promise<string>;
-    private doRefresh;
-    private persist;
-}
+import { DeviceAuthClient } from '@bettercms-ai/device-auth';
+export { DeviceAuthClient, loadConfig } from '@bettercms-ai/device-auth';
 
 interface BuildServerDeps {
     auth: DeviceAuthClient;
@@ -133,4 +13,4 @@ interface BuildServerDeps {
  */
 declare function buildServer(deps: BuildServerDeps): McpServer;
 
-export { DeviceAuthClient, buildServer, loadConfig };
+export { buildServer };

package/dist/index.js

@@ -4,309 +4,7 @@
 import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// src/config.ts
-import { homedir } from "os";
-import { join } from "path";
-var DEFAULT_API_URL = "https://api.bettercms.ai";
-function loadConfig(env = process.env) {
-  const apiUrl = (env.BETTERCMS_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
-  return {
-    apiUrl,
-    deviceBaseUrl: `${apiUrl}/api/v1/auth/device`,
-    managementBaseUrl: `${apiUrl}/api/v1`,
-    credentialsPath: env.BETTERCMS_MCP_CREDENTIALS?.trim() || join(homedir(), ".bettercms", "mcp-credentials.json"),
-    clientName: env.BETTERCMS_MCP_CLIENT_NAME?.trim() || "BetterCMS MCP"
-  };
-}
-
-// src/token-store.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname } from "path";
-var FileTokenStore = class {
-  constructor(path, key) {
-    this.path = path;
-    this.key = key;
-    this.pendingKey = `${key}::pending`;
-  }
-  path;
-  key;
-  /** Pending authorizations live under a sibling key so they never shadow creds. */
-  pendingKey;
-  async readAll() {
-    try {
-      const raw = await readFile(this.path, "utf-8");
-      const parsed = JSON.parse(raw);
-      return parsed && typeof parsed === "object" ? parsed : {};
-    } catch {
-      return {};
-    }
-  }
-  async writeAll(all) {
-    await mkdir(dirname(this.path), { recursive: true });
-    await writeFile(this.path, JSON.stringify(all, null, 2), { mode: 384 });
-  }
-  async read() {
-    const all = await this.readAll();
-    return all[this.key] ?? null;
-  }
-  async write(creds) {
-    const all = await this.readAll();
-    all[this.key] = creds;
-    await this.writeAll(all);
-  }
-  async clear() {
-    const all = await this.readAll();
-    delete all[this.key];
-    await this.writeAll(all);
-  }
-  async readPending() {
-    const all = await this.readAll();
-    return all[this.pendingKey] ?? null;
-  }
-  async writePending(pending) {
-    const all = await this.readAll();
-    all[this.pendingKey] = pending;
-    await this.writeAll(all);
-  }
-  async clearPending() {
-    const all = await this.readAll();
-    delete all[this.pendingKey];
-    await this.writeAll(all);
-  }
-};
-
-// src/device-auth.ts
-var EXPIRY_SKEW_MS = 6e4;
-var GRACE_POLL_MS = 25e3;
-var DeviceAuthError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "DeviceAuthError";
-  }
-};
-var DeviceAuthPendingError = class extends Error {
-  verificationUri;
-  verificationUriComplete;
-  userCode;
-  expiresAt;
-  constructor(pending) {
-    super("Authorization pending \u2014 approve in the browser, then retry.");
-    this.name = "DeviceAuthPendingError";
-    this.verificationUri = pending.verificationUri;
-    this.verificationUriComplete = pending.verificationUriComplete;
-    this.userCode = pending.userCode;
-    this.expiresAt = pending.expiresAt;
-  }
-};
-var DeviceAuthClient = class {
-  constructor(config, store, deps = {}) {
-    this.config = config;
-    this.store = store;
-    this.fetchImpl = deps.fetch ?? globalThis.fetch;
-    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    this.log = deps.log ?? ((m) => process.stderr.write(`${m}
-`));
-    this.now = deps.now ?? (() => Date.now());
-  }
-  config;
-  store;
-  fetchImpl;
-  sleep;
-  log;
-  now;
-  inFlight = null;
-  refreshInFlight = null;
-  /** The single live poller for the current device code (see runDeviceFlow). */
-  pollTask = null;
-  /** Return a valid access token, doing the least work necessary. Single-flighted. */
-  async getAccessToken() {
-    if (this.inFlight) return this.inFlight;
-    this.inFlight = this.resolveToken().finally(() => {
-      this.inFlight = null;
-    });
-    return this.inFlight;
-  }
-  async resolveToken() {
-    const creds = await this.store.read();
-    if (creds && creds.accessTokenExpiresAt - this.now() > EXPIRY_SKEW_MS) {
-      return creds.accessToken;
-    }
-    if (creds?.refreshToken) {
-      const refreshed = await this.refresh();
-      if (refreshed) return refreshed;
-    }
-    return this.runDeviceFlow();
-  }
-  /**
-   * Resume a still-live authorization if one is persisted, otherwise start a
-   * fresh one; then grace-poll. Throws {@link DeviceAuthPendingError} (carrying
-   * the activation link) if the user hasn't approved within the grace window.
-   */
-  async runDeviceFlow() {
-    let pending = await this.store.readPending();
-    if (pending && pending.expiresAt - this.now() <= EXPIRY_SKEW_MS) {
-      await this.store.clearPending();
-      pending = null;
-    }
-    if (!pending) {
-      pending = await this.startDeviceFlow();
-    }
-    const graceDeadline = Math.min(this.now() + GRACE_POLL_MS, pending.expiresAt);
-    const token = this.pollTask ? await Promise.race([this.pollTask, this.sleep(GRACE_POLL_MS).then(() => null)]) : await this.pollForApproval(pending, graceDeadline);
-    if (token) return token;
-    this.pollInBackground(pending);
-    throw new DeviceAuthPendingError(pending);
-  }
-  /** Keep redeeming this code until it expires, detached from any tool call. One per code. */
-  pollInBackground(pending) {
-    if (this.pollTask) return;
-    const task = this.pollForApproval(pending, pending.expiresAt);
-    this.pollTask = task;
-    void task.catch(() => {
-    }).finally(() => {
-      if (this.pollTask === task) this.pollTask = null;
-    });
-  }
-  /** Request a fresh device code, persist it as pending, and log a breadcrumb. */
-  async startDeviceFlow() {
-    const start = await this.fetchImpl(`${this.config.deviceBaseUrl}/code`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ client_name: this.config.clientName })
-    });
-    if (!start.ok) {
-      throw new DeviceAuthError(
-        `Failed to start device authorization (HTTP ${start.status}).`
-      );
-    }
-    const code = await start.json();
-    const pending = {
-      deviceCode: code.device_code,
-      userCode: code.user_code,
-      verificationUri: code.verification_uri,
-      verificationUriComplete: code.verification_uri_complete ?? `${code.verification_uri}?code=${encodeURIComponent(code.user_code)}`,
-      intervalSeconds: code.interval,
-      expiresAt: this.now() + code.expires_in * 1e3
-    };
-    await this.store.writePending(pending);
-    this.pollTask = null;
-    this.log("");
-    this.log("\u250C\u2500 BetterCMS authorization required \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-    this.log(`\u2502 Visit: ${pending.verificationUri}`);
-    this.log(`\u2502 Enter code: ${pending.userCode}`);
-    this.log(`\u2502 Or open: ${pending.verificationUriComplete}`);
-    this.log("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
-    return pending;
-  }
-  /**
-   * Poll the token endpoint until `deadline`. Returns the access token on
-   * approval, or null if the deadline passes while still pending. Throws
-   * {@link DeviceAuthError} on a terminal outcome (denied / expired).
-   */
-  async pollForApproval(pending, deadline) {
-    let intervalMs = pending.intervalSeconds * 1e3;
-    while (this.now() < deadline) {
-      await this.sleep(intervalMs);
-      if (this.now() >= deadline) break;
-      const res = await this.fetchImpl(`${this.config.deviceBaseUrl}/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          device_code: pending.deviceCode,
-          grant_type: "urn:ietf:params:oauth:grant-type:device_code"
-        })
-      });
-      if (res.ok) {
-        const body = await res.json();
-        await this.store.clearPending();
-        this.log("[bettercms-mcp] authorized \u2713");
-        return this.persist(body);
-      }
-      const err = await res.json().catch(() => ({}));
-      switch (err.error) {
-        case "authorization_pending":
-          continue;
-        case "slow_down":
-          intervalMs += 5e3;
-          continue;
-        case "access_denied":
-          await this.store.clearPending();
-          throw new DeviceAuthError("Authorization was denied.");
-        case "expired_token":
-          await this.store.clearPending();
-          throw new DeviceAuthError("The device code expired before approval. Try again.");
-        default:
-          throw new DeviceAuthError(
-            `Device authorization failed: ${err.error ?? `HTTP ${res.status}`}.`
-          );
-      }
-    }
-    return null;
-  }
-  /**
-   * Exchange the stored refresh token for a new access token. Single-flighted:
-   * the device `/refresh` endpoint is single-use (it rotates the refresh token
-   * and revokes the prior access key), so a burst of concurrent 401s must NOT
-   * each fire their own refresh — the first would rotate, and the rest would
-   * send the now-stale token, get `invalid_grant`, and wipe the freshly-minted
-   * credentials. Collapsing them into one in-flight rotation keeps the session
-   * alive without a needless re-auth.
-   */
-  async refresh() {
-    if (this.refreshInFlight) return this.refreshInFlight;
-    this.refreshInFlight = this.doRefresh().finally(() => {
-      this.refreshInFlight = null;
-    });
-    return this.refreshInFlight;
-  }
-  /**
-   * Forget the cached credentials and start a fresh device flow. Called when the
-   * bound project was deleted server-side (a key bound to a dead project can never
-   * succeed again) — clearing lets the user re-authorize against a LIVE project.
-   * Returns a new token if approval is fast, else throws {@link DeviceAuthPendingError}
-   * carrying the activation link (the next tool call resumes into the new project).
-   */
-  async resetAndReauthorize() {
-    await this.store.clear();
-    await this.store.clearPending();
-    return this.getAccessToken();
-  }
-  async doRefresh() {
-    const creds = await this.store.read();
-    if (!creds?.refreshToken) return null;
-    let res;
-    try {
-      res = await this.fetchImpl(`${this.config.deviceBaseUrl}/refresh`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ refresh_token: creds.refreshToken })
-      });
-    } catch {
-      return null;
-    }
-    if (res.ok) {
-      const body = await res.json();
-      return this.persist(body);
-    }
-    const err = await res.json().catch(() => ({}));
-    if (err.error === "invalid_grant" || res.status === 401 || res.status === 403) {
-      await this.store.clear();
-    }
-    return null;
-  }
-  async persist(body) {
-    const creds = {
-      accessToken: body.access_token,
-      refreshToken: body.refresh_token,
-      accessTokenExpiresAt: this.now() + body.expires_in * 1e3,
-      workspaceId: body.workspace_id,
-      projectId: body.project_id
-    };
-    await this.store.write(creds);
-    return creds.accessToken;
-  }
-};
+import { loadConfig, FileTokenStore, DeviceAuthClient } from "@bettercms-ai/device-auth";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -2282,6 +1980,7 @@ var LAYOUT_SECTION_ICON_SET = new Set(LAYOUT_SECTION_ICONS);
 
 // src/tools.ts
 import { BetterCMSError } from "@bettercms-ai/sdk";
+import { DeviceAuthPendingError } from "@bettercms-ai/device-auth";
 var FRAMEWORK_CHOICES = ["astro", "next", "react-ts", "other"];
 var FRAMEWORK_LABELS = {
   astro: "Astro \u2014 recommended default, static by default and fastest to publish",
@@ -3326,6 +3025,24 @@ function buildToolDefs(deps) {
         z.object({}).shape,
         async (c) => ok("Approved conversion plan.", await data(c, "GET", `/management/projects/current/conversion-plan`))
       ),
+      def(
+        "get_componentize_plan",
+        "Get the plan for turning this site's sections into components",
+        "What this site's SECTIONS would become as components \u2014 a proposal that creates nothing, changes nothing and is computed live on every call. For a site whose pages were DERIVED at import (the site get_conversion_brief describes), each top-level field GROUP is one section: `hero-*` and `faq-*` keys, and the repeaters the import already folded (`group-*`). Per page it returns each section's `groupKey`, its `sectionType` family (Hero, FAQ, CTA, Features, Social proof\u2026), its leaf `fields` (key, path, type, the value the CMS holds), a `shapeHash`, and either the component that already renders it (`reuse.componentId`) or the one this plan proposes (`reuse.proposedSlug`) \u2014 and the components themselves under `components`: a NEW one carries the exact `props` and `blockJson` create_component would take, while a row for a component that ALREADY EXISTS carries its `componentId`, `slug` and `name` and no definition, because nothing will be written for it. Groups with the SAME shape across pages collapse into ONE component with several placements. `pending` says why a group is not offered: `NO_GROUP_ROOT` (the page's field keys are still the derive lane's own \u2014 `h1-welcome`, `p-we-build-things` \u2014 so there is no family to group by; rename them into families first), `NOT_A_SECTION` (a lone scalar with no family, or the page's own metadata \u2014 a section is a group field, a repeater, or a family two or more leaves share, so a legal page of `title`/`metaDescription`/`intro` proposes nothing), `ALREADY_COMPONENTIZED`, `EMPTY_GROUP`, `NESTED_REPEATER` (a repeater inside a repeater \u2014 one prop cannot describe two levels of rows), `PAGE_NOT_EMPTY` (the page holds blocks this lane does not own and will not overwrite). Chrome is NEVER a section: `nav-`/`footer-` keys and everything promoted into the project Layout are edited through the Layout. Keep the `digest` \u2014 componentize_sections refuses any other.",
+        z.object({}).shape,
+        async (c) => ok("Componentize plan.", await data(c, "GET", `/management/projects/current/componentize-plan`))
+      ),
+      def(
+        "componentize_sections",
+        "Turn this site's derived sections into components",
+        "Turn this site's derived sections into components. CONFIRM WITH THE USER FIRST: show them get_componentize_plan's sections and say how many components it will create and which pages it will rewrite. It creates each proposed component as a DRAFT (its `sectionType` family, category 'section', placeable on any page) and replaces each page's DRAFT blocks with an ordered list of `component` instances \u2014 one per group, each carrying `props.bind: \"<groupKey>\"`, which points at the page field group that already holds the copy. So nothing is copied and nothing moves: the page keeps its `fields`, its values and its bindings, click-to-edit keeps working and the coverage meter does not change. Pass the plan's `digest`; a 409 `stale-plan` means the site changed since you read that plan, so read it again, show the user what changed and confirm again. Call it with `dryRun: true` first \u2014 same receipt, nothing written. Running it twice is safe: a group that already has a placement comes back in `sections.pending` as ALREADY_COMPONENTIZED and no second component is created. DRAFTS ONLY \u2014 an unpublished component renders as an EMPTY STRING on the live site, so publish_component each one and publish the pages before this reaches a visitor. Then run `npx @bettercms-ai/convert --componentize` in the repo so its templates render these sections from `pages[].blocks`.",
+        z.object({
+          digest: z.string().min(1).describe("The `digest` get_componentize_plan returned. A different one is refused with 409 stale-plan."),
+          pageIds: z.array(z.string().min(1)).optional().describe("Componentize only these pages (ids from the plan). Omit for every page the plan lists."),
+          dryRun: z.boolean().optional().describe("true = return the receipt without writing anything. Do this first.")
+        }).shape,
+        async (c, a) => ok("Componentized the sections.", await data(c, "POST", `/management/projects/current/componentize`, { digest: a.digest, pageIds: a.pageIds, dryRun: a.dryRun }))
+      ),
       def(
         "get_analytics_overview",
         "Get traffic overview",
@@ -4110,6 +3827,20 @@ sibling calls it \`headline\` silently drops that content on the swap.
 Pair \`sectionType\` with a library \`category\` (hero, content, social-proof, conversion) or
 the component never appears in the editor's "Add a section" picker.
 
+**An IMPORTED site gets there without you writing any of that.** Its pages were derived at
+import \u2014 flat field groups (\`hero-title\`, \`faq-question\`, the repeaters folded as \`group-*\`)
+and an empty \`blockJson\` \u2014 so there is nothing in the picker and no section to swap. Read
+\`get_componentize_plan\`: it groups those fields into sections, names each family, and proposes
+one component per SHAPE (the same hero on two pages is one component with two placements),
+with every string, link and image already declared as a prop. Show the user the plan and
+**confirm before writing**, then \`componentize_sections { digest, dryRun: true }\` and, once the
+receipt reads right, without \`dryRun\`. Each page's blocks become ordered \`component\`
+instances carrying \`props.bind\` \u2014 the field group keeps the copy, so nothing moves and
+click-to-edit keeps working. Then run \`npx @bettercms-ai/convert --componentize\` in the repo
+so its templates render those sections from \`pages[].blocks\`, and finish with the publishes:
+\`publish_component\` every new component and publish the pages, or the site renders the
+sections as empty strings.
+
 ## 5. Blocks and modular fields
 
 A \`kind:'block'\` model holds no entries of its own; it exists to be stacked inside another
@@ -4924,6 +4655,7 @@ function buildServer(deps) {
 }
 
 // src/index.ts
+import { DeviceAuthClient as DeviceAuthClient2, loadConfig as loadConfig2 } from "@bettercms-ai/device-auth";
 async function main() {
   const config = loadConfig();
   const store = new FileTokenStore(config.credentialsPath, config.apiUrl);
@@ -4951,8 +4683,8 @@ if (isMainModule()) {
   });
 }
 export {
-  DeviceAuthClient,
+  DeviceAuthClient2 as DeviceAuthClient,
   buildServer,
-  loadConfig
+  loadConfig2 as loadConfig
 };
 //# sourceMappingURL=index.js.map