draftgo-cli 4.0.1 → 4.0.22

package/src/commands/customService.js

@@ -1,8 +1,10 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 const log = require('../logger');
 const services = require('../customServices');
+const { report, formatSummary, formatStat } = require('../diffReport');
 
 function ids(positional) { return positional.map(String).filter(Boolean); }
 function isServiceType(value) {
@@ -28,9 +30,10 @@ async function checkout(projectDir, positional, flags = {}) {
 async function commit(projectDir, positional, flags = {}) {
   const values = ids(positional);
   if (!values.length) { log.err('Usage: draftgo commit custom-services <id...>'); return 1; }
-  const result = await services.commit(projectDir, values);
+  // The user-facing custom-service commit is a complete delivery operation.
+  const result = await services.publish(projectDir, values);
   if (flags.output === 'json') output(flags, result);
-  else result.forEach((item) => log.ok(`custom service ${item.resource_id}: ${item.status}`));
+  else result.forEach((item) => log.ok(`custom service ${item.id || item.resource_id}: published (commit + validate + publish)`));
   return 0;
 }
 
@@ -38,7 +41,18 @@ async function diff(projectDir, positional, flags = {}) {
   const id = positional[0];
   if (!id) { log.err('Usage: draftgo diff custom-services <id>'); return 1; }
   const result = services.diff(projectDir, id);
-  if (flags.output === 'json') output(flags, result);
+  const concise = Boolean(flags.stat || flags.summary);
+  const value = concise ? report(result.entry, result.file_outputs.map((file) => ({
+    path: file.filename,
+    changed: file.changed,
+    output: file.output,
+    base_path: path.join(result.entry.base_dir, file.filename),
+    local_path: path.join(result.entry.local_dir, file.filename),
+  }))) : null;
+  if (flags.output === 'json' && concise) output(flags, value);
+  else if (flags.output === 'json') output(flags, result);
+  else if (flags.stat) process.stdout.write(formatStat(value));
+  else if (flags.summary) process.stdout.write(formatSummary(value));
   else if (result.changed) process.stdout.write(result.output);
   else log.dim(`custom service ${id}: no local changes`);
   return 0;
@@ -60,8 +74,10 @@ async function test(projectDir, positional, flags = {}) {
   const readJSON = (value) => value ? JSON.parse(fs.readFileSync(String(value), 'utf8')) : undefined;
   const policy = String(flags['side-effect-policy'] || 'deny').toLowerCase();
   if (!['deny', 'mock', 'live'].includes(policy)) throw new Error('--side-effect-policy must be deny, mock, or live.');
+  const source = String(flags.source || 'draft').toLowerCase();
+  if (!['auto', 'draft', 'published'].includes(source)) throw new Error('--source must be auto, draft, or published.');
   const result = await services.test(projectDir, id, input, { handler: flags.handler, headers: readJSON(flags.headers), user: readJSON(flags.user),
-    testWrite: Boolean(flags['test-write']), sideEffectPolicy: policy });
+    testWrite: Boolean(flags['test-write']), sideEffectPolicy: policy, source });
   if (flags.output === 'json') output(flags, result);
   else log[result.status === 'success' ? 'ok' : 'err'](`custom service ${id}: ${result.status}`);
   return result.status === 'success' ? 0 : 1;

package/src/commands/dataRange.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+// DataRange is represented by db_meta record policies; it is not a second
+// authorization scope or a free-form client-side filter.
+const OPERATIONS = Object.freeze({
+  list: 'list_meta_api_db_meta_get',
+  create: 'create_meta_api_db_meta_post',
+  get: 'get_meta_api_db_meta__type__get',
+  update: 'update_meta_api_db_meta__id__put',
+  batch: 'update_meta_batch_api_db_meta_batch_patch',
+  delete: 'delete_meta_api_db_meta__id__delete',
+});
+
+function operationKey(value) {
+  const action = String(value || 'list').trim().toLowerCase();
+  return OPERATIONS[action] ? action : '';
+}
+
+async function dataRangeCommand(projectDir, positional, flags = {}) {
+  const action = operationKey(positional[0]);
+  if (!action) {
+    log.err('Usage: draftgo data-range list|create|get|update|batch|delete --input <json-file>');
+    return 1;
+  }
+  return callOperation(projectDir, OPERATIONS[action], flags);
+}
+
+module.exports = dataRangeCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;

package/src/commands/delete.js

@@ -7,6 +7,12 @@ const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
 const { cachedDescription, normalizeDescription, storeDescription } = require('../apiContractCache');
+const {
+  isContractCompatibilityError,
+  isHardContractIncompatibility,
+  sameOperationContract,
+  incompatibleOperationError,
+} = require('../contractCompatibility');
 
 function readParams(projectDir, flags) {
   const raw = flags.params ? String(flags.params)
@@ -65,10 +71,15 @@ async function deleteResource(projectDir, positional, flags = {}) {
   try {
     result = await invoke();
   } catch (error) {
-    if (error.code !== 'CONTRACT_CHANGED') throw error;
+    if (!isContractCompatibilityError(error)) throw error;
+    if (isHardContractIncompatibility(error)) throw incompatibleOperationError(selectedOperation, error);
+    const previousContract = contract;
     const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: selectedOperation });
     contract = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
     if (!contract) throw new Error('DraftGo API description is missing contract revision metadata.');
+    if (!sameOperationContract(previousContract, contract)) {
+      throw incompatibleOperationError(selectedOperation, error);
+    }
     result = await invoke();
   }
   if (flags.output === 'json') console.log(JSON.stringify(result, null, 2));

package/src/commands/diff.js

@@ -2,19 +2,35 @@
 
 const log = require('../logger');
 const { diffResource } = require('../worktree');
+const { report, formatSummary, formatStat } = require('../diffReport');
+const { absolutePath } = require('../worktree/manifest');
 
 function diff(projectDir, positional, flags = {}) {
   const [resourceType, resourceId] = positional;
   if (!resourceType || !resourceId) {
-    log.err('Usage: draftgo diff <pages|nav|docs> <id>');
+    log.err('Usage: draftgo diff <pages|nav|docs|custom-services> <id>');
     return 1;
   }
   if (require('./customService').isServiceType(resourceType)) {
     return require('./customService').diff(projectDir, [resourceId], flags);
   }
   const result = diffResource(projectDir, resourceType, resourceId);
-  if (flags.output === 'json') {
+  const concise = Boolean(flags.stat || flags.summary);
+  const value = concise ? report(result.entry, [{
+    path: result.entry.local_path,
+    changed: result.changed,
+    output: result.output,
+    base_path: absolutePath(projectDir, result.entry.base_path),
+    local_path: absolutePath(projectDir, result.entry.local_path),
+  }]) : null;
+  if (flags.output === 'json' && concise) {
+    console.log(JSON.stringify(value, null, 2));
+  } else if (flags.output === 'json') {
     console.log(JSON.stringify({ changed: result.changed, entry: result.entry, diff: result.output }, null, 2));
+  } else if (flags.stat) {
+    process.stdout.write(formatStat(value));
+  } else if (flags.summary) {
+    process.stdout.write(formatSummary(value));
   } else if (result.changed) {
     process.stdout.write(result.output);
   } else {

package/src/commands/grant.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+const OPERATIONS = Object.freeze({
+  list: 'listAccessGrants',
+  create: 'createAccessGrant',
+  get: 'getAccessGrant',
+  revoke: 'revokeAccessGrant',
+});
+
+function operationKey(value) {
+  const action = String(value || 'list').trim().toLowerCase();
+  return OPERATIONS[action] ? action : '';
+}
+
+async function grantCommand(projectDir, positional, flags = {}) {
+  const action = operationKey(positional[0]);
+  if (!action) {
+    log.err('Usage: draftgo grant list|create|get|revoke [--input <json-file>]');
+    return 1;
+  }
+  return callOperation(projectDir, OPERATIONS[action], flags);
+}
+
+module.exports = grantCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;

package/src/commands/group.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+const OPERATIONS = Object.freeze({
+  list: 'listUserGroups',
+  create: 'createUserGroup',
+  get: 'getUserGroup',
+  update: 'updateUserGroup',
+  replace: 'replaceUserGroup',
+  remove: 'removeUserGroup',
+  'members.list': 'listUserGroupMembers',
+  'members.add': 'addUserGroupMember',
+  'members.remove': 'removeUserGroupMember',
+});
+
+function operationKey(parts) {
+  const values = parts.map((part) => String(part || '').trim().toLowerCase()).filter(Boolean);
+  if (values.length === 1) return values[0] === 'delete' ? 'remove' : values[0];
+  if (values.length === 2 && ['member', 'members'].includes(values[0])) {
+    return `members.${values[1] === 'delete' ? 'remove' : values[1]}`;
+  }
+  return '';
+}
+
+async function groupCommand(projectDir, positional, flags = {}) {
+  const key = operationKey(positional);
+  if (!OPERATIONS[key]) {
+    log.err('Usage: draftgo group list|create|get|update|replace|remove | members list|add|remove [--input <json-file>]');
+    return 1;
+  }
+  return callOperation(projectDir, OPERATIONS[key], flags);
+}
+
+module.exports = groupCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;

package/src/commands/help.js

@@ -13,8 +13,8 @@ function help() {
 
   console.log(`draftgo v${getPackageVersion()} - DraftGo workbench CLI for AI coding agents
 
-DraftGo Next frontend baseline: React + Vite.
-Database pages may use native web technologies or bundled component libraries.
+DraftGo shell baseline: React + Vite. Database Pages default to native HTML,
+Tailwind CSS 4, and Basecoat UI; Oat UI remains an optional Web Components layer.
 MCP handles live discovery and structured resources; complete page, navigation,
 document, and custom-service bodies use checkout/commit outside MCP context.
 The installed Skill routes agents to task-specific References and MCP tools.
@@ -26,9 +26,9 @@ Usage:
                                     refresh installed or detected Skills.
   draftgo uninstall <target|all>   Remove Skill files. --purge also removes
                                     the entire .draftgo/ runtime directory.
-  draftgo status                   Show installed targets and Skill version.
+  draftgo status                   Show connection health, current scope, targets, and Skill version.
 
-  draftgo connect [<target>...]    Verify and save server/SAT, then configure
+  draftgo connect [<target>...]    Verify and save server/API Key, then configure
                                     a detected or explicit MCP host. This never
                                     downloads DraftGo business resources.
   draftgo mcp setup [<target>...]  Merge project-level stdio MCP configuration.
@@ -36,24 +36,42 @@ Usage:
   draftgo mcp test                 Test project, resource, and API MCP calls.
   draftgo mcp serve                Bridge local stdio to the remote /mcp endpoint.
 
-  draftgo map                      Read remote overview/resources through MCP and
-                                    overlay local checkout state.
-  draftgo checkout <type> <id...>  Download pages/nav/docs body + verified base.
+  draftgo map [--type <type>]      Locate bounded remote resource metadata and
+                                    overlay matching local checkout state.
+                                    Use --route/--title for exact selection.
+  draftgo checkout <type> <id...>  Download a long-form body + verified base,
+                                    including custom-service worktrees.
                                     --force explicitly replaces local changes.
   draftgo check [custom-services <id...>]
                                     Validate all checkouts or selected custom services.
                                     --remote also compares remote hash/version.
   draftgo verify [<type> <id...>]   Run the default delivery verification.
                                     Browser options are explicit and optional.
-  draftgo diff <type> <id>         Show checkout base versus local body.
-  draftgo commit <type> <id...>    Validate and upload complete checked-out bodies.
+  draftgo diff <type> <id>         Show checkout base versus local body/files.
+                                    --stat/--summary omit the full patch.
+  draftgo commit <type> <id...>    Validate and upload complete checked-out bodies/files.
+  draftgo components search <query>  Search the live component catalog.
+  draftgo components show <library/component>
+                                    Show HTML, props, slots, CSS variables and revision.
+  draftgo components expand --page <id> --instance <data-dg-instance>
+                                    Expand one component in a checked-out Page worktree.
+  draftgo components libraries list|show|create|update|delete
+                                    Manage component libraries.
+  draftgo components list|create|copy|delete
+                                    Manage component catalog entries.
+  draftgo components checkout|diff|verify|commit|publish <library/component>
+                                    Develop a component draft locally, then publish explicitly.
+  draftgo components import <zip> [--dry-run]
+  draftgo components export <library> [--file <zip>]
+                                    Transfer standard DraftGo component archives.
   draftgo refresh <type> <id...>   Safely refresh a clean checkout from the cloud.
   draftgo validate custom-services <id>
                                     Build and inspect the current cloud draft.
-  draftgo test custom-services <id> [--handler <selector>]
+  draftgo test custom-services <id> [--source <source>] [--input <file>] [--handler <selector>]
                                     Run the cloud draft in the DraftGo Runner.
   draftgo publish custom-services <id...>
-                                    Publish validated drafts atomically.
+                                    Publish current validated drafts; batch errors
+                                    report services already completed.
   draftgo reconcile <type> <id...> Repair stale metadata only when local equals remote.
   draftgo conflicts                List unresolved conflicts; --all includes resolved.
   draftgo conflict show <type> <id>
@@ -73,6 +91,18 @@ Usage:
                                     Describe one live API operation through MCP.
   draftgo api call <operation_id> --input <json-file>
                                     Call one described operation with UTF-8 JSON.
+  draftgo capabilities list|search|show|audit
+                                    Discover and audit the current server's live operation catalog.
+  draftgo space <action>            Manage spaces and workspace members.
+  draftgo group <action>            Manage workspace groups and group members.
+  draftgo grant list|create|get|revoke
+                                    Manage platform/space AccessGrants.
+  draftgo api-key status|create|update|delete|rotate|reset|enable|disable
+                                    Manage the current user's API key through MCP.
+  draftgo role permissions|list|create|get|update|delete
+                                    Manage structured permission templates.
+  draftgo data-range list|create|get|update|batch|delete
+                                    Manage db_meta record policies (none|owner|all).
   draftgo delete <operation_id> [id]
                                     Confirm and call a live delete operation.
   draftgo deploy [<type> <id...>]  Check, then diff or commit checked-out content.
@@ -96,7 +126,9 @@ Important flags:
   --server <url>           (connect) DraftGo base URL.
   --mcp-url <url>          (connect) Explicit endpoint; standard /mcp derives the
                            base URL; custom paths also need --server.
-  --token <sat>            (connect) SAT for non-interactive use.
+  --api-key <key>          (connect) DraftGo user API Key for non-interactive use.
+  --scope-type space --space-id <id>
+                           (connect) Save a target space for workspace resources.
   --timeout <ms>           (connect/mcp test) Network timeout.
   --allow-offline          (connect) Save only after explicitly accepting a
                            failed MCP validation.
@@ -107,15 +139,25 @@ Important flags:
   --connect                (init) Continue into DraftGo server connection.
   --no-setup               (init) Install the Skill without either setup flow.
   --output json            Print machine-readable output where supported.
-  --type <type>            (map) pages | nav/navigations | docs/articles.
+  --type <type>            (map) pages | nav/navigations | docs/articles |
+                           custom-services.
+  --route <path>           (map) Select resources with this exact route.
+  --title <title>          (map) Select resources with this exact title.
+  --limit <1-100>          (map) Maximum resources returned per type/page;
+                           defaults to 20.
+  --cursor <cursor>        (map) Continue one typed map result page.
+  --summary                (map/diff) Print bounded resource or change summary.
+  --stat                   (diff) Print per-file and total change statistics.
   --strict                 Treat check warnings as failures.
   --remote                 (check) Compare checkout hashes/versions with remote.
   --yes                    Skip supported confirmation prompts.
   --operation-id <id>      (delete) Select an operation explicitly.
   --params <json>          (api call/delete) Pass an API parameter object.
-  --input <file>           (api call/delete) Read a UTF-8 JSON parameter object.
+  --input <file>           (api call/delete/custom-service test) Read a UTF-8
+                           JSON object.
   --handler <selector>     (custom-service test) route:METHOD:/path, event:name,
                            scheduled:name, or a handler name.
+  --source <source>        (custom-service test) draft (default), auto, or published.
   --headers/--user <file>  (custom-service test) Read JSON test identity data.
   --test-write             (custom-service test) Permit declared write testing.
   --side-effect-policy <mode>
@@ -127,7 +169,7 @@ Important flags:
   --viewport <mode>        (verify) mobile | desktop | both.
   --frame <mode>           (verify) auto | top | all | <iframe-selector>.
   --token <mode>           (verify) auto | never; auto appends the configured
-                           SAT to same-origin URLs as the token query parameter.
+                           API Key to same-origin URLs as the token query parameter.
   --screenshot <mode>      (verify) always | never; always alone captures a screenshot.
   --browser <name>         (verify) chromium | chrome | msedge.
   --browser-path <file>    (verify) Explicit browser executable; environment
@@ -136,8 +178,8 @@ Important flags:
   --width/--height <px>    (verify) Override the default 1440x900 desktop viewport.
 
 Security:
-  .draftgo/config.json stores the server and SAT and is gitignored. Host MCP
-  files contain only "draftgo mcp serve"; they never contain the SAT.
+  .draftgo/config.json stores the server and API Key and is gitignored. Host MCP
+  files contain only "draftgo mcp serve"; they never contain the API Key.
 
 MCP targets (project config or status):
 ${mcpTargets}
@@ -147,13 +189,15 @@ ${targets}
 
 Examples:
   draftgo init codex
-  draftgo connect codex --server https://draftgo.example --token <sat>
+  draftgo connect codex --server https://draftgo.example --api-key <key>
   draftgo mcp test
-  draftgo map --output json
+  draftgo map --type pages --route /admin/channel-ops --summary --output json
   draftgo checkout pages 42
   draftgo verify pages 42
-  draftgo diff pages 42
+  draftgo diff pages 42 --stat
   draftgo commit pages 42
+  draftgo checkout custom-services 12
+  draftgo test custom-services 12 --handler route:POST:/health --input request.json
   draftgo work start "Build document management and role permissions"
   draftgo work complete 1 --note "Verification and delivery passed"
   draftgo deploy docs 7 --delivery preview

package/src/commands/init.js

@@ -80,8 +80,8 @@ async function init(projectDir, positional, flags) {
   const interactive = process.stdin.isTTY && process.stdout.isTTY;
 
   if (!hasConfig && !flagSkip) {
-    // 非交互场景下，如果同时给了 --server 和 --token，直接走 connect，不再阻塞在 TTY 提示上。
-    if (flags.server && flags.token && !flagConnect) {
+    // Non-interactive setup can connect immediately with a server and API Key.
+    if (flags.server && (flags['api-key'] || flags.token) && !flagConnect) {
       return await require('./connect')(projectDir, [], flags);
     }
     if (flagConnect) {
@@ -92,7 +92,7 @@ async function init(projectDir, positional, flags) {
       log.plain(`  ${log.c.cyan('[A]')} 连接基座服务`);
       log.dim('      使用已有 DraftGo 服务，接下来输入 BaseURL 和系统访问令牌。');
       log.plain(`  ${log.c.cyan('[B]')} 本地启动基座`);
-      log.dim('      使用 Docker 启动 DraftGo；按需准备共享的 MySQL、Redis 和 Milvus。');
+      log.dim('      使用 Docker 启动 DraftGo；按需准备共享的 MySQL、Redis 和 Qdrant。');
       log.plain(`  ${log.c.cyan('[C]')} 稍后自行处理`);
       log.dim('      仅安装 Skill，不写入服务配置，也不创建容器。');
       const choice = (await ask('请选择 [A/B/C]', { default: 'C' })).trim().toUpperCase();

package/src/commands/map.js

@@ -6,6 +6,7 @@ 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 customServices = require('../customServices');
 
 const REMOTE_RESOURCE_TYPES = Object.freeze({
@@ -40,6 +41,11 @@ function claimsMorePages(value) {
     && (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 normalizeMapResourceType(value) {
   if (require('./customService').isServiceType(value)) return 'custom_services';
   return REMOTE_RESOURCE_TYPES[canonicalResourceType(value)];
@@ -51,6 +57,79 @@ function requestedResourceTypes(flags = {}) {
     : [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);
+  if (type === 'custom_services') return `custom_services:${resource.resource_id}`;
+  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 listRemoteResourceType(session, resourceType, options = {}) {
   const resources = [];
   const seen = new Set();
@@ -92,19 +171,32 @@ function checkoutChanged(entry) {
 async function mapCommand(projectDir, flags = {}) {
   const resourceTypes = requestedResourceTypes(flags);
   const config = loadProjectConfig(projectDir);
-  const session = await openToolSession(config, [TOOL_NAMES.projectOverview, TOOL_NAMES.resourceList]);
-  const [remote, checkouts] = await allWithAbort([
-    (options) => allWithAbort([
-      (options) => callStructured(session, TOOL_NAMES.projectOverview, {}, options),
-      (options) => listRemoteResources(session, resourceTypes, options),
-    ], options),
+  const searching = flags.route != null || flags.title != null;
+  const session = await openToolSession(config, [searching ? TOOL_NAMES.resourceSearch : TOOL_NAMES.resourceList]);
+  const remote = await listMapResources(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) => entry.resource_type === 'custom_services'
+      ? selected.has(`custom_services:${entry.resource_id}`)
+      : selected.has(`${canonicalResourceType(entry.resource_type)}:${entry.resource_id}`))
+    : manifestEntries;
+  const contentEntries = statusEntries.filter((entry) => entry.resource_type !== 'custom_services');
+  const serviceIds = statusEntries
+    .filter((entry) => entry.resource_type === 'custom_services')
+    .map((entry) => entry.resource_id);
+  const checkouts = (await allWithAbort([
     async (options) => {
       const [contentStatus, serviceStatus] = await Promise.all([inspectRemoteCheckouts(projectDir, {
         config,
         client: session.client,
         tools: session.tools,
         signal: options.signal,
-      }), customServices.inspectRemote(projectDir, { config, signal: options.signal })]);
+        entries: contentEntries,
+      }), customServices.inspectRemote(projectDir, { config, signal: options.signal, ids: serviceIds })]);
       return [...contentStatus, ...serviceStatus].map((entry) => ({
         ...entry,
         exists: entry.local_hash !== null,
@@ -112,28 +204,58 @@ async function mapCommand(projectDir, flags = {}) {
         changed: checkoutChanged(entry),
       }));
     },
-  ]);
-  const [overview, resources] = remote;
+  ]))[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,
-    overview,
     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(result, null, 2));
+    console.log(JSON.stringify(flags.summary ? summary : result, null, 2));
     return 0;
   }
   log.title('draftgo map');
-  log.info(`Remote resources: ${resources.length}`);
-  const counts = new Map();
-  for (const resource of resources) {
-    const type = resource.resource_type || resource.type || 'unknown';
-    counts.set(type, (counts.get(type) || 0) + 1);
-  }
+  log.info(`Remote resources returned: ${resources.length}`);
   for (const [type, count] of [...counts.entries()].sort()) log.plain(`  ${type}: ${count}`);
   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}`
@@ -149,4 +271,10 @@ 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.normalizeRoute = normalizeRoute;
+module.exports.resourceMatches = resourceMatches;
+module.exports.positiveLimit = positiveLimit;
+module.exports.reportedTotal = reportedTotal;
 module.exports.checkoutChanged = checkoutChanged;

package/src/commands/mcp.js

@@ -17,7 +17,7 @@ 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 'SAT authentication or authorization failed.';
+  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.';
@@ -79,7 +79,7 @@ function status(projectDir, positional = [], flags = {}) {
   let exitCode = 0;
   try {
     const config = loadProjectConfig(projectDir);
-    log.plain(`  project      configured (${config.server}; SAT present)`);
+    log.plain(`  project      configured (${config.server}; API Key present)`);
   } catch (error) {
     log.plain(`  project      not ready (${error.message})`);
     exitCode = 1;