draftgo-cli 1.0.4

package/src/platforms.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// Single source of truth describing every supported AI-tool target.
+// Each platform receives the complete instruction body, subskills, domain
+// references, and the small scripts directory used for bundled documentation.
+//
+//   mainFile : the markdown file the AI tool reads first
+//   assetDir : where subskills, references, and scripts are placed
+//   skillDir : project-relative path used to substitute {{SKILL_DIR}} in
+//              template files (typically === assetDir written with forward
+//              slashes so it works in markdown)
+//   signals  : project-level files/dirs that indicate the tool is in use
+//   frontmatter: object → prepended as YAML frontmatter to mainFile; null →
+//                no frontmatter
+//
+// For platforms whose convention is a flat .md file (cursor / windsurf /
+// antigravity / copilot / kiro), the main file lives next to a sibling dir
+// that holds the rest of the assets.
+
+const SKILL_NAME = 'draftgo';
+const DESCRIPTION =
+  'DraftGo 开发助手。在用户谈及 DraftGo 开发、页面、导航、自定义脚本、bug 修复或同步等场景时激活。';
+
+const platforms = [
+  {
+    name: 'claudecode',
+    displayName: 'Claude Code',
+    mainFile: '.claude/skills/draftgo/SKILL.md',
+    assetDir: '.claude/skills/draftgo',
+    skillDir: '.claude/skills/draftgo',
+    signals: ['.claude'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'cursor',
+    displayName: 'Cursor',
+    mainFile: '.cursor/commands/draftgo.md',
+    assetDir: '.cursor/commands/draftgo',
+    skillDir: '.cursor/commands/draftgo',
+    signals: ['.cursor'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'windsurf',
+    displayName: 'Windsurf',
+    mainFile: '.windsurf/workflows/draftgo.md',
+    assetDir: '.windsurf/workflows/draftgo',
+    skillDir: '.windsurf/workflows/draftgo',
+    signals: ['.windsurf'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'antigravity',
+    displayName: 'Antigravity',
+    mainFile: '.agent/workflows/draftgo.md',
+    assetDir: '.agent/workflows/draftgo',
+    skillDir: '.agent/workflows/draftgo',
+    signals: ['.agent'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'kiro',
+    displayName: 'Kiro',
+    mainFile: '.kiro/steering/draftgo.md',
+    assetDir: '.kiro/steering/draftgo',
+    skillDir: '.kiro/steering/draftgo',
+    signals: ['.kiro'],
+    frontmatter: { inclusion: 'manual', name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'copilot',
+    displayName: 'GitHub Copilot',
+    mainFile: '.github/prompts/draftgo.prompt.md',
+    assetDir: '.github/prompts/draftgo',
+    skillDir: '.github/prompts/draftgo',
+    signals: ['.github/prompts', '.github/copilot-instructions.md'],
+    frontmatter: { mode: 'agent', description: DESCRIPTION },
+  },
+  {
+    name: 'codex',
+    displayName: 'Codex CLI',
+    mainFile: '.codex/skills/draftgo/SKILL.md',
+    assetDir: '.codex/skills/draftgo',
+    skillDir: '.codex/skills/draftgo',
+    signals: ['.codex'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'gemini',
+    displayName: 'Gemini CLI',
+    mainFile: '.gemini/skills/draftgo/SKILL.md',
+    assetDir: '.gemini/skills/draftgo',
+    skillDir: '.gemini/skills/draftgo',
+    signals: ['.gemini'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+  {
+    name: 'pi',
+    displayName: 'Pi',
+    mainFile: '.agents/skills/draftgo/SKILL.md',
+    assetDir: '.agents/skills/draftgo',
+    skillDir: '.agents/skills/draftgo',
+    signals: ['.agents/skills', '.pi'],
+    frontmatter: { name: SKILL_NAME, description: DESCRIPTION },
+  },
+];
+
+const byName = Object.fromEntries(platforms.map((p) => [p.name, p]));
+
+module.exports = { platforms, byName, SKILL_NAME, DESCRIPTION };

package/src/projectConfig.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { exists, ensureDir, appendGitignoreLine } = require('./fsx');
+
+const IGNORE_ENTRIES = [
+  '.draftgo/config.json',
+  '.draftgo/token',
+  '.draftgo/worktree/',
+  '.draftgo/conflicts/',
+	'.draftgo/api-contract-cache.json',
+	'.draftgo/api-contract-cache.json.lock',
+];
+
+function parseHttpUrl(raw) {
+  let value = String(raw || '').trim();
+  if (!value) return null;
+  if (!/^https?:\/\//i.test(value)) value = `http://${value}`;
+  const parsed = new URL(value);
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password
+      || parsed.search || parsed.hash) {
+    throw new Error('DraftGo server must be an absolute HTTP(S) URL without credentials, query, or fragment.');
+  }
+  return parsed;
+}
+
+function normalizeServer(raw) {
+  const parsed = parseHttpUrl(raw);
+  if (!parsed) return '';
+  return parsed.toString().replace(/\/+$/, '');
+}
+
+function normalizeMcpEndpoint(raw) {
+  const parsed = parseHttpUrl(raw);
+  return parsed ? parsed.toString() : '';
+}
+
+function normalizeConnection(raw) {
+  const value = normalizeMcpEndpoint(raw);
+  if (!value) return { server: '', mcp_url: '' };
+  const parsed = new URL(value);
+  const pathname = parsed.pathname.replace(/\/+$/, '');
+  if (!pathname.toLowerCase().endsWith('/mcp')) {
+    return { server: '', mcp_url: value };
+  }
+  parsed.pathname = pathname.slice(0, -4) || '/';
+  return {
+    server: parsed.toString().replace(/\/+$/, ''),
+    mcp_url: value,
+  };
+}
+
+function configPath(projectDir) {
+  return path.join(projectDir, '.draftgo', 'config.json');
+}
+
+function ensureProjectIgnores(projectDir) {
+  for (const entry of IGNORE_ENTRIES) appendGitignoreLine(projectDir, entry);
+}
+
+function readExisting(projectDir) {
+  const file = configPath(projectDir);
+  if (!exists(file)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    throw new Error(`Invalid .draftgo/config.json: ${error.message}`);
+  }
+}
+
+function writePrivateJson(file, value) {
+  ensureDir(path.dirname(file));
+  const suffix = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const temporary = `${file}.tmp-${suffix}`;
+  const backup = `${file}.bak-${suffix}`;
+  let backedUp = false;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(temporary, 0o600); } catch { /* Windows ACLs are inherited. */ }
+    const descriptor = fs.openSync(temporary, 'r+');
+    try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+    if (exists(file)) { fs.renameSync(file, backup); backedUp = true; }
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    if (backedUp && !exists(file) && exists(backup)) fs.renameSync(backup, file);
+    throw error;
+  } finally {
+    if (exists(temporary)) fs.rmSync(temporary, { force: true });
+  }
+  if (exists(backup)) fs.rmSync(backup, { force: true });
+  try { fs.chmodSync(file, 0o600); } catch { /* Windows ACLs are inherited. */ }
+}
+
+function writeProjectConfig(projectDir, server, token, options = {}) {
+  const normalizedServer = normalizeServer(server);
+  const apiKey = String(token || '').trim();
+  if (!normalizedServer) throw new Error('DraftGo server is required.');
+  if (!apiKey) throw new Error('DraftGo API Key is required.');
+  const existing = readExisting(projectDir);
+  const config = {
+    server: normalizedServer,
+    token: apiKey,
+    auto_push: existing.auto_push === true,
+  };
+  if (options.mcp_url) config.mcp_url = normalizeMcpEndpoint(options.mcp_url);
+  else delete config.mcp_url;
+  const file = configPath(projectDir);
+  writePrivateJson(file, config);
+  ensureProjectIgnores(projectDir);
+  return file;
+}
+
+function loadProjectConfig(projectDir, { requireToken = true } = {}) {
+  const file = configPath(projectDir);
+  if (!exists(file)) throw new Error('Missing .draftgo/config.json; run `draftgo connect` first.');
+  const config = readExisting(projectDir);
+  const server = normalizeServer(config.server);
+  const mcpUrl = config.mcp_url ? normalizeMcpEndpoint(config.mcp_url) : '';
+  const token = String(config.token || config.sat || '').trim();
+  if (!server) throw new Error('DraftGo project config is missing server.');
+  if (requireToken && !token) throw new Error('DraftGo project config is missing API Key.');
+  const result = { server, token, auto_push: config.auto_push === true, path: file };
+  if (mcpUrl) result.mcp_url = mcpUrl;
+  else delete result.mcp_url;
+  return result;
+}
+
+module.exports = {
+  IGNORE_ENTRIES,
+  configPath,
+  normalizeServer,
+  normalizeMcpEndpoint,
+  normalizeConnection,
+  ensureProjectIgnores,
+  writeProjectConfig,
+  loadProjectConfig,
+};

package/src/projectDesign.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureProjectDesign(projectDir) {
+  const directory = path.join(projectDir, 'Design');
+  fs.mkdirSync(directory, { recursive: true });
+  const destination = path.join(directory, 'README.md');
+  try {
+    fs.copyFileSync(path.join(__dirname, '..', 'resources', 'project-design', 'README.md'), destination, fs.constants.COPYFILE_EXCL);
+    return { created: true, path: destination };
+  } catch (error) {
+    if (error.code === 'EEXIST') return { created: false, path: destination };
+    throw error;
+  }
+}
+
+module.exports = { ensureProjectDesign };

package/src/projectHealth.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const runtime = require('./runtimeFiles');
+
+const PROTECTED_PREFIXES = ['worktree/', 'conflicts/', 'lessons/', 'tmp/', 'config.json', 'api-contract-cache.json', 'api-contract-cache.json.lock', 'worklog.md', 'story.yaml', '.version', 'runtime-manifest.json'];
+function projectHealth(projectDir) {
+  const root = runtime.draftgoRoot(projectDir); const registered = new Set(runtime.load(projectDir).entries.map((entry) => String(entry.path).replace(/\\/g, '/')));
+  const summary = { managed_files: 0, unknown_files: 0, temporary_files: 0, artifact_files: 0, total_bytes: 0, reclaimable_bytes: 0, warnings: [] };
+  if (!fs.existsSync(root)) return summary;
+  const visit = (directory) => {
+    for (const item of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, item.name); const relative = path.relative(root, absolute).replace(/\\/g, '/');
+      if (item.isDirectory()) {
+        if ((/^(.+\/)?(build|dist|node_modules|tmp-build|build-)/i.test(relative)) && directorySize(absolute) > 50 * 1024 * 1024) summary.warnings.push({ code: 'DG-PROJECT-LARGE-BUILD', path: relative });
+        visit(absolute); continue;
+      }
+      if (!item.isFile()) continue;
+      const size = fs.statSync(absolute).size; summary.total_bytes += size;
+      const managed = registered.has(relative) || PROTECTED_PREFIXES.some((prefix) => relative === prefix || relative.startsWith(prefix));
+      if (managed) summary.managed_files += 1; else summary.unknown_files += 1;
+      if (relative.startsWith('tmp/')) summary.temporary_files += 1;
+      if (relative.startsWith('artifacts/')) summary.artifact_files += 1;
+      if (registered.has(relative) || relative.startsWith('tmp/')) summary.reclaimable_bytes += size;
+      if (!managed && (/\.exe$/i.test(relative) || (/^[^/]+\.(go|json)$/i.test(relative) && !['config.json', 'runtime-manifest.json'].includes(relative)))) summary.warnings.push({ code: 'DG-PROJECT-UNKNOWN-FILE', path: relative, size });
+      if (relative.startsWith('artifacts/') && !registered.has(relative)) summary.warnings.push({ code: 'DG-PROJECT-UNREGISTERED-ARTIFACT', path: relative, size });
+    }
+  };
+  visit(root); return summary;
+}
+function directorySize(directory) { let total = 0; const visit = (current) => { for (const item of fs.readdirSync(current, { withFileTypes: true })) { const absolute = path.join(current, item.name); if (item.isDirectory()) visit(absolute); else if (item.isFile()) total += fs.statSync(absolute).size; if (total > 50 * 1024 * 1024) return; } }; visit(directory); return total; }
+module.exports = { projectHealth };

package/src/projectMap.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const parse5 = require('parse5');
+const { loadManifest, absolutePath } = require('./worktree/manifest');
+const { mediaType } = require('./worktree/types');
+const { validateInlineScripts } = require('./worktree/inlineScripts');
+
+function normalizeRoute(route) {
+  if (!route || typeof route !== 'string') return '';
+  const clean = route.trim();
+  if (!clean || /^https?:\/\//i.test(clean) || clean.startsWith('#') || clean.startsWith('mailto:')) return '';
+  return clean.startsWith('/') ? clean : `/${clean}`;
+}
+
+function extractRoutes(html) {
+  const routes = new Set();
+  if (!html) return routes;
+  let document;
+  try { document = parse5.parse(html); } catch { return routes; }
+  const visit = (node) => {
+    for (const attribute of node.attrs || []) {
+      if (attribute.name === 'href' || attribute.name === 'data-page-route') {
+        const route = normalizeRoute(attribute.value);
+        if (route) routes.add(route);
+      }
+    }
+    for (const child of node.childNodes || []) visit(child);
+  };
+  visit(document);
+  return routes;
+}
+
+function extractScriptBindings() {
+  return { routes: [], events: [], schedules: [] };
+}
+
+function htmlParseErrors(html) {
+  const errors = [];
+  try {
+    parse5.parse(html, { onParseError(error) {
+      if (error.code !== 'missing-doctype') errors.push({
+        code: error.code || 'html-parse-error', line: error.startLine || null, column: error.startCol || null,
+      });
+    } });
+  } catch (error) {
+    errors.push({ code: error.message || 'html-parse-error', line: null, column: null });
+  }
+  return errors;
+}
+
+function sha256File(file) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(file));
+  return hash.digest('hex');
+}
+
+function decodeTextFile(file, contentType) {
+  const match = String(contentType || '').match(/;\s*charset\s*=\s*[']?([^;'\s]+)/i);
+  const charset = match ? match[1] : 'utf-8';
+  return new TextDecoder(charset, { fatal: true }).decode(fs.readFileSync(file));
+}
+
+function classifyPageArea(entry) {
+  const route = normalizeRoute(entry.route);
+  if (route === '/') return 'home';
+  if (/^\/(login|setup|install|register)(\/|$)/i.test(route)) return 'system';
+  if (/^\/admin(\/|$)/i.test(route)) return 'admin';
+  return route ? 'business' : 'unknown';
+}
+
+function collectGroups(pages) {
+  const groups = { home: [], admin: [], business: [], system: [], unknown: [] };
+  for (const page of pages) groups[page.area || 'unknown'].push(page);
+  return groups;
+}
+
+function buildProjectMap(projectDir) {
+  const manifest = loadManifest(projectDir);
+  const checkouts = Object.values(manifest.entries).map((entry) => ({ ...entry }));
+  const pages = checkouts.filter((entry) => entry.resource_type === 'pages').map((entry) => ({
+    ...entry, id: entry.resource_id, html_file: entry.local_path, area: classifyPageArea(entry),
+  }));
+  const navigations = checkouts.filter((entry) => entry.resource_type === 'navigations').map((entry) => ({
+    ...entry, id: entry.resource_id, html_file: entry.local_path,
+  }));
+  const docs = checkouts.filter((entry) => entry.resource_type === 'docs').map((entry) => ({
+    ...entry, id: entry.resource_id, content_file: entry.local_path,
+  }));
+
+  const routeRefs = new Map();
+  for (const entry of [...pages, ...navigations]) {
+    const file = absolutePath(projectDir, entry.local_path);
+    if (!fs.existsSync(file)) continue;
+    let source;
+    try { source = decodeTextFile(file, entry.content_type); } catch { continue; }
+    for (const route of extractRoutes(source)) {
+      if (!routeRefs.has(route)) routeRefs.set(route, new Set());
+      routeRefs.get(route).add(`${entry.resource_type}:${entry.resource_id}`);
+    }
+  }
+  return {
+    projectDir,
+    manifest_path: '.draftgo/worktree/manifest.json',
+    checkouts,
+    pages,
+    navigations,
+    docs,
+    pageGroups: collectGroups(pages),
+    routeRefs: Object.fromEntries([...routeRefs].map(([route, sources]) => [route, [...sources]])),
+    remote_only: ['db_meta', 'models', 'prompts', 'plugins', 'knowledge', 'memory', 'agents', 'custom_services', 'system_config', 'roles', 'users', 'doc_categories'],
+  };
+}
+
+function worktreeFiles(projectDir, directory) {
+  const root = path.join(projectDir, '.draftgo', 'worktree', directory);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.join(root, entry.name));
+}
+
+function analyzeProject(projectDir, options = {}) {
+  const map = buildProjectMap(projectDir);
+  const errors = [];
+  const warnings = [];
+  const warningDetails = [];
+  const addWarning = (code, confidence, message) => {
+    warnings.push(message);
+    warningDetails.push({ code, confidence, message });
+  };
+  const registered = new Set();
+
+  const resourceKeys = options.resourceKeys ? new Set(options.resourceKeys) : null;
+  const selectedCheckouts = resourceKeys
+    ? map.checkouts.filter((entry) => resourceKeys.has(`${entry.resource_type}:${entry.resource_id}`))
+    : map.checkouts;
+
+  for (const entry of selectedCheckouts) {
+    let local;
+    let base;
+    try {
+      local = absolutePath(projectDir, entry.local_path);
+      base = absolutePath(projectDir, entry.base_path);
+    } catch (error) {
+      errors.push(`${entry.resource_type} ${entry.resource_id}: ${error.message}`);
+      continue;
+    }
+    registered.add(path.resolve(local).toLowerCase());
+    if (!fs.existsSync(local)) {
+      errors.push(`${entry.resource_type} ${entry.resource_id}: local content is missing (${entry.local_path}).`);
+    }
+    if (!fs.existsSync(base)) {
+      errors.push(`${entry.resource_type} ${entry.resource_id}: checkout base is missing (${entry.base_path}).`);
+    } else {
+      const actualBaseHash = sha256File(base);
+      if (actualBaseHash !== entry.base_hash) {
+        errors.push(`${entry.resource_type} ${entry.resource_id}: checkout base hash does not match the manifest `
+          + `(manifest=${entry.base_hash}, base=${actualBaseHash}). `
+          + `Run \`draftgo check --remote\` to classify the mismatch before replacing files.`);
+      }
+    }
+
+    const type = mediaType(entry.content_type);
+    let expectedExtension = entry.file_extension;
+    if (type === 'text/html' || type === 'application/xhtml+xml') expectedExtension = '.html';
+    else if (type === 'text/markdown' || type === 'text/x-markdown') expectedExtension = '.md';
+    else if (type === 'text/plain') expectedExtension = '.txt';
+    if (path.extname(entry.local_path).toLowerCase() !== String(expectedExtension).toLowerCase()) {
+      errors.push(`${entry.resource_type} ${entry.resource_id}: local extension does not preserve ${entry.content_type}.`);
+    }
+    if (fs.existsSync(local) && (type === 'text/html' || type === 'application/xhtml+xml')) {
+      let source;
+      try { source = decodeTextFile(local, entry.content_type); }
+      catch (error) {
+        errors.push(`${entry.resource_type} ${entry.resource_id}: ${error.message}`);
+        continue;
+      }
+      for (const issue of htmlParseErrors(source).slice(0, 20)) {
+        const position = issue.line ? ` at ${issue.line}:${issue.column || 1}` : '';
+        addWarning('DG-HTML-001', 'high', `${entry.resource_type} ${entry.resource_id}: ${issue.code}${position}.`);
+      }
+      for (const issue of validateInlineScripts(source).slice(0, 20)) {
+        errors.push(`${entry.resource_type} ${entry.resource_id}: inline script #${issue.script} `
+          + `(${issue.script_type}) ${issue.message} at ${entry.local_path}:${issue.line}:${issue.column}.`);
+      }
+    }
+  }
+
+  if (!resourceKeys) {
+    for (const directory of ['pages', 'navigations', 'docs']) {
+      for (const file of worktreeFiles(projectDir, directory)) {
+        if (!registered.has(path.resolve(file).toLowerCase())) {
+          const relative = path.relative(projectDir, file).replace(/\\/g, '/');
+          addWarning('DG-WORKTREE-ORPHAN', 'high', `Unregistered worktree file: ${relative}.`);
+        }
+      }
+    }
+  }
+  for (const page of map.pages.filter((entry) => !resourceKeys || resourceKeys.has(`pages:${entry.resource_id}`))) {
+    if (!page.route || page.route === '/' || page.area === 'system') continue;
+    const sources = map.routeRefs[normalizeRoute(page.route)] || [];
+    if (!sources.some((source) => source.startsWith('navigations:'))) {
+      addWarning('DG-ROUTE-001', 'medium',
+        `pages ${page.resource_id}: route ${page.route} is not referenced by a checked-out navigation.`);
+    }
+  }
+  return { map, errors, warnings, warningDetails };
+}
+
+module.exports = {
+  buildProjectMap,
+  analyzeProject,
+  normalizeRoute,
+  extractRoutes,
+  extractScriptBindings,
+  htmlParseErrors,
+};

package/src/prompt.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// Tiny interactive prompt helpers built on Node's readline.
+// No external deps. All functions return Promises.
+
+const readline = require('readline');
+
+function makeRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+}
+
+function ask(question, { default: def } = {}) {
+  return new Promise((resolve) => {
+    const rl = makeRL();
+    const hint = def !== undefined && def !== '' ? ` [${def}]` : '';
+    rl.question(`${question}${hint} `, (answer) => {
+      rl.close();
+      const v = (answer || '').trim();
+      resolve(v === '' && def !== undefined ? String(def) : v);
+    });
+  });
+}
+
+async function askRequired(question, { default: def, validate } = {}) {
+  // Loop until user supplies a non-empty value (or default is used).
+  // If `validate(v)` returns a string, treat as error message and re-prompt.
+  while (true) {
+    const v = await ask(question, { default: def });
+    if (!v) {
+      console.log('  (不能为空，请重新输入)');
+      continue;
+    }
+    if (typeof validate === 'function') {
+      const err = validate(v);
+      if (typeof err === 'string' && err) {
+        console.log(`  ${err}`);
+        continue;
+      }
+    }
+    return v;
+  }
+}
+
+async function confirm(question, { default: def = false } = {}) {
+  const yn = def ? 'Y/n' : 'y/N';
+  const v = (await ask(`${question} (${yn})`)).toLowerCase();
+  if (!v) return def;
+  return v === 'y' || v === 'yes';
+}
+
+async function askPassword(question, { default: def } = {}) {
+  // Best-effort masked input. Falls back to plain input if stdin is not a TTY.
+  if (!process.stdin.isTTY) return ask(question, { default: def });
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const out = process.stdout;
+    const hint = def ? ' [使用上次保存的值]' : '';
+    out.write(`${question}${hint} `);
+    let buf = '';
+    const onData = (ch) => {
+      const s = ch.toString('utf8');
+      for (const c of s) {
+        if (c === '\n' || c === '\r' || c === '\u0004') {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.removeListener('data', onData);
+          out.write('\n');
+          const v = buf;
+          resolve(v === '' && def !== undefined ? String(def) : v);
+          return;
+        } else if (c === '\u0003') { // Ctrl+C
+          process.exit(130);
+        } else if (c === '\u007f' || c === '\b') {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            out.write('\b \b');
+          }
+        } else {
+          buf += c;
+          out.write('*');
+        }
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', onData);
+  });
+}
+
+module.exports = { ask, askRequired, confirm, askPassword };