create-agdf 0.9.1 → 0.9.5

package/lib/cli/command-registry.js

@@ -0,0 +1,119 @@
+function command(name, usages) {
+  return Object.freeze({
+    name,
+    handler: name,
+    groups: Object.freeze(Object.keys(usages)),
+    usages: Object.freeze(Object.fromEntries(
+      Object.entries(usages).map(([group, suffixes]) => [group, Object.freeze(suffixes)]),
+    )),
+  });
+}
+
+export const commandRegistry = Object.freeze([
+  command("codex", { preferred: [""], scaffold: [""] }),
+  command("codex-repo", { preferred: [""], scaffold: [""] }),
+  command("claude", { preferred: [""], scaffold: [""] }),
+  command("copilot", { preferred: [""], scaffold: [""] }),
+  command("opencode", { preferred: [""], scaffold: [""] }),
+  command("opencode-status", { preferred: [""], scaffold: [""] }),
+  command("status", { preferred: [" [--surface <surface>] [--run <run_id>] [--json]"] }),
+  command("disable", { preferred: [" --surface <surface> [--scope repository] [--dir <path>]"] }),
+  command("uninstall", { preferred: [" --surface <surface> --scope global [--confirm]"] }),
+  command("opencode-repo", { preferred: [""], scaffold: [""] }),
+  command("both", { scaffold: [""] }),
+  command("init", { preferred: [""], scaffold: [""] }),
+  command("config", { scaffold: [" --language de"] }),
+  command("doctor", { preferred: [""], scaffold: [""], legacy: [" --json"] }),
+  command("gate-check", { preferred: [" --json"], scaffold: [""], legacy: [" --json"] }),
+  command("delivery-map", { scaffold: [""] }),
+  command("delivery-path-search", {
+    preferred: [" --surface codex --json", " --surface claude --json"],
+    scaffold: [" --surface codex", " --surface claude"],
+  }),
+  command("run-create", { preferred: [" --run <run_id>"] }),
+  command("run-migrate", { preferred: [" [--run <run_id>]"] }),
+  command("run-render-legacy", { preferred: [" --run <run_id>"] }),
+]);
+
+const commandByName = new Map(commandRegistry.map((entry) => [entry.name, entry]));
+
+export function resolveCommand(name) {
+  return commandByName.get(name) ?? null;
+}
+
+export function supportedCommandNames() {
+  return commandRegistry.map((entry) => entry.name);
+}
+
+export function validateCommandOptions(options) {
+  if (options.allActive && !["doctor", "delivery-map"].includes(options.target)) {
+    throw new Error("--all-active is supported only by doctor and delivery-map");
+  }
+  if (options.target === "run-create" && (!options.runId || options.allActive)) {
+    throw new Error("run-create requires --run and rejects --all-active");
+  }
+  if (options.target === "run-render-legacy" && !options.runId) {
+    throw new Error("run-render-legacy requires --run");
+  }
+  if (["disable", "uninstall"].includes(options.target) && ["", "generic", undefined].includes(options.surface)) {
+    throw new Error(`${options.target} requires an explicit --surface`);
+  }
+  if (options.target === "disable" && options.scope && options.scope !== "repository") {
+    throw new Error("disable supports repository scope only");
+  }
+  if (options.target === "uninstall" && options.scope !== "global") {
+    throw new Error("uninstall requires explicit --scope global");
+  }
+  if (options.confirm && options.target !== "uninstall") throw new Error("--confirm is supported only by uninstall");
+  return options;
+}
+
+function usageLines(group, prefix) {
+  return commandRegistry
+    .flatMap((entry) => (entry.usages[group] ?? []).map((suffix) => `  ${prefix}${entry.name}${suffix}`))
+    .join("\n");
+}
+
+export function renderUsage() {
+  return `AGDF CLI
+
+Primary commands:
+${usageLines("preferred", "npx --yes @agdf/cli@latest ")}
+
+Advanced / Compatibility
+
+Scaffold-compatible npm create usage:
+${usageLines("scaffold", "npm create agdf@latest -- ")}
+
+Backward-compatible create-agdf usage:
+${usageLines("legacy", "npx --yes create-agdf@latest ")}
+
+Options:
+  --dir <path>   Write files into a specific directory. With opencode, use this as the OpenCode config directory.
+  --force        Overwrite existing generated files
+  --language <tag>
+                 Set AGDF chat and artefact language. Defaults to detected system locale.
+  --lang <tag>   Alias for --language
+  --json         Print machine-readable command output as JSON
+  --status-card  Print compact gate-check status-card output for interactive use
+  --run <run_id> Select one canonical run
+  --all-active   Evaluate every active run (doctor and delivery-map only)
+  --surface <codex|claude|copilot|opencode|generic>
+                 Declare the active Delivery Path Search surface
+  --scope <repository|global>
+                 Select the lifecycle mutation scope
+  --confirm      Apply a previously previewed global uninstall plan
+  --fixture <path>
+                 Use deterministic evaluator/candidate fixtures instead of a live evaluator
+  --persist      Persist the redacted Delivery Path Search result under the current scope
+  --model <id>   Optional Codex evaluator model
+  --generate-candidates
+                 Add one bounded AI-native candidate-generation call before evaluation
+  --generator-model <id>
+                 Optional candidate-generator model override
+  --max-generated-candidates <1-5>
+  --generation-timeout-ms <1-30000>
+  --generation-cost-units <1-5>
+  --help         Show this help
+`;
+}

