godpowers 2.5.2 → 2.7.0

package/lib/pillars.js

@@ -96,8 +96,7 @@ const ARTIFACT_PILLAR_MAP = [
   { pattern: /(^|\/)stack\/DECISION\.md$/i, pillars: ['stack'] },
   { pattern: /(^|\/)roadmap\/ROADMAP\.md$/i, pillars: ['context', 'quality'] },
   { pattern: /(^|\/)build\/PLAN\.md$/i, pillars: ['quality', 'repo'] },
-  { pattern: /(^|\/)deploy\/STATE\.md$/i, pillars: ['deploy'] },
-  { pattern: /(^|\/)observe\/STATE\.md$/i, pillars: ['observe'] },
+  { pattern: /^\.godpowers\/state\.json$/i, pillars: ['context', 'deploy', 'observe'] },
   { pattern: /(^|\/)harden\/FINDINGS\.md$/i, pillars: ['security', 'auth'] },
   { pattern: /(^|\/)design\/DESIGN\.md$/i, pillars: ['ui'] },
   { pattern: /(^|\/)design\/PRODUCT\.md$/i, pillars: ['context', 'ui'] }
@@ -109,8 +108,7 @@ const GODPOWERS_ARTIFACTS = [
   '.godpowers/stack/DECISION.md',
   '.godpowers/roadmap/ROADMAP.md',
   '.godpowers/build/PLAN.md',
-  '.godpowers/deploy/STATE.md',
-  '.godpowers/observe/STATE.md',
+  '.godpowers/state.json',
   '.godpowers/harden/FINDINGS.md',
   '.godpowers/design/DESIGN.md',
   '.godpowers/design/PRODUCT.md'

package/lib/recipes.js

@@ -112,6 +112,14 @@ function evaluateStateCondition(condition, projectRoot) {
   if (cond.startsWith('file:')) {
     return fs.existsSync(path.join(projectRoot, cond.slice(5).trim()));
   }
+  if (cond.startsWith('state:')) {
+    const m = cond.slice(6).trim().match(/^([\w.-]+)\s*==\s*(.+)$/);
+    if (!m) return true;
+    const [, dottedPath, expected] = m;
+    const s = state.read(projectRoot);
+    const actual = state.valueAtPath(s, dottedPath);
+    return actual === expected.trim() || actual === parseValue(expected.trim());
+  }
   if (cond.startsWith('lifecycle-phase ==')) {
     const expected = cond.split('==')[1].trim();
     const s = state.read(projectRoot);
@@ -131,6 +139,14 @@ function evaluateStateCondition(condition, projectRoot) {
   return true;
 }
 
+function parseValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  if (/^\d+$/.test(value)) return parseInt(value, 10);
+  return value;
+}
+
 /**
  * Suggest top recipes based on current project state alone (no intent text).
  */

package/lib/router.js

@@ -119,11 +119,7 @@ function evaluateCheck(check, projectRoot) {
     if (!match) return false;
     const [, dottedPath, expected] = match;
     const s = state.read(projectRoot);
-    if (!s) return false;
-    const actual = dottedPath.split('.').reduce((acc, k) => {
-      if (!acc || k === '__proto__' || k === 'constructor' || k === 'prototype') return undefined;
-      return acc[k];
-    }, s.tiers || s);
+    const actual = state.valueAtPath(s, dottedPath);
     return actual === expected || actual === parseValue(expected);
   }
 

package/lib/source-sync.js

@@ -131,7 +131,7 @@ function progressLines(projectRoot) {
   lines.push(summarizeArtifact(projectRoot, '.godpowers/arch/ARCH.md', 'Architecture'));
   lines.push(summarizeArtifact(projectRoot, '.godpowers/roadmap/ROADMAP.md', 'Roadmap'));
   lines.push(summarizeArtifact(projectRoot, '.godpowers/stack/DECISION.md', 'Stack'));
-  lines.push(summarizeArtifact(projectRoot, '.godpowers/build/STATE.md', 'Build state'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/state.json', 'Godpowers state'));
   lines.push('');
   lines.push('## Return Path');
   lines.push('');

package/lib/state-advance.js

@@ -0,0 +1,244 @@
+/**
+ * State advance CLI mutation.
+ *
+ * Moves one tracked Godpowers step to a new status through state.json,
+ * cooperative locking, and generated markdown view refresh.
+ */
+
+const stateStore = require('./state');
+const stateLock = require('./state-lock');
+const stateViews = require('./state-views');
+
+const VALID_STATUSES = new Set([
+  'pending',
+  'in-flight',
+  'done',
+  'skipped',
+  'imported',
+  'failed',
+  're-invoked',
+  'not-required'
+]);
+
+function statusList() {
+  return Array.from(VALID_STATUSES).join(', ');
+}
+
+function check(status, reason, detail = {}) {
+  return {
+    id: detail.id || reason,
+    status,
+    reason: detail.message || reason,
+    artifact: detail.artifact || '.godpowers/state.json'
+  };
+}
+
+function resultFailure(projectRoot, id, reason, opts = {}) {
+  return {
+    command: 'state advance',
+    verdict: 'fail',
+    project: projectRoot,
+    step: opts.step || null,
+    status: opts.status || null,
+    previousStatus: null,
+    updated: null,
+    warnings: opts.warnings || [],
+    checks: [check('fail', reason, { id })],
+    findings: [{ id, severity: 'error', artifact: '.godpowers/state.json', reason }],
+    summary: { updated: false, state: '.godpowers/state.json', views: [stateViews.PROGRESS_VIEW_PATH] }
+  };
+}
+
+function resultPass(projectRoot, target, previousStatus, status, updated, warnings, views) {
+  return {
+    command: 'state advance',
+    verdict: 'pass',
+    project: projectRoot,
+    step: {
+      tierKey: target.tierKey,
+      subStepKey: target.subStepKey,
+      tierLabel: target.tierLabel,
+      subStepLabel: target.subStepLabel,
+      ordinal: target.ordinal
+    },
+    status,
+    previousStatus,
+    updated,
+    warnings,
+    checks: [check('pass', `advanced ${target.tierKey}.${target.subStepKey} to ${status}`, { id: 'state-advanced' })],
+    findings: [],
+    summary: { updated: true, state: '.godpowers/state.json', views: views || [stateViews.PROGRESS_VIEW_PATH] }
+  };
+}
+
+function normalizeStep(rawStep) {
+  return String(rawStep || '').trim();
+}
+
+function splitStep(rawStep) {
+  const step = normalizeStep(rawStep);
+  const compound = step.match(/^(tier-\d+)[.:/](.+)$/);
+  if (compound) {
+    return { tierKey: compound[1], subStepKey: compound[2] };
+  }
+  if (/^\d+$/.test(step)) {
+    return { ordinal: Number(step) };
+  }
+  return { subStepKey: step };
+}
+
+function resolveStep(currentState, rawStep) {
+  const token = splitStep(rawStep);
+  const steps = stateStore.orderedSubSteps(currentState);
+
+  if (token.ordinal != null) {
+    return steps.find(step => step.ordinal === token.ordinal) || null;
+  }
+
+  if (token.tierKey) {
+    return steps.find(step =>
+      step.tierKey === token.tierKey && step.subStepKey === token.subStepKey
+    ) || null;
+  }
+
+  const matches = steps.filter(step => step.subStepKey === token.subStepKey);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const err = new Error(`ambiguous step: ${rawStep}`);
+    err.code = 'AMBIGUOUS_STEP';
+    err.matches = matches.map(step => `${step.tierKey}.${step.subStepKey}`);
+    throw err;
+  }
+  return null;
+}
+
+function validateRequest(projectRoot, opts) {
+  if (!projectRoot) {
+    return resultFailure(projectRoot, 'project-required', 'state advance requires --project=<path>', opts);
+  }
+  if (!opts.step) {
+    return resultFailure(projectRoot, 'step-required', 'state advance requires --step=<step>', opts);
+  }
+  if (!opts.status) {
+    return resultFailure(projectRoot, 'status-required', 'state advance requires --status=<status>', opts);
+  }
+  if (!VALID_STATUSES.has(opts.status)) {
+    return resultFailure(projectRoot, 'status-invalid', `invalid status "${opts.status}"; expected one of ${statusList()}`, opts);
+  }
+  return null;
+}
+
+function advance(projectRoot, opts = {}) {
+  const request = {
+    step: normalizeStep(opts.step),
+    status: String(opts.status || '').trim(),
+    holder: opts.holder || `godpowers-state-advance:${process.pid}`,
+    ttlMs: opts.ttlMs
+  };
+  const invalid = validateRequest(projectRoot, request);
+  if (invalid) return invalid;
+
+  const initialState = stateStore.read(projectRoot);
+  if (!initialState) {
+    return resultFailure(projectRoot, 'state-missing', 'state.json not found', request);
+  }
+
+  let target;
+  try {
+    target = resolveStep(initialState, request.step);
+  } catch (e) {
+    if (e.code === 'AMBIGUOUS_STEP') {
+      return resultFailure(
+        projectRoot,
+        'step-ambiguous',
+        `ambiguous step "${request.step}"; use one of ${e.matches.join(', ')}`,
+        request
+      );
+    }
+    throw e;
+  }
+  if (!target) {
+    return resultFailure(projectRoot, 'step-not-found', `tracked step not found: ${request.step}`, request);
+  }
+
+  const lockResult = stateLock.acquire(projectRoot, {
+    holder: request.holder,
+    scope: `${target.tierKey}.${target.subStepKey}`,
+    ttlMs: request.ttlMs
+  });
+  if (!lockResult.acquired) {
+    return resultFailure(
+      projectRoot,
+      'lock-unavailable',
+      `state lock unavailable: held by ${lockResult.holder} on ${lockResult.scope}`,
+      request
+    );
+  }
+
+  const warnings = [];
+  try {
+    const currentState = stateStore.read(projectRoot);
+    const freshTarget = resolveStep(currentState, request.step);
+    if (!freshTarget) {
+      return resultFailure(projectRoot, 'step-not-found', `tracked step not found after lock: ${request.step}`, request);
+    }
+
+    const tier = currentState.tiers[freshTarget.tierKey] || {};
+    const current = tier[freshTarget.subStepKey] || {};
+    const previousStatus = current.status || 'pending';
+    const updated = opts.now || new Date().toISOString();
+    currentState.tiers[freshTarget.tierKey][freshTarget.subStepKey] = {
+      ...current,
+      status: request.status,
+      updated
+    };
+    stateStore.write(projectRoot, currentState, {
+      onStateViewWarning: warning => warnings.push(warning)
+    });
+    return resultPass(
+      projectRoot,
+      freshTarget,
+      previousStatus,
+      request.status,
+      updated,
+      warnings,
+      stateViews.viewPathsForState(currentState)
+    );
+  } finally {
+    stateLock.release(projectRoot, request.holder);
+  }
+}
+
+function render(result) {
+  const lines = [];
+  lines.push('Godpowers State Advance');
+  lines.push('');
+  lines.push(`Verdict: ${result.verdict}`);
+  if (result.verdict === 'pass') {
+    const step = result.step;
+    lines.push(`Step: ${step.tierKey}.${step.subStepKey}`);
+    lines.push(`Status: ${result.previousStatus} to ${result.status}`);
+    lines.push(`Updated: ${result.updated}`);
+    for (const warning of result.warnings || []) {
+      lines.push(`Warning: ${warning}`);
+    }
+  } else {
+    for (const finding of result.findings || []) {
+      lines.push(`Error: ${finding.reason}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function exitCode(result) {
+  return result && result.verdict === 'pass' ? 0 : 1;
+}
+
+module.exports = {
+  VALID_STATUSES,
+  advance,
+  render,
+  exitCode,
+  resolveStep,
+  statusList
+};

package/lib/state-lock.js

@@ -46,6 +46,10 @@ const state = require('./state');
 
 const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
+function writeLockState(projectRoot, nextState) {
+  return state.write(projectRoot, nextState, { refreshViews: false });
+}
+
 function nowIso(offsetMs) {
   const d = offsetMs ? new Date(Date.now() + offsetMs) : new Date();
   return d.toISOString();
@@ -102,7 +106,7 @@ function acquire(projectRoot, opts = {}) {
         (existing.scope === scope || existing.scope === 'all' || scope === 'all')) {
       existing.expires = nowIso(ttlMs);
       s.lock = existing;
-      state.write(projectRoot, s);
+      writeLockState(projectRoot, s);
       return { acquired: true, lock: existing, reentrant: true };
     }
     if (scopesConflict(existing.scope || 'all', scope)) {
@@ -134,7 +138,7 @@ function acquire(projectRoot, opts = {}) {
   };
   const reclaimedFrom = existing && isStale(existing) ? existing.holder : null;
   s.lock = lock;
-  state.write(projectRoot, s);
+  writeLockState(projectRoot, s);
   return {
     acquired: true,
     lock,
@@ -158,7 +162,7 @@ function release(projectRoot, holder) {
     return { released: false, reason: 'wrong-holder', heldBy: lock.holder };
   }
   s.lock = null;
-  state.write(projectRoot, s);
+  writeLockState(projectRoot, s);
   return { released: true, releasedAt: nowIso() };
 }
 
@@ -176,7 +180,7 @@ function reclaim(projectRoot, holder) {
   }
   const prev = lock.holder;
   s.lock = null;
-  state.write(projectRoot, s);
+  writeLockState(projectRoot, s);
   return { reclaimed: true, previousHolder: prev };
 }