@harness-forge/cli 0.1.0

package/scripts/ci/validate-no-placeholders.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const scanPaths = [
+  "README.md",
+  "AGENTS.md",
+  "docs",
+  "skills",
+  ".agents/skills",
+  "rules",
+  "templates",
+  "manifests"
+];
+const ignorePatterns = [
+  /(^|\/)skills\/speckit-/,
+  /(^|\/)\.agents\/skills\/speckit-/
+];
+const patterns = [
+  /\[NEEDS CLARIFICATION\]/,
+  /\bTODO\b/,
+  /\bTBD\b/,
+  /REPLACE ME/,
+  /INSERT [A-Z]/,
+  /lorem ipsum/i
+];
+
+async function listFiles(targetPath) {
+  const stats = await fs.stat(targetPath);
+  if (!stats.isDirectory()) {
+    return [targetPath];
+  }
+
+  const entries = await fs.readdir(targetPath, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = path.join(targetPath, entry.name);
+      if (entry.isDirectory()) {
+        return listFiles(absolutePath);
+      }
+
+      return [absolutePath];
+    })
+  );
+
+  return nested.flat();
+}
+
+const failures = [];
+for (const relativePath of scanPaths) {
+  const absolutePath = path.join(root, relativePath);
+  try {
+    await fs.access(absolutePath);
+  } catch {
+    continue;
+  }
+
+  for (const filePath of await listFiles(absolutePath)) {
+    if (!/\.(md|json)$/i.test(filePath)) {
+      continue;
+    }
+
+    const normalizedPath = path.relative(root, filePath).replaceAll("\\", "/");
+    if (ignorePatterns.some((pattern) => pattern.test(normalizedPath))) {
+      continue;
+    }
+
+    const content = await fs.readFile(filePath, "utf8");
+    for (const pattern of patterns) {
+      if (pattern.test(content)) {
+        failures.push({
+          file: normalizedPath,
+          pattern: pattern.toString()
+        });
+      }
+    }
+  }
+}
+
+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-pack-dependencies.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const manifestDir = path.join(root, "manifests", "bundles");
+const files = await fs.readdir(manifestDir);
+const bundles = [];
+const failures = [];
+
+for (const file of files) {
+  const manifest = JSON.parse(await fs.readFile(path.join(manifestDir, file), "utf8"));
+  bundles.push(...(manifest.bundles ?? []));
+}
+
+const ids = new Set(bundles.map((bundle) => bundle.id));
+
+for (const bundle of bundles) {
+  for (const dependency of bundle.dependencies ?? []) {
+    if (!ids.has(dependency)) {
+      failures.push({ issue: "Bundle dependency points to an unknown bundle.", dependency: `${bundle.id} -> ${dependency}` });
+    }
+  }
+
+  for (const assetPath of bundle.paths ?? []) {
+    try {
+      await fs.access(path.join(root, assetPath));
+    } catch {
+      failures.push({ issue: "Bundle path points to a missing file or directory.", bundleId: bundle.id, path: assetPath });
+    }
+  }
+}
+
+const catalogIndex = JSON.parse(await fs.readFile(path.join(root, "manifests", "catalog", "index.json"), "utf8"));
+for (const category of ["bundles", "profiles", "targets", "catalogs", "schemas"]) {
+  for (const relativePath of catalogIndex[category] ?? []) {
+    try {
+      await fs.access(path.join(root, relativePath));
+    } catch {
+      failures.push({ issue: "Catalog index points to a missing file.", category, path: relativePath });
+    }
+  }
+}
+
+const languageAssets = JSON.parse(await fs.readFile(path.join(root, "manifests", "catalog", "language-assets.json"), "utf8"));
+for (const [language, entry] of Object.entries(languageAssets.languages ?? {})) {
+  for (const relativePath of [entry.knowledgeBase, ...(entry.docs ?? []), ...(entry.rules ?? []), ...(entry.examples ?? [])].filter(Boolean)) {
+    try {
+      await fs.access(path.join(root, relativePath));
+    } catch {
+      failures.push({ issue: "Language asset catalog points to a missing file.", language, path: relativePath });
+    }
+  }
+}
+
+const referenceFiles = [
+  "docs/templates/authoring.md",
+  "docs/quickstart.md",
+  "scripts/templates/README.md"
+];
+
+for (const relativePath of referenceFiles) {
+  const content = await fs.readFile(path.join(root, relativePath), "utf8");
+  for (const match of content.matchAll(/scripts\/templates\/[A-Za-z0-9./_-]+/g)) {
+    const referencedPath = match[0];
+    try {
+      await fs.access(path.join(root, referencedPath));
+    } catch {
+      failures.push({ issue: "Documentation references a missing validator path.", file: relativePath, path: referencedPath });
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, bundles: bundles.length }, null, 2));

