draftgo-cli 3.0.39 → 3.0.41

package/src/changelog.js

@@ -0,0 +1,276 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { dgDir } = require('./paths');
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_LOCK_STALE_MS = 60_000;
+const DEFAULT_LOCK_RETRY_MS = 10;
+const LOCK_WAIT_ARRAY = new Int32Array(new SharedArrayBuffer(4));
+
+class ChangelogFormatError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ChangelogFormatError';
+    this.code = 'INVALID_CHANGELOG';
+  }
+}
+
+function changelogPath(projectDir) {
+  return path.join(dgDir(projectDir), 'changelog.md');
+}
+
+function formatLocalDate(value = new Date()) {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new TypeError('A valid Date is required.');
+  }
+  const year = String(value.getFullYear()).padStart(4, '0');
+  const month = String(value.getMonth() + 1).padStart(2, '0');
+  const day = String(value.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function isLeapYear(year) {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+function isCalendarDate(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (year < 1 || month < 1 || month > 12 || day < 1) return false;
+  const days = [31, isLeapYear(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= days[month - 1];
+}
+
+function normalizeMessage(value) {
+  const message = value == null ? '' : String(value).trim();
+  if (!message) throw new TypeError('Changelog result must not be empty.');
+  if (/[\r\n\u2028\u2029]/.test(message)) {
+    throw new TypeError('Changelog result must be a single line.');
+  }
+  return message;
+}
+
+function invalidFormat(detail) {
+  return new ChangelogFormatError(`Invalid .draftgo/changelog.md: ${detail}`);
+}
+
+function parseChangelog(source) {
+  if (typeof source !== 'string') throw new TypeError('Changelog source must be a string.');
+  if (source === '') return [];
+  if (/\r(?!\n)/.test(source)) throw invalidFormat('unsupported line ending.');
+
+  const normalized = source.replace(/\r\n/g, '\n');
+  const body = normalized.endsWith('\n') ? normalized.slice(0, -1) : normalized;
+  const lines = body.split('\n');
+  const blocks = [];
+  let cursor = 0;
+
+  while (cursor < lines.length) {
+    const date = lines[cursor];
+    if (!isCalendarDate(date)) throw invalidFormat(`expected a YYYY-MM-DD header at line ${cursor + 1}.`);
+    if (blocks.length && date <= blocks[blocks.length - 1].date) {
+      throw invalidFormat(`date blocks must be strictly increasing (line ${cursor + 1}).`);
+    }
+    cursor += 1;
+    if (lines[cursor] !== '===') throw invalidFormat(`expected === at line ${cursor + 1}.`);
+    cursor += 1;
+
+    const entries = [];
+    while (cursor < lines.length && lines[cursor] !== '') {
+      const match = /^([1-9]\d*)\. (.+)$/.exec(lines[cursor]);
+      if (!match) throw invalidFormat(`invalid entry at line ${cursor + 1}.`);
+      const number = Number(match[1]);
+      if (!Number.isSafeInteger(number) || number !== entries.length + 1) {
+        throw invalidFormat(`entries must be consecutively numbered from 1 (line ${cursor + 1}).`);
+      }
+      let message;
+      try {
+        message = normalizeMessage(match[2]);
+      } catch (error) {
+        throw invalidFormat(`${error.message} (line ${cursor + 1}).`);
+      }
+      if (message !== match[2]) throw invalidFormat(`entry has surrounding whitespace at line ${cursor + 1}.`);
+      entries.push({ number, message });
+      cursor += 1;
+    }
+    if (!entries.length) throw invalidFormat(`date block ${date} has no entries.`);
+    blocks.push({ date, entries });
+
+    if (cursor >= lines.length) break;
+    cursor += 1;
+    if (cursor >= lines.length || lines[cursor] === '') {
+      throw invalidFormat(`date blocks must be separated by exactly one blank line (line ${cursor + 1}).`);
+    }
+  }
+
+  return blocks;
+}
+
+function renderChangelog(blocks) {
+  if (!Array.isArray(blocks)) throw new TypeError('Changelog blocks must be an array.');
+  if (!blocks.length) return '';
+  return `${blocks.map((block) => [
+    block.date,
+    '===',
+    ...block.entries.map((entry) => `${entry.number}. ${entry.message}`),
+  ].join('\n')).join('\n\n')}\n`;
+}
+
+function appendChangelogEntry(source, value, now = new Date()) {
+  const message = normalizeMessage(value);
+  const date = formatLocalDate(now);
+  const blocks = parseChangelog(source);
+  const last = blocks[blocks.length - 1];
+
+  if (last && date < last.date) {
+    throw new ChangelogFormatError(
+      `Cannot append ${date}: the latest changelog block is ${last.date}. Check the local clock.`
+    );
+  }
+
+  let number;
+  if (last && last.date === date) {
+    number = last.entries.length + 1;
+    last.entries.push({ number, message });
+  } else {
+    number = 1;
+    blocks.push({ date, entries: [{ number, message }] });
+  }
+
+  return { content: renderChangelog(blocks), date, number, message };
+}
+
+function temporaryPath(destination) {
+  const suffix = crypto.randomBytes(8).toString('hex');
+  return path.join(path.dirname(destination), `.${path.basename(destination)}.${process.pid}.${suffix}.tmp`);
+}
+
+function lockOption(value, fallback, name, allowZero = false) {
+  const number = value == null ? fallback : Number(value);
+  const minimum = allowZero ? 0 : 1;
+  if (!Number.isSafeInteger(number) || number < minimum) {
+    throw new TypeError(`${name} must be an integer greater than or equal to ${minimum}.`);
+  }
+  return number;
+}
+
+function removeStaleLock(lockPath, staleMs) {
+  try {
+    const stat = fs.lstatSync(lockPath);
+    if (Date.now() - stat.mtimeMs < staleMs) return false;
+    fs.rmSync(lockPath, { force: true });
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return true;
+    throw error;
+  }
+}
+
+function acquireChangelogLock(destination, options = {}) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const lockPath = `${destination}.lock`;
+  const timeoutMs = lockOption(
+    options.lockTimeoutMs,
+    DEFAULT_LOCK_TIMEOUT_MS,
+    'lockTimeoutMs',
+    true,
+  );
+  const staleMs = lockOption(options.lockStaleMs, DEFAULT_LOCK_STALE_MS, 'lockStaleMs');
+  const retryMs = lockOption(options.lockRetryMs, DEFAULT_LOCK_RETRY_MS, 'lockRetryMs');
+  const token = `${process.pid}:${crypto.randomBytes(16).toString('hex')}`;
+  const started = Date.now();
+
+  while (true) {
+    let descriptor;
+    let created = false;
+    try {
+      descriptor = fs.openSync(lockPath, 'wx', 0o600);
+      created = true;
+      fs.writeFileSync(descriptor, `${token}\n`, 'utf8');
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      return { path: lockPath, token };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch { /* Preserve the original failure. */ }
+      }
+      if (created) {
+        try { fs.rmSync(lockPath, { force: true }); } catch { /* Best-effort cleanup. */ }
+      }
+      if (!error || error.code !== 'EEXIST') throw error;
+    }
+
+    if (removeStaleLock(lockPath, staleMs)) continue;
+    const elapsed = Date.now() - started;
+    if (elapsed >= timeoutMs) {
+      const error = new Error('Timed out waiting for .draftgo/changelog.md.lock.');
+      error.code = 'CHANGELOG_LOCK_TIMEOUT';
+      throw error;
+    }
+    Atomics.wait(LOCK_WAIT_ARRAY, 0, 0, Math.min(retryMs, timeoutMs - elapsed));
+  }
+}
+
+function releaseChangelogLock(lock) {
+  try {
+    const token = fs.readFileSync(lock.path, 'utf8').trim();
+    if (token === lock.token) fs.rmSync(lock.path, { force: true });
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+}
+
+function writeTextAtomic(destination, content) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const temporary = temporaryPath(destination);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, 'wx', 0o666);
+    fs.writeFileSync(descriptor, content, 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporary, destination);
+  } finally {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch { /* The original error is more useful. */ }
+    }
+    try { fs.rmSync(temporary, { force: true }); } catch { /* Best-effort temporary cleanup. */ }
+  }
+}
+
+function addChangelogEntry(projectDir, value, options = {}) {
+  const file = changelogPath(projectDir);
+  const message = normalizeMessage(value);
+  const lock = acquireChangelogLock(file, options);
+  try {
+    const source = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const result = appendChangelogEntry(source, message, options.now || new Date());
+    writeTextAtomic(file, result.content);
+    return { ...result, path: file };
+  } finally {
+    releaseChangelogLock(lock);
+  }
+}
+
+module.exports = {
+  ChangelogFormatError,
+  changelogPath,
+  formatLocalDate,
+  isCalendarDate,
+  normalizeMessage,
+  parseChangelog,
+  renderChangelog,
+  appendChangelogEntry,
+  acquireChangelogLock,
+  releaseChangelogLock,
+  writeTextAtomic,
+  addChangelogEntry,
+};

