godpowers 0.15.0

package/lib/suite-state.js

@@ -0,0 +1,220 @@
+/**
+ * Suite State Manager
+ *
+ * Aggregates per-repo state.json into a suite-level view.
+ *
+ * Storage:
+ *   <hub>/.godpowers/suite/state.json   (machine-readable aggregate)
+ *   <hub>/.godpowers/suite/STATE.md      (human-readable summary)
+ *   <hub>/.godpowers/suite/SYNC-LOG.md   (append-only history)
+ *
+ * Public API:
+ *   readSuiteState(hubPath) -> { repos, totals, lastSync }
+ *   writeSuiteState(hubPath, data) -> void
+ *   refreshFromRepos(hubPath) -> data (re-aggregate now)
+ *   appendSyncLog(hubPath, entry) -> void
+ *   format(hubPath) -> markdown summary
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const detector = require('./multi-repo-detector');
+
+function suiteDir(hubPath) {
+  return path.join(hubPath, '.godpowers', 'suite');
+}
+
+function suiteStatePath(hubPath) {
+  return path.join(suiteDir(hubPath), 'state.json');
+}
+
+function suiteStateMdPath(hubPath) {
+  return path.join(suiteDir(hubPath), 'STATE.md');
+}
+
+function suiteSyncLogPath(hubPath) {
+  return path.join(suiteDir(hubPath), 'SYNC-LOG.md');
+}
+
+function ensureSuiteDir(hubPath) {
+  fs.mkdirSync(suiteDir(hubPath), { recursive: true });
+}
+
+/**
+ * Read the persisted suite state.
+ */
+function readSuiteState(hubPath) {
+  const file = suiteStatePath(hubPath);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Write the suite state JSON.
+ */
+function writeSuiteState(hubPath, data) {
+  ensureSuiteDir(hubPath);
+  fs.writeFileSync(suiteStatePath(hubPath), JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Walk siblings, read each repo's state.json, build aggregate.
+ */
+function refreshFromRepos(hubPath) {
+  const config = detector.readSuiteConfig(hubPath);
+  if (!config) return null;
+
+  const siblings = (config.siblings || []).map(sib => {
+    if (typeof sib === 'string') return { name: sib, path: path.resolve(hubPath, sib) };
+    return { name: sib.name, path: path.resolve(hubPath, sib.path || sib.name) };
+  });
+
+  const repos = [];
+  let totalArtifacts = 0;
+  let totalDrift = 0;
+  let totalReviews = 0;
+  let totalCoverage = 0;
+  let coverageCount = 0;
+
+  for (const sib of siblings) {
+    const statePath = path.join(sib.path, '.godpowers', 'state.json');
+    if (!fs.existsSync(statePath)) {
+      repos.push({ name: sib.name, path: sib.path, status: 'no-state' });
+      continue;
+    }
+    try {
+      const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      const tiers = state.tiers || {};
+      const linkage = state.linkage || {};
+
+      // Count completed artifacts
+      let completedArtifacts = 0;
+      for (const tier of Object.values(tiers)) {
+        for (const sub of Object.values(tier)) {
+          if (sub && sub.status === 'done') completedArtifacts++;
+        }
+      }
+
+      const repoSummary = {
+        name: sib.name,
+        path: sib.path,
+        mode: state.project && state.project.mode,
+        scale: state.project && state.project.scale,
+        lifecyclePhase: state['lifecycle-phase'],
+        completedArtifacts,
+        linkage: {
+          coveragePct: linkage['coverage-pct'] || 0,
+          orphanCount: linkage['orphan-count'] || 0,
+          driftCount: linkage['drift-count'] || 0,
+          reviewRequiredItems: linkage['review-required-items'] || 0
+        }
+      };
+      repos.push(repoSummary);
+
+      totalArtifacts += completedArtifacts;
+      totalDrift += repoSummary.linkage.driftCount;
+      totalReviews += repoSummary.linkage.reviewRequiredItems;
+      totalCoverage += repoSummary.linkage.coveragePct;
+      coverageCount++;
+    } catch (e) {
+      repos.push({ name: sib.name, path: sib.path, status: 'parse-error', error: e.message });
+    }
+  }
+
+  const data = {
+    version: '1.0.0',
+    hubPath,
+    refreshedAt: new Date().toISOString(),
+    repos,
+    totals: {
+      artifacts: totalArtifacts,
+      drift: totalDrift,
+      reviewRequired: totalReviews,
+      avgCoverage: coverageCount > 0 ? totalCoverage / coverageCount : 0
+    }
+  };
+  writeSuiteState(hubPath, data);
+  writeStateMd(hubPath, data);
+  return data;
+}
+
+/**
+ * Write a human-readable STATE.md from the aggregate.
+ */
+function writeStateMd(hubPath, data) {
+  ensureSuiteDir(hubPath);
+  const lines = [];
+  lines.push(`# Suite State`);
+  lines.push('');
+  lines.push(`Refreshed: ${data.refreshedAt}`);
+  lines.push(`Hub: ${data.hubPath}`);
+  lines.push('');
+  lines.push(`## Aggregate`);
+  lines.push('');
+  lines.push(`- Total artifacts complete: ${data.totals.artifacts}`);
+  lines.push(`- Total drift findings: ${data.totals.drift}`);
+  lines.push(`- Pending reviews: ${data.totals.reviewRequired}`);
+  lines.push(`- Average linkage coverage: ${(data.totals.avgCoverage * 100).toFixed(0)}%`);
+  lines.push('');
+  lines.push(`## Per-repo`);
+  lines.push('');
+  lines.push('| Repo | Mode | Phase | Artifacts | Coverage | Drift | Reviews |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const repo of data.repos) {
+    if (repo.status) {
+      lines.push(`| ${repo.name} | (${repo.status}) | - | - | - | - | - |`);
+      continue;
+    }
+    const cov = repo.linkage.coveragePct ? `${(repo.linkage.coveragePct * 100).toFixed(0)}%` : '-';
+    lines.push(
+      `| ${repo.name} | ${repo.mode || '-'} | ${repo.lifecyclePhase || '-'} | ${repo.completedArtifacts} | ${cov} | ${repo.linkage.driftCount} | ${repo.linkage.reviewRequiredItems} |`
+    );
+  }
+  lines.push('');
+  fs.writeFileSync(suiteStateMdPath(hubPath), lines.join('\n'));
+}
+
+/**
+ * Append to SYNC-LOG.md.
+ */
+function appendSyncLog(hubPath, entry) {
+  ensureSuiteDir(hubPath);
+  const file = suiteSyncLogPath(hubPath);
+  const ts = new Date().toISOString();
+  const header = !fs.existsSync(file) ? `# Suite Sync Log\n\nAppend-only history of suite-level operations.\n\n` : '';
+  const block = `## ${ts}\n\n${entry}\n\n`;
+  if (header) {
+    fs.writeFileSync(file, header + block);
+  } else {
+    fs.appendFileSync(file, block);
+  }
+}
+
+/**
+ * Format the current suite state as a string (for /god-suite-status).
+ */
+function format(hubPath) {
+  const data = readSuiteState(hubPath);
+  if (!data) return 'No suite state. Run /god-suite-init first.';
+  if (fs.existsSync(suiteStateMdPath(hubPath))) {
+    return fs.readFileSync(suiteStateMdPath(hubPath), 'utf8');
+  }
+  return JSON.stringify(data, null, 2);
+}
+
+module.exports = {
+  suiteDir,
+  suiteStatePath,
+  suiteStateMdPath,
+  suiteSyncLogPath,
+  readSuiteState,
+  writeSuiteState,
+  refreshFromRepos,
+  appendSyncLog,
+  format
+};

package/lib/workflow-parser.js

@@ -0,0 +1,109 @@
+/**
+ * Workflow Parser
+ *
+ * Parse workflow YAML files into a structured DAG.
+ * Used by the workflow runner and by tests.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseSimpleYaml } = require('./intent');
+
+/**
+ * Parse a workflow YAML file into a structured object.
+ */
+function parseFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Workflow not found: ${filePath}`);
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  return parse(content);
+}
+
+/**
+ * Parse YAML content into a workflow object.
+ */
+function parse(yamlContent) {
+  const parsed = parseSimpleYaml(yamlContent);
+  validate(parsed);
+  return parsed;
+}
+
+/**
+ * Validate workflow structure. Throws on invalid.
+ */
+function validate(workflow) {
+  const errors = [];
+  if (workflow.apiVersion !== 'godpowers/v1') errors.push('apiVersion must be godpowers/v1');
+  if (workflow.kind !== 'Workflow') errors.push('kind must be Workflow');
+  if (!workflow.metadata || !workflow.metadata.name) errors.push('metadata.name required');
+  if (!workflow.metadata.version) errors.push('metadata.version required');
+  if (!workflow.on || !Array.isArray(workflow.on) || workflow.on.length === 0) {
+    errors.push('on must be a non-empty array');
+  }
+  if (!workflow.jobs || typeof workflow.jobs !== 'object') {
+    errors.push('jobs must be an object');
+  } else {
+    for (const [jobId, job] of Object.entries(workflow.jobs)) {
+      if (!job.uses) errors.push(`jobs.${jobId}.uses required`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Invalid workflow:\n  - ${errors.join('\n  - ')}`);
+  }
+  return true;
+}
+
+/**
+ * Build a topological order of job IDs.
+ * Returns array of arrays; each inner array is a "wave" that can run in parallel.
+ */
+function buildWaves(workflow) {
+  const jobs = workflow.jobs;
+  const remaining = new Set(Object.keys(jobs));
+  const completed = new Set();
+  const waves = [];
+
+  while (remaining.size > 0) {
+    const wave = [];
+    for (const jobId of remaining) {
+      const needs = normalizeNeeds(jobs[jobId].needs);
+      if (needs.every(n => completed.has(n))) {
+        wave.push(jobId);
+      }
+    }
+    if (wave.length === 0) {
+      throw new Error(`Cyclic dependency or unresolved needs in workflow ${workflow.metadata.name}`);
+    }
+    for (const jobId of wave) {
+      remaining.delete(jobId);
+      completed.add(jobId);
+    }
+    waves.push(wave);
+  }
+
+  return waves;
+}
+
+function normalizeNeeds(needs) {
+  if (!needs) return [];
+  if (typeof needs === 'string') return [needs];
+  return needs;
+}
+
+/**
+ * Load all workflows from a directory.
+ */
+function loadAll(dir) {
+  if (!fs.existsSync(dir)) return {};
+  const result = {};
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.yaml') && !file.endsWith('.yml')) continue;
+    const workflow = parseFile(path.join(dir, file));
+    result[workflow.metadata.name] = workflow;
+  }
+  return result;
+}
+
+module.exports = { parse, parseFile, validate, buildWaves, loadAll, normalizeNeeds };