package/scripts/ci/validate-packed-install-surface.mjs

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const manifestPath = path.join(root, "manifests", "catalog", "package-surface.json");
+const packageJsonPath = path.join(root, "package.json");
+const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+
+const requiredPaths = new Set([
+  ...(manifest.requiredPaths ?? []),
+  ...((manifest.groups ?? []).flatMap((group) => group.paths ?? [])),
+  ...((manifest.targetSurfaces ?? []).flatMap((surface) => surface.paths ?? []))
+]);
+
+const failures = [];
+const packageFiles = packageJson.files ?? [];
+
+function isCoveredByPackageFiles(requiredPath) {
+  return packageFiles.some((entry) => requiredPath === entry || requiredPath.startsWith(`${entry}/`));
+}
+
+for (const requiredPath of requiredPaths) {
+  try {
+    await fs.access(path.join(root, requiredPath));
+  } catch {
+    failures.push({ issue: "Required package-surface path is missing in the repository.", path: requiredPath });
+    continue;
+  }
+
+  if (!isCoveredByPackageFiles(requiredPath)) {
+    failures.push({ issue: "Required package-surface path is not covered by package.json files.", path: requiredPath });
+  }
+}
+
+const packed =
+  process.platform === "win32"
+    ? spawnSync("cmd.exe", ["/d", "/s", "/c", "npm pack --json --dry-run"], {
+        cwd: root,
+        encoding: "utf8"
+      })
+    : spawnSync("npm", ["pack", "--json", "--dry-run"], {
+        cwd: root,
+        encoding: "utf8"
+      });
+
+if ((packed.status ?? 1) !== 0) {
+  failures.push({
+    issue: "npm pack --dry-run failed.",
+    error: packed.error?.message,
+    stdout: packed.stdout?.trim(),
+    stderr: packed.stderr?.trim()
+  });
+} else {
+  const output = JSON.parse(packed.stdout || "[]");
+  const packedFiles = new Set((output[0]?.files ?? []).map((entry) => entry.path));
+
+  for (const requiredPath of requiredPaths) {
+    const absolutePath = path.join(root, requiredPath);
+    const stats = await fs.stat(absolutePath);
+    const packedMatch = stats.isDirectory()
+      ? [...packedFiles].some((filePath) => filePath.startsWith(`${requiredPath}/`))
+      : packedFiles.has(requiredPath);
+
+    if (!packedMatch) {
+      failures.push({ issue: "Required path is missing from npm pack dry-run output.", path: requiredPath });
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, requiredPaths: requiredPaths.size }, null, 2));

