@open-cr-agent/cli 0.4.0 → 0.6.0

package/dist/cloud/review.js

@@ -0,0 +1,76 @@
+import { originRepository } from "../repository-id.js";
+import { readAccountSalt, saveAccountSalt } from "./account-salt.js";
+import { CloudClient, sessionLostReason } from "./client.js";
+import { sharedFindings } from "./findings.js";
+import { accountHasMemory, fetchAccountMemory } from "./memory.js";
+import { repoHash, uploadOf, uploadReview } from "./upload.js";
+/** What a review loses when ocra Cloud cannot be used for it, said once. */
+export function sessionLostWarning(lost) {
+    const cause = lost.kind === "revoked"
+        ? sessionLostReason(lost)
+        : `could not reach ocra Cloud (${lost.reason})`;
+    return `${cause}; this review runs without your account's rules, limits (maxCostUsd included), models and memory, and uploads nothing`;
+}
+/**
+ * Undefined when the saved session is gone; a failure to reach ocra Cloud is
+ * one warning. The repository is the pull or merge request's when given,
+ * else origin's.
+ */
+export async function prepareCloudReview(root, deps, warn, repository) {
+    const id = repository ?? (await originRepository(root));
+    let salt;
+    try {
+        const answer = await new CloudClient(deps).accountSalt();
+        if (answer.kind === "signed-out")
+            return undefined;
+        if (answer.kind === "status")
+            throw new Error(`HTTP ${answer.status}`);
+        if (answer.kind === "malformed")
+            throw new Error("the answer is not a salt");
+        if (answer.kind !== "ok")
+            throw new Error(sessionLostReason(answer));
+        salt = answer.value;
+    }
+    catch (error) {
+        // The salt kept from the last answer, else this machine's, still groups
+        // the counts. Whether the account still shares findings is unknown, so
+        // none is sent and the account's memory is not applied.
+        warn(`could not read your ocra Cloud account (${error instanceof Error ? error.message : "error"}); this review sends no findings and applies no account memory`);
+        const kept = await readAccountSalt(deps.credentialsPath);
+        return {
+            repoHash: await repoHash(id, deps.credentialsPath, kept),
+            shareFindings: false,
+            memory: [],
+        };
+    }
+    await saveAccountSalt(deps.credentialsPath, salt);
+    const hash = await repoHash(id, deps.credentialsPath, salt ?? undefined);
+    if (salt === null) {
+        // Memory is keyed by the account's hash, which only a sharing account has.
+        if (await accountHasMemory(deps)) {
+            warn("your ocra Cloud account remembers findings, but applies them only while it shares findings (Settings in ocra Cloud); this review applies the repository's memory alone");
+        }
+        return { repoHash: hash, shareFindings: false, memory: [] };
+    }
+    return {
+        repoHash: hash,
+        shareFindings: true,
+        memory: await fetchAccountMemory(deps, hash, warn),
+    };
+}
+/** Sends the counts, and the findings when the account shares them. */
+export async function sendToCloud(report, cloud, deps, run) {
+    const upload = uploadOf(report, run.source, cloud.repoHash, run.durationMs);
+    const shared = cloud.shareFindings ? sharedFindings(report) : undefined;
+    const sent = await uploadReview(upload, deps, run.warn, shared?.findings);
+    if (!sent)
+        return;
+    if (sent.findings > 0) {
+        const left = shared?.left ? ` (${shared.left} left out by the size limit)` : "";
+        run.err.write(`[ocra] Sent this review's counts and ${sent.findings} finding(s) to ocra Cloud${left} (--no-upload to skip)\n`);
+    }
+    else {
+        run.err.write("[ocra] Sent this review's counts to ocra Cloud (--no-upload to skip)\n");
+    }
+}
+//# sourceMappingURL=review.js.map

package/dist/cloud/settings.d.ts

