@harness-forge/cli 0.1.0

package/scripts/ci/capability-matrix-shared.mjs

@@ -0,0 +1,263 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import Ajv2020 from "ajv/dist/2020.js";
+
+const CAPABILITY_SUPPORT_REF = "manifests/catalog/harness-capability-matrix.json";
+
+async function readJson(root, relativePath) {
+  return JSON.parse(await fs.readFile(path.join(root, relativePath), "utf8"));
+}
+
+async function readText(root, relativePath) {
+  return fs.readFile(path.join(root, relativePath), "utf8");
+}
+
+function formatSupportCell(record) {
+  return `${record.supportLevel} (${record.supportMode})`;
+}
+
+function toSummaryCell(records, taxonomyById, predicate) {
+  const values = records
+    .filter(predicate)
+    .map((record) => taxonomyById.get(record.capabilityId)?.displayName ?? record.capabilityId);
+
+  return values.length > 0 ? values.join(", ") : "none";
+}
+
+export async function loadCapabilityInputs(root) {
+  const [taxonomy, matrix, schema, targetManifest, compatibilityMatrix] = await Promise.all([
+    readJson(root, "manifests/catalog/capability-taxonomy.json"),
+    readJson(root, "manifests/catalog/harness-capability-matrix.json"),
+    readJson(root, "schemas/manifests/harness-capability-matrix.schema.json"),
+    readJson(root, "manifests/targets/core.json"),
+    readJson(root, "manifests/catalog/compatibility-matrix.json")
+  ]);
+
+  const adapters = await Promise.all(
+    (targetManifest.targets ?? []).map(async (target) => {
+      const adapterPath = `targets/${target.id}/adapter.json`;
+      try {
+        return [target.id, await readJson(root, adapterPath)];
+      } catch {
+        return [target.id, null];
+      }
+    })
+  );
+
+  return {
+    taxonomy,
+    matrix,
+    schema,
+    targetManifest,
+    compatibilityMatrix,
+    adapters: new Map(adapters)
+  };
+}
+
+export function buildCapabilityCompatibilityEntries(matrix) {
+  return [...matrix.targets]
+    .flatMap((target) =>
+      target.capabilities.map((record) => ({
+        subjectType: "target",
+        subjectId: target.targetId,
+        relationType: "supports-capability",
+        relatedType: "capability",
+        relatedId: record.capabilityId,
+        supportLevel: record.supportLevel,
+        supportMode: record.supportMode,
+        confidence: record.confidence,
+        evidenceSource: record.evidenceSource,
+        fallbackBehavior: record.fallbackBehavior,
+        ...(record.notes ? { notes: record.notes } : {})
+      }))
+    )
+    .sort((left, right) =>
+      `${left.subjectType}:${left.subjectId}:${left.relatedType}:${left.relatedId}`.localeCompare(
+        `${right.subjectType}:${right.subjectId}:${right.relatedType}:${right.relatedId}`
+      )
+    );
+}
+
+export function renderTargetSupportMarkdown(taxonomy, matrix) {
+  const taxonomyById = new Map(taxonomy.capabilities.map((entry) => [entry.id, entry]));
+  const lines = [
+    "# Target Support Matrix",
+    "",
+    "Harness Forge keeps one canonical target-capability truth source in",
+    "`manifests/catalog/harness-capability-matrix.json`. The broader",
+    "`manifests/catalog/compatibility-matrix.json` remains a derived view for",
+    "cross-surface relationships.",
+    "",
+    "## Support levels",
+    "",
+    "- `full`: shipped and validated in this package",
+    "- `partial`: usable with explicit gaps and fallback guidance",
+    "- `emulated`: approximated behavior without a native runtime surface",
+    "- `unsupported`: do not rely on it",
+    "",
+    "## Support modes",
+    "",
+    "- `native`: first-class runtime support ships in the package",
+    "- `translated`: support works through portable scripts or guidance layers",
+    "- `emulated`: behavior is approximated rather than native",
+    "- `documentation-only`: only docs and manifests are portable",
+    "- `unsupported`: no packaged runtime support is claimed",
+    "",
+    "## Target summary",
+    "",
+    "| Target | Overall support | Strengths | Gaps |",
+    "| --- | --- | --- | --- |"
+  ];
+
+  for (const target of matrix.targets) {
+    const strengths = toSummaryCell(
+      target.capabilities,
+      taxonomyById,
+      (record) => record.supportLevel === "full" && record.supportMode === "native"
+    );
+    const gaps = toSummaryCell(
+      target.capabilities,
+      taxonomyById,
+      (record) => !(record.supportLevel === "full" && record.supportMode === "native")
+    );
+    lines.push(`| \`${target.targetId}\` | ${target.supportLevel} | ${strengths} | ${gaps} |`);
+  }
+
+  lines.push("", "## Capability honesty", "", `| Capability | ${matrix.targets.map((target) => target.displayName).join(" | ")} |`);
+  lines.push(`| --- | ${matrix.targets.map(() => "---").join(" | ")} |`);
+
+  for (const capability of taxonomy.capabilities) {
+    const cells = matrix.targets.map((target) => {
+      const record = target.capabilities.find((entry) => entry.capabilityId === capability.id);
+      return record ? formatSupportCell(record) : "missing";
+    });
+    lines.push(`| ${capability.displayName} | ${cells.join(" | ")} |`);
+  }
+
+  lines.push("", "## Degraded support details");
+
+  for (const target of matrix.targets) {
+    const degraded = target.capabilities.filter(
+      (record) => !(record.supportLevel === "full" && record.supportMode === "native")
+    );
+    lines.push("", `### ${target.displayName}`);
+    if (degraded.length === 0) {
+      lines.push("", "- none");
+      continue;
+    }
+
+    lines.push("");
+    for (const record of degraded) {
+      const label = taxonomyById.get(record.capabilityId)?.displayName ?? record.capabilityId;
+      const detail = record.notes ? ` ${record.notes}` : "";
+      lines.push(
+        `- ${label}: ${record.supportLevel} via ${record.supportMode}. Fallback: ${record.fallbackBehavior ?? "No fallback documented."}${detail}`
+      );
+    }
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+export async function collectCapabilityValidationIssues(root, options = {}) {
+  const { checkDocs = true, checkCompatibility = true } = options;
+  const issues = [];
+  const { taxonomy, matrix, schema, targetManifest, compatibilityMatrix, adapters } = await loadCapabilityInputs(root);
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  ajv.addFormat("date-time", true);
+  const validate = ajv.compile(schema);
+
+  if (!validate(matrix)) {
+    for (const error of validate.errors ?? []) {
+      issues.push(`Schema validation failed at ${error.instancePath || "/"}: ${error.message}`);
+    }
+  }
+
+  const taxonomyIds = taxonomy.capabilities.map((entry) => entry.id);
+  const taxonomyIdSet = new Set(taxonomyIds);
+  if (taxonomyIdSet.size !== taxonomyIds.length) {
+    issues.push("Capability taxonomy contains duplicate capability ids.");
+  }
+
+  const targetIds = (targetManifest.targets ?? []).map((target) => target.id);
+  const targetIdSet = new Set(targetIds);
+  const matrixTargetIds = matrix.targets.map((target) => target.targetId);
+  if (new Set(matrixTargetIds).size !== matrixTargetIds.length) {
+    issues.push("Capability matrix contains duplicate target ids.");
+  }
+
+  for (const targetId of targetIds) {
+    if (!matrixTargetIds.includes(targetId)) {
+      issues.push(`Capability matrix is missing target ${targetId}.`);
+    }
+  }
+
+  for (const target of matrix.targets) {
+    if (!targetIdSet.has(target.targetId)) {
+      issues.push(`Capability matrix includes unknown target ${target.targetId}.`);
+    }
+
+    const capabilityIds = target.capabilities.map((record) => record.capabilityId);
+    if (new Set(capabilityIds).size !== capabilityIds.length) {
+      issues.push(`Target ${target.targetId} has duplicate capability records.`);
+    }
+
+    for (const capabilityId of taxonomyIds) {
+      if (!capabilityIds.includes(capabilityId)) {
+        issues.push(`Target ${target.targetId} is missing capability ${capabilityId}.`);
+      }
+    }
+
+    for (const record of target.capabilities) {
+      if (!taxonomyIdSet.has(record.capabilityId)) {
+        issues.push(`Target ${target.targetId} references unknown capability ${record.capabilityId}.`);
+      }
+
+      const degraded = !(record.supportLevel === "full" && record.supportMode === "native");
+      if (degraded && !record.fallbackBehavior) {
+        issues.push(`Target ${target.targetId} capability ${record.capabilityId} is degraded but missing fallback behavior.`);
+      }
+      if (!record.validationMethod) {
+        issues.push(`Target ${target.targetId} capability ${record.capabilityId} is missing validationMethod.`);
+      }
+      if (!record.evidenceSource?.length) {
+        issues.push(`Target ${target.targetId} capability ${record.capabilityId} is missing evidenceSource.`);
+      }
+    }
+  }
+
+  for (const target of targetManifest.targets ?? []) {
+    if (target.capabilitySupportRef !== CAPABILITY_SUPPORT_REF) {
+      issues.push(`Target manifest ${target.id} must set capabilitySupportRef to ${CAPABILITY_SUPPORT_REF}.`);
+    }
+
+    const adapter = adapters.get(target.id);
+    if (adapter && adapter.capabilitySupportRef !== CAPABILITY_SUPPORT_REF) {
+      issues.push(`Target adapter ${target.id} must set capabilitySupportRef to ${CAPABILITY_SUPPORT_REF}.`);
+    }
+  }
+
+  if (checkDocs) {
+    const expected = renderTargetSupportMarkdown(taxonomy, matrix);
+    const actual = await readText(root, "docs/target-support-matrix.md");
+    if (actual.replaceAll("\r\n", "\n") !== expected.replaceAll("\r\n", "\n")) {
+      issues.push("docs/target-support-matrix.md is out of sync with the canonical capability matrix.");
+    }
+  }
+
+  if (checkCompatibility) {
+    const actualEntries = (compatibilityMatrix.entries ?? []).filter(
+      (entry) => entry.relationType === "supports-capability" && entry.relatedType === "capability"
+    );
+    const expectedEntries = buildCapabilityCompatibilityEntries(matrix);
+    if (JSON.stringify(actualEntries) !== JSON.stringify(expectedEntries)) {
+      issues.push("manifests/catalog/compatibility-matrix.json is out of sync with the canonical capability matrix.");
+    }
+  }
+
+  return issues;
+}
+
+export { CAPABILITY_SUPPORT_REF };

package/scripts/ci/generate-compatibility-matrix.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { buildCapabilityCompatibilityEntries, loadCapabilityInputs } from "./capability-matrix-shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+async function readJson(relativePath) {
+  return JSON.parse(await fs.readFile(path.join(root, relativePath), "utf8"));
+}
+
+async function listBundleManifests() {
+  const manifestDir = path.join(root, "manifests", "bundles");
+  const files = await fs.readdir(manifestDir);
+  const manifests = await Promise.all(files.map((file) => readJson(path.join("manifests", "bundles", file))));
+  return manifests.flatMap((manifest) => manifest.bundles ?? []);
+}
+
+async function listWorkflowIds() {
+  const workflowDir = path.join(root, "templates", "workflows");
+  const files = await fs.readdir(workflowDir);
+  return files.filter((file) => file.endsWith(".md")).map((file) => file.replace(/\.md$/, ""));
+}
+
+async function listSkillIds() {
+  const skillDir = path.join(root, "skills");
+  const entries = await fs.readdir(skillDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function noteForLevel(target, level, subjectType, subjectId) {
+  if (level === "full") {
+    return undefined;
+  }
+
+  if (level === "partial") {
+    return `${target.displayName} only provides partial ${subjectType} support for ${subjectId}.`;
+  }
+
+  if (level === "emulated") {
+    return `${target.displayName} only emulates ${subjectType} support for ${subjectId}.`;
+  }
+
+  return `${target.displayName} does not ship ${subjectType} support for ${subjectId}.`;
+}
+
+const [{ targets }, { hooks }, languageAssets, frameworkAssets, { matrix: capabilityMatrixInputs }] = await Promise.all([
+  readJson(path.join("manifests", "targets", "core.json")),
+  readJson(path.join("manifests", "hooks", "index.json")),
+  readJson(path.join("manifests", "catalog", "language-assets.json")),
+  readJson(path.join("manifests", "catalog", "framework-assets.json")),
+  loadCapabilityInputs(root)
+]);
+const bundleManifests = await listBundleManifests();
+const workflowIds = await listWorkflowIds();
+const skillIds = await listSkillIds();
+const profileFiles = await fs.readdir(path.join(root, "manifests", "profiles"));
+const profiles = (
+  await Promise.all(profileFiles.map((file) => readJson(path.join("manifests", "profiles", file))))
+).flatMap((manifest) => manifest.profiles ?? []);
+
+const frameworkByBundleId = new Map((frameworkAssets.frameworks ?? []).map((framework) => [framework.bundleId, framework]));
+const entries = [];
+
+for (const bundle of bundleManifests) {
+  for (const target of targets) {
+    const level = bundle.targets.includes(target.id)
+      ? target.supportLevel === "partial" || target.supportLevel === "emulated"
+        ? target.supportLevel
+        : "full"
+      : "unsupported";
+    entries.push({
+      subjectType: "target",
+      subjectId: target.id,
+      relationType: "supports",
+      relatedType: "bundle",
+      relatedId: bundle.id,
+      supportLevel: level,
+      ...(noteForLevel(target, level, "bundle", bundle.id) ? { notes: noteForLevel(target, level, "bundle", bundle.id) } : {})
+    });
+  }
+}
+
+for (const hook of hooks ?? []) {
+  for (const target of targets) {
+    const level = hook.targetCompatibility?.[target.id] ?? "unsupported";
+    entries.push({
+      subjectType: "target",
+      subjectId: target.id,
+      relationType: "supports",
+      relatedType: "hook",
+      relatedId: hook.id,
+      supportLevel: level,
+      ...(noteForLevel(target, level, "hook", hook.id) ? { notes: noteForLevel(target, level, "hook", hook.id) } : {})
+    });
+  }
+}
+
+for (const skillId of skillIds) {
+  for (const target of targets) {
+    const level = target.id === "codex" || target.id === "claude-code" ? "full" : "partial";
+    entries.push({
+      subjectType: "target",
+      subjectId: target.id,
+      relationType: "supports",
+      relatedType: "skill",
+      relatedId: skillId,
+      supportLevel: level,
+      ...(noteForLevel(target, level, "skill", skillId) ? { notes: noteForLevel(target, level, "skill", skillId) } : {})
+    });
+  }
+}
+
+for (const workflowId of workflowIds) {
+  for (const target of targets) {
+    const level = target.id === "codex" || target.id === "claude-code" ? "full" : "partial";
+    entries.push({
+      subjectType: "workflow",
+      subjectId: workflowId,
+      relationType: "supports",
+      relatedType: "target",
+      relatedId: target.id,
+      supportLevel: level,
+      ...(noteForLevel(target, level, "workflow", workflowId) ? { notes: noteForLevel(target, level, "workflow", workflowId) } : {})
+    });
+  }
+}
+
+for (const profile of profiles) {
+  for (const target of targets) {
+    const level = profile.targetCompatibility?.[target.id] ?? "unsupported";
+    entries.push({
+      subjectType: "profile",
+      subjectId: profile.id,
+      relationType: "supports",
+      relatedType: "target",
+      relatedId: target.id,
+      supportLevel: level,
+      ...(noteForLevel(target, level, "profile", profile.id) ? { notes: noteForLevel(target, level, "profile", profile.id) } : {})
+    });
+  }
+}
+
+for (const [languageId, entry] of Object.entries(languageAssets.languages ?? {})) {
+  for (const frameworkBundleId of entry.frameworkBundles ?? []) {
+    const framework = frameworkByBundleId.get(frameworkBundleId);
+    if (!framework) {
+      continue;
+    }
+
+    entries.push({
+      subjectType: "language",
+      subjectId: languageId,
+      relationType: "extends",
+      relatedType: "framework",
+      relatedId: framework.id,
+      supportLevel: "full"
+    });
+  }
+}
+
+entries.push(...buildCapabilityCompatibilityEntries(capabilityMatrixInputs));
+
+entries.sort((left, right) =>
+  `${left.subjectType}:${left.subjectId}:${left.relatedType}:${left.relatedId}`.localeCompare(
+    `${right.subjectType}:${right.subjectId}:${right.relatedType}:${right.relatedId}`
+  )
+);
+
+const output = {
+  generatedAt: new Date().toISOString(),
+  entries
+};
+
+const destination = path.join(root, "manifests", "catalog", "compatibility-matrix.json");
+await fs.writeFile(destination, `${JSON.stringify(output, null, 2)}\n`, "utf8");
+
+const result = { ok: true, destination, entries: entries.length };
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/ci/generate-target-support-docs.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { loadCapabilityInputs, renderTargetSupportMarkdown } from "./capability-matrix-shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+const destination = path.join(root, "docs", "target-support-matrix.md");
+
+const { taxonomy, matrix } = await loadCapabilityInputs(root);
+const content = renderTargetSupportMarkdown(taxonomy, matrix);
+await fs.writeFile(destination, content, "utf8");
+
+const result = {
+  ok: true,
+  destination,
+  targets: matrix.targets.length,
+  capabilities: taxonomy.capabilities.length
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/ci/release-smoke.mjs

@@ -0,0 +1,121 @@
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const nodeCommand = process.execPath;
+const powerShellCandidates = process.platform === "win32" ? ["pwsh", "powershell"] : ["pwsh"];
+const shellCandidates = process.platform === "win32" ? ["bash"] : ["bash", "sh"];
+const requiredSurfaces = [
+  "manifests/catalog/enhanced-skill-import-inventory.json",
+  "docs/authoring/enhanced-skill-import.md",
+  "docs/release-process.md",
+  "CONTRIBUTING.md",
+  "CHANGELOG.md"
+];
+
+function run(command, args) {
+  return spawnSync(command, args, {
+    cwd: root,
+    stdio: "pipe",
+    encoding: "utf8"
+  });
+}
+
+const missingSurfaces = requiredSurfaces.filter((relativePath) => !fs.existsSync(path.join(root, relativePath)));
+if (missingSurfaces.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures: missingSurfaces.map((name) => ({ name, stderr: "Missing required surface" })) }, null, 2));
+  process.exit(1);
+}
+
+const scriptRuns = [
+  ["scripts/ci/smoke-runner.mjs"],
+  ["scripts/ci/validate-pack-dependencies.mjs"],
+  ["scripts/ci/validate-content-metadata.mjs"],
+  ["scripts/ci/validate-seeded-knowledge-coverage.mjs"],
+  ["scripts/ci/validate-generated-sync.mjs"],
+  ["scripts/ci/validate-packed-install-surface.mjs"],
+  ["scripts/ci/validate-capability-matrix.mjs"],
+  ["scripts/ci/validate-no-placeholders.mjs"],
+  ["scripts/ci/validate-skill-depth.mjs"],
+  ["scripts/ci/validate-framework-coverage.mjs"],
+  ["scripts/ci/validate-doc-command-alignment.mjs"],
+  ["scripts/ci/validate-manifest-runtime-consistency.mjs"],
+  ["scripts/knowledge/report-coverage.mjs", "--json"],
+  ["scripts/knowledge/report-drift.mjs", "--json"]
+].map(([relativePath, ...extraArgs]) => ({
+  name: relativePath,
+  result: run(nodeCommand, [path.join(root, relativePath), ...extraArgs])
+}));
+
+const powerShell = powerShellCandidates.find((candidate) => (run(candidate, ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"]).status ?? 1) === 0);
+const powerShellRuns = powerShell
+  ? [
+      ["scripts/templates/powershell/Check-TemplateFrontmatter.ps1", ["-Root", "."]],
+      ["scripts/templates/powershell/Check-TemplateLinks.ps1", ["-Root", "."]],
+      ["scripts/templates/powershell/Get-MissingTemplateSections.ps1", ["-Root", "."]],
+      ["scripts/templates/powershell/Test-WorkflowContracts.ps1", ["-Root", "."]]
+    ].map(([scriptPath, args]) => ({
+      name: scriptPath,
+      result: run(powerShell, ["-File", path.join(root, scriptPath), ...args])
+    }))
+  : [];
+
+const distCliPath = path.join(root, "dist", "cli", "index.js");
+const cliRuns = fs.existsSync(distCliPath)
+  ? [
+      { name: "help", result: run(nodeCommand, [distCliPath, "--help"]) },
+      { name: "init", result: run(nodeCommand, [distCliPath, "init", "--help"]) },
+      { name: "refresh", result: run(nodeCommand, [distCliPath, "refresh", "--help"]) },
+      { name: "task", result: run(nodeCommand, [distCliPath, "task", "--help"]) },
+      { name: "pack", result: run(nodeCommand, [distCliPath, "pack", "--help"]) },
+      { name: "review", result: run(nodeCommand, [distCliPath, "review", "--help"]) },
+      { name: "export", result: run(nodeCommand, [distCliPath, "export", "--help"]) },
+      { name: "catalog", result: run(nodeCommand, [distCliPath, "catalog", "--json"]) },
+      { name: "template-validate", result: run(nodeCommand, [distCliPath, "template", "validate", "--json"]) },
+      { name: "flow-status", result: run(nodeCommand, [distCliPath, "flow", "status", "--json"]) },
+      { name: "doctor", result: run(nodeCommand, [distCliPath, "doctor", "--json"]) },
+      { name: "audit", result: run(nodeCommand, [distCliPath, "audit", "--json"]) }
+    ]
+  : [];
+
+const shellRuntime = shellCandidates.find((candidate) => (run(candidate, ["-lc", "printf ok"]).status ?? 1) === 0);
+const shellRuns = shellRuntime
+  ? [
+      ["scripts/templates/shell/check-template-frontmatter.sh", ["."]],
+      ["scripts/templates/shell/check-template-links.sh", ["."]],
+      ["scripts/templates/shell/list-missing-template-sections.sh", ["."]],
+      ["scripts/templates/shell/verify-workflow-contracts.sh", ["."]]
+    ].map(([scriptPath, args]) => ({
+      name: scriptPath,
+      result: run(shellRuntime, [path.join(root, scriptPath), ...args])
+    }))
+  : [];
+
+const results = [...scriptRuns, ...shellRuns, ...powerShellRuns, ...cliRuns];
+const failures = results
+  .filter(({ result }) => (result.status ?? 1) !== 0)
+  .map(({ name, result }) => ({
+    name,
+    stdout: result.stdout?.trim(),
+    stderr: result.stderr?.trim()
+  }));
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      scripts: scriptRuns.length,
+      shell: shellRuns.length,
+      powerShell: powerShellRuns.length,
+      cli: cliRuns.length
+    },
+    null,
+    2
+  )
+);

package/scripts/ci/smoke-runner.mjs

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const cliPath = path.join(root, "dist", "cli", "index.js");
+
+function runCli(args, cwd = root) {
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    cwd,
+    encoding: "utf8",
+    stdio: "pipe"
+  });
+}
+
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hforge-production-smoke-"));
+await fs.writeFile(
+  path.join(tempRoot, "package.json"),
+  `${JSON.stringify({ name: "smoke-repo", private: true, version: "1.0.0" }, null, 2)}\n`,
+  "utf8"
+);
+
+const scenarios = [
+  {
+    name: "global-help",
+    args: ["--help"],
+    expectStatus: 0,
+    expectStdout: "Usage: hforge"
+  },
+  {
+    name: "commands-json",
+    args: ["commands", "--json"],
+    expectStatus: 0,
+    expectStdout: "\"cliCommands\""
+  },
+  {
+    name: "target-inspect",
+    args: ["target", "inspect", "codex", "--json"],
+    expectStatus: 0,
+    expectStdout: "\"id\": \"codex\""
+  },
+  {
+    name: "init",
+    args: ["init", "--root", tempRoot, "--json"],
+    expectStatus: 0,
+    expectStdout: "\"runtimeIndexPath\""
+  },
+  {
+    name: "status-after-init",
+    args: ["status", "--root", tempRoot, "--json"],
+    expectStatus: 0,
+    expectStdout: "\"runtimeSchemaVersion\""
+  },
+  {
+    name: "refresh-guidance",
+    args: ["refresh", "--root", tempRoot],
+    expectStatus: 1,
+    expectStderr: "No installed targets were found"
+  }
+];
+
+const results = scenarios.map((scenario) => {
+  const result = runCli(scenario.args);
+  return {
+    ...scenario,
+    status: result.status ?? 1,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim()
+  };
+});
+
+const failures = results.filter((result) => {
+  if (result.status !== result.expectStatus) {
+    return true;
+  }
+  if (result.expectStdout && !result.stdout.includes(result.expectStdout)) {
+    return true;
+  }
+  if (result.expectStderr && !result.stderr.includes(result.expectStderr)) {
+    return true;
+  }
+  return false;
+});
+
+console.log(JSON.stringify({ ok: failures.length === 0, tempRoot, results }, null, 2));
+
+if (failures.length > 0) {
+  process.exit(1);
+}