@harness-forge/cli 0.1.0

package/scripts/intelligence/synthesize-instructions.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { buildRepoMap } from "./shared/cartography.mjs";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const diff = args.includes("--diff");
+const write = args.includes("--write");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+const targetFlagIndex = args.indexOf("--target");
+const targetId = targetFlagIndex >= 0 ? args[targetFlagIndex + 1] ?? "codex" : "codex";
+
+const repoMap = await buildRepoMap(root);
+const scopeStrategy =
+  repoMap.workspaceType === "monorepo" || repoMap.services.length > 1 ? "mixed-scope" : "root-only";
+
+const recommendations = [
+  {
+    path: "AGENTS.md",
+    surfaceType: "root-guidance",
+    reason: "Every supported repo benefits from one root guidance surface.",
+    confidence: 0.95,
+    evidence: [...repoMap.supportingEvidence].slice(0, 3),
+    writeMode: write ? "write" : diff ? "diff" : "recommend-only"
+  }
+];
+
+if (scopeStrategy !== "root-only") {
+  for (const service of repoMap.services.slice(0, 2)) {
+    if (service.path === ".") {
+      continue;
+    }
+    recommendations.push({
+      path: `${service.path}/AGENTS.md`,
+      surfaceType: "scoped-guidance",
+      reason: "Multiple service boundaries justify a scoped guidance surface.",
+      confidence: 0.76,
+      evidence: [service.path],
+      writeMode: write ? "write" : diff ? "diff" : "recommend-only"
+    });
+  }
+}
+
+if (targetId === "cursor") {
+  recommendations.push({
+    path: ".cursor/rules/harness-forge.mdc",
+    surfaceType: "target-rule",
+    reason: "Cursor integrations should stay explicitly scoped and inspectable.",
+    confidence: 0.62,
+    evidence: ["target:cursor"],
+    writeMode: write ? "write" : diff ? "diff" : "recommend-only"
+  });
+}
+
+const instructionPlan = {
+  generatedAt: new Date().toISOString(),
+  workspaceId: repoMap.workspaceId,
+  targetId,
+  scopeStrategy,
+  sharedRuntimeRoot: ".hforge/runtime",
+  sharedRuntimeBridges: recommendations.map((recommendation) => recommendation.path),
+  sharedRuntimeArtifacts: [".hforge/runtime/index.json", ".hforge/runtime/README.md"],
+  recommendations,
+  recommendedProfiles: repoMap.workspaceType === "library" ? ["core"] : ["developer", "core"],
+  recommendedSkills: [
+    ...(repoMap.workspaceType === "monorepo" || repoMap.services.length > 1 ? ["repo-onboarding"] : []),
+    ...(repoMap.highRiskPaths.some((value) => /security/i.test(value)) ? ["security-scan"] : [])
+  ],
+  generatedArtifacts: recommendations.map((recommendation) => recommendation.path),
+  riskNotes: repoMap.qualityGaps.map((gap) => gap.id)
+};
+
+if (write) {
+  const targetPath = path.join(root, ".hforge", "generated", "instruction-plan.json");
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.writeFile(targetPath, `${JSON.stringify(instructionPlan, null, 2)}\n`, "utf8");
+}
+
+if (diff) {
+  const lines = instructionPlan.recommendations.map(
+    (recommendation) => `+ ${recommendation.path} :: ${recommendation.reason}`
+  );
+  console.log(lines.join("\n"));
+} else if (json) {
+  console.log(JSON.stringify(instructionPlan, null, 2));
+} else {
+  console.log(JSON.stringify(instructionPlan, null, 2));
+}

