@warpgogol/forge 5.2.4 → 5.3.1

package/src/types.ts

@@ -20,6 +20,101 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
+// RFC-1152: WorkspaceIO port types — declared locally so the standalone npm
+// build needs no @warpgogol/* package (ADR-0019). Structurally identical to
+// @warpgogol/werkstatt-shared/kernel/workspace-io — kernel callers passing a
+// real WorkspaceIO (context.io) are assignable both ways.
+
+export interface ExecOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  /** Extra environment variables merged over `process.env` for the child. */
+  env?: Record<string, string>;
+}
+
+export interface ExecResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * A directory entry in a port-neutral shape — no `node:fs` `Dirent` leaks
+ * through the port, so command modules never need to import `node:fs` just to
+ * type a listing. `isFile`/`isDirectory` are plain booleans (not methods).
+ */
+export interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+}
+
+/** Port-neutral `stat` result — no `node:fs` `Stats` leaks through the port. */
+export interface FileStat {
+  isFile: boolean;
+  isDirectory: boolean;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface WorkspaceIO {
+  readFile(path: string): Promise<string>;
+  readFileBytes(path: string): Promise<Uint8Array>;
+  exists(path: string): Promise<boolean>;
+  glob(pattern: string, opts?: { cwd?: string }): Promise<string[]>;
+  /** List a directory's immediate entries. Read-only; throws if the path is not a directory. */
+  readdir(path: string): Promise<DirEntry[]>;
+  /** File metadata in a port-neutral shape. Throws when the path does not exist. */
+  stat(path: string): Promise<FileStat>;
+  /** Resolve symlinks to the canonical absolute path. Read-only. */
+  realpath(path: string): Promise<string>;
+  /** Atomic by contract (rfc-0258). */
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  /** Append content to a file, creating it (and parent dirs) when absent. */
+  appendFile(path: string, content: string | Uint8Array): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  rm(path: string, opts?: { recursive?: boolean }): Promise<void>;
+  rename(src: string, dst: string): Promise<void>;
+  copyFile(src: string, dst: string): Promise<void>;
+  /** Create a unique temporary directory under `prefix`; returns its path. */
+  mkdtemp(prefix: string): Promise<string>;
+  exec(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+  /**
+   * RFC-1176: `true` only on the read-only adapter (`mutatesState: false`
+   * commands). Best-effort bookkeeping writes must be skipped with
+   * `if (!io.readonly)` instead of attempting a mutation that throws
+   * KERNEL-META-01 — the throw stays as the enforcement floor for
+   * undeclared mutations. Undefined on real and recording adapters.
+   */
+  readonly readonly?: boolean;
+}
+
+/**
+ * RFC-0960: Declared generated artifact specification on a kernel command.
+ * Lives on `ForgeCommandMetadata.generates[]` and is the source of truth
+ * for the derived generator ownership map.
+ */
+export interface GeneratedArtifactSpec {
+  /** Workpiece-relative path or glob, e.g. "src/content/system-health.generated.yaml". */
+  path: string;
+  /** Skip absence checks (RFC-0636 semantics) — e.g. produced only in build.post. */
+  conditional?: boolean;
+  /** Pipeline phase that produces it: informs which validator phase may assert existence. */
+  phase: "build.prepare" | "build.post" | "on-demand";
+  /**
+   * Override the default markerPolicy derivation. Default: public/** → "registry-only",
+   * everything else → "embedded". Set explicitly only for edge cases (e.g. .cache/pdf/**).
+   */
+  markerPolicy?: "embedded" | "registry-only";
+  /**
+   * Committed bytes contain non-deterministic fields (Ed25519 proofs, real-time
+   * created/generatedAt timestamps, build durations) — byte-compare against a
+   * dryRun render can never pass. generated.drift.validate skips volatile
+   * artifacts; existence/staleness/signature checks still apply elsewhere.
+   */
+  volatile?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Command input / output
 // ---------------------------------------------------------------------------
@@ -71,6 +166,24 @@ export interface ForgeCommandMetadata {
   description: string;
   scope: ForgeCommandScope;
   mutatesState?: boolean;
+  /**
+   * RFC-1176: permits `io.exec` on the read-only adapter — the command
+   * declares `mutatesState: false` but legitimately shells out for
+   * read-only probes. Structurally mirrors KernelCommandMetadata.
+   */
+  execOnReadOnly?: boolean;
+  /**
+   * RFC-1176: flag names whose truthy presence upgrades this invocation to
+   * a real (or `--dry-run` recording) adapter. Structurally mirrors
+   * KernelCommandMetadata.
+   */
+  mutatingFlags?: string[];
+  /**
+   * RFC-0960/0810: repo-relative path to the implementing module file —
+   * propagated into generator ownership entries (OWN-XCHECK-03 requires it
+   * on every command that declares generates[]).
+   */
+  modulePath?: string;
   requiresNetwork?: boolean;
   supportsAllSites?: boolean;
   /** RFC-0963: validation contract this command belongs to (e.g. "content", "seo"). */
@@ -118,6 +231,8 @@ export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];
   writes?: string[];
+  /** RFC-0960 generated-artifact declarations (on-demand generators). */
+  generates?: GeneratedArtifactSpec[];
   hidden?: boolean;
 }
 
@@ -126,6 +241,8 @@ export interface ForgeCommandDefinition<TData = unknown> extends ForgeCommandMet
   flags?: Record<string, ForgeFlagSpec>;
   reads?: string[];
   writes?: string[];
+  /** RFC-0960 generated-artifact declarations (on-demand generators). */
+  generates?: GeneratedArtifactSpec[];
   execute(
     input: ForgeCommandInput,
     context: ForgeRuntimeContext,
@@ -227,4 +344,10 @@ export interface ForgeRuntimeContext {
    * use this instead of calling resolveForgeRoot(workspaceRoot).
    */
   forgeRoot?: string;
+  /**
+   * RFC-1152: optional WorkspaceIO port — populated when a kernel invokes the
+   * command (writes flow through the recording adapter); absent under the
+   * standalone `forge` CLI, where helpers fall back to the ambient adapter.
+   */
+  io?: WorkspaceIO;
 }

package/src/utils/editable-region.ts

@@ -0,0 +1,156 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-1153: preservation-boundary split/merge for editable generated
+files. Pure, no I/O — callers read the existing file and write the merged
+result through WorkspaceIO. The `forge:custom` marker line bounds the
+generator-owned head; everything below it is carried over verbatim.</purpose>
+<non-goals>
+  <item>Do not perform file I/O — operates on in-memory content strings only.</item>
+  <item>Do not apply to non-editable generated files — GENERATED_MARKER files
+  keep the RFC-0081 binary semantics (marker present = overwrite, absent = skip).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>forge:custom marker bounds the generated head; canonical footer is the fallback boundary when absent.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1153: initial — splitEditableGenerated + mergeEditableGenerated with
+  forge:custom marker boundary and canonical-footer (last non-empty render line) fallback.</item>
+</CHANGE_SUMMARY>
+*/
+
+import {
+  CUSTOM_BOUNDARY_HINTS,
+  CUSTOM_BOUNDARY_MARKERS,
+  CUSTOM_BOUNDARY_TOKEN,
+  commentStyleForPath,
+} from "./generated-marker.ts";
+
+export interface EditableRegionSplit {
+  /** Content up to and including the boundary line (marker or footer). */
+  generatedHead: string;
+  /** Content after the boundary line, verbatim. null when empty. */
+  customTail: string | null;
+  boundary: "marker" | "footer" | "none";
+}
+
+/** DNA-58 rule: boundary and footer matching normalize CRLF to LF. */
+function normalizeNewlines(text: string): string {
+  return text.replace(/\r\n/g, "\n");
+}
+
+/**
+ * Canonical footer of a render — its last non-empty line. Callers that need
+ * the boundary value separately (doctor staleness, preserved-tail detection)
+ * derive it from the same render they pass to the merge.
+ */
+export function canonicalFooterOf(rendered: string): string | null {
+  const lines = normalizeNewlines(rendered).split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (line !== undefined && line.trim() !== "") return line;
+  }
+  return null;
+}
+
+/**
+ * Split an existing editable generated file at its preservation boundary.
+ *
+ * Priority:
+ * 1. First line containing the `forge:custom` token (comment-style agnostic —
+ *    a token in prose is a documented, deliberate-looking boundary hazard).
+ *    The marker line and an immediately following canonical hint line belong
+ *    to the generated head.
+ * 2. `footerLine` (canonical template footer, derived by callers from the
+ *    render as its last non-empty line) — first occurrence is the boundary.
+ * 3. `"none"` — no resolvable boundary.
+ */
+export function splitEditableGenerated(
+  content: string,
+  filePath: string,
+  footerLine?: string,
+): EditableRegionSplit {
+  const text = normalizeNewlines(content);
+  const style = commentStyleForPath(filePath);
+  const hint = CUSTOM_BOUNDARY_HINTS[style];
+  const lines = text.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== undefined && line.includes(CUSTOM_BOUNDARY_TOKEN)) {
+      let headEnd = i + 1;
+      if (lines[headEnd] === hint) headEnd += 1;
+      const tail = lines.slice(headEnd).join("\n");
+      return {
+        generatedHead: lines.slice(0, headEnd).join("\n"),
+        customTail: tail.trim() === "" ? null : tail,
+        boundary: "marker",
+      };
+    }
+  }
+
+  if (footerLine !== undefined) {
+    // lastIndexOf: the canonical footer is the template's last line — the
+    // trailingmost occurrence is the correct boundary even when an operator
+    // copied the line into a mid-file section.
+    const idx = lines.lastIndexOf(footerLine);
+    if (idx >= 0) {
+      const tail = lines.slice(idx + 1).join("\n");
+      return {
+        generatedHead: lines.slice(0, idx + 1).join("\n"),
+        customTail: tail.trim() === "" ? null : tail,
+        boundary: "footer",
+      };
+    }
+  }
+
+  return { generatedHead: text, customTail: null, boundary: "none" };
+}
+
+/**
+ * Merge a fresh render with an existing editable generated file.
+ *
+ * The canonical footer is derived internally as the last non-empty line of
+ * `rendered` — no per-file-kind footer registry exists; when a template tail
+ * changes, the boundary follows the new render automatically.
+ *
+ * Merge contract:
+ * - `existing === null` (new file): rendered + boundary marker + hint.
+ * - marker boundary: head = fresh render + marker + hint; tail verbatim.
+ * - footer boundary (legacy marker-less file): head = fresh render + marker +
+ *   hint (marker introduced now); tail = content after the legacy footer line.
+ * - none + identical content: clean regeneration, marker + hint appended.
+ * - none + divergent content: returns null — caller must skip and warn
+ *   (`unmapped-customization`), never overwrite.
+ *
+ * The result is LF-normalized; callers write through `writeFileIfChanged`.
+ */
+export function mergeEditableGenerated(
+  rendered: string,
+  existing: string | null,
+  filePath: string,
+): string | null {
+  const render = normalizeNewlines(rendered);
+  const style = commentStyleForPath(filePath);
+  const marker = CUSTOM_BOUNDARY_MARKERS[style];
+  const hint = CUSTOM_BOUNDARY_HINTS[style];
+  const boundaryBlock = `${marker}\n${hint}\n`;
+
+  if (existing === null) {
+    return `${render}${boundaryBlock}`;
+  }
+
+  const text = normalizeNewlines(existing);
+  const footer = canonicalFooterOf(render);
+  const split = splitEditableGenerated(text, filePath, footer ?? undefined);
+
+  if (split.boundary === "marker" || split.boundary === "footer") {
+    return `${render}${boundaryBlock}${split.customTail ?? ""}`;
+  }
+
+  if (text === render || text === `${render}${boundaryBlock}`) {
+    return `${render}${boundaryBlock}`;
+  }
+
+  return null;
+}

