@harness-forge/cli 0.1.0

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { collectCapabilityValidationIssues, loadCapabilityInputs } from "./capability-matrix-shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+const issues = await collectCapabilityValidationIssues(root);
+
+if (issues.length > 0) {
+  const result = { ok: false, issues };
+  if (json) {
+    console.error(JSON.stringify(result, null, 2));
+  } else {
+    console.error(JSON.stringify(result, null, 2));
+  }
+  process.exit(1);
+}
+
+const { taxonomy, matrix } = await loadCapabilityInputs(root);
+const result = {
+  ok: true,
+  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/validate-content-metadata.mjs

@@ -0,0 +1,188 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+
+const filesToValidate = [
+  "commands/plan.md",
+  "commands/test.md",
+  "agents/planner.md",
+  "contexts/dev.md",
+  "rules/README.md",
+  "rules/typescript/README.md",
+  "rules/java/README.md",
+  "rules/dotnet/README.md",
+  "rules/lua/README.md",
+  "rules/powershell/README.md",
+  "docs/catalog/languages/typescript.md",
+  "docs/catalog/languages/java.md",
+  "docs/catalog/languages/dotnet.md",
+  "docs/catalog/languages/lua.md",
+  "docs/catalog/languages/powershell.md",
+  "docs/style-guides/command-style-guide.md",
+  "docs/style-guides/agent-style-guide.md",
+  "docs/style-guides/rule-style-guide.md",
+  "templates/tasks/implement-feature.md",
+  "templates/tasks/fix-bug.md",
+  "templates/workflows/research-plan-implement-validate.md",
+  "templates/workflows/triage-reproduce-fix-verify.md"
+];
+
+const requiredSectionsByKind = {
+  command: ["## Syntax", "## Arguments and options", "## Output contract", "## Side effects", "## Failure behavior"],
+  agent: ["## Mission", "## Inputs expected", "## Workflow", "## Output contract", "## Stop conditions", "## Escalation rules"],
+  "language-pack": ["## Best fit", "## What ships"],
+  rule: [],
+  "style-guide": [],
+  "task-template": [],
+  "workflow-template": []
+};
+
+const allowedKinds = new Set([
+  "command",
+  "agent",
+  "context",
+  "rule",
+  "example",
+  "language-pack",
+  "style-guide",
+  "task-template",
+  "workflow-template"
+]);
+
+const allowedStatuses = new Set(["draft", "stable", "deprecated"]);
+
+function parseScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed === "true") {
+    return true;
+  }
+
+  if (trimmed === "false") {
+    return false;
+  }
+
+  if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+
+  return trimmed;
+}
+
+function parseYamlObject(raw) {
+  const result = {};
+  let currentArrayKey = null;
+
+  for (const line of raw.replaceAll("\r", "").split("\n")) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    const arrayItemMatch = line.match(/^\s*-\s+(.*)$/);
+    if (arrayItemMatch && currentArrayKey) {
+      result[currentArrayKey].push(parseScalar(arrayItemMatch[1]));
+      continue;
+    }
+
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+    if (!keyMatch) {
+      continue;
+    }
+
+    const [, key, rawValue = ""] = keyMatch;
+    if (rawValue.trim() === "") {
+      result[key] = [];
+      currentArrayKey = key;
+      continue;
+    }
+
+    result[key] = parseScalar(rawValue);
+    currentArrayKey = null;
+  }
+
+  return result;
+}
+
+function parseFrontMatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    metadata: parseYamlObject(match[1]),
+    body: match[2] ?? ""
+  };
+}
+
+function validateMetadata(metadata) {
+  const failures = [];
+  for (const field of ["id", "kind", "title", "summary", "status", "owner", "applies_to", "languages", "generated"]) {
+    if (!(field in metadata)) {
+      failures.push(`Missing required metadata field: ${field}`);
+    }
+  }
+
+  if (metadata.kind && !allowedKinds.has(metadata.kind)) {
+    failures.push(`Unsupported kind: ${metadata.kind}`);
+  }
+
+  if (metadata.status && !allowedStatuses.has(metadata.status)) {
+    failures.push(`Unsupported status: ${metadata.status}`);
+  }
+
+  if (metadata.applies_to && !Array.isArray(metadata.applies_to)) {
+    failures.push("applies_to must be an array.");
+  }
+
+  if (metadata.languages && !Array.isArray(metadata.languages)) {
+    failures.push("languages must be an array.");
+  }
+
+  if ("generated" in metadata && typeof metadata.generated !== "boolean") {
+    failures.push("generated must be a boolean.");
+  }
+
+  if (metadata.generated === true && typeof metadata.canonical_source !== "string") {
+    failures.push("generated content must declare canonical_source.");
+  }
+
+  return failures;
+}
+
+const failures = [];
+
+for (const relativePath of filesToValidate) {
+  const absolutePath = path.join(root, relativePath);
+  const content = await fs.readFile(absolutePath, "utf8");
+  const parsed = parseFrontMatter(content);
+
+  if (!parsed) {
+    failures.push({ file: relativePath, issue: "Missing YAML front matter." });
+    continue;
+  }
+
+  const metadataErrors = validateMetadata(parsed.metadata);
+  if (metadataErrors.length > 0) {
+    failures.push({
+      file: relativePath,
+      issue: "Metadata schema validation failed.",
+      details: metadataErrors
+    });
+    continue;
+  }
+
+  const requiredSections = requiredSectionsByKind[parsed.metadata.kind] ?? [];
+  for (const section of requiredSections) {
+    if (!parsed.body.includes(section)) {
+      failures.push({ file: relativePath, issue: `Missing required section: ${section}` });
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, validatedFiles: filesToValidate.length }, null, 2));

