vouchington-tooling 0.0.15 → 0.0.17

package/dist/dockerfile-parse/stages.mjs

@@ -0,0 +1,18 @@
+import { Cmd, Copy, From, Run } from 'dockerfile-ast';
+export function collectStages(parser) {
+    const stages = [];
+    let currentStage;
+    for (const instruction of parser.getInstructions()) {
+        if (instruction instanceof From) {
+            const stage = instruction.getBuildStage() ?? String(stages.length);
+            currentStage = { stage, instructions: [instruction] };
+            stages.push(currentStage);
+            continue;
+        }
+        if (currentStage &&
+            (instruction instanceof Copy || instruction instanceof Cmd || instruction instanceof Run)) {
+            currentStage.instructions.push(instruction);
+        }
+    }
+    return stages;
+}

package/dist/gha-pr-checkpoint/index.d.mts

@@ -0,0 +1,58 @@
+export declare const CHECKPOINT_MARKER = "pr-checkpoint:v1";
+export type CheckpointStatus = 'queued' | 'running' | 'awaiting_verification' | 'failed' | 'deadline' | 'unresumable' | 'complete';
+export type Checkpoint = {
+    marker: string;
+    repository: string;
+    pr: number;
+    /** Absent on checkpoints posted before trigger ids were recorded; keep optional so resume can still parse them. */
+    triggerCommentId?: number;
+    headRef: string;
+    startSha: string;
+    sessionStartSha: string;
+    runId: string;
+    runUrl: string;
+    actor: string;
+    sessionId: string;
+    /** Absent from v1 checkpoints created before session URLs were exposed. */
+    sessionUrl?: string;
+    resumeSourceRunId: string;
+    status: CheckpointStatus;
+    createdAt: string;
+    updatedAt: string;
+};
+export type GitHubComment = {
+    id: number;
+    user?: {
+        login?: string;
+        type?: string;
+    };
+    performed_via_github_app?: {
+        slug?: string;
+    } | null;
+    body?: string;
+    created_at?: string;
+};
+export interface CheckpointCodecOptions {
+    marker?: string;
+    sessionIdPattern?: RegExp;
+}
+export interface TrustedCheckpointActor {
+    actor: string;
+    userType?: string;
+    appSlug?: string;
+}
+/**
+ * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
+ * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
+ * authored by the expected App identity.
+ */
+export declare function isTrustedCheckpointComment(comment: GitHubComment, context: TrustedCheckpointActor): boolean;
+export declare function renderCheckpoint(checkpoint: Checkpoint, options?: {
+    marker?: string;
+}): string;
+export declare function parseCheckpoint(body: string, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function validateCheckpoint(value: unknown, options?: CheckpointCodecOptions): Checkpoint | undefined;
+export declare function sortedCheckpointCandidates(comments: GitHubComment[], options?: CheckpointCodecOptions): {
+    comment: GitHubComment;
+    checkpoint: Checkpoint;
+}[];

package/dist/gha-pr-checkpoint/index.mjs

@@ -0,0 +1,100 @@
+export const CHECKPOINT_MARKER = 'pr-checkpoint:v1';
+/**
+ * Anti-forgery predicate: a checkpoint HTML comment is plain text any PR commenter can paste,
+ * so `parseCheckpoint` alone proves shape, not provenance. This proves the comment itself was
+ * authored by the expected App identity.
+ */
+export function isTrustedCheckpointComment(comment, context) {
+    return (comment.user?.login === context.actor &&
+        comment.user?.type === (context.userType ?? 'Bot') &&
+        comment.performed_via_github_app?.slug === (context.appSlug ?? 'github-actions'));
+}
+export function renderCheckpoint(checkpoint, options = {}) {
+    const marker = options.marker ?? checkpoint.marker;
+    const payload = Buffer.from(JSON.stringify({ ...checkpoint, marker }), 'utf8').toString('base64url');
+    const session = checkpoint.sessionUrl
+        ? `[${checkpoint.sessionId}](${checkpoint.sessionUrl})`
+        : `\`${checkpoint.sessionId || 'pending'}\``;
+    return [
+        `👀 [View the automation workflow run](${checkpoint.runUrl}).`,
+        '',
+        `Status: \`${checkpoint.status}\` · Session: ${session}`,
+        '',
+        `<!-- ${marker} ${payload} -->`,
+    ].join('\n');
+}
+export function parseCheckpoint(body, options = {}) {
+    const marker = options.marker ?? CHECKPOINT_MARKER;
+    const match = body.match(new RegExp(`<!-- ${escapeRegExp(marker)} ([A-Za-z0-9_-]+) -->`, 'u'));
+    if (!match?.[1])
+        return undefined;
+    try {
+        return validateCheckpoint(JSON.parse(Buffer.from(match[1], 'base64url').toString('utf8')), options);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function validateCheckpoint(value, options = {}) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const checkpoint = value;
+    const marker = options.marker ?? CHECKPOINT_MARKER;
+    if (checkpoint.marker !== marker ||
+        !Number.isInteger(checkpoint.pr) ||
+        (checkpoint.triggerCommentId !== undefined && !Number.isInteger(checkpoint.triggerCommentId)) ||
+        typeof checkpoint.startSha !== 'string' ||
+        !/^[0-9a-f]{40}$/u.test(checkpoint.startSha) ||
+        typeof checkpoint.sessionStartSha !== 'string' ||
+        !/^[0-9a-f]{40}$/u.test(checkpoint.sessionStartSha) ||
+        typeof checkpoint.runId !== 'string' ||
+        !/^[0-9]+$/u.test(checkpoint.runId) ||
+        typeof checkpoint.resumeSourceRunId !== 'string' ||
+        (checkpoint.resumeSourceRunId !== '' && !/^[0-9]+$/u.test(checkpoint.resumeSourceRunId)) ||
+        typeof checkpoint.repository !== 'string' ||
+        typeof checkpoint.headRef !== 'string' ||
+        typeof checkpoint.runUrl !== 'string' ||
+        typeof checkpoint.actor !== 'string' ||
+        typeof checkpoint.sessionId !== 'string' ||
+        typeof checkpoint.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(checkpoint.createdAt)) ||
+        typeof checkpoint.updatedAt !== 'string' ||
+        !Number.isFinite(Date.parse(checkpoint.updatedAt)) ||
+        typeof checkpoint.status !== 'string' ||
+        ![
+            'queued',
+            'running',
+            'awaiting_verification',
+            'failed',
+            'deadline',
+            'unresumable',
+            'complete',
+        ].includes(checkpoint.status)) {
+        return undefined;
+    }
+    if (checkpoint.sessionId &&
+        options.sessionIdPattern &&
+        !matchesPattern(options.sessionIdPattern, checkpoint.sessionId)) {
+        return undefined;
+    }
+    if (checkpoint.sessionUrl !== undefined &&
+        (!URL.canParse(checkpoint.sessionUrl) || !checkpoint.sessionUrl.startsWith('https:'))) {
+        return undefined;
+    }
+    return checkpoint;
+}
+export function sortedCheckpointCandidates(comments, options = {}) {
+    return comments
+        .map((comment) => ({ comment, checkpoint: parseCheckpoint(comment.body ?? '', options) }))
+        .filter((candidate) => candidate.checkpoint !== undefined)
+        .toSorted((left, right) => {
+        const timestampOrder = String(right.comment.created_at ?? '').localeCompare(String(left.comment.created_at ?? ''));
+        return timestampOrder || right.comment.id - left.comment.id;
+    });
+}
+function matchesPattern(pattern, value) {
+    return new RegExp(pattern.source, pattern.flags.replaceAll(/[gy]/g, '')).test(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/gha-rate-limit/index.d.mts

@@ -0,0 +1,15 @@
+export declare const MAX_RATE_LIMIT_WAIT_MS = 120000;
+export declare class GitHubRateLimitError extends Error {
+    readonly code: string;
+    readonly httpStatus?: number | undefined;
+    readonly retryAfter?: string | undefined;
+    readonly rateLimitRemaining?: string | undefined;
+    readonly rateLimitReset?: string | undefined;
+    constructor(code: string, message: string, httpStatus?: number, retryAfter?: string, rateLimitRemaining?: string, rateLimitReset?: string);
+}
+export declare function isRetryableCancellationError(error: unknown): boolean;
+export declare function rateLimitDelay(error: GitHubRateLimitError): number;
+export declare function isRateLimited(error: unknown): error is GitHubRateLimitError;
+export declare function reserveRateLimitDelay(used: {
+    milliseconds: number;
+}, delay: number): void;

package/dist/gha-rate-limit/index.mjs

@@ -0,0 +1,69 @@
+const MAX_DELAY_MS = 60_000;
+export const MAX_RATE_LIMIT_WAIT_MS = 120_000;
+export class GitHubRateLimitError extends Error {
+    code;
+    httpStatus;
+    retryAfter;
+    rateLimitRemaining;
+    rateLimitReset;
+    constructor(code, message, httpStatus, retryAfter, rateLimitRemaining, rateLimitReset) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.retryAfter = retryAfter;
+        this.rateLimitRemaining = rateLimitRemaining;
+        this.rateLimitReset = rateLimitReset;
+        this.name = 'GitHubRateLimitError';
+    }
+}
+function invalid() {
+    throw new GitHubRateLimitError('INVALID_RESPONSE', 'GitHub rate-limit response is invalid');
+}
+function rateLimit403(error) {
+    return (error.httpStatus === 403 && (error.retryAfter !== undefined || error.rateLimitRemaining === '0'));
+}
+export function isRetryableCancellationError(error) {
+    return (error instanceof GitHubRateLimitError &&
+        (error.code === 'REQUEST_FAILED' ||
+            (error.code === 'HTTP_STATUS' &&
+                (error.httpStatus === 429 ||
+                    rateLimit403(error) ||
+                    ((error.httpStatus ?? 0) >= 500 && (error.httpStatus ?? 0) <= 599)))));
+}
+export function rateLimitDelay(error) {
+    if (error.retryAfter !== undefined) {
+        if (!/^\d+$/u.test(error.retryAfter))
+            invalid();
+        const milliseconds = Number(error.retryAfter) * 1000;
+        if (!Number.isSafeInteger(milliseconds) || milliseconds > MAX_DELAY_MS)
+            invalid();
+        return milliseconds;
+    }
+    if (error.rateLimitRemaining !== undefined && !/^\d+$/u.test(error.rateLimitRemaining))
+        invalid();
+    if (error.rateLimitRemaining !== '0') {
+        if (error.httpStatus !== 429)
+            invalid();
+        return MAX_DELAY_MS;
+    }
+    if (!error.rateLimitReset || !/^\d+$/u.test(error.rateLimitReset))
+        invalid();
+    const reset = Number(error.rateLimitReset);
+    if (!Number.isSafeInteger(reset))
+        invalid();
+    const milliseconds = Math.max(0, reset * 1000 - Date.now());
+    if (milliseconds > MAX_DELAY_MS)
+        invalid();
+    return milliseconds;
+}
+export function isRateLimited(error) {
+    return (error instanceof GitHubRateLimitError &&
+        error.code === 'HTTP_STATUS' &&
+        (error.httpStatus === 429 || rateLimit403(error)));
+}
+export function reserveRateLimitDelay(used, delay) {
+    if (used.milliseconds + delay > MAX_RATE_LIMIT_WAIT_MS) {
+        throw new GitHubRateLimitError('RATE_LIMIT_WAIT_EXHAUSTED', 'GitHub rate-limit wait budget is exhausted');
+    }
+    used.milliseconds += delay;
+}

package/dist/index.d.mts

@@ -36,3 +36,21 @@ export type { CommentableIndex, CommentableLine, LineKind, PayloadRequirement, R
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mts';
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mts';
 export type { ExpectedTransportIdentity, ObjectSigner, PresignIdentity, TransportControl, } from './coverage-transport/index.mts';
+export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, restoreDeployedWorkspacePackages, } from './pnpm-deploy/index.mts';
+export type { NormalizeDeployedLayerResult, PruneResult, RestoreWorkspacePackagesOptions, } from './pnpm-deploy/index.mts';
+export { parseDockerfilePrewarmStages, parseDockerfileRuntimeImages, } from './dockerfile-parse/index.mts';
+export type { DockerfilePrewarmStage, DockerfileRuntimeImage, ParseDockerfilePrewarmOptions, ParseDockerfileRuntimeImagesOptions, } from './dockerfile-parse/index.mts';
+export { buildSccArgs, checkSccComplexity, parseSccComplexityViolations, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mts';
+export type { SccComplexityOptions, SccComplexityViolation } from './scc-complexity/index.mts';
+export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-local/index.mts';
+export type { CiLocalCommand, CiLocalSpawn, CiLocalSpawnOptions, CiLocalSpawnResult, CiLocalTarget, RunCiLocalOptions, } from './ci-local/index.mts';
+export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mts';
+export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mts';
+export type { Checkpoint, CheckpointCodecOptions, GitHubComment, } from './gha-pr-checkpoint/index.mts';
+export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mts';
+export type { WorkspaceGatesOptions } from './workspace-gates/index.mts';
+export { validateNugetUpdate } from './nuget-central-version/index.mts';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mts';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mts';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mts';
+export type { ResolvedDocument, ResolvedPin, ValidateResolvedPinDeltaOptions, } from './swift-resolved-pin-delta/index.mts';

package/dist/index.mjs

@@ -21,3 +21,14 @@ export { parseAstGrepRuleArgs, runAstGrepRule } from './ast-grep-rule/index.mjs'
 export { bodyOnlyReviewFallback, indexReviewFiles, MAX_REVIEW_COMMENTS, MAX_REVIEW_PAYLOAD_BYTES, nearestReviewLine, parsePatchCommentable, parseReviewFilesJson, parseReviewPayload, readRegularReviewPayload, remapReviewComments, ReviewPayloadError, reviewCommentSubject, rewriteSnappedSuggestion, snapReviewNote, stageReviewPayload, writeStagedOutput, } from './gha-review-payload/index.mjs';
 export { nextPageCursorFromLinkHeader, nextPageUrlFromLinkHeader, validatePaginationRequestUrl, } from './http-link-pagination/index.mjs';
 export { cmdDownloadCoverage, cmdDownloadVitestBlobs, cmdUpload, mintPresignedControl, transportObjectKeys, } from './coverage-transport/index.mjs';
+export { EPOCH_PRUNED_AT, normalizeDeployedLayer, pruneDeployedRuntimeDeps, restoreDeployedWorkspacePackages, } from './pnpm-deploy/index.mjs';
+export { parseDockerfilePrewarmStages, parseDockerfileRuntimeImages, } from './dockerfile-parse/index.mjs';
+export { buildSccArgs, checkSccComplexity, parseSccComplexityViolations, SCC_COMPLEXITY_LIMIT, } from './scc-complexity/index.mjs';
+export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-local/index.mjs';
+export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mjs';
+export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mjs';
+export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mjs';
+export { validateNugetUpdate } from './nuget-central-version/index.mjs';
+export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
+export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';
+export { validateResolvedPinDelta } from './swift-resolved-pin-delta/index.mjs';

package/dist/nuget-central-version/cli.d.mts

@@ -0,0 +1 @@
+export declare function runNugetCentralVersionCli(args: readonly string[]): void;

package/dist/nuget-central-version/cli.mjs

@@ -0,0 +1,11 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { validateNugetUpdate } from './index.mjs';
+export function runNugetCentralVersionCli(args) {
+    const [trustedPath, candidatePath, metadataPath, outputPath] = args;
+    if (!trustedPath || !candidatePath || !metadataPath || !outputPath || args.length !== 4) {
+        throw new Error('Usage: vouchington nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>');
+    }
+    const candidateSource = readFileSync(candidatePath, 'utf8');
+    validateNugetUpdate(readFileSync(trustedPath, 'utf8'), candidateSource, readFileSync(metadataPath, 'utf8'));
+    writeFileSync(outputPath, candidateSource);
+}

package/dist/nuget-central-version/index.d.mts

@@ -0,0 +1 @@
+export declare function validateNugetUpdate(trustedSource: string, candidateSource: string, metadataSource: string): string[];

package/dist/nuget-central-version/index.mjs

@@ -0,0 +1,74 @@
+const packageVersionPattern = /<PackageVersion\s+Include="(?<name>[^"]+)"\s+Version="(?<version>[^"]+)"\s*\/>/g;
+const literalNugetVersionPattern = /^\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+function parseVersions(source) {
+    const versions = new Map();
+    for (const match of source.matchAll(packageVersionPattern)) {
+        const name = match.groups?.name;
+        const version = match.groups?.version;
+        if (!name || !version || versions.has(name)) {
+            throw new Error('Directory.Packages.props must contain unique PackageVersion entries');
+        }
+        versions.set(name, { literal: match[0], version });
+    }
+    if (versions.size === 0)
+        throw new Error('Directory.Packages.props has no PackageVersion entries');
+    return versions;
+}
+export function validateNugetUpdate(trustedSource, candidateSource, metadataSource) {
+    const trusted = parseVersions(trustedSource);
+    const candidate = parseVersions(candidateSource);
+    if (candidate.size !== trusted.size) {
+        throw new Error('Dependabot may not add or remove central package declarations');
+    }
+    const changed = [];
+    let expected = trustedSource;
+    for (const [name, trustedEntry] of trusted) {
+        const candidateEntry = candidate.get(name);
+        if (!candidateEntry)
+            throw new Error(`Dependabot removed central package ${name}`);
+        if (candidateEntry.version === trustedEntry.version)
+            continue;
+        if (!literalNugetVersionPattern.test(trustedEntry.version)) {
+            throw new Error(`Dependabot may not change MSBuild-managed version for ${name}`);
+        }
+        if (!literalNugetVersionPattern.test(candidateEntry.version)) {
+            throw new Error(`Dependabot proposed a non-literal NuGet version for ${name}`);
+        }
+        changed.push(name);
+        expected = expected.replace(trustedEntry.literal, trustedEntry.literal.replace(`Version="${trustedEntry.version}"`, `Version="${candidateEntry.version}"`));
+    }
+    if (changed.length === 0)
+        throw new Error('Dependabot NuGet update changed no package versions');
+    if (candidateSource !== expected) {
+        throw new Error('Dependabot may change only literal central PackageVersion values');
+    }
+    const metadata = JSON.parse(metadataSource);
+    if (!Array.isArray(metadata))
+        throw new Error('Dependabot NuGet metadata must be an array');
+    const metadataByName = new Map();
+    for (const update of metadata) {
+        const name = update.dependencyName?.toLowerCase();
+        if (!name || !update.prevVersion || !update.newVersion || metadataByName.has(name)) {
+            throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+        }
+        metadataByName.set(name, update);
+    }
+    const metadataNames = [...metadataByName.keys()].toSorted();
+    const changedNames = changed.map((name) => name.toLowerCase()).toSorted();
+    if (metadataNames.length !== changedNames.length ||
+        new Set(metadataNames).size !== metadataNames.length) {
+        throw new Error('Dependabot NuGet metadata must identify every changed package exactly once');
+    }
+    if (!metadataNames.every((name, index) => name === changedNames[index])) {
+        throw new Error('Dependabot NuGet metadata does not match the changed central packages');
+    }
+    for (const name of changed) {
+        const update = metadataByName.get(name.toLowerCase());
+        const trustedVersion = trusted.get(name)?.version;
+        const candidateVersion = candidate.get(name)?.version;
+        if (update?.prevVersion !== trustedVersion || update?.newVersion !== candidateVersion) {
+            throw new Error(`Dependabot NuGet metadata versions do not match ${name}`);
+        }
+    }
+    return changed.toSorted();
+}

package/dist/pnpm-deploy/index.d.mts

@@ -0,0 +1,6 @@
+export { pruneDeployedRuntimeDeps, runPruneDeployedRuntimeDepsCli } from './prune.mts';
+export type { PruneResult } from './prune.mts';
+export { EPOCH_PRUNED_AT, normalizeDeployedLayer, runNormalizeDeployedLayerCli, } from './normalize.mts';
+export type { NormalizeDeployedLayerResult } from './normalize.mts';
+export { restoreDeployedWorkspacePackages, runRestoreDeployedWorkspacePackagesCli, } from './restore.mts';
+export type { RestoreWorkspacePackagesOptions } from './restore.mts';

package/dist/pnpm-deploy/index.mjs

@@ -0,0 +1,3 @@
+export { pruneDeployedRuntimeDeps, runPruneDeployedRuntimeDepsCli } from './prune.mjs';
+export { EPOCH_PRUNED_AT, normalizeDeployedLayer, runNormalizeDeployedLayerCli, } from './normalize.mjs';
+export { restoreDeployedWorkspacePackages, runRestoreDeployedWorkspacePackagesCli, } from './restore.mjs';

package/dist/pnpm-deploy/normalize.d.mts

@@ -0,0 +1,15 @@
+export declare const EPOCH_PRUNED_AT = "Thu, 01 Jan 1970 00:00:00 GMT";
+export interface NormalizeDeployedLayerResult {
+    prunedAtPinned: boolean;
+    entriesTouched: number;
+}
+export declare function normalizeDeployedLayer(prodDir: string): NormalizeDeployedLayerResult;
+interface NormalizeCliOptions {
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+    isMain: boolean;
+    normalize?: typeof normalizeDeployedLayer;
+    stdout: (message: string) => void;
+}
+export declare function runNormalizeDeployedLayerCli({ args, env, isMain, normalize, stdout, }: NormalizeCliOptions): void;
+export {};

package/dist/pnpm-deploy/normalize.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const EPOCH_PRUNED_AT = 'Thu, 01 Jan 1970 00:00:00 GMT';
+export function normalizeDeployedLayer(prodDir) {
+    return {
+        prunedAtPinned: pinPrunedAt(prodDir),
+        entriesTouched: clampTreeMtimes(prodDir),
+    };
+}
+function pinPrunedAt(prodDir) {
+    const modulesPath = path.join(prodDir, 'node_modules', '.modules.yaml');
+    if (!fs.existsSync(modulesPath)) {
+        throw new Error(`${modulesPath} is missing; expected pnpm deploy to write it`);
+    }
+    // pnpm 11.13.1 writeModulesManifest serializes this file with JSON.stringify
+    // despite the .yaml name. A pnpm bump that switches to YAML must update this parse.
+    const parsed = JSON.parse(fs.readFileSync(modulesPath, 'utf8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${modulesPath} is not a JSON object`);
+    }
+    const manifest = parsed;
+    manifest.prunedAt = EPOCH_PRUNED_AT;
+    fs.writeFileSync(modulesPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return true;
+}
+function clampTreeMtimes(root) {
+    let entriesTouched = 0;
+    function visit(entryPath, isDirectory) {
+        if (isDirectory) {
+            for (const entry of fs.readdirSync(entryPath, { withFileTypes: true })) {
+                visit(path.join(entryPath, entry.name), entry.isDirectory());
+            }
+        }
+        else {
+            const stats = fs.lstatSync(entryPath);
+            if (stats.isFile() && stats.nlink > 1) {
+                const copyPath = `${entryPath}.${process.pid}.copy`;
+                fs.copyFileSync(entryPath, copyPath);
+                fs.renameSync(copyPath, entryPath);
+            }
+        }
+        fs.lutimesSync(entryPath, 0, 0);
+        entriesTouched += 1;
+    }
+    visit(root, fs.lstatSync(root).isDirectory());
+    return entriesTouched;
+}
+function resolveCliProdDirs(args, env) {
+    if (args.length > 0)
+        return [...args];
+    const prodDir = env.PROD_DIR;
+    if (!prodDir)
+        throw new Error('PROD_DIR or a directory argument is required');
+    return [prodDir];
+}
+export function runNormalizeDeployedLayerCli({ args, env, isMain, normalize = normalizeDeployedLayer, stdout, }) {
+    if (!isMain)
+        return;
+    for (const prodDir of resolveCliProdDirs(args, env)) {
+        const result = normalize(prodDir);
+        const prunedAt = result.prunedAtPinned ? 'prunedAt pinned' : 'prunedAt absent';
+        stdout(`Normalized deployed layer at ${prodDir} (${prunedAt}, ${result.entriesTouched} entries)`);
+    }
+}

package/dist/pnpm-deploy/prune.d.mts

@@ -0,0 +1,14 @@
+export interface PruneResult {
+    bytesRemoved: number;
+    filesRemoved: number;
+}
+export declare function pruneDeployedRuntimeDeps(prodDir: string): PruneResult;
+interface PruneCliOptions {
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+    isMain: boolean;
+    prune?: typeof pruneDeployedRuntimeDeps;
+    stdout: (message: string) => void;
+}
+export declare function runPruneDeployedRuntimeDepsCli({ args, env, isMain, prune, stdout, }: PruneCliOptions): void;
+export {};

package/dist/pnpm-deploy/prune.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DECLARATION_SUFFIXES = ['.d.ts', '.d.mts', '.d.cts', '.d.ts.map', '.d.mts.map', '.d.cts.map'];
+function shouldPruneRuntimeDependencyFile(filePath) {
+    return (DECLARATION_SUFFIXES.some((suffix) => filePath.endsWith(suffix)) ||
+        filePath.endsWith('.tsbuildinfo'));
+}
+function pruneDirectory(dir) {
+    const result = { bytesRemoved: 0, filesRemoved: 0 };
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const child = pruneDirectory(entryPath);
+            result.bytesRemoved += child.bytesRemoved;
+            result.filesRemoved += child.filesRemoved;
+            continue;
+        }
+        if (!entry.isFile() || !shouldPruneRuntimeDependencyFile(entryPath))
+            continue;
+        const { size } = fs.statSync(entryPath);
+        fs.rmSync(entryPath, { force: true });
+        result.bytesRemoved += size;
+        result.filesRemoved += 1;
+    }
+    return result;
+}
+export function pruneDeployedRuntimeDeps(prodDir) {
+    const pnpmStore = path.join(prodDir, 'node_modules', '.pnpm');
+    if (!fs.existsSync(pnpmStore))
+        return { bytesRemoved: 0, filesRemoved: 0 };
+    return pruneDirectory(pnpmStore);
+}
+function resolveCliProdDirs(args, env) {
+    if (args.length > 0)
+        return [...args];
+    const prodDir = env.PROD_DIR;
+    if (!prodDir)
+        throw new Error('PROD_DIR or a directory argument is required');
+    return [prodDir];
+}
+export function runPruneDeployedRuntimeDepsCli({ args, env, isMain, prune = pruneDeployedRuntimeDeps, stdout, }) {
+    if (!isMain)
+        return;
+    for (const prodDir of resolveCliProdDirs(args, env)) {
+        const result = prune(prodDir);
+        stdout(`Pruned ${result.filesRemoved} runtime dependency artifact(s) from ${prodDir} (${result.bytesRemoved} bytes)`);
+    }
+}

package/dist/pnpm-deploy/restore.d.mts

@@ -0,0 +1,31 @@
+export interface RestoreWorkspacePackagesOptions {
+    backendDir?: string;
+    prodDir: string;
+    workspaceRoot?: string;
+}
+/**
+ * Node's --experimental-strip-types refuses to load TypeScript whose real path
+ * contains a node_modules segment, but pnpm deploy places workspace packages
+ * (shipped as TypeScript source) inside the virtual store at
+ * node_modules/.pnpm/<store-dir>/node_modules/<name>.
+ *
+ * Relocate every workspace-package copy outside node_modules while preserving
+ * pnpm's resolution topology, without enumerating dependencies:
+ *
+ * - move the content dir to workspace-packages/<store-dir>/<name>
+ * - leave a relative symlink at the original virtual-store location, so every
+ *   pnpm-created link (top-level node_modules entries, sibling links from other
+ *   store dirs) keeps resolving through it
+ * - add a node_modules backlink inside the moved dir pointing at the package's
+ *   original virtual-store sibling directory, so the package's own imports
+ *   resolve exactly as pnpm laid them out
+ */
+export declare function restoreDeployedWorkspacePackages({ backendDir, prodDir, workspaceRoot, }: RestoreWorkspacePackagesOptions): void;
+interface RestoreCliOptions {
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+    isMain: boolean;
+    restore?: typeof restoreDeployedWorkspacePackages;
+}
+export declare function runRestoreDeployedWorkspacePackagesCli({ args, env, isMain, restore, }: RestoreCliOptions): void;
+export {};