@manyoars/oars 0.0.0-stage → 0.1.1

package/dist/commands/deploy-input.js

@@ -0,0 +1,107 @@
+import { readFile } from 'node:fs/promises';
+import { CliError, ExitCode } from '../errors.js';
+const usage = (message) => new CliError(message, ExitCode.USAGE, 'usage');
+const DIGEST = /@sha256:[0-9a-f]{64}$/;
+const PRICE_KINDS = ['ONE_TIME', 'RECURRING_MONTHLY', 'CREDIT_PACK'];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const has = (value, key, type) => typeof Reflect.get(value, key) === type;
+const isService = (value) => isObject(value) && has(value, 'name', 'string') && has(value, 'image', 'string') && has(value, 'cpuMillicores', 'number') && has(value, 'memoryMib', 'number');
+const isRegisterRequest = (value) => {
+    if (!isObject(value) || !has(value, 'name', 'string'))
+        return false;
+    const services = Reflect.get(value, 'services');
+    return Array.isArray(services) && services.length > 0 && services.every(isService);
+};
+const isPriceKind = (value) => PRICE_KINDS.some((kind) => kind === value);
+const isPrice = (value) => isObject(value) && has(value, 'priceRef', 'string') && has(value, 'displayName', 'string') && has(value, 'amountUsd', 'string') && isPriceKind(Reflect.get(value, 'kind'));
+const isPrices = (value) => Array.isArray(value) && value.every(isPrice);
+/** A JSON file's parsed content; a file that cannot be read or parsed is exit 2 naming it. */
+const readJson = async (path) => {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw usage(`Cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw usage(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+/** The platform deploys what a digest names; a tag can move, so a service without one is refused before any request. */
+const requireDigest = (image) => {
+    if (!DIGEST.test(image)) {
+        throw usage(`${image} is not pinned by digest. Print one with: docker buildx imagetools inspect ${image}\nthen deploy <name>@sha256:<64 hex digits>.`);
+    }
+};
+const secretsFrom = (flags, env) => [
+    ...flags.secrets.map((entry) => {
+        const at = entry.indexOf('=');
+        // The entry may be the secret itself, so the message does not echo it.
+        if (at < 1)
+            throw usage('--secret takes NAME=value; use --secret-from-env NAME to read the value from the environment.');
+        return { name: entry.slice(0, at), value: entry.slice(at + 1) };
+    }),
+    ...flags.secretsFromEnv.map((name) => {
+        const value = env[name];
+        if (value === undefined || value === '')
+            throw usage(`--secret-from-env ${name}: the environment variable ${name} is not set.`);
+        return { name, value };
+    }),
+];
+const requestFromFlags = (flags, image) => {
+    if (flags.name === undefined)
+        throw usage('--image needs --name <name>.');
+    requireDigest(image);
+    return {
+        name: flags.name,
+        ...(flags.alwaysOn === true ? { alwaysOn: true } : {}),
+        services: [{ name: 'app', image, port: flags.port ?? 8080, public: flags.public ?? false, cpuMillicores: flags.cpuMillicores ?? 250, memoryMib: flags.memoryMib ?? 256 }],
+    };
+};
+const requestFromFile = async (flags, path) => {
+    const given = ['name', 'port', 'public', 'cpuMillicores', 'memoryMib'].filter((key) => flags[key] !== undefined);
+    if (given.length > 0)
+        throw usage('--name, --port, --public, --cpu-millicores and --memory-mib describe an --image deploy; a --manifest file holds its own.');
+    const parsed = await readJson(path);
+    if (!isRegisterRequest(parsed)) {
+        throw usage(`${path} is not a workload manifest: it needs a name and services, each with name, image, cpuMillicores and memoryMib.`);
+    }
+    for (const service of parsed.services)
+        requireDigest(service.image);
+    return flags.alwaysOn === true ? { ...parsed, alwaysOn: true } : parsed;
+};
+const pricesFromFile = async (path) => {
+    const parsed = await readJson(path);
+    if (!isPrices(parsed)) {
+        throw usage(`${path} must be a JSON array of prices, each with priceRef, displayName, amountUsd (a decimal string) and kind (ONE_TIME, RECURRING_MONTHLY or CREDIT_PACK).`);
+    }
+    return parsed;
+};
+const baseRequest = async (flags) => {
+    if (flags.image !== undefined)
+        return requestFromFlags(flags, flags.image);
+    if (flags.manifestFile !== undefined)
+        return requestFromFile(flags, flags.manifestFile);
+    throw usage('--template is not available yet: the public API does not publish the template catalog. Deploy with --image <name@sha256:...> --name <name>, or with --manifest <file>.');
+};
+/**
+ * Turns the flags into the calls' bodies without touching the network, so a mistake costs nothing. Exactly one of
+ * `--template`, `--image`, `--manifest`; `--template` waits for the public template catalog (the `oars templates` brief).
+ */
+export const loadDeployInput = async (flags, env) => {
+    if ([flags.template, flags.image, flags.manifestFile].filter((source) => source !== undefined).length !== 1) {
+        throw usage('Pass exactly one of --template, --image or --manifest.');
+    }
+    const base = await baseRequest(flags);
+    if (flags.prices.length > 0 || flags.noPrices)
+        throw usage("--price and --no-prices choose among a template's starter prices; use --price-file with --image or --manifest.");
+    const secrets = [...(base.secrets ?? []), ...secretsFrom(flags, env)];
+    return {
+        request: secrets.length === 0 ? base : { ...base, secrets },
+        prices: flags.priceFile === undefined ? [] : await pricesFromFile(flags.priceFile),
+    };
+};

package/dist/commands/deploy.d.ts

@@ -0,0 +1,22 @@
+import { type DeployFlags } from './deploy-input.js';
+import type { Outcome, RunDeps } from '../cli.js';
+export interface DeployOptions extends DeployFlags {
+    apiUrl: string;
+    /** The command line as typed (without the node and script entries), for the rerun line. */
+    argv: string[];
+    /** False for `--no-start`: register and price, but make no deploy call. */
+    start: boolean;
+    /** `--idempotency-key`: the base of every step's key. A fresh UUID when absent. */
+    idempotencyKey?: string;
+}
+/**
+ * The command that resumes a failed deploy: the same arguments plus `--idempotency-key <base>`. Secret values are never
+ * printed, so `--secret NAME=value` becomes `--secret-from-env NAME` (the developer exports NAME before the rerun).
+ */
+export declare const rerunCommand: (argv: string[], base: string) => string;
+/**
+ * The web deploy page's order: register, each price, deploy (design §3.1). Each call carries its own idempotency key
+ * (`stepKey(base, step)`), so a rerun with the same base replays what finished and carries on. The first failed step stops
+ * the sequence (exit 9) with the workload id, the rerun line, and the SDK key when this run minted it.
+ */
+export declare const deploy: (deps: RunDeps, options: DeployOptions) => Promise<Outcome>;

package/dist/commands/deploy.js

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto';
+import { apiClient, unwrap } from '../api.js';
+import { CliError, ExitCode } from '../errors.js';
+import { stepKey } from '../journal.js';
+import { resolveAuthToken } from '../session.js';
+import { loadDeployInput } from './deploy-input.js';
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+const quote = (token) => (SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", "'\\''")}'`);
+/**
+ * The command that resumes a failed deploy: the same arguments plus `--idempotency-key <base>`. Secret values are never
+ * printed, so `--secret NAME=value` becomes `--secret-from-env NAME` (the developer exports NAME before the rerun).
+ */
+export const rerunCommand = (argv, base) => {
+    const secretName = (entry) => entry.split('=')[0] ?? '';
+    const tokens = [];
+    for (let at = 0; at < argv.length; at += 1) {
+        const arg = argv[at] ?? '';
+        if (arg === '--idempotency-key') {
+            at += 1;
+        }
+        else if (arg === '--secret') {
+            at += 1;
+            tokens.push('--secret-from-env', secretName(argv[at] ?? ''));
+        }
+        else if (arg.startsWith('--secret=')) {
+            tokens.push('--secret-from-env', secretName(arg.slice('--secret='.length)));
+        }
+        else if (!arg.startsWith('--idempotency-key=')) {
+            tokens.push(arg);
+        }
+    }
+    return ['oars', ...tokens, '--idempotency-key', base].map(quote).join(' ');
+};
+/** A failure after register is exit 9 whatever its own code: the workload exists, so the developer's next move is the rerun. */
+const partialFailure = (error, step, partial) => {
+    const cause = error instanceof CliError ? error : new CliError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, ExitCode.UNEXPECTED, step);
+    return new CliError(cause.message, ExitCode.PARTIAL, step, cause.problem, partial);
+};
+/**
+ * The web deploy page's order: register, each price, deploy (design §3.1). Each call carries its own idempotency key
+ * (`stepKey(base, step)`), so a rerun with the same base replays what finished and carries on. The first failed step stops
+ * the sequence (exit 9) with the workload id, the rerun line, and the SDK key when this run minted it.
+ */
+export const deploy = async (deps, options) => {
+    const input = await loadDeployInput(options, deps.env);
+    const token = await resolveAuthToken(deps, options.apiUrl);
+    const base = options.idempotencyKey ?? randomUUID();
+    const clientFor = (step) => apiClient(deps, { apiUrl: options.apiUrl, step, token });
+    const prior = await deps.journal.read(base).catch(() => undefined);
+    const progress = { base, steps: prior?.steps ?? [] };
+    if (prior !== undefined) {
+        deps.io.stderr(`Resuming deploy ${base}: ${prior.steps.map((entry) => entry.step).join(', ') || 'nothing finished yet'} already done.\n`);
+    }
+    // The journal only tells the developer where the last run got to; the platform's replay is what makes the rerun correct, so
+    // a journal that cannot be written must not lose the one-time SDK key.
+    const note = async (step, status) => {
+        progress.steps = [...progress.steps.filter((entry) => entry.step !== step), { step, status }];
+        await deps.journal.write(progress).catch((error) => {
+            deps.io.stderr(`Could not record progress in the journal: ${error instanceof Error ? error.message : String(error)}\n`);
+        });
+    };
+    const registerResult = await clientFor('register').POST('/agents/workloads', {
+        params: { header: { 'Idempotency-Key': stepKey(base, 'register') } },
+        body: input.request,
+    });
+    const workload = unwrap('register', registerResult);
+    await note('register', registerResult.response.status);
+    // A replayed registration carries no key: only the run that created the workload can show it.
+    const partial = { workloadId: workload.id, ...(workload.sdkKey === undefined ? {} : { sdkKey: workload.sdkKey }), rerun: rerunCommand(options.argv, base) };
+    const path = { workloadId: workload.id };
+    const stages = [
+        ...input.prices.map((price) => {
+            const step = `price:${price.priceRef}`;
+            return {
+                step,
+                send: async () => {
+                    const result = await clientFor(step).POST('/billing/agents/{workloadId}/prices', { params: { path }, headers: { 'Idempotency-Key': stepKey(base, step) }, body: price });
+                    unwrap(step, result);
+                    return result.response.status;
+                },
+            };
+        }),
+        ...(options.start
+            ? [
+                {
+                    step: 'deploy',
+                    send: async () => {
+                        const result = await clientFor('deploy').POST('/agents/workloads/{workloadId}/deploy', { params: { path }, headers: { 'Idempotency-Key': stepKey(base, 'deploy') } });
+                        unwrap('deploy', result);
+                        return result.response.status;
+                    },
+                },
+            ]
+            : []),
+    ];
+    for (const stage of stages) {
+        let status;
+        try {
+            status = await stage.send();
+        }
+        catch (error) {
+            throw partialFailure(error, stage.step, partial);
+        }
+        await note(stage.step, status);
+    }
+    await deps.journal.delete(base).catch(() => undefined);
+    const prices = input.prices.map((price) => price.priceRef);
+    const nextSteps = [`oars status ${workload.id}`, `oars test-charge ${workload.id}${prices[0] === undefined ? '' : ` --price ${prices[0]}`}`];
+    const lines = [
+        `${options.start ? 'Deployed' : 'Registered'} ${workload.name} (workload ${workload.id})`,
+        ...(workload.sdkKey === undefined ? [] : [`SDK key (shown once; save it now): ${workload.sdkKey}`]),
+        ...(prices.length === 0 ? [] : [`Prices: ${prices.join(', ')}`]),
+        'Next:',
+        ...nextSteps.map((step) => `  ${step}`),
+    ];
+    return {
+        document: { ok: true, workloadId: workload.id, ...(workload.sdkKey === undefined ? {} : { sdkKey: workload.sdkKey }), prices, started: options.start, nextSteps },
+        text: lines.join('\n'),
+    };
+};

