@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/lifecycle/mcp-index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Per-install "this install has" index: the guidance layer's authoritative summary of exactly
+// which MCP servers were selected for this install, so an agent never assumes availability of a
+// server that isn't actually connected. Rendered fresh on every install/update from the resolved
+// selection — never hand-edited, and never a partial/empty file (null means "omit entirely").
+//
+// Each server's doc is emitted as an `@`-import, not as a "read this on use" instruction. That
+// instruction was prose describing a trigger, and nothing evaluates prose — the same shape this
+// guidance layer removed from its behavioral modes. A mode had an alternative (bind it to the
+// skill that reads it, at no context cost); a server doc has none, because there is no per-server
+// skill to bind to. So the choice here is an import that actually loads or a sentence that hopes.
+//
+// Only SELECTED servers are imported, so the cost is proportional to what is installed: a
+// one-server install pays for one doc, and an install with none produces no file at all.
+function renderMcpIndex(selectedServers                          )                {
+  if (!selectedServers || selectedServers.length === 0) return null;
+  const lines = ['# MCP short flags — this install'];
+  for (const server of selectedServers) {
+    lines.push(`# ${server.shortFlag} — prefer the \`${server.id}\` MCP server`);
+    lines.push(`@${server.doc}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { renderMcpIndex };

package/src/lifecycle/policies.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Registry lifecycle policies are logical intent. This projection reports what a
+// harness may render and any human prerequisite; native event serialization stays
+// in the owning harness adapter.
+const { harnessFor } = require('../registry/index.js');
+
+const POLICY_STATUSES = new Set(['supported', 'different', 'unavailable', 'prerequisite']);
+
+function unique(values       )        { return [...new Set(values.filter(Boolean))]; }
+
+function policyFor(registry     , id        )      {
+  const policy = registry?.lifecycle?.find((item     ) => item.id === id);
+  if (!policy) throw new Error(`Unknown lifecycle policy '${id}'`);
+  return policy;
+}
+
+function renderPolicy(policy     , harness     )      {
+  const mapping = policy?.mappings?.[harness.id];
+  if (!mapping) throw new Error(`Lifecycle policy '${policy.id}' has no mapping for '${harness.id}'`);
+  const requiredCapabilities = (policy.requires || []).map((capability        )                => {
+    const declaration = harness.capabilities?.[capability];
+    if (!declaration) throw new Error(`Lifecycle policy '${policy.id}' requires unknown '${harness.id}' capability '${capability}'`);
+    return [capability, declaration];
+  });
+  const unavailableCapability = requiredCapabilities.find(([, declaration]               ) => declaration.status === 'unavailable');
+  const prerequisites = unique([
+    ...(mapping.prerequisites || []),
+    ...requiredCapabilities.flatMap(([, declaration]               ) => declaration.prerequisites || []),
+  ]);
+  const capabilityStatus = unavailableCapability ? 'unavailable' : mapping.status;
+  const unavailable = capabilityStatus === 'unavailable';
+  const status = unavailable ? 'unavailable' : (prerequisites.length ? 'prerequisite' : capabilityStatus);
+  // POLICY_STATUSES was declared and exported while nothing consulted it, which left the one value
+  // here that does not originate in this function unchecked: `capabilityStatus` falls through from
+  // `mapping.status`, straight out of the registry. A registry typo therefore became a policy status
+  // no caller has a branch for, reported as though it were a real one. The two failures above already
+  // throw on invalid registry data — an absent mapping, an unknown capability — so this is the same
+  // check applied to the third field that comes from the same file.
+  if (!POLICY_STATUSES.has(status)) {
+    throw new Error(
+      `Lifecycle policy '${policy.id}' resolved status '${status}' for '${harness.id}', which is not `
+      + `one of: ${[...POLICY_STATUSES].join(', ')}. Check 'status' in the registry entry.`,
+    );
+  }
+  return Object.freeze({
+    id: policy.id,
+    intent: policy.intent,
+    harness: harness.id,
+    status,
+    capabilityStatus,
+    event: unavailable ? null : mapping.event,
+    renderable: !unavailable,
+    prerequisites,
+    fallback: unavailable ? (mapping.fallback || 'guidance') : null,
+    reason: unavailableCapability ? `Required capability '${unavailableCapability[0]}' is unavailable` : null,
+  });
+}
+
+/** Render policy status data for one harness without calling an adapter or writing state. */
+function renderPolicies(registry     , { harness: harnessId, policyIds }                                                    = {})      {
+  if (!harnessId) throw new Error('A harness id is required to render lifecycle policies');
+  const harness = harnessFor(registry, harnessId);
+  const policies = policyIds === undefined || policyIds === null
+    ? registry.lifecycle
+    : policyIds.map((id        ) => policyFor(registry, id));
+  if (!Array.isArray(policies)) throw new Error('Lifecycle policies must be an array');
+  return Object.freeze(policies.map((policy     ) => renderPolicy(policy, harness)));
+}
+
+module.exports = { POLICY_STATUSES, policyFor, renderPolicy, renderPolicies };

package/src/lifecycle/view.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+// lifecycle-view.js — CLI-facing view over the registry/lifecycle path: computes a plan across
+// every requested harness (claude/codex/gemini) from a loaded registry, a neutral ledger, and the
+// Codex-native source locations under `repoRoot`, then renders/gates it for bin/doflow.js's
+// install/update/remove/status commands.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { parseToml } = require('../helper/toml.js');
+const { createAdapterRegistry } = require('../adapters/index.js');
+const { declaredHarnessPaths } = require('../helper/harness-paths.js');
+const claudeAdapter = require('../adapters/claude/index.js');
+const codexAdapter = require('../adapters/codex/index.js');
+const { createGeminiAdapter } = require('../adapters/gemini/index.js');
+const { createOpenCodeAdapter } = require('../adapters/opencode/index.js');
+const { createPiAdapter } = require('../adapters/pi/index.js');
+const { createCopilotAdapter } = require('../adapters/copilot/index.js');
+const { createKiroAdapter } = require('../adapters/kiro/index.js');
+const { createAntigravityAdapter } = require('../adapters/antigravity/index.js');
+const { planLifecycle } = require('./index.js');
+const { stateRoot, readLedger, defaultLedger } = require('../state/index.js');
+const { selectAssets } = require('../registry/index.js');
+const { defaultLock, readLock, writeLock, diffLocks, removeLock, pinnedSelections } = require('../state/lockfile.js');
+// Tolerant because the projected runtime under `.doflow/runtime/` ships bin/, src/ and
+// core/registry/ but no package.json — see the `runtime.*` assets in core/registry/assets.json.
+// A hard require here would make every Node-backed verb fail in an install, which is the exact
+// defect that projection exists to fix. Only version reporting depends on this.
+function loadPkg() {
+  try { return require('../../package.json'); } catch { return { version: '0.0.0-installed', name: '@khoavu882/doflow' }; }
+}
+const pkg = loadPkg();
+
+function codexScope(scope     ) { return scope.global ? 'global' : 'project'; }
+
+function codexConfigResources(repoRoot     , fsImpl     ) {
+  const configSrc = path.join(repoRoot, 'core', 'harnesses', 'codex', 'config', 'config.toml');
+  const parsed = parseToml(fsImpl.readFileSync(configSrc, 'utf8'));
+  return [...parsed.entries.entries()].map(([identity, entry]) => ({
+    target: 'codex', kind: 'configuration-entry', identity, value: entry.value,
+    sourceVersion: pkg.version, selection: true,
+  }));
+}
+
+/** Registry/lifecycle is introduced as a read-only companion to the legacy installer.  It makes
+ * the capability and neutral-ledger view observable without changing the proven copy/backup
+ * mutation path until every native adapter has CLI-level parity.
+ * `registry` is loaded once per command (by the caller) and threaded through here rather than
+ * reloaded — the same registry also resolves every harness's MCP selection for that command. */
+function registryLifecycleView({ registry, scope, targets, mcpSelections = {}, mcpAdoptable = {}, retainedMcpIds = [], operation, repoRoot, force = false, adopt = false, permissions = false, statusline = false, fsImpl = fs }     ) {
+  const lifecycleScope = codexScope(scope);
+  const scopeRoot = scope.global ? os.homedir() : path.resolve(scope.projectRoot);
+  const neutralStateRoot = stateRoot({ scope: lifecycleScope, projectRoot: scopeRoot, homeDir: scopeRoot });
+  const ledger = readLedger(neutralStateRoot) ?? defaultLedger({ scope: lifecycleScope, scopeRoot });
+  // Mirrors buildAdapterRegistry() in src/cli/shared.js — including the declared-paths wiring —
+  // and is kept as a literal construction here because the registry guard pins every declared
+  // harness into each adapter-registry call site by parsing it.
+  const declared = declaredHarnessPaths();
+  const adapters = createAdapterRegistry({ claude: claudeAdapter.createClaudeAdapter({ declaredPaths: declared.claude }),
+    codex: codexAdapter.createCodexAdapter({ declaredPaths: declared.codex }), gemini: createGeminiAdapter({ declaredPaths: declared.gemini }),
+    opencode: createOpenCodeAdapter({ declaredPaths: declared.opencode }), pi: createPiAdapter({ declaredPaths: declared.pi }),
+    copilot: createCopilotAdapter({ declaredPaths: declared.copilot }), kiro: createKiroAdapter({ declaredPaths: declared.kiro }),
+    antigravity: createAntigravityAdapter({ declaredPaths: declared.antigravity }) });
+  const plan = planLifecycle({ registry, adapters, scope: lifecycleScope, scopeRoot, targets, mcpSelections, mcpAdoptable, retainedMcpIds, ledger, context: {
+    repoRoot, projectRoot: scopeRoot, homeDir: os.homedir(), sourceVersion: pkg.version,
+    codexConfigResources: codexConfigResources(repoRoot, fsImpl),
+    codexAgentsSourceDir: path.join(repoRoot, 'core', 'harnesses', 'codex', 'agents'),
+    codexHooksSourceFile: path.join(repoRoot, 'core', 'harnesses', 'codex', 'hooks', 'hooks.json'),
+    codexHooksSourceDir: path.join(repoRoot, 'core', 'harnesses', 'codex', 'hooks'),
+    geminiHooksSourceFile: path.join(repoRoot, 'core', 'harnesses', 'gemini', 'hooks', 'hooks.json'),
+    geminiHooksSourceDir: path.join(repoRoot, 'core', 'harnesses', 'gemini', 'hooks'),
+    operation,
+    force,
+    adopt,
+    permissions,
+    statusline,
+  } });
+  return { registry, stateRoot: neutralStateRoot, ledger, plan, adapters };
+}
+
+function printRegistryLifecycle(view     , prefix = '[PLAN]') {
+  console.log(`${prefix} Registry lifecycle: ${view.plan.changes.length} native change(s), ${view.plan.conflicts.length} conflict(s), ${view.plan.prerequisites.length} prerequisite(s)`);
+  for (const target of view.plan.targets) {
+    console.log(`${prefix}   ${target.harness}: ${target.changes.length} change(s)${target.conflicts.length ? `; conflicts: ${target.conflicts.join('; ')}` : ''}`);
+    const hookChange = target.changes.find((change     ) => change.nativeComponent === 'hooks');
+    if (hookChange?.nativePlan?.trust?.required) {
+      console.log(`${prefix}   ${target.harness} hooks trust: ${hookChange.nativePlan.trust.status} (review required in ${target.harness})`);
+    }
+    for (const notice of target.notices ?? []) console.log(`${prefix}   ${target.harness}: ${notice}`);
+  }
+  console.log(`${prefix} Neutral state: ${view.stateRoot}${readLedger(view.stateRoot) ? ' (existing ledger)' : ' (not yet created)'}`);
+}
+
+/** Prints the plan's notices after a real run. Independent of whether anything changed: a no-op
+ * reinstall of a harness that has a gap must still say so. */
+function printPlanNotices(view     ) {
+  for (const { harness, notice } of view.plan.notices) console.log(`[INFO] ${harness}: ${notice}`);
+}
+
+/** Harnesses whose native resources are reconciled through the registry/lifecycle path (all of
+ * them, as of this wiring). Kept as an explicit list — rather than reusing VALID from
+ * src/targets.js — so a future non-lifecycle target doesn't silently gain lifecycle behavior. */
+const LIFECYCLE_HARNESSES = ['claude', 'codex', 'gemini', 'opencode', 'pi', 'copilot', 'kiro', 'antigravity'];
+
+function assertSafeRegistryPlan(view     ) {
+  if (view.plan.safe) return;
+  for (const conflict of view.plan.conflicts) console.error(`[ERROR] ${conflict.harness} lifecycle refused: ${conflict.reason}`);
+  for (const prerequisite of view.plan.prerequisites) console.error(`[ERROR] ${prerequisite.harness} lifecycle prerequisite: ${prerequisite.prerequisite}`);
+  process.exitCode = 1;
+}
+
+/** Build the doflow.lock document a completed run leaves. Pure — no I/O — so tests can pin exactly
+ * what gets pinned without running an install.
+ *
+ * The lock accumulates: it pins every harness the previous lock pinned or this run planned, as long
+ * as the ledger (as the run left it) still holds a resource of that harness, so a narrower later run
+ * never drops another harness's pin and a harness whose last resource is gone leaves it. MCP
+ * selections carry over for pinned harnesses and are replaced by the rows this run resolved, `[]`
+ * included. Assets are recomputed from the registry for every pinned harness. `null` when no harness
+ * stays pinned. */
+function lockDocument({ registry, scope, scopeRoot, previous = null, ledger, plannedTargets = [], mcpSelections = {}, sourceVersion = pkg.version, now = new Date() }     ) {
+  const held = new Set((ledger?.resources ?? []).map((resource     ) => resource?.harness));
+  const pinned = [...new Set([...(previous?.targets ?? []).map((entry     ) => entry.harness), ...plannedTargets])]
+    .filter((harness) => held.has(harness)).sort();
+  if (!pinned.length) return null;
+  const assets = [];
+  for (const harness of pinned) {
+    for (const asset of selectAssets(registry, { harness })) {
+      const nativeDir = asset.nativeDir?.[harness];
+      assets.push({ id: asset.id, kind: asset.kind, ...(nativeDir ? { nativeDir } : {}) });
+    }
+  }
+  const rows = { ...pinnedSelections(previous), ...mcpSelections };
+  return {
+    ...defaultLock({ scope, scopeRoot }),
+    generatedAt: now.toISOString(),
+    sourceVersion,
+    targets: pinned.map((harness) => ({ harness })),
+    assets,
+    mcpSelections: Object.fromEntries(pinned.filter((harness) => Array.isArray(rows[harness])).map((harness) => [harness, rows[harness]])),
+  };
+}
+
+/** Describe the reviewable delta between the pinned lock and the next one: "created" for a first
+ * pin, "unchanged" when nothing pinned differs, "cleared" when nothing remains pinned, else a count
+ * of the changed rows. */
+function lockDelta(previous     , next     ) {
+  if (!next) return previous ? { changed: true, summary: 'cleared' } : { changed: false, summary: 'unchanged' };
+  if (!previous) return { changed: true, summary: 'created' };
+  const diff = diffLocks(previous, next);
+  if (diff.clean) return { changed: false, summary: 'unchanged' };
+  const count = ['targets', 'assets']
+    .flatMap((section) => Object.values     (diff[section]).map((list     ) => list.length))
+    .reduce((sum, n) => sum + n, 0)
+    + diff.mcpSelections.changed.length + (diff.meta.sourceVersion ? 1 : 0);
+  return { changed: true, summary: `${count} change(s)` };
+}
+
+/** Persist the lock for a completed command and return its delta against what was pinned before.
+ * An unchanged lock is left byte for byte, so routine re-runs neither rewrite the file nor
+ * manufacture noise; a `null` lock removes the file. */
+function recordLock(scopeArgs     , next     , { fsImpl = fs }      = {}) {
+  const delta = lockDelta(readLock(scopeArgs, { fsImpl }), next);
+  if (delta.changed) {
+    if (next) writeLock(scopeArgs, next, { fsImpl });
+    else removeLock(scopeArgs, { fsImpl });
+  }
+  return delta;
+}
+
+module.exports = {
+  codexScope, registryLifecycleView, printRegistryLifecycle, printPlanNotices, LIFECYCLE_HARNESSES, assertSafeRegistryPlan,
+  lockDocument, lockDelta, recordLock,
+};