agile-context-engineering 0.3.0 → 0.5.0

package/shared/lib/ace-core.js

@@ -0,0 +1,308 @@
+/**
+ * ACE Core — Universal helpers shared across all ACE skills.
+ *
+ * Extracted from ace-tools.js monolith. Contains: config loading, model resolution,
+ * path checks, environment detection, slug/timestamp generation, settings management,
+ * and process-level output/error helpers.
+ *
+ * Usage: const { loadConfig, resolveModel, output, error } = require('./ace-core');
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Model Profile Table ─────────────────────────────────────────────────────
+
+const MODEL_PROFILES = {
+  'ace-product-owner':            { quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'ace-project-researcher':       { quality: 'opus',   balanced: 'sonnet', budget: 'haiku' },
+  'ace-research-synthesizer':     { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'ace-wiki-mapper':              { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'ace-code-integration-analyst': { quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'ace-code-discovery-analyst':   { quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'ace-executor':                 { quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'ace-code-reviewer':            { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+
+// ─── Settings Defaults ───────────────────────────────────────────────────────
+
+const SETTINGS_DEFAULTS = {
+  model_profile: 'balanced',
+  commit_docs: true,
+  agent_teams: false,
+  github_project: {
+    enabled: false,
+    gh_installed: false,
+    repo: '',
+    project_number: null,
+    owner: '',
+  },
+};
+
+// ─── Process Output ──────────────────────────────────────────────────────────
+
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue));
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2));
+  }
+  process.exit(0);
+}
+
+function error(message) {
+  process.stderr.write('Error: ' + message + '\n');
+  process.exit(1);
+}
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+function loadConfig(cwd) {
+  const configPath = path.join(cwd, '.ace', 'config.json');
+  const defaults = {
+    version: '0.1.0',
+    projectName: '',
+    description: '',
+    storage: 'local',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: {
+      enabled: false,
+      repo: null,
+      labels: {
+        epic: 'ace:epic',
+        feature: 'ace:feature',
+        story: 'ace:story',
+        task: 'ace:task',
+      },
+    },
+    createdAt: '',
+  };
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return {
+      version: parsed.version ?? defaults.version,
+      projectName: parsed.projectName ?? defaults.projectName,
+      description: parsed.description ?? defaults.description,
+      storage: parsed.storage ?? defaults.storage,
+      model_profile: parsed.model_profile ?? defaults.model_profile,
+      commit_docs: parsed.commit_docs ?? defaults.commit_docs,
+      github: {
+        enabled: parsed.github?.enabled ?? defaults.github.enabled,
+        repo: parsed.github?.repo ?? defaults.github.repo,
+        labels: {
+          epic: parsed.github?.labels?.epic ?? defaults.github.labels.epic,
+          feature: parsed.github?.labels?.feature ?? defaults.github.labels.feature,
+          story: parsed.github?.labels?.story ?? defaults.github.labels.story,
+          task: parsed.github?.labels?.task ?? defaults.github.labels.task,
+        },
+      },
+      createdAt: parsed.createdAt ?? defaults.createdAt,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+// ─── Path Helpers ────────────────────────────────────────────────────────────
+
+function pathExists(cwd, targetPath) {
+  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+  try {
+    fs.statSync(fullPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeReadFile(filePath) {
+  try { return fs.readFileSync(filePath, 'utf-8'); }
+  catch { return null; }
+}
+
+// ─── Slug & Timestamp ────────────────────────────────────────────────────────
+
+function generateSlug(text) {
+  if (!text) return null;
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function currentTimestamp(format) {
+  const now = new Date();
+  switch (format) {
+    case 'date':
+      return now.toISOString().split('T')[0];
+    case 'filename':
+      return now.toISOString().replace(/[:.]/g, '-').replace('T', '_').split('Z')[0];
+    case 'full':
+    default:
+      return now.toISOString();
+  }
+}
+
+// ─── Model Resolution ────────────────────────────────────────────────────────
+
+function resolveModel(cwd, agentType) {
+  const config = loadConfig(cwd);
+  const profile = config.model_profile || 'balanced';
+  const agentModels = MODEL_PROFILES[agentType];
+  if (!agentModels) return 'sonnet';
+  return agentModels[profile] || agentModels['balanced'] || 'sonnet';
+}
+
+// ─── Code & Environment Detection ────────────────────────────────────────────
+
+/**
+ * Detect existing code files by walking up to maxDepth levels.
+ */
+function detectCodeFiles(cwd, maxDepth) {
+  const codeExtensions = new Set(['.cs', '.ts', '.js', '.py', '.go', '.rs', '.swift', '.java', '.tsx', '.jsx']);
+  const ignoreDirs = new Set(['node_modules', '.git', '.ace', '.gsd', 'dist', 'build', '__pycache__']);
+  const found = [];
+
+  function walk(dir, depth) {
+    if (depth > maxDepth || found.length >= 5) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (found.length >= 5) return;
+      if (entry.isDirectory()) {
+        if (!ignoreDirs.has(entry.name)) {
+          walk(path.join(dir, entry.name), depth + 1);
+        }
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (codeExtensions.has(ext)) {
+          found.push(path.join(dir, entry.name));
+        }
+      }
+    }
+  }
+
+  walk(cwd, 0);
+  return found;
+}
+
+/**
+ * Detect whether the project is brownfield (existing code/manifests) or greenfield.
+ */
+function detectBrownfieldStatus(cwd) {
+  const codeFiles = detectCodeFiles(cwd, 3);
+  const hasExistingCode = codeFiles.length > 0;
+
+  const packageFiles = [
+    'package.json', 'requirements.txt', 'pyproject.toml', 'Cargo.toml',
+    'go.mod', 'Package.swift', 'pom.xml', 'build.gradle',
+  ];
+
+  const hasDotnetProject = (() => {
+    try {
+      const rootFiles = fs.readdirSync(cwd);
+      return rootFiles.some(f => f.endsWith('.sln') || f.endsWith('.csproj'));
+    } catch {
+      return false;
+    }
+  })();
+
+  const hasPackageFile = packageFiles.some(f => pathExists(cwd, f)) || hasDotnetProject;
+  const isBrownfield = hasExistingCode || hasPackageFile;
+
+  return {
+    has_existing_code: hasExistingCode,
+    has_package_file: hasPackageFile,
+    is_brownfield: isBrownfield,
+    is_greenfield: !isBrownfield,
+  };
+}
+
+// ─── Settings ────────────────────────────────────────────────────────────────
+
+function loadSettings(cwd) {
+  const settingsPath = path.join(cwd, '.ace', 'settings.json');
+  try {
+    const raw = fs.readFileSync(settingsPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return {
+      model_profile: parsed.model_profile ?? SETTINGS_DEFAULTS.model_profile,
+      commit_docs: parsed.commit_docs ?? SETTINGS_DEFAULTS.commit_docs,
+      agent_teams: parsed.agent_teams ?? SETTINGS_DEFAULTS.agent_teams,
+      github_project: {
+        enabled: parsed.github_project?.enabled ?? SETTINGS_DEFAULTS.github_project.enabled,
+        gh_installed: parsed.github_project?.gh_installed ?? SETTINGS_DEFAULTS.github_project.gh_installed,
+        repo: parsed.github_project?.repo ?? SETTINGS_DEFAULTS.github_project.repo,
+        project_number: parsed.github_project?.project_number ?? SETTINGS_DEFAULTS.github_project.project_number,
+        owner: parsed.github_project?.owner ?? SETTINGS_DEFAULTS.github_project.owner,
+      },
+    };
+  } catch {
+    return JSON.parse(JSON.stringify(SETTINGS_DEFAULTS));
+  }
+}
+
+function writeSettings(cwd, settings) {
+  const aceDir = path.join(cwd, '.ace');
+  if (!fs.existsSync(aceDir)) {
+    fs.mkdirSync(aceDir, { recursive: true });
+  }
+  const settingsPath = path.join(aceDir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+
+// ─── Shell Execution ─────────────────────────────────────────────────────────
+
+/**
+ * Parse key=value arguments into an object.
+ */
+function parseKeyValueArgs(args) {
+  const result = {};
+  for (const arg of args) {
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex === -1) continue;
+    result[arg.substring(0, eqIndex)] = arg.substring(eqIndex + 1);
+  }
+  return result;
+}
+
+/**
+ * Run a shell command and return trimmed stdout. Returns null on failure.
+ */
+function execCommand(cmd, cwd) {
+  const { execSync } = require('child_process');
+  try {
+    return execSync(cmd, {
+      cwd,
+      shell: 'bash',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+      timeout: 30000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  SETTINGS_DEFAULTS,
+  output,
+  error,
+  loadConfig,
+  pathExists,
+  safeReadFile,
+  generateSlug,
+  currentTimestamp,
+  resolveModel,
+  detectCodeFiles,
+  detectBrownfieldStatus,
+  loadSettings,
+  writeSettings,
+  parseKeyValueArgs,
+  execCommand,
+};

package/shared/lib/ace-core.test.js

@@ -0,0 +1,308 @@
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const {
+  loadConfig, pathExists, safeReadFile, generateSlug, currentTimestamp,
+  resolveModel, detectBrownfieldStatus,
+  loadSettings, writeSettings, parseKeyValueArgs, MODEL_PROFILES,
+} = require('./ace-core');
+
+function createTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ace-core-test-'));
+}
+
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ─── generateSlug ────────────────────────────────────────────────────────────
+
+describe('generateSlug', () => {
+  it('converts text to lowercase slug', () => {
+    assert.strictEqual(generateSlug('Hello World'), 'hello-world');
+  });
+
+  it('handles special characters', () => {
+    assert.strictEqual(generateSlug('User Authentication & Login!!!'), 'user-authentication-login');
+  });
+
+  it('trims leading and trailing dashes', () => {
+    assert.strictEqual(generateSlug('---hello---'), 'hello');
+  });
+
+  it('returns null for empty input', () => {
+    assert.strictEqual(generateSlug(''), null);
+    assert.strictEqual(generateSlug(null), null);
+    assert.strictEqual(generateSlug(undefined), null);
+  });
+
+  it('handles multi-word input', () => {
+    assert.strictEqual(generateSlug('Platform Foundation Setup'), 'platform-foundation-setup');
+  });
+
+  it('handles numeric IDs in text', () => {
+    assert.strictEqual(generateSlug('E1-Platform Foundation'), 'e1-platform-foundation');
+    assert.strictEqual(generateSlug('#45-User Auth'), '45-user-auth');
+  });
+});
+
+// ─── currentTimestamp ────────────────────────────────────────────────────────
+
+describe('currentTimestamp', () => {
+  it('returns full ISO timestamp by default', () => {
+    const ts = currentTimestamp('full');
+    assert.match(ts, /^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it('returns date-only format', () => {
+    const ts = currentTimestamp('date');
+    assert.match(ts, /^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  it('returns filename-safe format', () => {
+    const ts = currentTimestamp('filename');
+    assert.ok(!ts.includes(':'), 'should not contain colons');
+    assert.ok(ts.includes('_'), 'should contain underscore separator');
+  });
+});
+
+// ─── loadConfig ──────────────────────────────────────────────────────────────
+
+describe('loadConfig', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('returns defaults when no config file exists', () => {
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.version, '0.1.0');
+    assert.strictEqual(config.projectName, '');
+    assert.strictEqual(config.storage, 'local');
+    assert.strictEqual(config.commit_docs, true);
+    assert.strictEqual(config.github.enabled, false);
+    assert.strictEqual(config.github.labels.epic, 'ace:epic');
+  });
+
+  it('reads existing config and merges with defaults', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.ace', 'config.json'), JSON.stringify({
+      projectName: 'Test Project',
+      github: { enabled: true, repo: 'owner/repo' },
+    }));
+
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.projectName, 'Test Project');
+    assert.strictEqual(config.github.enabled, true);
+    assert.strictEqual(config.github.repo, 'owner/repo');
+    assert.strictEqual(config.version, '0.1.0'); // default
+    assert.strictEqual(config.github.labels.epic, 'ace:epic'); // default
+  });
+
+  it('handles malformed JSON gracefully', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.ace', 'config.json'), 'not json');
+
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.version, '0.1.0');
+  });
+});
+
+// ─── pathExists ──────────────────────────────────────────────────────────────
+
+describe('pathExists', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('returns true for existing directory', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    assert.strictEqual(pathExists(tmpDir, '.ace'), true);
+  });
+
+  it('returns false for non-existent path', () => {
+    assert.strictEqual(pathExists(tmpDir, '.ace/config.json'), false);
+  });
+
+  it('returns true for existing file', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.ace', 'config.json'), '{}');
+    assert.strictEqual(pathExists(tmpDir, '.ace/config.json'), true);
+  });
+});
+
+// ─── safeReadFile ────────────────────────────────────────────────────────────
+
+describe('safeReadFile', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('reads file content', () => {
+    const fp = path.join(tmpDir, 'test.txt');
+    fs.writeFileSync(fp, 'hello');
+    assert.strictEqual(safeReadFile(fp), 'hello');
+  });
+
+  it('returns null for non-existent file', () => {
+    assert.strictEqual(safeReadFile(path.join(tmpDir, 'nope.txt')), null);
+  });
+});
+
+// ─── resolveModel ────────────────────────────────────────────────────────────
+
+describe('resolveModel', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('returns quality model for ace-product-owner', () => {
+    assert.strictEqual(resolveModel(tmpDir, 'ace-product-owner'), 'opus');
+  });
+
+  it('returns quality model for ace-code-reviewer', () => {
+    assert.strictEqual(resolveModel(tmpDir, 'ace-code-reviewer'), 'sonnet');
+  });
+
+  it('respects budget profile from config', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.ace', 'config.json'), JSON.stringify({
+      model_profile: 'budget',
+    }));
+    assert.strictEqual(resolveModel(tmpDir, 'ace-product-owner'), 'sonnet');
+  });
+
+  it('returns sonnet for unknown agent type', () => {
+    assert.strictEqual(resolveModel(tmpDir, 'unknown-agent'), 'sonnet');
+  });
+});
+
+// ─── detectCodeFiles & detectBrownfieldStatus ────────────────────────────────
+
+describe('detectBrownfieldStatus', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('detects greenfield (empty project)', () => {
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.is_greenfield, true);
+    assert.strictEqual(result.is_brownfield, false);
+  });
+
+  it('detects brownfield with code files', () => {
+    fs.writeFileSync(path.join(tmpDir, 'index.js'), 'console.log("hello");');
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.is_brownfield, true);
+    assert.strictEqual(result.has_existing_code, true);
+  });
+
+  it('detects brownfield with package file only', () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.is_brownfield, true);
+    assert.strictEqual(result.has_package_file, true);
+  });
+
+  it('ignores node_modules', () => {
+    fs.mkdirSync(path.join(tmpDir, 'node_modules', 'pkg'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'node_modules', 'pkg', 'index.js'), '');
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.has_existing_code, false);
+  });
+
+  it('detects nested code files up to depth 3', () => {
+    const nested = path.join(tmpDir, 'src', 'lib', 'utils');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.writeFileSync(path.join(nested, 'helper.ts'), 'export const x = 1;');
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.has_existing_code, true);
+  });
+
+  it('detects .csproj as package file', () => {
+    fs.writeFileSync(path.join(tmpDir, 'App.csproj'), '<Project />');
+    const result = detectBrownfieldStatus(tmpDir);
+    assert.strictEqual(result.has_package_file, true);
+  });
+});
+
+// ─── loadSettings / writeSettings ────────────────────────────────────────────
+
+describe('loadSettings / writeSettings', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('returns defaults when no settings file exists', () => {
+    const settings = loadSettings(tmpDir);
+    assert.strictEqual(settings.model_profile, 'balanced');
+    assert.strictEqual(settings.commit_docs, true);
+    assert.strictEqual(settings.github_project.enabled, false);
+  });
+
+  it('reads existing settings', () => {
+    fs.mkdirSync(path.join(tmpDir, '.ace'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.ace', 'settings.json'), JSON.stringify({
+      model_profile: 'quality',
+      github_project: { enabled: true, repo: 'owner/repo' },
+    }));
+    const settings = loadSettings(tmpDir);
+    assert.strictEqual(settings.model_profile, 'quality');
+    assert.strictEqual(settings.github_project.enabled, true);
+  });
+
+  it('writes settings and creates .ace directory', () => {
+    const settings = { model_profile: 'budget', commit_docs: false };
+    writeSettings(tmpDir, settings);
+
+    const written = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+    assert.strictEqual(written.model_profile, 'budget');
+    assert.strictEqual(written.commit_docs, false);
+  });
+});
+
+// ─── parseKeyValueArgs ───────────────────────────────────────────────────────
+
+describe('parseKeyValueArgs', () => {
+  it('parses key=value pairs', () => {
+    const result = parseKeyValueArgs(['story=path/to/file', 'status=Refined']);
+    assert.strictEqual(result.story, 'path/to/file');
+    assert.strictEqual(result.status, 'Refined');
+  });
+
+  it('handles values with equals signs', () => {
+    const result = parseKeyValueArgs(['query=a=b']);
+    assert.strictEqual(result.query, 'a=b');
+  });
+
+  it('ignores args without equals', () => {
+    const result = parseKeyValueArgs(['--raw', 'story=file.md']);
+    assert.strictEqual(result.story, 'file.md');
+    assert.strictEqual(result['--raw'], undefined);
+  });
+
+  it('returns empty object for empty input', () => {
+    const result = parseKeyValueArgs([]);
+    assert.deepStrictEqual(result, {});
+  });
+});
+
+// ─── MODEL_PROFILES ──────────────────────────────────────────────────────────
+
+describe('MODEL_PROFILES', () => {
+  it('has entries for all known agent types', () => {
+    const agents = [
+      'ace-product-owner', 'ace-project-researcher', 'ace-research-synthesizer',
+      'ace-wiki-mapper', 'ace-code-integration-analyst', 'ace-code-discovery-analyst',
+      'ace-executor', 'ace-code-reviewer',
+    ];
+    for (const agent of agents) {
+      assert.ok(MODEL_PROFILES[agent], `Missing profile for ${agent}`);
+      assert.ok(MODEL_PROFILES[agent].quality, `Missing quality for ${agent}`);
+      assert.ok(MODEL_PROFILES[agent].balanced, `Missing balanced for ${agent}`);
+      assert.ok(MODEL_PROFILES[agent].budget, `Missing budget for ${agent}`);
+    }
+  });
+});