@manyoars/oars 0.0.0-stage → 0.1.1

package/dist/journal.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** One step's `Idempotency-Key`: the lowercase SHA-256 hex of `<base>:<step>`, the 64-hex form every aor-common interceptor accepts. */
+export const stepKey = (base, step) => createHash('sha256').update(`${base}:${step}`).digest('hex');
+const isRecord = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const base = Reflect.get(value, 'base');
+    const steps = Reflect.get(value, 'steps');
+    return (typeof base === 'string' &&
+        Array.isArray(steps) &&
+        steps.every((entry) => typeof entry === 'object' && entry !== null && typeof Reflect.get(entry, 'step') === 'string' && typeof Reflect.get(entry, 'status') === 'number'));
+};
+const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/**
+ * 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 const fileJournalStore = (dir) => {
+    const folder = join(dir, 'oars', 'journal');
+    const fileFor = (base) => join(folder, `${createHash('sha256').update(base).digest('hex')}.json`);
+    return {
+        read: async (base) => {
+            let text;
+            try {
+                text = await readFile(fileFor(base), 'utf8');
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return undefined;
+                throw error;
+            }
+            try {
+                const parsed = JSON.parse(text);
+                return isRecord(parsed) && parsed.base === base ? parsed : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write: async (record) => {
+            await mkdir(folder, { recursive: true, mode: 0o700 });
+            const file = fileFor(record.base);
+            const temp = `${file}.tmp`;
+            try {
+                await writeFile(temp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+                await rename(temp, file);
+            }
+            catch (error) {
+                await rm(temp, { force: true });
+                throw error;
+            }
+        },
+        delete: (base) => rm(fileFor(base), { force: true }),
+    };
+};

package/dist/oidc.d.ts

@@ -0,0 +1,26 @@
+import * as client from 'openid-client';
+import { type RetryDeps } from './retry.js';
+/** The public Keycloak client T67 registers for the CLI: device authorization grant only. */
+export declare const CLIENT_ID = "oars-cli";
+export interface OidcContext extends RetryDeps {
+    /** The CLI's version, sent as `User-Agent: oars/<version>`. */
+    version: string;
+    /** Names where a failure happened in `--json` documents. */
+    step: string;
+}
+/** What the CLI keeps of a Keycloak token response. */
+export interface KeycloakTokens {
+    accessToken: string;
+    /** Absent when the realm did not rotate it. */
+    refreshToken?: string;
+}
+/** Keycloak discovery for the realm at `issuerUrl`. Plain http is accepted for a loopback issuer only (the local stack). */
+export declare const discover: (issuerUrl: string, context: OidcContext) => Promise<client.Configuration>;
+/** RFC 8628: asks Keycloak for a device and user code. */
+export declare const startDeviceAuthorization: (config: client.Configuration, step: string) => Promise<client.DeviceAuthorizationResponse>;
+/** Polls until the developer approves the code, honoring `slow_down`; a denied or expired code is an exit-3 failure. */
+export declare const awaitDeviceTokens: (config: client.Configuration, device: client.DeviceAuthorizationResponse, step: string) => Promise<KeycloakTokens>;
+/** Exchanges the stored refresh token. Keycloak rotates it, so the caller persists the new one before using the access token. */
+export declare const refreshTokens: (config: client.Configuration, refreshToken: string, step: string) => Promise<KeycloakTokens>;
+/** RFC 7009: revokes the refresh token, which ends the Keycloak session behind it. */
+export declare const revokeRefreshToken: (config: client.Configuration, refreshToken: string, step: string) => Promise<void>;

package/dist/oidc.js