package/dist/commands/login.d.ts

@@ -0,0 +1,10 @@
+import type { Outcome, RunDeps } from '../cli.js';
+export interface LoginOptions {
+    apiUrl: string;
+    /** `--issuer-url`; `OARS_ISSUER_URL` when absent. There is no production default until one is ruled. */
+    issuerUrl?: string;
+    /** False for `--no-browser`. */
+    browser: boolean;
+}
+/** RFC 8628 device flow on Keycloak, then the exchange; stores the credentials. */
+export declare const login: (deps: RunDeps, options: LoginOptions) => Promise<Outcome>;

package/dist/commands/login.js

@@ -0,0 +1,35 @@
+import { CliError, ExitCode } from '../errors.js';
+import { awaitDeviceTokens, discover, startDeviceAuthorization } from '../oidc.js';
+import { exchangeKeycloakToken } from '../session.js';
+const STEP = 'login';
+/** RFC 8628 device flow on Keycloak, then the exchange; stores the credentials. */
+export const login = async (deps, options) => {
+    const issuerUrl = options.issuerUrl ?? deps.env.OARS_ISSUER_URL;
+    if (issuerUrl === undefined || issuerUrl === '') {
+        throw new CliError('No Keycloak issuer URL: pass --issuer-url or set OARS_ISSUER_URL.', ExitCode.USAGE, 'usage');
+    }
+    const config = await discover(issuerUrl, { ...deps, step: STEP });
+    const device = await startDeviceAuthorization(config, STEP);
+    const url = device.verification_uri_complete ?? device.verification_uri;
+    deps.io.stderr(`To sign in, open ${url}\nand confirm the code ${device.user_code}\n`);
+    if (options.browser) {
+        await deps.openBrowser(url).catch(() => {
+            deps.io.stderr('Could not open a browser; open the link above yourself.\n');
+        });
+    }
+    const tokens = await awaitDeviceTokens(config, device, STEP);
+    if (tokens.refreshToken === undefined) {
+        throw new CliError('Keycloak returned no refresh token, so the login could not be kept.', ExitCode.UNEXPECTED, STEP);
+    }
+    const session = await exchangeKeycloakToken(deps, options.apiUrl, tokens.accessToken, STEP);
+    const email = session.user.email;
+    await deps.store.write({
+        issuerUrl,
+        apiUrl: options.apiUrl,
+        email,
+        refreshToken: tokens.refreshToken,
+        accessToken: session.accessToken,
+        expiresAt: session.expiresAt,
+    });
+    return { document: { ok: true, email }, text: `Logged in as ${email}` };
+};