package/scripts/knowledge/import-pack.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const dryRun = args.includes("--dry-run");
+const positionalArgs = args.filter((value) => !value.startsWith("--"));
+const [sourceDir, languageId] = positionalArgs;
+
+if (!sourceDir || !languageId) {
+  console.error("Usage: node scripts/knowledge/import-pack.mjs <source-dir> <language-id> [--dry-run] [--json]");
+  process.exit(1);
+}
+
+const root = process.cwd();
+const sourceRoot = path.resolve(sourceDir);
+const destinationRoot = path.join(root, "knowledge-bases", "structured", languageId);
+
+async function listFiles(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 listFiles(absolutePath);
+      }
+
+      return [absolutePath];
+    })
+  );
+
+  return nested.flat();
+}
+
+const files = await listFiles(sourceRoot);
+const copied = files.map((filePath) => path.relative(sourceRoot, filePath).replaceAll("\\", "/"));
+
+if (!dryRun) {
+  await fs.mkdir(destinationRoot, { recursive: true });
+  await fs.cp(sourceRoot, destinationRoot, { recursive: true, force: true });
+}
+
+const result = {
+  ok: true,
+  sourceRoot,
+  destinationRoot,
+  copiedCount: copied.length,
+  copied
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/knowledge/normalize-pack.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const dryRun = args.includes("--dry-run");
+const packRoot = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+const textExtensions = new Set([".md", ".txt", ".json", ".yaml", ".yml"]);
+
+async function listFiles(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 listFiles(absolutePath);
+      }
+
+      return [absolutePath];
+    })
+  );
+
+  return nested.flat();
+}
+
+const changed = [];
+for (const filePath of await listFiles(packRoot)) {
+  if (!textExtensions.has(path.extname(filePath).toLowerCase())) {
+    continue;
+  }
+
+  const original = await fs.readFile(filePath, "utf8");
+  const normalized = `${original.replaceAll("\r\n", "\n").replaceAll("\r", "\n").replace(/\s*$/, "")}\n`;
+  if (normalized !== original) {
+    changed.push(path.relative(packRoot, filePath).replaceAll("\\", "/"));
+    if (!dryRun) {
+      await fs.writeFile(filePath, normalized, "utf8");
+    }
+  }
+}
+
+const result = { ok: true, packRoot, changedCount: changed.length, changed };
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/knowledge/report-coverage.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const languageAssets = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "catalog", "language-assets.json"), "utf8")
+);
+
+const coverage = {};
+let totalExistingPaths = 0;
+let totalDeclaredPaths = 0;
+
+for (const [languageId, entry] of Object.entries(languageAssets.languages ?? {})) {
+  const categories = ["docs", "rules", "skills", "workflows", "examples"];
+  const categoryCoverage = {};
+
+  for (const category of categories) {
+    const paths = [...new Set((entry[category] ?? []).filter(Boolean))];
+    const existing = [];
+    const missing = [];
+
+    for (const relativePath of paths) {
+      if (await exists(path.join(root, relativePath))) {
+        existing.push(relativePath);
+      } else {
+        missing.push(relativePath);
+      }
+    }
+
+    categoryCoverage[category] = {
+      declared: paths.length,
+      existing: existing.length,
+      missing: missing.length
+    };
+    totalExistingPaths += existing.length;
+    totalDeclaredPaths += paths.length;
+  }
+
+  coverage[languageId] = {
+    maturity: entry.maturity,
+    knowledgeBase: entry.knowledgeBase,
+    categoryCoverage
+  };
+}
+
+const summary = {
+  languages: Object.keys(coverage).length,
+  totalDeclaredPaths,
+  totalExistingPaths,
+  missingPaths: totalDeclaredPaths - totalExistingPaths,
+  coverage
+};
+
+if (json) {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(
+    JSON.stringify(
+      {
+        languages: summary.languages,
+        totalDeclaredPaths,
+        totalExistingPaths,
+        missingPaths: summary.missingPaths
+      },
+      null,
+      2
+    )
+  );
+}

