gsd-cc 1.5.7 → 1.6.0

package/README.md

@@ -6,13 +6,14 @@ A project management system for AI-powered software development. Structure your
 
 Claude Code is the best coding agent available. But without structure, large projects degrade into chaos: context rot, lost decisions, no quality control.
 
-GSD-CC orchestrates Claude Code with native Skills (Markdown) — no API costs, no dependencies, no custom agent.
+GSD-CC orchestrates Claude Code with native Skills (Markdown) — no API costs,
+no build step, no custom agent.
 
 | Feature | GSD-CC |
 |---------|--------|
 | Runtime | Claude Code (native) |
 | Cost model | Max Plan (flat rate) |
-| Dependencies | Zero (Markdown + Bash) |
+| Dependencies | No build step (Markdown + Bash + CLI tools) |
 | Quality control | Mandatory UNIFY after every slice |
 | Boundary enforcement | Explicit DO NOT CHANGE rules per task |
 | Custom project types | Drop 3 files, done |
@@ -22,9 +23,31 @@ GSD-CC orchestrates Claude Code with native Skills (Markdown) — no API costs,
 ```bash
 npx gsd-cc            # Install globally (default)
 npx gsd-cc --local    # Install to current project only
-npx gsd-cc --uninstall
+npx gsd-cc --global --yes          # Install/update without prompts
+npx gsd-cc --local --language Deutsch
+npx gsd-cc --uninstall            # Remove detected installs safely
+npx gsd-cc --uninstall --global   # Remove only the global install
+npx gsd-cc --uninstall --local    # Remove only the local install
+npx gsd-cc dashboard --no-open    # Start the local dashboard
 ```
 
