@codename_inc/spectre 3.7.0 → 4.0.0

package/plugins/spectre/hooks/scripts/load-knowledge.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+/**
+ * load-knowledge.mjs
+ *
+ * SessionStart hook that refreshes the managed SPECTRE knowledge block in
+ * AGENTS.override.md and returns a short visible status line.
+ *
+ * Reads:
+ * - Apply skill from plugin: skills/apply/SKILL.md
+ * - Registry from project: .agents/skills/spectre-recall/references/registry.toon
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getPluginRoot() {
+  return process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..', '..');
+}
+
+function resolvePluginSkillPath(pluginRoot, skillName, ...parts) {
+  const candidates = [
+    path.join(pluginRoot, 'skills', skillName, ...parts),
+    path.join(pluginRoot, '..', 'skills', skillName, ...parts),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function skillBaseDir(projectDir) {
+  const agentsDir = path.join(projectDir, '.agents', 'skills');
+  if (fs.existsSync(agentsDir)) return agentsDir;
+  return path.join(projectDir, '.claude', 'skills');
+}
+
+function countRegistryEntries(lines) {
+  let count = 0;
+  for (const line of lines) {
+    if (line.trim() && line.includes('|') && !line.startsWith('#')) {
+      count++;
+    }
+  }
+  return count;
+}
+
+function stripFrontmatter(content) {
+  if (content.startsWith('---')) {
+    const end = content.indexOf('---', 3);
+    if (end !== -1) {
+      return content.slice(end + 3).trim();
+    }
+  }
+  return content;
+}
+
+function normalizeOverrideFile(content) {
+  return content
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function managedOverridePattern(startMarker, endMarker) {
+  return new RegExp(`\\n?${escapeRegExp(startMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}\\n?`, 'm');
+}
+
+function writeManagedOverride(overridePath, startMarker, endMarker, bodyContent) {
+  const current = fs.existsSync(overridePath) ? fs.readFileSync(overridePath, 'utf8') : '';
+  const pattern = managedOverridePattern(startMarker, endMarker);
+  const blockContent = `${startMarker}\n${bodyContent}\n${endMarker}`;
+  let updated;
+
+  if (pattern.test(current)) {
+    updated = current.replace(pattern, `${blockContent}\n`);
+  } else if (current.trim()) {
+    updated = `${current.trimEnd()}\n\n${blockContent}\n`;
+  } else {
+    updated = `${blockContent}\n`;
+  }
+
+  const normalized = normalizeOverrideFile(updated);
+  fs.writeFileSync(overridePath, normalized ? `${normalized}\n` : '');
+}
+
+function hasProjectKnowledgeSurface(projectDir, registryPath) {
+  const overridePath = path.join(projectDir, 'AGENTS.override.md');
+  const overrideContent = fs.existsSync(overridePath) ? fs.readFileSync(overridePath, 'utf8') : '';
+  return fs.existsSync(path.join(projectDir, '.spectre', 'manifest.json'))
+    || fs.existsSync(registryPath)
+    || overrideContent.includes('<!-- spectre-knowledge:start -->')
+    || overrideContent.includes('<!-- spectre-session:start -->');
+}
+
+function buildKnowledgeOverrideBody(applyContent) {
+  return [
+    '## SPECTRE Knowledge Context',
+    '',
+    'This block is managed by SPECTRE and replaced automatically on session start.',
+    'Use it before searching or implementing work in this repository.',
+    '',
+    applyContent.trim()
+  ].join('\n');
+}
+
+function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const pluginRoot = getPluginRoot();
+
+  const applySkillPath = resolvePluginSkillPath(pluginRoot, 'apply', 'SKILL.md');
+
+  if (!fs.existsSync(applySkillPath)) {
+    process.exit(0);
+  }
+
+  // Paths - check new name first, fall back to old names for migration
+  let registryPath = path.join(skillBaseDir(projectDir), 'spectre-recall', 'references', 'registry.toon');
+  const oldRegistryPath = path.join(projectDir, '.claude', 'skills', 'spectre-find', 'references', 'registry.toon');
+
+  // Support old "spectre-find" path for projects that haven't migrated
+  if (!fs.existsSync(registryPath) && fs.existsSync(oldRegistryPath)) {
+    registryPath = oldRegistryPath;
+  }
+
+  // Read registry if it exists
+  let registryContent = '';
+  let entryCount = 0;
+  if (fs.existsSync(registryPath)) {
+    registryContent = fs.readFileSync(registryPath, 'utf8').trim();
+    const lines = registryContent ? registryContent.split('\n') : [];
+    entryCount = countRegistryEntries(lines);
+  }
+
+  // Read apply skill and strip frontmatter
+  let applyContent = fs.readFileSync(applySkillPath, 'utf8');
+  applyContent = stripFrontmatter(applyContent);
+  applyContent = applyContent.replaceAll('.claude/skills/', '.agents/skills/').replaceAll('/spectre:', '');
+
+  if (hasProjectKnowledgeSurface(projectDir, registryPath)) {
+    writeManagedOverride(
+      path.join(projectDir, 'AGENTS.override.md'),
+      '<!-- spectre-knowledge:start -->',
+      '<!-- spectre-knowledge:end -->',
+      buildKnowledgeOverrideBody(applyContent)
+    );
+  }
+
+  // Visible notice
+  let visibleNotice;
+  if (entryCount > 0) {
+    visibleNotice = `\ud83d\udc7b spectre: ${entryCount} knowledge skills available`;
+  } else {
+    visibleNotice = '\ud83d\udc7b spectre: ready \u2014 capture knowledge with /spectre:learn';
+  }
+
+  const output = {
+    systemMessage: visibleNotice,
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart'
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output) + '\n');
+  process.exit(0);
+}
+
+export {
+  buildKnowledgeOverrideBody,
+  countRegistryEntries,
+  hasProjectKnowledgeSurface,
+  resolvePluginSkillPath,
+  stripFrontmatter
+};
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

package/plugins/spectre/hooks/scripts/register_learning.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+/**
+ * register_learning.mjs
+ *
+ * Registers a spectre learning and manages the project-level recall skill.
+ *
+ * Responsibilities:
+ * 1. Create/update registry at .claude/skills/spectre-recall/references/registry.toon
+ * 2. Read recall-template.md from plugin
+ * 3. Generate .claude/skills/spectre-recall/SKILL.md with embedded registry
+ *
+ * Usage:
+ *   node register_learning.mjs \
+ *     --project-root "/path/to/project" \
+ *     --skill-name "feature-my-feature" \
+ *     --category "feature" \
+ *     --triggers "keyword1, keyword2" \
+ *     --description "Use when doing X or Y"
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function getRegistryHeader() {
+  return [
+    '# SPECTRE Knowledge Registry',
+    '# Format: skill-name|category|triggers|description',
+    ''
+  ];
+}
+
+function updateRegistry(registryPath, entry, skillName) {
+  const entryPrefix = skillName + '|';
+  let lines;
+
+  if (fs.existsSync(registryPath)) {
+    const content = fs.readFileSync(registryPath, 'utf8').trim();
+    lines = content ? content.split('\n') : [];
+  } else {
+    lines = getRegistryHeader();
+  }
+
+  let entryExists = false;
+  const updatedLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith(entryPrefix)) {
+      updatedLines.push(entry);
+      entryExists = true;
+    } else {
+      updatedLines.push(line);
+    }
+  }
+
+  if (!entryExists) {
+    updatedLines.push(entry);
+  }
+
+  let content = updatedLines.join('\n');
+  if (!content.endsWith('\n')) {
+    content += '\n';
+  }
+
+  fs.writeFileSync(registryPath, content);
+  return content;
+}
+
+function generateFindSkill(findSkillPath, templatePath, registryContent) {
+  if (!fs.existsSync(templatePath)) {
+    process.stderr.write(`Warning: Template not found at ${templatePath}\n`);
+    return;
+  }
+
+  const template = fs.readFileSync(templatePath, 'utf8');
+  const skillContent = template.replace('{{REGISTRY}}', registryContent.trim());
+
+  fs.mkdirSync(path.dirname(findSkillPath), { recursive: true });
+  fs.writeFileSync(findSkillPath, skillContent);
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---')) return null;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return null;
+  return {
+    fmBlock: content.slice(4, end),
+    body: content.slice(end + 4)
+  };
+}
+
+function injectTriggerIntoSkill(skillPath, triggers) {
+  if (!fs.existsSync(skillPath)) return;
+
+  const content = fs.readFileSync(skillPath, 'utf8');
+  const parsed = parseFrontmatter(content);
+  if (!parsed) return;
+
+  const { fmBlock, body } = parsed;
+
+  const lines = fmBlock.split('\n');
+  const descIdx = lines.findIndex(l => /^description:\s*/.test(l));
+  if (descIdx === -1) return;
+
+  const descLine = lines[descIdx];
+  const rawValue = descLine.replace(/^description:\s*/, '').trim();
+
+  // Extract the plain description text and count lines to replace
+  let descText;
+  let linesToRemove = 1;
+
+  if (rawValue === '|' || rawValue === '>') {
+    // Block scalar — collect indented continuation lines
+    const continuationParts = [];
+    for (let i = descIdx + 1; i < lines.length; i++) {
+      if (/^\s+/.test(lines[i])) {
+        continuationParts.push(lines[i].trim());
+        linesToRemove++;
+      } else {
+        break;
+      }
+    }
+    descText = continuationParts.join(' ');
+  } else {
+    descText = rawValue;
+    // Strip surrounding quotes
+    if ((descText.startsWith('"') && descText.endsWith('"')) ||
+        (descText.startsWith("'") && descText.endsWith("'"))) {
+      descText = descText.slice(1, -1);
+    }
+  }
+
+  // Strip any existing TRIGGER clause so we can re-append with fresh triggers
+  descText = descText.replace(/\s*TRIGGER when:.*$/, '').trim();
+
+  // Single-line description with trigger appended
+  const newDesc = `description: ${descText} TRIGGER when: ${triggers}`;
+
+  // Idempotent: if the line is already exactly right, skip the write
+  if (linesToRemove === 1 && lines[descIdx] === newDesc) return;
+
+  lines.splice(descIdx, linesToRemove, newDesc);
+
+  const newFmBlock = lines.join('\n');
+  fs.writeFileSync(skillPath, `---\n${newFmBlock}\n---${body}`);
+}
+
+function migrateAllTriggers(projectRoot, registryContent) {
+  const skillsDir = skillBaseDir(projectRoot);
+  const lines = registryContent.trim().split('\n');
+  for (const line of lines) {
+    if (!line.trim() || line.startsWith('#')) continue;
+    const parts = line.split('|');
+    if (parts.length < 3) continue;
+    const skillName = parts[0];
+    const triggers = parts[2];
+    const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+    injectTriggerIntoSkill(skillPath, triggers);
+  }
+}
+
+function skillBaseDir(projectRoot) {
+  const agentsDir = path.join(projectRoot, '.agents', 'skills');
+  if (fs.existsSync(agentsDir)) return agentsDir;
+  return path.join(projectRoot, '.claude', 'skills');
+}
+
+function resolvePluginSkillPath(pluginRoot, skillName, ...parts) {
+  const candidates = [
+    path.join(pluginRoot, 'skills', skillName, ...parts),
+    path.join(pluginRoot, '..', 'skills', skillName, ...parts),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function parseArgs(argv) {
+  const args = {};
+  const flags = ['--project-root', '--skill-name', '--category', '--triggers', '--description'];
+
+  for (let i = 0; i < argv.length; i++) {
+    if (flags.includes(argv[i]) && i + 1 < argv.length) {
+      // Convert --project-root to projectRoot
+      const key = argv[i].slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      args[key] = argv[i + 1];
+      i++;
+    }
+  }
+
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const required = ['projectRoot', 'skillName', 'category', 'triggers', 'description'];
+  for (const key of required) {
+    if (!args[key]) {
+      process.stderr.write(`Error: missing required argument --${key.replace(/[A-Z]/g, c => '-' + c.toLowerCase())}\n`);
+      process.exit(1);
+    }
+  }
+
+  const projectRoot = args.projectRoot;
+
+  // New paths: registry lives inside spectre-recall skill
+  const recallDir = path.join(skillBaseDir(projectRoot), 'spectre-recall');
+  const registryDir = path.join(recallDir, 'references');
+  const registryPath = path.join(registryDir, 'registry.toon');
+  const recallSkillPath = path.join(recallDir, 'SKILL.md');
+
+  // Template is in the plugin — resolve via env var (hooks) or this script (manual invocation)
+  let pluginRoot;
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  } else {
+    // Fallback: resolve relative to this script
+    // Script is at: <plugin_root>/hooks/scripts/register_learning.mjs
+    pluginRoot = path.resolve(__dirname, '..', '..');
+  }
+  const templatePath = resolvePluginSkillPath(pluginRoot, 'learn', 'references', 'recall-template.md');
+
+  // Ensure directories exist
+  fs.mkdirSync(registryDir, { recursive: true });
+
+  // Build the registry entry
+  const entry = `${args.skillName}|${args.category}|${args.triggers}|${args.description}`;
+
+  // Update registry and get full content
+  const registryContent = updateRegistry(registryPath, entry, args.skillName);
+
+  // Generate recall skill with embedded registry
+  generateFindSkill(recallSkillPath, templatePath, registryContent);
+
+  // Reconcile triggers into all skill frontmatter descriptions
+  migrateAllTriggers(projectRoot, registryContent);
+
+  process.stdout.write(`Registered: ${entry}\n`);
+}
+
+export {
+  getRegistryHeader,
+  updateRegistry,
+  generateFindSkill,
+  parseFrontmatter,
+  injectTriggerIntoSkill,
+  migrateAllTriggers,
+  resolvePluginSkillPath,
+  parseArgs
+};
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(__filename)) {
+  main();
+}