package/scripts/ci/validate-doc-command-alignment.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const docsCommands = await fs.readFile(path.join(root, "docs", "commands.md"), "utf8");
+const readme = await fs.readFile(path.join(root, "README.md"), "utf8");
+const maintenanceDoc = await fs.readFile(path.join(root, "docs", "maintenance-lifecycle.md"), "utf8");
+const flowDoc = await fs.readFile(path.join(root, "docs", "flow-orchestration.md"), "utf8");
+const observabilityDoc = await fs.readFile(path.join(root, "docs", "observability.md"), "utf8");
+const troubleshootingDoc = await fs.readFile(path.join(root, "docs", "troubleshooting.md"), "utf8");
+const releaseProcessDoc = await fs.readFile(path.join(root, "docs", "release-process.md"), "utf8");
+const contributingDoc = await fs.readFile(path.join(root, "CONTRIBUTING.md"), "utf8");
+const packageJson = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+
+const failures = [];
+function includesAny(haystack, fragments) {
+  return fragments.some((fragment) => haystack.includes(fragment));
+}
+
+for (const command of [
+  "init",
+  "install",
+  "bootstrap",
+  "shell setup",
+  "shell status",
+  "refresh",
+  "task list",
+  "task inspect",
+  "pack inspect",
+  "review",
+  "export",
+  "commands",
+  "catalog",
+  "recommend",
+  "scan",
+  "cartograph",
+  "classify-boundaries",
+  "synthesize-instructions",
+  "target inspect",
+  "capabilities",
+  "template validate",
+  "template suggest",
+  "flow status",
+  "observability summarize",
+  "observability report",
+  "parallel plan",
+  "parallel status",
+  "parallel merge-check",
+  "doctor",
+  "audit",
+  "sync",
+  "diff-install",
+  "upgrade-surface",
+  "prune"
+]) {
+  if (!docsCommands.includes(command)) {
+    failures.push({ file: "docs/commands.md", issue: `Missing command reference ${command}` });
+  }
+}
+
+for (const fragment of ["doctor", "audit", "cartograph", "target inspect", "shell setup", "validate:release", "validate:local", "release:dry-run"]) {
+  if (!readme.includes(fragment)) {
+    failures.push({ file: "README.md", issue: `Missing README reference ${fragment}` });
+  }
+}
+
+if (!includesAny(readme, ["flow status", "flow recovery"])) {
+  failures.push({
+    file: "README.md",
+    issue: "Missing README reference for flow status or equivalent flow recovery guidance"
+  });
+}
+
+for (const fragment of ["doctor", "audit", "refresh", "diff-install", "sync", "upgrade-surface", "prune"]) {
+  if (!maintenanceDoc.includes(fragment)) {
+    failures.push({ file: "docs/maintenance-lifecycle.md", issue: `Missing maintenance command ${fragment}` });
+  }
+}
+
+if (!flowDoc.includes("flow status")) {
+  failures.push({ file: "docs/flow-orchestration.md", issue: "Missing flow status command reference." });
+}
+
+for (const fragment of ["report-effectiveness", "observability summarize", "observability report"]) {
+  if (!observabilityDoc.includes(fragment)) {
+    failures.push({ file: "docs/observability.md", issue: `Missing observability command reference ${fragment}.` });
+  }
+}
+
+for (const fragment of ["doctor", "audit", "refresh"]) {
+  if (!troubleshootingDoc.includes(fragment)) {
+    failures.push({ file: "docs/troubleshooting.md", issue: `Missing troubleshooting reference ${fragment}.` });
+  }
+}
+
+for (const fragment of ["validate:release", "release:dry-run"]) {
+  if (!releaseProcessDoc.includes(fragment)) {
+    failures.push({ file: "docs/release-process.md", issue: `Missing release-process reference ${fragment}.` });
+  }
+}
+
+for (const fragment of ["validate:local", "validate:release"]) {
+  if (!contributingDoc.includes(fragment)) {
+    failures.push({ file: "CONTRIBUTING.md", issue: `Missing contributor validation reference ${fragment}.` });
+  }
+}
+
+for (const fragment of ["parallel plan", "parallel status", "parallel merge-check"]) {
+  if (!flowDoc.includes(fragment)) {
+    failures.push({ file: "docs/flow-orchestration.md", issue: `Missing flow command reference ${fragment}.` });
+  }
+}
+
+for (const scriptName of [
+  "recommend:current",
+  "cartograph:current",
+  "instructions:codex",
+  "target:codex",
+  "target:claude-code",
+  "target:opencode",
+  "smoke:cli",
+  "validate:local",
+  "validate:compatibility",
+  "validate:skill-depth",
+  "validate:framework-coverage",
+  "validate:doc-command-alignment",
+  "validate:runtime-consistency",
+  "knowledge:coverage",
+  "knowledge:drift",
+  "flow:status",
+  "observability:summary",
+  "observability:report",
+  "release:dry-run"
+]) {
+  if (!packageJson.scripts?.[scriptName]) {
+    failures.push({ file: "package.json", issue: `Missing npm script ${scriptName}` });
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true }, null, 2));