package/scripts/knowledge/report-drift.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const failures = [];
+const languageAssets = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "catalog", "language-assets.json"), "utf8")
+);
+const frameworkAssets = JSON.parse(
+  await fs.readFile(path.join(root, "manifests", "catalog", "framework-assets.json"), "utf8")
+);
+
+for (const [languageId, entry] of Object.entries(languageAssets.languages ?? {})) {
+  const paths = [
+    entry.knowledgeBase,
+    ...(entry.docs ?? []),
+    ...(entry.rules ?? []),
+    ...(entry.skills ?? []),
+    ...(entry.workflows ?? []),
+    ...(entry.examples ?? [])
+  ].filter(Boolean);
+
+  for (const relativePath of paths) {
+    if (!(await exists(path.join(root, relativePath)))) {
+      failures.push({
+        type: "language-asset-missing",
+        languageId,
+        path: relativePath
+      });
+    }
+  }
+}
+
+for (const framework of frameworkAssets.frameworks ?? []) {
+  if (!(await exists(path.join(root, framework.docPath)))) {
+    failures.push({
+      type: "framework-doc-missing",
+      frameworkId: framework.id,
+      path: framework.docPath
+    });
+  }
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ ok: false, failures }, null, 2));
+  process.exit(1);
+}
+
+const result = { ok: true, languages: Object.keys(languageAssets.languages ?? {}).length, frameworks: frameworkAssets.frameworks?.length ?? 0 };
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/runtime/check-merge-readiness.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+const planPath = path.join(root, ".hforge", "generated", "parallel-plan.json");
+
+let plan = null;
+try {
+  plan = JSON.parse(await fs.readFile(planPath, "utf8"));
+} catch {
+  plan = null;
+}
+
+const result = plan
+  ? {
+      planId: plan.planId,
+      status: plan.strategy === "single-thread" ? "blocked" : "ready",
+      reasons: plan.strategy === "single-thread" ? [plan.fallbackToSingleThreadReason].filter(Boolean) : ["Shard plan has been generated."],
+      overlapPaths: plan.sharedRiskPaths ?? [],
+      staleDependencies: [],
+      missingArtifacts: [],
+      requiredActions:
+        plan.strategy === "single-thread"
+          ? ["Continue implementation in a single worktree."]
+          : ["Validate each shard before merge.", "Confirm merge criteria remain satisfied."]
+    }
+  : {
+      planId: null,
+      status: "blocked",
+      reasons: ["No parallel plan has been generated yet."],
+      overlapPaths: [],
+      staleDependencies: [],
+      missingArtifacts: [],
+      requiredActions: ["Create a parallel plan before checking merge readiness."]
+    };
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/runtime/check-parallel-status.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+const planPath = path.join(root, ".hforge", "generated", "parallel-plan.json");
+
+let plan = null;
+try {
+  plan = JSON.parse(await fs.readFile(planPath, "utf8"));
+} catch {
+  plan = null;
+}
+
+const result = plan
+  ? {
+      planId: plan.planId,
+      strategy: plan.strategy,
+      shardCount: plan.shards.length,
+      statuses: plan.shards.map((shard) => ({
+        shardId: shard.shardId,
+        status: "planned",
+        mergeReadiness: "unknown"
+      }))
+    }
+  : {
+      planId: null,
+      strategy: "uninitialized",
+      shardCount: 0,
+      statuses: []
+    };
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/runtime/create-parallel-plan.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const taskFile = path.resolve(args.find((value) => !value.startsWith("--")) ?? "specs/004-enhancement-pack-foundations/tasks.md");
+const root = process.cwd();
+const content = await fs.readFile(taskFile, "utf8");
+const lines = content.split(/\r?\n/);
+const tasks = lines
+  .filter((line) => /^- \[[ xX]\] T\d+/.test(line))
+  .map((line) => {
+    const id = line.match(/T\d+/)?.[0] ?? "unknown";
+    return {
+      id,
+      parallel: line.includes("[P]"),
+      description: line
+    };
+  });
+
+const parallelTasks = tasks.filter((task) => task.parallel);
+const plan = {
+  planId: `parallel-${path.basename(path.dirname(taskFile))}`,
+  featureId: path.basename(path.dirname(taskFile)),
+  strategy: parallelTasks.length >= 2 ? "local-isolated" : "single-thread",
+  rootTask: `Implement ${path.basename(path.dirname(taskFile))}`,
+  shards:
+    parallelTasks.length >= 2
+      ? parallelTasks.map((task, index) => ({
+          shardId: `shard-${index + 1}`,
+          taskIds: [task.id],
+          worktreePath: `.worktrees/${task.id}`,
+          risk: "low"
+        }))
+      : [
+          {
+            shardId: "main",
+            taskIds: tasks.slice(0, 10).map((task) => task.id),
+            worktreePath: ".",
+            risk: "medium"
+          }
+        ],
+  dependencies: [],
+  sharedRiskPaths: [],
+  expectedArtifacts: ["docs/target-support-matrix.md", "manifests/catalog/harness-capability-matrix.json"],
+  validationGates: ["npm run validate:capability-matrix", "npm run test"],
+  mergeCriteria: ["All shard validations passing", "No blocked shards"],
+  rollbackPlan: "Resume single-threaded execution if shard overlap becomes unsafe.",
+  fallbackToSingleThreadReason: parallelTasks.length >= 2 ? null : "Not enough low-overlap tasks were detected."
+};
+
+const destination = path.join(root, ".hforge", "generated", "parallel-plan.json");
+await fs.mkdir(path.dirname(destination), { recursive: true });
+await fs.writeFile(destination, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+
+if (json) {
+  console.log(JSON.stringify(plan, null, 2));
+} else {
+  console.log(JSON.stringify(plan, null, 2));
+}

package/scripts/runtime/flow-status.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+const distCli = path.join(root, "dist", "cli", "index.js");
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function inferFlowState() {
+  const specsRoot = path.join(root, "specs");
+  let featureDirs = [];
+  try {
+    featureDirs = (await fs.readdir(specsRoot, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(specsRoot, entry.name));
+  } catch {
+    return {
+      featureId: "uninitialized",
+      currentStage: "clarify",
+      status: "active",
+      lastArtifact: ".specify/state/agent-context.md",
+      nextAction: "Create a feature spec before attempting flow recovery.",
+      updatedAt: new Date().toISOString()
+    };
+  }
+
+  if (featureDirs.length === 0) {
+    return {
+      featureId: "uninitialized",
+      currentStage: "clarify",
+      status: "active",
+      lastArtifact: ".specify/state/agent-context.md",
+      nextAction: "Create a feature spec before attempting flow recovery.",
+      updatedAt: new Date().toISOString(),
+      artifactLineage: []
+    };
+  }
+
+  const stats = await Promise.all(
+    featureDirs.map(async (featureDir) => ({ featureDir, stat: await fs.stat(featureDir) }))
+  );
+  stats.sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs);
+  const featureDir = stats[0].featureDir;
+  const featureId = path.basename(featureDir);
+  const artifactLineage = [];
+  for (const relativePath of ["spec.md", "plan.md", "research.md", "data-model.md", "tasks.md"]) {
+    const absolutePath = path.join(featureDir, relativePath);
+    if (await exists(absolutePath)) {
+      artifactLineage.push(`specs/${featureId}/${relativePath}`);
+    }
+  }
+  const tasksPath = path.join(featureDir, "tasks.md");
+  const planPath = path.join(featureDir, "plan.md");
+  const specPath = path.join(featureDir, "spec.md");
+  let stage = "plan";
+  let status = "active";
+  if (await exists(tasksPath)) {
+    const content = await fs.readFile(tasksPath, "utf8");
+    const incomplete = (content.match(/^- \[ \]/gm) ?? []).length;
+    const complete = (content.match(/^- \[[xX]\]/gm) ?? []).length;
+    if (incomplete === 0 && complete > 0) {
+      stage = "validate";
+      status = "complete";
+    } else if (complete > 0) {
+      stage = "implement";
+    } else {
+      stage = "tasks";
+    }
+  } else if (await exists(planPath)) {
+    stage = "plan";
+  } else if (await exists(specPath)) {
+    stage = "specify";
+  }
+
+  return {
+    featureId,
+    currentStage: stage,
+    status,
+    lastArtifact: artifactLineage[artifactLineage.length - 1] ?? `specs/${featureId}/spec.md`,
+    nextAction: status === "complete" ? "Review validation output and release readiness." : "Continue the current flow stage.",
+    updatedAt: new Date().toISOString(),
+    artifactLineage
+  };
+}
+
+if (await exists(distCli)) {
+  const { execFileSync } = await import("node:child_process");
+  const output = execFileSync(process.execPath, [distCli, "flow", "status", "--root", root, "--json"], {
+    cwd: root,
+    encoding: "utf8"
+  });
+  if (json) {
+    process.stdout.write(output);
+  } else {
+    console.log(JSON.parse(output));
+  }
+} else {
+  const result = await inferFlowState();
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}

package/scripts/runtime/record-event.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+
+function readOption(name, fallback) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] ?? fallback : fallback;
+}
+
+const event = {
+  eventId: crypto.randomUUID(),
+  eventType: readOption("--event-type", "manual-event"),
+  recordedAt: new Date().toISOString(),
+  workspaceId: readOption("--workspace-id", root),
+  target: readOption("--target", "codex"),
+  featureId: readOption("--feature-id", undefined),
+  result: readOption("--result", "accepted"),
+  artifacts: [],
+  evidence: [],
+  tags: []
+};
+
+const destination = path.join(root, ".hforge", "observability", "events.json");
+let events = [];
+try {
+  events = JSON.parse(await fs.readFile(destination, "utf8"));
+} catch {
+  events = [];
+}
+
+events.push(event);
+await fs.mkdir(path.dirname(destination), { recursive: true });
+await fs.writeFile(destination, `${JSON.stringify(events, null, 2)}\n`, "utf8");
+
+if (json) {
+  console.log(JSON.stringify({ ok: true, destination, event }, null, 2));
+} else {
+  console.log(JSON.stringify({ ok: true, destination, event }, null, 2));
+}

package/scripts/runtime/recursive-plan.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, "..", "..");
+
+const args = process.argv.slice(2);
+const result = spawnSync(process.execPath, [path.join(repoRoot, "dist", "cli", "index.js"), "recursive", "plan", ...args], {
+  cwd: process.cwd(),
+  encoding: "utf8",
+  stdio: "pipe"
+});
+
+if (result.stdout) {
+  process.stdout.write(result.stdout);
+}
+
+if (result.stderr) {
+  process.stderr.write(result.stderr);
+}
+
+process.exit(result.status ?? 1);