package/dist/commands/logout.d.ts

@@ -0,0 +1,3 @@
+import type { Outcome, RunDeps } from '../cli.js';
+/** Revokes the stored refresh token at Keycloak, then deletes the credentials. A failed revocation still deletes them. */
+export declare const logout: (deps: RunDeps) => Promise<Outcome>;

package/dist/commands/logout.js

@@ -0,0 +1,17 @@
+import { discover, revokeRefreshToken } from '../oidc.js';
+const STEP = 'logout';
+/** Revokes the stored refresh token at Keycloak, then deletes the credentials. A failed revocation still deletes them. */
+export const logout = async (deps) => {
+    const stored = await deps.store.read();
+    if (stored !== undefined) {
+        try {
+            await revokeRefreshToken(await discover(stored.issuerUrl, { ...deps, step: STEP }), stored.refreshToken, STEP);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            deps.io.stderr(`The refresh token could not be revoked (${reason}); it stops working by itself when idle.\n`);
+        }
+    }
+    await deps.store.delete();
+    return { document: { ok: true }, text: 'Logged out' };
+};

package/dist/commands/status.d.ts

@@ -0,0 +1,7 @@
+import type { Outcome, RunDeps } from '../cli.js';
+export interface StatusOptions {
+    apiUrl: string;
+    workloadId: string;
+}
+/** The workload (`GET /agents/workloads/{id}`) and its billing mode (`GET /billing/agents/{id}/mode`, TEST until the creator goes live). */
+export declare const status: (deps: RunDeps, options: StatusOptions) => Promise<Outcome>;

