minutes-mcp 0.23.0 → 0.25.0

package/dist/autoInstall.d.ts

@@ -1,5 +1,6 @@
 type ExecFileAsync = (file: string, args: readonly string[], options?: {
     timeout?: number;
+    env?: NodeJS.ProcessEnv;
 }) => Promise<unknown>;
 export type Sha256Entry = {
     filename: string;
@@ -9,6 +10,27 @@ export declare function parseSha256Sums(raw: string): Sha256Entry[];
 export declare function findSha256ForAsset(raw: string, assetName: string): string | null;
 export declare function computeFileSha256(path: string): Promise<string>;
 export declare function verifyDownloadedAsset(path: string, expectedSha256: string): Promise<void>;
+/**
+ * Extract a zip on Windows via PowerShell's Expand-Archive.
+ *
+ * The paths travel in the environment, never in the command text. Two ways to
+ * get this wrong, both of which shipped:
+ *
+ * - Interpolating into a single-quoted PowerShell string breaks on a home
+ *   directory containing an apostrophe (`C:\Users\O'Brien`).
+ * - Passing them as trailing arguments and reading `$args[0]` does not work at
+ *   all: `powershell -Command` appends trailing arguments to the command text
+ *   and leaves `$args` empty (only `-File` binds them), so `$args[0]` is
+ *   `$null` and `Expand-Archive` rejects the parameter on every machine.
+ *
+ * `$env:` lookups are read at runtime and are never parsed as script, so no
+ * value of either path can alter the command.
+ */
+export declare function extractZipWithPowerShell(options: {
+    archivePath: string;
+    destDir: string;
+    execFileAsync: ExecFileAsync;
+}): Promise<void>;
 export declare function downloadReleaseBinaryWithChecksum(options: {
     binaryName: string;
     targetPath: string;

package/dist/autoInstall.js

@@ -36,6 +36,38 @@ export async function verifyDownloadedAsset(path, expectedSha256) {
         throw new Error(`checksum mismatch: expected ${expectedSha256.toLowerCase()}, got ${actual}`);
     }
 }
+/**
+ * Extract a zip on Windows via PowerShell's Expand-Archive.
+ *
+ * The paths travel in the environment, never in the command text. Two ways to
+ * get this wrong, both of which shipped:
+ *
+ * - Interpolating into a single-quoted PowerShell string breaks on a home
+ *   directory containing an apostrophe (`C:\Users\O'Brien`).
+ * - Passing them as trailing arguments and reading `$args[0]` does not work at
+ *   all: `powershell -Command` appends trailing arguments to the command text
+ *   and leaves `$args` empty (only `-File` binds them), so `$args[0]` is
+ *   `$null` and `Expand-Archive` rejects the parameter on every machine.
+ *
+ * `$env:` lookups are read at runtime and are never parsed as script, so no
+ * value of either path can alter the command.
+ */
+export async function extractZipWithPowerShell(options) {
+    const { archivePath, destDir, execFileAsync } = options;
+    await execFileAsync("powershell", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "Expand-Archive -Path $env:MINUTES_ZIP_PATH -DestinationPath $env:MINUTES_ZIP_DEST -Force",
+    ], {
+        timeout: 120000,
+        env: {
+            ...process.env,
+            MINUTES_ZIP_PATH: archivePath,
+            MINUTES_ZIP_DEST: destDir,
+        },
+    });
+}
 export async function downloadReleaseBinaryWithChecksum(options) {
     const { binaryName, targetPath, execFileAsync } = options;
     const baseUrl = options.baseUrl ?? "https://github.com/silverstein/minutes/releases/latest/download";

package/dist/corpus-lease-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/corpus-lease-worker.js

@@ -0,0 +1,94 @@
+import { createInterface } from "node:readline";
+import { markCorpusLeaseWorkerProcess, runCorpusLeaseWorkerRequest, } from "./corpus-lease.js";
+import { retireBoundReadersForProcessShutdown } from "./secure-read.js";
+// Content is sent in 64 KiB raw chunks, so every control line stays far below
+// this fixed ceiling and never scales with the full corpus size.
+const MAX_CONTROL_LINE_BYTES = 512 * 1024;
+markCorpusLeaseWorkerProcess();
+function fail() {
+    process.exit(70);
+}
+function send(message) {
+    const serialized = JSON.stringify(message);
+    if (Buffer.byteLength(serialized) > MAX_CONTROL_LINE_BYTES)
+        fail();
+    process.stdout.write(serialized + "\n");
+}
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+const responses = [];
+const responseWaiters = [];
+const pauseWaiters = new Map();
+lines.on("line", (line) => {
+    if (Buffer.byteLength(line) > MAX_CONTROL_LINE_BYTES)
+        fail();
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        fail();
+    }
+    if (message?.type === "resume" && Number.isSafeInteger(message.id)) {
+        const resume = pauseWaiters.get(message.id);
+        if (!resume)
+            fail();
+        pauseWaiters.delete(message.id);
+        resume();
+        return;
+    }
+    const waiter = responseWaiters.shift();
+    if (waiter)
+        waiter(message);
+    else
+        responses.push(message);
+});
+lines.on("close", () => fail());
+function nextResponse() {
+    const ready = responses.shift();
+    if (ready !== undefined)
+        return Promise.resolve(ready);
+    return new Promise((resolve) => responseWaiters.push(resolve));
+}
+const bridge = {
+    exchange: async (message) => {
+        send(message);
+        return nextResponse();
+    },
+    pause: (id, reservedEvent) => {
+        if (!Number.isSafeInteger(id) || pauseWaiters.has(id))
+            fail();
+        let resume;
+        const promise = new Promise((resolve) => {
+            resume = resolve;
+        });
+        pauseWaiters.set(id, resume);
+        return {
+            promise,
+            onReserved: () => send({ type: reservedEvent, id }),
+        };
+    },
+};
+let exitCode = 0;
+try {
+    const first = await nextResponse();
+    if (!first ||
+        first.type !== "begin" ||
+        !first.request ||
+        typeof first.request.root !== "string" ||
+        !first.request.budgets ||
+        !Number.isSafeInteger(first.request.timeoutMs) ||
+        !Array.isArray(first.request.hookNames)) {
+        fail();
+    }
+    await runCorpusLeaseWorkerRequest(first.request, bridge);
+}
+catch {
+    exitCode = 70;
+}
+try {
+    await retireBoundReadersForProcessShutdown();
+}
+catch {
+    exitCode = 70;
+}
+process.exit(exitCode);

package/dist/corpus-lease.d.ts

@@ -0,0 +1,176 @@
+export type CorpusReadBudgets = {
+    maxFileBytes: number;
+    maxCorpusBytes: number;
+    maxRetainedPathBytes: number;
+    maxFileCount: number;
+    maxDirectoryCount: number;
+    maxDirectoryEntries: number;
+    maxWatcherCount: number;
+    maxReaderCount: number;
+};
+export declare const DEFAULT_CORPUS_READ_BUDGETS: Readonly<CorpusReadBudgets>;
+export type CorpusVerificationStats = Readonly<{
+    fileCount: number;
+    retainedContentBytes: number;
+    totalBytes: number;
+}>;
+export type StableCorpusFile = Readonly<{
+    readonly path: string;
+    readonly relativePath: string;
+    readonly content: string;
+}>;
+export type StableCorpusSnapshot = Readonly<{
+    readonly canonicalRoot: string;
+    files: readonly StableCorpusFile[];
+}>;
+export type CorpusLeaseControls = {
+    failWatcher: (reason?: string) => void;
+    suppressNextFence: () => void;
+    requireRepulseForNextFence: () => void;
+    failNextFencePulse: () => void;
+    failNextSentinelOpen: () => void;
+    pauseNextSentinelOpen: (until: Promise<void>, onReserved?: () => void) => void;
+    pauseNextFenceAfterPending: (until: Promise<void>, onPending?: () => void) => void;
+};
+/**
+ * Test/diagnostic hooks for deterministic authorization-race coverage.
+ * Every awaited hook runs before the final sentinel fence; the successful
+ * final fence remains the operation's linearization point.
+ */
+export type CorpusLeaseHooks = {
+    /** Explicit corpus resource limits; omitted fields use the safe defaults. */
+    budgets?: Partial<CorpusReadBudgets>;
+    timeoutMs?: number;
+    beforeSentinelCreate?: (context: {
+        attempt: number;
+        slot: number;
+        capacity: Readonly<{
+            globalReserved: number;
+            globalRetained: number;
+            rootReserved: number;
+        }>;
+    }) => void | Promise<void>;
+    onWatcherReady?: (context: {
+        attempt: number;
+        controls: CorpusLeaseControls;
+    }) => void | Promise<void>;
+    afterBaseline?: (context: {
+        attempt: number;
+        controls: CorpusLeaseControls;
+    }) => void | Promise<void>;
+    beforeFinalManifest?: (context: {
+        attempt: number;
+        controls: CorpusLeaseControls;
+    }) => void | Promise<void>;
+    afterFinalManifest?: (context: {
+        attempt: number;
+        controls: CorpusLeaseControls;
+        verification: CorpusVerificationStats;
+    }) => void | Promise<void>;
+    beforeFinalFence?: (context: {
+        attempt: number;
+        controls: CorpusLeaseControls;
+    }) => void | Promise<void>;
+    /** Test-only worker entry override for hostile protocol fixtures. */
+    workerScriptForTest?: string;
+    /** Test-only deterministic worker stall injection. */
+    workerStallPhaseForTest?: "before-baseline" | "after-baseline" | "before-finalize" | "before-authorized";
+    /** Test-only deterministic parent deadline after the projection has started. */
+    operationDeadlineForTest?: Promise<void>;
+    /**
+     * Test-only: treat worker termination as unconfirmed, whatever really happened.
+     *
+     * Whether a kill is confirmed inside the grace window is a race a test cannot
+     * force: SIGKILL is untrappable, so no fixture can refuse to die on cue, and
+     * a shortened window is not enough either. A never-fed child dies almost
+     * immediately, so the termination promise usually wins even a zero-length
+     * race, and a test written that way passes without ever entering the branch
+     * it claims to cover.
+     *
+     * A boolean forces the branch instead. It is also the least powerful shape
+     * available: no delay to coerce, nothing to hold cleanup open, and it can
+     * only make the parent more conservative, since an unconfirmed kill of a
+     * worker that knew the corpus still poisons.
+     */
+    forceUnconfirmedTerminationForTest?: boolean;
+    /**
+     * Held *in addition to* the real reap before a stranded child counts as
+     * confirmed dead. Without it both halves of the contract race, because the
+     * child is SIGKILLed and so reaped within milliseconds: a test cannot
+     * observe "still refused" before recovery overtakes it.
+     *
+     * A promise the test never settles pins the refusing half; one it settles
+     * pins the recovering half. Because recovery waits for this promise *and*
+     * the real termination, it can only ever delay recovery relative to
+     * production. It cannot unlock the process before the child is genuinely
+     * reaped, so it cannot manufacture a pass out of a parent that fails closed
+     * too weakly. An earlier draft used `??` here, which substituted the hook
+     * for real termination and did exactly that.
+     */
+    confirmTerminationForTest?: Promise<void>;
+};
+/**
+ * Test-only: give this process's deferred releases a chance to settle.
+ *
+ * Best-effort and bounded, deliberately. The flake this exists for is a release
+ * that has not settled YET: a killed child whose termination lands as soon as
+ * the event loop breathes. Awaiting gives it that chance, so the next case
+ * starts from a clean charge instead of inheriting one.
+ *
+ * It does NOT throw on an unsettled deferral, because "never settles" is a
+ * supported end state, not a defect: a projection that ignores cancellation
+ * poisons admission permanently and by design, and the test covering that would
+ * fail a stricter hook for doing its job. Returns whether everything settled,
+ * for a caller that wants to know.
+ *
+ * Measured, so the budget is not a guess: one stranded child holds 15,335,424
+ * bytes against MAX_RETAINED_CORPUS_MEMORY_BYTES, awaiting while the child is
+ * still unreaped clears nothing, and awaiting after the reap lands clears it to
+ * zero. The bound only has to cover the gap between a case ending and its
+ * child's reap arriving, which is milliseconds unless the machine is saturated,
+ * so it is set well above that and still far below vitest's hook timeout.
+ */
+export declare function awaitDeferredCorpusReleasesForTests(timeoutMs?: number): Promise<boolean>;
+/** Test-only: the live retained-corpus charge, for leak assertions. */
+export declare function reservedCorpusMemoryBytesForTests(): number;
+export type CorpusLeaseWorkerRequest = Readonly<{
+    root: string;
+    budgets: Readonly<CorpusReadBudgets>;
+    timeoutMs: number;
+    hookNames: readonly string[];
+    stallPhase?: CorpusLeaseHooks["workerStallPhaseForTest"];
+}>;
+export type CorpusLeaseWorkerBridge = {
+    exchange: (message: unknown) => Promise<any>;
+    pause: (id: number, reservedEvent: string) => {
+        promise: Promise<void>;
+        onReserved: () => void;
+    };
+};
+/** Mark this short-lived helper before it touches the caller's corpus. */
+export declare function markCorpusLeaseWorkerProcess(): void;
+/** Worker-only entry point used by corpus-lease-worker.ts. */
+export declare function runCorpusLeaseWorkerRequest(request: CorpusLeaseWorkerRequest, bridge: CorpusLeaseWorkerBridge): Promise<void>;
+/**
+ * Run a multi-source projection while a killable worker owns every corpus
+ * traversal, exact read, watcher, fence, and cleanup filesystem operation.
+ */
+/**
+ * Authorize a stable corpus read, presenting one error for one condition.
+ *
+ * Every way the lease can refuse is a refusal, and callers get the same
+ * sentence for all of them. Without this, which sentence you saw depended on
+ * where the failure landed: `fail()` wraps refusals raised once the worker is
+ * running, but a `CorpusLeaseChangedError` thrown before that, such as the
+ * deadline guard at the top of the dispatch below, escaped raw.
+ *
+ * That is observable, not cosmetic. On a contended Windows runner a short
+ * budget can elapse between computing the deadline and the very next
+ * statement checking it, so the same timeout surfaced as
+ * "meeting corpus authorization deadline elapsed" instead of the documented
+ * refusal, and CI failed with a message mismatch rather than a real defect.
+ *
+ * `CorpusLeaseBudgetError` and the plain `Error` refusals keep their own text:
+ * those name a caller-actionable limit rather than an authorization outcome.
+ */
+export declare function withStableCorpusLease<T>(root: string, operation: (snapshot: StableCorpusSnapshot, attempt: number, signal: AbortSignal) => T | Promise<T>, hooks?: CorpusLeaseHooks): Promise<T>;