package/scripts/ci/validate-framework-coverage.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const frameworkAssets = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "catalog", "framework-assets.json"), "utf8")
+);
+const bundleManifest = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "bundles", "frameworks.json"), "utf8")
+);
+const languageAssets = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "catalog", "language-assets.json"), "utf8")
+);
+const catalogDoc = await fs.readFile(path.join(root, "docs", "catalog", "framework-packs.md"), "utf8");
+
+const failures = [];
+for (const framework of frameworkAssets.frameworks ?? []) {
+  const bundle = (bundleManifest.bundles ?? []).find((entry) => entry.id === framework.bundleId);
+  if (!bundle) {
+    failures.push({ frameworkId: framework.id, issue: "Missing framework bundle manifest." });
+    continue;
+  }
+
+  if (!bundle.paths.includes(framework.docPath)) {
+    failures.push({ frameworkId: framework.id, issue: "Bundle does not include framework doc path." });
+  }
+
+  try {
+    await fs.access(path.join(root, framework.docPath));
+  } catch {
+    failures.push({ frameworkId: framework.id, issue: "Framework doc path is missing.", path: framework.docPath });
+  }
+
+  if (!catalogDoc.includes(`\`${framework.id}\``)) {
+    failures.push({ frameworkId: framework.id, issue: "Framework catalog doc is missing the framework id." });
+  }
+
+  const referencedByLanguage = Object.values(languageAssets.languages ?? {}).some((entry) =>
+    (entry.frameworkBundles ?? []).includes(framework.bundleId)
+  );
+  if (!referencedByLanguage) {
+    failures.push({ frameworkId: framework.id, issue: "No language pack references this framework bundle." });
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, frameworks: frameworkAssets.frameworks?.length ?? 0 }, null, 2));