package/dist/commands/status.js

@@ -0,0 +1,18 @@
+import { apiClient, unwrap } from '../api.js';
+import { resolveAuthToken } from '../session.js';
+const STEP = 'status';
+/** The workload (`GET /agents/workloads/{id}`) and its billing mode (`GET /billing/agents/{id}/mode`, TEST until the creator goes live). */
+export const status = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const params = { path: { workloadId: options.workloadId } };
+    const workload = unwrap(STEP, await client.GET('/agents/workloads/{workloadId}', { params }));
+    const { billingMode } = unwrap(STEP, await client.GET('/billing/agents/{workloadId}/mode', { params }));
+    const { deployment } = workload;
+    const lines = [
+        `${workload.name} (${workload.id})`,
+        `Workload: ${workload.status}${workload.suspended ? ' (suspended)' : ''}`,
+        `Deployment: ${deployment.status} (${deployment.health}), desired ${deployment.desiredState}`,
+        `Billing mode: ${billingMode}`,
+    ];
+    return { document: { ok: true, workload, billingMode }, text: lines.join('\n') };
+};

package/dist/commands/test-charge.d.ts

@@ -0,0 +1,11 @@
+import type { Outcome, RunDeps } from '../cli.js';
+export interface TestChargeOptions {
+    apiUrl: string;
+    workloadId: string;
+    /** `--price`; absent means the workload's one active price. */
+    priceRef?: string;
+    /** The base of the step key, so a retry of this command replays the charge instead of making a second one. */
+    idempotencyKey: string;
+}
+/** `POST /billing/agents/{id}/test-charges`: a TEST-mode charge against one of the workload's prices (no money moves). */
+export declare const testCharge: (deps: RunDeps, options: TestChargeOptions) => Promise<Outcome>;

