gentyr 1.3.0

package/cli/lib/state.js

@@ -0,0 +1,140 @@
+/**
+ * Sync state management for GENTYR.
+ *
+ * Manages the .claude/gentyr-state.json file that tracks what version/config
+ * was last synced, enabling fast-path detection in the SessionStart hook.
+ *
+ * @module state
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const STATE_FILE = 'gentyr-state.json';
+
+/**
+ * @typedef {Object} GentyrState
+ * @property {string} version - Framework version at last sync
+ * @property {string} configHash - SHA-256 of settings.json.template + .mcp.json.template
+ * @property {string} claudeMdHash - SHA-256 of CLAUDE.md.gentyr-section
+ * @property {string[]} agentList - List of framework agent filenames
+ * @property {number} stateFilesVersion - Schema version for pre-created state files
+ * @property {string} lastSync - ISO timestamp of last sync
+ * @property {string} installModel - 'npm' or 'legacy'
+ */
+
+/**
+ * Read the current sync state from a project.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @returns {GentyrState|null} The current state, or null if not found
+ */
+export function readState(projectDir) {
+  const statePath = path.join(projectDir, '.claude', STATE_FILE);
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write sync state to a project.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @param {GentyrState} state - The state to write
+ */
+export function writeState(projectDir, state) {
+  const statePath = path.join(projectDir, '.claude', STATE_FILE);
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+}
+
+/**
+ * Compute a hash of template files for change detection.
+ *
+ * @param {string} frameworkDir - Absolute path to the framework directory
+ * @returns {string} SHA-256 hex hash of concatenated template contents
+ */
+export function computeConfigHash(frameworkDir) {
+  const files = [
+    path.join(frameworkDir, '.claude', 'settings.json.template'),
+    path.join(frameworkDir, '.mcp.json.template'),
+  ];
+  const hash = crypto.createHash('sha256');
+  for (const file of files) {
+    try {
+      hash.update(fs.readFileSync(file, 'utf8'));
+    } catch {
+      hash.update('');
+    }
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * Compute a hash of the CLAUDE.md gentyr section template.
+ *
+ * @param {string} frameworkDir - Absolute path to the framework directory
+ * @returns {string} SHA-256 hex hash
+ */
+export function computeClaudeMdHash(frameworkDir) {
+  const sectionPath = path.join(frameworkDir, 'CLAUDE.md.gentyr-section');
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(sectionPath, 'utf8')).digest('hex');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Read the framework version from version.json.
+ *
+ * @param {string} frameworkDir - Absolute path to the framework directory
+ * @returns {string} The version string, or '0.0.0' if not found
+ */
+export function readFrameworkVersion(frameworkDir) {
+  try {
+    const vj = JSON.parse(fs.readFileSync(path.join(frameworkDir, 'version.json'), 'utf8'));
+    return vj.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Get the list of framework agent filenames.
+ *
+ * @param {string} frameworkDir - Absolute path to the framework directory
+ * @returns {string[]} Array of agent markdown filenames
+ */
+export function getFrameworkAgents(frameworkDir) {
+  const agentsDir = path.join(frameworkDir, '.claude', 'agents');
+  try {
+    return fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Current state files schema version */
+export const STATE_FILES_VERSION = 1;
+
+/**
+ * Build a complete state object for the current framework.
+ *
+ * @param {string} frameworkDir - Absolute path to the framework directory
+ * @param {string} installModel - 'npm' or 'legacy'
+ * @returns {GentyrState}
+ */
+export function buildState(frameworkDir, installModel) {
+  return {
+    version: readFrameworkVersion(frameworkDir),
+    configHash: computeConfigHash(frameworkDir),
+    claudeMdHash: computeClaudeMdHash(frameworkDir),
+    agentList: getFrameworkAgents(frameworkDir),
+    stateFilesVersion: STATE_FILES_VERSION,
+    lastSync: new Date().toISOString(),
+    installModel,
+  };
+}

package/cli/lib/symlinks.js

@@ -0,0 +1,260 @@
+/**
+ * Symlink creation helpers for GENTYR installation.
+ *
+ * @module symlinks
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Create a symlink, replacing existing if it points to a different target.
+ * If a real directory exists at the link path, backs it up.
+ *
+ * @param {string} target - Symlink target (relative path)
+ * @param {string} linkPath - Absolute path where the symlink should be created
+ * @param {object} [opts]
+ * @param {boolean} [opts.quiet] - Suppress log output
+ * @returns {boolean} true if a new symlink was created
+ */
+export function safeSymlink(target, linkPath, opts = {}) {
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isSymbolicLink()) {
+      const existing = fs.readlinkSync(linkPath);
+      if (existing === target) return false; // already correct
+      fs.unlinkSync(linkPath);
+    } else if (stat.isDirectory()) {
+      const backupPath = linkPath + '.backup';
+      if (!opts.quiet) console.log(`  Moving existing ${path.basename(linkPath)}/ to ${path.basename(linkPath)}.backup/`);
+      fs.renameSync(linkPath, backupPath);
+    } else {
+      fs.unlinkSync(linkPath);
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  fs.symlinkSync(target, linkPath);
+  return true;
+}
+
+/**
+ * Create directory symlinks for standard GENTYR shared resources.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @param {string} frameworkRel - Relative framework path ('node_modules/gentyr' or '.claude-framework')
+ */
+export function createDirectorySymlinks(projectDir, frameworkRel) {
+  const claudeDir = path.join(projectDir, '.claude');
+  fs.mkdirSync(claudeDir, { recursive: true });
+
+  const dirLinks = [
+    { name: 'commands', target: `../${frameworkRel}/.claude/commands` },
+    { name: 'hooks', target: `../${frameworkRel}/.claude/hooks` },
+    { name: 'mcp', target: `../${frameworkRel}/.claude/mcp` },
+    { name: 'docs', target: `../${frameworkRel}/docs/shared` },
+  ];
+
+  for (const { name, target } of dirLinks) {
+    const linkPath = path.join(claudeDir, name);
+    if (safeSymlink(target, linkPath)) {
+      console.log(`  Symlink: .claude/${name}`);
+    } else {
+      console.log(`  Symlink: .claude/${name} (already correct)`);
+    }
+  }
+}
+
+/**
+ * Create individual agent file symlinks.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @param {string} frameworkRel - Relative framework path
+ * @param {string[]} agents - List of agent filenames (e.g. ['investigator.md', ...])
+ * @param {object} [opts]
+ * @param {boolean} [opts.preserveProjectAgents] - Don't overwrite non-symlink agents
+ */
+export function createAgentSymlinks(projectDir, frameworkRel, agents, opts = {}) {
+  const agentsDir = path.join(projectDir, '.claude', 'agents');
+
+  // Handle legacy directory symlink
+  try {
+    const stat = fs.lstatSync(agentsDir);
+    if (stat.isSymbolicLink()) {
+      fs.unlinkSync(agentsDir);
+      console.log('  Removed legacy agents directory symlink');
+    }
+  } catch {}
+
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  // Back up conflicting project-specific agent files
+  if (opts.preserveProjectAgents) {
+    for (const agent of agents) {
+      const agentPath = path.join(agentsDir, agent);
+      try {
+        const stat = fs.lstatSync(agentPath);
+        if (!stat.isSymbolicLink()) {
+          const backupDir = path.join(projectDir, '.claude', 'agents.backup');
+          fs.mkdirSync(backupDir, { recursive: true });
+          fs.renameSync(agentPath, path.join(backupDir, agent));
+          console.log(`  Backed up existing ${agent}`);
+        }
+      } catch {}
+    }
+  }
+
+  let created = 0;
+  for (const agent of agents) {
+    const target = `../../${frameworkRel}/.claude/agents/${agent}`;
+    const linkPath = path.join(agentsDir, agent);
+    safeSymlink(target, linkPath, { quiet: true });
+    created++;
+  }
+  console.log(`  Symlink: .claude/agents/ (${created} framework agents)`);
+}
+
+/**
+ * Create reporter symlinks for test frameworks.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @param {string} frameworkRel - Relative framework path
+ */
+export function createReporterSymlinks(projectDir, frameworkRel) {
+  const reportersDir = path.join(projectDir, '.claude', 'reporters');
+  fs.mkdirSync(reportersDir, { recursive: true });
+
+  const reporters = [
+    { config: 'jest.config', name: 'jest-failure-reporter.js' },
+    { config: 'vitest.config', name: 'vitest-failure-reporter.js' },
+    { config: 'playwright.config', name: 'playwright-failure-reporter.js' },
+  ];
+
+  for (const { config, name } of reporters) {
+    // Check for config file with various extensions
+    const extensions = ['.js', '.ts', '.mjs'];
+    const hasConfig = extensions.some(ext =>
+      fs.existsSync(path.join(projectDir, config + ext))
+    );
+    if (hasConfig) {
+      const target = `../../${frameworkRel}/.claude/hooks/reporters/${name}`;
+      const linkPath = path.join(reportersDir, name);
+      safeSymlink(target, linkPath, { quiet: true });
+      console.log(`  Symlink: .claude/reporters/${name}`);
+    }
+  }
+
+  // Monorepo package reporters
+  const packagesDir = path.join(projectDir, 'packages');
+  if (fs.existsSync(packagesDir)) {
+    try {
+      for (const pkg of fs.readdirSync(packagesDir)) {
+        const pkgDir = path.join(packagesDir, pkg);
+        const hasVitest = ['.js', '.ts', '.mjs'].some(ext =>
+          fs.existsSync(path.join(pkgDir, 'vitest.config' + ext))
+        );
+        if (hasVitest) {
+          const pkgReporters = path.join(pkgDir, '.claude', 'reporters');
+          fs.mkdirSync(pkgReporters, { recursive: true });
+          const target = `../../../../${frameworkRel}/.claude/hooks/reporters/vitest-failure-reporter.js`;
+          safeSymlink(target, path.join(pkgReporters, 'vitest-failure-reporter.js'), { quiet: true });
+          console.log(`  Symlink: packages/${pkg}/.claude/reporters/vitest-failure-reporter.js`);
+        }
+      }
+    } catch {}
+  }
+}
+
+/**
+ * Remove all GENTYR symlinks from a project.
+ *
+ * @param {string} projectDir - Absolute path to the target project
+ * @param {string[]} agents - List of framework agent filenames
+ */
+export function removeSymlinks(projectDir, agents) {
+  const claudeDir = path.join(projectDir, '.claude');
+
+  // Remove directory symlinks
+  for (const name of ['commands', 'hooks', 'mcp', 'docs']) {
+    const linkPath = path.join(claudeDir, name);
+    try {
+      if (fs.lstatSync(linkPath).isSymbolicLink()) {
+        fs.unlinkSync(linkPath);
+        console.log(`  Removed: .claude/${name}`);
+      }
+    } catch {}
+
+    // Restore backups
+    const backupPath = linkPath + '.backup';
+    if (fs.existsSync(backupPath)) {
+      fs.renameSync(backupPath, linkPath);
+      console.log(`  Restored backup: .claude/${name}`);
+    }
+  }
+
+  // Remove agent symlinks
+  const agentsDir = path.join(claudeDir, 'agents');
+  try {
+    if (fs.lstatSync(agentsDir).isSymbolicLink()) {
+      // Legacy directory symlink
+      fs.unlinkSync(agentsDir);
+      console.log('  Removed: .claude/agents (legacy directory symlink)');
+    } else {
+      let removed = 0;
+      for (const agent of agents) {
+        const agentPath = path.join(agentsDir, agent);
+        try {
+          if (fs.lstatSync(agentPath).isSymbolicLink()) {
+            fs.unlinkSync(agentPath);
+            removed++;
+          }
+        } catch {}
+      }
+      if (removed > 0) console.log(`  Removed: ${removed} framework agent symlinks`);
+
+      // Remove dir if empty
+      try {
+        const remaining = fs.readdirSync(agentsDir);
+        if (remaining.length === 0) {
+          fs.rmdirSync(agentsDir);
+          console.log('  Removed empty .claude/agents/');
+        } else {
+          console.log(`  Preserved: ${remaining.length} project-specific agent(s)`);
+        }
+      } catch {}
+    }
+  } catch {}
+
+  // Restore agent backups
+  const agentBackup = path.join(claudeDir, 'agents.backup');
+  if (fs.existsSync(agentBackup)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+    for (const file of fs.readdirSync(agentBackup)) {
+      fs.renameSync(path.join(agentBackup, file), path.join(agentsDir, file));
+    }
+    try { fs.rmdirSync(agentBackup); } catch {}
+    console.log('  Restored agents from backup');
+  }
+
+  // Remove reporters
+  const reportersDir = path.join(claudeDir, 'reporters');
+  if (fs.existsSync(reportersDir)) {
+    fs.rmSync(reportersDir, { recursive: true });
+    console.log('  Removed: .claude/reporters/');
+  }
+
+  // Remove monorepo package reporters
+  const packagesDir = path.join(projectDir, 'packages');
+  if (fs.existsSync(packagesDir)) {
+    try {
+      for (const pkg of fs.readdirSync(packagesDir)) {
+        const pkgReporters = path.join(packagesDir, pkg, '.claude', 'reporters');
+        if (fs.existsSync(pkgReporters)) {
+          fs.rmSync(pkgReporters, { recursive: true });
+          console.log(`  Removed: packages/${pkg}/.claude/reporters/`);
+        }
+      }
+    } catch {}
+  }
+}