@warpgogol/forge 4.1.5 → 4.2.1

package/dist/os/core/handlers/pinned-check.js

@@ -0,0 +1,159 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared pre-check utility for the forge pinned-files protection system (RFC-0733).
+Loads the pinned manifest from .forge/pinned.yaml and provides an isPinned lookup
+that all archive handlers call before moving files. Manifest loading is cached
+per invocation — loadPinnedManifest is called once and the result is reused.</purpose>
+<non-goals>
+  <item>Does not implement validation logic (git diff parsing, violation detection) — use pinned-validate.ts.</item>
+  <item>Does not implement manifest creation — use pinned-init.ts.</item>
+  <item>Does not enforce overrides or audit logging — that is pinned-validate.ts responsibility.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned-check utility — loadPinnedManifest, isPinned, checkFilesForPinned.</item>
+  <item>Gap fix: add isIntraDirMove to exempt moves within the same pinned directory (e.g. rfc.archive moves docs/rfcs/x.md → docs/rfcs/archive/implemented/x.md).</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+const PINNED_DIR = ".forge";
+const PINNED_FILE = "pinned.yaml";
+/**
+ * Path to the pinned manifest relative to the repository root.
+ */
+export const PINNED_MANIFEST_PATH = path.join(PINNED_DIR, PINNED_FILE);
+/**
+ * Error thrown when the manifest exists but is malformed (invalid YAML or missing required fields).
+ */
+export class PinnedManifestMalformedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PinnedManifestMalformedError";
+    }
+}
+/**
+ * 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 async function loadPinnedManifest(repoRoot) {
+    const manifestPath = path.join(repoRoot, PINNED_MANIFEST_PATH);
+    let content;
+    try {
+        content = await fs.readFile(manifestPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(content);
+    }
+    catch (err) {
+        throw new PinnedManifestMalformedError(`pinned.yaml is not valid YAML: ${String(err.message)}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new PinnedManifestMalformedError("pinned.yaml must contain a top-level object with a `pinned` array");
+    }
+    const obj = parsed;
+    if (!Array.isArray(obj["pinned"])) {
+        throw new PinnedManifestMalformedError("pinned.yaml is missing required `pinned` array field");
+    }
+    const entries = [];
+    for (const raw of obj["pinned"]) {
+        if (!raw || typeof raw !== "object") {
+            throw new PinnedManifestMalformedError("pinned.yaml: each entry must be an object with path, mode, and reason");
+        }
+        const entry = raw;
+        const entryPath = entry["path"];
+        const entryMode = entry["mode"];
+        const entryReason = entry["reason"];
+        if (typeof entryPath !== "string" || !entryPath) {
+            throw new PinnedManifestMalformedError("pinned.yaml: each entry must have a non-empty `path` string");
+        }
+        if (entryMode !== "protect" && entryMode !== "freeze") {
+            throw new PinnedManifestMalformedError(`pinned.yaml: entry "${entryPath}" has invalid mode "${String(entryMode)}" — must be "protect" or "freeze"`);
+        }
+        if (typeof entryReason !== "string" || !entryReason) {
+            throw new PinnedManifestMalformedError(`pinned.yaml: entry "${entryPath}" must have a non-empty reason string`);
+        }
+        entries.push({
+            path: entryPath,
+            mode: entryMode,
+            reason: entryReason,
+        });
+    }
+    return { pinned: entries };
+}
+/**
+ * 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 function isPinned(manifest, relPath) {
+    const normalizedRelPath = relPath.replace(/\\/g, "/");
+    for (const entry of manifest.pinned) {
+        const normalizedEntryPath = entry.path.replace(/\\/g, "/");
+        if (normalizedEntryPath.endsWith("/")) {
+            if (normalizedRelPath.startsWith(normalizedEntryPath)) {
+                return entry;
+            }
+        }
+        else if (normalizedRelPath === normalizedEntryPath) {
+            return entry;
+        }
+    }
+    return 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 function isIntraDirMove(manifest, sourceRel, destRel) {
+    const normalizedSource = sourceRel.replace(/\\/g, "/");
+    const normalizedDest = destRel.replace(/\\/g, "/");
+    for (const entry of manifest.pinned) {
+        const normalizedEntryPath = entry.path.replace(/\\/g, "/");
+        if (normalizedEntryPath.endsWith("/")) {
+            if (normalizedSource.startsWith(normalizedEntryPath) &&
+                normalizedDest.startsWith(normalizedEntryPath)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 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 function checkFilesForPinned(manifest, files) {
+    const violations = [];
+    for (const { relPath, operation } of files) {
+        const entry = isPinned(manifest, relPath);
+        if (entry) {
+            violations.push({
+                path: relPath,
+                mode: entry.mode,
+                operation,
+                reason: entry.reason,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=pinned-check.js.map

package/dist/os/core/handlers/pinned-check.js.map

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

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

@@ -0,0 +1,19 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { PinnedEntry } from "./pinned-types.ts";
+/**
+ * Default pinned entries for a forge-consuming repository.
+ * These are re-added by pinned.init if missing from an existing manifest.
+ */
+export declare const DEFAULT_PINNED_ENTRIES: PinnedEntry[];
+export interface PinnedInitResult {
+    command: "pinned.init";
+    status: "ok";
+    manifestPath: string;
+    manifestAction: "created" | "merged" | "unchanged";
+    entriesCount: number;
+    hookAction: "created" | "updated" | "unchanged";
+    gitignoreAction: "created" | "updated" | "unchanged";
+    ciWorkflowAction: "created" | "unchanged" | "skipped";
+}
+export declare function runPinnedInit(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<PinnedInitResult>>;
+//# sourceMappingURL=pinned-init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-init.d.ts","sourceRoot":"","sources":["../../../../os/core/handlers/pinned-init.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC;AAKrE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,EAgG/C,CAAC;AAmHF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,IAAI,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAChD,eAAe,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACrD,gBAAgB,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;CACvD;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,CAyE/C"}

package/dist/os/core/handlers/pinned-init.js

@@ -0,0 +1,283 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge pinned.init — creates .forge/pinned.yaml with default foundation
+entries, installs pre-commit hook, adds audit log to .gitignore, and optionally
+generates CI workflow. Idempotent: re-running merges defaults with existing entries.</purpose>
+<non-goals>
+  <item>Does not validate the manifest — use pinned.validate.</item>
+  <item>Does not enforce protection on archive commands — that is pinned-check.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned.init handler with manifest creation, hook installation, gitignore update, and CI workflow generation.</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.js";
+import { PINNED_MANIFEST_PATH, loadPinnedManifest } from "./pinned-check.js";
+const PRE_COMMIT_HOOK_MARKER = "# forge:pinned-check";
+const AUDIT_LOG_REL_PATH = ".forge/pinned-audit.log";
+/**
+ * Default pinned entries for a forge-consuming repository.
+ * These are re-added by pinned.init if missing from an existing manifest.
+ */
+export const DEFAULT_PINNED_ENTRIES = [
+    {
+        path: ".forge/pinned.yaml",
+        mode: "freeze",
+        reason: "Self-protection — manifest must not be tampered with",
+    },
+    {
+        path: "docs/rfcs/rfc-0000-template.md",
+        mode: "freeze",
+        reason: "RFC template — required for rfc.create",
+    },
+    {
+        path: "docs/adrs/adr-0000-template.md",
+        mode: "freeze",
+        reason: "ADR template — required for adr.create",
+    },
+    {
+        path: "docs/audits/audit-0000-template.md",
+        mode: "freeze",
+        reason: "Audit template — required for audit creation",
+    },
+    {
+        path: "docs/plans/plan-0000-template.md",
+        mode: "freeze",
+        reason: "Plan template — required for plan creation",
+    },
+    {
+        path: "docs/architecture-dna.md",
+        mode: "freeze",
+        reason: "Architecture DNA invariants — foundational governance document",
+    },
+    {
+        path: "forge.yaml",
+        mode: "protect",
+        reason: "Forge configuration — required for all forge commands",
+    },
+    {
+        path: "package.json",
+        mode: "protect",
+        reason: "Root package.json — workspace manifest",
+    },
+    {
+        path: "pnpm-workspace.yaml",
+        mode: "protect",
+        reason: "Workspace definition",
+    },
+    {
+        path: "AGENTS.md",
+        mode: "protect",
+        reason: "Agent rules manifest",
+    },
+    {
+        path: "PREFERENCES.md",
+        mode: "protect",
+        reason: "Operator preferences",
+    },
+    {
+        path: "docs/rfcs/",
+        mode: "protect",
+        reason: "RFC directory — structural foundation",
+    },
+    {
+        path: "docs/adrs/",
+        mode: "protect",
+        reason: "ADR directory — structural foundation",
+    },
+    {
+        path: "docs/audits/",
+        mode: "protect",
+        reason: "Audit directory — structural foundation",
+    },
+    {
+        path: "docs/plans/",
+        mode: "protect",
+        reason: "Plan directory — structural foundation",
+    },
+    {
+        path: "docs/sessions/",
+        mode: "protect",
+        reason: "Session directory — structural foundation",
+    },
+    {
+        path: "docs/explorations/",
+        mode: "protect",
+        reason: "Exploration directory — structural foundation",
+    },
+    {
+        path: "docs/specs/",
+        mode: "protect",
+        reason: "Spec snapshots — immutable vendored content",
+    },
+    {
+        path: "missions/",
+        mode: "protect",
+        reason: "Missions directory — structural foundation",
+    },
+];
+const PRE_COMMIT_HOOK_SCRIPT = `#!/bin/sh
+${PRE_COMMIT_HOOK_MARKER}
+# Installed by forge pinned.init — do not remove this marker block.
+# Pinned-files protection: blocks commits that delete/move/modify pinned files.
+# To override: FORGE_PINNED_OVERRIDE=path1,path2 git commit
+forge pinned.validate || exit 1
+`;
+const CI_WORKFLOW_TEMPLATE = `name: pinned-files
+on: [push, pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - run: npm install -g @warpgogol/forge
+      - run: forge pinned.validate --mode ci --json
+`;
+/**
+ * Merge default entries with existing manifest entries.
+ * - Re-adds missing default entries (forge expects them).
+ * - Never overwrites or removes custom entries.
+ */
+function mergeManifest(existing, defaults) {
+    if (!existing) {
+        return { pinned: [...defaults] };
+    }
+    const existingPaths = new Set(existing.pinned.map((e) => e.path));
+    const merged = [...existing.pinned];
+    for (const def of defaults) {
+        if (!existingPaths.has(def.path)) {
+            merged.push(def);
+        }
+    }
+    return { pinned: merged };
+}
+/**
+ * Install or merge the pre-commit hook.
+ * If a hook exists, appends the forge check with a marker for idempotent re-installation.
+ */
+async function installPreCommitHook(repoRoot) {
+    const hookPath = path.join(repoRoot, ".git", "hooks", "pre-commit");
+    let existingContent;
+    try {
+        existingContent = await fs.readFile(hookPath, "utf8");
+    }
+    catch {
+        // No existing hook — create new
+        await fs.mkdir(path.dirname(hookPath), { recursive: true });
+        await writeFileIfChanged(hookPath, PRE_COMMIT_HOOK_SCRIPT);
+        await fs.chmod(hookPath, 0o755);
+        return "created";
+    }
+    // Check if forge hook is already present
+    if (existingContent.includes(PRE_COMMIT_HOOK_MARKER)) {
+        return "unchanged";
+    }
+    // Append forge hook to existing hook
+    const mergedContent = existingContent + "\n" + PRE_COMMIT_HOOK_SCRIPT;
+    await writeFileIfChanged(hookPath, mergedContent);
+    await fs.chmod(hookPath, 0o755);
+    return "updated";
+}
+/**
+ * Add .forge/pinned-audit.log to .gitignore (or append to existing).
+ */
+async function addToGitignore(repoRoot) {
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const entry = AUDIT_LOG_REL_PATH;
+    let existingContent;
+    try {
+        existingContent = await fs.readFile(gitignorePath, "utf8");
+    }
+    catch {
+        // No .gitignore — create new
+        await writeFileIfChanged(gitignorePath, entry + "\n");
+        return "created";
+    }
+    // Check if entry already exists
+    const lines = existingContent.split("\n");
+    if (lines.some((l) => l.trim() === entry)) {
+        return "unchanged";
+    }
+    // Append entry
+    const mergedContent = existingContent.trimEnd() + "\n" + entry + "\n";
+    await writeFileIfChanged(gitignorePath, mergedContent);
+    return "updated";
+}
+/**
+ * Generate CI workflow file.
+ */
+async function generateCiWorkflow(repoRoot) {
+    const workflowPath = path.join(repoRoot, ".github", "workflows", "pinned-check.yml");
+    await fs.mkdir(path.dirname(workflowPath), { recursive: true });
+    await writeFileIfChanged(workflowPath, CI_WORKFLOW_TEMPLATE);
+    return "created";
+}
+export async function runPinnedInit(input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const ci = input.flags["ci"] === true;
+    // Load existing manifest (if any)
+    let existingManifest = null;
+    try {
+        existingManifest = await loadPinnedManifest(workspaceRoot);
+    }
+    catch {
+        // Malformed manifest — will be overwritten with defaults
+        existingManifest = null;
+    }
+    // Merge with defaults
+    const merged = mergeManifest(existingManifest, DEFAULT_PINNED_ENTRIES);
+    // Determine action
+    const manifestAction = existingManifest === null
+        ? "created"
+        : merged.pinned.length > existingManifest.pinned.length
+            ? "merged"
+            : "unchanged";
+    // Write manifest
+    const manifestFullPath = path.join(workspaceRoot, PINNED_MANIFEST_PATH);
+    await fs.mkdir(path.dirname(manifestFullPath), { recursive: true });
+    const manifestContent = stringifyYaml(merged);
+    await writeFileIfChanged(manifestFullPath, manifestContent);
+    // Install pre-commit hook
+    const hookAction = await installPreCommitHook(workspaceRoot);
+    // Add to .gitignore
+    const gitignoreAction = await addToGitignore(workspaceRoot);
+    // Optional CI workflow
+    let ciWorkflowAction = "skipped";
+    if (ci) {
+        ciWorkflowAction = await generateCiWorkflow(workspaceRoot);
+    }
+    const result = {
+        command: "pinned.init",
+        status: "ok",
+        manifestPath: PINNED_MANIFEST_PATH,
+        manifestAction,
+        entriesCount: merged.pinned.length,
+        hookAction,
+        gitignoreAction,
+        ciWorkflowAction,
+    };
+    if (outputFormat === "pretty") {
+        logger.success(`pinned.init: manifest ${manifestAction} (${merged.pinned.length} entries), hook ${hookAction}, gitignore ${gitignoreAction}` +
+            (ci ? `, CI workflow ${ciWorkflowAction}` : ""));
+    }
+    return {
+        data: result,
+        summary: `Manifest ${manifestAction} with ${merged.pinned.length} entries, hook ${hookAction}, gitignore ${gitignoreAction}`,
+        nextSteps: [
+            {
+                action: "Commit .forge/pinned.yaml and .gitignore changes",
+                kind: "required",
+            },
+            ...(ci
+                ? [{ action: "Commit .github/workflows/pinned-check.yml", kind: "required" }]
+                : []),
+        ],
+    };
+}
+//# sourceMappingURL=pinned-init.js.map

package/dist/os/core/handlers/pinned-init.js.map

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

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

@@ -0,0 +1,29 @@
+export type PinnedMode = "protect" | "freeze";
+export type PinnedOperation = "delete" | "move" | "modify";
+export interface PinnedEntry {
+    path: string;
+    mode: PinnedMode;
+    reason: string;
+}
+export interface PinnedManifest {
+    pinned: PinnedEntry[];
+}
+export interface PinnedViolation {
+    path: string;
+    mode: PinnedMode;
+    operation: PinnedOperation;
+    reason: string;
+}
+export type PinnedValidateMode = "staged" | "ci";
+export interface PinnedValidateOptions {
+    allowPinnedOverride?: string[];
+    mode?: PinnedValidateMode;
+    json?: boolean;
+}
+export interface PinnedValidateResult {
+    command: "pinned.validate";
+    status: "pass" | "fail";
+    violations: PinnedViolation[];
+    overrides: string[];
+}
+//# sourceMappingURL=pinned-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-types.d.ts","sourceRoot":"","sources":["../../../../os/core/handlers/pinned-types.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,IAAI,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/dist/os/core/handlers/pinned-types.js

@@ -0,0 +1,16 @@
+/*
+<MODULE_CONTRACT>
+<purpose>TypeScript contracts for the forge pinned-files protection system (RFC-0733).
+Defines the manifest, entry, violation, and result types used by pinned.init,
+pinned.validate, and the shared pre-check utility.</purpose>
+<non-goals>
+  <item>Does not implement validation logic — use pinned-check.ts and pinned-validate.ts.</item>
+  <item>Does not implement manifest creation — use pinned-init.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0733: initial pinned-files type contracts — PinnedEntry, PinnedManifest, PinnedViolation, PinnedValidateOptions, PinnedValidateResult.</item>
+</CHANGE_SUMMARY>
+*/
+export {};
+//# sourceMappingURL=pinned-types.js.map

package/dist/os/core/handlers/pinned-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-types.js","sourceRoot":"","sources":["../../../../os/core/handlers/pinned-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;EAaE"}

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

@@ -0,0 +1,4 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+import type { PinnedValidateResult } from "./pinned-types.ts";
+export declare function runPinnedValidate(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<PinnedValidateResult>>;
+//# sourceMappingURL=pinned-validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-validate.d.ts","sourceRoot":"","sources":["../../../../os/core/handlers/pinned-validate.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,KAAK,EAGV,oBAAoB,EAErB,MAAM,mBAAmB,CAAC;AAkG3B,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,CAAC,CAmKnD"}