@@ -0,0 +1,137 @@
+import * as client from 'openid-client';
+import { CliError, ExitCode, unreachableError } from './errors.js';
+import { retryingFetch } from './retry.js';
+/** The public Keycloak client T67 registers for the CLI: device authorization grant only. */
+export const CLIENT_ID = 'oars-cli';
+const SCOPE = 'openid email profile';
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Every call to Keycloak sends `User-Agent: oars/<version>` and gets design §3.2's retries, except the token endpoint:
+ * it rotates the refresh token, so a request it may have processed is never repeated blindly (device polling repeats
+ * by itself). `isTokenEndpoint` is told which URL that is once discovery has found it. A 502-504 or 429 that is still the
+ * answer once the retries are spent (or the token endpoint's single attempt) is design §3.2's exit 8 or 7 here, because
+ * handed on, the library would call it an unexpected status (exit 1).
+ */
+const keycloakFetch = ({ version, step, sleep, random }, isTokenEndpoint) => {
+    const retrying = retryingFetch((request) => fetch(request), { sleep, random });
+    return async (url, options) => {
+        const request = new Request(url, { ...options, headers: { ...options.headers, 'user-agent': `oars/${version}` } });
+        let response;
+        try {
+            response = await (isTokenEndpoint(url) ? fetch(request) : retrying(request));
+        }
+        catch (error) {
+            throw unreachableError(step, error);
+        }
+        const { status } = response;
+        if (status === 429 || status === 502 || status === 503 || status === 504) {
+            void response.body?.cancel().catch(() => undefined);
+            if (status === 429) {
+                const title = 'Keycloak is rate limiting this client. Wait a moment, then run the command again.';
+                throw new CliError(title, ExitCode.RATE_LIMITED, step, { code: 'RATE_LIMITED', title, status });
+            }
+            throw unreachableError(step, new Error(`Keycloak answered HTTP ${String(status)}`));
+        }
+        return response;
+    };
+};
+/** The CliError the library wrapped on its way out of our fetch, if any (it puts an unrecognized error in `cause`). */
+const wrapped = (error) => {
+    for (let current = error, depth = 0; current instanceof Error && depth < 5; current = current.cause, depth += 1) {
+        if (current instanceof CliError)
+            return current;
+    }
+    return undefined;
+};
+// OAuth errors that mean "sign in again" (exit 3), with the line the developer sees.
+const SIGN_IN_AGAIN = new Map([
+    ['invalid_grant', 'Your login has expired or was revoked. Run "oars login" to sign in again.'],
+    ['expired_token', 'The device code expired before it was approved. Run "oars login" again.'],
+    ['access_denied', 'Access was denied. Run "oars login" to try again.'],
+]);
+const signInAgain = (step, error) => {
+    const title = SIGN_IN_AGAIN.get(error) ?? error;
+    return new CliError(title, ExitCode.AUTH, step, { code: error.toUpperCase(), title });
+};
+const failure = (step, error) => {
+    const own = wrapped(error);
+    if (own !== undefined)
+        return own;
+    if (error instanceof client.ResponseBodyError) {
+        if (SIGN_IN_AGAIN.has(error.error))
+            return signInAgain(step, error.error);
+        const title = `Keycloak refused the request: ${error.error_description ?? error.error}`;
+        return new CliError(title, ExitCode.UNEXPECTED, step, { code: error.error.toUpperCase(), title });
+    }
+    if (error instanceof client.ClientError && error.code === 'OAUTH_TIMEOUT')
+        return unreachableError(step, error);
+    return new CliError(error instanceof Error ? error.message : String(error), ExitCode.UNEXPECTED, step);
+};
+const usage = (message) => new CliError(message, ExitCode.USAGE, 'usage');
+/** Keycloak discovery for the realm at `issuerUrl`. Plain http is accepted for a loopback issuer only (the local stack). */
+export const discover = async (issuerUrl, context) => {
+    let issuer;
+    try {
+        issuer = new URL(issuerUrl);
+    }
+    catch {
+        throw usage(`The issuer URL "${issuerUrl}" is not a URL.`);
+    }
+    const loopback = issuer.protocol === 'http:' && LOOPBACK_HOSTS.has(issuer.hostname);
+    if (issuer.protocol !== 'https:' && !loopback)
+        throw usage(`The issuer URL must use https (http is accepted for localhost only): ${issuerUrl}`);
+    let tokenEndpoint;
+    try {
+        const config = await client.discovery(issuer, CLIENT_ID, undefined, client.None(), {
+            [client.customFetch]: keycloakFetch(context, (url) => tokenEndpoint !== undefined && new URL(url).href === tokenEndpoint),
+            execute: loopback ? [client.allowInsecureRequests] : [],
+        });
+        const endpoint = config.serverMetadata().token_endpoint;
+        tokenEndpoint = endpoint === undefined ? undefined : new URL(endpoint).href;
+        return config;
+    }
+    catch (error) {
+        throw failure(context.step, error);
+    }
+};
+const tokensOf = (response) => response.refresh_token === undefined ? { accessToken: response.access_token } : { accessToken: response.access_token, refreshToken: response.refresh_token };
+/** RFC 8628: asks Keycloak for a device and user code. */
+export const startDeviceAuthorization = async (config, step) => {
+    try {
+        return await client.initiateDeviceAuthorization(config, { scope: SCOPE });
+    }
+    catch (error) {
+        throw failure(step, error);
+    }
+};
+/** Polls until the developer approves the code, honoring `slow_down`; a denied or expired code is an exit-3 failure. */
+export const awaitDeviceTokens = async (config, device, step) => {
+    try {
+        return tokensOf(await client.pollDeviceAuthorizationGrant(config, device));
+    }
+    catch (error) {
+        // The library stops polling at the code's `expires_in`; that deadline is the expired code, not a network timeout.
+        if (error instanceof client.ClientError && error.code === 'OAUTH_TIMEOUT') {
+            throw signInAgain(step, 'expired_token');
+        }
+        throw failure(step, error);
+    }
+};
+/** Exchanges the stored refresh token. Keycloak rotates it, so the caller persists the new one before using the access token. */
+export const refreshTokens = async (config, refreshToken, step) => {
+    try {
+        return tokensOf(await client.refreshTokenGrant(config, refreshToken));
+    }
+    catch (error) {
+        throw failure(step, error);
+    }
+};
+/** RFC 7009: revokes the refresh token, which ends the Keycloak session behind it. */
+export const revokeRefreshToken = async (config, refreshToken, step) => {
+    try {
+        await client.tokenRevocation(config, refreshToken);
+    }
+    catch (error) {
+        throw failure(step, error);
+    }
+};

package/dist/retry.d.ts

@@ -0,0 +1,11 @@
+export interface RetryDeps {
+    sleep: (ms: number) => Promise<void>;
+    /** In [0, 1); scales each delay between half and one and a half times its base. */
+    random: () => number;
+}
+/**
+ * Wraps a fetch so a transient failure is retried three times with jittered exponential backoff, never sooner than the
+ * server's Retry-After. Every attempt sends a clone, so the body and the Idempotency-Key repeat exactly. After the last
+ * retry the final response is returned, or the final network error thrown.
+ */
+export declare const retryingFetch: (send: (request: Request) => Promise<Response>, { sleep, random }: RetryDeps) => (request: Request) => Promise<Response>;

package/dist/retry.js

@@ -0,0 +1,40 @@
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+/** Seconds, or an HTTP date, from a Retry-After header; undefined when absent or unreadable. */
+const retryAfterMs = (response) => {
+    const header = response.headers.get('Retry-After');
+    if (header === null || header.trim() === '')
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+};
+/** Design §3.2: network errors, 502-504 and a 429 that names a wait are retried; nothing else is. */
+const worthRetrying = (response) => response.status === 502 || response.status === 503 || response.status === 504 || (response.status === 429 && retryAfterMs(response) !== undefined);
+/**
+ * Wraps a fetch so a transient failure is retried three times with jittered exponential backoff, never sooner than the
+ * server's Retry-After. Every attempt sends a clone, so the body and the Idempotency-Key repeat exactly. After the last
+ * retry the final response is returned, or the final network error thrown.
+ */
+export const retryingFetch = (send, { sleep, random }) => async (request) => {
+    for (let retry = 0;; retry += 1) {
+        const backoff = BASE_DELAY_MS * 2 ** retry * (0.5 + random());
+        let response;
+        try {
+            response = await send(request.clone());
+        }
+        catch (error) {
+            if (retry === MAX_RETRIES)
+                throw error;
+            await sleep(backoff);
+            continue;
+        }
+        if (retry === MAX_RETRIES || !worthRetrying(response))
+            return response;
+        // Not awaited: on a cloned body, cancel() settles only once the other branch is cancelled too.
+        void response.body?.cancel().catch(() => undefined);
+        await sleep(Math.max(backoff, retryAfterMs(response) ?? 0));
+    }
+};

package/dist/session.d.ts

@@ -0,0 +1,12 @@
+import type { components } from '@manyoars/oars-client';
+import type { RunDeps } from './cli.js';
+export type LoginSuccess = components['schemas']['LoginSuccess'];
+/** `POST /auth/oidc/exchange`: the platform session for a Keycloak access token. The first exchange provisions DEVELOPER (T60). */
+export declare const exchangeKeycloakToken: (deps: RunDeps, apiUrl: string, keycloakAccessToken: string, step: string) => Promise<LoginSuccess>;
+/**
+ * The bearer token for an API call to `apiUrl`. `OARS_API_KEY` wins over a stored login and touches no network; otherwise the
+ * stored access token while it is valid, else one refreshed through Keycloak and exchanged. A stored login belongs to the API
+ * it was made against: for any other `apiUrl` the call exits 2 and sends nothing, so one deployment's refresh token never
+ * reaches another host.
+ */
+export declare const resolveAuthToken: (deps: RunDeps, apiUrl: string) => Promise<string>;

package/dist/session.js

@@ -0,0 +1,41 @@
+import { apiClient, unwrap } from './api.js';
+import { CliError, ExitCode } from './errors.js';
+import { discover, refreshTokens } from './oidc.js';
+/** Treat a token that expires within this window as expired, so it cannot lapse between the check and the call. */
+const EXPIRY_SKEW_MS = 30_000;
+/** `POST /auth/oidc/exchange`: the platform session for a Keycloak access token. The first exchange provisions DEVELOPER (T60). */
+export const exchangeKeycloakToken = async (deps, apiUrl, keycloakAccessToken, step) => {
+    const client = apiClient(deps, { apiUrl, step });
+    return unwrap(step, await client.POST('/auth/oidc/exchange', { body: { accessToken: keycloakAccessToken } }));
+};
+const sameUrl = (a, b) => a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+const refreshLogin = async (deps, stored) => {
+    const step = 'auth';
+    const config = await discover(stored.issuerUrl, { ...deps, step });
+    const tokens = await refreshTokens(config, stored.refreshToken, step);
+    // Keycloak rotates the refresh token on every use, so the old one is already dead: save the new one before anything can fail.
+    const rotated = { ...stored, refreshToken: tokens.refreshToken ?? stored.refreshToken };
+    await deps.store.write(rotated);
+    const session = await exchangeKeycloakToken(deps, stored.apiUrl, tokens.accessToken, step);
+    await deps.store.write({ ...rotated, accessToken: session.accessToken, expiresAt: session.expiresAt });
+    return session.accessToken;
+};
+/**
+ * The bearer token for an API call to `apiUrl`. `OARS_API_KEY` wins over a stored login and touches no network; otherwise the
+ * stored access token while it is valid, else one refreshed through Keycloak and exchanged. A stored login belongs to the API
+ * it was made against: for any other `apiUrl` the call exits 2 and sends nothing, so one deployment's refresh token never
+ * reaches another host.
+ */
+export const resolveAuthToken = async (deps, apiUrl) => {
+    const key = deps.env.OARS_API_KEY;
+    if (key !== undefined && key !== '')
+        return key;
+    const stored = await deps.store.read();
+    if (stored === undefined)
+        throw new CliError('Not logged in. Run "oars login", or set OARS_API_KEY.', ExitCode.AUTH, 'auth');
+    if (!sameUrl(stored.apiUrl, apiUrl))
+        throw new CliError(`not logged in to ${apiUrl}; run oars login --api-url ${apiUrl}`, ExitCode.USAGE, 'auth');
+    if (Date.parse(stored.expiresAt) - EXPIRY_SKEW_MS > deps.now())
+        return stored.accessToken;
+    return refreshLogin(deps, stored);
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The oars CLI: log in to Many Oars, list the starter templates and deploy an agent",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manyoars/oars.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "oars": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "parity/deploy-plans"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:live": "vitest run --config vitest.live.config.ts"
+  },
+  "dependencies": {
+    "@manyoars/oars-client": "^0.1.1",
+    "commander": "^15.0.0",
+    "openid-client": "^6.8.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "msw": "^3.0.3",
+    "typescript": "~5.9.3",
+    "yaml": "^2.9.1"
+  }
+}

