gsdd-cli 0.2.0 → 0.3.1

package/bin/lib/init-prompts.mjs

@@ -0,0 +1,308 @@
+import * as readline from 'readline';
+import { DEFAULT_GIT_PROTOCOL, normalizeModelProfile } from './models.mjs';
+import { buildRuntimeChoices, INIT_VERSION, resolveWizardAdapterTargets } from './init-runtime.mjs';
+
+const ANSI = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+};
+
+export function createInitPromptApi({ input = process.stdin, output = process.stdout } = {}) {
+  return {
+    async runInitWizard({ cwd, adapters }) {
+      output.write(`${ANSI.bold}${ANSI.cyan}GSDD Install Wizard${ANSI.reset}\n`);
+      output.write(`${ANSI.dim}Portable skills are always installed. Select the runtimes you want GSDD to feel native in.${ANSI.reset}\n\n`);
+
+      const runtimeChoices = buildRuntimeChoices(adapters);
+      const selectedRuntimes = await promptMultiSelect({
+        input,
+        output,
+        title: 'Step 1 of 3 - Select runtimes',
+        hint: 'Space toggles, Enter confirms.',
+        choices: runtimeChoices,
+      });
+      const installGovernance = await promptConfirm({
+        input,
+        output,
+        title: 'Step 2 of 3 - Repo-wide AGENTS.md governance',
+        prompt: 'Install repo-wide AGENTS.md rules?',
+        defaultValue: false,
+        details: [
+          'Why care: consistent behavioral discipline across sessions and mixed-runtime teams.',
+          'Why skip it: it writes to the repo root, and your selected runtimes already discover .agents/skills/ natively.',
+        ],
+      });
+      const config = await promptForConfig(cwd, { input, output });
+      return {
+        selectedRuntimes,
+        adapterTargets: resolveWizardAdapterTargets(selectedRuntimes, installGovernance),
+        config,
+      };
+    },
+    promptForConfig(cwd) {
+      return promptForConfig(cwd, { input, output });
+    },
+  };
+}
+
+export async function promptForConfig(cwd, { input = process.stdin, output = process.stdout } = {}) {
+  output.write(`\n${ANSI.bold}Step 3 of 3 - Configure planning defaults${ANSI.reset}\n`);
+
+  const researchDepth = await promptSingleSelect({
+    input,
+    output,
+    title: 'Research depth',
+    choices: [
+      { value: 'balanced', label: 'balanced', description: 'SOTA research per phase (recommended)' },
+      { value: 'fast', label: 'fast', description: 'Skip deeper domain research and plan from current context' },
+      { value: 'deep', label: 'deep', description: 'Exhaustive research sweeps and parallel researchers' },
+    ],
+    defaultIndex: 0,
+  });
+  const parallelization = await promptSingleSelect({
+    input,
+    output,
+    title: 'Parallelization',
+    choices: yesNoChoices('Run independent agents in parallel?', true),
+    defaultIndex: 0,
+  });
+  const commitDocs = await promptSingleSelect({
+    input,
+    output,
+    title: 'Planning docs in git',
+    choices: yesNoChoices('Track .planning/ in git?', true),
+    defaultIndex: 0,
+  });
+  const modelProfile = await promptSingleSelect({
+    input,
+    output,
+    title: 'Model profile',
+    choices: [
+      { value: 'balanced', label: 'balanced', description: 'Capable default for most agents (recommended)' },
+      { value: 'quality', label: 'quality', description: 'Most capable model for research and roadmap work' },
+      { value: 'budget', label: 'budget', description: 'Cheapest and fastest model profile' },
+    ],
+    defaultIndex: 0,
+  });
+  const workflowResearch = await promptSingleSelect({
+    input,
+    output,
+    title: 'Workflow research',
+    choices: yesNoChoices('Research before planning each phase?', true),
+    defaultIndex: 0,
+  });
+  const workflowDiscuss = await promptSingleSelect({
+    input,
+    output,
+    title: 'Approach discussion',
+    choices: yesNoChoices('Explore approaches with the user before planning?', false),
+    defaultIndex: 0,
+  });
+  const workflowPlanCheck = await promptSingleSelect({
+    input,
+    output,
+    title: 'Plan checking',
+    choices: yesNoChoices('Run the fresh-context plan checker before execution?', true),
+    defaultIndex: 0,
+  });
+  const workflowVerifier = await promptSingleSelect({
+    input,
+    output,
+    title: 'Phase verification',
+    choices: yesNoChoices('Run phase verification after execution?', true),
+    defaultIndex: 0,
+  });
+
+  const gitProtocol = await promptGitProtocol(cwd, { input, output });
+
+  return {
+    researchDepth,
+    parallelization,
+    commitDocs,
+    modelProfile: normalizeModelProfile(modelProfile),
+    workflow: {
+      research: workflowResearch,
+      discuss: workflowDiscuss,
+      planCheck: workflowPlanCheck,
+      verifier: workflowVerifier,
+    },
+    gitProtocol,
+    initVersion: INIT_VERSION,
+  };
+}
+
+export async function promptGitProtocol(cwd, { input = process.stdin, output = process.stdout } = {}) {
+  if (typeof input.resume === 'function') input.resume();
+  output.write(`\n${ANSI.bold}Version control guidance${ANSI.reset}\n`);
+  output.write(`${ANSI.dim}This is advisory only. Repo or user conventions still win.${ANSI.reset}\n`);
+  const rl = readline.createInterface({ input, output });
+  const askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    let branch = await askQuestion('  Branching guidance (Enter for default): ');
+    branch = branch.trim() || DEFAULT_GIT_PROTOCOL.branch;
+
+    let commit = await askQuestion('  Commit guidance (Enter for default): ');
+    commit = commit.trim() || DEFAULT_GIT_PROTOCOL.commit;
+
+    let pr = await askQuestion('  PR guidance (Enter for default): ');
+    pr = pr.trim() || DEFAULT_GIT_PROTOCOL.pr;
+
+    return { branch, commit, pr };
+  } finally {
+    rl.close();
+  }
+}
+
+export function yesNoChoices(prompt, defaultYes) {
+  return [
+    { value: true, label: 'yes', description: `${prompt} Yes.` },
+    { value: false, label: 'no', description: `${prompt} No.` },
+  ].sort((a, b) => {
+    if (defaultYes) return a.value === true ? -1 : 1;
+    return a.value === false ? -1 : 1;
+  });
+}
+
+export async function promptConfirm({ input, output, title, prompt, defaultValue, details = [] }) {
+  if (typeof input.resume === 'function') input.resume();
+  output.write(`\n${ANSI.bold}${title}${ANSI.reset}\n`);
+  for (const detail of details) {
+    output.write(`  ${ANSI.dim}${detail}${ANSI.reset}\n`);
+  }
+  const rl = readline.createInterface({ input, output });
+  const suffix = defaultValue ? '[Y/n]' : '[y/N]';
+  try {
+    const answer = await new Promise((resolve) => rl.question(`  ${prompt} ${suffix}: `, resolve));
+    const normalized = answer.trim().toLowerCase();
+    if (!normalized) return defaultValue;
+    return normalized === 'y' || normalized === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+export async function promptSingleSelect({ input, output, title, choices, defaultIndex = 0 }) {
+  const selected = await promptChoiceList({
+    input,
+    output,
+    title,
+    choices: choices.map((choice, index) => ({
+      ...choice,
+      selected: index === defaultIndex,
+      detected: false,
+    })),
+    multi: false,
+  });
+  return selected[0];
+}
+
+export async function promptMultiSelect({ input, output, title, hint, choices }) {
+  return promptChoiceList({ input, output, title, hint, choices, multi: true });
+}
+
+export async function promptChoiceList({ input, output, title, hint = 'Use arrows to move. Enter confirms.', choices, multi }) {
+  if (typeof input.resume === 'function') input.resume();
+  readline.emitKeypressEvents(input);
+  const previousRawMode = typeof input.isRaw === 'boolean' ? input.isRaw : false;
+  if (typeof input.setRawMode === 'function') input.setRawMode(true);
+
+  let cursor = Math.max(0, choices.findIndex((choice) => choice.selected));
+  let renderedLines = 0;
+
+  const selectCursor = () => {
+    if (multi) return;
+    for (const choice of choices) choice.selected = false;
+    choices[cursor].selected = true;
+  };
+
+  const measureLines = (text) => {
+    const columns = Math.max(20, Number(output.columns) || 80);
+    const visible = stripAnsi(text);
+    return visible.split('\n').reduce((total, line) => {
+      const width = Math.max(1, line.length);
+      return total + Math.ceil(width / columns);
+    }, 0);
+  };
+
+  const render = () => {
+    if (renderedLines > 0) {
+      readline.moveCursor(output, 0, -renderedLines);
+    }
+    readline.cursorTo(output, 0);
+    readline.clearScreenDown(output);
+    const lines = [`${ANSI.bold}${title}${ANSI.reset}`];
+    if (hint) lines.push(`${ANSI.dim}${hint}${ANSI.reset}`);
+    lines.push('');
+    for (let i = 0; i < choices.length; i++) {
+      const choice = choices[i];
+      const pointer = i === cursor ? `${ANSI.green}>${ANSI.reset}` : ' ';
+      const mark = choice.selected ? `${ANSI.green}[x]${ANSI.reset}` : '[ ]';
+      const detected = choice.detected ? ` ${ANSI.dim}(detected)${ANSI.reset}` : '';
+      lines.push(`${pointer} ${mark} ${choice.label}${detected}`);
+      lines.push(`    ${ANSI.dim}${choice.description}${ANSI.reset}`);
+    }
+
+    renderedLines = 0;
+    for (const line of lines) {
+      output.write(`${line}\n`);
+      renderedLines += measureLines(line);
+    }
+  };
+
+  render();
+
+  const values = await new Promise((resolve, reject) => {
+    const cleanup = () => {
+      input.off('keypress', onKeypress);
+      if (typeof input.setRawMode === 'function') input.setRawMode(previousRawMode);
+    };
+
+    const onKeypress = (_, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        cleanup();
+        reject(new Error('Prompt cancelled by user'));
+        return;
+      }
+      if (key.name === 'up') {
+        cursor = cursor === 0 ? choices.length - 1 : cursor - 1;
+        selectCursor();
+        render();
+        return;
+      }
+      if (key.name === 'down') {
+        cursor = cursor === choices.length - 1 ? 0 : cursor + 1;
+        selectCursor();
+        render();
+        return;
+      }
+      if (key.name === 'space') {
+        if (multi) {
+          choices[cursor].selected = !choices[cursor].selected;
+        } else {
+          for (const choice of choices) choice.selected = false;
+          choices[cursor].selected = true;
+        }
+        render();
+        return;
+      }
+      if (key.name === 'return') {
+        selectCursor();
+        cleanup();
+        resolve(choices.filter((choice) => choice.selected).map((choice) => choice.value ?? choice.id));
+      }
+    };
+
+    input.on('keypress', onKeypress);
+  });
+
+  output.write('\n');
+  return values;
+}
+
+export function stripAnsi(text) {
+  return String(text).replace(/\x1B\[[0-9;]*[A-Za-z]/g, '');
+}

package/bin/lib/init-runtime.mjs

@@ -0,0 +1,224 @@
+const RUNTIME_OPTIONS = [
+  {
+    id: 'claude',
+    label: 'Claude Code',
+    description: 'Native skills, commands, and agents',
+    kind: 'native',
+  },
+  {
+    id: 'opencode',
+    label: 'OpenCode',
+    description: 'Native slash commands and agents',
+    kind: 'native',
+  },
+  {
+    id: 'codex',
+    label: 'Codex CLI',
+    description: 'Portable skills plus native checker agents',
+    kind: 'native',
+  },
+  {
+    id: 'cursor',
+    label: 'Cursor',
+    description: 'Skills-native slash commands from .agents/skills/',
+    kind: 'skills_native',
+  },
+  {
+    id: 'copilot',
+    label: 'GitHub Copilot',
+    description: 'Skills-native slash commands from .agents/skills/',
+    kind: 'skills_native',
+  },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    description: 'Skills-native slash commands from .agents/skills/',
+    kind: 'skills_native',
+  },
+];
+
+export const INIT_VERSION = 'v1.1';
+
+export function normalizeRequestedTools(requestedTools) {
+  const selectedRuntimes = [];
+  const adapterTargets = [];
+  const addRuntime = (runtime) => {
+    if (!selectedRuntimes.includes(runtime)) selectedRuntimes.push(runtime);
+  };
+  const addAdapter = (adapter) => {
+    if (!adapterTargets.includes(adapter)) adapterTargets.push(adapter);
+  };
+
+  for (const tool of requestedTools) {
+    if (tool === 'claude' || tool === 'opencode' || tool === 'codex') {
+      addRuntime(tool);
+      addAdapter(tool);
+      continue;
+    }
+    if (tool === 'cursor' || tool === 'copilot' || tool === 'gemini') {
+      addRuntime(tool);
+      addAdapter(tool);
+      continue;
+    }
+    if (tool === 'agents') {
+      addAdapter('agents');
+    }
+  }
+
+  return { selectedRuntimes, adapterTargets };
+}
+
+export function detectPlatforms(adapters) {
+  return Object.values(adapters)
+    .filter((adapter, index, arr) => arr.findIndex((other) => other.id === adapter.id) === index)
+    .filter((adapter) => adapter.detect())
+    .map((adapter) => adapter.name);
+}
+
+export function buildRuntimeChoices(adapters) {
+  const detected = new Set(detectPlatforms(adapters));
+  return RUNTIME_OPTIONS.map((option) => ({
+    ...option,
+    detected: detected.has(option.id),
+    selected: detected.has(option.id),
+  }));
+}
+
+export function resolveAdapters(adapters, platformNames) {
+  const seen = new Set();
+  const resolved = [];
+
+  for (const platformName of platformNames) {
+    const adapter = adapters[platformName];
+    if (!adapter || seen.has(adapter.id)) continue;
+    seen.add(adapter.id);
+    resolved.push(adapter);
+  }
+
+  return resolved;
+}
+
+export function getAdaptersToUpdate(adapters, platformNames) {
+  const requested = new Set(platformNames);
+  const seen = new Set();
+  const installed = [];
+
+  for (const [platformName, adapter] of Object.entries(adapters)) {
+    if (seen.has(adapter.id)) continue;
+    if (!requested.has(platformName) && !adapter.isInstalled()) continue;
+    seen.add(adapter.id);
+    installed.push(adapter);
+  }
+
+  return installed;
+}
+
+export async function resolveInteractiveInitSession({ ctx, promptApi, parsedTools, isAuto }) {
+  if (parsedTools.length > 0) {
+    return {
+      ...normalizeRequestedTools(parsedTools),
+      config: null,
+    };
+  }
+
+  if (isAuto) {
+    return { selectedRuntimes: [], adapterTargets: [], config: null };
+  }
+
+  if (!process.stdin.isTTY) {
+    return {
+      selectedRuntimes: detectPlatforms(ctx.adapters),
+      adapterTargets: detectPlatforms(ctx.adapters),
+      config: null,
+    };
+  }
+
+  return promptApi.runInitWizard({ cwd: ctx.cwd, adapters: ctx.adapters });
+}
+
+export function resolveWizardAdapterTargets(selectedRuntimes, installGovernance) {
+  const adapterTargets = [];
+  for (const runtime of selectedRuntimes) {
+    if (runtime === 'claude' || runtime === 'opencode' || runtime === 'codex') {
+      adapterTargets.push(runtime);
+    }
+  }
+  if (installGovernance) adapterTargets.push('agents');
+  return adapterTargets;
+}
+
+export function getPostInitRoutingLines(selectedRuntimes) {
+  const lines = [];
+  if (selectedRuntimes.includes('claude')) lines.push('  Claude Code:  /gsdd-new-project');
+  if (selectedRuntimes.includes('opencode')) lines.push('  OpenCode:     /gsdd-new-project');
+  if (selectedRuntimes.includes('codex')) lines.push('  Codex CLI:    $gsdd-new-project');
+  if (selectedRuntimes.includes('cursor')) lines.push('  Cursor:       /gsdd-new-project');
+  if (selectedRuntimes.includes('copilot')) lines.push('  Copilot:      /gsdd-new-project');
+  if (selectedRuntimes.includes('gemini')) lines.push('  Gemini CLI:   /gsdd-new-project');
+  lines.push('  Any tool:     open .agents/skills/gsdd-new-project/SKILL.md');
+  return lines;
+}
+
+export function getHelpText() {
+  return `
+gsdd - GSD Distilled CLI
+Spec-Driven Development for AI coding agents.
+
+Usage: gsdd <command> [args]
+
+Commands:
+  init [--tools <platform>] [--auto] [--brief <file>]
+                              Launch guided install wizard in TTYs, or use --tools for manual/headless setup
+                              --auto: non-interactive mode with smart defaults (requires --tools)
+                              --brief <file>: copy project brief to .planning/PROJECT_BRIEF.md
+  update [--tools <platform>] [--templates] [--dry]
+                              Regenerate adapters from latest framework sources
+                              --templates: also refresh .planning/templates/ and roles
+                              --dry: preview changes without writing files
+  health [--json]             Check workspace integrity (healthy/degraded/broken)
+  models [subcommand]         Inspect or update model profile / runtime overrides
+  find-phase [N]              Show phase info as JSON (for agent consumption)
+  verify <N>                  Run artifact checks for phase N
+  scaffold phase <N> [name]   Create a new phase plan file
+
+Platforms (for --tools):
+  claude    Generate Claude Code skills (.claude/skills/gsdd-*), commands (.claude/commands/gsdd-*.md), and native agents (.claude/agents/gsdd-*.md)
+  opencode  Generate OpenCode local slash commands (.opencode/commands/gsdd-*.md) + native agents (.opencode/agents/gsdd-*.md)
+  codex     Generate Codex CLI native plan-checker agent (.codex/agents/gsdd-plan-checker.toml)
+  agents    Generate/Update root AGENTS.md (bounded GSDD block)
+  cursor    Generate root AGENTS.md governance block; workflows are already discovered natively from .agents/skills/ (legacy alias kept for backward compatibility)
+  copilot   Generate root AGENTS.md governance block; workflows are already discovered natively from .agents/skills/ (legacy alias kept for backward compatibility)
+  gemini    Generate root AGENTS.md governance block; workflows are already discovered natively from .agents/skills/ (legacy alias kept for backward compatibility)
+  all       Generate all adapters (Claude, OpenCode, Codex, AGENTS-based surfaces)
+
+Notes:
+  - init always generates open-standard skills at .agents/skills/gsdd-* (portable workflow entrypoints)
+  - running plain \`gsdd init\` in a terminal opens the guided runtime-selection wizard
+  - the wizard lets you pick runtimes first, then separately decide whether repo-wide AGENTS.md governance is worth installing
+  - --tools remains the advanced/manual path and preserves legacy runtime aliases for backward compatibility
+  - --tools codex generates .codex/agents/gsdd-plan-checker.toml (portable skill is the entry surface)
+  - root AGENTS.md is only written on init when explicitly requested via --tools agents, --tools all, or the wizard governance opt-in
+
+Examples:
+  npx gsdd-cli init
+  npx gsdd-cli init --tools claude
+  npx gsdd-cli init --tools cursor
+  npx gsdd-cli init --auto --tools claude --brief project-idea.md
+  npx gsdd-cli init --auto --tools all
+  npx gsdd-cli models show
+  npx gsdd-cli models profile quality
+  npx gsdd-cli models agent-profile --agent plan-checker --profile quality
+  npx gsdd-cli models set --runtime opencode --agent plan-checker --model anthropic/claude-opus-4-6
+  npx gsdd-cli models clear --runtime opencode --agent plan-checker
+  npx gsdd-cli init --tools agents
+  npx gsdd-cli init --tools all
+  npx gsdd-cli update
+  npx gsdd-cli find-phase
+  npx gsdd-cli verify 1
+  npx gsdd-cli scaffold phase 4 Payments
+
+Workflows (run via skills/adapters generated by init, not direct CLI):
+  map-codebase      Map or refresh codebase (.agents/skills/gsdd-map-codebase/)
+  audit-milestone   Audit a completed milestone (.agents/skills/gsdd-audit-milestone/)
+`;
+}