@warpgogol/forge 2.8.0 → 2.8.2

package/src/types.ts

@@ -0,0 +1,221 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical forge runtime types — autonomous, no @warpgogol/* dependencies.
+Structurally compatible with @warpgogol/site-kernel types so that forge modules
+can be registered in a Warpgogol kernel without direct dependency.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/site-kernel or any @warpgogol/* package.</item>
+  <item>Do not add Warpgogol-specific fields to ForgeRuntimeContext — keep it minimal and portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial canonical forge types: ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext, ForgeFlagSpec, Diagnostic, CommandRegistry, ForgeLogger.</item>
+  <item>RFC-0518: add GateMetadata, GateSeverity, GatePhase, GateConditional types and optional gate field to ForgeCommandMetadata (structurally compatible with @warpgogol/site-kernel).</item>
+</CHANGE_SUMMARY>
+*/
+
+// ---------------------------------------------------------------------------
+// Command input / output
+// ---------------------------------------------------------------------------
+
+export type ForgeFlagValue = boolean | string | string[];
+
+export interface ForgeCommandInput {
+  argv: string[];
+  flags: Record<string, ForgeFlagValue>;
+}
+
+export interface ForgeCommandTiming {
+  durationMs?: number;
+  startedAt?: string;
+  endedAt?: string;
+}
+
+export interface ForgeNextStep {
+  action: string;
+  kind: "required" | "optional";
+}
+
+export interface ForgeCommandResult<TData = unknown> {
+  data?: TData;
+  nextSteps?: ForgeNextStep[];
+  exitCode?: number;
+  summary?: string;
+  timing?: ForgeCommandTiming;
+}
+
+// ---------------------------------------------------------------------------
+// Flag specs (RFC-0260 lineage)
+// ---------------------------------------------------------------------------
+
+export interface ForgeFlagSpec {
+  kind: "boolean" | "string" | "string[]";
+  required?: boolean;
+  default?: ForgeFlagValue;
+  description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Command metadata / definition
+// ---------------------------------------------------------------------------
+
+export type ForgeCommandScope = "app" | "workspace";
+
+export interface ForgeCommandMetadata {
+  description: string;
+  scope: ForgeCommandScope;
+  mutatesState?: boolean;
+  requiresNetwork?: boolean;
+  supportsAllSites?: boolean;
+  timeoutMs?: number;
+  expectedDurationMs?: number;
+  longRunning?: boolean;
+  cacheable?: boolean;
+  hidden?: boolean;
+  /**
+   * RFC-0518: declarative gate metadata. Optional. Structurally compatible
+   * with GateMetadata from @warpgogol/site-kernel. Does NOT affect execution.
+   */
+  gate?: GateMetadata;
+}
+
+// ---------------------------------------------------------------------------
+// RFC-0518: declarative gate metadata (structurally compatible with @warpgogol/site-kernel)
+// ---------------------------------------------------------------------------
+
+export type GateSeverity = "error" | "warning" | "mixed";
+export type GatePhase = "author" | "postbuild" | "workspace" | "mission" | "release";
+
+export interface GateConditional {
+  kind: "entitlement" | "flag" | "config";
+  ref: string;
+  description: string;
+}
+
+export interface GateMetadata {
+  severity: GateSeverity;
+  phase: GatePhase;
+  conditional?: GateConditional;
+  surfaces?: string[];
+  rules?: string[];
+  blocks?: string[];
+}
+
+export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
+  name: string;
+  provider: "workspace" | "site";
+  siteName?: string;
+  module?: string;
+  flags?: Record<string, ForgeFlagSpec>;
+  reads?: string[];
+  writes?: string[];
+  hidden?: boolean;
+}
+
+export interface ForgeCommandDefinition<TData = unknown> extends ForgeCommandMetadata {
+  name: string;
+  flags?: Record<string, ForgeFlagSpec>;
+  reads?: string[];
+  writes?: string[];
+  execute(
+    input: ForgeCommandInput,
+    context: ForgeRuntimeContext,
+  ): Promise<void | ForgeCommandResult<TData>> | void | ForgeCommandResult<TData>;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostic (RFC-0203 lineage)
+// ---------------------------------------------------------------------------
+
+export type DiagnosticSeverity = "error" | "warning" | "info";
+
+export interface DiagnosticEvidence {
+  kind: "rule" | "rendered" | "source" | "config" | "cache" | "runtime";
+  ruleFile?: string;
+  ruleId?: string;
+  file?: string;
+  url?: string;
+  snippet?: string;
+}
+
+export interface Diagnostic {
+  ruleId: string;
+  severity: DiagnosticSeverity;
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  fixHint?: string;
+  evidence?: DiagnosticEvidence[];
+  data?: Record<string, unknown>;
+  id?: string;
+  blockId?: string;
+  suggestion?: string;
+}
+
+export interface CheckResult {
+  command: string;
+  status: "pass" | "warn" | "fail";
+  diagnostics: Diagnostic[];
+  summary: { error: number; warning: number; info: number };
+}
+
+// ---------------------------------------------------------------------------
+// Logger — minimal, structurally compatible with KernelLogger
+// ---------------------------------------------------------------------------
+
+export interface ForgeLogger {
+  section(message: string, details?: unknown): void;
+  info(message: string, details?: unknown): void;
+  warn(message: string, details?: unknown): void;
+  error(message: string, details?: unknown): void;
+  success(message: string, details?: unknown): void;
+}
+
+// ---------------------------------------------------------------------------
+// CommandRegistry — interface injection for command discovery
+// ---------------------------------------------------------------------------
+
+export interface CommandRegistry {
+  listCommandNames(): string[];
+  listCommands(): ForgeRegisteredCommandInfo[];
+  getCommand(name: string): ForgeCommandDefinition | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime context — minimal, portable
+// ---------------------------------------------------------------------------
+
+export type ForgeOutputFormat = "pretty" | "json";
+
+export interface ForgeSiteContext {
+  name: string;
+  directory: string;
+  toolsDirectory: string;
+  configPath?: string;
+  packageName?: string;
+}
+
+export interface ForgeRuntimeContext {
+  workspaceRoot: string;
+  logger: ForgeLogger;
+  dryRun: boolean;
+  outputFormat: ForgeOutputFormat;
+  /**
+   * Optional command registry — provided by the runner (forge CLI or site-kernel).
+   * Forge commands that need to discover other commands (e.g. rfc lifecycle validation)
+   * access this through the context instead of importing a kernel-specific function.
+   */
+  commandRegistry?: CommandRegistry;
+  /** Optional target site/app context — provided when running in app-scoped mode. */
+  site?: ForgeSiteContext;
+  /** True only when --site <name> was passed explicitly by the caller. */
+  siteExplicit?: boolean;
+  /**
+   * Optional forge root override — provided when a command is called from
+   * another command (e.g. forge.create delegates to forge.init and forge.scaffold
+   * in a new directory where resolveForgeRoot would fail). When set, handlers
+   * use this instead of calling resolveForgeRoot(workspaceRoot).
+   */
+  forgeRoot?: string;
+}

package/src/utils/__tests__/fs-idempotent.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { writeFileIfChanged } from "../fs-idempotent.ts";
+import { join } from "node:path";
+import { mkdtemp, rm, readFile, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-idempotent-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("writeFileIfChanged", () => {
+  it("writes new file and returns 'written'", async () => {
+    const filePath = join(tempDir, "new.txt");
+    const result = await writeFileIfChanged(filePath, "hello");
+    expect(result).toBe("written");
+    expect(await readFile(filePath, "utf8")).toBe("hello");
+  });
+
+  it("returns 'unchanged' when content is identical", async () => {
+    const filePath = join(tempDir, "same.txt");
+    await writeFile(filePath, "same content", "utf8");
+    const result = await writeFileIfChanged(filePath, "same content");
+    expect(result).toBe("unchanged");
+  });
+
+  it("writes when string content differs", async () => {
+    const filePath = join(tempDir, "change.txt");
+    await writeFile(filePath, "old", "utf8");
+    const result = await writeFileIfChanged(filePath, "new");
+    expect(result).toBe("written");
+    expect(await readFile(filePath, "utf8")).toBe("new");
+  });
+
+  it("writes to nested paths when parent dirs exist", async () => {
+    await mkdir(join(tempDir, "sub", "dir"), { recursive: true });
+    const filePath = join(tempDir, "sub", "dir", "file.txt");
+    const result = await writeFileIfChanged(filePath, "nested");
+    expect(result).toBe("written");
+    expect(await readFile(filePath, "utf8")).toBe("nested");
+  });
+
+  it("handles Uint8Array content", async () => {
+    const filePath = join(tempDir, "binary.bin");
+    const data = new Uint8Array([1, 2, 3, 4, 5]);
+    const result = await writeFileIfChanged(filePath, data);
+    expect(result).toBe("written");
+    const buf = await readFile(filePath);
+    expect(new Uint8Array(buf)).toEqual(data);
+  });
+
+  it("returns 'unchanged' for identical Uint8Array content", async () => {
+    const filePath = join(tempDir, "binary.bin");
+    const data = new Uint8Array([10, 20, 30]);
+    await writeFileIfChanged(filePath, data);
+    const result = await writeFileIfChanged(filePath, data);
+    expect(result).toBe("unchanged");
+  });
+
+  it("writes when Uint8Array content differs", async () => {
+    const filePath = join(tempDir, "binary.bin");
+    await writeFileIfChanged(filePath, new Uint8Array([1, 2, 3]));
+    const result = await writeFileIfChanged(filePath, new Uint8Array([4, 5, 6]));
+    expect(result).toBe("written");
+    const buf = await readFile(filePath);
+    expect(new Uint8Array(buf)).toEqual(new Uint8Array([4, 5, 6]));
+  });
+});

package/src/utils/__tests__/fs-trash.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { trashPath } from "../fs-trash.ts";
+import { join } from "node:path";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { existsSync } from "node:fs";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-trash-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("trashPath", () => {
+  it("does not throw when path does not exist", async () => {
+    const nonExistent = join(tempDir, "nope.txt");
+    expect(existsSync(nonExistent)).toBe(false);
+    await expect(trashPath(nonExistent)).resolves.toBeUndefined();
+  });
+
+  it("trashes a file", async () => {
+    const filePath = join(tempDir, "to-trash.txt");
+    await writeFile(filePath, "content", "utf8");
+    expect(existsSync(filePath)).toBe(true);
+
+    await trashPath(filePath);
+
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it("trashes a directory", async () => {
+    const dirPath = join(tempDir, "to-trash-dir");
+    await mkdir(dirPath, { recursive: true });
+    await writeFile(join(dirPath, "inner.txt"), "inner", "utf8");
+    expect(existsSync(dirPath)).toBe(true);
+
+    await trashPath(dirPath);
+
+    expect(existsSync(dirPath)).toBe(false);
+  });
+});

package/src/utils/fs-atomic.ts

@@ -0,0 +1,93 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Atomic file-write primitive — canonical forge utility. Writes to a temp
+file then renames, with bounded retry for Windows EPERM/EBUSY.</purpose>
+<non-goals>
+  <item>Do not provide cross-process locks — convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to non-atomic writes — fail loudly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from @warpgogol/site-kernel/fs-atomic to forge as canonical source (dependency inversion).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { writeFile, rename as fsRename, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface WriteFileAtomicOptions {
+  retries?: number;
+}
+
+let renameImpl: typeof fsRename = fsRename;
+
+export function __setRenameImplForTests(impl: typeof fsRename | undefined): void {
+  renameImpl = impl ?? fsRename;
+}
+
+const DEFAULT_RETRIES = 10;
+const RETRY_BACKOFF_MS = 50;
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY"]);
+
+function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeTempPath(filePath: string): string {
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const random = randomBytes(6).toString("hex");
+  return join(dir, `${name}.${random}.tmp`);
+}
+
+export async function writeFileAtomic(
+  filePath: string,
+  content: string | Uint8Array,
+  options?: WriteFileAtomicOptions,
+): Promise<void> {
+  const retries = options?.retries ?? DEFAULT_RETRIES;
+  const tempPath = makeTempPath(filePath);
+  let tempWritten = false;
+
+  try {
+    await writeFile(tempPath, content);
+    tempWritten = true;
+
+    let attempt = 0;
+    for (;;) {
+      try {
+        await renameImpl(tempPath, filePath);
+        return;
+      } catch (error) {
+        if (attempt >= retries || !isRetryableError(error)) {
+          throw error;
+        }
+        attempt += 1;
+        if (existsSync(filePath)) {
+          try {
+            await unlink(filePath);
+          } catch {
+            // If unlink also fails, the retry loop will try again.
+          }
+        }
+        await sleep(RETRY_BACKOFF_MS * attempt);
+      }
+    }
+  } finally {
+    if (tempWritten) {
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Expected in the success path (temp file already renamed away).
+      }
+    }
+  }
+}

package/src/utils/fs-idempotent.ts

@@ -0,0 +1,41 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Idempotent file-write primitive — canonical forge utility. Writes only
+when file content differs, delegating to writeFileAtomic for the actual write.
+Reduces unnecessary disk writes and git churn in Compass and Werkstatt commands.</purpose>
+<non-goals>
+  <item>Do not provide cross-process locks — convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to non-atomic writes — fail loudly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0556: moved from @warpgogol/site-kernel/fs-idempotent to forge as canonical source (dependency inversion).</item>
+  <item>RFC-0603: extended to accept Uint8Array (Buffer) content for idempotent binary file writes — PNG preview images.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { writeFileAtomic } from "./fs-atomic.ts";
+
+export async function writeFileIfChanged(
+  filePath: string,
+  content: string | Uint8Array,
+): Promise<"written" | "unchanged"> {
+  try {
+    if (typeof content === "string") {
+      const existing = await readFile(filePath, "utf8");
+      if (existing === content) {
+        return "unchanged";
+      }
+    } else {
+      const existing = await readFile(filePath);
+      if (Buffer.compare(existing, Buffer.from(content)) === 0) {
+        return "unchanged";
+      }
+    }
+  } catch {
+    // File does not exist — proceed to write.
+  }
+  await writeFileAtomic(filePath, content);
+  return "written";
+}

package/src/utils/fs-trash-sync.ts

@@ -0,0 +1,37 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Synchronous trash-can deletion — shells out to `trash-put` (trash-cli)
+on Linux/macOS and PowerShell Recycle Bin on Windows. Used by synchronous
+code paths that cannot use the async `trash` npm package.</purpose>
+<non-goals>
+  <item>Do not use for async code paths — use trashPath from fs-trash.ts instead.</item>
+  <item>Requires `trash-put` (trash-cli) installed on Linux/macOS. On Windows, uses PowerShell Recycle Bin API (no external binary needed).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial implementation: sync wrapper for `trash-put` (Linux/macOS) and PowerShell Recycle Bin (Windows).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+export function trashSync(targetPath: string): void {
+  if (!existsSync(targetPath)) return;
+  if (process.platform === "win32") {
+    const isDir = statSync(targetPath).isDirectory();
+    const method = isDir ? "DeleteDirectory" : "DeleteFile";
+    const escaped = targetPath.replace(/'/g, "''");
+    execFileSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-Command",
+        `Add-Type -AssemblyName Microsoft.VisualBasic; [Microsoft.VisualBasic.FileIO.FileSystem]::${method}('${escaped}', 'OnlyErrorDialogs', 'SendToRecycleBin')`,
+      ],
+      { stdio: "pipe" },
+    );
+  } else {
+    execFileSync("trash-put", [targetPath], { stdio: "pipe" });
+  }
+}

package/src/utils/fs-trash.ts

@@ -0,0 +1,24 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trash-can deletion primitive — moves files/directories to the OS
+trash/recycle bin instead of permanently deleting them. Uses the `trash`
+npm package which implements the FreeDesktop.org Trash specification on
+Linux (no external `trash-put` binary required) and the Recycle Bin on
+Windows.</purpose>
+<non-goals>
+  <item>Do not implement trash eviction or retention policies — the OS manages that.</item>
+  <item>Do not use for ephemeral cleanup (lock files, temp files, atomic write leftovers) — those are system-internal and should use fs.unlink directly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial implementation: wraps npm `trash` package with glob disabled for safe path handling.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync } from "node:fs";
+import trash from "trash";
+
+export async function trashPath(targetPath: string): Promise<void> {
+  if (!existsSync(targetPath)) return;
+  await trash(targetPath, { glob: false });
+}

package/src/utils/fs.ts

@@ -0,0 +1,74 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial filesystem utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-filesystem utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of collectFiles, fileExists from @warpgogol/werkstatt-shared/share/fs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface CollectFilesOptions {
+  extensions?: string[];
+  ignore?: (name: string) => boolean;
+  withDirs?: boolean;
+}
+
+function defaultIgnore(name: string): boolean {
+  return name.startsWith("-") || name.startsWith("old-");
+}
+
+export async function collectFiles(
+  root: string,
+  options: CollectFilesOptions = {},
+): Promise<string[]> {
+  const { extensions, ignore = defaultIgnore, withDirs = false } = options;
+  const results: string[] = [];
+
+  // fs.walk.lint: allow — this is the canonical collectFiles implementation,
+  // inlined from @warpgogol/werkstatt-shared/share/fs to keep @warpgogol/forge dependency-free (RFC-0303).
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (ignore(entry.name)) continue;
+
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (withDirs) results.push(full);
+        await walk(full);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+
+      if (extensions && !extensions.some((ext) => entry.name.endsWith(ext))) continue;
+
+      results.push(full);
+    }
+  }
+
+  await walk(root);
+  return results;
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}