sdg-agents 1.0.5

package/src/engine/lib/prompt-utils.mjs

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import { select, checkbox, confirm } from '@inquirer/prompts';
+
+function isExitError(err) {
+  return err.name === 'ExitPromptError' || err.message?.includes('force closed');
+}
+
+async function safeSelect(options) {
+  try {
+    return await select(options);
+  } catch (error) {
+    if (isExitError(error)) return 'back';
+    throw error;
+  }
+}
+
+async function safeCheckbox(options) {
+  try {
+    return await checkbox(options);
+  } catch (error) {
+    if (isExitError(error)) return ['back'];
+    throw error;
+  }
+}
+
+async function safeConfirm(options) {
+  try {
+    return await confirm(options);
+  } catch (error) {
+    if (isExitError(error)) return false;
+    throw error;
+  }
+}
+
+const PROJECT_ROOT = process.cwd();
+const AI_DIR = path.join(PROJECT_ROOT, '.ai');
+const PROMPT_FILE = path.join(AI_DIR, 'last-prompt.md');
+
+function isMaintainerMode() {
+  const pkgPath = path.join(PROJECT_ROOT, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.name === 'sdg-agents';
+  } catch {
+    return false;
+  }
+}
+
+function savePromptToFile(content) {
+  if (!fs.existsSync(AI_DIR)) {
+    fs.mkdirSync(AI_DIR, { recursive: true });
+  }
+  fs.writeFileSync(PROMPT_FILE, content, 'utf8');
+}
+
+async function copyToClipboard(content) {
+  return new Promise((resolve) => {
+    let command;
+
+    switch (process.platform) {
+      case 'darwin':
+        command = 'pbcopy';
+        break;
+      case 'win32':
+        command = 'clip';
+        break;
+      case 'linux':
+        command = 'xclip -selection clipboard || xsel -bi';
+        break;
+      default:
+        return resolve(false);
+    }
+
+    const child = exec(command, (error) => {
+      resolve(!error);
+    });
+
+    child.on('error', () => {
+      resolve(false);
+    });
+
+    if (child.stdin) {
+      child.stdin.on('error', () => {
+        resolve(false);
+      });
+      child.stdin.write(content);
+      child.stdin.end();
+    } else {
+      resolve(false);
+    }
+  });
+}
+
+async function printPromptUI(content, title = 'AI Prompt Generated') {
+  const maintainer = isMaintainerMode();
+  savePromptToFile(content);
+  const copied = await copyToClipboard(content);
+
+  console.log(`\n  ✅ ${title}`);
+
+  if (maintainer) {
+    console.log('  🛠️  MAINTAINER MODE DETECTED: Prompt targets the Core Instructions.');
+  }
+
+  console.log('  ' + '─'.repeat(60));
+
+  if (copied) {
+    console.log('  📋 COPIED TO CLIPBOARD AUTOMATICALLY.');
+  } else {
+    console.log('  ⚠️  COULD NOT COPY TO CLIPBOARD (Install xclip/xsel on Linux).');
+  }
+
+  console.log(`  💾 SAVED TO: .ai/last-prompt.md`);
+  console.log('  ' + '─'.repeat(60));
+
+  console.log('\n  🤖 HOW TO USE WITH LOCAL AGENTS (Cursor, Claude Code, Windsurf):');
+  console.log('     Tell your agent: "Follow the instructions in .ai/last-prompt.md"');
+
+  console.log('\n  🌍 HOW TO USE WITH WEB CHATS (Claude.ai, ChatGPT, Gemini):');
+  console.log('     The prompt is already in your clipboard. Just paste it (Ctrl+V).');
+  console.log('  ' + '─'.repeat(60) + '\n');
+}
+
+const PromptUtils = {
+  isMaintainerMode,
+  savePromptToFile,
+  copyToClipboard,
+  printPromptUI,
+  safeSelect,
+  safeCheckbox,
+  safeConfirm,
+};
+
+export { PromptUtils };

package/src/engine/lib/result-utils.mjs

