create-agdf 0.10.1 → 0.10.2

package/lib/runtime/local-validator.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import process from "node:process";
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function digestDirectory(root) {
+  const files = [];
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stats = statSync(path);
+      if (stats.isDirectory()) visit(path);
+      else if (stats.isFile()) files.push(path);
+    }
+  }
+  visit(root);
+  const hash = createHash("sha256");
+  for (const path of files) {
+    hash.update(relative(root, path).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(readFileSync(path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function envelope(machineValidation, options, evidence = {}) {
+  return {
+    schema_version: "1",
+    machine_validation: machineValidation,
+    surface: options.surface,
+    expected_version: options.expectedVersion,
+    observed_version: evidence.observedVersion ?? null,
+    source: evidence.source ?? null,
+    registry_access: false,
+    ...(evidence.reason ? { reason: evidence.reason } : {}),
+  };
+}
+
+export function resolveLocalValidator(options) {
+  if (options.ownedPackageRoot) {
+    const packageManifest = readJson(join(options.ownedPackageRoot, "package.json"));
+    const observedVersion = packageManifest?.version ?? null;
+    if (!packageManifest) {
+      return { envelope: envelope("unavailable", options, { source: "config_local_package", reason: "package_missing" }) };
+    }
+    if (observedVersion !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "config_local_package" }) };
+    }
+    const entrypoint = join(options.ownedPackageRoot, "bin", "create-agdf.js");
+    if (!existsSync(entrypoint)) {
+      return { envelope: envelope("unavailable", options, { observedVersion, source: "config_local_package", reason: "entrypoint_missing" }) };
+    }
+    return {
+      envelope: envelope("owned_version_matched", options, { observedVersion, source: "config_local_package" }),
+      executable: process.execPath,
+      prefixArgs: [entrypoint],
+    };
+  }
+  const manifestPath = join(options.runtimeRoot, "runtime-manifest.json");
+  const manifestExists = existsSync(manifestPath);
+  const manifest = manifestExists ? readJson(manifestPath) : null;
+  if (manifestExists && !manifest) {
+    return { envelope: envelope("version_mismatch", options, { source: "plugin_bundle", reason: "manifest_invalid" }) };
+  }
+  if (manifest) {
+    const packageRoot = join(options.runtimeRoot, "create-agdf");
+    if (!existsSync(packageRoot)) {
+      return { envelope: envelope("unavailable", options, { source: "plugin_bundle", reason: "package_missing" }) };
+    }
+    const packageManifest = readJson(join(packageRoot, "package.json"));
+    const observedVersion = packageManifest?.version ?? manifest.version ?? null;
+    if (observedVersion !== options.expectedVersion || manifest.version !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle" }) };
+    }
+    let observedDigest = null;
+    try { observedDigest = digestDirectory(packageRoot); } catch {}
+    if (!observedDigest || manifest.digest !== observedDigest) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle", reason: "digest_mismatch" }) };
+    }
+    const entrypoint = resolve(options.runtimeRoot, manifest.entrypoint ?? "");
+    const entrypointRelative = relative(options.runtimeRoot, entrypoint);
+    if (!manifest.entrypoint || entrypointRelative === ".." || entrypointRelative.startsWith(`..${sep}`) || isAbsolute(entrypointRelative)) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "plugin_bundle", reason: "invalid_entrypoint" }) };
+    }
+    if (!existsSync(entrypoint)) {
+      return { envelope: envelope("unavailable", options, { observedVersion, source: "plugin_bundle", reason: "entrypoint_missing" }) };
+    }
+    return {
+      envelope: envelope("owned_version_matched", options, { observedVersion, source: "plugin_bundle" }),
+      executable: process.execPath,
+      prefixArgs: [entrypoint],
+    };
+  }
+
+  const configuredPath = options.configuredPath ?? process.env.AGDF_VALIDATOR_PATH ?? "";
+  if (configuredPath) {
+    if (!isAbsolute(configuredPath) || !existsSync(configuredPath)) {
+      return { envelope: envelope("unavailable", options, { source: "configured_path", reason: "invalid_absolute_path" }) };
+    }
+    const versionProbe = spawnSync(configuredPath, ["--version", "--json"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    let observedVersion = null;
+    try { observedVersion = JSON.parse(versionProbe.stdout)?.version ?? null; } catch {}
+    if (versionProbe.status !== 0 || observedVersion !== options.expectedVersion) {
+      return { envelope: envelope("version_mismatch", options, { observedVersion, source: "configured_path" }) };
+    }
+    return {
+      envelope: envelope("configured_version_matched", options, { observedVersion, source: "configured_path" }),
+      executable: configuredPath,
+      prefixArgs: [],
+    };
+  }
+
+  return { envelope: envelope(options.externalRequired ? "external_required" : "unavailable", options) };
+}
+
+export function runLocalValidator(options, args, io = console) {
+  const resolved = resolveLocalValidator(options);
+  if (args[0] === "--resolve-only") {
+    io.log(JSON.stringify(resolved.envelope, null, args.includes("--json") ? 2 : 0));
+    return resolved.executable ? 0 : 2;
+  }
+  if (!resolved.executable) {
+    io.error(JSON.stringify(resolved.envelope));
+    return 2;
+  }
+  const child = spawnSync(resolved.executable, [...resolved.prefixArgs, ...args], {
+    cwd: options.cwd ?? process.cwd(),
+    env: { ...process.env, AGDF_MACHINE_VALIDATION: resolved.envelope.machine_validation },
+    stdio: "inherit",
+  });
+  return child.status ?? 2;
+}

package/lib/runtime/validator-application.js

@@ -0,0 +1,40 @@
+import process from "node:process";
+import { createValidationHandlers } from "../cli/validation-handlers.js";
+import { validateCommandOptions } from "../cli/command-registry.js";
+import { CliUsageError, parseArgs } from "../cli/parse-args.js";
+import { pluginDefinition } from "../cli/runtime-context.js";
+
+const validatorCommands = new Set(["doctor", "gate-check", "delivery-map", "delivery-path-search"]);
+
+export async function runValidatorCli(argv = process.argv.slice(2), adapters = {}) {
+  const io = adapters.io ?? console;
+  if (argv.includes("--version")) {
+    const output = { name: "create-agdf", version: pluginDefinition.version };
+    io.log(argv.includes("--json") ? JSON.stringify(output) : output.version);
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs(argv, adapters.parser);
+  } catch (error) {
+    if (!(error instanceof CliUsageError)) throw error;
+    io.error(error.message);
+    return error.exitCode;
+  }
+  if (parsed.kind === "help") {
+    io.log("AGDF surface-local validator: doctor | gate-check | delivery-map | delivery-path-search");
+    return 0;
+  }
+  let options;
+  try {
+    options = validateCommandOptions(parsed.options);
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  if (!validatorCommands.has(options.target)) {
+    io.error(`The surface-local validator does not support lifecycle command: ${options.target}`);
+    return 1;
+  }
+  return await createValidationHandlers(io).get(options.target)(options);
+}

package/lib/scaffold/plan.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.js";
+export { doctorRequiredFiles } from "../control-evaluation/required-files.js";
 
 export const agdfFragmentPath = "AGENTS.agdf.md";
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
@@ -92,13 +93,6 @@ const artefactTemplateFiles = [
   join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
   join(".agdf", "control", "templates", "artefacts", "OR.md"),
 ];
-export const doctorRequiredFiles = [
-  join(".agdf", "control", "AGDF_RUN.md"),
-  join(".agdf", "control", "MASTER_BACKLOG.md"),
-  join(".agdf", "control", "SOT_REGISTRY.md"),
-  join(".agdf", "control", "CONTEXT_GRAPH.md"),
-  join(".agdf", "control", "AGENT_QUALITY_CONTRACTS.json"),
-];
 const copilotInstructionFiles = [
   join(".github", "copilot-instructions.md"),
   join(".github", "instructions", "agdf-governance.instructions.md"),

package/lib/scaffold/presentation.js

@@ -70,13 +70,13 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
   }
   if (target === "init") {
     io.log("- Create or migrate a canonical run, then fill its RUN_STATE.md with the current gate, evidence and next allowed action.");
-    io.log("- Run npx --yes @agdf/cli@latest doctor to check the control state before the next agent run.");
+    io.log("- Run the installed `agdf doctor` to check the control state before the next agent run.");
     io.log("- Commit the live control files once they represent the repository's current delivery state.");
     return;
   }
   if (target === "config") {
     io.log("- Restart or start a new agent session so the AGDF SessionStart hook reads the updated project language config.");
-    io.log("- Run npx --yes @agdf/cli@latest doctor when this repository also uses durable AGDF control state.");
+    io.log("- Run the installed `agdf doctor` when this repository also uses durable AGDF control state.");
     return;
   }
   if (wroteAgentsFragment) {

package/opencode-plugin.js

@@ -21,7 +21,7 @@ export const AGDFPlugin = async ({ directory, client }) => {
     "## AGDF Runtime Reminder",
     "This repository is AGDF-active through `.agdf/control/config.json`; use the globally installed AGDF runtime surface.",
     "For new build/change intent or unclear approval, load the native `agdf-global-gate-check` skill before later artefacts or implementation.",
-    "Use `npx --yes @agdf/cli@latest gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
+    "Use the config-local `agdf/bin/agdf-local.js gate-check --status-card` for compact interactive status. Use `--json` only as deterministic proof for automation or audit evidence, and summarize it instead of mirroring full JSON into chat.",
   ].join("\n");
 
   const inactiveGuidance = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -25,6 +25,10 @@
     "test:delivery-path-search-unit": "node ./scripts/delivery-path-search-unit-test.js",
     "test:delivery-path-search-generator": "node ./scripts/delivery-path-search-generator-test.js",
     "test:cli-modularization": "node ./scripts/cli-modularization-test.js",
+    "test:local-validator": "node ./scripts/local-validator-test.js",
+    "test:local-marketplace": "node ./scripts/local-marketplace-test.js",
+    "test:package-contents": "node ./scripts/package-contents-test.js",
+    "test:package-build": "node ./scripts/package-build-test.js",
     "test:lifecycle": "node ./scripts/lifecycle-test.js",
     "test:control-state": "node ./scripts/control-state-test.js",
     "test:interaction-presentation": "node ./scripts/interaction-presentation-test.js",
@@ -36,7 +40,7 @@
     "eval:skills:record": "node ./scripts/record-skill-evals.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && npm run test:cli-modularization && npm run test:lifecycle && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:cli-modularization && npm run test:local-validator && npm run test:local-marketplace && npm run test:package-build && npm run test:package-contents && npm run test:lifecycle && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [