@open-cr-agent/cli 0.5.0 → 0.6.0

package/dist/cloud/account-salt.d.ts

@@ -0,0 +1,6 @@
+export declare function accountSaltPath(credentialsPath: string): string;
+/** Keeps the salt beside the credentials (0600), or removes it when the account has none. */
+export declare function saveAccountSalt(credentialsPath: string, salt: string | null): Promise<void>;
+/** The salt kept beside the credentials, or undefined when there is none or it is not a salt. */
+export declare function readAccountSalt(credentialsPath: string): Promise<string | undefined>;
+//# sourceMappingURL=account-salt.d.ts.map

package/dist/cloud/account-salt.js

@@ -0,0 +1,33 @@
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { writePrivateFile } from "./private-file.js";
+// The account's repository-hash salt (ADR-0028, 4). The server answers one
+// only while the account shares findings, so that a repository hashes alike
+// on every machine of the account; null means the per-machine salt stays.
+// It is kept beside the credentials, readable only by this user, and
+// refreshed at login and by each signed-in review; a review that cannot
+// reach ocra Cloud hashes with the one kept, so its counts group alike.
+const SALT = /^[0-9a-f]{64}$/;
+export function accountSaltPath(credentialsPath) {
+    return join(dirname(credentialsPath), "account-salt");
+}
+/** Keeps the salt beside the credentials (0600), or removes it when the account has none. */
+export async function saveAccountSalt(credentialsPath, salt) {
+    const path = accountSaltPath(credentialsPath);
+    if (salt === null) {
+        await rm(path, { force: true });
+        return;
+    }
+    await writePrivateFile(path, `${salt}\n`);
+}
+/** The salt kept beside the credentials, or undefined when there is none or it is not a salt. */
+export async function readAccountSalt(credentialsPath) {
+    try {
+        const salt = (await readFile(accountSaltPath(credentialsPath), "utf8")).trim();
+        return SALT.test(salt) ? salt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=account-salt.js.map

package/dist/{review → cloud}/account-settings.js

@@ -1,7 +1,7 @@
+import { CLOUD_PREFIX, isCloudModel } from "@open-cr-agent/cloud-contract";
 import { repoRuleSchema } from "@open-cr-agent/core/internal";
 import { z } from "zod";
-import { CLOUD_PREFIX } from "./cloud-providers.js";
-import { configSchema } from "./config.js";
+import { configSchema } from "../config/schema.js";
 // What ocra Cloud's GET /api/preferences may set (ADR-0025, ADR-0027),
 // checked key by key with the configuration file's own schema: a key that
 // does not match is refused alone, and a key this CLI does not know is
@@ -15,8 +15,9 @@ const accountRules = z
     .max(50);
 // Account models go through the gateway with the account's stored keys
 // (ADR-0027): a chain naming any other provider could send the code where
-// this machine's own keys reach.
-const cloudModel = (chain) => chain.every((model) => model.startsWith(CLOUD_PREFIX) && model.indexOf("/") > 0);
+// this machine's own keys reach. Provider names and model ids are checked
+// against what ocra Cloud may name before they reach the runtime.
+const cloudModel = (chain) => chain.every(isCloudModel);
 const shape = configSchema.shape;
 const SETTINGS = {
     concurrency: shape.concurrency,

package/dist/cloud/browser.d.ts

@@ -0,0 +1,17 @@
+type Spawner = (command: string, args: string[], options: {
+    stdio: "ignore";
+    detached: true;
+}) => {
+    on(event: "error", listener: () => void): unknown;
+    unref(): void;
+};
+/**
+ * The sign-in page's address when ocra may open it: an https URL (http only
+ * on this machine) on the server in use. Undefined otherwise, and the user
+ * opens the printed address themselves.
+ */
+export declare function signInPage(candidate: string, server: string): string | undefined;
+/** Opens an address that signInPage accepted in the default browser. */
+export declare function openBrowser(href: string, platform?: NodeJS.Platform, spawner?: Spawner): void;
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/cloud/browser.js

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * The sign-in page's address when ocra may open it: an https URL (http only
+ * on this machine) on the server in use. Undefined otherwise, and the user
+ * opens the printed address themselves.
+ */
+export function signInPage(candidate, server) {
+    let url;
+    let origin;
+    try {
+        url = new URL(candidate);
+        origin = new URL(server).origin;
+    }
+    catch {
+        return undefined;
+    }
+    const scheme = url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK.has(url.hostname));
+    return scheme && url.origin === origin ? url.href : undefined;
+}
+/** Opens an address that signInPage accepted in the default browser. */
+export function openBrowser(href, platform = process.platform, spawner = spawn) {
+    const [cmd, args] = platform === "darwin"
+        ? ["open", [href]]
+        : platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", href]]
+            : ["xdg-open", [href]];
+    try {
+        const child = spawner(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // The URL is printed as well; a missing opener is not an error.
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/cloud/client.d.ts

@@ -0,0 +1,93 @@
+import { type DeviceCode, type ProviderEntry, type TokenAnswer } from "@open-cr-agent/cloud-contract";
+import { OcraError } from "@open-cr-agent/core";
+import { type Credentials } from "./credentials.js";
+import type { CloudDeps } from "./deps.js";
+/** A call to ocra Cloud that could not be sent or whose answer cannot be used. */
+export declare class CloudError extends OcraError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The saved session, or why there is none to use for this run. */
+export type CloudSession = {
+    kind: "ok";
+    credentials: Credentials;
+} | {
+    kind: "signed-out";
+} | {
+    kind: "revoked";
+} | {
+    kind: "unreachable";
+    reason: string;
+};
+export type CloudSessionLost = Exclude<CloudSession, {
+    kind: "ok";
+}>;
+/** Why the session cannot be used, as the reason a call to ocra Cloud failed. */
+export declare function sessionLostReason(lost: Exclude<CloudSessionLost, {
+    kind: "signed-out";
+}>): string;
+/** An account call's outcome: the value, the HTTP status of a refusal, an answer that is not one, or no session. */
+export type CloudResult<T> = {
+    kind: "ok";
+    value: T;
+} | {
+    kind: "status";
+    status: number;
+} | {
+    kind: "malformed";
+} | CloudSessionLost;
+export type LoginStart = {
+    kind: "started";
+    code: DeviceCode;
+} | {
+    kind: "refused";
+    status: number;
+};
+export declare class CloudClient {
+    private readonly deps;
+    constructor(deps: CloudDeps);
+    /** Starts the device flow (RFC 8628, 3.1). */
+    startLogin(server: string): Promise<LoginStart>;
+    /** One poll of the device flow (RFC 8628, 3.4); an answer that is not one has no field. */
+    pollLogin(server: string, deviceCode: string): Promise<TokenAnswer & {
+        status: number;
+    }>;
+    /** The account a token belongs to; undefined when the server refuses the token. */
+    account(server: string, token: string): Promise<{
+        login: string;
+    } | undefined>;
+    /** Ends the session on the server; the caller removes the local file. */
+    endSession(credentials: Credentials): Promise<void>;
+    /** The gateway's providers, listed without a session. */
+    providers(server: string): Promise<Exclude<CloudResult<ProviderEntry[]>, CloudSessionLost>>;
+    /**
+     * The saved session with a live access token, refreshed (and saved) when
+     * it has expired or is about to, or when the server refused `rejected`,
+     * the access token a call just got 401 for.
+     */
+    session(minValidityMs?: number, rejected?: string): Promise<CloudSession>;
+    /** The account's repository-hash salt; null while it shares no findings, or on a server without salts. */
+    accountSalt(): Promise<CloudResult<string | null>>;
+    /** The account's settings, as an object for the settings parsers. */
+    preferences(): Promise<CloudResult<Record<string, unknown>>>;
+    /** The findings the account remembers, for one repository's hash or for all. */
+    memory(repoHash?: string): Promise<CloudResult<unknown[]>>;
+    /** Sends a review's counts (and shared findings); answers how many findings the server kept. */
+    uploadReview(upload: unknown): Promise<Exclude<CloudResult<{
+        findings: number;
+    }>, {
+        kind: "malformed";
+    }>>;
+    /**
+     * A call for the account with the session's token. A 401 for a token this
+     * machine still holds live refreshes the session once and retries once.
+     * A failure to send the call throws a CloudError.
+     */
+    private call;
+    /** The new pair, saved; revoked when the server refuses the refresh token. */
+    private refresh;
+    private tokens;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cloud/client.js

@@ -0,0 +1,221 @@
+import { accountSchema, deviceCodeSchema, memoryAnswerSchema, preferencesAnswerSchema, providerEntrySchema, providersAnswerSchema, saltSchema, tokenAnswerSchema, uploadAnswerSchema, } from "@open-cr-agent/cloud-contract";
+import { errorMessage, OcraError } from "@open-cr-agent/core";
+import { VERSION } from "../version.js";
+import { readCredentials, writeCredentials } from "./credentials.js";
+import { withFileLock } from "./file-lock.js";
+// The one way to ocra Cloud (ADR-0024): every call goes through request(),
+// with its user agent and timeout, and every answer is checked against its
+// schema (@open-cr-agent/cloud-contract) before a caller sees it. Calls for the account carry the
+// saved session's token and renew it on the way.
+const USER_AGENT = `ocra/${VERSION}`;
+const CLOUD_TIMEOUT_MS = 30_000;
+/** A call to ocra Cloud that could not be sent or whose answer cannot be used. */
+export class CloudError extends OcraError {
+    constructor(message, options) {
+        super("CLOUD_API_FAILED", message, options);
+        this.name = "CloudError";
+    }
+}
+/** Why the session cannot be used, as the reason a call to ocra Cloud failed. */
+export function sessionLostReason(lost) {
+    return lost.kind === "revoked" ? "your ocra Cloud session ended: run ocra login" : lost.reason;
+}
+export class CloudClient {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Starts the device flow (RFC 8628, 3.1). */
+    async startLogin(server) {
+        const res = await this.request(`${server}/api/device/code`, {
+            method: "POST",
+            body: { client_name: this.deps.clientName },
+        });
+        const code = res.status === 200 ? await answerOf(res, deviceCodeSchema) : undefined;
+        return code ? { kind: "started", code } : { kind: "refused", status: res.status };
+    }
+    /** One poll of the device flow (RFC 8628, 3.4); an answer that is not one has no field. */
+    async pollLogin(server, deviceCode) {
+        return this.tokens(`${server}/api/device/token`, { device_code: deviceCode });
+    }
+    /** The account a token belongs to; undefined when the server refuses the token. */
+    async account(server, token) {
+        const res = await this.request(`${server}/api/me`, { token });
+        if (res.status === 401)
+            return undefined;
+        if (!res.ok)
+            throw new CloudError(`ocra Cloud answered ${res.status}`);
+        const me = await answerOf(res, accountSchema);
+        if (!me)
+            throw new CloudError("ocra Cloud's answer names no account");
+        return me;
+    }
+    /** Ends the session on the server; the caller removes the local file. */
+    async endSession(credentials) {
+        await this.request(`${credentials.server}/api/auth/logout`, {
+            method: "POST",
+            body: {},
+            token: credentials.access_token,
+        });
+    }
+    /** The gateway's providers, listed without a session. */
+    async providers(server) {
+        const res = await this.request(`${server}/api/providers`, {});
+        if (!res.ok)
+            return { kind: "status", status: res.status };
+        const body = await answerOf(res, providersAnswerSchema);
+        if (!body)
+            return { kind: "malformed" };
+        const entries = body.providers.flatMap((entry) => {
+            const parsed = providerEntrySchema.safeParse(entry);
+            return parsed.success ? [parsed.data] : [];
+        });
+        return { kind: "ok", value: entries };
+    }
+    /**
+     * The saved session with a live access token, refreshed (and saved) when
+     * it has expired or is about to, or when the server refused `rejected`,
+     * the access token a call just got 401 for.
+     */
+    async session(minValidityMs = 60_000, rejected) {
+        const { deps } = this;
+        const live = (c) => c.access_token !== rejected && c.expires_at - deps.now() > minValidityMs;
+        const saved = await readCredentials(deps.credentialsPath);
+        if (!saved)
+            return { kind: "signed-out" };
+        if (live(saved))
+            return { kind: "ok", credentials: saved };
+        // One refresh at a time on this machine: the server rotates the refresh
+        // token, so of two processes refreshing with one token, one is refused.
+        return withFileLock(`${deps.credentialsPath}.lock`, async () => {
+            const current = await readCredentials(deps.credentialsPath);
+            if (!current)
+                return { kind: "signed-out" };
+            // Another process may have refreshed while this one waited for the lock.
+            if (live(current))
+                return { kind: "ok", credentials: current };
+            const refreshed = await this.refresh(current);
+            if (refreshed.kind !== "revoked")
+                return refreshed;
+            // Rotated by a process that did not wait for the lock (an older ocra,
+            // or one that gave up waiting): its pair is in the file.
+            const latest = await readCredentials(deps.credentialsPath);
+            if (!latest || latest.refresh_token === current.refresh_token)
+                return refreshed;
+            if (live(latest))
+                return { kind: "ok", credentials: latest };
+            return this.refresh(latest);
+        });
+    }
+    /** The account's repository-hash salt; null while it shares no findings, or on a server without salts. */
+    async accountSalt() {
+        const answer = await this.call("/api/account/salt", saltSchema);
+        if (answer.kind === "status" && answer.status === 404)
+            return { kind: "ok", value: null };
+        return answer.kind === "ok" ? { kind: "ok", value: answer.value.salt } : answer;
+    }
+    /** The account's settings, as an object for the settings parsers. */
+    preferences() {
+        return this.call("/api/preferences", preferencesAnswerSchema);
+    }
+    /** The findings the account remembers, for one repository's hash or for all. */
+    async memory(repoHash) {
+        const query = repoHash === undefined ? "" : `?repo=${encodeURIComponent(repoHash)}`;
+        const answer = await this.call(`/api/memory${query}`, memoryAnswerSchema);
+        return answer.kind === "ok" ? { kind: "ok", value: answer.value.entries } : answer;
+    }
+    /** Sends a review's counts (and shared findings); answers how many findings the server kept. */
+    async uploadReview(upload) {
+        const answer = await this.call("/api/reviews", uploadAnswerSchema, {
+            method: "POST",
+            body: upload,
+        });
+        // An answer without a count keeps the counts it acknowledges.
+        if (answer.kind === "malformed")
+            return { kind: "ok", value: { findings: 0 } };
+        return answer.kind === "ok"
+            ? { kind: "ok", value: { findings: answer.value.findings ?? 0 } }
+            : answer;
+    }
+    /**
+     * A call for the account with the session's token. A 401 for a token this
+     * machine still holds live refreshes the session once and retries once.
+     * A failure to send the call throws a CloudError.
+     */
+    async call(path, schema, init = {}) {
+        let session = await this.session();
+        if (session.kind !== "ok")
+            return session;
+        const send = (c) => this.request(`${c.server}${path}`, { ...init, token: c.access_token });
+        let res = await send(session.credentials);
+        if (res.status === 401) {
+            session = await this.session(undefined, session.credentials.access_token);
+            if (session.kind !== "ok")
+                return session;
+            res = await send(session.credentials);
+        }
+        if (!res.ok)
+            return { kind: "status", status: res.status };
+        const value = await answerOf(res, schema);
+        return value === undefined ? { kind: "malformed" } : { kind: "ok", value };
+    }
+    /** The new pair, saved; revoked when the server refuses the refresh token. */
+    async refresh(saved) {
+        let t;
+        try {
+            t = await this.tokens(`${saved.server}/api/device/refresh`, {
+                refresh_token: saved.refresh_token,
+            });
+        }
+        catch (error) {
+            return { kind: "unreachable", reason: errorMessage(error) };
+        }
+        if (t.status === 401 || t.error === "invalid_grant")
+            return { kind: "revoked" };
+        if (t.status !== 200 || !t.access_token || !t.refresh_token || !t.expires_in) {
+            return { kind: "unreachable", reason: `HTTP ${t.status}` };
+        }
+        const next = {
+            ...saved,
+            access_token: t.access_token,
+            refresh_token: t.refresh_token,
+            expires_at: this.deps.now() + t.expires_in * 1000,
+        };
+        await writeCredentials(this.deps.credentialsPath, next);
+        return { kind: "ok", credentials: next };
+    }
+    async tokens(url, body) {
+        const res = await this.request(url, { method: "POST", body });
+        return { ...((await answerOf(res, tokenAnswerSchema)) ?? {}), status: res.status };
+    }
+    async request(url, init) {
+        try {
+            return await this.deps.fetch(url, {
+                ...(init.method ? { method: init.method } : {}),
+                headers: {
+                    "user-agent": USER_AGENT,
+                    ...(init.token ? { authorization: `Bearer ${init.token}` } : {}),
+                    ...(init.body !== undefined ? { "content-type": "application/json" } : {}),
+                },
+                ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+                signal: AbortSignal.timeout(CLOUD_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new CloudError(errorMessage(error), { cause: error });
+        }
+    }
+}
+/** The answer's JSON when it fits the schema; undefined when it is not JSON or does not fit. */
+async function answerOf(res, schema) {
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = schema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/cloud/credentials.d.ts

@@ -0,0 +1,18 @@
+export type Credentials = {
+    server: string;
+    login: string;
+    access_token: string;
+    refresh_token: string;
+    /** Epoch milliseconds when the access token expires. */
+    expires_at: number;
+};
+export declare function credentialsHint(): string;
+export declare function credentialsPath(env: Readonly<Record<string, string | undefined>>): string;
+/**
+ * The saved session; undefined when there is none or the file does not hold
+ * one, which `warn` hears about (a file cut short by a crash, or edited).
+ */
+export declare function readCredentials(path: string, warn?: (message: string) => void): Promise<Credentials | undefined>;
+export declare function loadCredentials(path: string): Promise<Credentials | "unreadable" | undefined>;
+export declare function writeCredentials(path: string, c: Credentials): Promise<void>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/cloud/credentials.js

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ocraConfigDir } from "../config/user-dir.js";
+import { writePrivateFile } from "./private-file.js";
+export function credentialsHint() {
+    return process.platform === "win32"
+        ? "%APPDATA%\\ocra\\credentials.json"
+        : "~/.config/ocra/credentials.json";
+}
+export function credentialsPath(env) {
+    return join(ocraConfigDir(env), "credentials.json");
+}
+/**
+ * The saved session; undefined when there is none or the file does not hold
+ * one, which `warn` hears about (a file cut short by a crash, or edited).
+ */
+export async function readCredentials(path, warn) {
+    const saved = await loadCredentials(path);
+    if (saved !== "unreadable")
+        return saved;
+    warn?.(`ignoring ${path}: it holds no ocra Cloud session; run ocra login to sign in again`);
+    return undefined;
+}
+export async function loadCredentials(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let c;
+    try {
+        c = JSON.parse(text);
+    }
+    catch {
+        return "unreadable";
+    }
+    if (typeof c !== "object" ||
+        c === null ||
+        !c.server ||
+        !c.access_token ||
+        !c.refresh_token ||
+        typeof c.expires_at !== "number") {
+        return "unreadable";
+    }
+    return c;
+}
+export async function writeCredentials(path, c) {
+    await writePrivateFile(path, `${JSON.stringify(c, null, 2)}\n`);
+}
+//# sourceMappingURL=credentials.js.map

package/dist/cloud/deps.d.ts

@@ -0,0 +1,14 @@
+/** ocra Cloud's address; OCRA_CLOUD_URL names another server. */
+export declare const DEFAULT_CLOUD_URL = "https://app.ocracloud.com";
+export type CloudDeps = {
+    env: Readonly<Record<string, string | undefined>>;
+    fetch: typeof fetch;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    openBrowser: (url: string) => void;
+    credentialsPath: string;
+    clientName: string;
+};
+export declare function defaultCloudDeps(env?: CloudDeps["env"]): CloudDeps;
+export declare function cloudUrl(env: CloudDeps["env"]): string;
+//# sourceMappingURL=deps.d.ts.map

package/dist/cloud/deps.js

@@ -0,0 +1,34 @@
+import { hostname } from "node:os";
+import { setTimeout as sleep } from "node:timers/promises";
+import { UsageError } from "../io/usage-error.js";
+import { VERSION } from "../version.js";
+import { openBrowser } from "./browser.js";
+import { credentialsPath } from "./credentials.js";
+/** ocra Cloud's address; OCRA_CLOUD_URL names another server. */
+export const DEFAULT_CLOUD_URL = "https://app.ocracloud.com";
+export function defaultCloudDeps(env = process.env) {
+    return {
+        env,
+        fetch: globalThis.fetch,
+        now: Date.now,
+        sleep: (ms) => sleep(ms),
+        openBrowser: (url) => openBrowser(url),
+        credentialsPath: credentialsPath(env),
+        clientName: `${hostname()} (ocra ${VERSION})`,
+    };
+}
+export function cloudUrl(env) {
+    const named = env.OCRA_CLOUD_URL || DEFAULT_CLOUD_URL;
+    let url;
+    try {
+        url = new URL(named);
+    }
+    catch {
+        throw new UsageError(`OCRA_CLOUD_URL is not a URL: ${named}`);
+    }
+    if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+        throw new UsageError(`OCRA_CLOUD_URL must use https: ${url}`);
+    }
+    return url.origin;
+}
+//# sourceMappingURL=deps.js.map

package/dist/cloud/file-lock.d.ts

@@ -0,0 +1,14 @@
+export type LockTiming = {
+    /** How long to wait for another holder before going on without the lock. */
+    waitMs: number;
+    /** A lock older than this was left by a process that died holding it. */
+    staleMs: number;
+    pollMs: number;
+};
+/**
+ * Runs `fn` holding the lock at `path`. When it cannot be had within
+ * `waitMs`, `fn` runs anyway: the lock only narrows races its callers must
+ * still survive, and a stuck holder must not stop a review.
+ */
+export declare function withFileLock<T>(path: string, fn: () => Promise<T>, timing?: LockTiming): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/cloud/file-lock.js

@@ -0,0 +1,77 @@
+import { randomBytes } from "node:crypto";
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+import { errnoCode, isNotFound } from "@open-cr-agent/core/internal";
+const TIMING = { waitMs: 10_000, staleMs: 30_000, pollMs: 50 };
+/**
+ * Runs `fn` holding the lock at `path`. When it cannot be had within
+ * `waitMs`, `fn` runs anyway: the lock only narrows races its callers must
+ * still survive, and a stuck holder must not stop a review.
+ */
+export async function withFileLock(path, fn, timing = TIMING) {
+    const token = await acquire(path, timing);
+    try {
+        return await fn();
+    }
+    finally {
+        if (token)
+            await release(path, token);
+    }
+}
+async function acquire(path, timing) {
+    const token = randomBytes(8).toString("hex");
+    const deadline = Date.now() + timing.waitMs;
+    for (;;) {
+        try {
+            await writeFile(path, JSON.stringify({ token, at: Date.now(), pid: process.pid }), {
+                flag: "wx",
+                mode: 0o600,
+            });
+            return token;
+        }
+        catch (error) {
+            // A lock that cannot be made at all (a read-only directory) is no lock.
+            if (errnoCode(error) !== "EEXIST")
+                return undefined;
+        }
+        const age = await ageOf(path);
+        if (age === undefined)
+            continue;
+        if (age > timing.staleMs) {
+            await rm(path, { force: true });
+            continue;
+        }
+        if (Date.now() >= deadline)
+            return undefined;
+        await sleep(timing.pollMs);
+    }
+}
+/** Milliseconds since the lock was taken; undefined when it is gone. */
+async function ageOf(path) {
+    try {
+        const at = JSON.parse(await readFile(path, "utf8")).at;
+        if (typeof at === "number")
+            return Date.now() - at;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+    }
+    // Being written, or not a lock of ours: its file's own time stands in.
+    try {
+        return Date.now() - (await stat(path)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function release(path, token) {
+    try {
+        const held = JSON.parse(await readFile(path, "utf8"));
+        // Broken as stale and taken by another: theirs now.
+        if (held.token === token)
+            await rm(path, { force: true });
+    }
+    catch { }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/cloud/findings.d.ts

@@ -0,0 +1,8 @@
+import { type SharedFinding } from "@open-cr-agent/cloud-contract";
+import type { ReviewReport } from "@open-cr-agent/core";
+/** The report's findings as uploaded, redacted and bounded; `left` counts those not sent. */
+export declare function sharedFindings(report: Pick<ReviewReport, "findings">): {
+    findings: SharedFinding[];
+    left: number;
+};
+//# sourceMappingURL=findings.d.ts.map