draftgo-cli 1.0.4

package/src/commands/local.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+const log = require('../logger');
+const { exists } = require('../fsx');
+const { detectDocker } = require('../localRuntime/detect');
+const { runWizard } = require('../localRuntime');
+
+function composeFile(projectDir) {
+  return path.join(projectDir, '.draftgo', 'docker', 'docker-compose.yaml');
+}
+
+function runCompose(projectDir, args, stdio = 'inherit') {
+  const docker = detectDocker();
+  if (!docker.ok) {
+    log.err(docker.reason === 'compose-missing'
+      ? '检测到 Docker，但缺少 compose 插件。'
+      : '未检测到可用 Docker。');
+    return 1;
+  }
+
+  const file = composeFile(projectDir);
+  if (!exists(file)) {
+    log.err('未找到 .draftgo/docker/docker-compose.yaml。');
+    log.dim('  请先运行 `draftgo local setup` 生成本地 DraftGo stack。');
+    return 1;
+  }
+
+  let result;
+  try {
+    result = spawnSync(docker.composeCmd, [...docker.composeArgs, '-f', file, ...args], {
+      cwd: path.dirname(file),
+      stdio,
+      shell: false,
+    });
+  } catch (error) {
+    log.err(`Failed to start Docker Compose: ${error.message}`);
+    return 1;
+  }
+
+  if (result.error) {
+    log.err(`Failed to start Docker Compose: ${result.error.message}`);
+    return 1;
+  }
+  if (!Number.isInteger(result.status)) {
+    log.err(result.signal
+      ? `Docker Compose terminated by signal ${result.signal}.`
+      : 'Docker Compose did not report an exit status.');
+    return 1;
+  }
+  return result.status;
+}
+
+function local(projectDir, positional, flags = {}) {
+  const action = positional[0] || 'status';
+
+  switch (action) {
+    case 'setup':
+      return runWizard(projectDir, {
+        yes: !!(flags.yes || flags.y),
+        ...(flags.params ? { params: flags.params } : {}),
+      });
+    case 'start':
+      return runCompose(projectDir, ['up', '-d']);
+    case 'stop':
+      return runCompose(projectDir, ['down']);
+    case 'logs':
+      return runCompose(projectDir, ['logs', ...(positional.slice(1).length ? positional.slice(1) : ['-f', 'app'])]);
+    case 'status':
+      return runCompose(projectDir, ['ps']);
+    default:
+      log.err(`未知 local 子命令：${action}`);
+      log.dim('  可用：draftgo local setup | start | stop | logs | status');
+      return 1;
+  }
+}
+
+module.exports = local;

package/src/commands/map.js

