@warpgogol/forge 4.1.6 → 4.2.1

package/dist/os/core/handlers/knowledge-compact.js

@@ -0,0 +1,204 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Command handler for forge.skill.knowledge.compact — wraps pure compaction functions in the kernel command contract (RFC-0662).</purpose>
+<non-goals>
+  <item>Do not implement planning logic — that lives in src/knowledge/compact.ts.</item>
+  <item>Do not import from @warpgogol/* — os/core may use dynamic imports but this handler stays forge-internal.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0662: initial knowledge compaction command handler.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { FORGE_SKILLS, discoverPackSkills } from "../../../src/registry.js";
+import { loadForgeConfig } from "../../../src/config/forge-config.js";
+import { resolveForgeRoot } from "../../../src/config/forge-config.js";
+import { planCompaction, executeCompaction, resolveRetentionDays, resolveStaleDays, } from "../../../src/knowledge/compact.js";
+import { parseKnowledgeFile } from "../../../src/knowledge/parse.js";
+function discoverSkillKnowledgeFiles(workspaceRoot, skillName, all) {
+    const result = [];
+    const config = loadForgeConfig(workspaceRoot);
+    // Resolve forge root
+    let forgeRoot;
+    try {
+        forgeRoot = resolveForgeRoot(workspaceRoot);
+    }
+    catch {
+        return result;
+    }
+    // Collect forge skills. skill.path is relative to forgeRoot and already
+    // includes the "skills/" prefix (see init.ts / skill-validate.ts).
+    for (const skill of FORGE_SKILLS) {
+        if (skillName && skill.name !== skillName)
+            continue;
+        if (!skill.knowledge || skill.knowledge.length === 0)
+            continue;
+        const skillDir = path.dirname(path.join(forgeRoot, skill.path));
+        const files = skill.knowledge
+            .map((f) => path.join(skillDir, f))
+            .filter((f) => {
+            try {
+                return fs.existsSync(f);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (files.length > 0) {
+            result.push({ skill: skill.name, files });
+        }
+    }
+    // Collect pack skills if --all or if --skill matches a pack skill
+    if (all || (skillName && !result.some((r) => r.skill === skillName))) {
+        let packSkills = [];
+        try {
+            packSkills = discoverPackSkills(workspaceRoot, config);
+        }
+        catch {
+            // Manifest missing or invalid — skip pack skills
+        }
+        for (const skill of packSkills) {
+            if (skillName && skill.name !== skillName)
+                continue;
+            if (!skill.knowledge || skill.knowledge.length === 0)
+                continue;
+            const packDir = path.resolve(workspaceRoot, skill.dir);
+            const skillDir = path.dirname(path.join(packDir, skill.path));
+            const files = skill.knowledge
+                .map((f) => path.join(skillDir, f))
+                .filter((f) => {
+                try {
+                    return fs.existsSync(f);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (files.length > 0) {
+                result.push({ skill: skill.name, files });
+            }
+        }
+    }
+    return result;
+}
+export async function runKnowledgeCompact(input, context) {
+    const { flags } = input;
+    const skillName = typeof flags["skill"] === "string" ? flags["skill"] : undefined;
+    // --all is consumed by the site-kernel CLI (consumeCommonFlags) before the
+    // command runs, so the command-level switch is --all-skills.
+    const all = flags["all-skills"] === true;
+    const dryRun = context.dryRun || flags["dry-run"] === true;
+    const json = flags["json"] === true;
+    // Validate exactly one of --skill / --all
+    if (!skillName && !all) {
+        return {
+            data: {
+                command: "forge.skill.knowledge.compact",
+                status: "fail",
+                dryRun,
+                files: [],
+                totals: { archived: 0, markedStale: 0, legacyFiles: 0 },
+                errors: ["Exactly one of --skill <name> or --all-skills is required."],
+            },
+            exitCode: 1,
+            summary: "Error: --skill or --all-skills is required.",
+        };
+    }
+    if (skillName && all) {
+        return {
+            data: {
+                command: "forge.skill.knowledge.compact",
+                status: "fail",
+                dryRun,
+                files: [],
+                totals: { archived: 0, markedStale: 0, legacyFiles: 0 },
+                errors: ["--skill and --all-skills are mutually exclusive."],
+            },
+            exitCode: 1,
+            summary: "Error: --skill and --all-skills are mutually exclusive.",
+        };
+    }
+    // Resolve retention and stale days
+    const flagRetention = typeof flags["retention-days"] === "string" ? Number(flags["retention-days"]) : undefined;
+    const flagStale = typeof flags["stale-days"] === "string" ? Number(flags["stale-days"]) : undefined;
+    const retentionDays = flagRetention !== undefined && flagRetention > 0 && Number.isInteger(flagRetention)
+        ? flagRetention
+        : resolveRetentionDays(context.workspaceRoot);
+    const staleDays = flagStale !== undefined && flagStale > 0 && Number.isInteger(flagStale)
+        ? flagStale
+        : resolveStaleDays(context.workspaceRoot);
+    // Discover target skills and their knowledge files
+    const skillFiles = discoverSkillKnowledgeFiles(context.workspaceRoot, skillName, all);
+    if (skillFiles.length === 0) {
+        const summary = skillName
+            ? `Skill "${skillName}" has no knowledge files to compact.`
+            : "No skills with knowledge files found.";
+        return {
+            data: {
+                command: "forge.skill.knowledge.compact",
+                status: "pass",
+                dryRun,
+                files: [],
+                totals: { archived: 0, markedStale: 0, legacyFiles: 0 },
+            },
+            exitCode: 0,
+            summary,
+        };
+    }
+    // Parse all knowledge files
+    const today = new Date().toISOString().slice(0, 10);
+    const allParsed = [];
+    const fileToSkill = new Map();
+    for (const { skill, files } of skillFiles) {
+        for (const file of files) {
+            const parsed = parseKnowledgeFile(file);
+            allParsed.push(parsed);
+            fileToSkill.set(file, skill);
+        }
+    }
+    // Plan compaction
+    const plans = planCompaction(allParsed, { retentionDays, staleDays, today });
+    // Execute compaction
+    const report = executeCompaction(plans, dryRun);
+    // Group by skill for output
+    const skillsOutput = skillFiles.map(({ skill, files }) => {
+        const skillFileResults = report.files.filter((r) => files.includes(r.file));
+        return {
+            skill,
+            files: skillFileResults.map((r) => ({
+                file: path.basename(r.file),
+                actions: r.actions,
+                legacySectionCount: r.legacySectionCount,
+            })),
+        };
+    });
+    const groupedReport = {
+        ...report,
+        skills: skillsOutput,
+    };
+    const exitCode = report.status === "pass" ? 0 : 1;
+    const summary = dryRun
+        ? `[dry-run] forge.skill.knowledge.compact: ${report.totals.archived} would archive, ${report.totals.markedStale} would mark stale, ${report.totals.legacyFiles} legacy file(s)`
+        : `forge.skill.knowledge.compact: ${report.totals.archived} archived, ${report.totals.markedStale} marked stale, ${report.totals.legacyFiles} legacy file(s)`;
+    if (context.outputFormat === "pretty" && !json) {
+        context.logger.section("Knowledge Compaction");
+        for (const skill of skillsOutput) {
+            context.logger.info(`Skill: ${skill.skill}`);
+            for (const file of skill.files) {
+                context.logger.info(`  ${file.file}: ${file.actions.length} action(s), ${file.legacySectionCount} legacy section(s)`);
+                for (const action of file.actions) {
+                    context.logger.info(`    ${action.kind}: ${action.entryId} — ${action.reason}`);
+                }
+            }
+        }
+        context.logger.info(`Totals: ${report.totals.archived} archived, ${report.totals.markedStale} marked stale, ${report.totals.legacyFiles} legacy file(s)`);
+    }
+    return {
+        data: groupedReport,
+        exitCode,
+        summary,
+    };
+}
+//# sourceMappingURL=knowledge-compact.js.map

package/dist/os/core/handlers/knowledge-compact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-compact.js","sourceRoot":"","sources":["../../../../os/core/handlers/knowledge-compact.ts"],"names":[],"mappings":"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"}

package/dist/os/core/handlers/package-health.d.ts

@@ -0,0 +1,17 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+export interface PackageHealthViolation {
+    ruleId: string;
+    packageName: string;
+    severity: "error" | "warning";
+    message: string;
+    file?: string;
+    fixHint?: string;
+}
+export interface PackageHealthResult {
+    command: "forge.package.health";
+    packagesChecked: number;
+    violations: PackageHealthViolation[];
+    passed: boolean;
+}
+export declare function runPackageHealth(_input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<PackageHealthResult>>;
+//# sourceMappingURL=package-health.d.ts.map

package/dist/os/core/handlers/package-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-health.d.ts","sourceRoot":"","sources":["../../../../os/core/handlers/package-health.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,sBAAsB,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;CACjB;AAiCD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,CAAC,CAsLlD"}

package/dist/os/core/handlers/package-health.js

@@ -0,0 +1,217 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.package.health — validate all published packages (private: false) for standalone extraction readiness. Checks engines.node, embedded CI workflow, extract.config.yaml, and devDependencies completeness (no hoisted tool deps).</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not modify files — read-only validation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial: forge.package.health validator — engines, CI workflow, extract config, devDeps completeness.</item>
+  <item>PKG-HEALTH-05: reject any versionBump in extract.config.yaml — version in package.json is source of truth.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs";
+import path from "node:path";
+const KNOWN_SCRIPT_TOOLS = {
+    eslint: "eslint",
+    prettier: "prettier",
+    vitest: "vitest",
+    tsc: "typescript",
+    tsx: "tsx",
+    turbo: "turbo",
+    biome: "@biomejs/biome",
+};
+function extractToolNames(scripts) {
+    const tools = new Set();
+    for (const scriptValue of Object.values(scripts)) {
+        for (const [toolName, depName] of Object.entries(KNOWN_SCRIPT_TOOLS)) {
+            if (scriptValue.includes(toolName) || scriptValue.includes(`pnpm exec ${toolName}`)) {
+                tools.add(depName);
+            }
+        }
+    }
+    return tools;
+}
+function readJsonFile(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function runPackageHealth(_input, context) {
+    const { workspaceRoot, logger } = context;
+    const packagesDir = path.join(workspaceRoot, "packages");
+    if (!fs.existsSync(packagesDir)) {
+        return {
+            data: {
+                command: "forge.package.health",
+                packagesChecked: 0,
+                violations: [],
+                passed: true,
+            },
+            exitCode: 0,
+            summary: "No packages/ directory found — nothing to check.",
+        };
+    }
+    const rootPkg = readJsonFile(path.join(workspaceRoot, "package.json"));
+    const rootEngines = rootPkg?.["engines"];
+    const rootNodeRange = rootEngines?.["node"];
+    const violations = [];
+    let packagesChecked = 0;
+    const entries = fs.readdirSync(packagesDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith("."))
+            continue;
+        const pkgDir = path.join(packagesDir, entry.name);
+        const pkgJsonPath = path.join(pkgDir, "package.json");
+        const pkg = readJsonFile(pkgJsonPath);
+        if (!pkg)
+            continue;
+        const isPrivate = pkg["private"] === true;
+        if (isPrivate)
+            continue;
+        packagesChecked++;
+        const packageName = String(pkg["name"] ?? entry.name);
+        // CHECK 1: engines.node exists and matches root
+        const pkgEngines = pkg["engines"];
+        const pkgNodeRange = pkgEngines?.["node"];
+        if (!pkgNodeRange) {
+            violations.push({
+                ruleId: "PKG-HEALTH-01",
+                packageName,
+                severity: "error",
+                message: `Missing engines.node in package.json. Root requires "${rootNodeRange ?? ">=24 <25"}".`,
+                file: pkgJsonPath,
+                fixHint: `Add "engines": { "node": "${rootNodeRange ?? ">=24 <25"}" } to package.json.`,
+            });
+        }
+        else if (rootNodeRange && pkgNodeRange !== rootNodeRange) {
+            violations.push({
+                ruleId: "PKG-HEALTH-01",
+                packageName,
+                severity: "warning",
+                message: `engines.node is "${pkgNodeRange}" but root is "${rootNodeRange}".`,
+                file: pkgJsonPath,
+                fixHint: `Align engines.node with root: "${rootNodeRange}".`,
+            });
+        }
+        // CHECK 2: .github/workflows/ci.yml exists inside package
+        const ciWorkflowPath = path.join(pkgDir, ".github", "workflows", "ci.yml");
+        if (!fs.existsSync(ciWorkflowPath)) {
+            violations.push({
+                ruleId: "PKG-HEALTH-02",
+                packageName,
+                severity: "error",
+                message: "Missing .github/workflows/ci.yml — standalone extraction repo will have no CI.",
+                file: pkgDir,
+                fixHint: "Create .github/workflows/ci.yml inside the package directory with Node 24 setup.",
+            });
+        }
+        // CHECK 3: extract.config.yaml exists
+        const extractConfigPath = path.join(pkgDir, "extract.config.yaml");
+        if (!fs.existsSync(extractConfigPath)) {
+            violations.push({
+                ruleId: "PKG-HEALTH-03",
+                packageName,
+                severity: "warning",
+                message: "Missing extract.config.yaml — package cannot be extracted via repo-extract.",
+                file: pkgDir,
+                fixHint: "Create extract.config.yaml with git remote and extraction settings.",
+            });
+        }
+        else {
+            // CHECK 3b: versionBump must be absent — version in package.json is source of truth
+            try {
+                const configRaw = fs.readFileSync(extractConfigPath, "utf8");
+                const versionBumpMatch = configRaw.match(/^versionBump:\s*(\S+)/m);
+                if (versionBumpMatch) {
+                    violations.push({
+                        ruleId: "PKG-HEALTH-05",
+                        packageName,
+                        severity: "error",
+                        message: `extract.config.yaml has versionBump: ${versionBumpMatch[1]} — this auto-increments the version on every extract. The version in package.json is the source of truth.`,
+                        file: extractConfigPath,
+                        fixHint: "Remove the versionBump line. Manually bump package.json version to the target before extracting.",
+                    });
+                }
+            }
+            catch {
+                // Read error — skip this check
+            }
+        }
+        // CHECK 4: devDependencies completeness — tools used in scripts must be declared
+        const scripts = (pkg["scripts"] ?? {});
+        const devDeps = (pkg["devDependencies"] ?? {});
+        const deps = (pkg["dependencies"] ?? {});
+        const allDeclared = { ...devDeps, ...deps };
+        const usedTools = extractToolNames(scripts);
+        for (const toolDep of usedTools) {
+            if (!(toolDep in allDeclared)) {
+                violations.push({
+                    ruleId: "PKG-HEALTH-04",
+                    packageName,
+                    severity: "error",
+                    message: `Script uses "${toolDep}" but it is not in devDependencies or dependencies. It relies on monorepo hoisting and will fail standalone.`,
+                    file: pkgJsonPath,
+                    fixHint: `Add "${toolDep}" to devDependencies in package.json.`,
+                });
+            }
+        }
+    }
+    const errors = violations.filter((v) => v.severity === "error");
+    const warnings = violations.filter((v) => v.severity === "warning");
+    const passed = errors.length === 0;
+    if (context.outputFormat === "pretty") {
+        if (packagesChecked === 0) {
+            logger.info("forge.package.health: no published packages found.");
+        }
+        else {
+            for (const v of violations) {
+                if (v.severity === "error") {
+                    logger.error(`  [${v.ruleId}] ${v.packageName}: ${v.message}`);
+                }
+                else {
+                    logger.warn(`  [${v.ruleId}] ${v.packageName}: ${v.message}`);
+                }
+            }
+            if (passed && warnings.length === 0) {
+                logger.success(`forge.package.health: all ${packagesChecked} published package(s) healthy.`);
+            }
+            else if (passed) {
+                logger.warn(`forge.package.health: ${packagesChecked} package(s) checked, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}.`);
+            }
+            else {
+                const parts = [];
+                parts.push(`${errors.length} error${errors.length === 1 ? "" : "s"}`);
+                if (warnings.length > 0)
+                    parts.push(`${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
+                logger.error(`forge.package.health: ${parts.join(", ")} across ${packagesChecked} package(s).`);
+            }
+        }
+    }
+    return {
+        data: {
+            command: "forge.package.health",
+            packagesChecked,
+            violations,
+            passed,
+        },
+        exitCode: passed ? 0 : 1,
+        summary: passed
+            ? warnings.length > 0
+                ? `All ${packagesChecked} package(s) passed with ${warnings.length} warning${warnings.length === 1 ? "" : "s"}.`
+                : `All ${packagesChecked} package(s) healthy.`
+            : `${errors.length} error${errors.length === 1 ? "" : "s"} found across ${packagesChecked} package(s).`,
+        nextSteps: errors.map((e) => ({
+            action: e.fixHint ?? e.message,
+            kind: "required",
+        })),
+    };
+}
+//# sourceMappingURL=package-health.js.map

package/dist/os/core/handlers/package-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-health.js","sourceRoot":"","sources":["../../../../os/core/handlers/package-health.ts"],"names":[],"mappings":"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"}

package/dist/os/core/handlers/pinned-check.d.ts

@@ -0,0 +1,49 @@
+import type { PinnedEntry, PinnedManifest, PinnedViolation } from "./pinned-types.ts";
+/**
+ * Path to the pinned manifest relative to the repository root.
+ */
+export declare const PINNED_MANIFEST_PATH: string;
+/**
+ * Error thrown when the manifest exists but is malformed (invalid YAML or missing required fields).
+ */
+export declare class PinnedManifestMalformedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load and parse the pinned manifest from .forge/pinned.yaml.
+ * Returns null if the file does not exist (protection is opt-in).
+ * Throws PinnedManifestMalformedError if the file exists but is not valid YAML
+ * or does not contain a `pinned` array.
+ */
+export declare function loadPinnedManifest(repoRoot: string): Promise<PinnedManifest | null>;
+/**
+ * Check if a relative file path matches a pinned entry.
+ *
+ * Path matching rules:
+ * - Exact match: if the entry path equals the file path, it matches.
+ * - Directory match: if the entry path ends with `/`, it matches any file
+ *   that starts with the directory prefix (recursive).
+ *
+ * Returns the matching PinnedEntry or null if no match.
+ */
+export declare function isPinned(manifest: PinnedManifest, relPath: string): PinnedEntry | null;
+/**
+ * Check if a move from sourceRel to destRel stays within the same pinned directory.
+ * This exempts intra-directory moves (e.g. rfc.archive moves
+ * docs/rfcs/rfc-0076.md → docs/rfcs/archive/implemented/rfc-0076.md)
+ * from the pinned pre-check, since the file hasn't left the protected directory.
+ *
+ * Only applies to directory-pinned entries (path ends with `/`).
+ * Returns true if the same pinned directory entry matches both source and dest.
+ */
+export declare function isIntraDirMove(manifest: PinnedManifest, sourceRel: string, destRel: string): boolean;
+/**
+ * Batch-check multiple file paths against the manifest.
+ * Returns violations for files that match a pinned entry.
+ * The operation type is determined by the caller (delete, move, or modify).
+ */
+export declare function checkFilesForPinned(manifest: PinnedManifest, files: Array<{
+    relPath: string;
+    operation: PinnedViolation["operation"];
+}>): PinnedViolation[];
+//# sourceMappingURL=pinned-check.d.ts.map

package/dist/os/core/handlers/pinned-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-check.d.ts","sourceRoot":"","sources":["../../../../os/core/handlers/pinned-check.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAc,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKlG;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAqC,CAAC;AAEvE;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkEzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAgBtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAiBT;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,eAAe,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,GACzE,eAAe,EAAE,CAgBnB"}