@warpgogol/forge 2.11.0 → 2.14.0

package/bin/cli.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/*
+<MODULE_CONTRACT>
+<purpose>CLI bin entrypoint for @warpgogol/forge — minimal command runner that
+registers forge modules and dispatches commands. Works autonomously without
+@warpgogol/werkstatt-engine.</purpose>
+<non-goals>
+  <item>Do not implement command logic — delegate to forge os/ modules and src/ handlers.</item>
+  <item>Do not replicate the full kernel runtime — minimal dispatch only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial CLI bin entrypoint for forge autonomy refactor.</item>
+  <item>RFC-0542: self-documenting output contract — renderNextSteps, renderIdeRecommendation, generateHelp, --help <command> flag.</item>
+  <item>RFC-0543: source VERSION from package.json at runtime instead of hardcoded constant.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+const logger = {
+  section(msg: string, details?: unknown) {
+    console.log(`\n■ ${msg}`);
+    if (details) console.log(details);
+  },
+  info(msg: string, details?: unknown) {
+    console.log(`  ${msg}`);
+    if (details) console.log(details);
+  },
+  warn(msg: string, details?: unknown) {
+    console.warn(`  ⚠ ${msg}`);
+    if (details) console.warn(details);
+  },
+  error(msg: string, details?: unknown) {
+    console.error(`  ✖ ${msg}`);
+    if (details) console.error(details);
+  },
+  success(msg: string, details?: unknown) {
+    console.log(`  ✓ ${msg}`);
+    if (details) console.log(details);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Minimal registry
+// ---------------------------------------------------------------------------
+
+import type {
+  ForgeCommandDefinition,
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+  ForgeFlagValue,
+  CommandRegistry,
+  ForgeRegisteredCommandInfo,
+} from "../src/types.ts";
+import { renderNextSteps, renderIdeRecommendation, generateHelp } from "../src/cli-output.ts";
+import type { ForgeModule, ForgeModuleRegistry, ForgePipelineStep } from "../src/forge-module.ts";
+
+class ForgeCliRegistry implements ForgeModuleRegistry, CommandRegistry {
+  private commands = new Map<string, ForgeCommandDefinition>();
+
+  registerCommand(command: ForgeCommandDefinition): void {
+    this.commands.set(command.name, command);
+  }
+
+  registerPipeline(_name: string, _steps: ForgePipelineStep[]): void {
+    // CLI mode: pipelines not supported — no-op
+  }
+
+  listCommandNames(): string[] {
+    return [...this.commands.keys()].sort();
+  }
+
+  listCommands(): ForgeRegisteredCommandInfo[] {
+    return [...this.commands.values()].map((c) => ({
+      name: c.name,
+      description: c.description,
+      scope: c.scope,
+      provider: "workspace" as const,
+      mutatesState: c.mutatesState,
+      requiresNetwork: c.requiresNetwork,
+      supportsAllSites: c.supportsAllSites,
+      timeoutMs: c.timeoutMs,
+      expectedDurationMs: c.expectedDurationMs,
+      longRunning: c.longRunning,
+      hidden: c.hidden,
+      flags: c.flags,
+      reads: c.reads,
+      writes: c.writes,
+    }));
+  }
+
+  getCommand(name: string): ForgeCommandDefinition | undefined {
+    return this.commands.get(name);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv: string[]): { flags: Record<string, ForgeFlagValue> } {
+  const flags: Record<string, ForgeFlagValue> = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const eqIndex = arg.indexOf("=");
+      if (eqIndex > 0) {
+        const key = arg.slice(2, eqIndex);
+        const value = arg.slice(eqIndex + 1);
+        flags[key] = value;
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else {
+      // RFC-0609: positional arguments are no longer collected; ignore them
+    }
+  }
+
+  return { flags };
+}
+
+// ---------------------------------------------------------------------------
+// Module registration
+// ---------------------------------------------------------------------------
+
+async function buildRegistry(): Promise<ForgeCliRegistry> {
+  const registry = new ForgeCliRegistry();
+
+  const modules: ForgeModule[] = [
+    await import("../os/core/core.module.ts").then((m) => m.forgeCoreModule),
+    await import("../os/rfc/rfc.module.ts").then((m) => m.forgeRfcModule),
+    await import("../os/workflow/workflow.module.ts").then((m) => m.forgeWorkflowModule),
+    await import("../os/naming/naming.module.ts").then((m) => m.forgeNamingModule),
+    await import("../os/compass/compass.module.ts").then((m) => m.forgeCompassModule),
+    await import("../os/werkstatt/werkstatt.module.ts").then((m) => m.forgeWerkstattModule),
+    await import("../os/session/session.module.ts").then((m) => m.forgeSessionModule),
+    await import("../os/exploration/exploration.module.ts").then((m) => m.forgeExplorationModule),
+    await import("../os/notes/notes.module.ts").then((m) => m.forgeNotesModule),
+  ].filter((m): m is ForgeModule => m !== null);
+
+  for (const mod of modules) {
+    await mod.register(registry);
+  }
+
+  return registry;
+}
+
+// ---------------------------------------------------------------------------
+// Output rendering (RFC-0542: self-documenting forge command output contract)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Version — sourced from package.json at runtime (RFC-0543)
+// ---------------------------------------------------------------------------
+
+function readVersion(): string {
+  // Source: packages/forge/bin/cli.ts → packages/forge/package.json (one up)
+  // Compiled: dist/bin/cli.js → package.json (two up)
+  for (const up of ["..", "../.."]) {
+    const pkgPath = join(__dirname, up, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+      if (pkg.version) return pkg.version;
+    } catch {
+      // try next candidate
+    }
+  }
+  return "0.0.0-unknown";
+}
+
+const VERSION = readVersion();
+
+function resolveForgeRootFromCli(): string | undefined {
+  // Source: packages/forge/bin/cli.ts → packages/forge/ (one up)
+  // Compiled: dist/bin/cli.js → packages/forge/ (two up)
+  for (const up of ["..", "../.."]) {
+    const pkgPath = join(__dirname, up, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+      if (pkg.name === "@warpgogol/forge") return join(__dirname, up);
+    } catch {
+      // try next candidate
+    }
+  }
+  return undefined;
+}
+
+function printCommandHelp(registry: ForgeCliRegistry, commandName: string): void {
+  const resolved = resolveCommandName(commandName, registry);
+  const cmd = resolved ? registry.getCommand(resolved) : undefined;
+  if (!resolved || !cmd) {
+    logger.error(`Unknown command: ${commandName}`);
+    logger.info(`Run 'forge --help' for available commands.`);
+    process.exit(1);
+  }
+  const displayName = resolved.replace(/^forge\./, "");
+  console.log(`forge ${displayName}`);
+  console.log(`\n  ${cmd.description}`);
+  if (cmd.flags && Object.keys(cmd.flags).length > 0) {
+    console.log("\nFlags:");
+    for (const [flagName, flagSpec] of Object.entries(cmd.flags)) {
+      const required = flagSpec.required ? " (required)" : "";
+      console.log(`  --${flagName}${required}  ${flagSpec.description}`);
+    }
+  }
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Command-name resolution (RFC-0699)
+// ---------------------------------------------------------------------------
+
+function resolveCommandName(commandName: string, registry: ForgeCliRegistry): string | undefined {
+  if (registry.getCommand(commandName)) {
+    if (commandName.startsWith("forge.")) {
+      const unqualified = commandName.slice("forge.".length);
+      logger.warn("'" + commandName + "' is deprecated; use '" + unqualified + "'");
+    }
+    return commandName;
+  }
+  const qualified = "forge." + commandName;
+  if (registry.getCommand(qualified)) {
+    return qualified;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || (argv[0] === "--help" && argv.length === 1) || argv[0] === "-h") {
+    const registry = await buildRegistry();
+    console.log(generateHelp(registry));
+    process.exit(0);
+  }
+
+  if (argv[0] === "--help" && argv.length >= 2) {
+    const registry = await buildRegistry();
+    printCommandHelp(registry, argv[1]);
+    return;
+  }
+
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    console.log(`forge ${VERSION}`);
+    process.exit(0);
+  }
+
+  const commandName = argv[0];
+  const rest = argv.slice(1);
+  const { flags } = parseArgs(rest);
+
+  const registry = await buildRegistry();
+  const resolved = resolveCommandName(commandName, registry);
+  const command = resolved ? registry.getCommand(resolved) : undefined;
+
+  if (!command) {
+    logger.error(`Unknown command: ${commandName}`);
+    logger.info(`Run 'forge --help' for available commands.`);
+    process.exit(1);
+  }
+
+  const workspaceRoot = resolve(process.cwd());
+  const outputFormat = flags["json"] === true ? "json" : "pretty";
+  const dryRun = flags["dry-run"] === true;
+
+  const input: ForgeCommandInput = { argv: rest, flags };
+  const resolvedForgeRoot = resolveForgeRootFromCli();
+  if (outputFormat === "pretty" && commandName === "forge.create") {
+    logger.info(`forge root: ${resolvedForgeRoot ?? "(not resolved)"}`);
+  }
+
+  const context: ForgeRuntimeContext = {
+    workspaceRoot,
+    forgeRoot: resolvedForgeRoot,
+    logger,
+    dryRun,
+    outputFormat,
+    commandRegistry: registry,
+  };
+
+  try {
+    const result = (await command.execute(input, context)) as ForgeCommandResult | void;
+    if (result && outputFormat === "json") {
+      const output = { ...(result.data ?? {}), nextSteps: result.nextSteps ?? [] };
+      console.log(JSON.stringify(output, null, 2));
+    } else if (result && outputFormat === "pretty") {
+      if (result.summary) {
+        console.log(result.summary);
+      }
+      const nextStepsText = renderNextSteps(result.nextSteps);
+      if (nextStepsText) {
+        console.log(nextStepsText);
+      }
+      if (commandName === "forge.create") {
+        console.log(renderIdeRecommendation());
+      }
+    }
+    const exitCode = result?.exitCode ?? 0;
+    process.exit(exitCode);
+  } catch (error) {
+    logger.error(
+      error instanceof Error ? error.message : String(error),
+      error instanceof Error && error.stack ? error.stack : undefined,
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  logger.error(
+    error instanceof Error ? error.message : String(error),
+    error instanceof Error && error.stack ? error.stack : undefined,
+  );
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.11.0",
+  "version": "2.14.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -147,8 +147,7 @@
     }
   },
   "files": [
-    "dist/",
-    "bin/cli.js",
+    "bin/",
     "skills/",
     "profiles/",
     "src/",
@@ -165,8 +164,7 @@
     "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "test:tarball:node24": "node test-fixtures/node24-consumer/smoke.mjs",
-    "prepublishOnly": "pnpm exec tsc -p tsconfig.json"
+    "test:tarball:node24": "node test-fixtures/node24-consumer/smoke.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
@@ -188,131 +186,7 @@
     "node": ">=24 <25"
   },
   "publishConfig": {
-    "access": "public",
-    "main": "./dist/src/index.js",
-    "types": "./dist/src/index.d.ts",
-    "exports": {
-      ".": {
-        "types": "./dist/src/index.d.ts",
-        "default": "./dist/src/index.js"
-      },
-      "./types": {
-        "types": "./dist/src/types.d.ts",
-        "default": "./dist/src/types.js"
-      },
-      "./utils": {
-        "types": "./dist/src/utils/index.d.ts",
-        "default": "./dist/src/utils/index.js"
-      },
-      "./config": {
-        "types": "./dist/src/config/forge-config.d.ts",
-        "default": "./dist/src/config/forge-config.js"
-      },
-      "./os/core": {
-        "types": "./dist/os/core/core.module.d.ts",
-        "default": "./dist/os/core/core.module.js"
-      },
-      "./os/compass": {
-        "types": "./dist/os/compass/index.d.ts",
-        "default": "./dist/os/compass/index.js"
-      },
-      "./os/naming": {
-        "types": "./dist/os/naming/index.d.ts",
-        "default": "./dist/os/naming/index.js"
-      },
-      "./os/naming-module": {
-        "types": "./dist/os/naming/naming.module.d.ts",
-        "default": "./dist/os/naming/naming.module.js"
-      },
-      "./os/rfc": {
-        "types": "./dist/os/rfc/index.d.ts",
-        "default": "./dist/os/rfc/index.js"
-      },
-      "./os/rfc-module": {
-        "types": "./dist/os/rfc/rfc.module.d.ts",
-        "default": "./dist/os/rfc/rfc.module.js"
-      },
-      "./os/werkstatt": {
-        "types": "./dist/os/werkstatt/index.d.ts",
-        "default": "./dist/os/werkstatt/index.js"
-      },
-      "./os/workflow": {
-        "types": "./dist/os/workflow/index.d.ts",
-        "default": "./dist/os/workflow/index.js"
-      },
-      "./os/workflow-module": {
-        "types": "./dist/os/workflow/workflow.module.d.ts",
-        "default": "./dist/os/workflow/workflow.module.js"
-      },
-      "./os/spec-module": {
-        "types": "./dist/os/spec/spec.module.d.ts",
-        "default": "./dist/os/spec/spec.module.js"
-      },
-      "./os/adr": {
-        "types": "./dist/os/adr/index.d.ts",
-        "default": "./dist/os/adr/index.js"
-      },
-      "./os/adr-module": {
-        "types": "./dist/os/adr/adr.module.d.ts",
-        "default": "./dist/os/adr/adr.module.js"
-      },
-      "./os/plan": {
-        "types": "./dist/os/plan/index.d.ts",
-        "default": "./dist/os/plan/index.js"
-      },
-      "./os/plan-module": {
-        "types": "./dist/os/plan/plan.module.d.ts",
-        "default": "./dist/os/plan/plan.module.js"
-      },
-      "./os/audit": {
-        "types": "./dist/os/audit/index.d.ts",
-        "default": "./dist/os/audit/index.js"
-      },
-      "./os/audit-module": {
-        "types": "./dist/os/audit/audit.module.d.ts",
-        "default": "./dist/os/audit/audit.module.js"
-      },
-      "./os/session": {
-        "types": "./dist/os/session/index.d.ts",
-        "default": "./dist/os/session/index.js"
-      },
-      "./os/session-module": {
-        "types": "./dist/os/session/session.module.d.ts",
-        "default": "./dist/os/session/session.module.js"
-      },
-      "./os/mission": {
-        "types": "./dist/os/mission/index.d.ts",
-        "default": "./dist/os/mission/index.js"
-      },
-      "./os/mission-module": {
-        "types": "./dist/os/mission/mission.module.d.ts",
-        "default": "./dist/os/mission/mission.module.js"
-      },
-      "./os/exploration": {
-        "types": "./dist/os/exploration/index.d.ts",
-        "default": "./dist/os/exploration/index.js"
-      },
-      "./os/exploration-module": {
-        "types": "./dist/os/exploration/exploration.module.d.ts",
-        "default": "./dist/os/exploration/exploration.module.js"
-      },
-      "./os/notes": {
-        "types": "./dist/os/notes/index.d.ts",
-        "default": "./dist/os/notes/index.js"
-      },
-      "./os/notes-module": {
-        "types": "./dist/os/notes/notes.module.d.ts",
-        "default": "./dist/os/notes/notes.module.js"
-      },
-      "./os/program": {
-        "types": "./dist/os/program/program.module.d.ts",
-        "default": "./dist/os/program/program.module.js"
-      },
-      "./os/plugin": {
-        "types": "./dist/os/plugin/plugin.module.d.ts",
-        "default": "./dist/os/plugin/plugin.module.js"
-      }
-    }
+    "access": "public"
   },
   "packageManager": "pnpm@11.10.0"
 }

package/src/types/werkstatt-shared-shims.d.ts

@@ -25,6 +25,16 @@ declare module "@warpgogol/werkstatt-shared" {
   export const readDefaultLanguageCode: any;
 }
 
+declare module "@warpgogol/werkstatt-shared/plugin" {
+  export interface PluginHookContext {}
+  export interface HookResult {}
+  export interface StackPathConventions {}
+  export interface StackInvariant {}
+  export interface WerkstattPluginHooks {}
+  export interface WerkstattPlugin {}
+  export type DeployAdapterFactory = any;
+}
+
 declare module "@warpgogol/werkstatt-shared/checks" {
   export function parseSuppressionsConfig(...args: any[]): any;
   export function loadWorkshopSuppressions(...args: any[]): any;

package/dist/bin/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}