draftgo-cli 1.0.4

package/src/commands/capabilities.js

@@ -0,0 +1,100 @@
+'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 limit = flags.limit == null ? 20 : Number(flags.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error('--limit must be an integer between 1 and 100.');
+  const input = { limit };
+  if (query) input.query = query;
+  if (flags.module) input.module = String(flags.module);
+  if (flags.type) input.module = String(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 registryRevision = null;
+  let total = null;
+  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));
+    registryRevision ||= page && page.registry_revision || null;
+    if (Number.isFinite(Number(page && page.total))) total = Number(page.total);
+    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, registry_revision: registryRevision, total };
+}
+
+async function capabilities(projectDir, positional = [], flags = {}) {
+  if (flags['resource-type'] != null) {
+    throw new Error('Capabilities --resource-type is not supported; use --type or --module for a Registry module.');
+  }
+  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 { registryRevision, descriptionForRevision } = require('./api');
+    const session = await openToolSession(config, [TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe]);
+    const revision = await registryRevision(session, operationID);
+    const result = await descriptionForRevision(projectDir, config, session, operationID, revision);
+    print(result, flags, `DraftGo capability ${operationID}`);
+    return 0;
+  }
+  if (action === 'audit') {
+    const session = await openToolSession(config, [TOOL_NAMES.apiSearch]);
+    const catalog = await collect(session, '', flags, true);
+    const result = {
+      server: config.server,
+      registry_revision: catalog.registry_revision,
+      total_operations: catalog.total ?? catalog.items.length,
+      discovered_operations: catalog.items.length,
+      complete: catalog.next_cursor == null && (catalog.total == null || catalog.total === 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, false);
+  print(result, 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

@@ -0,0 +1,82 @@
+'use strict';
+
+const log = require('../logger');
+const { analyzeProject } = require('../projectMap');
+const { inspectRemoteCheckouts } = require('../worktree/status');
+const { projectHealth } = require('../projectHealth');
+
+async function check(projectDir, positional = [], flags = {}) {
+  if (!Array.isArray(positional)) {
+    flags = positional || {};
+    positional = [];
+  }
+  if (positional.length) {
+    if (!flags.quiet) log.err('Usage: draftgo check [--remote]');
+    return 1;
+  }
+  const resourceKeys = flags.resourceKeys || null;
+  const quiet = Boolean(flags.quiet);
+  const result = analyzeProject(projectDir, { resourceKeys });
+  if (resourceKeys) {
+    const manifestKeys = new Set(Object.keys(result.map.checkouts.reduce((entries, entry) => {
+      entries[`${entry.resource_type}:${entry.resource_id}`] = true;
+      return entries;
+    }, {})));
+    for (const key of resourceKeys) if (!manifestKeys.has(key)) result.errors.push(`${key}: resource is not checked out`);
+  }
+  const hygiene = projectHealth(projectDir);
+  const hygieneWarnings = resourceKeys ? [] : hygiene.warnings;
+  hygieneWarnings.forEach((warning) => result.warningDetails.push({ code: warning.code, confidence: 'high', message: `${warning.path}${warning.size ? ` (${warning.size} bytes)` : ''}` }));
+  hygieneWarnings.forEach((warning) => result.warnings.push(`${warning.code}: ${warning.path}`));
+  let remote = null;
+  let remoteError = null;
+  if (flags.remote) {
+    try {
+      remote = await inspectRemoteCheckouts(projectDir, resourceKeys ? {
+          entries: result.map.checkouts.filter((entry) => resourceKeys.includes(`${entry.resource_type}:${entry.resource_id}`)),
+        } : {});
+      for (const entry of remote) {
+        if (!['clean', 'clean_local', 'local_modified'].includes(entry.state)) {
+          const detail = `${entry.resource_type} ${entry.resource_id}: ${entry.state}`
+            + ` (local=${entry.local_hash || '-'}, base=${entry.manifest_hash || '-'}, `
+            + `remote=${entry.remote_hash || '-'}, remote_version=${entry.remote_version || '-'})`
+            + (entry.recommendation ? `; run ${entry.recommendation}` : '');
+          result.errors.push(detail);
+        }
+      }
+    } catch (error) {
+      remoteError = { code: error.code || 'REMOTE_CHECK_FAILED', message: error.message };
+      result.errors.push(`Remote checkout check failed: ${error.message}`);
+    }
+  }
+  const output = {
+    content_validation: { map: result.map, errors: result.errors, warnings: result.warnings, warning_details: result.warningDetails },
+    remote_validation: { resources: remote, error: remoteError },
+    project_hygiene: hygiene,
+  };
+  const code = result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
+  if (flags.returnResult) return { code, ...output };
+  if (quiet) return code;
+  if (flags.output === 'json') {
+    if (!quiet) console.log(JSON.stringify(output, null, 2));
+    return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
+  }
+
+  if (!quiet) log.title('draftgo check');
+  const selectedCount = (type, entries) => resourceKeys
+    ? entries.filter((entry) => resourceKeys.includes(`${type}:${entry.resource_id}`)).length
+    : entries.length;
+  log.info(`Checked-out pages: ${selectedCount('pages', result.map.pages)}`);
+  log.info(`Checked-out navigations: ${selectedCount('navigations', result.map.navigations)}`);
+  log.info(`Checked-out docs: ${selectedCount('docs', result.map.docs)}`);
+  log.info(`Project: ${hygiene.managed_files} managed, ${hygiene.unknown_files} unknown, ${hygiene.temporary_files} temporary, ${hygiene.artifact_files} artifact file(s)`);
+  log.info(`Project size: ${hygiene.total_bytes} bytes; reclaimable: ${hygiene.reclaimable_bytes} bytes`);
+  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 (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;
+}
+
+module.exports = check;

package/src/commands/checkout.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const log = require('../logger');
+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...>');
+    return 1;
+  }
+  const results = await checkoutResources(projectDir, resourceType, ids, { force: Boolean(flags.force) });
+  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
+  else for (const entry of results) log.ok(`Checked out ${entry.resource_type} ${entry.resource_id} -> ${entry.local_path}`);
+  return 0;
+}
+
+module.exports = checkout;

package/src/commands/clean.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const log = require('../logger');
+const runtime = require('../runtimeFiles');
+
+const MANAGED_PREFIXES = ['tmp/', 'artifacts/ui/', 'artifacts/api/'];
+function fileSize(file) { try { const stat = fs.statSync(file); return stat.isFile() ? stat.size : 0; } catch { return 0; } }
+function olderThan(value) {
+  if (value == null || value === '') return 0;
+  const match = String(value).match(/^(\d+)([dhm])$/i); if (!match) throw new Error('--older-than must use <number>d, <number>h, or <number>m.');
+  const unit = { d: 86400000, h: 3600000, m: 60000 }[match[2].toLowerCase()]; return Number(match[1]) * unit;
+}
+function plan(projectDir, flags = {}) {
+  const root = runtime.draftgoRoot(projectDir); const manifest = runtime.load(projectDir); const age = olderThan(flags['older-than']); const now = Date.now();
+  const types = new Set(String(flags.type || '').split(',').map((item) => item.trim()).filter(Boolean)); const candidates = [];
+  for (const entry of manifest.entries) {
+    if (!entry.cleanable || (types.size && !types.has(entry.type))) continue;
+    const relative = String(entry.path).replace(/\\/g, '/');
+    if (!MANAGED_PREFIXES.some((prefix) => relative.startsWith(prefix))) continue;
+    const absolute = path.resolve(root, relative); if (!runtime.inside(root, absolute) || !fs.existsSync(absolute)) continue;
+    const stat = fs.statSync(absolute); if (age && now - stat.mtimeMs < age) continue;
+    candidates.push({ ...entry, absolute, size: stat.isFile() ? stat.size : 0, reason: 'runtime_manifest' });
+  }
+  const tmp = path.resolve(root, 'tmp');
+  if (fs.existsSync(tmp) && runtime.inside(root, tmp) && (!types.size || types.has('tmp') || types.has('ai'))) {
+    const visitTmp = (current) => {
+      for (const child of fs.readdirSync(current, { withFileTypes: true })) {
+        const absolute = path.join(current, child.name);
+        if (child.isDirectory()) visitTmp(absolute);
+        else if (child.isFile() && !candidates.some((entry) => entry.absolute === absolute)) {
+          const stat = fs.statSync(absolute);
+          if (!age || now - stat.mtimeMs >= age) candidates.push({
+            path: path.relative(root, absolute).replace(/\\/g, '/'), absolute,
+            type: path.relative(tmp, absolute).replace(/\\/g, '/').startsWith('ai/') ? 'ai' : 'tmp',
+            size: stat.size, reason: 'temporary_area',
+          });
+        }
+      }
+    };
+    visitTmp(tmp);
+  }
+  if (flags['all-artifacts']) {
+    for (const prefix of MANAGED_PREFIXES.filter((item) => item.startsWith('artifacts/'))) {
+      const directory = path.resolve(root, prefix); if (!runtime.inside(root, directory) || !fs.existsSync(directory)) continue;
+      const visit = (current) => { for (const child of fs.readdirSync(current, { withFileTypes: true })) { const absolute = path.join(current, child.name); if (child.isDirectory()) visit(absolute); else if (child.isFile() && !candidates.some((entry) => entry.absolute === absolute)) candidates.push({ path: path.relative(root, absolute).replace(/\\/g, '/'), absolute, type: 'artifact', size: fileSize(absolute), reason: 'all_artifacts' }); } };
+      visit(directory);
+    }
+  }
+  return { entries: candidates, count: candidates.length, bytes: candidates.reduce((sum, entry) => sum + entry.size, 0) };
+}
+async function clean(projectDir, _positional, flags = {}) {
+  const result = plan(projectDir, flags); const output = { count: result.count, bytes: result.bytes, entries: result.entries.map(({ absolute, ...entry }) => entry) };
+  if (flags.output === 'json') console.log(JSON.stringify({ ...output, deleted: Boolean(flags.yes && !flags['dry-run']) }, null, 2));
+  else { log.title('draftgo clean'); result.entries.forEach((entry) => log.info(`${entry.path} (${entry.size} bytes)`)); log.info(`Reclaimable: ${result.bytes} bytes in ${result.count} file(s).`); }
+  if (!flags.yes || flags['dry-run']) { if (!flags.output) log.dim('Run with --yes to delete this plan.'); return 0; }
+  const manifest = runtime.load(projectDir); const removed = new Set();
+  for (const entry of result.entries) { if (!runtime.inside(runtime.draftgoRoot(projectDir), entry.absolute)) throw new Error('Clean target escaped .draftgo.'); fs.rmSync(entry.absolute, { force: true }); removed.add(entry.path); }
+  const tmp = path.join(runtime.draftgoRoot(projectDir), 'tmp');
+  if (fs.existsSync(tmp)) {
+    const removeEmpty = (directory) => {
+      for (const child of fs.readdirSync(directory, { withFileTypes: true })) if (child.isDirectory()) removeEmpty(path.join(directory, child.name));
+      if (directory !== tmp && fs.readdirSync(directory).length === 0) fs.rmdirSync(directory);
+    };
+    removeEmpty(tmp);
+  }
+  manifest.entries = manifest.entries.filter((entry) => !removed.has(entry.path)); runtime.save(projectDir, manifest);
+  if (!flags.output) log.ok(`Deleted ${result.count} managed file(s).`); return 0;
+}
+clean.plan = plan;
+module.exports = clean;

package/src/commands/commit.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const log = require('../logger');
+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...>');
+    return 1;
+  }
+  const streamed = [];
+  const printStatus = (result) => {
+    streamed.push(result);
+    if (flags.output === 'json') return;
+    if (result.status === 'committed') log.ok(`${result.resource_type} ${result.resource_id}: committed`);
+    else if (result.status === 'unchanged') log.dim(`${result.resource_type} ${result.resource_id}: unchanged`);
+    else if (result.status === 'failed') log.err(`${result.resource_type} ${result.resource_id}: failed (${result.code}) - ${result.message}`
+      + (result.remote_change_possible ? ' Remote change is possible; run draftgo check --remote.' : ''));
+    else log.warn(`${result.resource_type} ${result.resource_id}: not started`);
+  };
+  try {
+    const results = await commitResources(projectDir, resourceType, ids, { onStatus: printStatus });
+    if (flags.output === 'json') console.log(JSON.stringify({
+      completed: results.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: [],
+      not_started: [],
+    }, null, 2));
+  } catch (error) {
+    const batch = error.details && (error.details.batch || error.details);
+    const summary = batch && Array.isArray(batch.completed) ? batch : {
+      completed: streamed.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: streamed.filter((item) => item.status === 'failed'),
+      not_started: streamed.filter((item) => item.status === 'not_started'),
+    };
+    if (flags.output === 'json') console.log(JSON.stringify({ error: {
+      code: error.code || 'COMMIT_FAILED', message: error.message,
+    }, ...summary }, null, 2));
+    else log.err(`Commit batch stopped: ${summary.completed.length} completed, `
+      + `${summary.failed.length} failed, ${summary.not_started.length} not started. `
+      + `${summary.completed.length ? 'Remote changes already occurred for completed resources.' : 'No remote content was changed.'}`);
+    return 1;
+  }
+  return 0;
+}
+
+module.exports = commit;