@dzhechkov/keysarium 1.0.0

package/src/commands/doctor.js

@@ -0,0 +1,469 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  green, red, yellow, cyan, bold, dim,
+  info, success, warn, error: logError,
+  fileExists, readJSON, readManifest,
+  MANIFEST_FILE,
+} = require('../utils');
+
+// ---------------------------------------------------------------------------
+// Check definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a single check. Returns { name, passed, detail, fix }.
+ */
+function check(name, fn) {
+  try {
+    const result = fn();
+    return {
+      name,
+      passed: result.passed,
+      detail: result.detail || '',
+      fix: result.fix || '',
+    };
+  } catch (err) {
+    return {
+      name,
+      passed: false,
+      detail: `Exception: ${err.message}`,
+      fix: 'Investigate the error above.',
+    };
+  }
+}
+
+/**
+ * Check 1: Verify every file in manifest exists on disk.
+ */
+function checkFilesExist(manifest, targetDir) {
+  return check('Files exist', () => {
+    const files = manifest.files || [];
+    const missing = [];
+
+    for (const relPath of files) {
+      const absPath = path.join(targetDir, relPath);
+      if (!fileExists(absPath)) {
+        missing.push(relPath);
+      }
+    }
+
+    if (missing.length === 0) {
+      return {
+        passed: true,
+        detail: `All ${files.length} manifest files present`,
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `${missing.length} file(s) missing: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? '...' : ''}`,
+      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing files.`,
+    };
+  });
+}
+
+/**
+ * Check 2: CLAUDE.md contains key sections.
+ */
+function checkClaudeMd(targetDir) {
+  return check('CLAUDE.md valid', () => {
+    const claudePath = path.join(targetDir, 'CLAUDE.md');
+
+    if (!fileExists(claudePath)) {
+      return {
+        passed: false,
+        detail: 'CLAUDE.md not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} or ${cyan('@dzhechko/keysarium init --force')} to restore.`,
+      };
+    }
+
+    const content = fs.readFileSync(claudePath, 'utf8');
+    const requiredSections = ['Pipeline', 'Skills'];
+    const missingSections = [];
+
+    for (const section of requiredSections) {
+      // Case-insensitive search for the section heading or keyword
+      if (!content.toLowerCase().includes(section.toLowerCase())) {
+        missingSections.push(section);
+      }
+    }
+
+    if (missingSections.length === 0) {
+      return {
+        passed: true,
+        detail: 'Contains required sections (Pipeline, Skills)',
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `Missing sections: ${missingSections.join(', ')}`,
+      fix: 'Restore CLAUDE.md from the template or add the missing sections manually.',
+    };
+  });
+}
+
+/**
+ * Check 3: Each skill directory has SKILL.md.
+ */
+function checkSkillsComplete(targetDir) {
+  return check('Skills complete', () => {
+    const skillsDir = path.join(targetDir, '.claude', 'skills');
+
+    if (!fileExists(skillsDir)) {
+      return {
+        passed: false,
+        detail: '.claude/skills/ directory not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore skills.`,
+      };
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(skillsDir);
+    } catch {
+      return {
+        passed: false,
+        detail: 'Cannot read .claude/skills/ directory',
+        fix: 'Check directory permissions.',
+      };
+    }
+
+    const skillDirs = entries.filter((entry) => {
+      const entryPath = path.join(skillsDir, entry);
+      try {
+        return fs.statSync(entryPath).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+
+    const missingSkillMd = [];
+    for (const dir of skillDirs) {
+      const skillMdPath = path.join(skillsDir, dir, 'SKILL.md');
+      if (!fileExists(skillMdPath)) {
+        missingSkillMd.push(dir);
+      }
+    }
+
+    if (missingSkillMd.length === 0) {
+      return {
+        passed: true,
+        detail: `${skillDirs.length} skill(s), all have SKILL.md`,
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `Missing SKILL.md in: ${missingSkillMd.join(', ')}`,
+      fix: 'Each skill directory must contain a SKILL.md file. Run update to restore.',
+    };
+  });
+}
+
+/**
+ * Check 4: All 11 command .md files are present.
+ */
+function checkCommandsPresent(targetDir) {
+  return check('Commands present', () => {
+    const commandsDir = path.join(targetDir, '.claude', 'commands');
+    const expectedCommands = [
+      'casarium.md',
+      'new-research.md',
+      'parallel-research.md',
+      'discovery.md',
+      'explore-case.md',
+      'research.md',
+      'cjm-prototype.md',
+      'solve.md',
+      'architecture-phase.md',
+      'presentation.md',
+      'harvest.md',
+    ];
+
+    if (!fileExists(commandsDir)) {
+      return {
+        passed: false,
+        detail: '.claude/commands/ directory not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore commands.`,
+      };
+    }
+
+    const missing = [];
+    for (const cmd of expectedCommands) {
+      if (!fileExists(path.join(commandsDir, cmd))) {
+        missing.push(cmd);
+      }
+    }
+
+    if (missing.length === 0) {
+      return {
+        passed: true,
+        detail: `All ${expectedCommands.length} command files present`,
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `Missing ${missing.length} command(s): ${missing.join(', ')}`,
+      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing commands.`,
+    };
+  });
+}
+
+/**
+ * Check 5: All 7 rule .md files are present.
+ */
+function checkRulesPresent(targetDir) {
+  return check('Rules present', () => {
+    const rulesDir = path.join(targetDir, '.claude', 'rules');
+    const expectedRules = [
+      'agent-swarm.md',
+      'anti-patterns.md',
+      'checkpoint-protocol.md',
+      'domain-specific.md',
+      'file-conventions.md',
+      'modular-reuse.md',
+      'research-quality.md',
+    ];
+
+    if (!fileExists(rulesDir)) {
+      return {
+        passed: false,
+        detail: '.claude/rules/ directory not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore rules.`,
+      };
+    }
+
+    const missing = [];
+    for (const rule of expectedRules) {
+      if (!fileExists(path.join(rulesDir, rule))) {
+        missing.push(rule);
+      }
+    }
+
+    if (missing.length === 0) {
+      return {
+        passed: true,
+        detail: `All ${expectedRules.length} rule files present`,
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `Missing ${missing.length} rule(s): ${missing.join(', ')}`,
+      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing rules.`,
+    };
+  });
+}
+
+/**
+ * Check 6: All 5 agent .md files are present.
+ */
+function checkAgentsPresent(targetDir) {
+  return check('Agents present', () => {
+    const agentsDir = path.join(targetDir, '.claude', 'agents');
+
+    if (!fileExists(agentsDir)) {
+      return {
+        passed: false,
+        detail: '.claude/agents/ directory not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore agents.`,
+      };
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(agentsDir);
+    } catch {
+      return {
+        passed: false,
+        detail: 'Cannot read .claude/agents/ directory',
+        fix: 'Check directory permissions.',
+      };
+    }
+
+    const mdFiles = entries.filter((e) => e.endsWith('.md'));
+
+    if (mdFiles.length >= 5) {
+      return {
+        passed: true,
+        detail: `${mdFiles.length} agent file(s) present`,
+      };
+    }
+
+    return {
+      passed: false,
+      detail: `Only ${mdFiles.length}/5 agent files found`,
+      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing agent templates.`,
+    };
+  });
+}
+
+/**
+ * Check 7: .claude/settings.json is valid JSON.
+ */
+function checkSettingsValid(targetDir) {
+  return check('Settings valid', () => {
+    const settingsPath = path.join(targetDir, '.claude', 'settings.json');
+
+    if (!fileExists(settingsPath)) {
+      return {
+        passed: false,
+        detail: '.claude/settings.json not found',
+        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore settings.`,
+      };
+    }
+
+    const data = readJSON(settingsPath);
+    if (data === null) {
+      return {
+        passed: false,
+        detail: '.claude/settings.json contains invalid JSON',
+        fix: 'Fix the JSON syntax in .claude/settings.json or restore from template.',
+      };
+    }
+
+    return {
+      passed: true,
+      detail: 'Valid JSON',
+    };
+  });
+}
+
+/**
+ * Check 8: researches/ directory exists.
+ */
+function checkResearchDir(targetDir) {
+  return check('Research dir', () => {
+    const researchesDir = path.join(targetDir, 'researches');
+
+    if (!fileExists(researchesDir)) {
+      return {
+        passed: false,
+        detail: 'researches/ directory not found',
+        fix: 'Create the directory: mkdir researches',
+      };
+    }
+
+    try {
+      const stat = fs.statSync(researchesDir);
+      if (!stat.isDirectory()) {
+        return {
+          passed: false,
+          detail: 'researches exists but is not a directory',
+          fix: 'Remove the file and create a directory: rm researches && mkdir researches',
+        };
+      }
+    } catch {
+      return {
+        passed: false,
+        detail: 'Cannot stat researches/',
+        fix: 'Check filesystem permissions.',
+      };
+    }
+
+    return {
+      passed: true,
+      detail: 'Directory exists',
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+
+/**
+ * `@dzhechko/keysarium doctor` — Health check for the toolkit installation.
+ *
+ * @param {object} options
+ * @param {string}  options.targetDir — Project root directory
+ */
+async function run(options) {
+  const { targetDir } = options;
+  const manifestPath = path.join(targetDir, MANIFEST_FILE);
+
+  // ── a) Check manifest exists ───────────────────────────────────────────
+  if (!fileExists(manifestPath)) {
+    logError('Keysarium is not installed in this directory.');
+    info(`Run ${cyan('@dzhechko/keysarium init')} to install.`);
+    process.exit(1);
+  }
+
+  const manifest = readManifest(targetDir);
+  if (!manifest) {
+    logError('Failed to read .keysarium.json — file may be corrupted.');
+    process.exit(1);
+  }
+
+  console.log('');
+  info(bold(`Running health checks for @dzhechko/keysarium v${manifest.version}...`));
+  console.log('');
+
+  // ── b) Run all checks ─────────────────────────────────────────────────
+  const results = [
+    checkFilesExist(manifest, targetDir),
+    checkClaudeMd(targetDir),
+    checkSkillsComplete(targetDir),
+    checkCommandsPresent(targetDir),
+    checkRulesPresent(targetDir),
+    checkAgentsPresent(targetDir),
+    checkSettingsValid(targetDir),
+    checkResearchDir(targetDir),
+  ];
+
+  // ── c) Display results ─────────────────────────────────────────────────
+  let passedCount = 0;
+  const failures = [];
+
+  for (const result of results) {
+    const icon = result.passed ? green('\u2713') : red('\u2717');
+    const statusColor = result.passed ? green : red;
+    const detailStr = result.detail ? dim(` — ${result.detail}`) : '';
+
+    console.log(`  ${icon} ${statusColor(result.name)}${detailStr}`);
+
+    if (result.passed) {
+      passedCount++;
+    } else {
+      failures.push(result);
+    }
+  }
+
+  // ── d) Summary ─────────────────────────────────────────────────────────
+  console.log('');
+  const total = results.length;
+
+  if (passedCount === total) {
+    success(bold(`${passedCount}/${total} checks passed — installation is healthy!`));
+    console.log('');
+    process.exit(0);
+  }
+
+  warn(bold(`${passedCount}/${total} checks passed`));
+  console.log('');
+
+  // ── e) Show fix suggestions ────────────────────────────────────────────
+  console.log(bold('Fix suggestions:'));
+  console.log('');
+
+  for (const failure of failures) {
+    console.log(`  ${red('\u2717')} ${bold(failure.name)}`);
+    if (failure.detail) {
+      console.log(`    ${dim(failure.detail)}`);
+    }
+    if (failure.fix) {
+      console.log(`    ${yellow('Fix:')} ${failure.fix}`);
+    }
+    console.log('');
+  }
+
+  process.exit(1);
+}
+
+module.exports = run;
+module.exports.run = run;

package/src/commands/init.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  green, yellow, cyan, bold, dim,
+  info, success, warn, error: logError, step,
+  copyDirRecursive, fileExists, readJSON,
+  ensureDir, getRelativePaths,
+  createManifest, writeManifest, getTemplatesDir,
+  COMPONENTS, MANIFEST_FILE,
+} = require('../utils');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine which component keys to install based on CLI flags.
+ *   Default:  core group + lib
+ *   --minimal: core group only (no lib)
+ *   --with-docs: add docs group
+ */
+function resolveComponents(options) {
+  const { minimal, withDocs } = options;
+  const coreKeys = ['skills', 'commands', 'rules', 'agents', 'hooks', 'claude_md', 'harvest'];
+  const keys = [...coreKeys];
+
+  if (!minimal) {
+    keys.push('lib');
+  }
+
+  if (withDocs) {
+    keys.push('docs');
+  }
+
+  return keys.filter((k) => COMPONENTS[k]);
+}
+
+/**
+ * Copy a single component from templates to the target directory.
+ * Returns array of relative file paths that were installed.
+ */
+function installComponent(comp, templatesDir, targetDir) {
+  const src = path.join(templatesDir, comp.src);
+  const dest = path.join(targetDir, comp.src);
+
+  if (!fileExists(src)) {
+    warn(`Template source not found: ${comp.src} — skipping.`);
+    return [];
+  }
+
+  if (comp.isFile) {
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+    return [comp.src];
+  }
+
+  copyDirRecursive(src, dest);
+  return getRelativePaths(dest).map((rel) => path.join(comp.src, rel));
+}
+
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+
+/**
+ * `@dzhechko/keysarium init` — Install the toolkit into the target project.
+ *
+ * @param {object} options
+ * @param {boolean} options.minimal   — Install only core (no lib)
+ * @param {boolean} options.force     — Overwrite existing installation
+ * @param {boolean} options.withDocs  — Include docs/ directory
+ * @param {boolean} options.dryRun    — Preview without writing anything
+ * @param {string}  options.targetDir — Destination project root
+ */
+async function run(options) {
+  const { force, dryRun, targetDir } = options;
+  const manifestPath = path.join(targetDir, MANIFEST_FILE);
+
+  // ── a) Check for existing installation ──────────────────────────────────
+  if (fileExists(manifestPath)) {
+    if (!force) {
+      warn('Keysarium is already installed in this directory.');
+      info(`Run ${cyan('@dzhechko/keysarium update')} to update, or use ${yellow('--force')} to overwrite.`);
+      process.exit(1);
+    }
+    warn('Existing installation found — overwriting (--force).');
+  }
+
+  // ── b) Determine components ─────────────────────────────────────────────
+  const componentKeys = resolveComponents(options);
+  const templatesDir = getTemplatesDir();
+
+  // ── c) Show plan ────────────────────────────────────────────────────────
+  console.log('');
+  info(bold('Installation plan:'));
+  console.log('');
+
+  for (const key of componentKeys) {
+    const comp = COMPONENTS[key];
+    console.log(`  ${green('+')} ${comp.label}`);
+  }
+
+  console.log('');
+
+  if (dryRun) {
+    warn('Dry run — no files were written.');
+    process.exit(0);
+  }
+
+  // ── d) Install components ───────────────────────────────────────────────
+  const totalComponents = componentKeys.length;
+  const installedFiles = [];
+
+  for (let i = 0; i < totalComponents; i++) {
+    const key = componentKeys[i];
+    const comp = COMPONENTS[key];
+    step(i + 1, totalComponents, `Installing ${comp.label}...`);
+
+    const files = installComponent(comp, templatesDir, targetDir);
+    installedFiles.push(...files);
+  }
+
+  // ── e) Create researches/ directory ─────────────────────────────────────
+  const researchesDir = path.join(targetDir, 'researches');
+  ensureDir(researchesDir);
+  const gitkeepPath = path.join(researchesDir, '.gitkeep');
+  if (!fileExists(gitkeepPath)) {
+    fs.writeFileSync(gitkeepPath, '', 'utf8');
+  }
+  info('Created researches/ directory with .gitkeep');
+
+  // ── f) Write manifest ──────────────────────────────────────────────────
+  const pkgPath = path.resolve(__dirname, '../../package.json');
+  const pkg = readJSON(pkgPath);
+  const version = pkg ? pkg.version : '0.0.0';
+
+  const manifest = createManifest(version, componentKeys, installedFiles.sort());
+  writeManifest(targetDir, manifest);
+  info('Created .keysarium.json manifest');
+
+  // ── g) Success summary ─────────────────────────────────────────────────
+  console.log('');
+  success(bold('Installation complete!'));
+  console.log('');
+
+  console.log(bold('Installed components:'));
+  for (const key of componentKeys) {
+    const comp = COMPONENTS[key];
+    console.log(`  ${green('\u2713')} ${comp.label}`);
+  }
+
+  console.log('');
+  console.log(bold('Next steps:'));
+  console.log(`  1. Open ${cyan('Claude Code')} in this directory`);
+  console.log(`  2. Run ${cyan('/casarium [your case description]')}`);
+  console.log(`  3. Follow the 7-phase pipeline`);
+  console.log('');
+  console.log(bold('Available commands:'));
+  console.log(`  ${cyan('/casarium')}          ${dim('\u2014 Full pipeline')}`);
+  console.log(`  ${cyan('/new-research')}      ${dim('\u2014 New research')}`);
+  console.log(`  ${cyan('/parallel-research')} ${dim('\u2014 Multiple cases in parallel')}`);
+  console.log(`  ${cyan('/harvest')}           ${dim('\u2014 Extract knowledge')}`);
+  console.log('');
+
+  process.exit(0);
+}
+
+module.exports = run;
+module.exports.run = run;