@warpgogol/forge 2.1.0 → 2.2.0

package/dist/src/types.d.ts

@@ -0,0 +1,152 @@
+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;
+}
+export interface ForgeFlagSpec {
+    kind: "boolean" | "string" | "string[]";
+    required?: boolean;
+    default?: ForgeFlagValue;
+    description: string;
+}
+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;
+    /**
+     * RFC-0518: declarative gate metadata. Optional. Structurally compatible
+     * with GateMetadata from @warpgogol/site-kernel. Does NOT affect execution.
+     */
+    gate?: GateMetadata;
+}
+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[];
+}
+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>;
+}
+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;
+    };
+}
+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;
+}
+export interface CommandRegistry {
+    listCommandNames(): string[];
+    listCommands(): ForgeRegisteredCommandInfo[];
+    getCommand(name: string): ForgeCommandDefinition | undefined;
+}
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,17 @@
+/*
+<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>
+*/
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE"}

package/dist/src/utils/fs-atomic.d.ts

@@ -0,0 +1,7 @@
+import { rename as fsRename } from "node:fs/promises";
+export interface WriteFileAtomicOptions {
+    retries?: number;
+}
+export declare function __setRenameImplForTests(impl: typeof fsRename | undefined): void;
+export declare function writeFileAtomic(filePath: string, content: string | Uint8Array, options?: WriteFileAtomicOptions): Promise<void>;
+//# sourceMappingURL=fs-atomic.d.ts.map

package/dist/src/utils/fs-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-atomic.d.ts","sourceRoot":"","sources":["../../../src/utils/fs-atomic.ts"],"names":[],"mappings":"AAcA,OAAO,EAAa,MAAM,IAAI,QAAQ,EAAU,MAAM,kBAAkB,CAAC;AAKzE,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,QAAQ,GAAG,SAAS,GAAG,IAAI,CAE/E;AAuBD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/src/utils/fs-atomic.js