@@ -0,0 +1,395 @@
+'use strict';
+
+const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { canonicalResourceType } = require('../worktree/types');
+const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+const { allWithAbort } = require('../mcp/parallel');
+const { inspectRemoteCheckouts } = require('../worktree/status');
+const { loadManifest } = require('../worktree/manifest');
+
+const REMOTE_RESOURCE_TYPES = Object.freeze({
+  pages: 'pages',
+  navigations: 'navigations',
+  docs: 'docs/articles',
+});
+const DEFAULT_REMOTE_RESOURCE_TYPES = Object.freeze(Object.values(REMOTE_RESOURCE_TYPES));
+const LIST_OPERATIONS = Object.freeze({
+  pages: 'listPage',
+  navigations: 'listNavigation',
+  'docs/articles': 'listDocAdminArticle',
+});
+
+function itemsFrom(value) {
+  if (Array.isArray(value)) return value;
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value.items)) return value.items;
+  if (Array.isArray(value.resources)) return value.resources;
+  if (value.data) return itemsFrom(value.data);
+  return [];
+}
+
+function nextCursor(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (Object.prototype.hasOwnProperty.call(value, 'next_cursor')) return value.next_cursor;
+  if (Object.prototype.hasOwnProperty.call(value, 'nextCursor')) return value.nextCursor;
+  return (value.has_more === true || value.hasMore === true)
+    && Object.prototype.hasOwnProperty.call(value, 'cursor')
+    ? value.cursor
+    : null;
+}
+
+function claimsMorePages(value) {
+  return !!value && typeof value === 'object'
+    && (value.has_more === true || value.hasMore === true);
+}
+
+function reportedTotal(value) {
+  const total = value && typeof value === 'object' ? value.total : null;
+  return Number.isInteger(total) && total >= 0 ? total : null;
+}
+
+function registryCursor(operationID, page) {
+  return Buffer.from(JSON.stringify({ operation_id: operationID, page }), 'utf8').toString('base64url');
+}
+
+function registryPageFromCursor(cursor, operationID) {
+  if (cursor == null || cursor === '') return 1;
+  try {
+    const value = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+    if (value && value.operation_id === operationID && Number.isSafeInteger(value.page) && value.page > 1) {
+      return value.page;
+    }
+  } catch { /* Report one stable CLI error below. */ }
+  throw new Error(`Map --cursor is not valid for Registry operation ${operationID}.`);
+}
+
+function queryProperties(operation) {
+  const schema = operation && operation.input_schema;
+  const query = schema && schema.properties && schema.properties.query;
+  return query && query.properties && typeof query.properties === 'object' ? query.properties : {};
+}
+
+function registryQuery(operation, operationID, flags) {
+  const properties = queryProperties(operation);
+  const query = {};
+  const limit = positiveLimit(flags.limit);
+  const cursor = flags.cursor == null ? '' : String(flags.cursor);
+  if (Object.prototype.hasOwnProperty.call(properties, 'cursor')) {
+    if (cursor) query.cursor = cursor;
+    if (Object.prototype.hasOwnProperty.call(properties, 'limit')) query.limit = limit;
+  } else if (Object.prototype.hasOwnProperty.call(properties, 'page')
+      && Object.prototype.hasOwnProperty.call(properties, 'page_size')) {
+    query.page = registryPageFromCursor(cursor, operationID);
+    query.page_size = limit;
+  } else if (cursor) {
+    throw new Error(`${operationID} does not expose a paginated Registry contract.`);
+  }
+
+  const search = flags.route != null ? normalizeRoute(flags.route)
+    : flags.title != null ? String(flags.title) : '';
+  if (search) {
+    const key = flags.route != null && Object.prototype.hasOwnProperty.call(properties, 'route')
+      ? 'route'
+      : ['search', 'q', 'query'].find((candidate) => Object.prototype.hasOwnProperty.call(properties, candidate));
+    if (key) query[key] = search;
+  }
+  return query;
+}
+
+function registryPagination(payload, operationID, query, returned) {
+  const serverCursor = nextCursor(payload);
+  if (serverCursor != null && serverCursor !== '') {
+    return {
+      next_cursor: String(serverCursor),
+      has_more: true,
+      total: reportedTotal(payload),
+    };
+  }
+  if (claimsMorePages(payload)) {
+    throw new Error(`${operationID} reported more pages without a cursor.`);
+  }
+  const total = reportedTotal(payload);
+  const page = Number(query.page);
+  const pageSize = Number(query.page_size);
+  const hasMore = Number.isSafeInteger(page) && Number.isSafeInteger(pageSize)
+    && (total != null ? page * pageSize < total : returned === pageSize);
+  return {
+    next_cursor: hasMore ? registryCursor(operationID, page + 1) : null,
+    has_more: hasMore,
+    total,
+  };
+}
+
+function normalizeMapResourceType(value) {
+  return REMOTE_RESOURCE_TYPES[canonicalResourceType(value)];
+}
+
+function requestedResourceTypes(flags = {}) {
+  return flags.type == null
+    ? DEFAULT_REMOTE_RESOURCE_TYPES
+    : [normalizeMapResourceType(flags.type)];
+}
+
+function normalizeRoute(value) {
+  // DraftGo stores page routes without surrounding slashes. Accept either the
+  // stored form or the browser form users naturally paste into the CLI.
+  return String(value == null ? '' : value).trim().replace(/^\/+|\/+$/g, '');
+}
+
+function positiveLimit(value, fallback = 20) {
+  if (value == null) return fallback;
+  if (!/^\d+$/.test(String(value)) || Number(value) < 1 || Number(value) > 100) {
+    throw new Error('Map --limit must be an integer between 1 and 100.');
+  }
+  return Number(value);
+}
+
+function resourceType(resource) {
+  return resource.resource_type || resource.type || 'unknown';
+}
+
+function resourceMatches(resource, flags = {}) {
+  const route = flags.route == null ? null : normalizeRoute(flags.route);
+  const title = flags.title == null ? null : String(flags.title);
+  return (route == null || normalizeRoute(resource.route) === route)
+    && (title == null || String(resource.title == null ? '' : resource.title) === title);
+}
+
+function resourceKey(resource) {
+  const type = resourceType(resource);
+  return `${canonicalResourceType(type)}:${resource.resource_id}`;
+}
+
+function paginationFrom(payload, resourceTypeName) {
+  const cursor = nextCursor(payload);
+  if ((cursor == null || cursor === '') && claimsMorePages(payload)) {
+    throw new Error(`DraftGo resource_list (${resourceTypeName}) reported more pages without a cursor.`);
+  }
+  return {
+    next_cursor: cursor == null || cursor === '' ? null : String(cursor),
+    has_more: claimsMorePages(payload) || (cursor != null && cursor !== ''),
+    total: reportedTotal(payload),
+  };
+}
+
+async function listRemoteResourcePage(session, resourceTypeName, flags = {}, options = {}) {
+  const filtered = flags.route != null || flags.title != null;
+  const args = { resource_type: resourceTypeName, limit: positiveLimit(flags.limit) };
+  if (flags.cursor != null && flags.cursor !== '') args.cursor = String(flags.cursor);
+  if (filtered) {
+    // resource_search narrows the remote candidate set; the strict equality
+    // checks below keep --route/--title deterministic even when search is fuzzy.
+    args.query = flags.route != null ? normalizeRoute(flags.route) : String(flags.title);
+  }
+  const payload = await callStructured(
+    session,
+    filtered ? TOOL_NAMES.resourceSearch : TOOL_NAMES.resourceList,
+    args,
+    options,
+  );
+  return { resources: itemsFrom(payload).filter((resource) => resourceMatches(resource, flags)), pagination: paginationFrom(payload, resourceTypeName) };
+}
+
+async function listMapResources(session, resourceTypes, flags, options = {}) {
+  if (flags.cursor != null && flags.cursor !== '' && resourceTypes.length !== 1) {
+    throw new Error('Map --cursor requires exactly one --type.');
+  }
+  const groups = await allWithAbort(resourceTypes.map((resourceTypeName) =>
+    (queryOptions) => listRemoteResourcePage(session, resourceTypeName, flags, queryOptions)), options);
+  return {
+    resources: groups.flatMap((group) => group.resources),
+    pagination: Object.fromEntries(groups.map((group, index) => [resourceTypes[index], group.pagination])),
+  };
+}
+
+async function listRegistryResources(projectDir, config, session, resourceTypes, flags = {}) {
+  const { registryRevision, descriptionForRevision } = require('./api');
+  if (flags.cursor != null && flags.cursor !== '' && resourceTypes.length !== 1) {
+    throw new Error('Map --cursor requires exactly one --type.');
+  }
+  const groups = await allWithAbort(resourceTypes.map((type) => async (options) => {
+    const operationID = LIST_OPERATIONS[type];
+    const revision = await registryRevision(session, operationID);
+    const description = await descriptionForRevision(projectDir, config, session, operationID, revision);
+    const operation = description.operation || {};
+    const query = registryQuery(operation, operationID, flags);
+    const invoke = {
+      operation_id: operationID,
+      registry_revision: revision,
+    };
+    if (Object.keys(query).length) invoke.query = query;
+    const payload = await callStructured(session, TOOL_NAMES.apiCall, invoke, options);
+    const response = payload && payload.response !== undefined ? payload.response
+      : payload && payload.data !== undefined ? payload.data : payload;
+    const responseItems = itemsFrom(response);
+    const resources = responseItems
+      .map((item) => ({ ...item, resource_type: type, resource_id: String(item.resource_id ?? item.id) }))
+      .filter((item) => item.resource_id && item.resource_id !== 'undefined')
+      .filter((item) => resourceMatches(item, flags));
+    return {
+      resources,
+      pagination: registryPagination(response, operationID, query, responseItems.length),
+    };
+  }));
+  return {
+    resources: groups.flatMap((group) => group.resources),
+    pagination: Object.fromEntries(groups.map((group, index) => [resourceTypes[index], group.pagination])),
+  };
+}
+
+async function listRemoteResourceType(session, resourceType, options = {}) {
+  const resources = [];
+  const seen = new Set();
+  let cursor = null;
+  for (let page = 0; page < 100; page += 1) {
+    const args = { resource_type: resourceType, limit: 100 };
+    if (cursor != null && cursor !== '') args.cursor = cursor;
+    const payload = await callStructured(session, TOOL_NAMES.resourceList, args, options);
+    resources.push(...itemsFrom(payload));
+    cursor = nextCursor(payload);
+    if (cursor == null || cursor === '') {
+      if (claimsMorePages(payload)) {
+        throw new Error(`DraftGo resource_list (${resourceType}) reported more pages without a cursor.`);
+      }
+      return resources;
+    }
+    const cursorKey = String(cursor);
+    if (seen.has(cursorKey)) {
+      throw new Error(`DraftGo resource_list (${resourceType}) repeated a cursor.`);
+    }
+    seen.add(cursorKey);
+  }
+  throw new Error(`DraftGo resource_list (${resourceType}) exceeded 100 pages.`);
+}
+
+async function listRemoteResources(session, resourceTypes = DEFAULT_REMOTE_RESOURCE_TYPES, options = {}) {
+  const groups = await allWithAbort(resourceTypes.map((resourceType) =>
+    (queryOptions) => listRemoteResourceType(session, resourceType, queryOptions)), options);
+  return groups.flat();
+}
+
+function checkoutChanged(entry) { return entry.local_hash !== null && entry.local_hash !== entry.base_hash; }
+
+async function mapCommand(projectDir, flags = {}) {
+  const resourceTypes = requestedResourceTypes(flags);
+  const config = loadProjectConfig(projectDir);
+  const searching = flags.route != null || flags.title != null;
+  let session;
+  let remote;
+  try {
+    session = await openToolSession(config, [searching ? TOOL_NAMES.resourceSearch : TOOL_NAMES.resourceList]);
+    remote = await listMapResources(session, resourceTypes, flags);
+  } catch (error) {
+    if (!error || error.code !== 'MCP_TOOL_UNAVAILABLE') throw error;
+    session = await openToolSession(config, [TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall]);
+    remote = await listRegistryResources(projectDir, config, session, resourceTypes, flags);
+  }
+  const manifestEntries = Object.values(loadManifest(projectDir).entries);
+  const selected = new Set(remote.resources.map(resourceKey));
+  // A filtered map is a focused inspection, so do not make unrelated local
+  // worktree state dominate its output. The unfiltered command retains the
+  // established full-worktree status behavior.
+  const statusEntries = searching
+    ? manifestEntries.filter((entry) => selected.has(`${canonicalResourceType(entry.resource_type)}:${entry.resource_id}`))
+    : manifestEntries;
+  const checkouts = (await allWithAbort([
+    async (options) => {
+      const contentStatus = await inspectRemoteCheckouts(projectDir, {
+        config,
+        client: session.client,
+        tools: session.tools,
+        signal: options.signal,
+        entries: statusEntries,
+      });
+      return contentStatus.map((entry) => ({
+        ...entry,
+        exists: entry.local_hash !== null,
+        current_hash: entry.local_hash,
+        changed: checkoutChanged(entry),
+      }));
+    },
+  ]))[0];
+  const resources = remote.resources;
+  const counts = new Map();
+  for (const resource of resources) {
+    const type = resourceType(resource);
+    counts.set(type, (counts.get(type) || 0) + 1);
+  }
+  const checkoutStates = new Map();
+  for (const entry of checkouts) {
+    const state = entry.state || (!entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean');
+    checkoutStates.set(state, (checkoutStates.get(state) || 0) + 1);
+  }
+  const result = {
+    server: config.server,
+    resources,
+    checkouts,
+    pagination: remote.pagination,
+  };
+
+  const summary = {
+    server: config.server,
+    summary: {
+      resources: {
+        returned: resources.length,
+        matched: resources.length,
+        returned_by_type: Object.fromEntries([...counts.entries()].sort()),
+        // This is the server's fuzzy-search/list candidate count before the
+        // client-side exact route/title check. It is null when not reported.
+        candidate_total_by_type: Object.fromEntries(Object.entries(remote.pagination)
+          .map(([type, page]) => [type, page.total])),
+      },
+      checkouts: { total: checkouts.length, by_state: Object.fromEntries([...checkoutStates.entries()].sort()) },
+      truncated: Object.values(remote.pagination).some((page) => page.has_more),
+      pagination: remote.pagination,
+    },
+  };
+
+  if (flags.output === 'json') {
+    console.log(JSON.stringify(flags.summary ? summary : result, null, 2));
+    return 0;
+  }
+  log.title('draftgo map');
+  log.info(`Remote resources returned: ${resources.length}`);
+  for (const [type, count] of [...counts.entries()].sort()) log.plain(`  ${type}: ${count}`);
+  if (!flags.summary) {
+    for (const resource of resources) {
+      log.plain(`  ${resourceType(resource)} ${resource.resource_id}: ${resource.title || '-'} route=${resource.route || '-'} code=${resource.code || '-'} slug=${resource.slug || '-'}`);
+    }
+  }
+  log.info(`Local checkouts: ${checkouts.length}`);
+  if (flags.summary) {
+    for (const [state, count] of [...checkoutStates.entries()].sort()) log.plain(`  ${state}: ${count}`);
+    for (const [type, page] of Object.entries(remote.pagination)) {
+      if (page.has_more) log.plain(`  ${type}: more results; use --type ${type} --cursor ${page.next_cursor}`);
+    }
+    return 0;
+  }
+  for (const entry of checkouts) {
+    const state = entry.state || (!entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean');
+    log.plain(`  ${entry.resource_type} ${entry.resource_id}: ${state}`
+      + ` local=${entry.local_hash || entry.current_hash || '-'} base=${entry.manifest_hash || entry.base_hash || '-'} remote=${entry.remote_hash || '-'} `
+      + `version=${entry.manifest_version ?? '-'}->${entry.remote_version ?? '-'} `
+      + `(${entry.local_path})`);
+  }
+  return 0;
+}
+
+module.exports = mapCommand;
+module.exports.itemsFrom = itemsFrom;
+module.exports.normalizeMapResourceType = normalizeMapResourceType;
+module.exports.requestedResourceTypes = requestedResourceTypes;
+module.exports.listRemoteResources = listRemoteResources;
+module.exports.listRemoteResourcePage = listRemoteResourcePage;
+module.exports.listMapResources = listMapResources;
+module.exports.listRegistryResources = listRegistryResources;
+module.exports.normalizeRoute = normalizeRoute;
+module.exports.resourceMatches = resourceMatches;
+module.exports.positiveLimit = positiveLimit;
+module.exports.reportedTotal = reportedTotal;
+module.exports.registryCursor = registryCursor;
+module.exports.registryPageFromCursor = registryPageFromCursor;
+module.exports.registryQuery = registryQuery;
+module.exports.registryPagination = registryPagination;
+module.exports.checkoutChanged = checkoutChanged;

package/src/commands/mcp.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { testConnection } = require('../mcp/client');
+const { redactText } = require('../mcp/protocol');
+const {
+  HOSTS,
+  detectHostTargets,
+  setupHosts,
+  statusHosts,
+} = require('../mcp/hosts');
+const { serveStdio } = require('../mcp/stdio');
+const { parseTimeout } = require('../timeout');
+
+function classifyMcpFailure(error) {
+  const message = String(error && error.message || error || '');
+  const code = error && error.code;
+  const status = error && error.status;
+  if (status === 401 || status === 403) return 'API Key authentication or authorization failed.';
+  if (/session|uninitialized|initialize first|not initialized/i.test(message)
+      || ['SESSION_EXPIRED', 'MCP_SESSION_EXPIRED', -32002].includes(code)) {
+    return 'The MCP session was lost or the server rejected the initialized state; check sticky sessions and service restarts.';
+  }
+  if (status >= 500) return 'The MCP service returned a server error; inspect the service request ID and logs.';
+  if (/tools\/call|tool/i.test(message)) return 'Tool invocation failed after protocol setup; inspect the tool contract and server handler.';
+  return 'Connection or MCP protocol negotiation failed.';
+}
+
+function targetArgs(positional, flags) {
+  const values = positional.slice();
+  if (flags.target) values.push(...String(flags.target).split(','));
+  return values.map((value) => String(value).trim()).filter(Boolean);
+}
+
+function printUsage() {
+  log.plain('Usage:');
+  log.plain('  draftgo mcp setup [target...]');
+  log.plain('  draftgo mcp status [target...]');
+  log.plain('  draftgo mcp test');
+  log.plain('  draftgo mcp serve');
+  log.dim(`  targets: ${HOSTS.map((host) => host.name).join(', ')}`);
+}
+
+function setup(projectDir, positional = [], flags = {}) {
+  const targets = targetArgs(positional, flags);
+  const detected = targets.length ? null : detectHostTargets(projectDir);
+  if (!targets.length && detected.length === 0) {
+    log.err('No supported AI host was detected in this project.');
+    log.dim('  Run `draftgo mcp setup <target>` to select one explicitly.');
+    return 1;
+  }
+
+  const results = setupHosts(projectDir, targets.length ? targets : detected.map((host) => host.name));
+  let configured = 0;
+  let unsupported = 0;
+  for (const result of results) {
+    if (!result.supported) {
+      unsupported += 1;
+      log.warn(`${result.host.displayName}: ${result.reason}`);
+      continue;
+    }
+    configured += 1;
+    if (result.changed) log.ok(`${result.host.displayName}: ${result.host.path}`);
+    else log.info(`${result.host.displayName}: already configured`);
+  }
+  if (!configured && unsupported) return 1;
+  if (!configured) {
+    log.err('No MCP host configuration was written.');
+    return 1;
+  }
+  return 0;
+}
+
+function status(projectDir, positional = [], flags = {}) {
+  const targets = targetArgs(positional, flags);
+  const results = statusHosts(projectDir, targets);
+  log.title('draftgo mcp status');
+  let exitCode = 0;
+  try {
+    const config = loadProjectConfig(projectDir);
+    log.plain(`  project      configured (${config.server}; API Key present)`);
+  } catch (error) {
+    log.plain(`  project      not ready (${error.message})`);
+    exitCode = 1;
+  }
+  for (const result of results) {
+    if (!result.supported) {
+      log.plain(`  - ${result.host.name.padEnd(12)} unsupported`);
+    } else if (result.configured && result.secure) {
+      log.plain(`  OK ${result.host.name.padEnd(12)} ${result.host.path}`);
+    } else if (result.error) {
+      log.plain(`  x  ${result.host.name.padEnd(12)} invalid config`);
+      exitCode = 1;
+    } else {
+      log.plain(`  -  ${result.host.name.padEnd(12)} not configured`);
+    }
+  }
+  return exitCode;
+}
+
+async function test(projectDir, _positional = [], flags = {}) {
+  let config;
+  const stages = [];
+  try {
+    config = loadProjectConfig(projectDir);
+    const result = await testConnection(config, {
+      timeoutMs: parseTimeout(flags.timeout),
+      onStage(stage, status) {
+        stages.push({ stage, status });
+        if (status === 'succeeded') log.ok(`MCP ${stage} succeeded.`);
+        else if (status === 'failed') log.err(`MCP ${stage} failed.`);
+        else log.step(`MCP ${stage}...`);
+      },
+    });
+    log.ok(`MCP diagnostic completed: ${result.testedCalls.length} tools/call checks passed.`);
+    log.dim(`  protocol: ${result.protocolVersion}`);
+    return 0;
+  } catch (error) {
+    const token = config && String(config.token || config.sat || '');
+    log.err(redactText(error && error.message ? error.message : error, [token]));
+    const last = stages[stages.length - 1];
+    if (last) log.info(`MCP diagnostic stopped at ${last.stage} (${last.status}).`);
+    log.info(classifyMcpFailure(error));
+    return 1;
+  }
+}
+
+async function serve(projectDir, _positional = [], _flags = {}) {
+  return serveStdio(projectDir);
+}
+
+async function mcp(projectDir, positional = [], flags = {}) {
+  const [action, ...rest] = positional;
+  if (action === 'setup') return setup(projectDir, rest, flags);
+  if (action === 'status') return status(projectDir, rest, flags);
+  if (action === 'test') return test(projectDir, rest, flags);
+  if (action === 'serve') return serve(projectDir, rest, flags);
+  printUsage();
+  return 1;
+}
+
+mcp.setup = setup;
+mcp.status = status;
+mcp.test = test;
+mcp.serve = serve;
+mcp.printUsage = printUsage;
+
+module.exports = mcp;
+module.exports.classifyMcpFailure = classifyMcpFailure;

package/src/commands/reconcile.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const log = require('../logger');
+const { reconcileResources } = require('../worktree');
+
+async function reconcile(projectDir, positional, flags = {}) {
+  const [resourceType, ...ids] = positional;
+  if (!resourceType || !ids.length) {
+    log.err('Usage: draftgo reconcile <pages|nav|docs> <id...>');
+    return 1;
+  }
+  const results = await reconcileResources(projectDir, resourceType, ids);
+  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
+  else for (const result of results) {
+    log.ok(`Reconciled ${result.resource_type} ${result.resource_id} -> ${result.base_version ?? result.base_revision}`);
+  }
+  return 0;
+}
+
+module.exports = reconcile;

package/src/commands/role.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+const OPERATIONS = Object.freeze({
+  permissions: 'listPermissions',
+  list: 'listRoles',
+  create: 'createRole',
+  get: 'getRole',
+  update: 'updateRole',
+  delete: 'deleteRole',
+});
+
+function operationKey(value) {
+  const action = String(value || 'list').trim().toLowerCase();
+  return OPERATIONS[action] ? action : '';
+}
+
+async function roleCommand(projectDir, positional, flags = {}) {
+  const action = operationKey(positional[0]);
+  if (!action) {
+    log.err('Usage: draftgo role permissions|list|create|get|update|delete [--input <json-file>]');
+    return 1;
+  }
+  return callOperation(projectDir, OPERATIONS[action], flags);
+}
+
+module.exports = roleCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;