package/lib/cli/delivery-path-search-command.js

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { searchInputFromControl } from '../delivery-path-search/state-adapter.js';
+import { runDeliveryPathSearch } from '../delivery-path-search/search-engine.js';
+import { codexEvaluator } from '../delivery-path-search/evaluators/codex.js';
+import { claudeEvaluator } from '../delivery-path-search/evaluators/claude.js';
+import { fixtureEvaluator } from '../delivery-path-search/evaluators/protocol.js';
+import { codexGenerator } from '../delivery-path-search/generators/codex.js';
+import { claudeGenerator } from '../delivery-path-search/generators/claude.js';
+import { fixtureGenerator } from '../delivery-path-search/generators/protocol.js';
+import { enforcementForSurface } from '../delivery-path-search/surfaces/capabilities.js';
+import { persistSearchResult } from '../delivery-path-search/persistence.js';
+
+export async function executeDeliveryPathSearch(options, io = console) {
+  const fixture = options.fixture ? JSON.parse(readFileSync(options.fixture, "utf8")) : null;
+  const enforcement = fixture?.input?.enforcement ?? enforcementForSurface(options.surface);
+  const fixtureGeneration = fixture?.generator_response;
+  const generationEnabled = Boolean(fixtureGeneration || options.generateCandidates);
+  const baseInput = fixture?.input ?? searchInputFromControl(options.dir, {
+    scopeKey: options.runId,
+    enforcement,
+    generation: generationEnabled ? {
+      enabled: true,
+      maxProposals: options.maxGeneratedCandidates,
+      maxDurationMs: options.generationTimeoutMs,
+      maxCostUnits: options.generationCostUnits,
+    } : undefined,
+  });
+  const input = generationEnabled && !baseInput.generation ? {
+    ...baseInput,
+    generation: {
+      enabled: true,
+      max_calls: 1,
+      max_proposals: options.maxGeneratedCandidates,
+      max_duration_ms: options.generationTimeoutMs,
+      max_cost_units: options.generationCostUnits,
+    },
+  } : baseInput;
+  const evaluator = fixture
+    ? fixtureEvaluator(fixture.evaluations ?? {})
+    : options.surface === "codex"
+      ? codexEvaluator({ cwd: options.dir, model: options.model })
+      : options.surface === "claude"
+        ? claudeEvaluator({ cwd: options.dir, model: options.model })
+        : null;
+  if (!evaluator) {
+    throw new Error(`${options.surface} has no executable evaluator in this release. Codex and Claude are the reference adapters; --fixture is available for deterministic contract testing.`);
+  }
+  const generator = fixtureGeneration
+    ? fixtureGenerator(fixtureGeneration)
+    : options.generateCandidates && options.surface === "codex"
+      ? codexGenerator({ cwd: options.dir, model: options.generatorModel, timeoutMs: options.generationTimeoutMs })
+      : options.generateCandidates && options.surface === "claude"
+        ? claudeGenerator({ cwd: options.dir, model: options.generatorModel, timeoutMs: options.generationTimeoutMs })
+        : null;
+  if (options.generateCandidates && !generator) {
+    throw new Error(`${options.surface} has no executable candidate generator; Codex and Claude are tool-enforced reference transports.`);
+  }
+  const result = await runDeliveryPathSearch(input, evaluator, { candidates: fixture?.candidates, generator });
+  if (options.persist) result.persistence = persistSearchResult(options.dir, result);
+  if (options.json) {
+    io.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  io.log(`AGDF Delivery Path Search: ${result.status}`);
+  io.log(`Current gate: ${result.current_gate}`);
+  io.log(`Enforcement: ${result.enforcement.level}`);
+  io.log(`Recommendation: ${result.recommendation?.action ?? "none"}`);
+  io.log(`Evaluations: ${result.budgets.evaluations}`);
+  io.log(`Generation: ${result.generation.status} (${result.generation.accepted}/${result.generation.returned} accepted)`);
+  io.log(`Generation budget: ${result.generation.cost_units} cost units, ${result.generation.duration_ms} ms`);
+  if (result.generation.failure_code) io.log(`Generation failure: ${result.generation.failure_code}`);
+  io.log(`Stopping reason: ${result.stopping_reason}`);
+  io.log(result.next_gate_action);
+  return result;
+}

package/lib/cli/parse-args.js

@@ -0,0 +1,150 @@
+import { resolve } from "node:path";
+import process from "node:process";
+import { configuredLanguage, resolveLanguagePreference } from "./runtime-context.js";
+import { resolveCommand, supportedCommandNames } from "./command-registry.js";
+
+export class CliUsageError extends Error {
+  constructor(message, { showUsage = false } = {}) {
+    super(message);
+    this.name = "CliUsageError";
+    this.exitCode = 1;
+    this.showUsage = showUsage;
+  }
+}
+
+function requiredValue(args, index, option) {
+  const next = args[index + 1];
+  if (!next) throw new CliUsageError(`Missing value for ${option}`);
+  return next;
+}
+
+export function parseArgs(argv, dependencies = {}) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  const languagePreference = dependencies.resolveLanguagePreference ?? resolveLanguagePreference;
+  const normalizeLanguage = dependencies.configuredLanguage ?? configuredLanguage;
+  const args = [...argv];
+  let target;
+  let dir = ".";
+  let force = false;
+  let json = false;
+  let statusCard = false;
+  let language;
+  let dirExplicit = false;
+  let surface = "generic";
+  let fixture;
+  let persist = false;
+  let model;
+  let generateCandidates = false;
+  let generatorModel;
+  let maxGeneratedCandidates = 5;
+  let generationTimeoutMs = 30000;
+  let generationCostUnits = 5;
+  let runId;
+  let allActive = false;
+  let scope;
+  let confirm = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg === "--help" || arg === "-h") return { kind: "help" };
+    if (arg === "--force") { force = true; continue; }
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--status-card") { statusCard = true; continue; }
+    if (arg === "--persist") { persist = true; continue; }
+    if (arg === "--generate-candidates") { generateCandidates = true; continue; }
+    if (arg === "--all-active") { allActive = true; continue; }
+    if (arg === "--confirm") { confirm = true; continue; }
+
+    if (arg === "--run") {
+      runId = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (["--surface", "--scope", "--fixture", "--model", "--generator-model", "--max-generated-candidates", "--generation-timeout-ms", "--generation-cost-units"].includes(arg)) {
+      const next = requiredValue(args, i, arg);
+      if (arg === "--surface") {
+        if (!["codex", "claude", "copilot", "opencode", "generic"].includes(next)) {
+          throw new CliUsageError("Unsupported surface. Use codex, claude, copilot, opencode or generic.");
+        }
+        surface = next;
+      } else if (arg === "--scope") {
+        if (!["repository", "global"].includes(next)) throw new CliUsageError("Unsupported scope. Use repository or global.");
+        scope = next;
+      } else if (arg === "--fixture") fixture = next;
+      else if (arg === "--model") model = next;
+      else if (arg === "--generator-model") generatorModel = next;
+      else {
+        const value = Number(next);
+        const maximum = arg === "--generation-timeout-ms" ? 30000 : 5;
+        if (!Number.isInteger(value) || value < 1 || value > maximum) {
+          throw new CliUsageError(`${arg} must be an integer from 1 to ${maximum}.`);
+        }
+        if (arg === "--max-generated-candidates") maxGeneratedCandidates = value;
+        else if (arg === "--generation-timeout-ms") generationTimeoutMs = value;
+        else generationCostUnits = value;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--language" || arg === "--lang") {
+      const next = requiredValue(args, i, arg);
+      const normalized = normalizeLanguage(next);
+      if (!normalized) throw new CliUsageError("Invalid language tag. Use a BCP 47 tag such as de, en or fr-CA.");
+      language = normalized;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--dir") {
+      dir = requiredValue(args, i, arg);
+      dirExplicit = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--target" || arg === "-t") {
+      target = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !target) {
+      target = arg;
+      continue;
+    }
+    throw new CliUsageError(`Unknown argument: ${arg}`);
+  }
+
+  if (!target || !resolveCommand(target)) {
+    throw new CliUsageError(`Please choose one target: ${supportedCommandNames().join(", ")}.`, { showUsage: true });
+  }
+
+  return {
+    kind: "command",
+    options: {
+      target,
+      dir: resolve(cwd, dir),
+      force,
+      json,
+      statusCard,
+      dirExplicit,
+      language: languagePreference(language),
+      surface,
+      fixture: fixture ? resolve(cwd, fixture) : null,
+      persist,
+      model,
+      generateCandidates,
+      runId,
+      allActive,
+      scope,
+      confirm,
+      generatorModel,
+      maxGeneratedCandidates,
+      generationTimeoutMs,
+      generationCostUnits,
+    },
+  };
+}