@@ -0,0 +1,22 @@
+import type { SettingsLayer } from "../config/settings.js";
+import { type AccountPlugins } from "../plugins/account.js";
+import { type AccountSettings } from "./account-settings.js";
+import { type CloudSessionLost } from "./client.js";
+import type { CloudDeps } from "./deps.js";
+export type AccountRead = {
+    kind: "read";
+    settings?: AccountSettings;
+    plugins: AccountPlugins;
+} | CloudSessionLost;
+/**
+ * The account's settings. A server that cannot be reached, or a session
+ * that ended, is answered for the caller to say once what the run loses;
+ * an answer that cannot be used is a warning here and no settings.
+ */
+export declare function fetchAccountSettings(deps: CloudDeps, warn: (message: string) => void): Promise<AccountRead>;
+/**
+ * The account's settings as the layer under the configuration: they fill
+ * what it leaves out, and add to its include, exclude and rules.
+ */
+export declare function accountLayer(account: AccountSettings): SettingsLayer;
+//# sourceMappingURL=settings.d.ts.map

package/dist/cloud/settings.js

@@ -0,0 +1,64 @@
+import { errorMessage } from "@open-cr-agent/core";
+import { parseAccountPlugins } from "../plugins/account.js";
+import { parseAccountSettings } from "./account-settings.js";
+import { CloudClient } from "./client.js";
+const NO_PLUGINS = { plugins: [], pluginSettings: {} };
+/**
+ * The account's settings. A server that cannot be reached, or a session
+ * that ended, is answered for the caller to say once what the run loses;
+ * an answer that cannot be used is a warning here and no settings.
+ */
+export async function fetchAccountSettings(deps, warn) {
+    let answer;
+    try {
+        answer = await new CloudClient(deps).preferences();
+    }
+    catch (error) {
+        return { kind: "unreachable", reason: errorMessage(error) };
+    }
+    if (answer.kind === "status") {
+        // A server without account settings has none to apply.
+        if (answer.status === 404)
+            return { kind: "read", plugins: NO_PLUGINS };
+        if (answer.status >= 500 || answer.status === 429) {
+            return { kind: "unreachable", reason: `HTTP ${answer.status}` };
+        }
+        warn(`could not read your ocra Cloud settings (HTTP ${answer.status}); the review uses the repository's`);
+        return { kind: "read", plugins: NO_PLUGINS };
+    }
+    if (answer.kind === "malformed") {
+        warn("ignoring your ocra Cloud settings: the server's answer is not an object");
+        return { kind: "read", plugins: NO_PLUGINS };
+    }
+    if (answer.kind !== "ok")
+        return answer;
+    const body = answer.value;
+    const { settings, warnings } = parseAccountSettings(body);
+    for (const warning of warnings)
+        warn(warning);
+    return {
+        kind: "read",
+        ...(settings ? { settings } : {}),
+        plugins: parseAccountPlugins(body, warn),
+    };
+}
+/**
+ * The account's settings as the layer under the configuration: they fill
+ * what it leaves out, and add to its include, exclude and rules.
+ */
+export function accountLayer(account) {
+    const { version: _, rules, ultra, ...settings } = account;
+    return {
+        source: "account",
+        under: true,
+        settings: {
+            ...settings,
+            ...(rules
+                ? { rules: rules.map((rule) => ({ ...rule, source: "account" })) }
+                : {}),
+            // The account's default for --ultra; there is no --no-ultra to refuse it.
+            ...(ultra === true ? { ultra } : {}),
+        },
+    };
+}
+//# sourceMappingURL=settings.js.map

package/dist/cloud/upload.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewSource, ReviewUpload, SharedFinding } from "@open-cr-agent/cloud-contract";
+import { type ReviewReport } from "@open-cr-agent/core";
+import type { CloudDeps } from "./deps.js";
+export declare function uploadOf(report: ReviewReport, source: ReviewSource, repoHash: string, durationMs: number): ReviewUpload;
+/**
+ * The hash of a repository named as `https://host/owner/repo`
+ * (repository-id.ts), salted with the account's salt when given, else this machine's.
+ */
+export declare function repoHash(repository: string, credentialsPath: string, accountSalt?: string): Promise<string>;
+/** Whether this run talks to ocra Cloud at all: signed in, not turned off. */
+export declare function cloudEnabled(deps: CloudDeps, warn: (message: string) => void): Promise<boolean>;
+/**
+ * Sends the counts, and the findings when given; answers how many findings
+ * the server kept, or undefined when it took nothing. A failure is a
+ * warning, never a failed review.
+ */
+export declare function uploadReview(upload: ReviewUpload, deps: CloudDeps, warn: (message: string) => void, findings?: readonly SharedFinding[]): Promise<{
+    findings: number;
+} | undefined>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/cloud/upload.js