package/src/utils/fs-idempotent.ts

@@ -27,28 +27,34 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import { readFile } from "node:fs/promises";
-import { writeFileAtomic } from "./fs-atomic.ts";
+import type { WorkspaceIO } from "../types.ts";
+import { resolveIo } from "./io.ts";
 
+// Forge-autonomy boundary (ADR-0019 / FORGE-AUTONOMY-01): `io` is optional and
+// TYPE-ONLY — forge's standalone CLI has no kernel context, so `resolveIo`
+// falls back to the ambient adapter. Kernel callers pass context.io so the
+// read-compare-write goes through the recording adapter.
 export async function writeFileIfChanged(
   filePath: string,
   content: string | Uint8Array,
+  io?: WorkspaceIO,
 ): Promise<"written" | "unchanged"> {
+  const fio = resolveIo(io);
   try {
     if (typeof content === "string") {
-      const existing = await readFile(filePath, "utf8");
+      const existing = await fio.readFile(filePath);
       if (existing === content) {
         return "unchanged";
       }
     } else {
-      const existing = await readFile(filePath);
-      if (Buffer.compare(existing, Buffer.from(content)) === 0) {
+      const existing = await fio.readFileBytes(filePath);
+      if (Buffer.compare(Buffer.from(existing), Buffer.from(content)) === 0) {
         return "unchanged";
       }
     }
   } catch {
     // File does not exist — proceed to write.
   }
-  await writeFileAtomic(filePath, content);
+  await fio.writeFile(filePath, content);
   return "written";
 }

package/src/utils/generated-marker.ts

@@ -20,6 +20,31 @@ export const GENERATED_MARKER =
 export const EDITABLE_GENERATED_MARKER =
   "GENERATED. Safe to edit — project-specific changes are expected and encouraged.";
 
+/**
+ * RFC-1153: preservation boundary marker for editable generated files.
+ * Everything below the marker line is carried over verbatim on regeneration;
+ * everything above (including the marker line itself) is generator-owned.
+ * Emitted in the file's comment style — see CUSTOM_BOUNDARY_MARKERS.
+ */
+export const CUSTOM_BOUNDARY_TOKEN = "forge:custom";
+
+export const CUSTOM_BOUNDARY_MARKERS: Record<GeneratedHeaderCommentStyle, string> = {
+  "line-slash": "// forge:custom",
+  "line-hash": "# forge:custom",
+  "block-html": "<!-- forge:custom -->",
+  "block-css": "/* forge:custom */",
+};
+
+const CUSTOM_BOUNDARY_HINT_TEXT =
+  "Add workspace-specific guidance below this line. Everything below is preserved on regeneration.";
+
+export const CUSTOM_BOUNDARY_HINTS: Record<GeneratedHeaderCommentStyle, string> = {
+  "line-slash": `// ${CUSTOM_BOUNDARY_HINT_TEXT}`,
+  "line-hash": `# ${CUSTOM_BOUNDARY_HINT_TEXT}`,
+  "block-html": `<!-- ${CUSTOM_BOUNDARY_HINT_TEXT} -->`,
+  "block-css": `/* ${CUSTOM_BOUNDARY_HINT_TEXT} */`,
+};
+
 const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
 const SAFE_TO_EDIT_LINE =
   "This file is generated but editable — your changes are preserved on regeneration.";
@@ -28,6 +53,15 @@ export function hasGeneratedMarker(content: string): boolean {
   return content.includes(GENERATED_MARKER) || content.includes(EDITABLE_GENERATED_MARKER);
 }
 
+/**
+ * RFC-1153: true only for files carrying the editable marker. A file bearing
+ * just GENERATED_MARKER is fully generator-owned (RFC-0081) — the merge
+ * upgrades it to the editable boundary contract instead of skipping it.
+ */
+export function hasEditableGeneratedMarker(content: string): boolean {
+  return content.includes(EDITABLE_GENERATED_MARKER);
+}
+
 export interface StripGeneratedMarkerResult {
   changed: boolean;
   content: string;
@@ -112,9 +146,9 @@ export interface GeneratedHeaderInput {
   editable?: boolean;
 }
 
-type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
+export type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
 
-function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
+export function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
   const lower = filePath.toLowerCase().replace(/\\/g, "/");
   const base = lower.slice(lower.lastIndexOf("/") + 1);
   if (

package/src/utils/index.ts

@@ -27,14 +27,31 @@ export { writeFileIfChanged } from "./fs-idempotent.ts";
 export {
   GENERATED_MARKER,
   EDITABLE_GENERATED_MARKER,
+  CUSTOM_BOUNDARY_TOKEN,
+  CUSTOM_BOUNDARY_MARKERS,
+  CUSTOM_BOUNDARY_HINTS,
   hasGeneratedMarker,
+  hasEditableGeneratedMarker,
   stripGeneratedMarker,
   buildGeneratedHeader,
+  commentStyleForPath,
   isGeneratedMarkerTextCandidate,
+  type GeneratedHeaderCommentStyle,
   type GeneratedHeaderInput,
   type StripGeneratedMarkerResult,
 } from "./generated-marker.ts";
+export {
+  splitEditableGenerated,
+  mergeEditableGenerated,
+  canonicalFooterOf,
+  type EditableRegionSplit,
+} from "./editable-region.ts";
 export { toKebabCase } from "./string-utils.ts";
+export {
+  alignMarkdownTable,
+  parseMarkdownTable,
+  type ParsedMarkdownTable,
+} from "./markdown-table.ts";
 export { collectFiles, fileExists, type CollectFilesOptions } from "./fs.ts";
 export { byteHash } from "./hash.ts";
 export { trashPath } from "./fs-trash.ts";

package/src/utils/io.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1152 (Wave 2a): the standalone-CLI ambient WorkspaceIO adapter. Forge
+helpers take an optional `io?: WorkspaceIO` — when absent, `resolveIo` returns
+this ambient adapter so the standalone `forge` CLI keeps working without a
+kernel context. Kernel callers (`forge/os` handlers) pass `context.io` through.
+</purpose>
+<non-goals>
+  <item>Do not record WriteIntents — forge CLI has no execution-report surface.</item>
+  <item>Do not enforce sync parity — WorkspaceIO is async-only; sync helpers stay ambient.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>createDefaultIO is deliberately unused — forge keeps a minimal ambient adapter for the standalone CLI.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1152 Wave 2a: initial ambient adapter for forge standalone CLI.</item>
+</CHANGE_SUMMARY>
+*/
+
+import {
+  readFile as fsReadFile,
+  mkdir as fsMkdir,
+  rm as fsRm,
+  readdir as fsReaddir,
+  stat as fsStat,
+  rename as fsRename,
+  appendFile as fsAppendFile,
+  copyFile as fsCopyFile,
+  mkdtemp as fsMkdtemp,
+  realpath as fsRealpath,
+  glob as fsGlob,
+} from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+import type { ExecOptions, ExecResult, WorkspaceIO } from "../types.ts";
+import { writeFileAtomic } from "./fs-atomic.ts";
+
+async function execImpl(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: opts?.cwd,
+      env: opts?.env ? { ...process.env, ...opts.env } : undefined,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          child.kill();
+        }, opts.timeoutMs)
+      : undefined;
+    timer?.unref?.();
+    child.on("close", (exitCode) => {
+      if (timer) clearTimeout(timer);
+      resolve({ exitCode, stdout, stderr });
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+/**
+ * The ambient adapter — real fs, no intent recording. Used by forge helpers
+ * when no `io` is injected (standalone `forge` CLI path).
+ */
+export const ambientIo: WorkspaceIO = {
+  async readFile(path) {
+    return fsReadFile(path, "utf8");
+  },
+  async readFileBytes(path) {
+    return fsReadFile(path);
+  },
+  async exists(path) {
+    try {
+      await fsStat(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async glob(pattern, opts) {
+    const results: string[] = [];
+    for await (const entry of fsGlob(pattern, { cwd: opts?.cwd })) {
+      results.push(entry);
+    }
+    return results;
+  },
+  async readdir(path) {
+    const entries = await fsReaddir(path, { withFileTypes: true });
+    return entries.map((entry) => ({
+      name: entry.name,
+      isFile: entry.isFile(),
+      isDirectory: entry.isDirectory(),
+    }));
+  },
+  async stat(path) {
+    const s = await fsStat(path);
+    return { isFile: s.isFile(), isDirectory: s.isDirectory(), mtimeMs: s.mtimeMs, size: s.size };
+  },
+  async realpath(path) {
+    return fsRealpath(path);
+  },
+  async writeFile(path, content) {
+    await fsMkdir(dirname(path), { recursive: true });
+    await writeFileAtomic(path, content);
+  },
+  async appendFile(path, content) {
+    await fsMkdir(dirname(path), { recursive: true });
+    await fsAppendFile(path, content);
+  },
+  async mkdir(path) {
+    await fsMkdir(path, { recursive: true });
+  },
+  async rm(path, opts) {
+    await fsRm(path, { recursive: opts?.recursive ?? true, force: true });
+  },
+  async rename(src, dst) {
+    await fsMkdir(dirname(dst), { recursive: true });
+    await fsRename(src, dst);
+  },
+  async copyFile(src, dst) {
+    await fsMkdir(dirname(dst), { recursive: true });
+    await fsCopyFile(src, dst);
+  },
+  async mkdtemp(prefix) {
+    return fsMkdtemp(prefix);
+  },
+  exec: execImpl,
+};
+
+/** Resolve the effective io for a helper: injected port or ambient default. */
+export function resolveIo(io?: WorkspaceIO): WorkspaceIO {
+  return io ?? ambientIo;
+}