package/lib/cli/runtime-context.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import {
+  canonicalizeLanguageTag,
+  resolvePresentationLocale,
+} from "../interaction-presentation.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const packageRoot = resolve(__dirname, "../..");
+export const generatedRoot = join(packageRoot, "generated");
+
+const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
+const interactionLocalesPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-interaction-locales.json");
+
+export const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
+export const interactionLocales = JSON.parse(readFileSync(interactionLocalesPath, "utf8"));
+
+export function configuredLanguage(value) {
+  const normalized = canonicalizeLanguageTag(value);
+  if (!normalized) return "";
+  const language = normalized.split("-")[0];
+  if (interactionLocales.locales[normalized] || interactionLocales.locales[language]) {
+    return resolvePresentationLocale(interactionLocales, normalized);
+  }
+  return normalized;
+}
+
+export function detectSystemLocale(env = process.env) {
+  const envLocale = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || "";
+  if (envLocale) return envLocale;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale || "";
+  } catch {
+    return "";
+  }
+}
+
+export function resolveLanguagePreference(explicitLanguage, env = process.env) {
+  const explicit = configuredLanguage(explicitLanguage);
+  if (explicit) {
+    return {
+      artifact_language: explicit,
+      chat_language: explicit,
+      runtime_language: "en",
+      source: "parameter",
+      detected_locale: detectSystemLocale(env) || "unknown",
+    };
+  }
+
+  const detectedLocale = detectSystemLocale(env);
+  const detected = configuredLanguage(detectedLocale) || interactionLocales.fallbackLocale;
+  return {
+    artifact_language: detected,
+    chat_language: detected,
+    runtime_language: "en",
+    source: detectedLocale ? "system_locale" : "default",
+    detected_locale: detectedLocale || "unknown",
+  };
+}
+
+export function resolveConfiguredChatLanguage(targetDir) {
+  const configPath = join(targetDir, ".agdf", "control", "config.json");
+  if (!existsSync(configPath)) return interactionLocales.fallbackLocale;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    return resolvePresentationLocale(interactionLocales, config.chat_language);
+  } catch {
+    return interactionLocales.fallbackLocale;
+  }
+}
+
+export function languageConfigContent(languagePreference) {
+  return `${JSON.stringify({
+    artifact_language: languagePreference.artifact_language,
+    chat_language: languagePreference.chat_language,
+    runtime_language: languagePreference.runtime_language,
+    source: languagePreference.source,
+    detected_locale: languagePreference.detected_locale,
+  }, null, 2)}\n`;
+}