@@ -0,0 +1,81 @@
+/*
+<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";
+let renameImpl = fsRename;
+export function __setRenameImplForTests(impl) {
+    renameImpl = impl ?? fsRename;
+}
+const DEFAULT_RETRIES = 10;
+const RETRY_BACKOFF_MS = 50;
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY"]);
+function isRetryableError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function makeTempPath(filePath) {
+    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, content, options) {
+    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).
+            }
+        }
+    }
+}
+//# sourceMappingURL=fs-atomic.js.map

package/dist/src/utils/fs-atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-atomic.js","sourceRoot":"","sources":["../../../src/utils/fs-atomic.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/fs-idempotent.d.ts

@@ -0,0 +1,2 @@
+export declare function writeFileIfChanged(filePath: string, content: string | Uint8Array): Promise<"written" | "unchanged">;
+//# sourceMappingURL=fs-idempotent.d.ts.map

package/dist/src/utils/fs-idempotent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-idempotent.d.ts","sourceRoot":"","sources":["../../../src/utils/fs-idempotent.ts"],"names":[],"mappings":"AAmBA,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC,CAkBlC"}

package/dist/src/utils/fs-idempotent.js

@@ -0,0 +1,39 @@
+/*
+<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.js";
+export async function writeFileIfChanged(filePath, content) {
+    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";
+}
+//# sourceMappingURL=fs-idempotent.js.map

package/dist/src/utils/fs-idempotent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-idempotent.js","sourceRoot":"","sources":["../../../src/utils/fs-idempotent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAA4B;IAE5B,IAAI,CAAC;QACH,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACzB,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC1C,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;IACD,MAAM,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,SAAS,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,2 @@
+export declare function trashSync(targetPath: string): void;
+//# sourceMappingURL=fs-trash-sync.d.ts.map

package/dist/src/utils/fs-trash-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trash-sync.d.ts","sourceRoot":"","sources":["../../../src/utils/fs-trash-sync.ts"],"names":[],"mappings":"AAkBA,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAkBlD"}

package/dist/src/utils/fs-trash-sync.js

@@ -0,0 +1,34 @@
+/*
+<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) {
+    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" });
+    }
+}
+//# sourceMappingURL=fs-trash-sync.js.map

package/dist/src/utils/fs-trash-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trash-sync.js","sourceRoot":"","sources":["../../../src/utils/fs-trash-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;EAaE;AAEF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO;IACpC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACjD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,YAAY,CAAC;QACxD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/C,YAAY,CACV,YAAY,EACZ;YACE,YAAY;YACZ,UAAU;YACV,4FAA4F,MAAM,KAAK,OAAO,4CAA4C;SAC3J,EACD,EAAE,KAAK,EAAE,MAAM,EAAE,CAClB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/src/utils/fs-trash.d.ts

@@ -0,0 +1,2 @@
+export declare function trashPath(targetPath: string): Promise<void>;
+//# sourceMappingURL=fs-trash.d.ts.map

package/dist/src/utils/fs-trash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trash.d.ts","sourceRoot":"","sources":["../../../src/utils/fs-trash.ts"],"names":[],"mappings":"AAoBA,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE"}

package/dist/src/utils/fs-trash.js

@@ -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) {
+    if (!existsSync(targetPath))
+        return;
+    await trash(targetPath, { glob: false });
+}
+//# sourceMappingURL=fs-trash.js.map

package/dist/src/utils/fs-trash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trash.js","sourceRoot":"","sources":["../../../src/utils/fs-trash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AAEF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAAkB;IAChD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO;IACpC,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/src/utils/fs.d.ts

@@ -0,0 +1,8 @@
+export interface CollectFilesOptions {
+    extensions?: string[];
+    ignore?: (name: string) => boolean;
+    withDirs?: boolean;
+}
+export declare function collectFiles(root: string, options?: CollectFilesOptions): Promise<string[]>;
+export declare function fileExists(path: string): Promise<boolean>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/src/utils/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/utils/fs.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAmCnB;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D"}

package/dist/src/utils/fs.js

@@ -0,0 +1,60 @@
+/*
+<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";
+function defaultIgnore(name) {
+    return name.startsWith("-") || name.startsWith("old-");
+}
+export async function collectFiles(root, options = {}) {
+    const { extensions, ignore = defaultIgnore, withDirs = false } = options;
+    const results = [];
+    // 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) {
+        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) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/src/utils/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../src/utils/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;EAWE;AAEF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,UAA+B,EAAE;IAEjC,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa,EAAE,QAAQ,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACzE,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,2EAA2E;IAC3E,yGAAyG;IACzG,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAEjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAEnC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,QAAQ;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjB,SAAS;YACX,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;gBAAE,SAAS;YAE9B,IAAI,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAAE,SAAS;YAEhF,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/src/utils/generated-marker.d.ts

@@ -0,0 +1,21 @@
+export declare const GENERATED_MARKER = "GENERATED. Do not change this line unless the file contains project specific changes.";
+export declare function hasGeneratedMarker(content: string): boolean;
+export interface StripGeneratedMarkerResult {
+    changed: boolean;
+    content: string;
+}
+export declare function stripGeneratedMarker(content: string): StripGeneratedMarkerResult;
+export interface GeneratedHeaderInput {
+    filePath: string;
+    ownerCommand: string;
+    templatePath?: string;
+    site?: string;
+    /**
+     * Command prefix for the regenerate hint. Defaults to "forge" (autonomous mode).
+     * Site-kernel callers pass "pnpm exec werkstatt run" for Warpgogol context.
+     */
+    commandPrefix?: string;
+}
+export declare function buildGeneratedHeader(input: GeneratedHeaderInput): string;
+export declare function isGeneratedMarkerTextCandidate(filePath: string): boolean;
+//# sourceMappingURL=generated-marker.d.ts.map

package/dist/src/utils/generated-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-marker.d.ts","sourceRoot":"","sources":["../../../src/utils/generated-marker.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,gBAAgB,0FAC4D,CAAC;AAE1F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,0BAA0B,CAmDhF;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CA4BxE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiBxE"}

package/dist/src/utils/generated-marker.js