+GSD-CC tracks installed assets in `~/.claude/gsd-cc/install-manifest.json`
+(global) or `./.claude/gsd-cc/install-manifest.json` (local), removes only
+files it owns during uninstall, and aborts if an existing target file cannot
+be proven safe to overwrite.
+
+Installed layout:
+- Hooks: `~/.claude/hooks/gsd-cc/` or `./.claude/hooks/gsd-cc/`
+- Custom types: `~/.claude/skills/seed/types/<your-type>/` or `./.claude/skills/seed/types/<your-type>/`
+- Scope-specific uninstall: `--global` or `--local`
+- Prompt-free installs: `--yes`
+- Explicit UI language: `--language <name>`
+
+Reinstall and update runs preserve existing `GSD-CC language` and
+`GSD-CC commit language` settings by default. In non-interactive mode, missing
+UI language defaults to English and missing scope defaults to a global install.
+Commit language defaults to English and can be changed with `/gsd-cc-config`.
+
 ## Usage
 
 ```bash
@@ -38,12 +61,62 @@ GSD-CC reads your project state and suggests the next action. The full cycle:
 
 Auto-mode runs tasks autonomously via `claude -p` on your Max Plan.
 
+Artifact convention:
+- Slice overview: `.gsd/S{nn}-PLAN.md`
+- Per-task plans: `.gsd/S{nn}-T{nn}-PLAN.xml`
+
+## Dashboard
+
+The dashboard gives you a browser view of the current repository's GSD state:
+
+```bash
+npx gsd-cc dashboard
+npx gsd-cc dashboard --no-open
+npx gsd-cc dashboard --host 127.0.0.1 --port 4766
+```
+
+Inside Claude Code, run `/gsd-cc-dashboard` for the same launcher guidance.
+
+The server is local-only by default: it binds to `127.0.0.1`, reads `.gsd/`
+from the current project, and serves dashboard assets from the installed
+package. V1 is read-only. It shows project progress, auto-mode events, token
+costs, and safe `.gsd/` artifact previews, but it does not write files or run
+workflow actions.
+
 ## Requirements
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
 - Claude Code **Max Plan** (recommended for auto-mode)
 - **Git** initialized in your project
-- **jq** installed (`brew install jq`) — required for auto-mode
+- **jq** installed (`brew install jq`) — required for hooks-ready and
+  auto-ready installs
+
+Install still succeeds without `jq`, but jq-dependent hooks stay disabled and
+auto-mode remains unavailable until `jq` is installed. Rerun the installer
+after adding `jq` to activate hooks.
+
+## Testing
+
+From this package directory:
+
+```bash
+npm test
+```
+
+For dashboard integration sweeps, also launch the read-only Web App from a
+project that has `.gsd/` state:
+
+```bash
+npx gsd-cc dashboard --no-open
+```
+
+The dashboard is optional for auto-mode. Auto-mode writes `.gsd/events.jsonl`
+and other artifacts directly, so it continues to work when the dashboard
+server is not running.
+
+The suite uses temporary homes, projects, fake `claude`/`jq` binaries, and
+temporary Git repositories. It must not touch the developer's real
+`~/.claude`, call the real `claude` CLI, or require network access.
 
 ## Documentation
 

package/bin/install/args.js

@@ -0,0 +1,161 @@
+function defaultParsed() {
+  return {
+    command: 'install',
+    global: false,
+    local: false,
+    uninstall: false,
+    help: false,
+    yes: false,
+    language: null,
+    dashboard: null,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY)
+  };
+}
+
+function parseRequiredValue(rawArgs, index, optionName) {
+  const value = rawArgs[index + 1];
+  if (value === undefined || value.startsWith('-') || !value.trim()) {
+    throw new Error(`${optionName} requires a non-empty value.`);
+  }
+  return value.trim();
+}
+
+function parseDashboardPort(value) {
+  const trimmed = String(value).trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new Error('--port requires a number between 1 and 65535.');
+  }
+
+  const port = Number(trimmed);
+  if (port < 1 || port > 65535) {
+    throw new Error('--port requires a number between 1 and 65535.');
+  }
+
+  return port;
+}
+
+function ensureDashboardOptions(parsed) {
+  if (!parsed.dashboard) {
+    parsed.dashboard = {
+      host: null,
+      port: null,
+      open: true
+    };
+  }
+}
+
+function parseArgs(rawArgs) {
+  const parsed = defaultParsed();
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+
+    if (index === 0 && arg === 'dashboard') {
+      parsed.command = 'dashboard';
+      ensureDashboardOptions(parsed);
+      continue;
+    }
+
+    if (parsed.command === 'dashboard') {
+      if (arg === '--no-open') {
+        parsed.dashboard.open = false;
+        continue;
+      }
+
+      if (arg === '--host') {
+        parsed.dashboard.host = parseRequiredValue(rawArgs, index, '--host');
+        index += 1;
+        continue;
+      }
+
+      if (arg.startsWith('--host=')) {
+        const value = arg.slice('--host='.length).trim();
+        if (!value) {
+          throw new Error('--host requires a non-empty value.');
+        }
+        parsed.dashboard.host = value;
+        continue;
+      }
+
+      if (arg === '--port') {
+        parsed.dashboard.port = parseDashboardPort(
+          parseRequiredValue(rawArgs, index, '--port')
+        );
+        index += 1;
+        continue;
+      }
+
+      if (arg.startsWith('--port=')) {
+        parsed.dashboard.port = parseDashboardPort(arg.slice('--port='.length));
+        continue;
+      }
+
+      if (arg === '--help' || arg === '-h') {
+        parsed.help = true;
+        continue;
+      }
+
+      if (arg.startsWith('-')) {
+        throw new Error(`Unknown dashboard option: ${arg}`);
+      }
+
+      throw new Error(`Unexpected dashboard argument: ${arg}`);
+    }
+
+    if (arg === '--global' || arg === '-g') {
+      parsed.global = true;
+      continue;
+    }
+
+    if (arg === '--local' || arg === '-l') {
+      parsed.local = true;
+      continue;
+    }
+
+    if (arg === '--uninstall') {
+      parsed.uninstall = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === '--yes' || arg === '-y') {
+      parsed.yes = true;
+      continue;
+    }
+
+    if (arg === '--language') {
+      parsed.language = parseRequiredValue(rawArgs, index, '--language');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--language=')) {
+      const value = arg.slice('--language='.length).trim();
+      if (!value) {
+        throw new Error('--language requires a non-empty value.');
+      }
+      parsed.language = value;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  if (parsed.global && parsed.local) {
+    throw new Error('Cannot specify both --global and --local.');
+  }
+
+  return parsed;
+}
+
+module.exports = {
+  parseArgs
+};

package/bin/install/assets.js

@@ -0,0 +1,230 @@
+
+const fs = require('fs');
+const path = require('path');
+const {
+  INSTALL_LAYOUT,
+  CURRENT_HOOK_DIR,
+  LEGACY_HOOK_DIR
+} = require('./constants');
+const {
+  compareFileContents,
+  ensureDirectory,
+  sortPathsDeepFirst
+} = require('./fs-utils');
+const { formatPath } = require('./paths');
+const { buildHookSpecs } = require('./hooks');
+
+function collectRelativeFiles(rootDir, currentDir, files) {
+  const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const absolutePath = path.join(currentDir, entry.name);
+
+    if (entry.isDirectory()) {
+      collectRelativeFiles(rootDir, absolutePath, files);
+      continue;
+    }
+
+    files.push(path.relative(rootDir, absolutePath));
+  }
+}
+
+function collectAssets(srcBase, claudeBase) {
+  const assets = [];
+
+  for (const layout of INSTALL_LAYOUT) {
+    const sourceRoot = path.join(srcBase, layout.sourceDir);
+    if (!fs.existsSync(sourceRoot)) {
+      continue;
+    }
+
+    const relativeFiles = [];
+    collectRelativeFiles(sourceRoot, sourceRoot, relativeFiles);
+
+    for (const relativePath of relativeFiles) {
+      const targetRelativePath = path.join(layout.targetDir, relativePath);
+      assets.push({
+        sourcePath: path.join(sourceRoot, relativePath),
+        targetPath: path.join(claudeBase, targetRelativePath),
+        targetRelativePath,
+      });
+    }
+  }
+
+  return assets.sort((left, right) => {
+    return left.targetRelativePath.localeCompare(right.targetRelativePath);
+  });
+}
+
+function fileContains(filePath, snippet) {
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+
+  return fs.readFileSync(filePath, 'utf8').includes(snippet);
+}
+
+function detectLegacyInstallation(claudeBase) {
+  const reasons = [];
+  const skillsRoot = path.join(claudeBase, 'skills');
+  const routerSkill = path.join(skillsRoot, 'gsd-cc', 'SKILL.md');
+
+  if (fileContains(routerSkill, 'name: gsd-cc')) {
+    reasons.push('skills/gsd-cc/SKILL.md');
+  }
+
+  if (fs.existsSync(skillsRoot)) {
+    const entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (entry.name === 'gsd' || entry.name.startsWith('gsd-cc-')) {
+        reasons.push(path.join('skills', entry.name));
+      }
+    }
+  }
+
+  for (const spec of buildHookSpecs(claudeBase, LEGACY_HOOK_DIR)) {
+    for (const hook of spec.hooks) {
+      if (fs.existsSync(hook.command)) {
+        reasons.push(path.relative(claudeBase, hook.command));
+      }
+    }
+  }
+
+  return {
+    detected: reasons.length > 0,
+    reasons: [...new Set(reasons)].sort()
+  };
+}
+
+function collectLegacyPaths(claudeBase, assets) {
+  const detection = detectLegacyInstallation(claudeBase);
+  const legacyFiles = new Set();
+  const legacyDirectories = new Set();
+  const warnings = [];
+
+  if (!detection.detected) {
+    return {
+      detected: false,
+      reasons: [],
+      files: [],
+      directories: [],
+      warnings
+    };
+  }
+
+  for (const asset of assets) {
+    if (fs.existsSync(asset.targetPath)) {
+      legacyFiles.add(asset.targetRelativePath);
+    }
+  }
+
+  for (const spec of buildHookSpecs(claudeBase, LEGACY_HOOK_DIR)) {
+    for (const command of spec.commands) {
+      const absolutePath = path.join(claudeBase, command);
+      if (fs.existsSync(absolutePath)) {
+        legacyFiles.add(command);
+      }
+    }
+  }
+
+  const skillsRoot = path.join(claudeBase, 'skills');
+  if (fs.existsSync(skillsRoot)) {
+    const entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (entry.name === 'gsd' || entry.name.startsWith('gsd-cc-')) {
+        legacyDirectories.add(path.join('skills', entry.name));
+      }
+    }
+  }
+
+  const promptsDir = path.join(claudeBase, 'prompts');
+  if (fs.existsSync(promptsDir)) {
+    warnings.push(
+      `${formatPath(promptsDir)} was left in place because GSD-CC can no ` +
+      'longer prove it owns that directory.'
+    );
+  }
+
+  return {
+    detected: true,
+    reasons: detection.reasons,
+    files: [...legacyFiles].sort(),
+    directories: sortPathsDeepFirst([...legacyDirectories]),
+    warnings
+  };
+}
+
+function ensureNoConflicts(assets, ownedRelativePaths) {
+  const conflicts = [];
+
+  for (const asset of assets) {
+    if (!fs.existsSync(asset.targetPath)) {
+      continue;
+    }
+
+    if (ownedRelativePaths.has(asset.targetRelativePath)) {
+      continue;
+    }
+
+    const targetStat = fs.lstatSync(asset.targetPath);
+    if (!targetStat.isFile()) {
+      conflicts.push(asset.targetRelativePath);
+      continue;
+    }
+
+    if (compareFileContents(asset.sourcePath, asset.targetPath)) {
+      continue;
+    }
+
+    conflicts.push(asset.targetRelativePath);
+  }
+
+  if (conflicts.length === 0) {
+    return;
+  }
+
+  const rendered = conflicts.map((relativePath) => {
+    const asset = assets.find((candidate) => {
+      return candidate.targetRelativePath === relativePath;
+    });
+    return `  - ${formatPath(asset ? asset.targetPath : relativePath)}`;
+  }).join('\n');
+
+  throw new Error(
+    'Refusing to overwrite files that are not proven to be owned by GSD-CC:\n' +
+    `${rendered}\n` +
+    'Remove the conflicting files manually or uninstall the existing tool first.'
+  );
+}
+
+function getInstallMode(asset) {
+  const hookDirPrefix = `${CURRENT_HOOK_DIR}${path.sep}`;
+  if (
+    asset.targetRelativePath.startsWith(hookDirPrefix) &&
+    asset.targetRelativePath.endsWith('.sh')
+  ) {
+    return 0o755;
+  }
+
+  return fs.statSync(asset.sourcePath).mode & 0o777;
+}
+
+function copyAsset(asset) {
+  ensureDirectory(path.dirname(asset.targetPath));
+  fs.copyFileSync(asset.sourcePath, asset.targetPath);
+  fs.chmodSync(asset.targetPath, getInstallMode(asset));
+}
+
+module.exports = {
+  collectAssets,
+  collectLegacyPaths,
+  detectLegacyInstallation,
+  ensureNoConflicts,
+  copyAsset
+};

package/bin/install/cli.js

@@ -0,0 +1,167 @@
+const os = require('os');
+const readline = require('readline');
+const pkg = require('../../package.json');
+const { parseArgs } = require('./args');
+const { COLORS } = require('./constants');
+const { launchDashboard } = require('./dashboard');
+const { getClaudeBase } = require('./paths');
+const { writeLanguageConfig } = require('./language-config');
+const {
+  installAndConfigure,
+  printDefaultGlobalChoice,
+  printLanguageSet,
+  uninstall
+} = require('./operations');
+
+const { cyan, yellow, red, dim, reset } = COLORS;
+
+const banner = `
+${cyan}   ██████╗ ███████╗██████╗        ██████╗ ██████╗
+  ██╔════╝ ██╔════╝██╔══██╗      ██╔════╝██╔════╝
+  ██║  ███╗███████╗██║  ██║█████╗██║     ██║
+  ██║   ██║╚════██║██║  ██║╚════╝██║     ██║
+  ╚██████╔╝███████║██████╔╝      ╚██████╗╚██████╗
+   ╚═════╝ ╚══════╝╚═════╝        ╚═════╝ ╚═════╝${reset}
+
+  Get Shit Done on Claude Code ${dim}v${pkg.version}${reset}
+`;
+
+function printHelp() {
+  console.log(`  ${yellow}Usage:${reset} npx gsd-cc [options]
+         npx gsd-cc dashboard [options]
+
+  ${yellow}Commands:${reset}
+    ${cyan}dashboard${reset}       Start the local dashboard server
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}      Install globally to ~/.claude/skills/ ${dim}(default)${reset}
+    ${cyan}-l, --local${reset}       Install locally to ./.claude/skills/
+    ${cyan}--uninstall${reset}       Remove GSD-CC safely from detected installs
+    ${cyan}-y, --yes${reset}         Run without prompts
+    ${cyan}--language <name>${reset} Set GSD-CC language non-interactively
+    ${cyan}-h, --help${reset}        Show this help message
+
+  ${yellow}Dashboard Options:${reset}
+    ${cyan}--host <host>${reset}     Host to bind ${dim}(default: 127.0.0.1)${reset}
+    ${cyan}--port <number>${reset}   Port to bind ${dim}(default: 4766)${reset}
+    ${cyan}--no-open${reset}         Do not open a browser automatically
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install globally (default)${reset}
+    npx gsd-cc
+
+    ${dim}# Install to current project only${reset}
+    npx gsd-cc --local
+
+    ${dim}# Update or automate without prompts${reset}
+    npx gsd-cc --global --yes
+
+    ${dim}# Remove GSD-CC${reset}
+    npx gsd-cc --uninstall
+
+    ${dim}# Start the dashboard launcher${reset}
+    npx gsd-cc dashboard --no-open
+`);
+}
+
+function fail(error) {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`  ${red}Error:${reset} ${message}`);
+  process.exit(1);
+}
+
+function promptLanguage(isGlobal, onDone) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log(`
+  ${yellow}Which language should GSD-CC use?${reset}
+  ${dim}(e.g. English, Deutsch, Français, Español, ...)${reset}
+  ${dim}You can change this anytime with /gsd-cc-config in Claude Code${reset}
+`);
+
+  rl.question(`  Language ${dim}[English]${reset}: `, (answer) => {
+    rl.close();
+
+    try {
+      const language = answer.trim() || 'English';
+      writeLanguageConfig(isGlobal, language);
+      printLanguageSet(language);
+      onDone();
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
+
+function promptLocation(installOptions) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const globalPath = getClaudeBase(true).replace(os.homedir(), '~');
+
+  console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalPath})${reset} — available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.claude/)${reset} — this project only
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    console.log();
+
+    try {
+      const isGlobal = (answer.trim() || '1') !== '2';
+      installAndConfigure(isGlobal, installOptions, promptLanguage);
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
+
+function main(rawArgs) {
+  let options;
+  try {
+    options = parseArgs(rawArgs);
+  } catch (error) {
+    console.log(banner);
+    fail(error);
+  }
+
+  const hasGlobal = options.global;
+  const hasLocal = options.local;
+  const hasUninstall = options.uninstall;
+  const hasHelp = options.help;
+
+  console.log(banner);
+
+  if (hasHelp) {
+    printHelp();
+    return;
+  }
+
+  try {
+    if (options.command === 'dashboard') {
+      launchDashboard(options).catch(fail);
+    } else if (hasUninstall) {
+      uninstall(options);
+    } else if (hasGlobal) {
+      installAndConfigure(true, options, promptLanguage);
+    } else if (hasLocal) {
+      installAndConfigure(false, options, promptLanguage);
+    } else if (options.yes || !options.interactive) {
+      printDefaultGlobalChoice();
+      installAndConfigure(true, options, promptLanguage);
+    } else {
+      promptLocation(options);
+    }
+  } catch (error) {
+    fail(error);
+  }
+}
+
+module.exports = { main };