package/lib/workflow-runner.js

@@ -0,0 +1,221 @@
+/**
+ * Workflow Runner - v0.14 executable workflows.
+ *
+ * Reads a parsed workflow (from lib/workflow-parser.js), computes a
+ * plan (the agent dispatch order, with dependency waves), and either:
+ *   - emits the plan only (--plan mode), writing
+ *     .godpowers/runs/<id>/plan.yaml
+ *   - emits a plan AND signals the orchestrator agent to execute it
+ *     step by step
+ *
+ * For the pure-skill model, "execute" doesn't shell out; the
+ * orchestrator agent reads the plan and dispatches agents inside its
+ * AI context. The runner's contract is therefore:
+ *
+ *   - parse + validate the YAML
+ *   - compute waves (parallel groups)
+ *   - emit a deterministic plan
+ *   - return the plan for the orchestrator to follow
+ *
+ * Public API:
+ *   loadByName(workflowName, opts?) -> workflow object
+ *   plan(workflow, ctx?) -> { steps: [...], waves: [...], summary }
+ *   writePlan(projectRoot, runId, plan) -> path
+ *   readPlan(projectRoot, runId) -> plan | null
+ *   listWorkflows(opts?) -> [{ name, version, description, file }]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const parser = require('./workflow-parser');
+
+function workflowsDir(opts) {
+  if (opts && opts.dir) return opts.dir;
+  // Prefer project-local override, then repo workflows/
+  const candidates = [
+    path.join(process.cwd(), '.godpowers', 'workflows'),
+    path.join(__dirname, '..', 'workflows')
+  ];
+  return candidates.find(d => fs.existsSync(d)) || candidates[1];
+}
+
+/**
+ * List all available workflows. opts.dir overrides the default
+ * lookup chain.
+ */
+function listWorkflows(opts = {}) {
+  const dir = workflowsDir(opts);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.yaml'))
+    .map(f => {
+      try {
+        const wf = parser.parseFile(path.join(dir, f));
+        return {
+          name: wf.metadata && wf.metadata.name,
+          version: wf.metadata && wf.metadata.version,
+          description: wf.metadata && wf.metadata.description,
+          file: path.join(dir, f)
+        };
+      } catch (e) {
+        return { name: path.basename(f, '.yaml'), file: path.join(dir, f),
+                 error: e.message };
+      }
+    });
+}
+
+/**
+ * Load a workflow by name (looks up name in workflows/ dir).
+ * If `name` ends with .yaml, treats it as a path.
+ */
+function loadByName(name, opts = {}) {
+  if (name.endsWith('.yaml') && fs.existsSync(name)) {
+    return parser.parseFile(name);
+  }
+  const dir = workflowsDir(opts);
+  // Look up by metadata.name first; then by filename
+  for (const f of fs.readdirSync(dir).filter(f => f.endsWith('.yaml'))) {
+    const wf = parser.parseFile(path.join(dir, f));
+    if (wf.metadata && wf.metadata.name === name) return wf;
+  }
+  const filePath = path.join(dir, `${name}.yaml`);
+  if (fs.existsSync(filePath)) return parser.parseFile(filePath);
+  throw new Error(`workflow not found: ${name} (searched in ${dir})`);
+}
+
+/**
+ * Compute an execution plan from a workflow. Uses parser.buildWaves
+ * for dependency ordering.
+ *
+ * Returns:
+ *   {
+ *     workflow: { name, version, description },
+ *     steps: [{ jobKey, agent, tier, needs, uses, review?, on-pass?, on-fail? }],
+ *     waves: [[jobKey, ...], ...],
+ *     summary: '...'
+ *   }
+ */
+function plan(workflow, ctx = {}) {
+  const waves = parser.buildWaves(workflow);
+  const steps = [];
+  for (const wave of waves) {
+    for (const jobKey of wave) {
+      const job = workflow.jobs[jobKey] || {};
+      steps.push({
+        jobKey,
+        agent: extractAgent(job.uses),
+        tier: job.tier != null ? `tier-${job.tier}` : null,
+        needs: parser.normalizeNeeds(job.needs),
+        uses: job.uses,
+        review: job.review || null,
+        'on-pass': job['on-pass'] || null,
+        'on-fail': job['on-fail'] || null,
+        with: job.with || null
+      });
+    }
+  }
+  const summary = formatSummary(workflow, waves, steps);
+  return {
+    workflow: {
+      name: workflow.metadata && workflow.metadata.name,
+      version: workflow.metadata && workflow.metadata.version,
+      description: workflow.metadata && workflow.metadata.description
+    },
+    steps,
+    waves,
+    summary,
+    generatedAt: new Date().toISOString(),
+    context: ctx
+  };
+}
+
+function extractAgent(uses) {
+  if (!uses) return null;
+  const m = String(uses).match(/^([a-z][a-z0-9-]*)/);
+  return m ? m[1] : uses;
+}
+
+function formatSummary(workflow, waves, steps) {
+  const lines = [];
+  lines.push(`Workflow: ${workflow.metadata && workflow.metadata.name} v${workflow.metadata && workflow.metadata.version}`);
+  if (workflow.metadata && workflow.metadata.description) {
+    lines.push(workflow.metadata.description.split('\n')[0]);
+  }
+  lines.push('');
+  lines.push(`Steps: ${steps.length} across ${waves.length} wave${waves.length === 1 ? '' : 's'}`);
+  lines.push('');
+  for (let i = 0; i < waves.length; i++) {
+    lines.push(`Wave ${i + 1}:`);
+    for (const jobKey of waves[i]) {
+      const step = steps.find(s => s.jobKey === jobKey);
+      const agent = step.agent || '(no agent)';
+      const tier = step.tier ? ` [${step.tier}]` : '';
+      lines.push(`  - ${jobKey}${tier}: ${agent}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Write a plan to disk.
+ */
+function writePlan(projectRoot, runId, planObj) {
+  const dir = path.join(projectRoot, '.godpowers', 'runs', runId);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'plan.yaml');
+  fs.writeFileSync(file, serializePlan(planObj));
+  return file;
+}
+
+function serializePlan(p) {
+  // YAML-ish hand-roll, paired with our minimal parser
+  const lines = [];
+  lines.push(`# Generated workflow plan`);
+  lines.push(`# Workflow: ${p.workflow.name} v${p.workflow.version}`);
+  lines.push(`# Generated: ${p.generatedAt}`);
+  lines.push('');
+  lines.push(`workflow: ${p.workflow.name}`);
+  lines.push(`version: ${p.workflow.version}`);
+  lines.push(`generated-at: ${p.generatedAt}`);
+  lines.push(`step-count: ${p.steps.length}`);
+  lines.push(`wave-count: ${p.waves.length}`);
+  lines.push('');
+  lines.push('waves:');
+  for (let i = 0; i < p.waves.length; i++) {
+    lines.push(`  - index: ${i + 1}`);
+    lines.push('    steps:');
+    for (const jobKey of p.waves[i]) {
+      const step = p.steps.find(s => s.jobKey === jobKey);
+      lines.push(`      - jobKey: ${jobKey}`);
+      if (step.tier) lines.push(`        tier: ${step.tier}`);
+      if (step.agent) lines.push(`        agent: ${step.agent}`);
+      if (step.uses)  lines.push(`        uses: ${step.uses}`);
+      if (step.needs && step.needs.length) {
+        lines.push(`        needs: [${step.needs.join(', ')}]`);
+      }
+    }
+  }
+  lines.push('');
+  lines.push('summary: |');
+  for (const l of (p.summary || '').split('\n')) {
+    lines.push(`  ${l}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function readPlan(projectRoot, runId) {
+  const file = path.join(projectRoot, '.godpowers', 'runs', runId, 'plan.yaml');
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, 'utf8');
+}
+
+module.exports = {
+  workflowsDir,
+  listWorkflows,
+  loadByName,
+  plan,
+  writePlan,
+  readPlan,
+  serializePlan
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "godpowers",
+  "version": "0.15.0",
+  "description": "Ship fast. Ship right. Ship everything. Ship accountably.",
+  "bin": {
+    "godpowers": "./bin/install.js"
+  },
+  "scripts": {
+    "test": "node scripts/validate-skills.js && bash scripts/smoke.sh && node scripts/test-runtime.js && node scripts/test-router.js && node scripts/test-recipes.js && node scripts/test-context-writer.js && node scripts/test-artifact-linter.js && node scripts/test-artifact-diff.js && node scripts/test-design-foundation.js && node scripts/test-linkage.js && node scripts/test-impact.js && node scripts/test-reverse-sync.js && node scripts/test-integration.js && node scripts/test-cross-artifact.js && node scripts/test-awesome-design.js && node scripts/test-skillui-bridge.js && node scripts/test-runtime-verification.js && node scripts/test-agent-browser.js && node scripts/test-mode-d.js && node scripts/test-runtime-heuristics.js && node scripts/test-agent-validator.js && node scripts/test-story-validator.js && node scripts/test-state.js && node scripts/test-intent.js && node scripts/test-events.js && node scripts/test-golden-artifacts.js && node scripts/test-install-smoke.js && node scripts/test-checkpoint.js && node scripts/test-extensions.js && node scripts/test-event-reader.js && node scripts/test-state-lock.js && node scripts/test-cost-saver.js && node scripts/test-budget-onoff.js && node scripts/test-workflow-runner.js && node scripts/test-otel-exporter.js && node scripts/test-extensions-publish.js",
+    "prepublishOnly": "npm test",
+    "validate-skills": "node scripts/validate-skills.js",
+    "smoke": "bash scripts/smoke.sh",
+    "test:runtime": "node scripts/test-runtime.js",
+    "test:router": "node scripts/test-router.js",
+    "test:recipes": "node scripts/test-recipes.js",
+    "test:context": "node scripts/test-context-writer.js",
+    "test:linter": "node scripts/test-artifact-linter.js",
+    "test:diff": "node scripts/test-artifact-diff.js"
+  },
+  "keywords": [
+    "ai",
+    "coding",
+    "agent",
+    "claude",
+    "codex",
+    "cursor",
+    "tdd",
+    "orchestration",
+    "godmode",
+    "slash-commands"
+  ],
+  "author": "Godpowers",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aihxp/godpowers.git"
+  },
+  "homepage": "https://github.com/aihxp/godpowers#readme",
+  "bugs": {
+    "url": "https://github.com/aihxp/godpowers/issues"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "templates/",
+    "references/",
+    "routing/",
+    "workflows/",
+    "schema/",
+    "lib/",
+    "extensions/",
+    "INSPIRATION.md",
+    "SKILL.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}