@hanzlaa/rcode 2.1.0

package/cli/context.js

@@ -0,0 +1,213 @@
+/**
+ * rihal-code context — inspect and refresh the .rihal/ memory bank freshness.
+ *
+ * The memory bank (.rihal/context/active.md + project-brief.md) is what
+ * every Rihal workflow reads at runtime. If it goes stale, agents silently
+ * work from outdated assumptions. This command makes staleness visible.
+ *
+ * Usage:
+ *   rihal-code context                   show staleness report (default)
+ *   rihal-code context --check           exit non-zero if stale (for CI/hooks)
+ *   rihal-code context --refresh         write fresh fingerprint after a manual scan
+ *   rihal-code context --install-hook    opt-in post-commit git hook that
+ *                                         prints a warning when stale
+ *
+ * The refresh does NOT rewrite active.md or project-brief.md — that's
+ * /rihal:init's job (the scan requires an LLM). --refresh just stores the
+ * current fingerprint so the next check sees things as fresh.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  computeFingerprint,
+  writeFingerprint,
+  checkStaleness,
+  commitsBetween,
+  STALE_THRESHOLDS,
+} = require('./lib/memory-bank.cjs');
+
+function parseArgs(args) {
+  const opts = { check: false, refresh: false, installHook: false };
+  for (const arg of args) {
+    if (arg === '--check') opts.check = true;
+    else if (arg === '--refresh') opts.refresh = true;
+    else if (arg === '--install-hook') opts.installHook = true;
+    else {
+      console.error(`Unknown flag: ${arg}`);
+      console.error(`Usage: rihal-code context [--check|--refresh|--install-hook]`);
+      process.exit(1);
+    }
+  }
+  return opts;
+}
+
+function ensureRihalDir(cwd) {
+  if (!fs.existsSync(path.join(cwd, '.rihal'))) {
+    console.error(`❌ No .rihal/ directory found in ${cwd}`);
+    console.error(`   Run 'rihal-code install' first.`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Print the full staleness report to stdout. Always exits 0 — use --check
+ * for exit code semantics.
+ */
+function printReport(cwd) {
+  const report = checkStaleness(cwd);
+
+  const symbol =
+    report.status === 'fresh'
+      ? '✓'
+      : report.status === 'stale'
+      ? '⚠'
+      : '✗';
+  const statusLabel = report.status.toUpperCase();
+
+  console.log(`\n🧠 Memory bank status: ${symbol} ${statusLabel}\n`);
+
+  if (report.reasons.length > 0) {
+    console.log(`   Reasons:`);
+    for (const reason of report.reasons) {
+      console.log(`     • ${reason}`);
+    }
+    console.log();
+  }
+
+  console.log(`   Context files:`);
+  const activeMark = report.context_files.active ? '✓' : '✗';
+  const briefMark = report.context_files.brief ? '✓' : '✗';
+  console.log(`     ${activeMark} .rihal/context/active.md`);
+  console.log(`     ${briefMark} .rihal/context/project-brief.md`);
+  console.log();
+
+  if (report.stored) {
+    console.log(`   Last init:  ${report.stored.timestamp || 'unknown'}`);
+    if (report.stored.git_head) {
+      const shortHead = report.stored.git_head.slice(0, 7);
+      const branch = report.stored.git_branch || 'detached';
+      console.log(`               ${shortHead} on ${branch}`);
+    }
+    if (report.stored.manifest_name) {
+      console.log(`               ${report.stored.manifest_name} (${report.stored.manifest_hash})`);
+    }
+  } else {
+    console.log(`   Last init:  (never)`);
+  }
+
+  console.log(`   Current:    ${report.current.timestamp}`);
+  if (report.current.git_head) {
+    const shortHead = report.current.git_head.slice(0, 7);
+    const branch = report.current.git_branch || 'detached';
+    console.log(`               ${shortHead} on ${branch}`);
+  }
+  if (report.current.manifest_name) {
+    console.log(`               ${report.current.manifest_name} (${report.current.manifest_hash})`);
+  }
+
+  // Commits since last init (informational)
+  if (report.stored?.git_head && report.current.git_head) {
+    const n = commitsBetween(cwd, report.stored.git_head, report.current.git_head);
+    if (n !== null) {
+      console.log(`\n   Commits since init: ${n} (threshold: ${STALE_THRESHOLDS.commitsSinceInit})`);
+    }
+  }
+
+  console.log();
+
+  if (report.status !== 'fresh') {
+    console.log(`   ➡ Refresh with: /rihal:init (in your editor)`);
+    console.log();
+  }
+}
+
+/**
+ * --refresh: recompute and save the fingerprint to .rihal/state.json.
+ * Only use this when you know the memory bank was actually refreshed
+ * (e.g. by /rihal:init running end-to-end). Does NOT rewrite context files.
+ */
+function doRefresh(cwd) {
+  ensureRihalDir(cwd);
+  const fp = writeFingerprint(cwd);
+  console.log(`\n✅ Fingerprint saved to .rihal/state.json`);
+  console.log(`   git:       ${fp.git_head ? fp.git_head.slice(0, 7) : '(no git)'}`);
+  console.log(`   manifest:  ${fp.manifest_name || '(none)'}`);
+  console.log(`   structure: ${fp.structure_dirs.length} top-level dirs`);
+  console.log();
+}
+
+/**
+ * --install-hook: write .git/hooks/post-commit that prints a staleness
+ * warning after each commit. Opt-in, does not auto-refresh.
+ */
+function installHook(cwd) {
+  const gitDir = path.join(cwd, '.git');
+  if (!fs.existsSync(gitDir)) {
+    console.error(`❌ Not a git repository (no .git/ found).`);
+    console.error(`   The post-commit hook requires git.`);
+    process.exit(1);
+  }
+
+  const hooksDir = path.join(gitDir, 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, 'post-commit');
+
+  const hookContent = `#!/bin/sh
+# Rihal Code — memory bank freshness check
+# Installed by: rihal-code context --install-hook
+# Non-blocking: prints a one-line warning if the memory bank is stale.
+if command -v rihal-code >/dev/null 2>&1; then
+  output=$(rihal-code context --check 2>&1)
+  if [ $? -ne 0 ]; then
+    echo ""
+    echo "⚠ Rihal memory bank is stale — run /rihal:init in your editor to refresh."
+    echo "   $(echo "$output" | grep '•' | head -1 | sed 's/^ *//')"
+  fi
+fi
+`;
+
+  // Don't clobber an existing hook without asking
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf8');
+    if (existing.includes('Rihal Code — memory bank freshness')) {
+      console.log(`✓ post-commit hook already installed at ${hookPath}`);
+      return;
+    }
+    console.error(`❌ A post-commit hook already exists at ${hookPath}`);
+    console.error(`   Refusing to overwrite. Merge manually or remove the existing hook first.`);
+    process.exit(1);
+  }
+
+  fs.writeFileSync(hookPath, hookContent);
+  fs.chmodSync(hookPath, 0o755);
+  console.log(`✅ Installed post-commit hook at ${hookPath}`);
+  console.log(`   After each commit, you'll see a warning if the memory bank goes stale.`);
+  console.log(`   To remove: rm ${hookPath}`);
+}
+
+module.exports = function context(args) {
+  const cwd = process.cwd();
+  const opts = parseArgs(args);
+
+  if (opts.installHook) {
+    installHook(cwd);
+    return;
+  }
+
+  if (opts.refresh) {
+    doRefresh(cwd);
+    return;
+  }
+
+  // Default / --check: need .rihal/ to exist
+  ensureRihalDir(cwd);
+  printReport(cwd);
+
+  if (opts.check) {
+    const report = checkStaleness(cwd);
+    if (report.status !== 'fresh') {
+      process.exit(1);
+    }
+  }
+};