package/dist/commands/test-charge.js

@@ -0,0 +1,34 @@
+import { apiClient, unwrap } from '../api.js';
+import { CliError, ExitCode } from '../errors.js';
+import { stepKey } from '../journal.js';
+import { resolveAuthToken } from '../session.js';
+const STEP = 'test-charge';
+/** The price a charge without `--price` uses: the workload's only active one, else exit 2 saying which to pick from. */
+const onlyActivePrice = async (client, workloadId) => {
+    const page = unwrap(STEP, await client.GET('/billing/agents/{workloadId}/prices', { params: { path: { workloadId }, query: { size: 100 } } }));
+    const active = page.content.filter((price) => price.active).map((price) => price.priceRef);
+    if (!page.last) {
+        throw new CliError(`${workloadId} has more prices than one request lists; pass --price <priceRef>.`, ExitCode.USAGE, 'usage');
+    }
+    const [only, ...others] = active;
+    if (only === undefined) {
+        throw new CliError(`${workloadId} has no active price; create one, or pass --price <priceRef>.`, ExitCode.USAGE, 'usage');
+    }
+    if (others.length > 0) {
+        throw new CliError(`${workloadId} has several active prices (${active.join(', ')}); pass --price <priceRef>.`, ExitCode.USAGE, 'usage');
+    }
+    return only;
+};
+/** `POST /billing/agents/{id}/test-charges`: a TEST-mode charge against one of the workload's prices (no money moves). */
+export const testCharge = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const priceRef = options.priceRef ?? (await onlyActivePrice(client, options.workloadId));
+    const charge = unwrap(STEP, await client.POST('/billing/agents/{workloadId}/test-charges', {
+        params: { path: { workloadId: options.workloadId }, header: { 'Idempotency-Key': stepKey(options.idempotencyKey, STEP) } },
+        body: { priceRef },
+    }));
+    return {
+        document: { ok: true, chargeId: charge.chargeId, status: charge.status },
+        text: `Test charge ${charge.chargeId} for ${priceRef}: ${charge.status}`,
+    };
+};

