@warpgogol/forge 5.2.4 → 5.3.0

package/dist/src/onboarding/skill-markers.js

@@ -0,0 +1,131 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1154: .forge-managed marker manifests for synced skill dirs and the
+stale-dir prune for forge upgrade. Every skill-sync site records the files it
+wrote into .agents/skills/<name>/ so a later upgrade can distinguish
+forge-owned leftover dirs from consumer-authored skills — ownership is proven
+by the marker, not inferred from the name.
+</purpose>
+<non-goals>
+  <item>Do not prune unmarked dirs — no marker means consumer-owned (pre-RFC-1154 syncs, hand-authored skills).</item>
+  <item>Do not delete dirs containing files outside the manifest — consumer additions keep the dir.</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>Marker is a per-dir JSON manifest ({ files: string[] }) — fail-safe: missing marker means no right to delete.</item>
+  <item>Prune only when on-disk contents ⊆ manifest files + marker; extras keep the dir and warn.</item>
+</KEY_DECISIONS>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial implementation — SKILL_MARKER_FILE, writeSkillMarker, pruneStaleSkillDirs.</item>
+</CHANGE_SUMMARY>
+*/
+import path from "node:path";
+import { resolveIo } from "../utils/io.js";
+import { writeFileIfChanged } from "../utils/fs-idempotent.js";
+import * as sfs from "../utils/sync-fs.js";
+/** Marker file name written into every forge-synced skill dir. */
+export const SKILL_MARKER_FILE = ".forge-managed";
+/** Canonical marker bytes — deterministic, sorted file list. */
+export function buildSkillMarkerContent(files) {
+    const manifest = { files: [...files].sort() };
+    return JSON.stringify(manifest) + "\n";
+}
+/** Write the .forge-managed manifest into a synced skill dir (async/io path). */
+export async function writeSkillMarker(skillDir, files, io) {
+    const fio = resolveIo(io);
+    await writeFileIfChanged(path.join(skillDir, SKILL_MARKER_FILE), buildSkillMarkerContent(files), fio);
+}
+/** Sync twin for runInit (sync call path — no WorkspaceIO). */
+export function writeSkillMarkerSync(skillDir, files) {
+    const markerPath = path.join(skillDir, SKILL_MARKER_FILE);
+    const next = buildSkillMarkerContent(files);
+    try {
+        if (sfs.readFileSync(markerPath, "utf8") === next)
+            return;
+    }
+    catch {
+        // Marker absent or unreadable — write below
+    }
+    sfs.writeFileSync(markerPath, next, "utf8");
+}
+function parseMarker(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            Array.isArray(parsed.files) &&
+            parsed.files.every((f) => typeof f === "string")) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Prune stale synced skill dirs under `agentsSkillsDir`: a dir is stale when it
+ * carries `.forge-managed` and its name is not in `currentSyncSet`. Deletion is
+ * allowed only when every file in the dir is listed in the manifest (or is the
+ * marker itself). Corrupt markers and dirs with extra files are kept and
+ * reported in `keptWithConsumerFiles`.
+ */
+export async function pruneStaleSkillDirs(agentsSkillsDir, currentSyncSet, io) {
+    const fio = resolveIo(io);
+    const result = { pruned: [], keptWithConsumerFiles: [] };
+    let entries;
+    try {
+        entries = await fio.readdir(agentsSkillsDir);
+    }
+    catch {
+        return result; // No skills dir — nothing to prune
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory)
+            continue;
+        const name = entry.name;
+        if (currentSyncSet.has(name))
+            continue;
+        const dir = path.join(agentsSkillsDir, name);
+        const markerPath = path.join(dir, SKILL_MARKER_FILE);
+        if (!(await fio.exists(markerPath)))
+            continue; // consumer-owned — never touch
+        let manifest = null;
+        try {
+            manifest = parseMarker(await fio.readFile(markerPath));
+        }
+        catch {
+            manifest = null;
+        }
+        if (!manifest) {
+            result.keptWithConsumerFiles.push(`${name} (corrupt marker)`);
+            continue;
+        }
+        const allowed = new Set([...manifest.files, SKILL_MARKER_FILE]);
+        const onDisk = await listFilesRecursive(dir, fio);
+        const extra = onDisk.filter((f) => !allowed.has(f));
+        if (extra.length > 0) {
+            result.keptWithConsumerFiles.push(`${name} (consumer files: ${extra.join(", ")})`);
+            continue;
+        }
+        await fio.rm(dir, { recursive: true });
+        result.pruned.push(name);
+    }
+    return result;
+}
+async function listFilesRecursive(dir, io, prefix = "") {
+    const out = [];
+    const entries = await io.readdir(dir);
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory) {
+            out.push(...(await listFilesRecursive(path.join(dir, entry.name), io, rel)));
+        }
+        else {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=skill-markers.js.map

package/dist/src/onboarding/skill-markers.js.map

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

package/dist/src/onboarding/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { type PrettierignoreResult } from "./prettierignore.ts";
 import type { SkippedSkill } from "./init.ts";
 import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
 export interface UpgradeResult {
@@ -12,6 +13,12 @@ export interface UpgradeResult {
     }[];
     skippedSkills: SkippedSkill[];
     nestedAgentsGenerated: string[];
+    /** RFC-1153: dry-run only — nested guides whose merged output differs from disk. */
+    nestedAgentsPlanned: string[];
+    /** RFC-1153: files merged with a carried custom tail below the boundary. */
+    nestedAgentsPreserved: string[];
+    /** RFC-1153: hand-written or unmapped files skipped by the merge. */
+    nestedAgentsSkipped: string[];
     memoryScaffold: {
         created: string[];
         gitignoreUpdated: boolean;
@@ -22,6 +29,9 @@ export interface UpgradeResult {
     latestNpmVersion: string | null;
     npmVersionWarning: string | null;
     doctorReport: unknown;
+    skillsPruned: string[];
+    skillsKeptWithConsumerFiles: string[];
+    prettierignore: PrettierignoreResult;
 }
 export declare function runUpgrade(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<UpgradeResult>>;
 //# sourceMappingURL=upgrade.d.ts.map

package/dist/src/onboarding/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/onboarding/upgrade.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAiB,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE7G,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpF,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,OAAO,CAAC;CACvB;AA+QD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAwQ5C"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/onboarding/upgrade.ts"],"names":[],"mappings":"AA8CA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAiB,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE7G,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,oFAAoF;IACpF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,4EAA4E;IAC5E,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,qEAAqE;IACrE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpF,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,OAAO,CAAC;IAEtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,cAAc,EAAE,oBAAoB,CAAC;CACtC;AAoYD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAoU5C"}