package/scripts/ci/validate-generated-sync.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const scanRoots = ["docs", "commands", "agents", "contexts", "rules", "templates"];
+
+async function listMarkdownFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        return listMarkdownFiles(absolutePath);
+      }
+
+      return absolutePath.endsWith(".md") ? [absolutePath] : [];
+    })
+  );
+
+  return nested.flat();
+}
+
+function parseScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed === "true") {
+    return true;
+  }
+
+  if (trimmed === "false") {
+    return false;
+  }
+
+  if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+
+  return trimmed;
+}
+
+function parseFrontMatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return null;
+  }
+
+  const metadata = {};
+  let currentArrayKey = null;
+
+  for (const line of match[1].replaceAll("\r", "").split("\n")) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    const arrayItemMatch = line.match(/^\s*-\s+(.*)$/);
+    if (arrayItemMatch && currentArrayKey) {
+      metadata[currentArrayKey].push(parseScalar(arrayItemMatch[1]));
+      continue;
+    }
+
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+    if (!keyMatch) {
+      continue;
+    }
+
+    const [, key, rawValue = ""] = keyMatch;
+    if (rawValue.trim() === "") {
+      metadata[key] = [];
+      currentArrayKey = key;
+      continue;
+    }
+
+    metadata[key] = parseScalar(rawValue);
+    currentArrayKey = null;
+  }
+
+  return metadata;
+}
+
+const failures = [];
+let generatedFiles = 0;
+
+for (const scanRoot of scanRoots) {
+  const absoluteRoot = path.join(root, scanRoot);
+  try {
+    await fs.access(absoluteRoot);
+  } catch {
+    continue;
+  }
+
+  for (const absolutePath of await listMarkdownFiles(absoluteRoot)) {
+    const content = await fs.readFile(absolutePath, "utf8");
+    const metadata = parseFrontMatter(content);
+    if (!metadata || metadata.generated !== true) {
+      continue;
+    }
+
+    generatedFiles += 1;
+    const canonicalSource = metadata.canonical_source;
+    if (!canonicalSource) {
+      failures.push({ file: path.relative(root, absolutePath).replaceAll("\\", "/"), issue: "Generated file is missing canonical_source." });
+      continue;
+    }
+
+    const canonicalPath = path.join(root, canonicalSource);
+    try {
+      await fs.access(canonicalPath);
+    } catch {
+      failures.push({
+        file: path.relative(root, absolutePath).replaceAll("\\", "/"),
+        issue: "Generated file points to a missing canonical source.",
+        canonicalSource
+      });
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, generatedFiles }, null, 2));

