create-agdf 0.14.5 → 0.20.0

package/lib/lifecycle/result.js

@@ -1,7 +1,18 @@
-const OPERATIONS = new Set(["install", "update", "status", "disable", "uninstall", "repository_setup"]);
+const OPERATIONS = new Set(["install", "update", "status", "disable", "uninstall", "repository_setup", "control_init"]);
 const RESULTS = new Set(["success", "partial", "failed", "preview"]);
 const SCOPES = new Set(["global", "repository"]);
 const SURFACES = new Set(["codex", "claude", "copilot", "opencode", "generic"]);
+const OPERATION_OUTCOMES = new Set(["reported", "created", "unchanged", "repaired", "preview", "succeeded", "partial", "failed"]);
+const STATUS_EXCLUDED_AUTHORITY = Object.freeze(["target_inference", "run_creation", "gate_approval", "mutation"]);
+const LIFECYCLE_EXCLUDED_AUTHORITY = Object.freeze([
+  "target_inference",
+  "run_creation",
+  "ur_persistence",
+  "gate_approval",
+  "implementation",
+  "qa",
+  "release",
+]);
 const GLOBAL_INSTALL_RESTART_ACTIONS = Object.freeze({
   codex: "Fully restart Codex, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
   claude: "Fully restart Claude Code, then start a fresh session. Restoring the previous session can retain stale AGDF skills.",
@@ -13,7 +24,135 @@ function text(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 
+function lifecycleOperationId(operation, surface, scope) {
+  if (["install", "update"].includes(operation)) {
+    if (surface === "generic") throw new Error(`${operation} requires a concrete lifecycle surface.`);
+    return `lifecycle.plugin.install.${surface}`;
+  }
+  if (operation === "repository_setup") {
+    if (!["codex", "opencode"].includes(surface)) {
+      throw new Error("Repository setup requires the codex or opencode surface.");
+    }
+    return `lifecycle.repository.activate.${surface}`;
+  }
+  if (operation === "disable") return "lifecycle.repository.disable";
+  if (operation === "uninstall") return "lifecycle.plugin.uninstall";
+  if (operation === "control_init") return "lifecycle.control.init";
+  if (operation === "status" && scope === "repository") {
+    return surface === "opencode" ? "status.opencode_repository" : "status.repository_delivery";
+  }
+  if (operation === "status" && surface !== "generic") return `status.installation.${surface}`;
+  return "status.overview";
+}
+
+function lifecyclePlannedEffect(operation) {
+  if (["install", "update"].includes(operation)) return "install_or_update_global_plugin";
+  if (operation === "repository_setup") return "configure_repository_plugin_surface";
+  if (operation === "disable") return "disable_repository_plugin";
+  if (operation === "uninstall") return "uninstall_global_plugin";
+  if (operation === "control_init") return "create_canonical_control_scaffold";
+  return "read_only_status";
+}
+
+function lifecycleOutcome(result) {
+  if (result === "success") return "succeeded";
+  if (result === "partial") return "partial";
+  if (result === "failed") return "failed";
+  return "preview";
+}
+
+export function createOperationStatus({
+  operationId,
+  outcome,
+  targetScope,
+  target = null,
+  plannedEffect,
+  excludedAuthority,
+  authorizes = false,
+} = {}) {
+  const normalizedScope = text(targetScope);
+  const normalizedTarget = text(target) || null;
+  const normalizedExcludedAuthority = Array.isArray(excludedAuthority)
+    ? excludedAuthority.map(text).filter(Boolean)
+    : [];
+  const status = {
+    operation_id: text(operationId),
+    outcome: text(outcome),
+    target_scope: normalizedScope,
+    target: normalizedTarget,
+    planned_effect: text(plannedEffect),
+    excluded_authority: Object.freeze(normalizedExcludedAuthority),
+    authorizes: false,
+  };
+  if (!status.operation_id
+      || !OPERATION_OUTCOMES.has(status.outcome)
+      || !SCOPES.has(status.target_scope)
+      || (status.target_scope === "repository" && !status.target)
+      || (status.target_scope === "global" && status.target !== null)
+      || !status.planned_effect
+      || status.excluded_authority.length === 0
+      || !status.excluded_authority.includes("gate_approval")
+      || authorizes !== false) {
+    throw new Error("Lifecycle operation_status must be complete, target-bound when required and non-authorizing.");
+  }
+  return Object.freeze(status);
+}
+
+function deriveLifecycleOperationStatus(input) {
+  const operation = text(input.operation);
+  const result = text(input.result);
+  const surface = text(input.surface);
+  const scope = text(input.scope);
+  let outcome = operation === "status" ? "reported" : lifecycleOutcome(result);
+  if (operation === "control_init" && result !== "failed") {
+    const initializationOutcome = text(input.operationOutcome);
+    if (!["created", "unchanged", "repaired"].includes(initializationOutcome)) {
+      throw new Error("Control initialization requires an explicit created, unchanged or repaired operation outcome.");
+    }
+    outcome = initializationOutcome;
+  }
+  return createOperationStatus({
+    operationId: lifecycleOperationId(operation, surface, scope),
+    outcome,
+    targetScope: scope,
+    target: input.target,
+    plannedEffect: lifecyclePlannedEffect(operation),
+    excludedAuthority: operation === "status" ? STATUS_EXCLUDED_AUTHORITY : LIFECYCLE_EXCLUDED_AUTHORITY,
+  });
+}
+
+function assertSuppliedOperationStatus(expected, supplied) {
+  if (supplied.operation_id !== expected.operation_id) {
+    throw new Error(`Lifecycle operation_status must use the exact operation id ${expected.operation_id}.`);
+  }
+  if (supplied.outcome !== expected.outcome) {
+    throw new Error(`Lifecycle operation_status outcome must be ${expected.outcome}.`);
+  }
+  if (supplied.target_scope !== expected.target_scope || supplied.target !== expected.target) {
+    throw new Error("Lifecycle operation_status target scope and target must be derived exactly from the lifecycle request.");
+  }
+  if (supplied.planned_effect !== expected.planned_effect) {
+    throw new Error(`Lifecycle operation_status must use the exact planned effect ${expected.planned_effect}.`);
+  }
+  if (JSON.stringify(supplied.excluded_authority) !== JSON.stringify(expected.excluded_authority)) {
+    throw new Error("Lifecycle operation_status must use the exact excluded-authority contract for its operation.");
+  }
+}
+
 export function createLifecycleResult(input = {}) {
+  const suppliedOperationStatus = input.operation_status
+    ? createOperationStatus({
+        operationId: input.operation_status.operation_id,
+        outcome: input.operation_status.outcome,
+        targetScope: input.operation_status.target_scope,
+        target: input.operation_status.target,
+        plannedEffect: input.operation_status.planned_effect,
+        excludedAuthority: input.operation_status.excluded_authority,
+        authorizes: input.operation_status.authorizes,
+      })
+    : null;
+  const operationStatus = deriveLifecycleOperationStatus(input);
+  if (suppliedOperationStatus) assertSuppliedOperationStatus(operationStatus, suppliedOperationStatus);
   const result = {
     schema_version: 1,
     operation: text(input.operation),
@@ -60,6 +199,7 @@ export function createLifecycleResult(input = {}) {
     changes: [...(input.changes ?? [])],
     retained: [...(input.retained ?? [])],
     failure: input.failure ?? null,
+    operation_status: operationStatus,
   };
   assertLifecycleResult(result);
   return Object.freeze(result);
@@ -78,6 +218,46 @@ export function assertLifecycleResult(value) {
     throw new Error("A verified lifecycle version requires an observed installed version.");
   }
   if (value.result === "failed" && !value.failure) throw new Error("Failed lifecycle results require failure evidence.");
+  if (!value.operation_status
+      || !value.operation_status.operation_id
+      || !OPERATION_OUTCOMES.has(value.operation_status.outcome)
+      || !SCOPES.has(value.operation_status.target_scope)
+      || (value.operation_status.target_scope === "repository" && !value.operation_status.target)
+      || (value.operation_status.target_scope === "global" && value.operation_status.target !== null)
+      || !value.operation_status.planned_effect
+      || value.operation_status.excluded_authority.length === 0
+      || !value.operation_status.excluded_authority.includes("gate_approval")
+      || value.operation_status.authorizes !== false) {
+    throw new Error("Lifecycle operation_status must be complete, target-bound when required and non-authorizing.");
+  }
+  const expectedOperationId = lifecycleOperationId(value.operation, value.surface, value.scope);
+  if (value.operation_status.operation_id !== expectedOperationId) {
+    throw new Error(`Lifecycle operation_status must use the exact operation id ${expectedOperationId}.`);
+  }
+  const expectedOutcome = value.operation === "status" ? "reported" : lifecycleOutcome(value.result);
+  if (value.operation !== "control_init" && value.operation_status.outcome !== expectedOutcome) {
+    throw new Error(`Lifecycle operation_status outcome must reflect lifecycle result ${value.result}.`);
+  }
+  if (value.operation === "control_init"
+      && (value.operation_status?.operation_id !== "lifecycle.control.init"
+        || !(value.result === "failed"
+          ? value.operation_status?.outcome === "failed"
+          : ["created", "unchanged", "repaired"].includes(value.operation_status?.outcome)))) {
+    throw new Error("Control initialization requires a canonical lifecycle.control.init outcome.");
+  }
+  if (value.operation_status.target_scope !== value.scope) {
+    throw new Error("Lifecycle operation_status target_scope must match the lifecycle scope.");
+  }
+  const expectedPlannedEffect = lifecyclePlannedEffect(value.operation);
+  if (value.operation_status.planned_effect !== expectedPlannedEffect) {
+    throw new Error(`Lifecycle operation_status must use the exact planned effect ${expectedPlannedEffect}.`);
+  }
+  const expectedExcludedAuthority = value.operation === "status"
+    ? STATUS_EXCLUDED_AUTHORITY
+    : LIFECYCLE_EXCLUDED_AUTHORITY;
+  if (JSON.stringify(value.operation_status.excluded_authority) !== JSON.stringify(expectedExcludedAuthority)) {
+    throw new Error("Lifecycle operation_status must use the exact excluded-authority contract for its operation.");
+  }
   return value;
 }
 
@@ -87,12 +267,13 @@ export function globalInstallRestartAction(surface) {
   return Object.freeze({ kind: "restart", text: action });
 }
 
-export function lifecycleFailure({ operation, surface, scope, phase, message, evidence = [], nextAction }) {
+export function lifecycleFailure({ operation, surface, scope, target = null, phase, message, evidence = [], nextAction }) {
   return createLifecycleResult({
     operation,
     result: "failed",
     surface,
     scope,
+    target,
     verification: { status: "degraded", evidence },
     next_action: { kind: "recovery", text: nextAction },
     failure: { phase, message },

package/lib/lifecycle/status.js

@@ -1,23 +1,30 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { pluginDefinition } from "../cli/runtime-context.js";
-import { evaluateDoctor } from "../control-evaluation/doctor.js";
-import { evaluateGateCheck } from "../control-evaluation/gate-check.js";
-import { evaluateOpenCodeStatus } from "../installers/opencode.js";
-import { inspectPluginSurface } from "../installers/plugin-installers.js";
-import { inspectGeneratedRepositoryMarketplace } from "../runtime/plugin-provenance.js";
+import { evaluateDoctor } from "#agdf-core/control-evaluation/doctor.js";
+import { evaluateGateCheck } from "#agdf-core/control-evaluation/gate-check.js";
+import * as openCodeInstaller from "../installers/opencode.js";
+import { evaluateOpenCodeRepositoryActivation } from "../installers/opencode-activation.js";
+import { inspectPluginSurface, pluginBootstrapCommands } from "../installers/plugin-installers.js";
+import { inspectCodexRepositoryStatus } from "../host-adapters/codex/plugin.js";
+import { inspectOpenCodeInstallation, inspectOpenCodeRepositoryStatus } from "../host-adapters/opencode/status.js";
 import { runtimeCheckStatus } from "../runtime-check-consent/service.js";
+import { createOperationStatus } from "./result.js";
+import { cliGitObservation } from "../control-evaluation/git-observation.js";
+
+const SUPPORTED_SURFACES = Object.freeze(["codex", "claude", "copilot", "opencode"]);
+
+export function inspectControlPresence(targetDir, dependencies = {}) {
+  const pathExists = dependencies.existsSync ?? existsSync;
+  return pathExists(join(targetDir, ".agdf", "control")) ? "candidate_present" : "absent";
+}
 
 function deliveryStatus(targetDir, selection, dependencies) {
-  const controlDir = join(targetDir, ".agdf", "control");
-  const hasLiveControl = existsSync(join(controlDir, "runs"))
-    || (existsSync(join(controlDir, "AGDF_RUN.md")) && existsSync(join(controlDir, "MASTER_BACKLOG.md")));
-  if (!hasLiveControl) {
+  if (dependencies.inspectControlPresence(targetDir) === "absent") {
     return { status: "not_configured", run_id: null, current_gate: null, evidence: [] };
   }
   try {
-    const doctor = dependencies.evaluateDoctor(targetDir, selection);
-    const gate = dependencies.evaluateGateCheck(targetDir, selection);
+    const doctor = dependencies.evaluateDoctor(targetDir, selection, cliGitObservation);
+    const gate = dependencies.evaluateGateCheck(targetDir, selection, cliGitObservation);
     return {
       status: gate.status === "blocked" || doctor.status === "block" ? "blocked" : gate.status === "complete" ? "complete" : "open",
       run_id: selection.runId || null,
@@ -29,57 +36,37 @@ function deliveryStatus(targetDir, selection, dependencies) {
   }
 }
 
-function repositoryStatus(targetDir, surface) {
+function repositoryStatus(targetDir, surface, dependencies) {
   if (surface === "codex") {
-    const repository = inspectGeneratedRepositoryMarketplace(targetDir);
-    const marketplace = repository.marketplacePath;
-    const disabled = join(targetDir, ".codex", "config.toml");
-    const config = existsSync(disabled) ? readFileSync(disabled, "utf8") : "";
-    const isDisabled = ["agdf@agdf-repo", "agdf@agdf"].some((selector) => {
-      const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const section = config.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
-      return /^enabled\s*=\s*false\s*$/m.test(section);
-    });
-    return {
-      status: isDisabled ? "disabled" : repository.status === "matched" ? "active" : repository.status === "invalid" ? "degraded" : "not_configured",
-      scope: "repository",
-      evidence: [marketplace, ...(repository.reason ? [repository.reason] : [])],
-    };
+    return inspectCodexRepositoryStatus(targetDir);
   }
   if (surface === "opencode") {
-    const instructions = join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName);
-    return { status: existsSync(instructions) ? "active" : "not_configured", scope: "repository", evidence: [instructions] };
+    return inspectOpenCodeRepositoryStatus(targetDir, dependencies.evaluateOpenCodeRepositoryActivation);
   }
   return { status: "unknown", scope: "repository", evidence: [] };
 }
 
-function inspectInstallation(surface, targetDir, options, deps, exec) {
+function inspectGlobalSurface(surface, options, dependencies) {
   if (surface === "opencode") {
-    const report = deps.evaluateOpenCodeStatus(targetDir, options.configDir);
-    return {
-      status: report.status === "configured" && report.package.version_status === "current" ? "healthy" : report.status === "configured" ? "degraded" : "not_installed",
-      surface,
-      version: report.package.installed_version,
-      evidence: [report.global_config.path],
-    };
+    return inspectOpenCodeInstallation(options, dependencies.evaluateOpenCodeGlobalStatus);
   }
-  if (["codex", "claude", "copilot"].includes(surface)) return deps.inspectPluginSurface(surface, exec);
+  if (SUPPORTED_SURFACES.includes(surface)) return dependencies.inspectPluginSurface(surface, dependencies.exec);
   return { status: "unknown", surface, version: null, evidence: [`unsupported_status_probe:${surface}`] };
 }
 
-export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}) {
+export function inspectGlobalInstallationStatus(options = {}, dependencies = {}) {
   const deps = {
-    evaluateDoctor: dependencies.evaluateDoctor ?? evaluateDoctor,
-    evaluateGateCheck: dependencies.evaluateGateCheck ?? evaluateGateCheck,
-    evaluateOpenCodeStatus: dependencies.evaluateOpenCodeStatus ?? evaluateOpenCodeStatus,
+    evaluateOpenCodeGlobalStatus: dependencies.evaluateOpenCodeGlobalStatus
+      ?? openCodeInstaller.evaluateOpenCodeGlobalStatus,
     inspectPluginSurface: dependencies.inspectPluginSurface ?? inspectPluginSurface,
+    exec: dependencies.exec,
   };
   let surface = options.surface && options.surface !== "generic" ? options.surface : null;
   let installation;
   if (surface) {
-    installation = inspectInstallation(surface, targetDir, options, deps, dependencies.exec);
+    installation = inspectGlobalSurface(surface, options, deps);
   } else {
-    const probes = ["codex", "claude", "copilot", "opencode"].map((candidate) => inspectInstallation(candidate, targetDir, options, deps, dependencies.exec));
+    const probes = SUPPORTED_SURFACES.map((candidate) => inspectGlobalSurface(candidate, options, deps));
     const observed = probes.filter((probe) => ["healthy", "degraded"].includes(probe.status));
     if (observed.length === 1) {
       installation = observed[0];
@@ -94,27 +81,124 @@ export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}
       };
     }
   }
-  const repository = repositoryStatus(targetDir, surface);
-  const delivery = deliveryStatus(targetDir, { runId: options.runId }, deps);
-  const runtimeChecks = ["codex", "claude", "copilot", "opencode"].includes(surface)
+  if (options.surface && options.surface !== "generic" && SUPPORTED_SURFACES.includes(options.surface)) {
+    return installationStatusReport(installation);
+  }
+  return publicInstallationFacts(installation);
+}
+
+function publicInstallationFacts(installation) {
+  const {
+    schema_version: _schemaVersion,
+    recommended_action: _recommendedAction,
+    operation_status: _operationStatus,
+    next_action: _nextAction,
+    ...facts
+  } = installation;
+  return facts;
+}
+
+function installationStatusReport(installation) {
+  const facts = publicInstallationFacts(installation);
+  const nextAction = installation.recommended_action
+    || (installation.status === "healthy"
+      ? "No further installation action is required."
+      : `Run ${bootstrapCommands(installation.surface).install} to install or repair AGDF.`);
+  return Object.freeze({
+    schema_version: 1,
+    ...facts,
+    operation_status: createOperationStatus({
+      operationId: `status.installation.${installation.surface}`,
+      outcome: "reported",
+      targetScope: "global",
+      plannedEffect: "read_only_status",
+      excludedAuthority: ["target_inference", "run_creation", "gate_approval", "mutation"],
+    }),
+    next_action: Object.freeze({ kind: "action", text: nextAction }),
+  });
+}
+
+function runtimeStatus(surface, options) {
+  return SUPPORTED_SURFACES.includes(surface)
     ? runtimeCheckStatus(options.dataRoot, surface)
     : { requested: "unknown", effective: "unavailable", reason: "unsupported_host_capability" };
-  const nextText = surface === "multiple"
-    ? "Multiple AGDF host surfaces were detected; rerun status with an explicit --surface."
-    : surface === "generic"
-    ? "No installed AGDF host surface could be selected safely; rerun status with an explicit --surface."
-    : installation.status !== "healthy"
-    ? `Run npx --yes @agdf/cli@latest ${surface} to install or repair AGDF.`
-    : repository.status === "disabled"
-    ? "Restart the host to apply the repository-local disable; the healthy global AGDF installation remains available."
-    : repository.status === "degraded"
-    ? "The repository marketplace is incomplete or invalid; use the supported repository scaffold or the healthy durable global AGDF installation."
-    : repository.status === "not_configured"
-    ? `Run npx --yes @agdf/cli@latest ${surface === "codex" ? "codex-repo" : `${surface}-repo`} in this repository.`
-    : delivery.status === "blocked"
-    ? "Resolve the reported delivery blocker without changing the healthy installation."
-    : delivery.status === "not_configured"
-    ? "Start a new task; status created no run and requires no approval. Initialize durable control only when the repository needs it."
-    : "Continue with the reported delivery next step.";
-  return { schema_version: 1, installation, repository, delivery, runtime_checks: runtimeChecks, next_action: { kind: "action", text: nextText } };
+}
+
+function nextStatusAction(installation, repository, delivery) {
+  const surface = installation.surface;
+  if (surface === "multiple") return "Multiple AGDF host surfaces were detected; rerun status with an explicit --surface.";
+  if (surface === "generic") return "No installed AGDF host surface could be selected safely; rerun status with an explicit --surface.";
+  if (installation.status !== "healthy") return `Run ${bootstrapCommands(surface).install} to install or repair AGDF.`;
+  if (repository.status === "unresolved") return "Provide an explicit --dir to include repository and delivery status; cwd is not target authority.";
+  if (repository.status === "disabled") return "Restart the host to apply the repository-local disable; the healthy global AGDF installation remains available.";
+  if (repository.status === "degraded") return "The repository marketplace is incomplete or invalid; use the supported repository scaffold or the healthy durable global AGDF installation.";
+  if (repository.status === "not_configured") return `Run ${bootstrapCommands(surface).repository} in this repository.`;
+  if (delivery.status === "blocked") return "Resolve the reported delivery blocker without changing the healthy installation.";
+  if (delivery.status === "not_configured") return "Start a new task; status created no run and requires no approval. Initialize durable control only when the repository needs it.";
+  return "Continue with the reported delivery next step.";
+}
+
+function composeStatus({ operationId, targetDir = null, options, installation, dependencies }) {
+  const surface = installation.surface;
+  const repository = targetDir
+    ? repositoryStatus(targetDir, surface, dependencies)
+    : { status: "unresolved", scope: "repository", evidence: [] };
+  const delivery = targetDir
+    ? deliveryStatus(targetDir, { runId: options.runId }, dependencies)
+    : { status: "unresolved", run_id: null, current_gate: null, evidence: [] };
+  return {
+    schema_version: 1,
+    operation_status: createOperationStatus({
+      operationId,
+      outcome: "reported",
+      targetScope: targetDir ? "repository" : "global",
+      target: targetDir,
+      plannedEffect: "read_only_status",
+      excludedAuthority: ["target_inference", "run_creation", "gate_approval", "mutation"],
+    }),
+    installation,
+    repository,
+    delivery,
+    runtime_checks: runtimeStatus(surface, options),
+    next_action: { kind: "action", text: nextStatusAction(installation, repository, delivery) },
+  };
+}
+
+function statusDependencies(dependencies) {
+  return {
+    evaluateDoctor: dependencies.evaluateDoctor ?? evaluateDoctor,
+    evaluateGateCheck: dependencies.evaluateGateCheck ?? evaluateGateCheck,
+    inspectControlPresence: dependencies.inspectControlPresence
+      ?? ((targetDir) => inspectControlPresence(targetDir, dependencies)),
+    evaluateOpenCodeRepositoryActivation: dependencies.evaluateOpenCodeRepositoryActivation
+      ?? evaluateOpenCodeRepositoryActivation,
+  };
+}
+
+export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}) {
+  const installation = publicInstallationFacts(inspectGlobalInstallationStatus(options, dependencies));
+  return composeStatus({
+    operationId: "status.repository_delivery",
+    targetDir,
+    options,
+    installation,
+    dependencies: statusDependencies(dependencies),
+  });
+}
+
+export function evaluateStatusOverview(options = {}, dependencies = {}) {
+  const installation = publicInstallationFacts(inspectGlobalInstallationStatus(options, dependencies));
+  const targetDir = typeof options.targetDir === "string" && options.targetDir ? options.targetDir : null;
+  return composeStatus({
+    operationId: "status.overview",
+    targetDir,
+    options,
+    installation,
+    dependencies: statusDependencies(dependencies),
+  });
+}
+
+function bootstrapCommands(surface) {
+  if (surface === "opencode") return openCodeInstaller.bootstrapCommands();
+  return pluginBootstrapCommands(surface) ?? { install: `npx --yes @agdf/cli@latest ${surface}`, repository: `npx --yes @agdf/cli@latest ${surface}-repo` };
 }