@moretea-labs/forge 1.7.0 → 1.7.1

package/scripts/inspect-project-state.ts

@@ -1,280 +1,5 @@
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { join, resolve } from "path";
-import { loadWorkflowContract, resolveWorkflowContractForRepo } from "./workflow-contract.ts";
+#!/usr/bin/env bun
+export * from "../assets/templates/helpers/inspect-project-state";
+import { runTrackedForgeHelper } from "./lib/run-forge-helper";
 
-type Mode = "initialize" | "migrate" | "audit" | "repair";
-
-type InspectionResult = {
-  repo: string;
-  mode: Mode;
-  legacy_contract_version: string;
-  drift_signals: string[];
-  required_decisions: string[];
-  safe_defaults: string[];
-  detected_paths: string[];
-  upgrade_plan: UpgradePlanItem[];
-};
-
-type UpgradePlanItem = {
-  id: string;
-  signal: string;
-  action: string;
-  risk: string;
-  ownership: string;
-  paths: string[];
-  target_paths?: string[];
-  summary: string;
-};
-
-function parseArgs(argv: string[]) {
-  let repo = process.cwd();
-  let format: "json" | "text" = "json";
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === "--repo") {
-      repo = argv[i + 1] ? resolve(argv[i + 1]) : repo;
-      i += 1;
-      continue;
-    }
-    if (arg === "--format") {
-      format = argv[i + 1] === "text" ? "text" : "json";
-      i += 1;
-    }
-  }
-
-  return { repo, format };
-}
-
-function fileHasContent(path: string, pattern: RegExp): boolean {
-  if (!existsSync(path)) return false;
-  return pattern.test(readFileSync(path, "utf-8"));
-}
-
-function jsonPathExists(path: string, keys: string[]): boolean {
-  if (!existsSync(path)) return false;
-  try {
-    let value: unknown = JSON.parse(readFileSync(path, "utf-8"));
-    for (const key of keys) {
-      if (!value || typeof value !== "object" || !(key in value)) return false;
-      value = (value as Record<string, unknown>)[key];
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function hasAnyPath(repo: string, relPaths: string[]): boolean {
-  return relPaths.some((relPath) => existsSync(join(repo, relPath)));
-}
-
-function hasCustomClaudeHooks(repo: string): boolean {
-  const hooksDir = join(repo, ".claude", "hooks");
-  if (!existsSync(hooksDir)) return false;
-  try {
-    return readdirSync(hooksDir).some((entry) => /^custom-.*\.sh$/.test(entry));
-  } catch {
-    return false;
-  }
-}
-
-function detectMode(repo: string): Mode {
-  const hasTasks = existsSync(join(repo, "tasks"));
-  const hasPlan = existsSync(join(repo, "plans"));
-  const hasLegacyDocs =
-    existsSync(join(repo, "docs", "plan.md")) || existsSync(join(repo, "docs", "TODO.md"));
-  const hasLegacySkillFactory =
-    existsSync(join(repo, ".claude", "skill-factory")) ||
-    existsSync(join(repo, "scripts", "skill-factory-check.sh")) ||
-    existsSync(join(repo, "scripts", "skill-factory-create.sh")) ||
-    existsSync(join(repo, ".ai", "hooks", "memory-intake.sh")) ||
-    existsSync(join(repo, ".ai", "hooks", "skill-factory-session-end.sh"));
-
-  if (hasTasks && hasPlan) return "audit";
-  if (hasLegacyDocs || hasLegacySkillFactory) return "migrate";
-  if (!hasTasks && !hasPlan && !hasLegacyDocs) return "initialize";
-  return "repair";
-}
-
-export function inspectRepo(repo: string): InspectionResult {
-  const contract = loadWorkflowContract(resolveWorkflowContractForRepo(repo));
-  const latestContract = loadWorkflowContract();
-  const upgradeActions = latestContract.migrations.upgrade?.actions ?? contract.migrations.upgrade?.actions ?? [];
-  const detectedPathSet = new Set(
-    [...new Set([...contract.migrations.legacyPaths, ...latestContract.migrations.legacyPaths])]
-      .map((relPath) => relPath)
-      .filter((relPath) => existsSync(join(repo, relPath)))
-  );
-  const driftSignals: string[] = [];
-  const requiredDecisions: string[] = [];
-  const safeDefaults = [
-    "Preserve repo-local tasks-first workflow",
-    "Archive uncertain legacy content instead of overwriting it",
-    "Delete only manifest-owned known_generated legacy files",
-    "Distill repeated corrections into tasks/lessons.md and hidden contracts into docs/researches/",
-  ];
-
-  const runtimeManifest = join(repo, contract.artifacts.runtimeManifest);
-  const todoFile = join(repo, contract.documents.deferredGoalLedger ?? contract.documents.taskChecklist ?? "tasks/todos.md");
-  const legacySingularTodoFile = join(repo, "tasks", "todo.md");
-  const legacyTaskSprintDir = join(repo, "tasks", "sprints");
-  const policyFile = join(repo, ".ai", "harness", "policy.json");
-  const generatedClaudeHookPaths = [
-    ".claude/hooks/run-hook.sh",
-    ".claude/hooks/finalize-handoff.sh",
-    ".claude/hooks/session-start-context.sh",
-    ".claude/hooks/hook-input.sh",
-    ".claude/hooks/lib/workflow-state.sh",
-    ".claude/hooks/lib/session-state.sh",
-  ];
-  const ignoredReferenceOrSecretPaths = [
-    "_ref",
-    "_ops",
-  ];
-
-  if (!existsSync(runtimeManifest)) {
-    driftSignals.push("missing-runtime-contract-manifest");
-  }
-  if (existsSync(policyFile) && !jsonPathExists(policyFile, ["upgrade", "strategy_version"])) {
-    driftSignals.push("policy-missing-upgrade-strategy");
-  }
-  if (existsSync(join(repo, "docs", "plan.md"))) {
-    driftSignals.push("legacy-docs-plan");
-  }
-  if (existsSync(join(repo, "docs", "TODO.md"))) {
-    driftSignals.push("legacy-docs-todo");
-  }
-  if (existsSync(legacySingularTodoFile) && legacySingularTodoFile !== todoFile) {
-    driftSignals.push("legacy-singular-todo-file");
-  }
-  if (existsSync(legacyTaskSprintDir)) {
-    driftSignals.push("legacy-task-sprint-prds");
-  }
-  if (
-    existsSync(join(repo, ".claude", "skill-factory")) ||
-    existsSync(join(repo, "scripts", "skill-factory-check.sh")) ||
-    existsSync(join(repo, "scripts", "skill-factory-create.sh")) ||
-    existsSync(join(repo, ".ai", "hooks", "memory-intake.sh")) ||
-    existsSync(join(repo, ".ai", "hooks", "skill-factory-session-end.sh"))
-  ) {
-    driftSignals.push("legacy-skill-factory-surface");
-  }
-  if (existsSync(join(repo, "docs", "PROGRESS.md"))) {
-    driftSignals.push("legacy-docs-progress");
-  }
-  if (
-    existsSync(todoFile) &&
-    (
-      !fileHasContent(todoFile, /^# Deferred Goal Ledger\s*$/m) ||
-      !fileHasContent(todoFile, /^\> \*\*Status\*\*:\s*Backlog\s*$/m)
-    )
-  ) {
-    driftSignals.push("legacy-task-checklist-format");
-  }
-  if (hasAnyPath(repo, generatedClaudeHookPaths)) {
-    driftSignals.push("stale-generated-claude-hook-shims");
-  }
-
-  if (driftSignals.includes("missing-runtime-contract-manifest")) {
-    requiredDecisions.push("Install runtime workflow contract manifest");
-  }
-  if (driftSignals.includes("policy-missing-upgrade-strategy")) {
-    requiredDecisions.push("Merge versioned upgrade strategy into harness policy");
-  }
-  if (driftSignals.includes("legacy-docs-plan") || driftSignals.includes("legacy-docs-todo")) {
-    requiredDecisions.push("Run legacy document migration before template refresh");
-  }
-  if (driftSignals.includes("legacy-singular-todo-file")) {
-    requiredDecisions.push("Migrate legacy tasks/todo.md into tasks/todos.md");
-  }
-  if (driftSignals.includes("legacy-task-sprint-prds")) {
-    requiredDecisions.push("Move legacy tasks/sprints/*.sprint.md into plans/sprints/*.sprint.md");
-  }
-  if (driftSignals.includes("legacy-docs-progress")) {
-    requiredDecisions.push("Archive legacy docs/PROGRESS.md into research report or changelog surfaces");
-  }
-  if (driftSignals.includes("legacy-skill-factory-surface")) {
-    requiredDecisions.push("Remove repo-local Skill Factory and auto-memory surfaces");
-  }
-  if (driftSignals.includes("stale-generated-claude-hook-shims")) {
-    requiredDecisions.push("Remove manifest-owned generated .claude/hooks shims and keep .ai/hooks as source of truth");
-  }
-
-  const upgradeSignals = new Set(driftSignals);
-  if (hasCustomClaudeHooks(repo)) {
-    upgradeSignals.add("custom-claude-hooks");
-  }
-  if (hasAnyPath(repo, ignoredReferenceOrSecretPaths)) {
-    upgradeSignals.add("ignored-reference-or-secret-surfaces");
-  }
-  const upgradePlan = upgradeActions
-    .filter((action) => upgradeSignals.has(action.signal))
-    .map((action) => {
-      for (const relPath of action.paths) {
-        if (!relPath.includes("*") && existsSync(join(repo, relPath))) {
-          detectedPathSet.add(relPath);
-        }
-      }
-      return {
-        id: action.id,
-        signal: action.signal,
-        action: action.action,
-        risk: action.risk,
-        ownership: action.ownership,
-        paths: action.paths,
-        target_paths: action.targetPaths,
-        summary: action.summary,
-      };
-    });
-
-  let legacyContractVersion = "current-v1";
-  if (driftSignals.includes("legacy-docs-plan") || driftSignals.includes("legacy-docs-todo")) {
-    legacyContractVersion = "pre-tasks-first";
-  } else if (driftSignals.includes("missing-runtime-contract-manifest")) {
-    legacyContractVersion = "tasks-first-without-contract-manifest";
-  }
-
-  return {
-    repo,
-    mode: detectMode(repo),
-    legacy_contract_version: legacyContractVersion,
-    drift_signals: driftSignals,
-    required_decisions: requiredDecisions,
-    safe_defaults: safeDefaults,
-    detected_paths: [...detectedPathSet].sort(),
-    upgrade_plan: upgradePlan,
-  };
-}
-
-function renderText(result: InspectionResult): string {
-  const lines = [
-    `repo: ${result.repo}`,
-    `mode: ${result.mode}`,
-    `legacy_contract_version: ${result.legacy_contract_version}`,
-    `drift_signals: ${result.drift_signals.join(", ") || "(none)"}`,
-    `required_decisions: ${result.required_decisions.join(" | ") || "(none)"}`,
-    `safe_defaults: ${result.safe_defaults.join(" | ")}`,
-    `upgrade_plan:`,
-  ];
-  if (result.upgrade_plan.length === 0) {
-    lines.push("- (none)");
-  } else {
-    for (const item of result.upgrade_plan) {
-      const target = item.target_paths?.length ? ` -> ${item.target_paths.join(", ")}` : "";
-      lines.push(
-        `- ${item.action} ${item.id} [${item.risk}, ${item.ownership}]: ${item.paths.join(", ")}${target}`
-      );
-    }
-  }
-  return lines.join("\n");
-}
-
-const { repo, format } = parseArgs(process.argv.slice(2));
-const result = inspectRepo(repo);
-
-if (format === "text") {
-  console.log(renderText(result));
-} else {
-  console.log(JSON.stringify(result, null, 2));
-}
+if (import.meta.main) runTrackedForgeHelper("inspect-project-state.ts");

package/scripts/lib/project-init-lib.sh

@@ -1055,7 +1055,9 @@ pi_install_helpers() {
   fi
 
   if [[ "$mode" != "apply" ]]; then
-    if [[ "$source_repo_target" -eq 1 || "$(pi_repo_pins_helper_source "$target_dir" && printf yes || true)" == "yes" ]]; then
+    if [[ "$source_repo_target" -eq 1 ]]; then
+      echo "[dry-run] preserve tracked source helper compatibility surfaces in $scripts_dir"
+    elif [[ "$(pi_repo_pins_helper_source "$target_dir" && printf yes || true)" == "yes" ]]; then
       echo "[dry-run] install source helpers into $scripts_dir"
     else
       echo "[dry-run] install helper compatibility wrappers in $scripts_dir; package runtime dispatches through forge run"
@@ -1083,7 +1085,10 @@ pi_install_helpers() {
           fi
         fi
         if [[ "$source_repo_target" -eq 1 ]]; then
-          cp "$helpers_dir/$helper_name" "$scripts_dir/$helper_name"
+          # Self-host source helpers are tracked compatibility surfaces. Their
+          # implementation authority lives in assets/templates/helpers; never
+          # copy the full runtime implementation back into scripts/.
+          continue
         elif pi_repo_pins_helper_source "$target_dir"; then
           cp "$helpers_dir/$helper_name" "$runtime_dir/$helper_name"
           pi_normalize_installed_helper "$runtime_dir/$helper_name"

package/scripts/lib/run-forge-helper.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+HELPER_NAME="${1:?helper filename is required}"
+shift
+HELPER_ID="${HELPER_NAME%.*}"
+
+if command -v bun >/dev/null 2>&1 && [[ -f "$SOURCE_ROOT/src/cli/index.ts" && -f "$SOURCE_ROOT/assets/templates/helpers/$HELPER_NAME" ]]; then
+  exec bun "$SOURCE_ROOT/src/cli/index.ts" run "$HELPER_ID" "$@"
+fi
+
+if command -v forge >/dev/null 2>&1; then
+  exec forge run "$HELPER_ID" "$@"
+fi
+
+echo "Missing Forge runtime for helper $HELPER_ID" >&2
+exit 1

package/scripts/lib/run-forge-helper.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function runTrackedForgeHelper(helperName: string, args = process.argv.slice(2)): never {
+  const helperId = helperName.replace(/\.[^.]+$/, "");
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const sourceRoot = resolve(scriptDir, "..", "..");
+  const sourceCli = join(sourceRoot, "src", "cli", "index.ts");
+  const canonicalHelper = join(sourceRoot, "assets", "templates", "helpers", helperName);
+  const command = existsSync(sourceCli) && existsSync(canonicalHelper)
+    ? ["bun", sourceCli, "run", helperId]
+    : ["forge", "run", helperId];
+  const result = spawnSync(command[0], [...command.slice(1), ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    console.error(`Missing Forge runtime for helper ${helperId}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}

package/scripts/migrate-project-template.sh

@@ -1,36 +1,4 @@
 #!/bin/bash
-# Run the canonical Forge adoption path without guessing a developer checkout.
-#
-# The self-host repository invokes this script directly, so delegating to a
-# discovered copy of this same filename used to recurse. Installed helper
-# copies use an explicit source root when one is supplied, otherwise the
-# installed `forge` CLI.
-
 set -euo pipefail
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SELF_SOURCE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-SOURCE_ROOT="${FORGE_SOURCE_ROOT:-${AGENTIC_DEV_ROOT:-${AGENTIC_DEV_SKILL_ROOT:-}}}"
-
-run_source_root() {
-  local root="$1"
-  shift
-  [[ -f "$root/src/cli/index.ts" ]] || return 1
-  command -v bun >/dev/null 2>&1 || {
-    echo "[migrate] bun is required to run Forge from source: $root" >&2
-    exit 1
-  }
-  exec bun "$root/src/cli/index.ts" adopt "$@" --no-codegraph --no-verify
-}
-
-run_source_root "$SELF_SOURCE_ROOT" "$@"
-if [[ -n "$SOURCE_ROOT" ]]; then
-  run_source_root "$SOURCE_ROOT" "$@"
-fi
-
-if command -v forge >/dev/null 2>&1; then
-  exec forge adopt "$@" --no-codegraph --no-verify
-fi
-
-echo "[migrate] Missing Forge CLI; set FORGE_SOURCE_ROOT to a Forge source checkout." >&2
-exit 1
+exec "$SCRIPT_DIR/lib/run-forge-helper.sh" "migrate-project-template.sh" "$@"