package/scripts/ci/validate-manifest-runtime-consistency.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+
+async function readJson(relativePath) {
+  return JSON.parse(await fs.readFile(path.join(root, relativePath), "utf8"));
+}
+
+const [targetsManifest, hooksManifest, languageAssets, frameworkAssets, compatibilityMatrix, flowArtifacts, capabilityTaxonomy] = 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")),
+  readJson(path.join("manifests", "catalog", "compatibility-matrix.json")),
+  readJson(path.join("manifests", "catalog", "flow-artifacts.json")),
+  readJson(path.join("manifests", "catalog", "capability-taxonomy.json"))
+]);
+const bundleFiles = await fs.readdir(path.join(root, "manifests", "bundles"));
+const profileFiles = await fs.readdir(path.join(root, "manifests", "profiles"));
+const workflowFiles = await fs.readdir(path.join(root, "templates", "workflows"));
+const skillEntries = await fs.readdir(path.join(root, "skills"), { withFileTypes: true });
+
+const bundles = (
+  await Promise.all(bundleFiles.map((file) => readJson(path.join("manifests", "bundles", file))))
+).flatMap((manifest) => manifest.bundles ?? []);
+const profiles = (
+  await Promise.all(profileFiles.map((file) => readJson(path.join("manifests", "profiles", file))))
+).flatMap((manifest) => manifest.profiles ?? []);
+
+const targetIds = new Set((targetsManifest.targets ?? []).map((target) => target.id));
+const bundleIds = new Set(bundles.map((bundle) => bundle.id));
+const hookIds = new Set((hooksManifest.hooks ?? []).map((hook) => hook.id));
+const profileIds = new Set(profiles.map((profile) => profile.id));
+const workflowIds = new Set(workflowFiles.filter((file) => file.endsWith(".md")).map((file) => file.replace(/\.md$/, "")));
+const skillIds = new Set(skillEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
+const languageIds = new Set(Object.keys(languageAssets.languages ?? {}));
+const frameworkIds = new Set((frameworkAssets.frameworks ?? []).map((framework) => framework.id));
+const capabilityIds = new Set((capabilityTaxonomy.capabilities ?? []).map((capability) => capability.id));
+
+const failures = [];
+
+for (const profile of profiles) {
+  for (const bundleId of profile.bundleIds ?? []) {
+    if (!bundleIds.has(bundleId)) {
+      failures.push({ issue: "Profile references an unknown bundle id.", profileId: profile.id, bundleId });
+    }
+  }
+
+  for (const targetId of profile.recommendedTargets ?? []) {
+    if (!targetIds.has(targetId)) {
+      failures.push({ issue: "Profile references an unknown target.", profileId: profile.id, targetId });
+    }
+  }
+
+  for (const hookId of profile.recommendedHooks ?? []) {
+    if (!hookIds.has(hookId)) {
+      failures.push({ issue: "Profile references an unknown hook.", profileId: profile.id, hookId });
+    }
+  }
+
+  for (const targetId of Object.keys(profile.targetCompatibility ?? {})) {
+    if (!targetIds.has(targetId)) {
+      failures.push({ issue: "Profile targetCompatibility references an unknown target.", profileId: profile.id, targetId });
+    }
+  }
+}
+
+for (const hook of hooksManifest.hooks ?? []) {
+  for (const targetId of Object.keys(hook.targetCompatibility ?? {})) {
+    if (!targetIds.has(targetId)) {
+      failures.push({ issue: "Hook targetCompatibility references an unknown target.", hookId: hook.id, targetId });
+    }
+  }
+}
+
+for (const requiredArtifactId of ["spec", "plan", "tasks", "flow-state", "issue-export"]) {
+  if (!(flowArtifacts.artifacts ?? []).some((artifact) => artifact.id === requiredArtifactId)) {
+    failures.push({ issue: "Flow artifact catalog is missing a required artifact.", artifactId: requiredArtifactId });
+  }
+}
+
+function isKnown(type, id) {
+  switch (type) {
+    case "target":
+      return targetIds.has(id);
+    case "bundle":
+      return bundleIds.has(id);
+    case "hook":
+      return hookIds.has(id);
+    case "profile":
+      return profileIds.has(id);
+    case "workflow":
+      return workflowIds.has(id);
+    case "skill":
+      return skillIds.has(id);
+    case "language":
+      return languageIds.has(id);
+    case "framework":
+      return frameworkIds.has(id);
+    case "capability":
+      return capabilityIds.has(id);
+    default:
+      return false;
+  }
+}
+
+for (const entry of compatibilityMatrix.entries ?? []) {
+  if (!isKnown(entry.subjectType, entry.subjectId)) {
+    failures.push({ issue: "Compatibility entry subject is unknown.", subjectType: entry.subjectType, subjectId: entry.subjectId });
+  }
+
+  if (!isKnown(entry.relatedType, entry.relatedId)) {
+    failures.push({ issue: "Compatibility entry relation target is unknown.", relatedType: entry.relatedType, relatedId: entry.relatedId });
+  }
+
+  if ((entry.supportLevel === "partial" || entry.supportLevel === "unsupported" || entry.supportLevel === "emulated") && !entry.notes) {
+    failures.push({
+      issue: "Compatibility entries with non-full support must include notes.",
+      subjectType: entry.subjectType,
+      subjectId: entry.subjectId,
+      relatedType: entry.relatedType,
+      relatedId: entry.relatedId
+    });
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, profiles: profiles.length, compatibilityEntries: compatibilityMatrix.entries?.length ?? 0 }, null, 2));