package/src/cli.js

@@ -25,6 +25,7 @@ const VALUE_FLAGS = new Set([
   'params',
   'input',
   'type',
+  'task',
 ]);
 
 function parse(argv) {

package/src/commandRegistry.js

@@ -7,6 +7,8 @@ const commands = [
   { 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: 'context', run: (dir, args, flags) => require('./commands/context')(dir, args, flags) },
+  { name: 'changelog', run: (dir, args, flags) => require('./commands/changelog')(dir, args, flags) },
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
   { name: 'check', run: (dir, _args, flags) => require('./commands/check')(dir, flags) },
   { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUi')(dir, args, flags) },

package/src/commands/changelog.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const log = require('../logger');
+const { addChangelogEntry } = require('../changelog');
+
+function printUsage() {
+  log.err('Usage: draftgo changelog add <completed-result>');
+}
+
+function changelog(projectDir, positional = []) {
+  const [action, ...messageParts] = positional;
+  if (action !== 'add' || !messageParts.length) {
+    printUsage();
+    return 1;
+  }
+
+  const result = addChangelogEntry(projectDir, messageParts.join(' '));
+  log.ok(`Changelog updated: .draftgo/changelog.md (${result.date} #${result.number})`);
+  return 0;
+}
+
+changelog.printUsage = printUsage;
+
+module.exports = changelog;

package/src/commands/context.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const log = require('../logger');
+const { collectContext, TASK_PROFILES } = require('../context');
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+function parseTimeout(value) {
+  if (value == null) return undefined;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) {
+    throw new TypeError('--timeout must be a positive integer in milliseconds.');
+  }
+  const timeoutMs = Number(text);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+    throw new TypeError(`--timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`);
+  }
+  return timeoutMs;
+}
+
+function printUsage() {
+  log.err('Usage: draftgo context --task <task> --output json');
+  log.dim(`  tasks: ${Object.keys(TASK_PROFILES).join(', ')}`);
+}
+
+async function contextCommand(projectDir, positional = [], flags = {}) {
+  if (positional.length || !flags.task || (flags.output && flags.output !== 'json')) {
+    printUsage();
+    return 1;
+  }
+  const result = await collectContext(projectDir, flags.task, {
+    timeoutMs: parseTimeout(flags.timeout),
+  });
+  console.log(JSON.stringify(result, null, 2));
+  return 0;
+}
+
+contextCommand.printUsage = printUsage;
+contextCommand.parseTimeout = parseTimeout;
+
+module.exports = contextCommand;

package/src/commands/help.js

@@ -17,6 +17,8 @@ DraftGo Next frontend baseline: React + Vite.
 Database pages use standard HTML + Tailwind CSS.
 MCP handles live discovery and structured resources; complete page, navigation,
 and document bodies use checkout/commit outside MCP context.
+The context command combines exact local Reference sections with live MCP data;
+it is a CLI orchestration command, not an MCP tool.
 
 Usage:
   draftgo init [<target>...]       Install the DraftGo Skill. No target = detect.
@@ -35,6 +37,9 @@ Usage:
   draftgo mcp test                 Test initialize, tools/list, and tools/call.
   draftgo mcp serve                Bridge local stdio to the remote /mcp endpoint.
 
+  draftgo context --task <task>    Read exact task Reference sections, then reuse
+                                    one MCP session to query project, resources,
+                                    APIs, and data structures in parallel.
   draftgo map                      Read remote overview/resources through MCP and
                                     overlay local checkout state.
   draftgo checkout <type> <id...>  Download pages/nav/docs body + verified base.
@@ -62,6 +67,8 @@ Usage:
   draftgo auto-push [<type> <id...>]
                                     With config.auto_push=true, check and commit
                                     changed checkouts. Any conflict stops the run.
+  draftgo changelog add <result>   Append one completed result after the task has
+                                    passed unified verification and delivery.
   draftgo pull                     Migration notice only; always downloads nothing.
   draftgo push <type> <id...>      Deprecated alias to commit for pages/nav/docs.
                                     Push-all and structured-resource push are removed.
@@ -82,7 +89,7 @@ Important flags:
   --target <name,...>      Select one or more MCP setup/status targets.
   --server <url>           (connect) DraftGo base URL.
   --token <sat>            (connect) SAT for non-interactive use.
-  --timeout <ms>           (connect/mcp test) Network timeout.
+  --timeout <ms>           (connect/mcp test/context) Network timeout.
   --allow-offline          (connect) Save only after explicitly accepting a
                            failed MCP validation.
   --no-mcp-setup           (connect) Do not write host MCP configuration.
@@ -93,6 +100,8 @@ Important flags:
   --local-dev              (init) Continue into local Docker setup.
   --no-setup               (init) Install the Skill without either setup flow.
   --output json            Print machine-readable output where supported.
+  --task <task>            (context) frontend | data | custom-service | aihub |
+                           content | project.
   --strict                 Treat check warnings as failures.
   --yes                    Skip supported confirmation prompts.
   --operation-id <id>      (delete) Select an operation explicitly.
@@ -120,11 +129,13 @@ Examples:
   draftgo init codex
   draftgo connect codex --server https://draftgo.example --token <sat>
   draftgo mcp test
+  draftgo context --task frontend --output json
   draftgo map --output json
   draftgo checkout pages 42
   draftgo check --strict
   draftgo diff pages 42
   draftgo commit pages 42
+  draftgo changelog add "Complete document management and role permissions"
   draftgo deploy docs 7 --delivery preview
 `);
 }

package/src/commands/update.js

@@ -9,6 +9,12 @@ const { detectTargets } = require('../detect');
 
 const REENTRY_FLAG = 'DRAFTGO_UPDATE_REENTERED';
 
+function installedTargetsNotRefreshed(projectDir, refreshedTargets) {
+  const refreshed = new Set(refreshedTargets.map((target) => target.name));
+  return all.filter((target) =>
+    !refreshed.has(target.name) && target.status(projectDir).installed);
+}
+
 async function updateCliIfNeeded(projectDir, positional, flags) {
   if (process.env[REENTRY_FLAG] === '1' || flags['skip-update-check'] || process.env.DRAFTGO_NO_UPDATE_CHECK === '1') {
     return null;
@@ -105,7 +111,15 @@ async function update(projectDir, positional, flags) {
     log.err(`更新未完成，失败目标：${failures.join(', ')}`);
     return 1;
   }
-  writeInstalledVersion(projectDir);
+  const staleInstalled = installedTargetsNotRefreshed(projectDir, resolved);
+  if (staleInstalled.length) {
+    log.dim(
+      `  未更新全局 skill 版本标记；尚有未刷新的已安装目标：${staleInstalled
+        .map((target) => target.displayName).join(', ')}`,
+    );
+  } else {
+    writeInstalledVersion(projectDir);
+  }
 
   log.title('完成');
   return 0;
@@ -113,3 +127,4 @@ async function update(projectDir, positional, flags) {
 
 module.exports = update;
 module.exports.updateCliIfNeeded = updateCliIfNeeded;
+module.exports.installedTargetsNotRefreshed = installedTargetsNotRefreshed;