create-agdf 0.9.1 → 0.9.5

package/lib/lifecycle/operations.js

@@ -0,0 +1,177 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+import { evaluateOpenCodeStatus, openCodeNpmInvocation } from "../installers/opencode.js";
+import { inspectPluginSurface } from "../installers/plugin-installers.js";
+
+const CODEX_DISABLE_MARKER = "# AGDF-OWNED-REPOSITORY-PLUGIN-STATE";
+
+function pluginSection(content, selector) {
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return content.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
+}
+
+function repositorySelector(targetDir) {
+  return existsSync(join(targetDir, ".agents", "plugins", "marketplace.json")) ? "agdf@agdf-repo" : "agdf@agdf";
+}
+
+export function planRepositoryDisable(targetDir, surface) {
+  if (surface !== "codex") {
+    throw new Error(`Repository disable is not supported safely for ${surface}; no files were changed.`);
+  }
+  const path = join(targetDir, ".codex", "config.toml");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const selector = repositorySelector(targetDir);
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const sectionPattern = new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`);
+  const currentSection = pluginSection(existing, selector);
+  const enabledMatches = [...currentSection.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  if (currentSection && enabledMatches.length !== 1) {
+    throw new Error(`Refusing to modify ambiguous AGDF plugin state in ${path}.`);
+  }
+  const section = currentSection
+    ? currentSection.replace(/^enabled\s*=\s*(true|false)\s*$/m, "enabled = false")
+    : `${CODEX_DISABLE_MARKER}\n[plugins.${JSON.stringify(selector)}]\nenabled = false`;
+  const content = currentSection
+    ? existing.replace(sectionPattern, section).replace(/\s*$/, "\n")
+    : `${existing.replace(/\s*$/, "")}${existing.trim() ? "\n\n" : ""}${section}\n`;
+  return Object.freeze({
+    operation: "disable",
+    surface,
+    scope: "repository",
+    mutations: Object.freeze([{ kind: "write", path, content, ownership: currentSection ? "exact_plugin_section" : "agdf_marker" }]),
+    retained: Object.freeze([join(targetDir, ".agdf", "control"), "global AGDF plugin availability"]),
+    expected: Object.freeze({ repository_status: "disabled" }),
+  });
+}
+
+export function verifyRepositoryDisabled(targetDir) {
+  const path = join(targetDir, ".codex", "config.toml");
+  if (!existsSync(path)) return { status: "failed", evidence: [`missing:${path}`] };
+  const selector = repositorySelector(targetDir);
+  const section = pluginSection(readFileSync(path, "utf8"), selector);
+  const matches = [...section.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  return matches.length === 1 && matches[0][1] === "false"
+    ? { status: "healthy", evidence: [`${path}:${selector}:enabled=false`] }
+    : { status: "failed", evidence: [`postcondition_failed:${path}:${selector}`] };
+}
+
+export function verifyGlobalUninstall(plan, targetDir, { configDir, exec, inspect = inspectPluginSurface, evaluateOpenCode = evaluateOpenCodeStatus } = {}) {
+  if (plan.surface === "opencode") {
+    const report = evaluateOpenCode(targetDir, configDir);
+    const remainingOwnedFiles = plan.mutations
+      .filter((mutation) => mutation.kind === "remove")
+      .map((mutation) => mutation.path)
+      .filter((path) => existsSync(path));
+    return report.status === "not_configured" && remainingOwnedFiles.length === 0
+      ? { status: "healthy", evidence: [report.global_config.path, "marker_owned_global_files_removed"] }
+      : { status: "failed", evidence: [report.global_config.path, ...remainingOwnedFiles.map((path) => `still_present:${path}`)] };
+  }
+  const report = inspect(plan.surface, exec);
+  return report.status === "not_installed"
+    ? { status: "healthy", evidence: report.evidence }
+    : { status: "failed", evidence: [...report.evidence, `observed:${report.status}`] };
+}
+
+export function planGlobalUninstall(surface, { configDir } = {}) {
+  if (surface === "codex") {
+    return nativeUninstallPlan(surface, "codex", ["plugin", "remove", "agdf@agdf"]);
+  }
+  if (surface === "claude") {
+    return nativeUninstallPlan(surface, "claude", ["plugin", "uninstall", "agdf@agdf", "--scope", "user"]);
+  }
+  if (surface === "opencode") {
+    if (!configDir) throw new Error("OpenCode uninstall requires its explicit config directory.");
+    const configPath = join(configDir, "opencode.json");
+    if (!existsSync(configPath)) throw new Error(`OpenCode config not found: ${configPath}`);
+    let config;
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Refusing to modify unreadable OpenCode config: ${configPath}`);
+    }
+    if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+      throw new Error(`Refusing to modify OpenCode config with non-array plugin field: ${configPath}`);
+    }
+    const next = { ...config };
+    next.plugin = (config.plugin ?? []).filter((entry) => entry !== pluginDefinition.opencode.npmPackage);
+    if (Array.isArray(config.instructions)) next.instructions = config.instructions.filter((entry) => entry !== "AGDF.md");
+    const npm = openCodeNpmInvocation(["uninstall", "--silent", pluginDefinition.opencode.npmPackage]);
+    const mutations = [
+      { kind: "write", path: configPath, content: `${JSON.stringify(next, null, 2)}\n`, ownership: "exact_known_entries" },
+      { kind: "command", executable: npm.executable, args: npm.args, cwd: configDir },
+    ];
+    const retained = ["repository AGDF files", ".agdf/control"];
+    for (const candidate of openCodeOwnedGlobalFiles(configDir)) {
+      if (!existsSync(candidate.path)) continue;
+      const content = readFileSync(candidate.path, "utf8");
+      if (candidate.owned(content)) mutations.push({ kind: "remove", path: candidate.path, ownership: "agdf_marker" });
+      else retained.push(candidate.path);
+    }
+    return Object.freeze({
+      operation: "uninstall",
+      surface,
+      scope: "global",
+      mutations: Object.freeze(mutations),
+      retained: Object.freeze(retained),
+      expected: Object.freeze({ installation_status: "not_installed" }),
+    });
+  }
+  throw new Error(`Global uninstall is not supported for ${surface}.`);
+}
+
+function openCodeOwnedGlobalFiles(configDir) {
+  const firstLine = (marker) => (content) => content.split(/\r?\n/)[0] === marker;
+  const afterFrontmatter = (marker) => (content) => {
+    const lines = content.split(/\r?\n/);
+    const end = lines.findIndex((line, index) => index > 0 && line === "---");
+    return end >= 0 && lines[end + 1] === marker;
+  };
+  const files = [
+    { path: join(configDir, pluginDefinition.opencode.instructionsFileName), owned: firstLine("<!-- AGDF-GLOBAL-INSTRUCTIONS -->") },
+    { path: join(configDir, pluginDefinition.opencode.runtimeContractFileName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") },
+  ];
+  for (const moduleName of ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"]) {
+    files.push({ path: join(configDir, "contracts", moduleName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") });
+  }
+  for (const skill of pluginDefinition.skillSet) {
+    const name = `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`;
+    const marker = `<!-- AGDF-GLOBAL-SKILL: ${name} -->`;
+    files.push({ path: join(configDir, "skills", name, "SKILL.md"), owned: afterFrontmatter(marker) });
+  }
+  return files;
+}
+
+function nativeUninstallPlan(surface, executable, args) {
+  return Object.freeze({
+    operation: "uninstall",
+    surface,
+    scope: "global",
+    mutations: Object.freeze([{ kind: "command", executable, args: Object.freeze(args) }]),
+    retained: Object.freeze(["repository AGDF files", ".agdf/control", "ambiguous configuration"]),
+    expected: Object.freeze({ installation_status: "not_installed" }),
+  });
+}
+
+export function applyLifecyclePlan(plan, { exec = execFileSync } = {}) {
+  const completed = [];
+  for (const mutation of plan.mutations) {
+    try {
+      if (mutation.kind === "write") {
+        mkdirSync(dirname(mutation.path), { recursive: true });
+        writeFileSync(mutation.path, mutation.content, "utf8");
+        completed.push({ kind: "write", path: mutation.path });
+      } else if (mutation.kind === "remove") {
+        rmSync(mutation.path);
+        completed.push({ kind: "remove", path: mutation.path });
+      } else if (mutation.kind === "command") {
+        exec(mutation.executable, mutation.args, { cwd: mutation.cwd, stdio: "inherit" });
+        completed.push({ kind: "command", executable: mutation.executable, args: mutation.args });
+      }
+    } catch (error) {
+      return { status: completed.length ? "partial" : "failed", completed, error, retained: [...plan.retained] };
+    }
+  }
+  return { status: "success", completed, error: null, retained: [...plan.retained] };
+}

package/lib/lifecycle/presentation.js

@@ -0,0 +1,52 @@
+import { interactionLocales } from "../cli/runtime-context.js";
+
+function copy(locale) {
+  const language = String(locale ?? "").toLowerCase().split("-")[0];
+  return (interactionLocales.locales[language] ?? interactionLocales.locales[interactionLocales.fallbackLocale]).primary.lifecycleResult;
+}
+
+export function lifecycleCardLines(report, locale = "en") {
+  const c = copy(locale);
+  const version = report.version.transition === "updated" && report.version.previous && report.version.installed
+    ? `${report.version.previous} -> ${report.version.installed}`
+    : report.version.installed || (report.version.expected ? `${c.unknown}; expected ${report.version.expected}` : c.unknown);
+  const versionStatus = report.version.transition && report.version.transition !== "updated"
+    ? `${report.version.status}; transition ${report.version.transition}`
+    : report.version.status;
+  return [
+    c.title,
+    `${c.result}: ${report.result}`,
+    `${c.surface}: ${report.surface}`,
+    `${c.scope}: ${report.scope}`,
+    `${c.version}: ${version} (${versionStatus})`,
+    `${c.verification}: ${report.verification.status}`,
+    `${c.restart}: ${report.restart.required ? c.yes : c.no}${report.restart.reason !== "none" ? ` (${report.restart.reason})` : ""}`,
+    `${c.next}: ${report.next_action.text}`,
+  ];
+}
+
+export function printLifecycleResult(report, { json = false, locale = "en", io = console } = {}) {
+  if (json) {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const line of lifecycleCardLines(report, locale)) io.log(line);
+  if (report.failure) io.log(`Failure phase: ${report.failure.phase}: ${report.failure.message}`);
+  if (report.retained.length) {
+    io.log("Retained:");
+    for (const item of report.retained) io.log(`- ${typeof item === "string" ? item : JSON.stringify(item)}`);
+  }
+}
+
+export function printGeneralStatus(report, { json = false, locale = "en", io = console } = {}) {
+  if (json) {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const c = copy(locale);
+  io.log(c.statusTitle);
+  io.log(`${c.installation}: ${report.installation.status}${report.installation.version ? ` (${report.installation.version})` : ""}`);
+  io.log(`${c.repository}: ${report.repository.status}`);
+  io.log(`${c.delivery}: ${report.delivery.status}${report.delivery.current_gate ? ` (${report.delivery.current_gate})` : ""}`);
+  io.log(`${c.next}: ${report.next_action.text}`);
+}

package/lib/lifecycle/result.js

@@ -0,0 +1,69 @@
+const OPERATIONS = new Set(["install", "update", "status", "disable", "uninstall", "repository_setup"]);
+const RESULTS = new Set(["success", "partial", "failed", "preview"]);
+const SCOPES = new Set(["global", "repository"]);
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function createLifecycleResult(input = {}) {
+  const result = {
+    schema_version: 1,
+    operation: text(input.operation),
+    result: text(input.result),
+    surface: text(input.surface),
+    scope: text(input.scope),
+    version: {
+      expected: text(input.version?.expected) || null,
+      installed: text(input.version?.installed) || null,
+      previous: text(input.version?.previous) || null,
+      status: text(input.version?.status) || "unknown",
+      transition: text(input.version?.transition) || null,
+    },
+    verification: {
+      status: text(input.verification?.status) || "unknown",
+      evidence: [...(input.verification?.evidence ?? [])].map(String),
+    },
+    restart: {
+      required: Boolean(input.restart?.required),
+      reason: text(input.restart?.reason) || "none",
+    },
+    next_action: {
+      kind: text(input.next_action?.kind) || "none",
+      text: text(input.next_action?.text) || "No further action required.",
+    },
+    changes: [...(input.changes ?? [])],
+    retained: [...(input.retained ?? [])],
+    failure: input.failure ?? null,
+  };
+  assertLifecycleResult(result);
+  return Object.freeze(result);
+}
+
+export function assertLifecycleResult(value) {
+  if (value?.schema_version !== 1) throw new Error("Lifecycle result requires schema_version 1.");
+  if (!OPERATIONS.has(value.operation)) throw new Error(`Unsupported lifecycle operation: ${value.operation || "missing"}.`);
+  if (!RESULTS.has(value.result)) throw new Error(`Unsupported lifecycle result: ${value.result || "missing"}.`);
+  if (!value.surface) throw new Error("Lifecycle result requires a surface.");
+  if (!SCOPES.has(value.scope)) throw new Error(`Unsupported lifecycle scope: ${value.scope || "missing"}.`);
+  if (!value.next_action || Array.isArray(value.next_action) || !text(value.next_action.text)) {
+    throw new Error("Lifecycle result requires exactly one next action.");
+  }
+  if (value.version.status === "verified" && !value.version.installed) {
+    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.");
+  return value;
+}
+
+export function lifecycleFailure({ operation, surface, scope, phase, message, evidence = [], nextAction }) {
+  return createLifecycleResult({
+    operation,
+    result: "failed",
+    surface,
+    scope,
+    verification: { status: "degraded", evidence },
+    next_action: { kind: "recovery", text: nextAction },
+    failure: { phase, message },
+  });
+}

package/lib/lifecycle/status.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } 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";
+
+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) {
+    return { status: "not_configured", run_id: null, current_gate: null, evidence: [] };
+  }
+  try {
+    const doctor = dependencies.evaluateDoctor(targetDir, selection);
+    const gate = dependencies.evaluateGateCheck(targetDir, selection);
+    return {
+      status: gate.status === "blocked" || doctor.status === "block" ? "blocked" : gate.status === "complete" ? "complete" : "open",
+      run_id: selection.runId || null,
+      current_gate: gate.current_gate || null,
+      evidence: [`doctor:${doctor.status}`, `gate-check:${gate.status}`],
+    };
+  } catch (error) {
+    return { status: "unknown", run_id: selection.runId || null, current_gate: null, evidence: [error.message] };
+  }
+}
+
+function repositoryStatus(targetDir, surface) {
+  if (surface === "codex") {
+    const marketplace = join(targetDir, ".agents", "plugins", "marketplace.json");
+    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" : existsSync(marketplace) ? "active" : "not_configured", scope: "repository", evidence: [marketplace] };
+  }
+  if (surface === "opencode") {
+    const instructions = join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName);
+    return { status: existsSync(instructions) ? "active" : "not_configured", scope: "repository", evidence: [instructions] };
+  }
+  return { status: "unknown", scope: "repository", evidence: [] };
+}
+
+function inspectInstallation(surface, targetDir, options, deps, exec) {
+  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],
+    };
+  }
+  if (["codex", "claude"].includes(surface)) return deps.inspectPluginSurface(surface, exec);
+  return { status: "unknown", surface, version: null, evidence: [`unsupported_status_probe:${surface}`] };
+}
+
+export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}) {
+  const deps = {
+    evaluateDoctor: dependencies.evaluateDoctor ?? evaluateDoctor,
+    evaluateGateCheck: dependencies.evaluateGateCheck ?? evaluateGateCheck,
+    evaluateOpenCodeStatus: dependencies.evaluateOpenCodeStatus ?? evaluateOpenCodeStatus,
+    inspectPluginSurface: dependencies.inspectPluginSurface ?? inspectPluginSurface,
+  };
+  let surface = options.surface && options.surface !== "generic" ? options.surface : null;
+  let installation;
+  if (surface) {
+    installation = inspectInstallation(surface, targetDir, options, deps, dependencies.exec);
+  } else {
+    const probes = ["codex", "claude", "opencode"].map((candidate) => inspectInstallation(candidate, targetDir, options, deps, dependencies.exec));
+    const observed = probes.filter((probe) => ["healthy", "degraded"].includes(probe.status));
+    if (observed.length === 1) {
+      installation = observed[0];
+      surface = installation.surface;
+    } else {
+      surface = observed.length > 1 ? "multiple" : "generic";
+      installation = {
+        status: "unknown",
+        surface,
+        version: null,
+        evidence: probes.flatMap((probe) => probe.evidence.map((item) => `${probe.surface}:${item}`)),
+      };
+    }
+  }
+  const repository = repositoryStatus(targetDir, surface);
+  const delivery = deliveryStatus(targetDir, { runId: options.runId }, deps);
+  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 === "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, next_action: { kind: "action", text: nextText } };
+}