@open-cr-agent/cli 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 `ocra` is the command line of [Open-CR-Agent](https://github.com/jma49/Open-CR-Agent), an open-source multi-agent code reviewer for local changes and GitHub pull requests. Deterministic code selects and bundles the files, matches rules and anchors comments; LLM reviewers make the judgment calls, and a verification pass checks what they report.
 
-This is an early 0.x release: options and output may change between minor versions. What the reviews find and miss is measured on the [quality page](https://ocra.majincheng.com/en/docs/quality).
+This is an early 0.x release: options and output may change between minor versions. What the reviews find and miss is measured on the [quality page](https://ocracloud.com/en/docs/quality).
 
 ## Install
 
@@ -34,8 +34,8 @@ Pull requests can also be reviewed by the GitHub Action: inline comments, one su
 
 ## Documentation
 
-- [Quickstart](https://ocra.majincheng.com/en/docs/quickstart) and the manual, in [English](https://ocra.majincheng.com/en/docs) and [中文](https://ocra.majincheng.com/zh/docs)
-- [GitHub pull requests](https://ocra.majincheng.com/en/docs/github)
+- [Quickstart](https://ocracloud.com/en/docs/quickstart) and the manual, in [English](https://ocracloud.com/en/docs) and [中文](https://ocracloud.com/zh/docs)
+- [GitHub pull requests](https://ocracloud.com/en/docs/github)
 - [Changelog](https://github.com/jma49/Open-CR-Agent/blob/main/CHANGELOG.md) and [issues](https://github.com/jma49/Open-CR-Agent/issues)
 
 ## License

package/dist/account-salt.d.ts

@@ -0,0 +1,7 @@
+import type { CloudDeps } from "./cloud.js";
+export declare function accountSaltPath(credentialsPath: string): string;
+/** The account's salt, or null; throws when the server cannot be asked. */
+export declare function fetchAccountSalt(deps: Pick<CloudDeps, "fetch">, server: string, token: string): Promise<string | null>;
+/** 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>;
+//# sourceMappingURL=account-salt.d.ts.map

package/dist/account-salt.js

@@ -0,0 +1,43 @@
+import { chmod, mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { VERSION } from "./version.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.
+const SALT = /^[0-9a-f]{64}$/;
+export function accountSaltPath(credentialsPath) {
+    return join(dirname(credentialsPath), "account-salt");
+}
+/** The account's salt, or null; throws when the server cannot be asked. */
+export async function fetchAccountSalt(deps, server, token) {
+    const res = await deps.fetch(`${server}/api/account/salt`, {
+        headers: { authorization: `Bearer ${token}`, "user-agent": `ocra/${VERSION}` },
+        signal: AbortSignal.timeout(15_000),
+    });
+    // A server without account salts shares no findings.
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    const body = (await res.json());
+    if (body.salt === null)
+        return null;
+    if (typeof body.salt === "string" && SALT.test(body.salt))
+        return body.salt;
+    throw new Error("the answer is not a 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 mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${salt}\n`, { mode: 0o600 });
+    // writeFile keeps the mode of a file that already exists.
+    await chmod(path, 0o600);
+}
+//# sourceMappingURL=account-salt.js.map

package/dist/cloud.d.ts

@@ -0,0 +1,34 @@
+import type { Output } from "./review/progress.js";
+/** ocra Cloud's address; OCRA_CLOUD_URL names another server. */
+export declare const DEFAULT_CLOUD_URL = "https://app.ocracloud.com";
+export declare const LOGIN_USAGE: string;
+export type Credentials = {
+    server: string;
+    login: string;
+    access_token: string;
+    refresh_token: string;
+    /** Epoch milliseconds when the access token expires. */
+    expires_at: number;
+};
+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 credentialsPath(env: CloudDeps["env"]): string;
+/** ~/.config/ocra ($XDG_CONFIG_HOME/ocra), or %APPDATA%\ocra on Windows: this machine's own. */
+export declare function ocraConfigDir(env: CloudDeps["env"]): string;
+export declare function readCredentials(path: string): Promise<Credentials | undefined>;
+/**
+ * The saved session with a live access token, refreshed (and saved) when
+ * it has expired or is about to; undefined when not signed in or the
+ * session was revoked.
+ */
+export declare function cloudSession(deps: CloudDeps, minValidityMs?: number): Promise<Credentials | undefined>;
+export declare function cloudCommand(command: "login" | "logout" | "whoami", argv: string[], out: Output, err: Output, deps: CloudDeps): Promise<number>;
+//# sourceMappingURL=cloud.d.ts.map

package/dist/cloud.js

@@ -0,0 +1,272 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { errorMessage } from "@open-cr-agent/core/internal";
+import { fetchAccountSalt, saveAccountSalt } from "./account-salt.js";
+import { UsageError } from "./review/args.js";
+import { forTerminal } from "./review/terminal.js";
+import { VERSION } from "./version.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.
+/** ocra Cloud's address; OCRA_CLOUD_URL names another server. */
+export const DEFAULT_CLOUD_URL = "https://app.ocracloud.com";
+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 function defaultCloudDeps(env = process.env) {
+    return {
+        env,
+        fetch: globalThis.fetch,
+        now: Date.now,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        openBrowser,
+        credentialsPath: credentialsPath(env),
+        clientName: `${hostname()} (ocra ${VERSION})`,
+    };
+}
+function credentialsHint() {
+    return process.platform === "win32"
+        ? "%APPDATA%\\ocra\\credentials.json"
+        : "~/.config/ocra/credentials.json";
+}
+export function credentialsPath(env) {
+    return join(ocraConfigDir(env), "credentials.json");
+}
+/** ~/.config/ocra ($XDG_CONFIG_HOME/ocra), or %APPDATA%\ocra on Windows: this machine's own. */
+export function ocraConfigDir(env) {
+    const base = process.platform === "win32"
+        ? (env.APPDATA ?? join(homedir(), "AppData", "Roaming"))
+        : (env.XDG_CONFIG_HOME ?? join(homedir(), ".config"));
+    return join(base, "ocra");
+}
+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;
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(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.
+    }
+}
+export async function readCredentials(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const c = JSON.parse(text);
+    if (!c.server || !c.access_token || !c.refresh_token || typeof c.expires_at !== "number") {
+        return undefined;
+    }
+    return c;
+}
+async function writeCredentials(path, c) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(c, null, 2)}\n`, { mode: 0o600 });
+    // writeFile keeps the mode of a file that already exists.
+    await chmod(path, 0o600);
+}
+async function postJson(deps, url, body, token) {
+    const res = await deps.fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "user-agent": `ocra/${VERSION}`,
+            ...(token ? { authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30_000),
+    });
+    return {
+        status: res.status,
+        body: (await res.json().catch(() => ({}))),
+    };
+}
+async function fetchMe(deps, server, token) {
+    const res = await deps.fetch(`${server}/api/me`, {
+        headers: { authorization: `Bearer ${token}`, "user-agent": `ocra/${VERSION}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (res.status === 401)
+        return undefined;
+    if (!res.ok)
+        throw new Error(`ocra Cloud answered ${res.status}`);
+    return (await res.json());
+}
+/**
+ * The saved session with a live access token, refreshed (and saved) when
+ * it has expired or is about to; undefined when not signed in or the
+ * session was revoked.
+ */
+export async function cloudSession(deps, minValidityMs = 60_000) {
+    const saved = await readCredentials(deps.credentialsPath);
+    if (!saved)
+        return undefined;
+    if (saved.expires_at - deps.now() > minValidityMs)
+        return saved;
+    const { status, body } = await postJson(deps, `${saved.server}/api/device/refresh`, {
+        refresh_token: saved.refresh_token,
+    });
+    const t = body;
+    if (status !== 200 || !t.access_token || !t.refresh_token || !t.expires_in)
+        return undefined;
+    const next = {
+        ...saved,
+        access_token: t.access_token,
+        refresh_token: t.refresh_token,
+        expires_at: deps.now() + t.expires_in * 1000,
+    };
+    await writeCredentials(deps.credentialsPath, next);
+    return next;
+}
+export async function cloudCommand(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 0;
+    }
+    if (deps.env.OCRA_CLOUD === "off") {
+        err.write("ocra Cloud is off (OCRA_CLOUD=off).\n");
+        return 2;
+    }
+    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 session = await cloudSession(deps);
+    if (!session) {
+        err.write("Not signed in. Run ocra login.\n");
+        return 1;
+    }
+    const me = await fetchMe(deps, session.server, session.access_token);
+    if (!me) {
+        err.write("The saved session was revoked. Run ocra login.\n");
+        return 1;
+    }
+    out.write(forTerminal(`${me.login} on ${session.server}\n`));
+    return 0;
+}
+async function logout(out, deps) {
+    const saved = await readCredentials(deps.credentialsPath);
+    if (saved) {
+        // Ends the session on the server too; the local file goes either way.
+        const session = await cloudSession(deps).catch(() => undefined);
+        if (session) {
+            await postJson(deps, `${session.server}/api/auth/logout`, {}, session.access_token).catch(() => { });
+        }
+    }
+    await rm(deps.credentialsPath, { force: true });
+    await saveAccountSalt(deps.credentialsPath, null);
+    out.write(saved ? "Signed out.\n" : "Not signed in.\n");
+    return 0;
+}
+async function login(out, err, deps, browser) {
+    const server = cloudUrl(deps.env);
+    const start = await postJson(deps, `${server}/api/device/code`, { client_name: deps.clientName });
+    const code = start.body;
+    if (start.status !== 200 ||
+        !code.device_code ||
+        !code.user_code ||
+        !code.verification_uri_complete) {
+        err.write(`ocra Cloud did not start a login (HTTP ${start.status}). Try again in a minute.\n`);
+        return 2;
+    }
+    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)
+        deps.openBrowser(code.verification_uri_complete);
+    let interval = (code.interval ?? 5) * 1000;
+    const deadline = deps.now() + (code.expires_in ?? 600) * 1000;
+    while (deps.now() < deadline) {
+        await deps.sleep(interval);
+        let answer;
+        try {
+            answer = await postJson(deps, `${server}/api/device/token`, {
+                device_code: code.device_code,
+            });
+        }
+        catch (error) {
+            // A dropped connection is retried on the next tick.
+            err.write(forTerminal(`(${errorMessage(error)}; retrying)\n`));
+            continue;
+        }
+        const t = answer.body;
+        if (answer.status === 200 && t.access_token && t.refresh_token && t.expires_in) {
+            const me = await fetchMe(deps, server, t.access_token);
+            const credentials = {
+                server,
+                login: me?.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 fetchAccountSalt(deps, server, t.access_token)
+                .then((salt) => saveAccountSalt(deps.credentialsPath, salt))
+                .catch(() => { });
+            out.write(forTerminal(`Signed in as ${credentials.login}.\n`));
+            return 0;
+        }
+        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 1;
+        }
+        if (t.error === "expired_token")
+            break;
+        err.write(forTerminal(`Login failed: ${t.error ?? `HTTP ${answer.status}`}\n`));
+        return 2;
+    }
+    err.write("The code expired before it was confirmed. Run ocra login again.\n");
+    return 1;
+}
+//# sourceMappingURL=cloud.js.map

package/dist/plugin-store.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare function isPackageName(name: string): boolean;
+export declare function isExactVersion(version: string): boolean;
+declare const allowedSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    integrity: z.ZodString;
+}, z.core.$strict>;
+export type AllowedPlugin = z.infer<typeof allowedSchema>;
+export declare function pluginsDir(env: Readonly<Record<string, string | undefined>>): string;
+export declare function readAllowed(dir: string): Promise<AllowedPlugin[]>;
+export declare function writeAllowed(dir: string, plugins: readonly AllowedPlugin[]): Promise<void>;
+export declare function ensureDir(dir: string): Promise<void>;
+/** What npm's lockfile in the directory says it installed for a package. */
+export declare function installedEntry(dir: string, name: string): Promise<{
+    version?: string;
+    integrity?: string;
+} | undefined>;
+export {};
+//# sourceMappingURL=plugin-store.d.ts.map

package/dist/plugin-store.js

@@ -0,0 +1,84 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { ocraConfigDir } from "./cloud.js";
+import { ConfigError } from "./review/config.js";
+// The plugins this machine allows its ocra Cloud account to name (ADR-0027):
+// installed by `ocra plugins allow` into a directory of the user's own, never
+// the reviewed checkout, and recorded with the integrity npm installed.
+// npm's package-name rules, less a leading "-" or "." that npm could read as
+// an option or a path; at most 214 characters.
+const PACKAGE_NAME = /^(?:@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*$/;
+// An exact version: no range, tag or URL.
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function isPackageName(name) {
+    return name.length <= 214 && PACKAGE_NAME.test(name);
+}
+export function isExactVersion(version) {
+    return version.length <= 256 && EXACT_VERSION.test(version);
+}
+const allowedSchema = z
+    .object({
+    name: z.string().refine(isPackageName),
+    version: z.string().refine(isExactVersion),
+    integrity: z.string().min(1),
+})
+    .strict();
+const fileSchema = z.object({ plugins: z.array(allowedSchema) }).strict();
+export function pluginsDir(env) {
+    return join(ocraConfigDir(env), "plugins");
+}
+export async function readAllowed(dir) {
+    let text;
+    try {
+        text = await readFile(join(dir, "plugins.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = undefined;
+    }
+    const parsed = fileSchema.safeParse(data);
+    if (!parsed.success) {
+        throw new ConfigError(`${join(dir, "plugins.json")} is invalid; allow the plugins again or remove it`);
+    }
+    return parsed.data.plugins;
+}
+export async function writeAllowed(dir, plugins) {
+    await ensureDir(dir);
+    const path = join(dir, "plugins.json");
+    const sorted = [...plugins].sort((a, b) => (a.name < b.name ? -1 : 1));
+    await writeFile(path, `${JSON.stringify({ plugins: sorted }, null, 2)}\n`, { mode: 0o600 });
+    // writeFile keeps the mode of a file that already exists.
+    await chmod(path, 0o600);
+}
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+}
+/** What npm's lockfile in the directory says it installed for a package. */
+export async function installedEntry(dir, name) {
+    let lock;
+    try {
+        lock = JSON.parse(await readFile(join(dir, "package-lock.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const entry = lock.packages?.[`node_modules/${name}`];
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const { version, integrity } = entry;
+    return {
+        ...(typeof version === "string" ? { version } : {}),
+        ...(typeof integrity === "string" ? { integrity } : {}),
+    };
+}
+//# sourceMappingURL=plugin-store.js.map

package/dist/plugins-command.d.ts

@@ -0,0 +1,15 @@
+import type { Output } from "./review/progress.js";
+export declare const PLUGINS_USAGE = "Usage: ocra plugins allow <name>@<version>\n       ocra plugins deny <name>\n       ocra plugins list\n\nYour ocra Cloud settings may name plugins; a review loads one only if this\nmachine allows it. allow shows the package and who published it, installs that\nexact version with install scripts off into a directory of your own, and\nrecords its integrity; deny removes it.\n";
+/** Runs npm with these arguments, never through a shell; resolves with its standard output. */
+export type NpmRunner = (args: readonly string[]) => Promise<string>;
+export interface PluginsDeps {
+    dir: string;
+    npm: NpmRunner;
+}
+export declare function pluginsCommand(argv: readonly string[], out: Output, deps: PluginsDeps): Promise<number>;
+export declare function parseSpec(spec: string): {
+    name: string;
+    version: string;
+};
+export declare function defaultNpm(env?: NodeJS.ProcessEnv): NpmRunner;
+//# sourceMappingURL=plugins-command.d.ts.map