@codename_inc/spectre 3.7.0

package/src/lib/knowledge.js

@@ -0,0 +1,217 @@
+import fs from 'fs';
+import path from 'path';
+import { projectPaths, spectrePluginRoot, ensureDir } from './paths.js';
+
+function stripFrontmatter(content) {
+  if (!content.startsWith('---\n')) {
+    return content.trim();
+  }
+
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return content.trim();
+  }
+
+  return content.slice(end + 5).trim();
+}
+
+function rewriteProjectSkillPaths(content) {
+  return content.replaceAll('.claude/skills/', '.agents/skills/');
+}
+
+function rewriteCodexCommandRefs(content) {
+  return content.replaceAll('/spectre:', 'spectre-');
+}
+
+function markUserInvocable(content, value = true) {
+  if (!content.startsWith('---\n')) {
+    return content;
+  }
+
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return content;
+  }
+
+  const frontmatter = content.slice(4, end).trimEnd();
+  const body = content.slice(end + 5);
+  const nextFrontmatter = frontmatter.includes('\nuser-invocable:')
+    ? frontmatter.replace(/\nuser-invocable:\s*(true|false)/, `\nuser-invocable: ${value}`)
+    : `${frontmatter}\nuser-invocable: ${value}`;
+
+  return `---\n${nextFrontmatter}\n---\n${body}`;
+}
+
+function codexPathConvention(content) {
+  return content.replace(
+    /Resolution order:[\s\S]*?Do NOT use `git rev-parse --show-toplevel` or any git command to resolve this path\./,
+    [
+      'Resolution rule:',
+      '- Use the current working directory (`$PWD`) as `{{project_root}}`.',
+      '',
+      'Do NOT use `git rev-parse --show-toplevel` or any git command to resolve this path.'
+    ].join('\n')
+  );
+}
+
+function codexLearnIntro(content) {
+  return content.replace(
+    "You capture durable project knowledge into Skills that Claude Code loads on-demand.",
+    'You capture durable project knowledge into Skills that Codex loads on-demand.'
+  );
+}
+
+function normalizeSkillMarkdown(content) {
+  return content.replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+function pluginSkillPath(skillName) {
+  return path.join(spectrePluginRoot(), 'skills', skillName, 'SKILL.md');
+}
+
+function recallTemplatePath() {
+  return path.join(spectrePluginRoot(), 'skills', 'spectre-learn', 'references', 'recall-template.md');
+}
+
+function pluginSkillContent(skillName) {
+  return fs.readFileSync(pluginSkillPath(skillName), 'utf8');
+}
+
+export function codexSharedSkillContent(skillName) {
+  if (skillName === 'spectre-apply') {
+    return `${normalizeSkillMarkdown(rewriteCodexCommandRefs(rewriteProjectSkillPaths(pluginSkillContent(skillName))))}\n`;
+  }
+
+  if (skillName === 'spectre-learn') {
+    return `${normalizeSkillMarkdown(markUserInvocable(rewriteCodexCommandRefs(codexPathConvention(codexLearnIntro(rewriteProjectSkillPaths(pluginSkillContent(skillName)))))))}\n`;
+  }
+
+  return null;
+}
+
+export function knowledgeRegistryHeader() {
+  return [
+    '# SPECTRE Knowledge Registry',
+    '# Format: skill-name|category|triggers|description',
+    ''
+  ].join('\n');
+}
+
+export function countKnowledgeEntries(registryContent) {
+  const lines = registryContent ? registryContent.split('\n') : [];
+  let count = 0;
+  for (const line of lines) {
+    if (line.trim() && line.includes('|') && !line.startsWith('#')) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function readKnowledgeRegistry(projectDir) {
+  const paths = projectPaths(projectDir);
+  const registryContent = fs.existsSync(paths.knowledgeRegistryPath)
+    ? fs.readFileSync(paths.knowledgeRegistryPath, 'utf8').trim()
+    : '';
+
+  return {
+    registryContent,
+    entryCount: countKnowledgeEntries(registryContent),
+    registryPath: paths.knowledgeRegistryPath
+  };
+}
+
+function knowledgeRegistrySection(registryContent, entryCount) {
+  if (entryCount > 0) {
+    return [
+      '## Registry',
+      '',
+      '**Format**: `skill-name|category|triggers|description`',
+      '',
+      '```',
+      registryContent,
+      '```',
+      '',
+      'Each entry corresponds to a skill that can be loaded via `Skill({skill-name})`',
+      '',
+      '**Categories:** feature, gotchas, patterns, decisions, procedures, integration, performance, testing, ux, strategy'
+    ].join('\n');
+  }
+
+  return [
+    '## Registry',
+    '',
+    'No knowledge has been captured for this project yet. The behavioral rules in this document still apply.',
+    '',
+    'To capture knowledge from this session, use `spectre-learn` after completing significant work.',
+    '',
+    '**Categories:** feature, gotchas, patterns, decisions, procedures, integration, performance, testing, ux, strategy'
+  ].join('\n');
+}
+
+export function generateRecallSkillContent(projectDir) {
+  const { registryContent } = readKnowledgeRegistry(projectDir);
+  const template = fs.readFileSync(recallTemplatePath(), 'utf8');
+  return `${markUserInvocable(rewriteCodexCommandRefs(template.replace('{{REGISTRY}}', registryContent.trim())))}\n`;
+}
+
+export function ensureKnowledgeFiles(projectDir) {
+  const paths = projectPaths(projectDir);
+  ensureDir(paths.projectSkillsDir);
+  ensureDir(paths.recallReferencesDir);
+
+  if (!fs.existsSync(paths.knowledgeRegistryPath)) {
+    fs.writeFileSync(paths.knowledgeRegistryPath, `${knowledgeRegistryHeader()}\n`);
+  }
+
+  fs.writeFileSync(paths.recallSkillPath, generateRecallSkillContent(projectDir));
+}
+
+export function buildKnowledgeOverrideBody(projectDir) {
+  ensureKnowledgeFiles(projectDir);
+  const { registryContent, entryCount } = readKnowledgeRegistry(projectDir);
+  const applyContent = stripFrontmatter(rewriteCodexCommandRefs(rewriteProjectSkillPaths(pluginSkillContent('spectre-apply')))).replace(
+    /## Registry Location[\s\S]*?(?=## Workflow)/,
+    `${knowledgeRegistrySection(registryContent, entryCount)}\n\n`
+  );
+
+  return normalizeSkillMarkdown(applyContent);
+}
+
+export function updateKnowledgeRegistry(projectDir, { skillName, category, triggers, description }) {
+  ensureKnowledgeFiles(projectDir);
+  const paths = projectPaths(projectDir);
+  const entry = `${skillName}|${category}|${triggers}|${description}`;
+  const entryPrefix = `${skillName}|`;
+  const existing = fs.readFileSync(paths.knowledgeRegistryPath, 'utf8').trim();
+  const lines = existing ? existing.split('\n') : knowledgeRegistryHeader().split('\n');
+  const updatedLines = [];
+  let replaced = false;
+
+  for (const line of lines) {
+    if (line.startsWith(entryPrefix)) {
+      updatedLines.push(entry);
+      replaced = true;
+    } else {
+      updatedLines.push(line);
+    }
+  }
+
+  if (!replaced) {
+    updatedLines.push(entry);
+  }
+
+  fs.writeFileSync(paths.knowledgeRegistryPath, `${updatedLines.join('\n').trimEnd()}\n`);
+  fs.writeFileSync(paths.recallSkillPath, generateRecallSkillContent(projectDir));
+}
+
+export function knowledgeStatusMessage(projectDir) {
+  ensureKnowledgeFiles(projectDir);
+  const { entryCount } = readKnowledgeRegistry(projectDir);
+
+  if (entryCount === 0) {
+    return '👻 spectre: ready — capture knowledge with spectre-learn';
+  }
+
+  return `👻 spectre: ${entryCount} knowledge skills available`;
+}

package/src/lib/paths.js

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function repoRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+export function spectrePluginRoot() {
+  return path.join(repoRoot(), 'plugins', 'spectre');
+}
+
+export function resolveCodexHome() {
+  const envHome = process.env.CODEX_HOME;
+  if (envHome) {
+    return envHome;
+  }
+  return path.join(os.homedir(), '.codex');
+}
+
+export function codexConfigPath() {
+  return path.join(resolveCodexHome(), 'config.toml');
+}
+
+export function codexHooksConfigPath() {
+  return path.join(resolveCodexHome(), 'hooks.json');
+}
+
+export function codexPromptsDir() {
+  return path.join(resolveCodexHome(), 'prompts');
+}
+
+export function codexSkillsDir() {
+  return path.join(resolveCodexHome(), 'skills');
+}
+
+export function codexRuntimeRoot() {
+  return path.join(resolveCodexHome(), 'spectre');
+}
+
+export function runtimeSourceRoot() {
+  return path.join(codexRuntimeRoot(), 'source');
+}
+
+export function runtimeSourceCommandsDir() {
+  return path.join(runtimeSourceRoot(), 'commands');
+}
+
+export function runtimeSourceAgentsDir() {
+  return path.join(runtimeSourceRoot(), 'agents');
+}
+
+export function runtimeAgentsDir() {
+  return path.join(codexRuntimeRoot(), 'agents');
+}
+
+export function runtimeToolsDir() {
+  return path.join(codexRuntimeRoot(), 'tools');
+}
+
+export function runtimeHooksDir() {
+  return path.join(codexRuntimeRoot(), 'hooks');
+}
+
+export function projectCodexHome(projectDir) {
+  return path.join(projectDir, '.codex');
+}
+
+export function projectPaths(projectDir) {
+  const projectSkillsDir = path.join(projectDir, '.agents', 'skills');
+  const recallSkillDir = path.join(projectSkillsDir, 'spectre-recall');
+  const recallReferencesDir = path.join(recallSkillDir, 'references');
+  return {
+    projectDir,
+    projectCodexHome: projectCodexHome(projectDir),
+    projectCodexConfigPath: path.join(projectCodexHome(projectDir), 'config.toml'),
+    projectSpectreBinDir: path.join(projectDir, '.spectre', 'bin'),
+    spectreDir: path.join(projectDir, '.spectre'),
+    manifestPath: path.join(projectDir, '.spectre', 'manifest.json'),
+    rootAgentsPath: path.join(projectDir, 'AGENTS.md'),
+    overrideAgentsPath: path.join(projectDir, 'AGENTS.override.md'),
+    projectSkillsDir,
+    recallSkillDir,
+    recallSkillPath: path.join(recallSkillDir, 'SKILL.md'),
+    recallReferencesDir,
+    knowledgeRegistryPath: path.join(recallReferencesDir, 'registry.toon'),
+    sessionSkillDir: path.join(projectDir, '.agents', 'skills', 'spectre-session'),
+    sessionSkillPath: path.join(projectDir, '.agents', 'skills', 'spectre-session', 'SKILL.md')
+  };
+}
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}