@@ -0,0 +1,183 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { coverageGaps } from "@open-cr-agent/core";
+import { verificationSchema } from "@open-cr-agent/core/internal";
+import { VERSION } from "../version.js";
+import { CloudClient, CloudError, sessionLostReason } from "./client.js";
+import { readCredentials } from "./credentials.js";
+import { createPrivateFile, writePrivateFile } from "./private-file.js";
+// After a review, a signed-in CLI sends ocra Cloud its counts (ADR-0024):
+// the verdict, how many findings of each severity, files and tasks, tokens
+// and time. A path, a title, a finding's text or code go only when the
+// account shares findings (ADR-0028, findings.ts). The repository is
+// a salted hash of its `https://host/owner/repo` (repository-id.ts), so
+// the server can group reviews of one repository without learning which
+// it is: the salt stays on this machine, or is the account's while it
+// shares findings, so the hash matches on all its machines.
+export function uploadOf(report, source, repoHash, durationMs) {
+    const severity = (s) => report.findings.filter((f) => f.severity === s).length;
+    const gaps = coverageGaps(report);
+    return {
+        runId: report.runId,
+        repoHash,
+        source,
+        tier: report.tier,
+        verdict: report.verdict,
+        // As the exit code reads it: a review that missed files or could not
+        // verify a critical finding is incomplete.
+        complete: gaps.notReviewed === 0 && report.unverifiedCriticals === 0,
+        findings: {
+            critical: severity("critical"),
+            warning: severity("warning"),
+            suggestion: severity("suggestion"),
+        },
+        files: {
+            reviewed: report.coverage.filter((c) => c.status === "reviewed").length,
+            notReviewed: gaps.notReviewed,
+        },
+        tasks: {
+            completed: report.tasks.filter((t) => t.status === "completed").length,
+            failed: report.tasks.filter((t) => t.status === "failed" || t.status === "timed_out").length,
+        },
+        usage: {
+            inputTokens: report.usage.inputTokens,
+            outputTokens: report.usage.outputTokens,
+            costUsd: report.usage.costUsd ?? 0,
+        },
+        durationMs: Math.round(durationMs),
+        ocraVersion: VERSION,
+        ...perReviewer(report),
+    };
+}
+// Counted as `ocra metrics` counts one report: a failed or timed-out task is
+// failed, a finding without a verification is unchecked, a dismissal outranks
+// a fix, and a fixed or dismissed finding is attributed to the reviewer the
+// earlier review recorded for it, else to the reviewer of a finding with its
+// fingerprint in this report, else to none.
+function perReviewer(report) {
+    const reviewers = new Map();
+    const of = (id) => {
+        let r = reviewers.get(id);
+        if (!r) {
+            r = {
+                tasks: 0,
+                failedTasks: 0,
+                findings: { critical: 0, warning: 0, suggestion: 0 },
+                costUsd: 0,
+                fixed: 0,
+                dismissed: 0,
+            };
+            reviewers.set(id, r);
+        }
+        return r;
+    };
+    for (const task of report.tasks) {
+        const r = of(task.reviewer);
+        r.tasks += 1;
+        if (task.status === "failed" || task.status === "timed_out")
+            r.failedTasks += 1;
+        r.costUsd += task.usage.costUsd;
+    }
+    const verification = Object.fromEntries(verificationSchema.options.map((v) => [v, 0]));
+    const reviewerOf = new Map();
+    for (const finding of report.findings) {
+        of(finding.reviewer).findings[finding.severity] += 1;
+        verification[finding.verification ?? "unchecked"] += 1;
+        if (!reviewerOf.has(finding.fingerprint))
+            reviewerOf.set(finding.fingerprint, finding.reviewer);
+    }
+    const outcomeReviewer = (f) => f.reviewer ?? reviewerOf.get(f.fingerprint);
+    const dismissed = new Map((report.rereview?.dismissed ?? []).map((f) => [f.fingerprint, outcomeReviewer(f)]));
+    const fixed = new Map((report.rereview?.fixed ?? [])
+        .filter((f) => !dismissed.has(f.fingerprint))
+        .map((f) => [f.fingerprint, outcomeReviewer(f)]));
+    for (const reviewer of fixed.values())
+        if (reviewer)
+            of(reviewer).fixed += 1;
+    for (const reviewer of dismissed.values())
+        if (reviewer)
+            of(reviewer).dismissed += 1;
+    return {
+        reviewers: Object.fromEntries([...reviewers].sort(([a], [b]) => a.localeCompare(b))),
+        verification,
+        outcomes: { fixed: fixed.size, dismissed: dismissed.size },
+    };
+}
+/** This machine's random salt, kept beside the credentials, made on first use. */
+async function machineSalt(credentialsPath) {
+    const path = join(dirname(credentialsPath), "upload-salt");
+    const existing = await readSalt(path);
+    if (existing !== "unreadable") {
+        if (existing)
+            return existing;
+        // Two first reviews at once agree on the salt the first of them made.
+        const fresh = randomBytes(32).toString("hex");
+        if (await createPrivateFile(path, `${fresh}\n`))
+            return fresh;
+        const made = await readSalt(path);
+        if (made && made !== "unreadable")
+            return made;
+    }
+    const fresh = randomBytes(32).toString("hex");
+    await writePrivateFile(path, `${fresh}\n`);
+    return fresh;
+}
+async function readSalt(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const salt = text.trim();
+    return /^[0-9a-f]{64}$/.test(salt) ? salt : "unreadable";
+}
+/**
+ * The hash of a repository named as `https://host/owner/repo`
+ * (repository-id.ts), salted with the account's salt when given, else this machine's.
+ */
+export async function repoHash(repository, credentialsPath, accountSalt) {
+    const salt = accountSalt ?? (await machineSalt(credentialsPath));
+    return createHash("sha256").update(`${salt}:${repository}`).digest("hex");
+}
+/** Whether this run talks to ocra Cloud at all: signed in, not turned off. */
+export async function cloudEnabled(deps, warn) {
+    return (deps.env.OCRA_CLOUD !== "off" &&
+        (await readCredentials(deps.credentialsPath, warn)) !== undefined);
+}
+/**
+ * Sends the counts, and the findings when given; answers how many findings
+ * the server kept, or undefined when it took nothing. A failure is a
+ * warning, never a failed review.
+ */
+export async function uploadReview(upload, deps, warn, findings) {
+    try {
+        const answer = await new CloudClient(deps).uploadReview(
+        // The counts stay in `findings`; the shared list goes in `findingList`.
+        findings ? { ...upload, findingList: findings } : upload);
+        if (answer.kind === "signed-out")
+            return undefined;
+        if (answer.kind === "status") {
+            warn(`ocra Cloud did not take the review's counts (HTTP ${answer.status})`);
+            return undefined;
+        }
+        if (answer.kind !== "ok") {
+            warn(`could not send the review's counts to ocra Cloud: ${sessionLostReason(answer)}`);
+            return undefined;
+        }
+        return answer.value;
+    }
+    catch (error) {
+        warn(`could not send the review's counts to ocra Cloud: ${failureName(error)}`);
+        return undefined;
+    }
+}
+// The warning names the error, not its message; for a call that could not be
+// sent, the cause's name (TypeError for a network failure).
+function failureName(error) {
+    const cause = error instanceof CloudError && error.cause instanceof Error ? error.cause : error;
+    return cause instanceof Error ? cause.name : "error";
+}
+//# sourceMappingURL=upload.js.map