package/dist/credentials.d.ts

@@ -0,0 +1,28 @@
+/** What `oars login` keeps: the Keycloak refresh token and the platform access token the exchange returned for it. */
+export interface StoredCredentials {
+    issuerUrl: string;
+    apiUrl: string;
+    email: string;
+    refreshToken: string;
+    accessToken: string;
+    /** When `accessToken` stops working (ISO 8601). */
+    expiresAt: string;
+}
+export interface CredentialStore {
+    /** Undefined when nobody is logged in, including when the file is unreadable as credentials. */
+    read: () => Promise<StoredCredentials | undefined>;
+    /** Replaces the file atomically, owner-only. */
+    write: (credentials: StoredCredentials) => Promise<void>;
+    delete: () => Promise<void>;
+}
+/**
+ * `%APPDATA%` on Windows (the user-profile ACL keeps it private), `$XDG_CONFIG_HOME` or `~/.config` elsewhere. An empty or
+ * relative value counts as unset, as the XDG spec has it: a relative one would put the credentials under the cwd, which
+ * could be a git checkout.
+ */
+export declare const defaultConfigDir: (env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string) => string;
+/**
+ * Keeps the credentials in `<dir>/oars/credentials.json`, mode 0600 (design §3.4). A write goes to a fresh sibling file, is
+ * synced, then renamed over the old one, so a crash leaves either the old credentials or the new, never half of either.
+ */
+export declare const fileCredentialStore: (dir: string) => CredentialStore;