@@ -0,0 +1,14 @@
+function success(value) {
+  return { isSuccess: true, isFailure: false, value, error: null };
+}
+
+function fail(message, code) {
+  return { isSuccess: false, isFailure: true, value: null, error: { message, code } };
+}
+
+const ResultUtils = {
+  success,
+  fail,
+};
+
+export { ResultUtils };

package/src/engine/lib/ruleset-injector.mjs

@@ -0,0 +1,183 @@
+/**
+ * Ruleset Injector — Copies instruction files into the target project.
+ * Handles version-aware filtering of markdown/XML content blocks.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { STACK_DISPLAY_NAMES } from '../config/stack-display.mjs';
+import { FsUtils } from './fs-utils.mjs';
+
+const { copyRecursiveSync, filterContentByVersion, getDirname } = FsUtils;
+
+const __dirname = getDirname(import.meta.url);
+const SOURCE_INSTRUCTIONS = path.join(__dirname, '..', '..', 'assets', 'instructions');
+const SOURCE_WORKFLOWS = path.join(SOURCE_INSTRUCTIONS, 'workflows');
+const SOURCE_COMMANDS = path.join(SOURCE_INSTRUCTIONS, 'commands');
+const SOURCE_DEV_GUIDES = path.join(__dirname, '..', '..', 'assets', 'dev-guides');
+const SOURCE_DEV_TRACKS = path.join(SOURCE_DEV_GUIDES, 'prompt-tracks');
+const SOURCE_COMPETENCIES = path.join(SOURCE_INSTRUCTIONS, 'competencies');
+
+/**
+ * Creates the .ai/instructions directory structure in the target project.
+ */
+function prepareProjectStructure(targetDir) {
+  const instructionsDir = path.join(targetDir, '.ai', 'instructions');
+  const workflowsDir = path.join(targetDir, '.ai', 'workflows');
+  const commandsDir = path.join(targetDir, '.ai', 'commands');
+
+  if (!fs.existsSync(instructionsDir)) fs.mkdirSync(instructionsDir, { recursive: true });
+  if (!fs.existsSync(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
+  if (!fs.existsSync(commandsDir)) fs.mkdirSync(commandsDir, { recursive: true });
+}
+
+/**
+ * Injects core, flavor, idiom, and template rulesets into the target project.
+ */
+function injectRulesets(targetDir, selections, { noDevGuides = false } = {}) {
+  const { flavor, idioms } = selections;
+  const projectAiInstructions = path.join(targetDir, '.ai', 'instructions');
+
+  copyRecursiveSync(
+    path.join(SOURCE_INSTRUCTIONS, 'core'),
+    path.join(projectAiInstructions, 'core')
+  );
+
+  const flavorSrc = path.join(SOURCE_INSTRUCTIONS, 'flavors', flavor);
+  if (fs.existsSync(flavorSrc)) {
+    copyRecursiveSync(flavorSrc, path.join(projectAiInstructions, 'flavor'));
+  }
+
+  for (const idiom of idioms) {
+    injectFilteredIdiom(idiom, selections.versions[idiom], projectAiInstructions);
+  }
+
+  injectCompetencies(selections, projectAiInstructions);
+
+  copyRecursiveSync(
+    path.join(SOURCE_INSTRUCTIONS, 'templates'),
+    path.join(projectAiInstructions, 'templates')
+  );
+
+  if (fs.existsSync(SOURCE_WORKFLOWS)) {
+    copyRecursiveSync(SOURCE_WORKFLOWS, path.join(targetDir, '.ai', 'workflows'));
+  }
+
+  if (fs.existsSync(SOURCE_COMMANDS)) {
+    copyRecursiveSync(SOURCE_COMMANDS, path.join(targetDir, '.ai', 'commands'));
+  }
+
+  if (!noDevGuides) injectDevGuides(targetDir);
+}
+
+/**
+ * Copies dev-guides (reference files, spec templates, guides) into the target project.
+ * Always included alongside the instruction set.
+ */
+function injectDevGuides(targetDir) {
+  if (!fs.existsSync(SOURCE_DEV_GUIDES)) return;
+  copyRecursiveSync(SOURCE_DEV_GUIDES, path.join(targetDir, '.ai', 'dev-guides'));
+}
+
+/**
+ * Injects specification templates (tracks) into the target project.
+ */
+function injectPrompts(targetDir, track) {
+  const projectRootPromptsDir = path.join(targetDir, '.ai', 'prompts');
+  const devTracksDir = path.join(projectRootPromptsDir, 'dev-tracks');
+
+  // Total replacement: clear the WHOLE .ai/prompts directory if it exists
+  if (fs.existsSync(projectRootPromptsDir)) {
+    fs.rmSync(projectRootPromptsDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(devTracksDir, { recursive: true });
+
+  if (track === 'all') {
+    // Copy all tracks from source to project
+    copyRecursiveSync(SOURCE_DEV_TRACKS, devTracksDir);
+  } else {
+    // Copy specific track folder into dev-tracks
+    const trackSrc = path.join(SOURCE_DEV_TRACKS, track);
+    const dest = path.join(devTracksDir, track);
+    if (fs.existsSync(trackSrc)) {
+      copyRecursiveSync(trackSrc, dest);
+    }
+  }
+}
+
+/**
+ * Collects the list of directories and files that would be created (for --dry-run).
+ */
+function collectOutputSummary(selections) {
+  const { mode, flavor, idioms, track } = selections;
+  const directories = [];
+
+  if (mode === 'agents') {
+    directories.push('.ai/instructions/core/');
+    if (flavor) directories.push('.ai/instructions/flavor/');
+    for (const idiom of idioms) directories.push(`.ai/instructions/idioms/${idiom}/`);
+    directories.push('.ai/instructions/templates/');
+    directories.push('.ai/instructions/competencies/');
+    directories.push('.ai/workflows/');
+    directories.push('.ai/commands/');
+    directories.push('.ai/dev-guides/');
+  } else if (mode === 'prompts') {
+    if (track) directories.push('.ai/prompts/dev-tracks/');
+  }
+
+  return { directories };
+}
+
+// --- Private ---
+
+function injectCompetencies(selections, projectAiInstructions) {
+  if (!fs.existsSync(SOURCE_COMPETENCIES)) return;
+
+  const hasBackend = selections.idioms.some((idiomId) => STACK_DISPLAY_NAMES[idiomId]?.isBackend);
+  const hasFrontend = selections.idioms.some((idiomId) => STACK_DISPLAY_NAMES[idiomId]?.isFrontend);
+
+  if (!hasBackend && !hasFrontend) return;
+
+  const competenciesDir = path.join(projectAiInstructions, 'competencies');
+  if (!fs.existsSync(competenciesDir)) fs.mkdirSync(competenciesDir, { recursive: true });
+
+  if (hasBackend) {
+    const src = path.join(SOURCE_COMPETENCIES, 'backend.md');
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(competenciesDir, 'backend.md'));
+  }
+
+  if (hasFrontend) {
+    const src = path.join(SOURCE_COMPETENCIES, 'frontend.md');
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(competenciesDir, 'frontend.md'));
+  }
+}
+
+function injectFilteredIdiom(idiom, targetVersion, projectAiInstructions) {
+  const idiomSrc = path.join(SOURCE_INSTRUCTIONS, 'idioms', idiom);
+  if (!fs.existsSync(idiomSrc)) return;
+
+  const projectIdiomDir = path.join(projectAiInstructions, 'idioms', idiom);
+  if (!fs.existsSync(projectIdiomDir)) fs.mkdirSync(projectIdiomDir, { recursive: true });
+
+  for (const file of fs.readdirSync(idiomSrc)) {
+    const srcFile = path.join(idiomSrc, file);
+    const destFile = path.join(projectIdiomDir, file);
+
+    if (file.endsWith('.md') || file.endsWith('.xml')) {
+      let content = fs.readFileSync(srcFile, 'utf8');
+      content = filterContentByVersion(content, targetVersion);
+      fs.writeFileSync(destFile, content, 'utf8');
+    } else {
+      copyRecursiveSync(srcFile, destFile);
+    }
+  }
+}
+
+export const RulesetInjector = {
+  prepareProjectStructure,
+  injectRulesets,
+  injectDevGuides,
+  injectPrompts,
+  collectOutputSummary,
+};

package/src/engine/lib/ui-utils.mjs

@@ -0,0 +1,216 @@
+/**
+ * Bundle UI — All console output and user confirmation for the bundle lifecycle.
+ * Single responsibility: presentation and interaction only, no file I/O.
+ */
+
+import { STACK_DISPLAY_NAMES } from '../config/stack-display.mjs';
+import { RulesetInjector } from './ruleset-injector.mjs';
+import { PromptUtils } from './prompt-utils.mjs';
+
+const { collectOutputSummary } = RulesetInjector;
+const { safeConfirm } = PromptUtils;
+
+function printWelcome() {
+  console.log('\n  Installing instruction set...');
+  console.log('  ' + '─'.repeat(55));
+}
+
+function printStep(step, total, message) {
+  console.log(`[${step}/${total}] ${message}`);
+}
+
+function printAborted() {
+  console.log('\n  Aborted. No files were written.\n');
+}
+
+function printQuickSetupStart() {
+  console.log(`\n  ⚡ Quick setup — installing with defaults...`);
+}
+
+function printProjectRoot(targetDir) {
+  console.log(`\n  Project Root: ${targetDir}`);
+}
+
+function printActivationGuide() {
+  console.log('\n  Your agent is ready. Start with a task.');
+  console.log('  If it does not auto-load the rules, paste this once:');
+  console.log('\n    Read .ai/skill/AGENTS.md\n');
+}
+
+function printSuccessAgents(targetDir) {
+  console.log('\n  ✅ Done.');
+  console.log('  ' + '─'.repeat(55));
+  console.log(`  Project: ${targetDir}\n`);
+  console.log('  .ai/');
+  console.log('  .ai-backlog/             (gitignored)');
+  printActivationGuide();
+}
+
+function printSuccessPrompts(targetDir) {
+  console.log('\n  ✅ Done.');
+  console.log('  ' + '─'.repeat(55));
+  console.log(`  Project: ${targetDir}\n`);
+  console.log('  .ai/prompts/dev-tracks/  — specification templates\n');
+}
+
+function printQuickSuccess(targetDir) {
+  console.log('\n  ⚡ Done.');
+  console.log('  ' + '─'.repeat(55));
+  console.log(`  Project: ${targetDir}\n`);
+  console.log('  .ai/');
+  console.log('  .ai-backlog/             (gitignored)');
+  printActivationGuide();
+}
+
+function printQuickDryRun(targetDir) {
+  console.log(`\n  ⚡ [DRY RUN] Quick setup — nothing will be written.`);
+  console.log('  ' + '─'.repeat(55));
+  console.log(`  Project: ${targetDir}\n`);
+  console.log(`  [1/5] Would prepare .ai/ structure`);
+  console.log(`  [2/5] Would inject rules and dev-guides → .ai/`);
+  console.log(`  [3/5] Would assemble AGENTS.md`);
+  console.log(`  [4/5] Would write agent config and backlog`);
+  console.log(`  [5/5] Would inject spec templates → .ai/prompts/dev-tracks/`);
+  console.log('\n  Run without --dry-run to apply.\n');
+}
+
+function printDryRunPreview(selections, targetDir) {
+  const summary = collectOutputSummary(selections);
+
+  console.log('\n  📋 DRY RUN — Preview of files that would be created:');
+  console.log('  ' + '─'.repeat(55));
+  console.log(`  Project Root: ${targetDir}\n`);
+
+  console.log('  Instruction directories:');
+  for (const dir of summary.directories) {
+    console.log(`    📁 ${dir}`);
+  }
+
+  console.log(`    📄 .ai/skill/AGENTS.md`);
+
+  const activeAgents = [...(selections.agents || []), selections.ide].filter(Boolean);
+  const ideTargets = {
+    cursor: '.cursor/rules/sdg-agents.mdc',
+    windsurf: '.windsurfrules',
+    vscode: '.github/copilot-instructions.md',
+    copilot: '.github/copilot-instructions.md',
+    claude: 'CLAUDE.md',
+    roocode: '.clinerules',
+    gemini: 'AI_INSTRUCTIONS.md',
+  };
+
+  for (const agent of activeAgents) {
+    if (agent === 'none' || agent === 'antigravity' || agent === 'all') continue;
+    if (ideTargets[agent]) {
+      console.log(`    📄 ${ideTargets[agent]}`);
+    }
+  }
+
+  if (selections.mode === 'agents') {
+    console.log('    📄 .ai/.sdg-manifest.json');
+  }
+
+  console.log('\n  ' + '─'.repeat(55));
+  console.log('  Run without --dry-run to apply.\n');
+}
+
+async function printBuildSummary(selections) {
+  const { flavor, idioms, versions, designPreset, mode, track } = selections;
+
+  const flavorLabel = STACK_DISPLAY_NAMES[flavor]?.name ?? flavor;
+  const idiomsLabel = idioms
+    .map((id) => {
+      const name = STACK_DISPLAY_NAMES[id]?.name ?? id;
+      const ver = versions?.[id] ? ` (${versions[id]})` : '';
+      return `${name}${ver}`;
+    })
+    .join(', ');
+
+  console.log('\n  ┌─ Build Summary ──────────────────────────────────────┐');
+
+  if (mode === 'prompts') {
+    console.log(
+      '  │  Track:   ' +
+        (track === 'all' ? '00, 01, 02 (Full Training)'.padEnd(43) : track.padEnd(43)) +
+        '│'
+    );
+  } else {
+    console.log(`  │  Flavor:  ${flavorLabel.padEnd(43)}│`);
+    console.log(`  │  Idioms:  ${idiomsLabel.padEnd(43)}│`);
+    if (designPreset) {
+      console.log(`  │  Preset:  ${designPreset.padEnd(43)}│`);
+    }
+  }
+
+  console.log('  └──────────────────────────────────────────────────────┘');
+
+  return safeConfirm({ message: '  Proceed?', default: true });
+}
+
+function printHeader(version) {
+  console.log(`\n  Spec-Driven Guide — Agents v${version}`);
+  console.log('  ' + '─'.repeat(50));
+  console.log('  A working protocol and engineering rules for your AI agent.');
+  console.log('  Press Ctrl+C to exit.\n');
+}
+
+function printFooter() {
+  console.log('\n  See you.\n');
+}
+
+function printHelp(version) {
+  console.log(`
+  sdg-agents v${version}
+  Installs a structured instruction set for AI agents into your project.
+
+  Usage:
+    npx sdg-agents [command] [options]
+
+  Commands:
+    init         Install the instruction set (interactive or via flags)
+    review       Compare local rules vs source
+    sync         Update patterns from source
+    update       Refresh the LTS version registry
+    add          Add a language idiom to an existing project
+    clear        Remove the .ai/ folder
+
+  Global Options:
+    -h, --help       Show this help
+    -v, --version    Show version
+
+  Init Options:
+    --flavor <name>      Architecture flavor (vertical-slice, mvc, lite, legacy)
+    --idiom <name>       Language idiom — repeatable or comma-separated
+    --no-dev-guides      Skip reference files and spec templates
+    --dry-run            Preview without writing files
+
+  Examples:
+    npx sdg-agents
+    npx sdg-agents init --flavor vertical-slice --idiom typescript
+    npx sdg-agents init --flavor mvc --idiom typescript,python
+    npx sdg-agents init --flavor lite --idiom go --no-dev-guides
+    npx sdg-agents init --flavor mvc --idiom python --dry-run
+    npx sdg-agents add
+    npx sdg-agents clear
+`);
+}
+
+const BundleUI = {
+  printWelcome,
+  printStep,
+  printAborted,
+  printQuickSetupStart,
+  printProjectRoot,
+  printActivationGuide,
+  printSuccessAgents,
+  printSuccessPrompts,
+  printQuickSuccess,
+  printQuickDryRun,
+  printDryRunPreview,
+  printBuildSummary,
+  printHeader,
+  printFooter,
+  printHelp,
+};
+
+export { BundleUI };