agile-context-engineering 0.2.2 → 0.5.0

package/skills/plan-story/script.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+
+/**
+ * plan-story skill script — Entry point for all ace-tools operations
+ * needed by the plan-story skill.
+ *
+ * Subcommands:
+ *   init [story-param]        Environment detection for plan-story workflow
+ *   update-state story=X status=Y   Update story status across files
+ *   sync-github repo=X story_file=Y  Sync story/feature to GitHub
+ *   resolve-model <agent-type>       Get model for agent based on profile
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, safeReadFile, generateSlug, resolveModel,
+  detectBrownfieldStatus, loadSettings, execCommand,
+  output, error, parseKeyValueArgs,
+} = require('../../shared/lib/ace-core');
+
+const {
+  classifyStoryParam, extractStoryMetadata, extractStoryRequirements,
+  extractIssueNumber, extractIssueNumberFromFile, computeStoryPaths,
+  updateState,
+} = require('../../shared/lib/ace-story');
+
+const { syncStory, resolveFields, createIssue } = require('../../shared/lib/ace-github');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const cmd = args[0];
+
+switch (cmd) {
+  case 'init':
+    cmdInit(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'update-state':
+    updateState(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'sync-github':
+    syncStory(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'resolve-model': {
+    const agentType = args[1];
+    if (!agentType) error('resolve-model requires agent-type argument');
+    const model = resolveModel(cwd, agentType);
+    output({ model, agent: agentType }, raw, model);
+    break;
+  }
+  case 'generate-slug': {
+    const text = args.slice(1).filter(a => a !== '--raw').join(' ');
+    if (!text) error('generate-slug requires text argument');
+    const slug = generateSlug(text);
+    output({ slug }, raw, slug);
+    break;
+  }
+  case 'resolve-fields':
+    resolveFields(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'create-issue':
+    createIssue(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init, update-state, sync-github, resolve-model, generate-slug, resolve-fields, create-issue`);
+}
+
+// ─── Init: Plan Story ────────────────────────────────────────────────────────
+
+/**
+ * Environment detection for the plan-story workflow.
+ *
+ * Detects: git, gh CLI, GitHub project, brownfield status, wiki state,
+ * product artifacts, and story source/content/metadata.
+ *
+ * Supports three input modes:
+ *   - story param provided → loads existing file or fetches GitHub issue
+ *   - text param provided (no story) → uses inline text as seed description
+ *   - neither → new story mode, workflow handles placement
+ *
+ * initArgs: array of arguments — either a single positional path/URL,
+ *           or key=value pairs (story=X text=Y)
+ */
+function cmdInit(cwd, raw, initArgs) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  // ── Environment detection ──
+  const has_git = pathExists(cwd, '.git');
+  const has_gh_cli = (() => {
+    try {
+      const { execSync } = require('child_process');
+      execSync('gh --version', { stdio: 'pipe' });
+      return true;
+    } catch { return false; }
+  })();
+  const github_project = loadSettings(cwd).github_project;
+
+  // Wiki detection
+  const wikiSystemDir = '.docs/wiki/system-wide';
+  const has_wiki_system_wide = pathExists(cwd, wikiSystemDir);
+  const wikiSubsystemsDir = '.docs/wiki/subsystems';
+  const has_wiki_subsystems = pathExists(cwd, wikiSubsystemsDir);
+  let wiki_subsystem_names = [];
+  if (has_wiki_subsystems) {
+    try {
+      const entries = fs.readdirSync(path.join(cwd, wikiSubsystemsDir), { withFileTypes: true });
+      wiki_subsystem_names = entries.filter(e => e.isDirectory()).map(e => e.name);
+    } catch {}
+  }
+  const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
+
+  // ── Parse input: support both positional and key=value forms ──
+  // Positional: script.js init path/to/story.md
+  // Key-value:  script.js init story=path/to/story.md text="some description"
+  const hasKeyValue = initArgs.some(a => a.includes('='));
+  let resolvedStoryParam = null;
+  let textParam = null;
+
+  if (hasKeyValue) {
+    const kvArgs = parseKeyValueArgs(initArgs);
+    resolvedStoryParam = kvArgs.story || null;
+    textParam = kvArgs.text || null;
+  } else if (initArgs.length > 0) {
+    // Positional: treat entire arg list as the story param
+    resolvedStoryParam = initArgs.join(' ');
+  }
+
+  // ── Base result (shared across all modes) ──
+  const baseResult = {
+    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
+    commit_docs: config.commit_docs,
+    has_git, has_gh_cli, github_project,
+    ...brownfield,
+    has_wiki, has_wiki_system_wide, has_wiki_subsystems, wiki_subsystem_names,
+    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_product_backlog: pathExists(cwd, '.ace/artifacts/product/product-backlog.md'),
+  };
+
+  // ── Mode 1: No story param and no text → new story mode ──
+  if (!resolvedStoryParam && !textParam) {
+    output({
+      ...baseResult,
+      story_source: 'new',
+      story_valid: true,
+      story_error: null,
+      story_content: null,
+      story: { id: null, title: null, status: null, size: null, issue_number: null },
+      feature: { id: null, title: null, issue_number: null },
+      epic: { id: null, title: null },
+      user_story: null, description: null, acceptance_criteria_count: 0,
+      paths: null,
+      has_external_analysis: false, has_integration_analysis: false,
+      has_feature_file: false, has_story_file: false,
+    }, raw);
+    return;
+  }
+
+  // ── Mode 2: Text param only → use text as seed description ──
+  if (!resolvedStoryParam && textParam) {
+    output({
+      ...baseResult,
+      story_source: 'text',
+      story_valid: true,
+      story_error: null,
+      story_content: textParam,
+      story: { id: null, title: null, status: null, size: null, issue_number: null },
+      feature: { id: null, title: null, issue_number: null },
+      epic: { id: null, title: null },
+      user_story: null, description: textParam, acceptance_criteria_count: 0,
+      paths: null,
+      has_external_analysis: false, has_integration_analysis: false,
+      has_feature_file: false, has_story_file: false,
+    }, raw);
+    return;
+  }
+
+  // ── Mode 3: Story param provided → classify and load ──
+  const classified = classifyStoryParam(resolvedStoryParam);
+
+  // Invalid param
+  if (classified.type === null || classified.type === 'invalid') {
+    output({
+      ...baseResult,
+      story_source: null,
+      story_valid: false,
+      story_error: classified.reason || 'No story parameter provided',
+      story_content: null,
+      story: { id: null, title: null, status: null, size: null, issue_number: null },
+      feature: { id: null, title: null, issue_number: null },
+      epic: { id: null, title: null },
+      user_story: null, description: null, acceptance_criteria_count: 0,
+      paths: null,
+      has_external_analysis: false, has_integration_analysis: false,
+      has_feature_file: false, has_story_file: false,
+    }, raw);
+    return;
+  }
+
+  // ── Load story content ──
+  let storyContent = null;
+  let storySource = classified.type === 'file' ? 'file' : 'github';
+  let storyError = null;
+  let storyFilePath = null;
+
+  if (classified.type === 'file') {
+    const resolvedPath = path.isAbsolute(classified.filePath)
+      ? classified.filePath
+      : path.join(cwd, classified.filePath);
+    if (!pathExists(cwd, classified.filePath)) {
+      storyError = `Story file not found: ${classified.filePath}`;
+    } else {
+      storyContent = safeReadFile(resolvedPath);
+      storyFilePath = classified.filePath;
+      if (!storyContent) storyError = `Could not read story file: ${classified.filePath}`;
+    }
+  } else {
+    // github-url or issue-number
+    if (!has_gh_cli) {
+      storyError = 'GitHub CLI (gh) not installed. Cannot fetch GitHub issues.';
+    } else {
+      const repo = classified.repo || (github_project.repo || null);
+      if (!repo) {
+        storyError = 'No repository configured. Provide a full GitHub URL or configure github_project.repo in settings.';
+      } else {
+        const ghResult = execCommand(
+          `gh issue view ${classified.issueNumber} --repo ${repo} --json title,body,labels,state`,
+          cwd
+        );
+        if (!ghResult) {
+          storyError = `Could not fetch GitHub issue #${classified.issueNumber} from ${repo}.`;
+        } else {
+          try {
+            const issue = JSON.parse(ghResult);
+            storyContent = issue.body || '';
+            if (storyContent && !storyContent.match(/^#\s+/m)) {
+              storyContent = `# ${issue.title}\n\n${storyContent}`;
+            }
+          } catch {
+            storyError = `Failed to parse GitHub issue response for #${classified.issueNumber}.`;
+          }
+        }
+      }
+    }
+  }
+
+  // ── Extract metadata & requirements ──
+  const metadata = extractStoryMetadata(storyContent);
+  const requirements = extractStoryRequirements(storyContent);
+
+  // ── Compute paths ──
+  let paths = null;
+  let has_story_file = false;
+
+  if (storyFilePath) {
+    const resolvedPath = path.isAbsolute(storyFilePath)
+      ? storyFilePath
+      : path.join(cwd, storyFilePath);
+    const storyDir = path.dirname(resolvedPath);
+    const relStoryDir = path.relative(cwd, storyDir).replace(/\\/g, '/');
+    const storySlug = path.basename(storyDir);
+    const featureDir = path.dirname(storyDir);
+    const relFeatureDir = path.relative(cwd, featureDir).replace(/\\/g, '/');
+    const featureSlug = path.basename(featureDir);
+
+    paths = {
+      epic_slug: null,
+      feature_slug: featureSlug,
+      story_slug: storySlug,
+      story_dir: relStoryDir,
+      story_file: storyFilePath.replace(/\\/g, '/'),
+      external_analysis_file: `${relStoryDir}/external-analysis.md`,
+      integration_analysis_file: `${relStoryDir}/integration-analysis.md`,
+      feature_dir: relFeatureDir,
+      feature_file: `${relFeatureDir}/${featureSlug}.md`,
+    };
+    has_story_file = true;
+  } else if (metadata.epic.id && metadata.feature.id && metadata.id) {
+    paths = computeStoryPaths(
+      metadata.epic.id, metadata.epic.title || '',
+      metadata.feature.id, metadata.feature.title || '',
+      metadata.id, metadata.title || ''
+    );
+    has_story_file = paths ? pathExists(cwd, paths.story_file) : false;
+  }
+
+  // ── Check artifact existence ──
+  const has_external_analysis = paths ? pathExists(cwd, paths.external_analysis_file) : false;
+  const has_integration_analysis = paths ? pathExists(cwd, paths.integration_analysis_file) : false;
+  const has_feature_file = paths ? pathExists(cwd, paths.feature_file) : false;
+
+  // ── Build result ──
+  output({
+    ...baseResult,
+    story_source: storySource,
+    story_valid: storyContent !== null && storyError === null,
+    story_error: storyError,
+    story_content: storyContent,
+    story: {
+      id: metadata.id,
+      title: metadata.title,
+      status: metadata.status,
+      size: metadata.size,
+      issue_number: extractIssueNumber(metadata.link),
+    },
+    feature: {
+      ...metadata.feature,
+      issue_number: paths ? extractIssueNumberFromFile(cwd, paths.feature_file) : null,
+    },
+    epic: metadata.epic,
+    user_story: requirements.user_story,
+    description: requirements.description,
+    acceptance_criteria_count: requirements.acceptance_criteria_count,
+    paths,
+    has_external_analysis,
+    has_integration_analysis,
+    has_feature_file,
+    has_story_file,
+  }, raw);
+}