package/scripts/ci/validate-seeded-knowledge-coverage.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const seededRoot = path.join(root, "knowledge-bases", "seeded");
+const manifestPath = path.join(root, "manifests", "catalog", "seeded-knowledge-files.json");
+const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+
+async function listFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        return listFiles(absolutePath);
+      }
+
+      return [absolutePath];
+    })
+  );
+
+  return results.flat();
+}
+
+const seededFiles = (await listFiles(seededRoot))
+  .map((absolutePath) => path.relative(root, absolutePath).replaceAll("\\", "/"))
+  .sort();
+
+const manifestEntries = manifest.files ?? [];
+const manifestByPackagePath = new Map(manifestEntries.map((entry) => [entry.packagePath, entry]));
+const failures = [];
+const seededArchiveFiles = seededFiles.filter((filePath) => filePath !== "knowledge-bases/seeded/README.md");
+
+for (const filePath of seededArchiveFiles) {
+  if (!manifestByPackagePath.has(filePath)) {
+    failures.push({ issue: "Seeded file missing from coverage manifest.", file: filePath });
+  }
+}
+
+for (const entry of manifestEntries) {
+  const absolutePath = path.join(root, entry.packagePath);
+  try {
+    await fs.access(absolutePath);
+  } catch {
+    failures.push({ issue: "Manifest entry points to a missing shipped file.", file: entry.packagePath });
+  }
+}
+
+const expectedLanguages = new Set(["typescript", "java", "dotnet", "lua", "powershell"]);
+const countsByLanguage = Object.fromEntries([...expectedLanguages].map((language) => [language, 0]));
+const kindsByLanguage = Object.fromEntries([...expectedLanguages].map((language) => [language, new Set()]));
+
+for (const entry of manifestEntries) {
+  if (countsByLanguage[entry.language] === undefined) {
+    failures.push({ issue: "Unexpected language in coverage manifest.", file: entry.packagePath, language: entry.language });
+    continue;
+  }
+
+  countsByLanguage[entry.language] += 1;
+  kindsByLanguage[entry.language].add(entry.contentKind);
+}
+
+for (const language of expectedLanguages) {
+  if ((countsByLanguage[language] ?? 0) === 0) {
+    failures.push({ issue: "No files mapped for seeded language.", language });
+    continue;
+  }
+
+  for (const requiredKind of ["overview", "review-checklist", "framework-notes", "example", "common-rule", "language-rule"]) {
+    if (!kindsByLanguage[language].has(requiredKind)) {
+      failures.push({ issue: "Seeded language is missing a required coverage kind.", language, requiredKind });
+    }
+  }
+}
+
+if (seededArchiveFiles.length !== manifestEntries.length) {
+  failures.push({
+    issue: "Seeded file count does not match manifest coverage.",
+    seededFiles: seededArchiveFiles.length,
+    manifestEntries: manifestEntries.length
+  });
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, seededFiles: seededArchiveFiles.length }, null, 2));

