draftgo-cli 3.0.56 → 4.0.22

package/src/apiContractCache.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+const WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+function cachePath(projectDir) {
+  return path.join(projectDir, '.draftgo', 'api-contract-cache.json');
+}
+
+function emptyCache(server) {
+  return { schema_version: SCHEMA_VERSION, server, operations: {} };
+}
+
+function readCache(projectDir, server) {
+  const file = cachePath(projectDir);
+  if (!fs.existsSync(file)) return emptyCache(server);
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!value || value.schema_version !== SCHEMA_VERSION || value.server !== server
+        || !value.operations || Array.isArray(value.operations)) return emptyCache(server);
+    return value;
+  } catch {
+    return emptyCache(server);
+  }
+}
+
+function normalizeDescription(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const operation = value.operation && typeof value.operation === 'object' ? value.operation : value;
+  const registryRevision = String(value.registry_revision || operation.registry_revision || '').trim();
+  const contractHash = String(value.contract_hash || operation.contract_hash || '').trim();
+  const operationId = String(operation.operation_id || '').trim();
+  if (!operationId || !registryRevision || !contractHash) return null;
+  const normalized = { ...operation };
+  delete normalized.registry_revision;
+  delete normalized.contract_hash;
+  return { operation: normalized, registry_revision: registryRevision, contract_hash: contractHash };
+}
+
+function cachedDescription(projectDir, server, operationId) {
+  const cached = readCache(projectDir, server).operations[String(operationId)];
+  return normalizeDescription(cached);
+}
+
+function acquire(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lock = `${file}.lock`;
+  const started = Date.now();
+  while (true) {
+    try {
+      const descriptor = fs.openSync(lock, 'wx', 0o600);
+      fs.closeSync(descriptor);
+      return lock;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+    }
+    try {
+      if (Date.now() - fs.statSync(lock).mtimeMs > 30_000) {
+        fs.rmSync(lock, { force: true });
+        continue;
+      }
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+      continue;
+    }
+    if (Date.now() - started >= 2000) return null;
+    Atomics.wait(WAIT, 0, 0, 10);
+  }
+}
+
+function writeAtomic(file, value) {
+  const temporary = `${file}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.rmSync(temporary, { force: true }); } catch { /* Best-effort cleanup. */ }
+  }
+}
+
+function storeDescription(projectDir, server, value) {
+  const normalized = normalizeDescription(value);
+  if (!normalized) return null;
+  const file = cachePath(projectDir);
+  const lock = acquire(file);
+  if (!lock) return normalized;
+  try {
+    const cache = readCache(projectDir, server);
+    cache.operations[normalized.operation.operation_id] = {
+      ...normalized,
+      described_at: new Date().toISOString(),
+    };
+    cache.updated_at = new Date().toISOString();
+    writeAtomic(file, cache);
+  } finally {
+    try { fs.rmSync(lock, { force: true }); } catch { /* Cache writes are best effort. */ }
+  }
+  return normalized;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  cachePath,
+  readCache,
+  normalizeDescription,
+  cachedDescription,
+  storeDescription,
+};

package/src/cli.js

@@ -8,13 +8,12 @@ const VALUE_FLAGS = new Set([
   'target',
   'server',
   'mcp-url',
+  'api-key',
   'token',
   'output',
   'url',
   'browser',
   'browser-path',
-  'resource',
-  'mobile-check',
   'ui',
   'frame',
   'viewport',
@@ -31,30 +30,35 @@ const VALUE_FLAGS = new Set([
   'params',
   'input',
   'type',
+  'route',
   'title',
-  'description',
-  'item-id',
-  'id',
-  'owner',
-  'original',
-  'original-requirement',
-  'clarified',
-  'clarified-requirement',
-  'expected-effect',
-  'effect',
-  'scope',
-  'out-of-scope',
-  'content',
-  'acceptance',
-  'module-logic',
-  'user-journey',
-  'item',
+  'limit',
+  'cursor',
   'date',
   'handler',
+  'source',
   'headers',
   'user',
   'side-effect-policy',
-  'evidence',
+  'page',
+  'instance',
+  'note',
+  'file',
+  'library',
+  'name',
+  'slug',
+  'category',
+  'description',
+  'tags',
+  'source-type',
+  'status',
+  'scope-type',
+  'space-id',
+  'module',
+  'resource-type',
+  'method',
+  'risk',
+  'permission',
 ]);
 
 function parse(argv) {

package/src/commandRegistry.js

@@ -5,15 +5,13 @@
 const commands = [
   { name: 'init', run: (dir, args, flags) => require('./commands/init')(dir, args, flags) },
   { name: 'update', run: (dir, args, flags) => require('./commands/update')(dir, args, flags) },
-  { name: 'uninstall', aliases: ['remove'], run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
-  { name: 'status', run: (dir) => require('./commands/status')(dir) },
-  { name: 'changelog', run: (dir, args, flags) => require('./commands/changelog')(dir, args, flags) },
-  { name: 'task', run: (dir, args, flags) => require('./commands/task')(dir, args, flags) },
+  { name: 'uninstall', run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
+  { name: 'status', run: (dir, args, flags) => require('./commands/status')(dir, args, flags) },
+  { name: 'work', run: (dir, args, flags) => require('./commands/worklog')(dir, args, flags) },
   { name: 'clean', run: (dir, args, flags) => require('./commands/clean')(dir, args, flags) },
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
   { name: 'check', run: (dir, args, flags) => require('./commands/check')(dir, args, flags) },
   { name: 'verify', run: (dir, args, flags) => require('./commands/verify')(dir, args, flags) },
-  { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUiCompat')(dir, args, flags) },
   { name: 'mcp', run: (dir, args, flags) => require('./commands/mcp')(dir, args, flags) },
   { name: 'checkout', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
   { name: 'refresh', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
@@ -26,15 +24,20 @@ const commands = [
   { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },
   { name: 'conflict', run: (dir, args, flags) => require('./commands/conflict')(dir, args, flags) },
   { name: 'api', run: (dir, args, flags) => require('./commands/api')(dir, args, flags) },
-  { name: 'delete', aliases: ['del', 'rm'], run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
+  { name: 'space', run: (dir, args, flags) => require('./commands/space')(dir, args, flags) },
+  { name: 'group', run: (dir, args, flags) => require('./commands/group')(dir, args, flags) },
+  { name: 'grant', run: (dir, args, flags) => require('./commands/grant')(dir, args, flags) },
+  { name: 'api-key', run: (dir, args, flags) => require('./commands/apiKey')(dir, args, flags) },
+  { name: 'role', run: (dir, args, flags) => require('./commands/role')(dir, args, flags) },
+  { name: 'data-range', run: (dir, args, flags) => require('./commands/dataRange')(dir, args, flags) },
+  { name: 'delete', run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
   { name: 'deploy', run: (dir, args, flags) => require('./commands/deploy')(dir, args, flags) },
-  { name: 'auto-push', aliases: ['autopush'], run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
-  { name: 'pull', run: (dir, args, flags) => require('./commands/sync')(dir, 'pull', args, flags) },
-  { name: 'push', run: (dir, args, flags) => require('./commands/sync')(dir, 'push', args, flags) },
+  { name: 'auto-push', run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
   { name: 'local', run: (dir, args, flags) => require('./commands/local')(dir, args, flags) },
-  { name: 'list-targets', aliases: ['targets'], run: () => require('./commands/listTargets')() },
-  { name: 'local-dev', aliases: ['localdev'], run: (dir, args, flags) => require('./commands/localDev')(dir, args, flags) },
-  { name: 'connect', aliases: ['login'], run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+  { name: 'list-targets', run: () => require('./commands/listTargets')() },
+  { name: 'connect', run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+  { name: 'components', run: (dir, args, flags) => require('./commands/components')(dir, args, flags) },
+  { name: 'capabilities', run: (dir, args, flags) => require('./commands/capabilities')(dir, args, flags) },
 ];
 
 const aliases = new Map();

package/src/commands/api.js

@@ -5,7 +5,15 @@ const path = require('path');
 const log = require('../logger');
 const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
-const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+const { TOOL_NAMES, openToolSession, callStructured, configuredScope } = require('../mcp/tools');
+const { cachedDescription, normalizeDescription, storeDescription } = require('../apiContractCache');
+const {
+  isContractCompatibilityError,
+  isHardContractIncompatibility,
+  isDangerousOperation,
+  sameOperationContract,
+  incompatibleOperationError,
+} = require('../contractCompatibility');
 
 function readCallInput(projectDir, flags) {
   const raw = flags.input
@@ -66,27 +74,49 @@ async function callOperation(projectDir, operationId, flags = {}) {
   let session;
   let description;
   let input;
+  let config;
   try {
-    const config = loadProjectConfig(projectDir);
+	config = loadProjectConfig(projectDir);
     session = await openToolSession(config, [TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall]);
-    description = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+    description = cachedDescription(projectDir, config.server, operationId);
+    if (!description) {
+      const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+      description = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+    }
+    if (!description) throw new Error('DraftGo API description is missing contract revision metadata.');
     input = readCallInput(projectDir, flags);
   } catch (error) {
     return printCallError(operationId, error, flags);
   }
-  const destructive = description && (description.destructive === true
-    || description.operation && description.operation.destructive === true);
-  if (destructive && !flags.yes && !flags.y) {
+  const dangerous = isDangerousOperation(description);
+  if (dangerous && !flags.yes && !flags.y) {
     const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
     if (!approved) return 0;
   }
   let result;
   try {
-    result = await callStructured(session, TOOL_NAMES.apiCall, {
-      ...input,
-      operation_id: operationId,
-      ...(destructive ? { confirm: true } : {}),
+    const invoke = (contract, confirmed) => callStructured(session, TOOL_NAMES.apiCall, {
+      ...input, operation_id: operationId, registry_revision: contract.registry_revision,
+      ...configuredScope(config, contract),
+      ...(confirmed ? { confirm: true } : {}),
     });
+    try {
+      result = await invoke(description, dangerous);
+    } catch (error) {
+      if (!isContractCompatibilityError(error)) throw error;
+      if (isHardContractIncompatibility(error)) {
+        throw incompatibleOperationError(operationId, error);
+      }
+      const previousDescription = description;
+      const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+      description = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+      if (!description) throw new Error('DraftGo API description is missing contract revision metadata.');
+      const changedDangerous = isDangerousOperation(description);
+      if ((dangerous || changedDangerous) && !sameOperationContract(previousDescription, description)) {
+        throw incompatibleOperationError(operationId, error);
+      }
+      result = await invoke(description, changedDangerous);
+    }
   } catch (error) {
     return printCallError(operationId, error, flags);
   }
@@ -130,6 +160,7 @@ async function apiCommand(projectDir, positional, flags = {}) {
   const result = await callStructured(session, expected, describe
     ? { operation_id: query }
     : { query });
+  if (describe) storeDescription(projectDir, config.server, result);
   if (flags.output === 'json') console.log(JSON.stringify(result, null, 2));
   else printResult(describe ? `DraftGo API ${query}` : `DraftGo API search: ${query}`, result);
   return 0;

package/src/commands/apiKey.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const log = require('../logger');
+const { callOperation } = require('./api');
+
+const OPERATIONS = Object.freeze({
+  status: 'getCurrentUserAPIKey',
+  create: 'createCurrentUserAPIKey',
+  update: 'updateCurrentUserAPIKey',
+  delete: 'deleteCurrentUserAPIKey',
+  rotate: 'rotateCurrentUserAPIKey',
+  reset: 'resetCurrentUserAPIKey',
+  enable: 'enableCurrentUserAPIKey',
+  disable: 'disableCurrentUserAPIKey',
+});
+
+function operationKey(value) {
+  const action = String(value || 'status').trim().toLowerCase();
+  return OPERATIONS[action] ? action : '';
+}
+
+async function apiKeyCommand(projectDir, positional, flags = {}) {
+  const action = operationKey(positional[0]);
+  if (!action) {
+    log.err('Usage: draftgo api-key status|create|update|delete|rotate|reset|enable|disable [--input <json-file>]');
+    return 1;
+  }
+  if (action === 'reset') log.warn('api-key reset is deprecated; prefer rotate.');
+  return callOperation(projectDir, OPERATIONS[action], flags);
+}
+
+module.exports = apiKeyCommand;
+module.exports.OPERATIONS = OPERATIONS;
+module.exports.operationKey = operationKey;

package/src/commands/capabilities.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+
+function itemsOf(value) {
+  if (Array.isArray(value)) return value;
+  return value && Array.isArray(value.items) ? value.items : [];
+}
+
+function nextCursorOf(value) {
+  return value && (value.next_cursor ?? value.nextCursor) || null;
+}
+
+function print(value, flags, title) {
+  if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));
+  else {
+    log.title(title);
+    if (Array.isArray(value)) value.forEach(item => log.plain(`  ${item.operation_id || item.name || JSON.stringify(item)}`));
+    else console.log(JSON.stringify(value, null, 2));
+  }
+}
+
+function searchArguments(query, flags, cursor) {
+  const input = { limit: Math.min(100, Math.max(1, Number(flags.limit) || 100)) };
+  if (query) input.query = query;
+  if (flags.module) input.module = String(flags.module);
+  if (flags['resource-type'] || flags.type) input.resource_type = String(flags['resource-type'] || flags.type);
+  if (flags.method) input.method = String(flags.method).toUpperCase();
+  if (flags.risk) input.risk = String(flags.risk);
+  if (flags.permission) input.permission = String(flags.permission);
+  if (cursor) input.cursor = cursor;
+  return input;
+}
+
+async function collect(session, query, flags, allPages) {
+  const result = [];
+  let cursor = flags.cursor || null;
+  const seen = new Set();
+  do {
+    const page = await callStructured(session, TOOL_NAMES.apiSearch, searchArguments(query, flags, cursor));
+    result.push(...itemsOf(page));
+    cursor = nextCursorOf(page);
+    if (!allPages || !cursor) break;
+    if (seen.has(cursor)) throw new Error('DraftGo capability search repeated a cursor.');
+    seen.add(cursor);
+  } while (true);
+  return { items: result, next_cursor: cursor };
+}
+
+async function capabilities(projectDir, positional = [], flags = {}) {
+  const action = String(positional[0] || 'list').toLowerCase();
+  const config = loadProjectConfig(projectDir);
+  if (action === 'show') {
+    const operationID = String(positional[1] || '').trim();
+    if (!operationID) throw new Error('Usage: draftgo capabilities show <operation_id>');
+    const session = await openToolSession(config, [TOOL_NAMES.apiDescribe]);
+    const result = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationID });
+    print(result, flags, `DraftGo capability ${operationID}`);
+    return 0;
+  }
+  if (action === 'audit') {
+    const session = await openToolSession(config, [TOOL_NAMES.projectOverview, TOOL_NAMES.apiSearch]);
+    const overview = await callStructured(session, TOOL_NAMES.projectOverview, {});
+    const catalog = await collect(session, '', flags, true);
+    const registry = overview && (overview.operation_registry || overview.registry) || {};
+    const result = {
+      server: config.server,
+      registry_revision: registry.registry_revision || overview.registry_revision || null,
+      mapped_operations: registry.mapped_operations ?? registry.mapped ?? catalog.items.length,
+      excluded_operations: registry.excluded_operations ?? registry.excluded ?? null,
+      total_operations: registry.total_operations ?? registry.total ?? null,
+      discovered_operations: catalog.items.length,
+      complete: (registry.mapped_operations ?? registry.mapped ?? catalog.items.length) === catalog.items.length,
+    };
+    print(result, flags, 'DraftGo capability audit');
+    return result.complete ? 0 : 1;
+  }
+  if (action !== 'list' && action !== 'search') throw new Error('Usage: draftgo capabilities list|search|show|audit');
+  const query = action === 'search' ? positional.slice(1).join(' ').trim() : '';
+  if (action === 'search' && !query && !flags.module && !flags.type && !flags.method && !flags.risk && !flags.permission) {
+    throw new Error('Capability search needs a query or filter.');
+  }
+  const session = await openToolSession(config, [TOOL_NAMES.apiSearch]);
+  const result = await collect(session, query, flags, action === 'list' && !flags.cursor);
+  print(flags.output === 'json' ? result : result.items, flags, action === 'search' ? `DraftGo capabilities: ${query || 'filtered'}` : 'DraftGo capabilities');
+  return 0;
+}
+
+module.exports = capabilities;
+module.exports.searchArguments = searchArguments;
+module.exports.itemsOf = itemsOf;

package/src/commands/check.js

@@ -1,18 +1,11 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
 const log = require('../logger');
 const { analyzeProject } = require('../projectMap');
 const { inspectRemoteCheckouts } = require('../worktree/status');
 const customServices = require('../customServices');
 const { workspaceHealth } = require('../workspaceHealth');
 
-function legacyCacheDetected(projectDir) {
-  return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
-    .some((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
-}
-
 async function check(projectDir, positional = [], flags = {}) {
   if (!Array.isArray(positional)) {
     flags = positional || {};
@@ -94,7 +87,7 @@ async function check(projectDir, positional = [], flags = {}) {
     workspace_hygiene: hygiene,
   };
   if (flags.output === 'json') {
-    console.log(JSON.stringify({ ...output, legacy_cache_ignored: legacyCacheDetected(projectDir) }, null, 2));
+    console.log(JSON.stringify(output, null, 2));
     return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
   }
 
@@ -111,8 +104,6 @@ async function check(projectDir, positional = [], flags = {}) {
   if (remote) log.info(`Remote checkout comparison: ${remote.length} resource(s)`);
   for (const message of result.errors) log.err(message);
   for (const detail of result.warningDetails) log.warn(`[${detail.code}/${detail.confidence}] ${detail.message}`);
-  if (legacyCacheDetected(projectDir)) log.dim('  Legacy .draftgo index caches were detected and ignored.');
-
   if (result.errors.length || (flags.strict && result.warnings.length)) return 1;
   log.ok(result.warnings.length ? 'Local checkout validation completed with warnings.' : 'Local checkout validation passed.');
   return 0;

package/src/commands/checkout.js

@@ -6,7 +6,7 @@ const { checkoutResources } = require('../worktree');
 async function checkout(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo checkout <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo checkout <pages|nav|docs|custom-services> <id...>');
     return 1;
   }
   if (require('./customService').isServiceType(resourceType)) {

package/src/commands/commit.js

@@ -6,7 +6,7 @@ const { commitResources } = require('../worktree');
 async function commit(projectDir, positional, flags = {}) {
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
+    log.err('Usage: draftgo commit <pages|nav|docs|custom-services> <id...>');
     return 1;
   }
   if (require('./customService').isServiceType(resourceType)) {