sdg-agents 1.0.6 → 1.0.9

package/README.md

@@ -5,7 +5,7 @@
     A CLI that installs a structured instruction set for AI agents into your project.<br>
     <a href="docs/README.pt-BR.md">Versão em Português (Brasil)</a>
   </p>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square&logo=nodedotjs" alt="Node" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen?style=flat-square&logo=nodedotjs" alt="Node" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-ISC-blue?style=flat-square" alt="License: ISC" /></a>
 </div>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",
@@ -8,7 +8,7 @@
     "sdg-agents": "./src/engine/bin/index.mjs"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
     "dev": "node src/engine/bin/index.mjs",
@@ -43,29 +43,17 @@
   "author": "thiagocajadev",
   "license": "ISC",
   "files": [
-    "src/engine/bin/index.mjs",
-    "src/engine/bin/add-idiom.mjs",
-    "src/engine/config/",
-    "src/engine/lib/cli-parser.mjs",
-    "src/engine/lib/display-utils.mjs",
-    "src/engine/lib/fs-utils.mjs",
-    "src/engine/lib/instruction-assembler.mjs",
-    "src/engine/lib/manifest-utils.mjs",
-    "src/engine/lib/prompt-utils.mjs",
-    "src/engine/lib/result-utils.mjs",
-    "src/engine/lib/ruleset-injector.mjs",
-    "src/engine/lib/ui-utils.mjs",
-    "src/engine/lib/wizard.mjs",
+    "src/engine/",
     "src/assets/"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/thiagocajadev/sgd-agents-cli.git"
+    "url": "git+https://github.com/thiagocajadev/sdg-agents-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/thiagocajadev/sgd-agents-cli/issues"
+    "url": "https://github.com/thiagocajadev/sdg-agents-cli/issues"
   },
