gsd-cc 1.5.7 → 1.6.0

package/bin/install/constants.js

@@ -0,0 +1,77 @@
+
+const path = require('path');
+
+const COLORS = {
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m'
+};
+
+const MANAGED_BY = 'gsd-cc';
+const MANIFEST_VERSION = 1;
+const MANIFEST_DIR = 'gsd-cc';
+const MANIFEST_FILENAME = 'install-manifest.json';
+const CURRENT_HOOK_DIR = path.join('hooks', 'gsd-cc');
+const LEGACY_HOOK_DIR = 'hooks';
+const CLAUDE_CONFIG_BLOCK_START = '<!-- gsd-cc:config:start -->';
+const CLAUDE_CONFIG_BLOCK_END = '<!-- gsd-cc:config:end -->';
+const LEGACY_CLAUDE_CONFIG_REGEX = /\n?# GSD-CC Config\nGSD-CC language: .+\n(?:GSD-CC commit language: .+\n?)?/;
+const LEGACY_LANGUAGE_CONFIG_REGEX = /(?:^|\n)# GSD-CC Config\nGSD-CC language:\s*([^\n]+)(?:\n|$)/;
+const LANGUAGE_LINE_REGEX = /^GSD-CC language:\s*(.+?)\s*$/m;
+const COMMIT_LANGUAGE_LINE_REGEX = /^GSD-CC commit language:\s*(.+?)\s*$/m;
+const DEFAULT_COMMIT_LANGUAGE = 'English';
+
+const INSTALL_LAYOUT = [
+  { sourceDir: 'dashboard', targetDir: 'dashboard' },
+  { sourceDir: 'skills', targetDir: 'skills' },
+  { sourceDir: 'hooks', targetDir: CURRENT_HOOK_DIR },
+  { sourceDir: 'checklists', targetDir: 'checklists' },
+  { sourceDir: 'scripts', targetDir: 'scripts' },
+  { sourceDir: 'templates', targetDir: 'templates' },
+];
+
+const HOOK_SPECS = [
+  {
+    event: 'PreToolUse',
+    matcher: 'Edit|Write|MultiEdit',
+    hooks: [
+      { file: 'gsd-boundary-guard.sh', timeout: 5000 },
+      { file: 'gsd-prompt-guard.sh', timeout: 5000 }
+    ]
+  },
+  {
+    event: 'PostToolUse',
+    matcher: null,
+    hooks: [
+      { file: 'gsd-context-monitor.sh', timeout: 5000 },
+      { file: 'gsd-statusline.sh', timeout: 3000 }
+    ]
+  },
+  {
+    event: 'PostToolUse',
+    matcher: 'Edit|Write',
+    hooks: [{ file: 'gsd-workflow-guard.sh', timeout: 5000 }]
+  }
+];
+
+module.exports = {
+  COLORS,
+  MANAGED_BY,
+  MANIFEST_VERSION,
+  MANIFEST_DIR,
+  MANIFEST_FILENAME,
+  CURRENT_HOOK_DIR,
+  LEGACY_HOOK_DIR,
+  CLAUDE_CONFIG_BLOCK_START,
+  CLAUDE_CONFIG_BLOCK_END,
+  LEGACY_CLAUDE_CONFIG_REGEX,
+  LEGACY_LANGUAGE_CONFIG_REGEX,
+  LANGUAGE_LINE_REGEX,
+  COMMIT_LANGUAGE_LINE_REGEX,
+  DEFAULT_COMMIT_LANGUAGE,
+  INSTALL_LAYOUT,
+  HOOK_SPECS
+};

package/bin/install/dashboard.js