package/dist/credentials.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { join, posix, win32 } from 'node:path';
+const hasString = (value, key) => key in value && typeof Reflect.get(value, key) === 'string';
+const isStoredCredentials = (value) => typeof value === 'object' &&
+    value !== null &&
+    hasString(value, 'issuerUrl') &&
+    hasString(value, 'apiUrl') &&
+    hasString(value, 'email') &&
+    hasString(value, 'refreshToken') &&
+    hasString(value, 'accessToken') &&
+    hasString(value, 'expiresAt');
+const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/**
+ * `%APPDATA%` on Windows (the user-profile ACL keeps it private), `$XDG_CONFIG_HOME` or `~/.config` elsewhere. An empty or
+ * relative value counts as unset, as the XDG spec has it: a relative one would put the credentials under the cwd, which
+ * could be a git checkout.
+ */
+export const defaultConfigDir = (env, platform, home) => {
+    const windows = platform === 'win32';
+    const configured = windows ? env.APPDATA : env.XDG_CONFIG_HOME;
+    if (configured !== undefined && (windows ? win32 : posix).isAbsolute(configured))
+        return configured;
+    return windows ? join(home, 'AppData', 'Roaming') : join(home, '.config');
+};
+/**
+ * Keeps the credentials in `<dir>/oars/credentials.json`, mode 0600 (design §3.4). A write goes to a fresh sibling file, is
+ * synced, then renamed over the old one, so a crash leaves either the old credentials or the new, never half of either.
+ */
+export const fileCredentialStore = (dir) => {
+    const folder = join(dir, 'oars');
+    const file = join(folder, 'credentials.json');
+    return {
+        read: async () => {
+            let text;
+            try {
+                text = await readFile(file, 'utf8');
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return undefined;
+                throw error;
+            }
+            try {
+                const parsed = JSON.parse(text);
+                return isStoredCredentials(parsed) ? parsed : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write: async (credentials) => {
+            await mkdir(folder, { recursive: true, mode: 0o700 });
+            const temp = join(folder, `credentials.${randomUUID()}.tmp`);
+            try {
+                const handle = await open(temp, 'wx', 0o600);
+                try {
+                    await handle.writeFile(`${JSON.stringify(credentials, null, 2)}\n`);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temp, file);
+            }
+            catch (error) {
+                await rm(temp, { force: true });
+                throw error;
+            }
+        },
+        delete: () => rm(file, { force: true }),
+    };
+};

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+import type { components } from '@manyoars/oars-client';
+export type ProblemDetail = components['schemas']['ProblemDetail'];
+/** Design §3.2's exit-code table. */
+export declare const ExitCode: {
+    readonly OK: 0;
+    readonly UNEXPECTED: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly INVALID: 4;
+    readonly CONFLICT: 5;
+    readonly HUMAN: 6;
+    readonly RATE_LIMITED: 7;
+    readonly UNREACHABLE: 8;
+    readonly PARTIAL: 9;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/** The exit code for a failed response. The problem's code (then its type) decides; the status covers what has none. Text is never read. */
+export declare const exitCodeForProblem: (status: number, problem?: ProblemDetail) => ExitCode;
+/** What a deploy that stopped after registering leaves behind: the workload, the key shown only once, and the command that resumes. */
+export interface PartialDeploy {
+    workloadId: string;
+    /** Only when the run that failed minted it: no rerun can show it again. */
+    sdkKey?: string;
+    rerun: string;
+}
+/** A failure the CLI reports and exits on. `step` names where it happened in `--json` documents. */
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    readonly step: string;
+    readonly problem: ProblemDetail;
+    readonly partial?: PartialDeploy | undefined;
+    constructor(message: string, exitCode: ExitCode, step: string, problem?: ProblemDetail, partial?: PartialDeploy | undefined);
+}
+/** Keeps the known string fields of a response body that should be a ProblemDetail; anything else (HTML from a proxy) is no problem. */
+export declare const toProblem: (body: unknown) => ProblemDetail | undefined;
+/** A CliError for a non-2xx response; its message is the problem's title, else detail, else the status. */
+export declare const problemError: (step: string, status: number, body: unknown) => CliError;
+/** A request that never got an answer (after the retries). */
+export declare const unreachableError: (step: string, cause: unknown) => CliError;

package/dist/errors.js

@@ -0,0 +1,73 @@
+/** Design §3.2's exit-code table. */
+export const ExitCode = {
+    OK: 0,
+    UNEXPECTED: 1,
+    USAGE: 2,
+    AUTH: 3,
+    INVALID: 4,
+    CONFLICT: 5,
+    HUMAN: 6,
+    RATE_LIMITED: 7,
+    UNREACHABLE: 8,
+    PARTIAL: 9,
+};
+const codes = (exit, ...names) => names.map((name) => [name, exit]);
+// Problem codes (or types) from spec 1 §13, T87 and T92. EXPIRED_TOKEN and ACCESS_DENIED are the device flow's own, raised locally.
+const BY_CODE = new Map([
+    ...codes(ExitCode.AUTH, 'SDK_KEY_INVALID', 'EXPIRED_TOKEN', 'ACCESS_DENIED'),
+    ...codes(ExitCode.INVALID, 'MANIFEST_INVALID', 'MULTI_SERVICE_DISABLED', 'PRICE_NOT_FOUND', 'PRICE_INACTIVE', 'FEE_POLICY_INVALID', 'LIVE_MODE_REQUIRED', 'TEST_MODE_ONLY'),
+    ...codes(ExitCode.CONFLICT, 'IDEMPOTENCY_CONFLICT', 'WORKLOAD_FINGERPRINT_EXISTS'),
+    ...codes(ExitCode.HUMAN, 'ACCOUNT_NOT_READY', 'PAYMENT_METHOD_REQUIRED', 'INSUFFICIENT_CREDITS', 'COMPUTE_CAP_REACHED'),
+    ...codes(ExitCode.RATE_LIMITED, 'RATE_LIMITED'),
+]);
+/** The exit code for a failed response. The problem's code (then its type) decides; the status covers what has none. Text is never read. */
+export const exitCodeForProblem = (status, problem) => {
+    const key = problem?.code ?? problem?.type;
+    const byCode = key === undefined ? undefined : BY_CODE.get(key);
+    if (byCode !== undefined)
+        return byCode;
+    if (status === 401 || status === 403)
+        return ExitCode.AUTH;
+    if (status === 400 || status === 422)
+        return ExitCode.INVALID;
+    if (status === 429)
+        return ExitCode.RATE_LIMITED;
+    if (status === 502 || status === 503 || status === 504)
+        return ExitCode.UNREACHABLE;
+    return ExitCode.UNEXPECTED;
+};
+/** A failure the CLI reports and exits on. `step` names where it happened in `--json` documents. */
+export class CliError extends Error {
+    exitCode;
+    step;
+    problem;
+    partial;
+    constructor(message, exitCode, step, problem = { title: message }, partial) {
+        super(message);
+        this.exitCode = exitCode;
+        this.step = step;
+        this.problem = problem;
+        this.partial = partial;
+        this.name = 'CliError';
+    }
+}
+/** Keeps the known string fields of a response body that should be a ProblemDetail; anything else (HTML from a proxy) is no problem. */
+export const toProblem = (body) => {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const problem = {};
+    for (const key of ['actionUrl', 'code', 'detail', 'title', 'type']) {
+        const value = Reflect.get(body, key);
+        if (typeof value === 'string')
+            problem[key] = value;
+    }
+    return problem;
+};
+/** A CliError for a non-2xx response; its message is the problem's title, else detail, else the status. */
+export const problemError = (step, status, body) => {
+    const problem = toProblem(body);
+    const message = problem?.title ?? problem?.detail ?? `The platform answered HTTP ${String(status)}`;
+    return new CliError(message, exitCodeForProblem(status, problem), step, { ...problem, title: message, status });
+};
+/** A request that never got an answer (after the retries). */
+export const unreachableError = (step, cause) => new CliError(`Cannot reach the server: ${cause instanceof Error ? cause.message : String(cause)}`, ExitCode.UNREACHABLE, step);

package/dist/journal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a command got to, for the rerun that follows a failure (design §3.2). It holds step names and the HTTP status each
+ * answered with, never a secret: the SDK key is shown once and the platform replays every finished step by its idempotency key.
+ */
+export interface JournalRecord {
+    /** The human base key (`--idempotency-key` or the UUID the first run made). */
+    base: string;
+    steps: Array<{
+        step: string;
+        status: number;
+    }>;
+}
+export interface JournalStore {
+    /** Undefined when no run with this base key has left a record, including when the file is unreadable as one. */
+    read: (base: string) => Promise<JournalRecord | undefined>;
+    write: (record: JournalRecord) => Promise<void>;
+    delete: (base: string) => Promise<void>;
+}
+/** One step's `Idempotency-Key`: the lowercase SHA-256 hex of `<base>:<step>`, the 64-hex form every aor-common interceptor accepts. */
+export declare const stepKey: (base: string, step: string) => string;
+/**
+ * Keeps one file per base key in `<dir>/oars/journal/`, named by the key's hash because the key is whatever the developer typed.
+ * A write goes to a sibling file and is renamed over the old one; a torn file reads as no record, and the platform's replay
+ * makes the rerun correct either way.
+ */
+export declare const fileJournalStore: (dir: string) => JournalStore;