-  "homepage": "https://github.com/thiagocajadev/sgd-agents-cli#readme",
+  "homepage": "https://github.com/thiagocajadev/sdg-agents-cli#readme",
   "dependencies": {
     "@inquirer/prompts": "^8.3.2",
     "dedent": "^1.7.2"

package/src/engine/bin/auto-bump.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { ResultUtils } from '../lib/result-utils.mjs';
+import { FsUtils } from '../lib/fs-utils.mjs';
+
+const { success } = ResultUtils;
+const { runIfDirect } = FsUtils;
+
+// bin/ → engine/ → src/ → root
+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../');
+const PACKAGE_PATHS = [path.join(ROOT_DIR, 'package.json')];
+
+// --- Orchestrator ---
+
+async function run() {
+  const commitMsg = readLastCommitMessage();
+
+  const bumpType = detectBumpType(commitMsg);
+  if (bumpType === 'skip') {
+    console.log('  auto-bump: skipped (version commit detected)');
+    return success({ from: null, to: null, bump: 'skip' });
+  }
+
+  const rootPkg = readPackageJson(resolveRootPackagePath());
+  const nextVersion = bumpVersion(rootPkg.version, bumpType);
+
+  syncAllPackages(nextVersion);
+  stageAndCommit(nextVersion);
+
+  console.log(`  auto-bump: ${rootPkg.version} → ${nextVersion} (${bumpType})`);
+  return success({ from: rootPkg.version, to: nextVersion, bump: bumpType });
+}
+
+// --- Core Logic ---
+
+function detectBumpType(commitMsg) {
+  const firstLine = commitMsg.split('\n')[0].trim();
+  const footer = commitMsg.split('\n').slice(1).join('\n');
+
+  if (/^chore:\s*bump version/i.test(firstLine)) return 'skip';
+  if (/^[a-z]+!:/.test(firstLine)) return 'major';
+  if (/BREAKING CHANGE:/m.test(footer)) return 'major';
+  if (/^feat:/.test(firstLine)) return 'minor';
+  return 'patch';
+}
+
+function bumpVersion(current, bumpType) {
+  const [major, minor, patch] = current.split('.').map(Number);
+
+  switch (bumpType) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+// --- Sync & Commit ---
+
+function syncAllPackages(nextVersion) {
+  const paths = resolvePackagePaths();
+  for (const pkgPath of paths) {
+    writeVersion(pkgPath, nextVersion);
+  }
+}
+
+function stageAndCommit(nextVersion) {
+  const paths = resolvePackagePaths();
+  const files = paths.filter((p) => fs.existsSync(p)).join(' ');
+  execSync(`git add ${files}`, { stdio: 'inherit' });
+  execSync(`git commit -m "chore: bump version to ${nextVersion}"`, { stdio: 'inherit' });
+}
+
+// --- File Helpers ---
+
+function readLastCommitMessage() {
+  return execSync('git log -1 --pretty=%B').toString().trim();
+}
+
+function resolveRootPackagePath() {
+  return PACKAGE_PATHS[0];
+}
+
+function resolvePackagePaths() {
+  return PACKAGE_PATHS.filter((p) => fs.existsSync(p));
+}
+
+function readPackageJson(pkgPath) {
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+}
+
+function writeVersion(pkgPath, version) {
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = readPackageJson(pkgPath);
+  pkg.version = version;
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+export const AutoBump = {
+  run,
+  detectBumpType,
+  bumpVersion,
+};
+
+runIfDirect(import.meta.url, run);

package/src/engine/bin/build-bundle.mjs

@@ -0,0 +1,259 @@
+/**
+ * Build Bundle — Orchestrates wizard, injection, and assembly.
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { WizardUtils } from '../lib/wizard.mjs';
+import { RulesetInjector } from '../lib/ruleset-injector.mjs';
+import { InstructionAssembler } from '../lib/instruction-assembler.mjs';
+import { ResultUtils } from '../lib/result-utils.mjs';
+import { FsUtils } from '../lib/fs-utils.mjs';
+import { BundleUI } from '../lib/ui-utils.mjs';
+
+const { gatherUserSelections, validateSelections, autoSelectVersions } = WizardUtils;
+const { prepareProjectStructure, injectRulesets, injectPrompts } = RulesetInjector;
+const {
+  buildMasterInstructions,
+  buildPromptModeStub,
+  writeAgentConfig,
+  writeBacklogFiles,
+  writeGitignore,
+  writeManifest,
+} = InstructionAssembler;
+const { success } = ResultUtils;
+const { runIfDirect } = FsUtils;
+const {
+  printWelcome,
+  printStep,
+  printAborted,
+  printQuickSetupStart,
+  printProjectRoot,
+  printSuccessAgents,
+  printSuccessPrompts,
+  printQuickSuccess,
+  printQuickDryRun,
+  printDryRunPreview,
+  printBuildSummary,
+} = BundleUI;
+
+const require = createRequire(import.meta.url);
+const packageJson = require('../../../package.json');
+
+/**
+ * Entry point for both interactive (wizard) and non-interactive (flags) modes.
+ */
+async function run(targetDir = process.cwd(), options = {}) {
+  printWelcome();
+
+  if (options.selections) {
+    return runNonInteractive(targetDir, options);
+  }
+
+  return runInteractive(targetDir, options);
+}
+
+async function runNonInteractive(targetDir, options) {
+  const { dryRun = false, noDevGuides = false, selections } = options;
+
+  const validationResult = validateSelections(selections);
+  if (validationResult.isFailure) {
+    console.log(`\n  ⚠️  ${validationResult.error.message}`);
+    process.exit(1);
+  }
+
+  autoSelectVersions(selections);
+
+  const state = { step: 'execute', userSelections: selections };
+  const result = await handleFinalExecutionPhase(state, targetDir, {
+    dryRun,
+    noDevGuides,
+    skipConfirm: true,
+  });
+  if (result.isFailure) {
+    console.log(`\n  ⚠️  ${result.error.message}`);
+    process.exit(1);
+  }
+}
+
+async function runInteractive(targetDir, options) {
+  const state = { step: 'selections', userSelections: null };
+
+  while (state.step !== 'done') {
+    const result = await handleExecutionStep(state, targetDir, options);
+    if (result.isFailure) {
+      if (result.error.code !== 'USER_BACK') {
+        console.log(`\n  ⚠️  ${result.error.message}`);
+      }
+      return;
+    }
+  }
+}
+
+// --- Phase Handlers (Storytelling) ---
+
+async function handleExecutionStep(state, targetDir, options) {
+  switch (state.step) {
+    case 'selections':
+      return handleSelectionPhase(state, targetDir);
+    case 'execute':
+      return handleFinalExecutionPhase(state, targetDir, options);
+    default:
+      return success();
+  }
+}
+
+async function handleSelectionPhase(state, targetDir) {
+  const result = await gatherUserSelections(targetDir);
+  if (result.isFailure) return result;
+
+  state.userSelections = result.value;
+  state.step = 'execute';
+  return success();
+}
+
+async function handleFinalExecutionPhase(state, targetDir, options = {}) {
+  const { dryRun = false, noDevGuides = false, skipConfirm = false } = options;
+  const selections = state.userSelections;
+
+  if (selections.mode === 'quick') {
+    return runQuickMode(state, targetDir, { dryRun, noDevGuides });
+  }
+
+  if (dryRun) {
+    printDryRunPreview(selections, targetDir);
+    state.step = 'done';
+    return success();
+  }
+
+  if (selections.mode === 'prompts') {
+    return runPromptsMode(state, targetDir, selections, { skipConfirm });
+  }
+
+  return runAgentsMode(state, targetDir, selections, { skipConfirm, noDevGuides });
+}
+
+// --- Mode Runners (Narrative Orchestration) ---
+
+async function runQuickMode(state, targetDir, { dryRun, noDevGuides = false }) {
+  if (dryRun) return abortForDryRun(state, targetDir, printQuickDryRun);
+
+  printQuickSetupStart();
+  executeQuickPipeline(targetDir, state.userSelections, { noDevGuides });
+
+  printQuickSuccess(targetDir);
+  state.step = 'done';
+  return success();
+}
+
+async function runPromptsMode(state, targetDir, selections, { skipConfirm = false } = {}) {
+  const confirmed = skipConfirm || (await printBuildSummary(selections));
+  if (!confirmed) return abortExecution(state);
+
+  printProjectRoot(targetDir);
+  executePromptsPipeline(targetDir, selections);
+
+  printSuccessPrompts(targetDir);
+  state.step = 'done';
+  return success();
+}
+
+async function runAgentsMode(
+  state,
+  targetDir,
+  selections,
+  { skipConfirm = false, noDevGuides = false } = {}
+) {
+  const confirmed = skipConfirm || (await printBuildSummary(selections));
+  if (!confirmed) return abortExecution(state);
+
+  printProjectRoot(targetDir);
+  executeAgentsPipeline(targetDir, selections, { noDevGuides });
+
+  printSuccessAgents(targetDir);
+  state.step = 'done';
+  return success();
+}
+
+// --- Implementation Details ---
+
+function abortForDryRun(state, targetDir, printer) {
+  printer(targetDir);
+  state.step = 'done';
+  return success();
+}
+
+function abortExecution(state) {
+  printAborted();
+  state.step = 'done';
+  return success();
+}
+
+function executeQuickPipeline(targetDir, selections, { noDevGuides = false } = {}) {
+  printStep(1, 5, 'Preparing .ai/ structure...');
+  prepareProjectStructure(targetDir);
+
+  printStep(2, 5, 'Injecting rules and dev-guides...');
+  injectRulesets(targetDir, selections, { noDevGuides });
+
+  printStep(3, 5, 'Assembling AGENTS.md...');
+  const content = buildMasterInstructions(selections);
+
+  printStep(4, 5, 'Writing agent config and backlog...');
+  writeAgentConfig(targetDir, content, getActiveAgents(selections));
+  writeBacklogFiles(targetDir, selections);
+  writeGitignore(targetDir);
+
+  printStep(5, 5, 'Injecting spec templates...');
+  injectPrompts(targetDir, selections.track);
+  writeManifest(targetDir, selections, packageJson.version);
+}
+
+function executePromptsPipeline(targetDir, selections) {
+  printStep(1, 3, 'Preparing .ai/ structure...');
+  prepareProjectStructure(targetDir);
+
+  printStep(2, 3, `Injecting specification track: ${selections.track}...`);
+  injectPrompts(targetDir, selections.track);
+
+  printStep(3, 3, 'Writing prompts-only fallback config...');
+  const stubContent = buildPromptModeStub();
+  writeAgentConfig(targetDir, stubContent, getActiveAgents(selections));
+  writeGitignore(targetDir);
+}
+
+function executeAgentsPipeline(targetDir, selections, { noDevGuides = false } = {}) {
+  printStep(1, 5, 'Preparing .ai/ structure...');
+  prepareProjectStructure(targetDir);
+
+  printStep(2, 5, 'Injecting rules and dev-guides...');
+  injectRulesets(targetDir, selections, { noDevGuides });
+
+  printStep(3, 5, 'Assembling AGENTS.md...');
+  const content = buildMasterInstructions(selections);
+
+  printStep(4, 5, 'Writing agent config and backlog...');
+  writeAgentConfig(targetDir, content, getActiveAgents(selections));
+  writeBacklogFiles(targetDir, selections);
+  writeGitignore(targetDir);
+
+  printStep(5, 5, 'Finalizing manifest...');
+  writeManifest(targetDir, selections, packageJson.version);
+}
+
+function getActiveAgents(selections) {
+  const agentCandidates = [...(selections.agents || []), selections.ide];
+  const activeAgents = agentCandidates.filter((agent) => agent !== null && agent !== undefined);
+  return activeAgents;
+}
+
+export const SDG = {
+  run,
+};
+
+runIfDirect(import.meta.url, () => {
+  const targetDir = process.argv[2] ?? process.cwd();
+  const dryRun = process.argv.includes('--dry-run');
+  return run(path.resolve(targetDir), { dryRun });
+});

package/src/engine/bin/check-sync.mjs

@@ -0,0 +1,116 @@
+/**
+ * Check Sync — Detects drift between the source-of-truth assets and the live .ai/ directory.
+ * Compares only the mirrored directories — not flavor/ which is generated with a rename.
+ * The .ai/ directory is a curated subset of src/assets/ — not a full mirror.
+ *
+ * FOLLOWS: Narrative Cascade & Lexical Scoping (nested helpers)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { FsUtils } from '../lib/fs-utils.mjs';
+import { ResultUtils } from '../lib/result-utils.mjs';
+
+const { getDirname, runIfDirect } = FsUtils;
+const { success, fail } = ResultUtils;
+
+const __dirname = getDirname(import.meta.url);
+const MONOREPO_ROOT = path.join(__dirname, '..', '..', '..', '..', '..');
+const ASSETS_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', 'src', 'assets', 'instructions');
+const AI_DIR = path.join(MONOREPO_ROOT, 'packages', 'cli', '.ai', 'instructions');
+
+// why: flavor/ in .ai/ is populated by renaming flavors/{id}/ — no direct mirror exists in src/assets/flavor/
+const MIRRORED_DIRS = ['core', 'idioms', 'templates', 'competencies'];
+
+/**
+ * Compares files present in .ai/ mirrored directories against src/assets/.
+ * Reports any files that exist in .ai/ but differ from their src/assets/ counterpart.
+ */
+function run() {
+  const driftedFiles = [];
+
+  for (const mirroredDir of MIRRORED_DIRS) {
+    const liveDir = path.join(AI_DIR, mirroredDir);
+    const sourceDir = path.join(ASSETS_DIR, mirroredDir);
+    const dirDrifts = collectDriftedFiles(liveDir, sourceDir, mirroredDir);
+    driftedFiles.push(...dirDrifts);
+  }
+
+  const runResult = reportResult(driftedFiles);
+  return runResult;
+
+  // --- Scoped Internal Helpers (The Stepdown Rule & Lexical Scoping) ---
+
+  function collectDriftedFiles(liveDir, sourceDir, relPrefix) {
+    if (!fs.existsSync(liveDir)) return [];
+
+    const entries = fs.readdirSync(liveDir, { withFileTypes: true });
+    const localDrifts = [];
+
+    for (const entry of entries) {
+      const relPath = path.join(relPrefix, entry.name);
+      const livePath = path.join(liveDir, entry.name);
+      const sourcePath = path.join(sourceDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const nestedDrifts = collectDriftedFiles(livePath, sourcePath, relPath);
+        localDrifts.push(...nestedDrifts);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const fileDrift = checkFileDrift(livePath, sourcePath, relPath);
+        if (fileDrift !== null) localDrifts.push(fileDrift);
+      }
+    }
+
+    return localDrifts;
+  }
+
+  function checkFileDrift(livePath, sourcePath, relPath) {
+    if (!fs.existsSync(sourcePath)) {
+      const missingDrift = { relPath, reason: 'missing in src/assets/' };
+      return missingDrift;
+    }
+
+    const liveHash = hashFile(livePath);
+    const sourceHash = hashFile(sourcePath);
+
+    if (liveHash !== sourceHash) {
+      const contentDrift = { relPath, reason: 'content differs' };
+      return contentDrift;
+    }
+
+    return null;
+
+    function hashFile(filePath) {
+      const content = fs.readFileSync(filePath);
+      const fileHash = crypto.createHash('sha256').update(content).digest('hex');
+      return fileHash;
+    }
+  }
+
+  function reportResult(drifts) {
+    if (drifts.length === 0) {
+      console.log('\n  ✅ .ai/instructions/ is in sync with src/assets/instructions/\n');
+      const syncOk = success();
+      return syncOk;
+    }
+
+    console.error('\n  ❌ Drift detected — files in .ai/ differ from src/assets/:\n');
+    for (const drift of drifts) {
+      console.error(`     ${drift.relPath} (${drift.reason})`);
+    }
+    console.error(
+      '\n  Fix: apply the same edits to both copies, or re-run `npx sdg-agents init` to regenerate.\n'
+    );
+    const driftFailure = fail({ message: 'SYNC_DRIFT', count: drifts.length });
+    return driftFailure;
+  }
+}
+
+export const SyncChecker = { run };
+
+runIfDirect(import.meta.url, async () => {
+  const result = run();
+  if (result.isFailure) process.exit(1);
+});

package/src/engine/bin/clear-bundle.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { confirm } from '@inquirer/prompts';
+import { ResultUtils } from '../lib/result-utils.mjs';
+import { FsUtils } from '../lib/fs-utils.mjs';
+
+const { success } = ResultUtils;
+const { runIfDirect } = FsUtils;
+
+/**
+ * Spec Driven Guide — Reset/Clear Utility
+ * Deletes all generated SDG files and the .ia directory.
+ */
+async function run(targetDir = process.cwd(), options = {}) {
+  const dryRun = options.dryRun || process.argv.includes('--dry-run');
+
+  console.log('\n  Spec Driven Guide — Clear Generated Content');
+  console.log('  ' + '─'.repeat(50));
+
+  const itemsToRemove = ['.ia', '.ai', '.sdg-prompts'];
+  let existing = [];
+
+  // Check current directory
+  for (const item of itemsToRemove) {
+    const fullPath = path.join(targetDir, item);
+    if (fs.existsSync(fullPath)) {
+      existing.push({ name: item, fullPath });
+    }
+  }
+
+  // Check packages/* if we are in a monorepo
+  const packagesDir = path.join(targetDir, 'packages');
+  if (fs.existsSync(packagesDir)) {
+    const subPackages = fs.readdirSync(packagesDir);
+    for (const pkg of subPackages) {
+      for (const item of itemsToRemove) {
+        const fullPath = path.join(packagesDir, pkg, item);
+        if (fs.existsSync(fullPath)) {
+          existing.push({ name: `packages/${pkg}/${item}`, fullPath });
+        }
+      }
+    }
+  }
+
+  if (existing.length === 0) {
+    console.log('\n  ✅ No Spec Driven Guide content found to clear.\n');
+    return success();
+  }
+
+  if (dryRun) {
+    console.log('\n  [DRY RUN] The following items would be removed:');
+    for (const item of existing) {
+      console.log(`  - ${item.name}`);
+    }
+    console.log('\n  No files were deleted (dry-run mode).\n');
+    return success();
+  }
+
+  printWarning();
+  printItemsToRemove(existing);
+
+  const userConfirmed = await confirm({
+    message: '\n  Are you sure you want to proceed?',
+    default: false,
+  });
+
+  if (!userConfirmed) {
+    console.log('\n  Aborted. No files were deleted.\n');
+    return success();
+  }
+
+  executeCleanup(existing);
+
+  console.log('\n  ✨ Project cleared successfully!\n');
+  return success();
+}
+
+function printWarning() {
+  console.log('\n');
+  console.log('  ┌──────────────────────────────────────────────────────┐ ');
+  console.log('  │  ⚠️  WARNING: PERMANENT DELETION DETECTED             │ ');
+  console.log('  │  This action will IRREVERSIBLY remove all SDG rules, │ ');
+  console.log('  │  AI instructions, and project manifests.             │ ');
+  console.log('  └──────────────────────────────────────────────────────┘ ');
+}
+
+function printItemsToRemove(items) {
+  console.log('\n  The following items will be REMOVED:');
+  for (const item of items) {
+    console.log(`  - ${item.name}`);
+  }
+}
+
+function executeCleanup(items) {
+  console.log('\n  Cleaning up...');
+
+  for (const item of items) {
+    const { name, fullPath } = item;
+    try {
+      if (fs.statSync(fullPath).isDirectory()) {
+        fs.rmSync(fullPath, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(fullPath);
+      }
+      console.log(`  [OK] Removed ${name}`);
+    } catch (error) {
+      console.log(`  [FAIL] Could not remove ${name}: ${error.message}`);
+    }
+  }
+}
+
+export const Cleaner = {
+  run,
+};
+
+runIfDirect(import.meta.url, run);