@@ -0,0 +1,93 @@
+const path = require('path');
+const { spawn } = require('child_process');
+const {
+  startDashboardServer
+} = require('../../scripts/dashboard-server');
+
+function shouldOpenBrowser(options) {
+  return Boolean(
+    options.dashboard
+    && options.dashboard.open !== false
+    && options.interactive
+    && !process.env.CI
+    && !process.env.GSD_CC_TEST_RUNNER
+  );
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let command;
+  let args;
+
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const child = spawn(command, args, {
+    detached: true,
+    stdio: 'ignore'
+  });
+
+  child.on('error', () => {});
+  child.unref();
+}
+
+function installShutdownHandlers(dashboard) {
+  let stopping = false;
+
+  async function stop(signal) {
+    if (stopping) {
+      return;
+    }
+
+    stopping = true;
+
+    try {
+      await dashboard.close();
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      console.error(`  Error stopping dashboard: ${message}`);
+    }
+
+    process.exit(signal === 'SIGINT' ? 130 : 143);
+  }
+
+  process.once('SIGINT', () => stop('SIGINT'));
+  process.once('SIGTERM', () => stop('SIGTERM'));
+}
+
+async function launchDashboard(options) {
+  const dashboardOptions = options.dashboard || {};
+  const requestedPort = dashboardOptions.port;
+  const dashboard = await startDashboardServer({
+    host: dashboardOptions.host,
+    port: requestedPort,
+    projectRoot: process.cwd(),
+    allowPortFallback: requestedPort === null || requestedPort === undefined
+  });
+
+  console.log(`  GSD-CC Dashboard running at ${dashboard.url}`);
+  console.log(`  Watching ${path.join(dashboard.projectRoot, '.gsd')}`);
+
+  if (shouldOpenBrowser(options)) {
+    openBrowser(dashboard.url);
+    console.log('  Opening browser.');
+  }
+
+  console.log('  Press Ctrl+C to stop.');
+
+  installShutdownHandlers(dashboard);
+  return dashboard;
+}
+
+module.exports = {
+  launchDashboard,
+  shouldOpenBrowser
+};

package/bin/install/dependencies.js