package/skills/plan-story/script.test.js

@@ -0,0 +1,240 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+/**
+ * Create a minimal ACE project structure in a temp directory.
+ */
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  // .ace/config.json
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  // .ace/settings.json
+  fs.writeFileSync(path.join(aceDir, 'settings.json'), JSON.stringify({
+    model_profile: 'quality',
+    commit_docs: true,
+    agent_teams: false,
+    github_project: { enabled: false, gh_installed: false, repo: '', project_number: null, owner: '' },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+/**
+ * Create a story file in the test project.
+ */
+function createStoryFile(tmpDir, relPath, content) {
+  const fullPath = path.join(tmpDir, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, 'utf-8');
+  return relPath;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('plan-story script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection for a story file', () => {
+      const storyContent = [
+        '# S1: Add Login Button',
+        '**Feature**: F1 User Auth | **Epic**: E1 Platform',
+        '**Status**: Todo | **Size**: 3 | **Sprint**: — | **Link**: —',
+        '',
+        '## User Story',
+        '',
+        '> As a user,',
+        '> I want to click a login button,',
+        '> so that I can access my account.',
+        '',
+        '## Description',
+        '',
+        'Adds a login button to the header.',
+        '',
+        '## Acceptance Criteria',
+        '',
+        '### Scenario: Click login button',
+        '',
+        '**Given** the user is on the homepage',
+        '**When** they click "Login"',
+        '**Then** they see the login form',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-platform/f1-user-auth/s1-add-login-button/s1-add-login-button.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('init', storyPath, tmpDir));
+
+      assert.ok(result.product_owner_model, 'should have product_owner_model');
+      assert.strictEqual(result.story_valid, true, 'story should be valid');
+      assert.strictEqual(result.story_source, 'file');
+      assert.strictEqual(result.story.id, 'S1');
+      assert.strictEqual(result.story.title, 'Add Login Button');
+      assert.strictEqual(result.story.status, 'Todo');
+      assert.strictEqual(result.acceptance_criteria_count, 1);
+      assert.ok(result.paths, 'should have computed paths');
+      assert.ok(result.paths.story_file.includes('s1-add-login-button'));
+      assert.strictEqual(result.has_story_file, true);
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+    });
+
+    it('returns valid result for new story mode (no params)', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(result.story_source, 'new');
+      assert.strictEqual(result.story_valid, true);
+      assert.strictEqual(result.story_content, null);
+      assert.strictEqual(result.story.id, null);
+      assert.strictEqual(result.paths, null);
+    });
+
+    it('returns valid result for text mode', () => {
+      const result = JSON.parse(runScript('init', 'text="User can reset password"', tmpDir));
+
+      assert.strictEqual(result.story_source, 'text');
+      assert.strictEqual(result.story_valid, true);
+      assert.strictEqual(result.story_content, 'User can reset password');
+      assert.strictEqual(result.description, 'User can reset password');
+      assert.strictEqual(result.story.id, null);
+    });
+
+    it('handles non-existent story file gracefully', () => {
+      const result = JSON.parse(runScript('init', 'nonexistent/story.md', tmpDir));
+
+      assert.strictEqual(result.story_valid, false);
+      assert.ok(result.story_error.includes('not found'));
+    });
+
+    it('returns brownfield detection fields', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+
+  describe('resolve-model', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns a model string with --raw', () => {
+      const result = runScript('resolve-model', 'ace-product-owner --raw', tmpDir).trim();
+      assert.match(result, /^(opus|sonnet|haiku)$/);
+    });
+
+    it('returns JSON without --raw', () => {
+      const result = JSON.parse(runScript('resolve-model', 'ace-product-owner', tmpDir));
+      assert.ok(result.model);
+      assert.strictEqual(result.agent, 'ace-product-owner');
+    });
+
+    it('returns sonnet for unknown agent type', () => {
+      const result = runScript('resolve-model', 'unknown-agent --raw', tmpDir).trim();
+      assert.strictEqual(result, 'sonnet');
+    });
+  });
+
+  describe('update-state', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('updates story status in the story file', () => {
+      const storyContent = [
+        '# S1: Test Story',
+        '**Feature**: F1 Test Feature | **Epic**: E1 Test Epic',
+        '**Status**: Todo | **Size**: 3 | **Sprint**: — | **Link**: —',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test-epic/f1-test-feature/s1-test-story/s1-test-story.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('update-state', `story=${storyPath} status=Refined`, tmpDir));
+
+      assert.strictEqual(result.story_updated, true);
+      assert.strictEqual(result.new_status, 'Refined');
+
+      // Verify file was actually updated
+      const updated = fs.readFileSync(path.join(tmpDir, storyPath), 'utf-8');
+      assert.ok(updated.includes('**Status**: Refined'));
+    });
+
+    it('normalizes InProgress to "In Progress"', () => {
+      const storyContent = [
+        '# S2: Another Story',
+        '**Feature**: F1 Test Feature | **Epic**: E1 Test Epic',
+        '**Status**: Refined | **Size**: 2 | **Sprint**: — | **Link**: —',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test-epic/f1-test-feature/s2-another-story/s2-another-story.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('update-state', `story=${storyPath} status=InProgress`, tmpDir));
+
+      assert.strictEqual(result.new_status, 'In Progress');
+
+      const updated = fs.readFileSync(path.join(tmpDir, storyPath), 'utf-8');
+      assert.ok(updated.includes('**Status**: In Progress'));
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+
+    it('errors on resolve-model without agent type', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" resolve-model`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});