package/scripts/ci/validate-skill-depth.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const operationalSkills = [
+  "engineering-assistant",
+  "repo-onboarding",
+  "security-scan",
+  "release-readiness",
+  "documentation-lookup",
+  "architecture-decision-records",
+  "parallel-worktree-supervisor",
+  "incident-triage",
+  "dependency-upgrade-safety",
+  "performance-profiling",
+  "test-strategy-and-coverage",
+  "api-contract-review",
+  "db-migration-review",
+  "pr-triage-and-summary",
+  "observability-setup",
+  "repo-modernization",
+  "cloud-architect"
+];
+const languageSkills = [
+  "python-engineering",
+  "go-engineering",
+  "kotlin-engineering",
+  "rust-engineering",
+  "cpp-engineering",
+  "php-engineering",
+  "perl-engineering",
+  "swift-engineering",
+  "shell-engineering",
+  "javascript-engineering"
+];
+const failures = [];
+
+for (const requiredPath of [
+  "manifests/catalog/enhanced-skill-import-inventory.json",
+  "docs/authoring/enhanced-skill-import.md"
+]) {
+  try {
+    await fs.access(path.join(root, requiredPath));
+  } catch {
+    failures.push({
+      skillId: "enhanced-skill-governance",
+      file: requiredPath,
+      issue: "Missing required import governance surface"
+    });
+  }
+}
+
+for (const skillId of operationalSkills) {
+  const filePath = path.join(root, "skills", skillId, "SKILL.md");
+  const content = await fs.readFile(filePath, "utf8");
+  for (const section of ["## Trigger Signals", "## Inspect First", "## Workflow", "## Output Contract", "## Failure Modes", "## Escalation"]) {
+    if (!content.includes(section)) {
+      failures.push({ skillId, file: `skills/${skillId}/SKILL.md`, issue: `Missing section ${section}` });
+    }
+  }
+
+  for (const match of content.matchAll(/`(skills\/[^`]+)`/g)) {
+    const referencedPath = match[1];
+    try {
+      await fs.access(path.join(root, referencedPath));
+    } catch {
+      failures.push({ skillId, file: `skills/${skillId}/SKILL.md`, issue: `Missing referenced file ${referencedPath}` });
+    }
+  }
+}
+
+for (const skillId of languageSkills) {
+  const filePath = path.join(root, "skills", skillId, "SKILL.md");
+  const content = await fs.readFile(filePath, "utf8");
+  for (const section of ["## Activation", "## Load Order", "## Execution Contract", "## Validation", "## Escalation"]) {
+    if (!content.includes(section)) {
+      failures.push({ skillId, file: `skills/${skillId}/SKILL.md`, issue: `Missing section ${section}` });
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, operationalSkills: operationalSkills.length, languageSkills: languageSkills.length }, null, 2));

package/scripts/codex/apply-home-config.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const getArg = (flag, fallback = undefined) => {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : fallback;
+};
+
+const workspace = path.resolve(getArg("--workspace", "."));
+const homeFile = path.resolve(getArg("--home-file", path.join(os.homedir(), ".codex", "config.toml")));
+const dryRun = args.includes("--dry-run");
+const workspaceConfigPath = path.join(workspace, ".codex", "config.toml");
+const markers = { start: "# >>> harness-forge managed block >>>", end: "# <<< harness-forge managed block <<<" };
+
+const workspaceConfig = await fs.readFile(workspaceConfigPath, "utf8");
+let existing = "";
+try { existing = await fs.readFile(homeFile, "utf8"); } catch { existing = ""; }
+
+const block = `${markers.start}
+# source: ${workspaceConfigPath}
+${workspaceConfig.trim()}
+${markers.end}
+`;
+const esc = (value) => value.replace(/[.*+?^${}()|[\]\]/g, "\$&");
+const pattern = new RegExp(`${esc(markers.start)}[\s\S]*?${esc(markers.end)}\n?`, "g");
+const next = existing.match(pattern) ? existing.replace(pattern, block) : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}`;
+
+if (dryRun) {
+  process.stdout.write(next);
+  process.exit(0);
+}
+
+await fs.mkdir(path.dirname(homeFile), { recursive: true });
+await fs.writeFile(homeFile, next, "utf8");
+process.stdout.write(`${homeFile}
+`);

package/scripts/intelligence/cartograph-repo.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { buildRepoMap } from "./shared/cartography.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+const repoMap = await buildRepoMap(root);
+
+if (json) {
+  console.log(JSON.stringify(repoMap, null, 2));
+} else {
+  console.log(JSON.stringify(repoMap, null, 2));
+}

package/scripts/intelligence/classify-boundaries.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { classifyServiceBoundaries } from "./shared/cartography.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+const boundaries = await classifyServiceBoundaries(root);
+
+if (json) {
+  console.log(JSON.stringify({ root, boundaries }, null, 2));
+} else {
+  console.log(JSON.stringify({ root, boundaries }, null, 2));
+}

package/scripts/intelligence/detect-frameworks.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { collectRepoFacts, formatHumanReadable } from "./shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+const result = await collectRepoFacts(root);
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(formatHumanReadable(result));
+}

package/scripts/intelligence/scan-repo.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { collectRepoFacts, formatHumanReadable } from "./shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+const result = await collectRepoFacts(root);
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(formatHumanReadable(result));
+}

package/scripts/intelligence/score-recommendations.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { formatHumanReadable, scoreRecommendations } from "./shared.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+const result = await scoreRecommendations(root);
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(formatHumanReadable(result));
+}