package/cli/dashboard.js

@@ -0,0 +1,38 @@
+/**
+ * rihal-code dashboard — start the Diwan view-only dashboard
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+module.exports = function dashboard(args, { packageRoot }) {
+  const serverPath = path.join(packageRoot, 'server/dashboard.js');
+  const cwd = process.cwd();
+  const rihalDir = path.join(cwd, '.rihal');
+
+  console.log(`\n🕌 Starting Diwan dashboard...`);
+  console.log(`   Scanning: ${rihalDir}`);
+
+  // Fork the dashboard process with RIHAL_DIR pointing at the user's current project
+  const proc = spawn('node', [serverPath], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      RIHAL_DIR: rihalDir,
+    },
+  });
+
+  proc.on('error', (err) => {
+    console.error('Failed to start dashboard:', err.message);
+    process.exit(1);
+  });
+
+  // Graceful shutdown
+  const shutdown = () => {
+    console.log('\nStopping dashboard...');
+    proc.kill('SIGTERM');
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+};

package/cli/digest.js

@@ -0,0 +1,66 @@
+/**
+ * rihal-code digest — print compact agent digests
+ *
+ * Resolution order for a specific agent:
+ *   1. rihal/digests/<name>.md            (curated 20-line digest)
+ *   2. rihal/agents/rihal-<name>.md       (fallback: full agent file)
+ *
+ * Accepts both `sadiq` and `rihal-sadiq` as input (rihal- prefix stripped).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function normalize(name) {
+  return name.replace(/^rihal-/, '');
+}
+
+function listAvailable(digestDir, agentsDir) {
+  const digestNames = fs.existsSync(digestDir)
+    ? fs.readdirSync(digestDir).filter((f) => f.endsWith('.md') && f !== 'README.md').map((f) => f.replace('.md', ''))
+    : [];
+  const agentNames = fs.existsSync(agentsDir)
+    ? fs.readdirSync(agentsDir)
+        .filter((f) => f.endsWith('.md') && f.startsWith('rihal-'))
+        .map((f) => f.replace(/^rihal-/, '').replace('.md', ''))
+    : [];
+  return Array.from(new Set([...digestNames, ...agentNames])).sort();
+}
+
+function resolveAgentFile(name, digestDir, agentsDir) {
+  const digestFile = path.join(digestDir, `${name}.md`);
+  if (fs.existsSync(digestFile)) return { file: digestFile, source: 'digest' };
+  const agentFile = path.join(agentsDir, `rihal-${name}.md`);
+  if (fs.existsSync(agentFile)) return { file: agentFile, source: 'agent' };
+  return null;
+}
+
+module.exports = function digest(args, { packageRoot }) {
+  const digestDir = path.join(packageRoot, 'rihal/digests');
+  const agentsDir = path.join(packageRoot, 'rihal/agents');
+  const specificAgent = args[0];
+
+  if (specificAgent) {
+    const name = normalize(specificAgent);
+    const resolved = resolveAgentFile(name, digestDir, agentsDir);
+    if (!resolved) {
+      console.error(`No digest or agent found for: ${specificAgent}`);
+      console.error(`Available: ${listAvailable(digestDir, agentsDir).join(', ')}`);
+      process.exit(1);
+    }
+    if (resolved.source === 'agent') {
+      console.log(`# (fallback: full agent file — no curated digest exists)\n`);
+    }
+    console.log(fs.readFileSync(resolved.file, 'utf8'));
+    return;
+  }
+
+  const names = listAvailable(digestDir, agentsDir);
+  console.log(`\n🕌 All Rihal Code Agent Digests\n`);
+  for (const name of names) {
+    const resolved = resolveAgentFile(name, digestDir, agentsDir);
+    if (!resolved) continue;
+    console.log(fs.readFileSync(resolved.file, 'utf8'));
+    console.log('\n' + '═'.repeat(80) + '\n');
+  }
+};

package/cli/doctor.js

@@ -0,0 +1,283 @@
+/**
+ * rihal-code doctor — preflight + compliance checks
+ *
+ * Two sections:
+ *   1. Preflight — environment checks that affect whether install/sync will work
+ *      (node version, writable .rihal/, model-profiles.json validity, optional
+ *      git/gh availability, agent manifest drift)
+ *   2. Package compliance — 5-component skill standard on the package source
+ *
+ * Exit codes:
+ *   0 — everything green (some warn-only items may still have printed ⚠)
+ *   1 — any hard failure (preflight BLOCK or compliance failures)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { verifyInstall, formatReport } = require('./lib/manifest.cjs');
+const { checkStaleness } = require('./lib/memory-bank.cjs');
+
+// ---------- Shared helpers ----------
+
+function findSkillFiles(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findSkillFiles(full));
+    } else if (entry.isFile() && entry.name === 'SKILL.md') {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function checkCompliance(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const missing = [];
+  if (!/^name:/m.test(content)) missing.push('name');
+  if (!/^description:/m.test(content)) missing.push('description');
+  if (!/^## Output Format/m.test(content)) missing.push('Output Format');
+  if (!/^## Examples/m.test(content)) missing.push('Examples');
+  return missing;
+}
+
+function isWritable(dir) {
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandAvailable(cmd) {
+  const result = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+// ---------- Preflight checks ----------
+
+/**
+ * Each check returns { label, status, message }.
+ * status ∈ 'ok' | 'warn' | 'fail'.
+ *
+ * ok   — no output beyond the ✓
+ * warn — optional capability missing; non-fatal
+ * fail — hard problem; exits non-zero
+ */
+function runPreflight(cwd, packageRoot) {
+  const checks = [];
+
+  // 1. Node version ≥ 18 (from package.json engines)
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split('.')[0], 10);
+  checks.push({
+    label: 'Node.js ≥ 18',
+    status: major >= 18 ? 'ok' : 'fail',
+    message: `v${nodeVersion}${major < 18 ? ' — upgrade to 18 LTS or newer' : ''}`,
+  });
+
+  // 2. .rihal/ state directory — only check if project is initialized
+  const rihalDir = path.join(cwd, '.rihal');
+  if (fs.existsSync(rihalDir)) {
+    checks.push({
+      label: '.rihal/ writable',
+      status: isWritable(rihalDir) ? 'ok' : 'fail',
+      message: rihalDir,
+    });
+  } else {
+    checks.push({
+      label: '.rihal/ state',
+      status: 'warn',
+      message: 'not initialized in this directory (run `rihal-code install`)',
+    });
+  }
+
+  // 3. Package model-profiles.json parses and has expected profiles
+  const profilesPath = path.join(packageRoot, 'rihal/config/model-profiles.json');
+  if (fs.existsSync(profilesPath)) {
+    try {
+      const profiles = JSON.parse(fs.readFileSync(profilesPath, 'utf8'));
+      const expected = ['quality', 'balanced', 'budget', 'inherit'];
+      const names = Object.keys(profiles.profiles || profiles);
+      const missing = expected.filter((p) => !names.includes(p));
+      if (missing.length === 0) {
+        checks.push({
+          label: 'model-profiles.json',
+          status: 'ok',
+          message: `${names.length} profiles (${names.join(', ')})`,
+        });
+      } else {
+        checks.push({
+          label: 'model-profiles.json',
+          status: 'fail',
+          message: `missing expected profiles: ${missing.join(', ')}`,
+        });
+      }
+    } catch (e) {
+      checks.push({
+        label: 'model-profiles.json',
+        status: 'fail',
+        message: `invalid JSON: ${e.message}`,
+      });
+    }
+  } else {
+    checks.push({
+      label: 'model-profiles.json',
+      status: 'fail',
+      message: 'missing from package',
+    });
+  }
+
+  // 4. git availability — warn-only (many features don't need it)
+  checks.push({
+    label: 'git CLI',
+    status: commandAvailable('git') ? 'ok' : 'warn',
+    message: commandAvailable('git') ? 'available' : 'not found (some features disabled)',
+  });
+
+  // 5. gh availability — warn-only (only github-sync needs it)
+  checks.push({
+    label: 'gh CLI',
+    status: commandAvailable('gh') ? 'ok' : 'warn',
+    message: commandAvailable('gh')
+      ? 'available (github-sync ready)'
+      : 'not found (github-sync unavailable)',
+  });
+
+  // 6. Agent manifest drift (only if .rihal/ is initialized — indicates installed editors)
+  if (fs.existsSync(rihalDir)) {
+    const editors = [];
+    if (fs.existsSync(path.join(cwd, '.claude/skills'))) editors.push('claude');
+    if (fs.existsSync(path.join(cwd, '.cursor/rules'))) editors.push('cursor');
+    if (fs.existsSync(path.join(cwd, '.windsurf/rules'))) editors.push('windsurf');
+    if (fs.existsSync(path.join(cwd, '.antigravity/agents'))) editors.push('antigravity');
+
+    if (editors.length > 0) {
+      const { reports, hasDrift } = verifyInstall(cwd, packageRoot, editors);
+      if (hasDrift) {
+        checks.push({
+          label: 'Agent manifest',
+          status: 'fail',
+          message: `drift detected across ${editors.join(', ')}`,
+          detail: formatReport(reports),
+        });
+      } else {
+        const totals = reports
+          .map((r) => `${r.editor}:${r.installedCount}`)
+          .join(' ');
+        checks.push({
+          label: 'Agent manifest',
+          status: 'ok',
+          message: totals,
+        });
+      }
+    }
+
+    // 7. Memory bank freshness (warn-only — stale memory bank doesn't
+    // break anything, it just degrades answer quality over time).
+    const staleness = checkStaleness(cwd);
+    if (staleness.status === 'fresh') {
+      checks.push({
+        label: 'Memory bank',
+        status: 'ok',
+        message: 'fresh',
+      });
+    } else if (staleness.status === 'never') {
+      checks.push({
+        label: 'Memory bank',
+        status: 'warn',
+        message: 'never initialized (run /rihal:init to populate)',
+      });
+    } else {
+      checks.push({
+        label: 'Memory bank',
+        status: 'warn',
+        message: `STALE — ${staleness.reasons[0]}${staleness.reasons.length > 1 ? ` (+${staleness.reasons.length - 1} more)` : ''} — run /rihal:init`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function printChecks(checks) {
+  let failures = 0;
+  for (const c of checks) {
+    const symbol = c.status === 'ok' ? '✓' : c.status === 'warn' ? '⚠' : '✗';
+    console.log(`   ${symbol} ${c.label.padEnd(22)} ${c.message}`);
+    if (c.detail) {
+      console.log(c.detail);
+    }
+    if (c.status === 'fail') failures++;
+  }
+  return failures;
+}
+
+// ---------- Package compliance ----------
+
+function runCompliance(packageRoot) {
+  const skillDirs = [
+    path.join(packageRoot, 'rihal/skills/agents'),
+    path.join(packageRoot, 'rihal/skills/actions'),
+  ];
+
+  let totalSkills = 0;
+  let failing = 0;
+  const problems = [];
+
+  for (const dir of skillDirs) {
+    const files = findSkillFiles(dir);
+    for (const file of files) {
+      totalSkills++;
+      const missing = checkCompliance(file);
+      if (missing.length > 0) {
+        failing++;
+        const rel = path.relative(packageRoot, file);
+        problems.push({ file: rel, missing });
+      }
+    }
+  }
+
+  if (problems.length > 0) {
+    console.log(`   ✗ ${failing} / ${totalSkills} skills are non-compliant:\n`);
+    for (const p of problems) {
+      console.log(`     ${p.file}`);
+      console.log(`       missing: ${p.missing.join(', ')}`);
+    }
+  } else {
+    console.log(
+      `   ✓ All ${totalSkills} skills compliant with 5-component standard`
+    );
+  }
+
+  return failing;
+}
+
+// ---------- Entrypoint ----------
+
+module.exports = function doctor(args, { packageRoot }) {
+  const cwd = process.cwd();
+
+  console.log(`\n🕌 Rihal Code — Doctor\n`);
+
+  console.log(`Preflight:`);
+  const checks = runPreflight(cwd, packageRoot);
+  const preflightFailures = printChecks(checks);
+
+  console.log(`\nPackage compliance:`);
+  const complianceFailures = runCompliance(packageRoot);
+
+  const totalFailures = preflightFailures + complianceFailures;
+  console.log();
+  if (totalFailures === 0) {
+    console.log(`✅ All checks passed.`);
+  } else {
+    console.log(`❌ ${totalFailures} check(s) failed — see above.`);
+  }
+  console.log();
+  process.exit(totalFailures > 0 ? 1 : 0);
+};