@@ -0,0 +1,128 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical GENERATED_MARKER constant and advisory header builder for
+generated-file governance. Moved from @warpgogol/site-kernel to forge as canonical
+source (dependency inversion).</purpose>
+<non-goals>
+  <item>Do not perform file I/O — operates on in-memory content strings only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from @warpgogol/site-kernel/generated-marker to forge as canonical source.</item>
+  <item>Added optional commandPrefix to GeneratedHeaderInput — defaults to "forge" for autonomous mode; site-kernel passes "pnpm exec werkstatt run".</item>
+</CHANGE_SUMMARY>
+*/
+export const GENERATED_MARKER = "GENERATED. Do not change this line unless the file contains project specific changes.";
+export function hasGeneratedMarker(content) {
+    return content.includes(GENERATED_MARKER);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
+export function stripGeneratedMarker(content) {
+    const raw = GENERATED_MARKER;
+    let result = content;
+    let changed = false;
+    const applyAll = (patterns) => {
+        for (const pattern of patterns) {
+            const next = result.replace(pattern, "");
+            if (next !== result) {
+                changed = true;
+                result = next;
+            }
+        }
+    };
+    applyAll([
+        new RegExp(`<!--[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?-->\\n?`, "g"),
+        new RegExp(`/\\*[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?\\*/\\n?`, "g"),
+    ]);
+    for (const token of ["//", "#"]) {
+        const t = escapeRegex(token);
+        const advisoryLine = (suffix) => `(?:[ \\t]*${t}[ \\t]*${suffix}\\n)?`;
+        const pattern = new RegExp(`^[ \\t]*${t}[ \\t]*${escapeRegex(raw)}\\n` +
+            advisoryLine(escapeRegex(DO_NOT_EDIT_LINE)) +
+            advisoryLine("Owner command:.*") +
+            advisoryLine("Edit instead:.*") +
+            advisoryLine("Regenerate:.*"), "gm");
+        applyAll([pattern]);
+    }
+    applyAll([
+        new RegExp(`^\\s*<!--\\s*${escapeRegex(raw)}\\s*-->\\n?`, "gm"),
+        new RegExp(`^\\s*//\\s*${escapeRegex(raw)}\\n?`, "gm"),
+        new RegExp(`^\\s*/\\*\\s*${escapeRegex(raw)}\\s*\\*/\\n?`, "gm"),
+        new RegExp(`^\\s*#\\s*${escapeRegex(raw)}\\n?`, "gm"),
+        new RegExp(`^\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    ]);
+    if (result.includes(raw)) {
+        const next = result.split(raw).join("");
+        if (next !== result) {
+            changed = true;
+            result = next;
+        }
+    }
+    return { changed, content: result };
+}
+function commentStyleForPath(filePath) {
+    const lower = filePath.toLowerCase().replace(/\\/g, "/");
+    const base = lower.slice(lower.lastIndexOf("/") + 1);
+    if (base === ".gitattributes" ||
+        base === "_headers" ||
+        base === "_redirects" ||
+        base.endsWith(".txt") ||
+        base.endsWith(".yml") ||
+        base.endsWith(".yaml")) {
+        return "line-hash";
+    }
+    if (base.endsWith(".md"))
+        return "block-html";
+    if (base.endsWith(".css"))
+        return "block-css";
+    return "line-slash";
+}
+export function buildGeneratedHeader(input) {
+    const style = commentStyleForPath(input.filePath);
+    const prefix = input.commandPrefix ?? "forge";
+    const regenerateCommand = input.site
+        ? `${prefix} ${input.ownerCommand} --site ${input.site}`
+        : `${prefix} ${input.ownerCommand}`;
+    const editInstead = input.templatePath
+        ? `Edit instead: ${input.templatePath}`
+        : `Edit instead: the ${input.ownerCommand} generator source (not this file).`;
+    const lines = [
+        GENERATED_MARKER,
+        DO_NOT_EDIT_LINE,
+        `Owner command: ${input.ownerCommand}`,
+        editInstead,
+        `Regenerate:   ${regenerateCommand}`,
+    ];
+    switch (style) {
+        case "line-slash":
+            return `${lines.map((line) => `// ${line}`).join("\n")}\n`;
+        case "line-hash":
+            return `${lines.map((line) => `# ${line}`).join("\n")}\n`;
+        case "block-css":
+            return `/*\n${lines.map((line) => `  ${line}`).join("\n")}\n*/\n`;
+        case "block-html":
+            return `<!--\n${lines.map((line) => `  ${line}`).join("\n")}\n-->\n`;
+    }
+}
+export function isGeneratedMarkerTextCandidate(filePath) {
+    const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+    const TEXT_EXTS = new Set([
+        ".txt",
+        ".xml",
+        ".md",
+        ".yml",
+        ".yaml",
+        ".css",
+        ".js",
+        ".mjs",
+        ".ts",
+        ".json",
+        ".html",
+        ".astro",
+    ]);
+    return TEXT_EXTS.has(ext);
+}
+//# sourceMappingURL=generated-marker.js.map