package/scripts/intelligence/shared/cartography.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { collectRepoFacts } from "../shared.mjs";
+
+const IGNORED_DIRS = new Set([".git", ".hforge", ".next", ".nuxt", ".specify", ".turbo", "build", "coverage", "dist", "node_modules", "vendor"]);
+const BOUNDARY_MARKERS = [
+  { matcher: (name) => name === "package.json", classification: "package" },
+  { matcher: (name) => name === "pyproject.toml", classification: "python-project" },
+  { matcher: (name) => name === "go.mod", classification: "go-module" },
+  { matcher: (name) => name === "pom.xml", classification: "java-service" },
+  { matcher: (name) => /\.csproj$/i.test(name), classification: "dotnet-service" }
+];
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function walkDirectories(root, visit, current = root) {
+  let entries = [];
+  try {
+    entries = await fs.readdir(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  await visit(current, entries);
+  for (const entry of entries) {
+    if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) {
+      continue;
+    }
+    await walkDirectories(root, visit, path.join(current, entry.name));
+  }
+}
+
+function normalizePath(root, targetPath) {
+  const relative = path.relative(root, targetPath).replaceAll("\\", "/");
+  return relative.length > 0 ? relative : ".";
+}
+
+export async function classifyServiceBoundaries(root) {
+  const boundaries = [];
+  await walkDirectories(root, async (directory, entries) => {
+    const marker = BOUNDARY_MARKERS.find((candidate) => entries.some((entry) => entry.isFile() && candidate.matcher(entry.name)));
+    if (!marker) {
+      return;
+    }
+
+    const relativePath = normalizePath(root, directory);
+    boundaries.push({
+      id: relativePath === "." ? "workspace-root" : relativePath.replaceAll("/", "-"),
+      path: relativePath,
+      classification: marker.classification
+    });
+  });
+
+  if (boundaries.length === 0 && (await exists(path.join(root, "src")))) {
+    boundaries.push({
+      id: "workspace-root",
+      path: ".",
+      classification: "source-root"
+    });
+  }
+
+  return boundaries.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export async function listInstructionSurfaces(root) {
+  const candidates = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".agents/skills",
+    ".codex/config.toml",
+    ".claude/settings.local.json",
+    ".cursor/rules"
+  ];
+
+  const discovered = [];
+  for (const candidate of candidates) {
+    if (await exists(path.join(root, candidate))) {
+      discovered.push(candidate);
+    }
+  }
+
+  return discovered;
+}
+
+export async function buildRepoMap(root) {
+  const facts = await collectRepoFacts(root);
+  const services = await classifyServiceBoundaries(root);
+  const existingInstructionSurfaces = await listInstructionSurfaces(root);
+  const criticalPaths = services.slice(0, 3).map((service) => service.path);
+  const highRiskPaths = [...new Set(facts.riskSignals.flatMap((signal) => signal.evidence))].slice(0, 6);
+  const supportingEvidence = [
+    ...facts.dominantLanguages.flatMap((signal) => signal.evidence),
+    ...facts.frameworkMatches.flatMap((signal) => signal.evidence),
+    ...facts.missingValidationSurfaces.flatMap((signal) => signal.evidence)
+  ].slice(0, 12);
+
+  return {
+    generatedAt: facts.generatedAt,
+    workspaceId: facts.root,
+    workspaceType: facts.repoType,
+    dominantLanguages: facts.dominantLanguages.map(({ id, confidence, evidence }) => ({ id, confidence, evidence })),
+    frameworks: facts.frameworkMatches.map(({ id, confidence, evidence }) => ({ id, confidence, evidence })),
+    services,
+    criticalPaths,
+    highRiskPaths,
+    existingInstructionSurfaces,
+    sharedRuntimeRoot: ".hforge/runtime",
+    sharedRuntimeBridges: ["AGENTS.md", "CLAUDE.md", ".hforge/runtime/index.json", ".hforge/runtime/README.md"],
+    sharedRuntimeArtifacts: [
+      ".hforge/runtime/repo/repo-map.json",
+      ".hforge/runtime/repo/recommendations.json",
+      ".hforge/runtime/repo/target-support.json",
+      ".hforge/runtime/repo/instruction-plan.json",
+      ".hforge/runtime/repo/scan-summary.json",
+      ".hforge/runtime/findings/validation-gaps.json",
+      ".hforge/runtime/findings/risk-signals.json"
+    ],
+    qualityGaps: facts.missingValidationSurfaces.map(({ id, confidence, evidence }) => ({ id, confidence, evidence })),
+    supportingEvidence
+  };
+}