@@ -0,0 +1,150 @@
+
+const fs = require('fs');
+const path = require('path');
+const { COLORS } = require('./constants');
+
+const { green, yellow, reset } = COLORS;
+
+function findExecutable(command) {
+  const searchPath = process.env.PATH || '';
+  const extensions = process.platform === 'win32'
+    ? ['', ...(process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+      .split(';')
+      .filter(Boolean)
+      .map((extension) => extension.toLowerCase())]
+    : [''];
+
+  for (const directory of searchPath.split(path.delimiter)) {
+    if (!directory) {
+      continue;
+    }
+
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${command}${extension}`);
+
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch (error) {
+        continue;
+      }
+    }
+  }
+
+  return null;
+}
+
+function buildReadinessState(reasons) {
+  return {
+    ready: reasons.length === 0,
+    reasons
+  };
+}
+
+function probeDependencies() {
+  const dependencies = {
+    jq: {
+      label: 'jq',
+      path: findExecutable('jq')
+    },
+    git: {
+      label: 'git',
+      path: findExecutable('git')
+    },
+    claude: {
+      label: 'claude CLI',
+      path: findExecutable('claude')
+    }
+  };
+
+  for (const dependency of Object.values(dependencies)) {
+    dependency.available = Boolean(dependency.path);
+  }
+
+  const hookReasons = [];
+  if (!dependencies.jq.available) {
+    hookReasons.push('jq not found');
+  }
+
+  const autoReasons = [];
+  if (!dependencies.jq.available) {
+    autoReasons.push('jq not found');
+  }
+  if (!dependencies.git.available) {
+    autoReasons.push('git not found');
+  }
+  if (!dependencies.claude.available) {
+    autoReasons.push('claude CLI not found');
+  }
+
+  return {
+    dependencies,
+    readiness: {
+      install: buildReadinessState([]),
+      hooks: buildReadinessState(hookReasons),
+      auto: buildReadinessState(autoReasons)
+    }
+  };
+}
+
+function getReadinessStatusLabel(name, readiness) {
+  if (readiness.ready) {
+    return `${green}ready${reset}`;
+  }
+
+  return name === 'hooks'
+    ? `${yellow}disabled${reset}`
+    : `${yellow}unavailable${reset}`;
+}
+
+function formatReadinessLine(name, label, readiness) {
+  const suffix = readiness.ready
+    ? ''
+    : ` (${readiness.reasons.join(', ')})`;
+
+  return `  ${label}: ${getReadinessStatusLabel(name, readiness)}${suffix}`;
+}
+
+function getRecoverySteps(probe, isGlobal) {
+  const steps = [];
+  const reinstallCommand = isGlobal ? 'npx gsd-cc' : 'npx gsd-cc --local';
+
+  if (!probe.dependencies.jq.available) {
+    if (process.platform === 'darwin') {
+      steps.push('Install jq: brew install jq');
+    } else if (process.platform === 'linux') {
+      steps.push('Install jq with your distro package manager, such as apt, yum, or pacman');
+    } else {
+      steps.push('Install jq with your system package manager or from https://jqlang.github.io/jq/download/');
+    }
+    steps.push(`Rerun ${reinstallCommand} to enable hooks after jq is available`);
+  }
+
+  if (!probe.dependencies.git.available) {
+    steps.push('Install Git and ensure `git` is available in your PATH');
+  }
+
+  if (!probe.dependencies.claude.available) {
+    steps.push('Install Claude Code and ensure `claude` is available in your PATH');
+  }
+
+  return steps;
+}
+
+function printReadinessSummary(probe, isGlobal) {
+  console.log('\n  Readiness summary:');
+  console.log(formatReadinessLine('install', 'Installation', probe.readiness.install));
+  console.log(formatReadinessLine('hooks', 'Hooks', probe.readiness.hooks));
+  console.log(formatReadinessLine('auto', 'Auto-mode', probe.readiness.auto));
+
+  const steps = getRecoverySteps(probe, isGlobal);
+  for (const step of steps) {
+    console.log(`  Next step: ${step}`);
+  }
+}
+
+module.exports = {
+  findExecutable,
+  probeDependencies,
+  printReadinessSummary
+};

package/bin/install/fs-utils.js

@@ -0,0 +1,133 @@
+
+const fs = require('fs');
+const path = require('path');
+const { MANIFEST_DIR } = require('./constants');
+const { formatPath } = require('./paths');
+
+function ensureDirectory(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeFileAtomic(filePath, content, mode) {
+  ensureDirectory(path.dirname(filePath));
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  const options = mode === undefined ? undefined : { mode };
+  fs.writeFileSync(tempPath, content, options);
+  if (mode !== undefined) {
+    fs.chmodSync(tempPath, mode);
+  }
+  fs.renameSync(tempPath, filePath);
+}
+
+function writeJsonAtomic(jsonPath, value) {
+  writeFileAtomic(jsonPath, JSON.stringify(value, null, 2) + '\n');
+}
+
+function loadJsonFile(jsonPath, label) {
+  if (!fs.existsSync(jsonPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `${label} at ${formatPath(jsonPath)} contains invalid JSON. ` +
+      `GSD-CC left it untouched.`
+    );
+  }
+}
+
+function validateSettingsStructure(settings, settingsPath) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error(
+      `Claude settings at ${formatPath(settingsPath)} must be a JSON object.`
+    );
+  }
+
+  if (
+    settings.hooks !== undefined &&
+    (typeof settings.hooks !== 'object' || Array.isArray(settings.hooks))
+  ) {
+    throw new Error(
+      `Claude settings at ${formatPath(settingsPath)} contain an invalid ` +
+      '"hooks" value. Expected an object.'
+    );
+  }
+
+  if (settings.hooks) {
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) {
+        throw new Error(
+          `Claude settings at ${formatPath(settingsPath)} contain an invalid ` +
+          `hook list for "${event}". Expected an array.`
+        );
+      }
+    }
+  }
+}
+
+function loadJsonFileForCleanup(jsonPath, label, warnings) {
+  try {
+    return loadJsonFile(jsonPath, label);
+  } catch (error) {
+    warnings.push(error.message);
+    return null;
+  }
+}
+
+function compareFileContents(sourcePath, targetPath) {
+  const sourceStat = fs.statSync(sourcePath);
+  const targetStat = fs.statSync(targetPath);
+
+  if (!sourceStat.isFile() || !targetStat.isFile()) {
+    return false;
+  }
+
+  if (sourceStat.size !== targetStat.size) {
+    return false;
+  }
+
+  return fs.readFileSync(sourcePath).equals(fs.readFileSync(targetPath));
+}
+
+function countSegments(relativePath) {
+  return relativePath.split(path.sep).length;
+}
+
+function sortPathsDeepFirst(paths) {
+  return [...paths].sort((left, right) => {
+    const depth = countSegments(right) - countSegments(left);
+    if (depth !== 0) {
+      return depth;
+    }
+    return right.localeCompare(left);
+  });
+}
+
+function collectManagedDirectories(relativeFilePaths) {
+  const directories = new Set([MANIFEST_DIR]);
+
+  for (const relativeFilePath of relativeFilePaths) {
+    let currentDir = path.dirname(relativeFilePath);
+
+    while (currentDir && currentDir !== '.') {
+      directories.add(currentDir);
+      currentDir = path.dirname(currentDir);
+    }
+  }
+
+  return sortPathsDeepFirst([...directories]);
+}
+
+module.exports = {
+  ensureDirectory,
+  writeFileAtomic,
+  writeJsonAtomic,
+  loadJsonFile,
+  validateSettingsStructure,
+  loadJsonFileForCleanup,
+  compareFileContents,
+  sortPathsDeepFirst,
+  collectManagedDirectories
+};

package/bin/install/hooks.js

@@ -0,0 +1,152 @@
+
+const path = require('path');
+const { HOOK_SPECS } = require('./constants');
+
+function buildHookSpecs(claudeBase, relativeHookDir) {
+  return HOOK_SPECS.map((group) => {
+    const commands = group.hooks.map((hook) => path.join(relativeHookDir, hook.file));
+    return {
+      event: group.event,
+      matcher: group.matcher,
+      commands,
+      hooks: group.hooks.map((hook) => ({
+        type: 'command',
+        command: path.join(claudeBase, relativeHookDir, hook.file),
+        timeout: hook.timeout
+      }))
+    };
+  });
+}
+
+function normalizeMatcher(value) {
+  return value || null;
+}
+
+function hookEntryMatchesSpec(entry, spec) {
+  if (normalizeMatcher(entry.matcher) !== normalizeMatcher(spec.matcher)) {
+    return false;
+  }
+
+  if (!Array.isArray(entry.hooks) || entry.hooks.length !== spec.hooks.length) {
+    return false;
+  }
+
+  return entry.hooks.every((hook, index) => {
+    const expected = spec.hooks[index];
+    return hook &&
+      hook.type === 'command' &&
+      typeof hook.command === 'string' &&
+      path.normalize(hook.command) === path.normalize(expected.command);
+  });
+}
+
+function normalizeHookCommand(command) {
+  return path.normalize(command);
+}
+
+function collectManagedHookCommands(specs) {
+  const commands = new Set();
+
+  for (const spec of specs) {
+    for (const hook of spec.hooks) {
+      if (hook && hook.type === 'command' && typeof hook.command === 'string') {
+        commands.add(normalizeHookCommand(hook.command));
+      }
+    }
+  }
+
+  return commands;
+}
+
+function hookEntryOwnedByCommands(entry, managedCommands) {
+  if (!Array.isArray(entry.hooks) || entry.hooks.length === 0) {
+    return false;
+  }
+
+  return entry.hooks.every((hook) => {
+    return hook &&
+      hook.type === 'command' &&
+      typeof hook.command === 'string' &&
+      managedCommands.has(normalizeHookCommand(hook.command));
+  });
+}
+
+function removeHookEntries(settings, specs) {
+  if (!settings.hooks) {
+    return false;
+  }
+
+  if (typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    throw new Error(
+      'Claude settings contain an invalid "hooks" value. ' +
+      'Expected an object of hook arrays.'
+    );
+  }
+
+  let changed = false;
+  const managedCommands = collectManagedHookCommands(specs);
+
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) {
+      throw new Error(
+        `Claude settings contain an invalid hook list for "${event}". ` +
+        'Expected an array.'
+      );
+    }
+
+    const eventSpecs = specs.filter((spec) => spec.event === event);
+    if (eventSpecs.length === 0) {
+      continue;
+    }
+
+    const nextEntries = entries.filter((entry) => {
+      const exactMatch = eventSpecs.some((spec) => hookEntryMatchesSpec(entry, spec));
+      return !(exactMatch || hookEntryOwnedByCommands(entry, managedCommands));
+    });
+
+    if (nextEntries.length !== entries.length) {
+      changed = true;
+    }
+
+    if (nextEntries.length === 0) {
+      delete settings.hooks[event];
+    } else {
+      settings.hooks[event] = nextEntries;
+    }
+  }
+
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  return changed;
+}
+
+function addHookEntries(settings, specs) {
+  if (specs.length === 0) {
+    return;
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  for (const spec of specs) {
+    if (!settings.hooks[spec.event]) {
+      settings.hooks[spec.event] = [];
+    }
+
+    const entry = { hooks: spec.hooks };
+    if (spec.matcher) {
+      entry.matcher = spec.matcher;
+    }
+
+    settings.hooks[spec.event].push(entry);
+  }
+}
+
+module.exports = {
+  buildHookSpecs,
+  removeHookEntries,
+  addHookEntries
+};