package/plugins/spectre/hooks/scripts/{test_bootstrap.cjs → test_bootstrap.mjs}

@@ -1,18 +1,23 @@
 #!/usr/bin/env node
-'use strict';
 
-const { describe, it } = require('node:test');
-const assert = require('node:assert');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { cleanupStalePaths, STALE_PATHS } = require('./bootstrap.cjs');
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { cleanupStalePaths, STALE_PATHS } from './bootstrap.mjs';
+import { readStdinWithTimeout, STDIN_TIMEOUT } from './lib.mjs';
 
 function createTempDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'spectre-bootstrap-test-'));
 }
 
 describe('bootstrap', () => {
+  it('imports shared hook helpers through ESM', () => {
+    assert.strictEqual(STDIN_TIMEOUT, 2000);
+    assert.strictEqual(typeof readStdinWithTimeout, 'function');
+  });
+
   it('STALE_PATHS is a non-empty array', () => {
     assert.ok(Array.isArray(STALE_PATHS));
     assert.ok(STALE_PATHS.length > 0);

package/plugins/spectre/hooks/scripts/{test_handoff-resume.cjs → test_handoff-resume.mjs}

@@ -1,20 +1,22 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
- * Tests for handoff-resume.cjs
+ * Tests for handoff-resume.mjs
  *
- * Run with: node --test plugins/spectre/hooks/scripts/test_handoff-resume.cjs
+ * Run with: node --test plugins/spectre/hooks/scripts/test_handoff-resume.mjs
  */
 
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execFileSync, execSync } = require('child_process');
-
-const SCRIPT_PATH = path.join(__dirname, 'handoff-resume.cjs');
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync, execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SCRIPT_PATH = path.join(__dirname, 'handoff-resume.mjs');
 
 function createTmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'spectre-hr-'));