package/parity/deploy-plans/paid-api.json

@@ -0,0 +1,34 @@
+[
+  {
+    "method": "POST",
+    "path": "/agents/workloads",
+    "body": {
+      "name": "Paid API",
+      "services": [
+        {
+          "name": "api",
+          "image": "ghcr.io/manyoars/paid-api@sha256:bc18de1da5b0a0fbdc18d6d68aa9da4f89a0ab118a2c18921a1247b09d9d4146",
+          "port": 8080,
+          "public": true,
+          "cpuMillicores": 250,
+          "memoryMib": 256
+        }
+      ]
+    }
+  },
+  {
+    "method": "POST",
+    "path": "/billing/agents/{workloadId}/prices",
+    "body": { "priceRef": "calls-100", "displayName": "100 calls", "amountUsd": "5.00", "kind": "CREDIT_PACK", "credits": 100 }
+  },
+  {
+    "method": "POST",
+    "path": "/billing/agents/{workloadId}/prices",
+    "body": { "priceRef": "calls-1000", "displayName": "1,000 calls", "amountUsd": "40.00", "kind": "CREDIT_PACK", "credits": 1000 }
+  },
+  {
+    "method": "POST",
+    "path": "/agents/workloads/{workloadId}/deploy",
+    "body": null
+  }
+]

package/parity/deploy-plans/per-task-agent.json

@@ -0,0 +1,34 @@
+[
+  {
+    "method": "POST",
+    "path": "/agents/workloads",
+    "body": {
+      "name": "Per-task agent",
+      "services": [
+        {
+          "name": "agent",
+          "image": "ghcr.io/manyoars/per-task-agent@sha256:b88bb11504236ad97349f6a4ad820a98c16eef670e9aa2f93c157019406aecd6",
+          "port": 8080,
+          "public": true,
+          "cpuMillicores": 500,
+          "memoryMib": 512
+        }
+      ]
+    }
+  },
+  {
+    "method": "POST",
+    "path": "/billing/agents/{workloadId}/prices",
+    "body": { "priceRef": "task-1", "displayName": "1 task", "amountUsd": "9.00", "kind": "CREDIT_PACK", "credits": 1 }
+  },
+  {
+    "method": "POST",
+    "path": "/billing/agents/{workloadId}/prices",
+    "body": { "priceRef": "tasks-5", "displayName": "5 tasks", "amountUsd": "40.00", "kind": "CREDIT_PACK", "credits": 5 }
+  },
+  {
+    "method": "POST",
+    "path": "/agents/workloads/{workloadId}/deploy",
+    "body": null
+  }
+]