package/dist/commands/login.d.ts

@@ -0,0 +1,5 @@
+import { type CloudDeps } from "../cloud/deps.js";
+import type { Output } from "../io/output.js";
+export declare const LOGIN_USAGE: string;
+export declare function loginCommand(command: "login" | "logout" | "whoami", argv: string[], out: Output, err: Output, deps: CloudDeps): Promise<number>;
+//# sourceMappingURL=login.d.ts.map

package/dist/commands/login.js

@@ -0,0 +1,164 @@
+import { rm } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { errorMessage } from "@open-cr-agent/core";
+import { saveAccountSalt } from "../cloud/account-salt.js";
+import { signInPage } from "../cloud/browser.js";
+import { CloudClient } from "../cloud/client.js";
+import { credentialsHint, loadCredentials, writeCredentials, } from "../cloud/credentials.js";
+import { cloudUrl, DEFAULT_CLOUD_URL } from "../cloud/deps.js";
+import { EXIT } from "../io/exit.js";
+import { forTerminal } from "../io/terminal.js";
+// ocra Cloud sign-in (ADR-0024): `ocra login` runs the OAuth device flow
+// (RFC 8628) against ocra Cloud, `ocra whoami` shows the account, and
+// `ocra logout` ends the session. Nothing here runs unless one of these
+// commands is used: a self-hosted user never sees a login prompt.
+export const LOGIN_USAGE = `Usage: ocra login [--no-browser]
+       ocra logout
+       ocra whoami
+
+Sign in to ocra Cloud with GitHub, so reviews can use the model keys stored
+there. ocra login shows a code, opens the browser to confirm it, and saves the
+session to ${credentialsHint()} (readable only by you).
+
+Environment:
+  OCRA_CLOUD=off   Disable ocra Cloud: these commands refuse to run
+  OCRA_CLOUD_URL   Another ocra Cloud server (default ${DEFAULT_CLOUD_URL})
+`;
+export async function loginCommand(command, argv, out, err, deps) {
+    const { values } = parseArgs({
+        args: argv,
+        strict: true,
+        options: { "no-browser": { type: "boolean" }, help: { type: "boolean", short: "h" } },
+    });
+    if (values.help) {
+        out.write(LOGIN_USAGE);
+        return EXIT.ok;
+    }
+    if (deps.env.OCRA_CLOUD === "off") {
+        err.write("ocra Cloud is off (OCRA_CLOUD=off).\n");
+        return EXIT.error;
+    }
+    if (command === "whoami")
+        return whoami(out, err, deps);
+    if (command === "logout")
+        return logout(out, deps);
+    return login(out, err, deps, !values["no-browser"]);
+}
+async function whoami(out, err, deps) {
+    const client = new CloudClient(deps);
+    const session = await client.session();
+    if (session.kind === "signed-out") {
+        err.write("Not signed in. Run ocra login.\n");
+        return EXIT.notSignedIn;
+    }
+    if (session.kind === "unreachable") {
+        err.write(forTerminal(`ocra Cloud could not be reached (${session.reason}).\n`));
+        return EXIT.error;
+    }
+    const me = session.kind === "ok"
+        ? await client.account(session.credentials.server, session.credentials.access_token)
+        : undefined;
+    if (session.kind !== "ok" || !me) {
+        err.write("Your ocra Cloud session ended. Run ocra login.\n");
+        return EXIT.notSignedIn;
+    }
+    out.write(forTerminal(`${me.login} on ${session.credentials.server}\n`));
+    return EXIT.ok;
+}
+async function logout(out, deps) {
+    const saved = await loadCredentials(deps.credentialsPath);
+    if (saved && saved !== "unreadable") {
+        // Ends the session on the server too; the local file goes either way.
+        const client = new CloudClient(deps);
+        const session = await client.session().catch(() => undefined);
+        if (session?.kind === "ok")
+            await client.endSession(session.credentials).catch(() => { });
+    }
+    await rm(deps.credentialsPath, { force: true });
+    await saveAccountSalt(deps.credentialsPath, null);
+    out.write(saved === "unreadable"
+        ? "Removed the saved session, which could not be read.\n"
+        : saved
+            ? "Signed out.\n"
+            : "Not signed in.\n");
+    return EXIT.ok;
+}
+async function login(out, err, deps, browser) {
+    const server = cloudUrl(deps.env);
+    const client = new CloudClient(deps);
+    const start = await client.startLogin(server);
+    if (start.kind === "refused") {
+        err.write(`ocra Cloud did not start a login (HTTP ${start.status}). Try again in a minute.\n`);
+        return EXIT.error;
+    }
+    const { code } = start;
+    out.write(forTerminal(`Confirm this code in your browser: ${code.user_code}\n` +
+        `  ${code.verification_uri_complete}\n` +
+        `(or open ${code.verification_uri} and type it)\n\nWaiting for approval...\n`));
+    if (browser) {
+        const page = signInPage(code.verification_uri_complete, server);
+        if (page)
+            deps.openBrowser(page);
+        else
+            err.write(`ocra opens only pages on ${server}; open the address above yourself.\n`);
+    }
+    let interval = (code.interval ?? 5) * 1000;
+    const deadline = deps.now() + (code.expires_in ?? 600) * 1000;
+    while (deps.now() < deadline) {
+        await deps.sleep(interval);
+        let t;
+        try {
+            t = await client.pollLogin(server, code.device_code);
+        }
+        catch (error) {
+            // A dropped connection is retried on the next tick.
+            err.write(forTerminal(`(${errorMessage(error)}; retrying)\n`));
+            continue;
+        }
+        if (t.status === 200 && t.access_token && t.refresh_token && t.expires_in) {
+            // The tokens are issued: they are saved even when the login cannot be read.
+            let login;
+            let unknown = "";
+            try {
+                login = (await client.account(server, t.access_token))?.login;
+            }
+            catch (error) {
+                unknown = errorMessage(error);
+            }
+            const credentials = {
+                server,
+                login: login ?? "",
+                access_token: t.access_token,
+                refresh_token: t.refresh_token,
+                expires_at: deps.now() + t.expires_in * 1000,
+            };
+            await writeCredentials(deps.credentialsPath, credentials);
+            // Best effort: each signed-in review asks again.
+            await client
+                .accountSalt()
+                .then((salt) => salt.kind === "ok" ? saveAccountSalt(deps.credentialsPath, salt.value) : undefined)
+                .catch(() => { });
+            out.write(forTerminal(login
+                ? `Signed in as ${login}.\n`
+                : `Signed in; the login is unknown${unknown ? ` (${unknown})` : ""}: ocra whoami asks again.\n`));
+            return EXIT.ok;
+        }
+        if (t.error === "authorization_pending")
+            continue;
+        if (t.error === "slow_down") {
+            interval = typeof t.interval === "number" ? t.interval * 1000 : interval + 5000;
+            continue;
+        }
+        if (t.error === "access_denied") {
+            err.write("Login denied in the browser.\n");
+            return EXIT.notSignedIn;
+        }
+        if (t.error === "expired_token")
+            break;
+        err.write(forTerminal(`Login failed: ${t.error ?? `HTTP ${t.status}`}\n`));
+        return EXIT.error;
+    }
+    err.write("The code expired before it was confirmed. Run ocra login again.\n");
+    return EXIT.notSignedIn;
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/memory.d.ts

@@ -0,0 +1,3 @@
+import type { Output } from "../io/output.js";
+export declare function memoryCommand(argv: string[], out: Output, cwd: string, now?: Date): Promise<number>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/{memory.js → commands/memory.js}

@@ -1,13 +1,14 @@
 import { constants, existsSync } from "node:fs";
-import { lstat, mkdir, open, readdir, readFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { MEMORY_PATH, parseMemory, serializeMemory } from "@open-cr-agent/core/internal";
+import { isNotFound, MEMORY_PATH, parseMemory, readReport, serializeMemory, } from "@open-cr-agent/core/internal";
 import { findRepositoryRoot } from "@open-cr-agent/vcs-local/internal";
-import { UsageError } from "./review/args.js";
-import { SESSIONS_DIR } from "./review/command.js";
-import { forTerminal } from "./review/terminal.js";
-export const MEMORY_USAGE = `Usage: ocra memory <command>
+import { EXIT } from "../io/exit.js";
+import { forTerminal } from "../io/terminal.js";
+import { UsageError } from "../io/usage-error.js";
+import { listSessions, reportPath, SESSIONS_DIR, sessionsDir } from "../session/store.js";
+const MEMORY_USAGE = `Usage: ocra memory <command>
 
 Remember findings the team accepts, so ocra stops reporting them.
 Entries live in ${MEMORY_PATH}; commit it to share them.
@@ -31,7 +32,7 @@ export async function memoryCommand(argv, out, cwd, now = new Date()) {
     const [command, id] = positionals;
     if (values.help || command === undefined) {
         out.write(MEMORY_USAGE);
-        return 0;
+        return EXIT.ok;
     }
     const root = await findRepositoryRoot(cwd);
     const memory = await readMemory(root);
@@ -41,7 +42,7 @@ export async function memoryCommand(argv, out, cwd, now = new Date()) {
         for (const e of memory) {
             out.write(forTerminal(`${e.fingerprint.slice(0, 8)}  ${e.file}  ${e.title}\n    ${e.reason}\n`));
         }
-        return 0;
+        return EXIT.ok;
     }
     if (command !== "add")
         throw new UsageError(`Unknown memory command: ${command}`);
@@ -50,10 +51,10 @@ export async function memoryCommand(argv, out, cwd, now = new Date()) {
     if (!values.reason?.trim())
         throw new UsageError("ocra memory add needs --reason");
     const report = values.session ? resolve(cwd, values.session) : await newestSession(root);
-    const finding = await findFinding(join(report, "report.json"), id);
+    const finding = await findFinding(reportPath(report), id);
     if (memory.some((e) => e.fingerprint === finding.fingerprint)) {
         out.write(`Already remembered: ${forTerminal(finding.title)}\n`);
-        return 0;
+        return EXIT.ok;
     }
     const entry = {
         fingerprint: finding.fingerprint,
@@ -64,7 +65,7 @@ export async function memoryCommand(argv, out, cwd, now = new Date()) {
     };
     await writeRepositoryFile(root, MEMORY_PATH, serializeMemory([...memory, entry]));
     out.write(forTerminal(`Remembered ${finding.fingerprint.slice(0, 8)}: ${finding.title}\nCommit ${MEMORY_PATH} to share it.\n`));
-    return 0;
+    return EXIT.ok;
 }
 // The repository may be someone else's clone: a planted symlink at
 // .ocra/memory.json, or at .ocra, must not make ocra write elsewhere.
@@ -89,26 +90,26 @@ async function readMemory(root) {
         return parseMemory(await readFile(join(root, MEMORY_PATH), "utf8"));
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (isNotFound(error))
             return [];
         throw error;
     }
 }
 async function newestSession(root) {
-    const dir = join(root, SESSIONS_DIR);
-    const sessions = (await readdir(dir).catch(() => [])).filter((n) => !n.startsWith(".")).sort();
+    const dir = sessionsDir(root);
     // An interrupted run leaves a session without a report.
-    for (const name of sessions.reverse()) {
-        if (existsSync(join(dir, name, "report.json")))
+    for (const name of (await listSessions(dir)).reverse()) {
+        if (existsSync(reportPath(join(dir, name))))
             return join(dir, name);
     }
     throw new UsageError(`No finished review in ${SESSIONS_DIR}; run ocra review first`);
 }
 async function findFinding(reportPath, id) {
-    const report = JSON.parse(await readFile(reportPath, "utf8"));
-    const matches = (report.findings ?? []).filter((f) => f.fingerprint.startsWith(id));
-    if (matches.length === 1)
-        return matches[0];
+    const report = await readReport(reportPath);
+    const matches = report.findings.filter((f) => f.fingerprint.startsWith(id));
+    const [only] = matches;
+    if (only && matches.length === 1)
+        return only;
     throw new UsageError(matches.length === 0
         ? `No finding ${id} in ${reportPath}`
         : `${id} matches ${matches.length} findings; use more characters`);