@manyoars/oars 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @manyoars/oars
+
+The `oars` command line for Many Oars: sign in, deploy an agent, set its prices and make a test charge against it.
+
+Node 24 or later. ESM only.
+
+## Install
+
+```sh
+npm install --global @manyoars/oars
+oars --help
+```
+
+Or run it once without installing:
+
+```sh
+npx @manyoars/oars <command>
+```
+
+## Commands
+
+`oars --help` lists the commands below (`oars help <command>` shows one command's flags). `oars --version` prints the version.
+
+These flags work on every command:
+
+- `--json` prints one JSON document on stdout instead of text (see below).
+- `--api-url <url>` sets the platform API. The default is `OARS_API_URL`, else `https://api.manyoars.com`.
+- `--idempotency-key <key>` is the base of every step's idempotency key (default: a fresh UUID). Rerun a failed command with the same key to resume.
+
+### login
+
+Signs in with your browser (RFC 8628 device flow) and stores the login.
+
+- `--no-browser` prints the link and code without opening a browser.
+- `--issuer-url <url>` is the Keycloak realm URL. The default is `OARS_ISSUER_URL`. With neither, `login` uses the built-in Many Oars issuer once Many Oars has launched, which it learns from `https://manyoars.com/.well-known/oars.json` (`{"launched": true}`). The flag only switches the built-in issuer on; it never supplies a URL. Before launch, with no `--issuer-url` or `OARS_ISSUER_URL`, the command prints "Many Oars has not launched yet: pass --issuer-url or set OARS_ISSUER_URL." and exits 2.
+
+### logout
+
+Revokes the stored login and deletes it.
+
+### templates
+
+`oars templates` lists the starter templates `oars deploy --template` takes: each id, name, description, and starter prices. Needs a login.
+
+### deploy
+
+Registers a workload, creates its prices, and deploys it. Pass exactly one of `--template`, `--image`, or `--manifest`. It stops at the first failed step and exits 9 (see below). A `--template` id the catalog lacks exits 2, and an unreachable catalog exits 8, before anything is registered.
+
+- `--image <ref>` deploys an image pinned by digest (`name@sha256:...`). Companions: `--name <name>`, `--port <n>` (default 8080), `--public`, `--cpu-millicores <n>` (default 250), `--memory-mib <n>` (default 256).
+- `--manifest <file>` deploys a JSON workload manifest.
+- `--always-on` keeps the public service running instead of idling. It works with every source.
+- `--template <id>` deploys a starter template from the catalog (`oars templates`): it registers the entry's manifest, creates every starter price, then deploys. `--price <ref>` (repeatable) creates only the named ones; `--no-prices` creates none. `--name`, `--port`, `--public`, `--cpu-millicores`, `--memory-mib`, and `--price-file` do not combine with it.
+- `--price-file <file>` is a JSON array of prices to create (with `--image` or `--manifest`).
+- `--secret <NAME=value>` and `--secret-from-env <NAME>` add a workload secret; both repeat. Prefer `--secret-from-env`, which keeps the value out of your shell history.
+- `--no-start` registers and prices the workload without deploying it.
+
+The SDK key is shown once, so save it when `deploy` prints it.
+
+### status
+
+`oars status <workloadId>` shows a workload and its billing mode.
+
+### test-charge
+
+`oars test-charge <workloadId>` makes a TEST-mode charge against one of the workload's prices.
+
+- `--price <ref>` picks the price. The default is the workload's only active price.
+
+## The `--json` contract
+
+With `--json`, stdout carries exactly one JSON document and a success exits 0.
+
+- Success: `{"ok": true, ...}`. The rest depends on the command: `login` adds `email`; `deploy` adds `workloadId`, `prices`, `started`, `nextSteps` and, when this run minted it, `sdkKey`; `templates` adds `templates`; `status` adds `workload` and `billingMode`; `test-charge` adds `chargeId` and `status`.
+- Failure: `{"ok": false, "step": "...", "problem": {...}}`, where `problem` is the platform's problem document (`title`, `detail`, `code`, `actionUrl` when it sent them). A `deploy` that stopped after registering also carries `workloadId`, `rerun` and, if that run minted it, `sdkKey`.
+
+Without `--json`, a failure prints the problem to stderr instead.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | unexpected error |
+| 2 | usage error |
+| 3 | authentication failed (login expired or denied, SDK key invalid, HTTP 401 or 403) |
+| 4 | the platform rejected the input |
+| 5 | conflict (an idempotency key or workload already used) |
+| 6 | a person must act first (account, payment method, credits, or compute cap); the last stderr line starts "Needs you:" and names the link |
+| 7 | rate limited |
+| 8 | the platform could not be reached |
+| 9 | `deploy` stopped part way; rerun the printed command to resume |
+
+## Source
+
+[github.com/manyoars/oars](https://github.com/manyoars/oars/tree/main/packages/cli), [Apache-2.0](https://github.com/manyoars/oars/blob/main/LICENSE).

package/dist/cli.js

@@ -5,6 +5,7 @@ import { deploy } from './commands/deploy.js';
 import { login } from './commands/login.js';
 import { logout } from './commands/logout.js';
 import { status } from './commands/status.js';
+import { templates } from './commands/templates.js';
 import { testCharge } from './commands/test-charge.js';
 import { CliError, ExitCode } from './errors.js';
 const flag = (options, name) => options[name] === true;
@@ -30,6 +31,16 @@ const positiveInteger = (value) => {
 const emit = (deps, json, outcome) => {
     deps.io.stdout(`${json ? JSON.stringify(outcome.document) : outcome.text}\n`);
 };
+/** The last line of an exit 6: the one thing a person must do, by link when the platform sent one, then to rerun. Stripe onboarding is the step most runs wait on. */
+const needsYouLine = (code, actionUrl) => {
+    const stripe = code === 'ACCOUNT_NOT_READY';
+    if (actionUrl !== undefined && actionUrl !== '') {
+        return `Needs you: ${stripe ? 'finish Stripe onboarding at' : 'open'} ${actionUrl}, then rerun this command.`;
+    }
+    return stripe
+        ? 'Needs you: finish Stripe onboarding (Account, then Payout account, in the Many Oars web app), then rerun this command.'
+        : 'Needs you: a step only a person can do. Do it in the Many Oars web app, then rerun this command.';
+};
 /**
  * `--json` prints `{ok: false, step, problem}` on stdout, plus `workloadId`, `sdkKey` and `rerun` after a deploy that stopped;
  * otherwise the problem's title, detail and URL go to stderr, then the rerun line, and the one-time SDK key goes to stdout.
@@ -42,7 +53,8 @@ const printFailure = (deps, json, error) => {
     }
     const { title, detail, actionUrl } = error.problem;
     const resume = partial === undefined ? [] : [`Workload ${partial.workloadId} is registered; the deploy stopped at ${error.step}.`, `Rerun to resume: ${partial.rerun}`];
-    deps.io.stderr(`${[title ?? error.message, detail, actionUrl, ...resume].filter((line) => line !== undefined && line !== '').join('\n')}\n`);
+    const needsYou = error.exitCode === ExitCode.HUMAN ? [needsYouLine(error.problem.code, actionUrl)] : [];
+    deps.io.stderr(`${[title ?? error.message, detail, ...(needsYou.length === 0 ? [actionUrl] : []), ...resume, ...needsYou].filter((line) => line !== undefined && line !== '').join('\n')}\n`);
     if (partial?.sdkKey !== undefined)
         deps.io.stdout(`SDK key (shown once; save it now): ${partial.sdkKey}\n`);
 };
@@ -59,7 +71,7 @@ const buildProgram = (deps, argv) => {
         .command('login')
         .description('sign in with your browser (RFC 8628 device flow)')
         .option('--no-browser', 'print the link and code without opening a browser')
-        .option('--issuer-url <url>', 'the Keycloak realm URL (default: OARS_ISSUER_URL)')
+        .option('--issuer-url <url>', 'the Keycloak realm URL (default: OARS_ISSUER_URL, else Many Oars once it has launched)')
         .action(async (_options, command) => {
         const options = command.optsWithGlobals();
         const outcome = await login(deps, {
@@ -76,10 +88,17 @@ const buildProgram = (deps, argv) => {
         const options = command.optsWithGlobals();
         emit(deps, flag(options, 'json'), await logout(deps));
     });
+    program
+        .command('templates')
+        .description('list the starter templates `oars deploy --template` takes')
+        .action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        emit(deps, flag(options, 'json'), await templates(deps, { apiUrl: resolveApiUrl(deps, text(options, 'apiUrl')) }));
+    });
     program
         .command('deploy')
         .description('register a workload, create its prices and deploy it; stops at the first failed step (exit 9)')
-        .option('--template <id>', 'a starter template (not available until the public API lists them)')
+        .option('--template <id>', 'a starter template from the catalog (see: oars templates)')
         .option('--image <ref>', 'an image pinned by digest (name@sha256:...)')
         .option('--manifest <file>', 'a JSON workload manifest')
         .option('--name <name>', 'the workload name (--image)')
@@ -88,8 +107,8 @@ const buildProgram = (deps, argv) => {
         .option('--cpu-millicores <n>', 'CPU in millicores (--image; default 250)', positiveInteger)
         .option('--memory-mib <n>', 'memory in MiB (--image; default 256)', positiveInteger)
         .option('--always-on', 'keep the public service running instead of idling')
-        .option('--price <ref>', 'a starter price to create (--template; repeatable)', collect)
-        .option('--no-prices', 'create none of the starter prices (--template)')
+        .option('--price <ref>', 'a starter price to create instead of all of them (--template; repeatable)', collect)
+        .option('--no-prices', "create none of the template's starter prices (--template)")
         .option('--price-file <file>', 'a JSON array of prices to create (--image, --manifest)')
         .option('--secret <NAME=value>', 'a secret for the workload (repeatable); prefer --secret-from-env', collect)
         .option('--secret-from-env <NAME>', 'a secret read from the environment variable NAME (repeatable)', collect)

package/dist/commands/deploy-input.d.ts

@@ -1,4 +1,5 @@
 import type { components } from '@manyoars/oars-client';
+import type { AgentTemplate } from './templates.js';
 type RegisterWorkloadRequest = components['schemas']['RegisterWorkloadRequest'];
 type CreatePriceInput = components['schemas']['CreatePriceInput'];
 /** What `oars deploy` is told to deploy, as the flags give it. A flag the developer did not pass is undefined. */
@@ -12,7 +13,7 @@ export interface DeployFlags {
     cpuMillicores?: number;
     memoryMib?: number;
     alwaysOn?: boolean;
-    /** `--price`: starter prices to pick from a template. */
+    /** `--price`: starter prices to pick from a template (all of them by default). */
     prices: string[];
     /** `--no-prices`. */
     noPrices: boolean;
@@ -27,9 +28,11 @@ export interface DeployInput {
     request: RegisterWorkloadRequest;
     prices: CreatePriceInput[];
 }
+/** Reads the catalog once, when a `--template` deploy has passed every check that needs no network. */
+export type TemplateLookup = () => Promise<AgentTemplate[]>;
 /**
- * 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).
+ * Turns the flags into the calls' bodies. Exactly one of `--template`, `--image`, `--manifest`. Every mistake the flags alone can
+ * show is found before any request; only `--template` then reads the catalog (`catalog`), so a typo there costs one GET.
  */
-export declare const loadDeployInput: (flags: DeployFlags, env: NodeJS.ProcessEnv) => Promise<DeployInput>;
+export declare const loadDeployInput: (flags: DeployFlags, env: NodeJS.ProcessEnv, catalog: TemplateLookup) => Promise<DeployInput>;
 export {};

package/dist/commands/deploy-input.js

@@ -62,10 +62,22 @@ const requestFromFlags = (flags, image) => {
         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) => {
+/** The register body of an --image or --manifest deploy. */
+const imageOrFileRequest = async (flags) => {
+    if (flags.image !== undefined)
+        return requestFromFlags(flags, flags.image);
+    if (flags.manifestFile !== undefined)
+        return requestFromFile(flags, flags.manifestFile);
+    throw usage('Pass exactly one of --template, --image, or --manifest.');
+};
+/** The flags that describe an --image deploy; a template or a manifest file holds its own. */
+const refuseImageFlags = (flags, source) => {
     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.');
+        throw usage(`--name, --port, --public, --cpu-millicores, and --memory-mib describe an --image deploy; ${source} holds its own.`);
+};
+const requestFromFile = async (flags, path) => {
+    refuseImageFlags(flags, 'a --manifest file');
     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.`);
@@ -81,27 +93,58 @@ const pricesFromFile = async (path) => {
     }
     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>.');
+/** A starter price as the create call takes it. `credits` is left out of a price that has none (the wire may carry null). */
+const priceFromTemplate = (price) => ({
+    priceRef: price.priceRef,
+    displayName: price.displayName,
+    amountUsd: price.amountUsd,
+    kind: price.kind,
+    ...(typeof price.credits === 'number' ? { credits: price.credits } : {}),
+});
+/** `--template`: the entry's manifest, and the starter prices `--price` picked (every one without it, none for `--no-prices`). */
+const fromTemplate = (flags, template) => {
+    const wanted = flags.noPrices ? [] : flags.prices;
+    const unknown = wanted.filter((ref) => !template.starterPrices.some((price) => price.priceRef === ref));
+    if (unknown.length > 0) {
+        throw usage(`Template ${template.templateId} has no starter price ${unknown.join(', ')}; its prices are ${template.starterPrices.map((price) => price.priceRef).join(', ')}.`);
+    }
+    const chosen = flags.noPrices || flags.prices.length > 0 ? template.starterPrices.filter((price) => wanted.includes(price.priceRef)) : template.starterPrices;
+    return { request: flags.alwaysOn === true ? { ...template.manifest, alwaysOn: true } : template.manifest, prices: chosen.map(priceFromTemplate) };
+};
+/** A catalog entry's id is what the platform serves, so an id it does not list is exit 2 naming the ids it does. */
+const findTemplate = async (id, resolve) => {
+    const catalog = await resolve();
+    const found = catalog.find((template) => template.templateId === id);
+    if (found === undefined) {
+        throw usage(`No template ${id}. ${catalog.length === 0 ? 'The catalog is empty.' : `Available: ${catalog.map((template) => template.templateId).join(', ')}.`} List them with: oars templates`);
+    }
+    return found;
+};
+/** The checks on a `--template` deploy's flags, then its catalog entry; the flags are all read before the one GET. */
+const templateInput = async (flags, id, catalog) => {
+    refuseImageFlags(flags, 'the template');
+    if (flags.priceFile !== undefined)
+        throw usage('--price-file adds prices to an --image or --manifest deploy; a template brings its own: choose among them with --price, or skip them with --no-prices.');
+    if (flags.noPrices && flags.prices.length > 0)
+        throw usage('--price and --no-prices contradict each other.');
+    return fromTemplate(flags, await findTemplate(id, catalog));
 };
 /**
- * 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).
+ * Turns the flags into the calls' bodies. Exactly one of `--template`, `--image`, `--manifest`. Every mistake the flags alone can
+ * show is found before any request; only `--template` then reads the catalog (`catalog`), so a typo there costs one GET.
  */
-export const loadDeployInput = async (flags, env) => {
+export const loadDeployInput = async (flags, env, catalog) => {
     if ([flags.template, flags.image, flags.manifestFile].filter((source) => source !== undefined).length !== 1) {
-        throw usage('Pass exactly one of --template, --image or --manifest.');
+        throw usage('Pass exactly one of --template, --image, or --manifest.');
     }
-    const base = await baseRequest(flags);
-    if (flags.prices.length > 0 || flags.noPrices)
+    const picked = flags.template === undefined ? undefined : await templateInput(flags, flags.template, catalog);
+    if (picked === undefined && (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 base = picked?.request ?? (await imageOrFileRequest(flags));
     const secrets = [...(base.secrets ?? []), ...secretsFrom(flags, env)];
     return {
         request: secrets.length === 0 ? base : { ...base, secrets },
-        prices: flags.priceFile === undefined ? [] : await pricesFromFile(flags.priceFile),
+        prices: picked?.prices ?? (flags.priceFile === undefined ? [] : await pricesFromFile(flags.priceFile)),
     };
 };

package/dist/commands/deploy.js

@@ -4,6 +4,7 @@ import { CliError, ExitCode } from '../errors.js';
 import { stepKey } from '../journal.js';
 import { resolveAuthToken } from '../session.js';
 import { loadDeployInput } from './deploy-input.js';
+import { listTemplates, STEP as TEMPLATES_STEP } from './templates.js';
 const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 const quote = (token) => (SHELL_SAFE.test(token) ? token : `'${token.replaceAll("'", "'\\''")}'`);
 /**
@@ -42,8 +43,11 @@ const partialFailure = (error, step, partial) => {
  * 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);
+    // Resolved once, and only when a step needs it: a deploy with a mistake in its flags fails before it asks for a login.
+    let pending;
+    const authToken = () => (pending ??= resolveAuthToken(deps, options.apiUrl));
+    const input = await loadDeployInput(options, deps.env, async () => listTemplates(apiClient(deps, { apiUrl: options.apiUrl, step: TEMPLATES_STEP, token: await authToken() })));
+    const token = await authToken();
     const base = options.idempotencyKey ?? randomUUID();
     const clientFor = (step) => apiClient(deps, { apiUrl: options.apiUrl, step, token });
     const prior = await deps.journal.read(base).catch(() => undefined);

package/dist/commands/login.d.ts

@@ -1,7 +1,7 @@
 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. */
+    /** `--issuer-url`; `OARS_ISSUER_URL` when absent, then the built-in production issuer once Many Oars has launched (issuer.ts). */
     issuerUrl?: string;
     /** False for `--no-browser`. */
     browser: boolean;

package/dist/commands/login.js

@@ -1,13 +1,11 @@
 import { CliError, ExitCode } from '../errors.js';
+import { resolveIssuerUrl } from '../issuer.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 issuerUrl = await resolveIssuerUrl(deps, options.issuerUrl);
     const config = await discover(issuerUrl, { ...deps, step: STEP });
     const device = await startDeviceAuthorization(config, STEP);
     const url = device.verification_uri_complete ?? device.verification_uri;

package/dist/commands/templates.d.ts

@@ -0,0 +1,11 @@
+import type { components, OarsClient } from '@manyoars/oars-client';
+import type { Outcome, RunDeps } from '../cli.js';
+export type AgentTemplate = components['schemas']['AgentTemplateResponse'];
+export interface TemplatesOptions {
+    apiUrl: string;
+}
+export declare const STEP = "templates";
+/** Every entry of `GET /agents/templates`, following the pages until the last one. */
+export declare const listTemplates: (client: OarsClient) => Promise<AgentTemplate[]>;
+/** `oars templates`: the platform's starter-template catalog, the ids `oars deploy --template` takes. */
+export declare const templates: (deps: RunDeps, options: TemplatesOptions) => Promise<Outcome>;

package/dist/commands/templates.js

@@ -0,0 +1,32 @@
+import { apiClient, unwrap } from '../api.js';
+import { resolveAuthToken } from '../session.js';
+export const STEP = 'templates';
+// The catalog holds a handful of entries; a page this large is the whole of it, and the loop below only covers a catalog that outgrows it.
+const PAGE_SIZE = 100;
+/** Every entry of `GET /agents/templates`, following the pages until the last one. */
+export const listTemplates = async (client) => {
+    const templates = [];
+    for (let page = 0;; page += 1) {
+        const result = unwrap(STEP, await client.GET('/agents/templates', { params: { query: { page, size: PAGE_SIZE } } }));
+        templates.push(...result.content);
+        if (result.last)
+            return templates;
+    }
+};
+const describePrice = (price) => `${price.priceRef} ($${price.amountUsd}${typeof price.credits === 'number' ? `, ${String(price.credits)} credits` : ''})`;
+/** `oars templates`: the platform's starter-template catalog, the ids `oars deploy --template` takes. */
+export const templates = async (deps, options) => {
+    const client = apiClient(deps, { apiUrl: options.apiUrl, step: STEP, token: await resolveAuthToken(deps, options.apiUrl) });
+    const catalog = await listTemplates(client);
+    const lines = catalog.length === 0
+        ? ['No starter templates are available.']
+        : [
+            ...catalog.flatMap((template) => [
+                `${template.templateId}: ${template.name}`,
+                `  ${template.description}`,
+                ...(template.starterPrices.length === 0 ? [] : [`  Prices: ${template.starterPrices.map(describePrice).join(', ')}`]),
+            ]),
+            'Deploy one with: oars deploy --template <id>',
+        ];
+    return { document: { ok: true, templates: catalog }, text: lines.join('\n') };
+};

package/dist/issuer.d.ts

@@ -0,0 +1,10 @@
+import type { RunDeps } from './cli.js';
+/**
+ * The production Keycloak realm (aor-platform/k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it:
+ * the launch flag below only switches it on, so a compromised site cannot send logins anywhere else.
+ */
+export declare const PRODUCTION_ISSUER_URL = "https://login.manyoars.com/realms/aor";
+/** The marketing site serves `{"launched": true}` here from launch day. */
+export declare const LAUNCH_FLAG_URL = "https://manyoars.com/.well-known/oars.json";
+/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer once the launch flag is on. */
+export declare const resolveIssuerUrl: (deps: RunDeps, flag?: string) => Promise<string>;

package/dist/issuer.js

@@ -0,0 +1,38 @@
+import { CliError, ExitCode } from './errors.js';
+/**
+ * The production Keycloak realm (aor-platform/k8s/configmap.yaml: KEYCLOAK_ISSUER_URI). It ships in the CLI, reviewed with it:
+ * the launch flag below only switches it on, so a compromised site cannot send logins anywhere else.
+ */
+export const PRODUCTION_ISSUER_URL = 'https://login.manyoars.com/realms/aor';
+/** The marketing site serves `{"launched": true}` here from launch day. */
+export const LAUNCH_FLAG_URL = 'https://manyoars.com/.well-known/oars.json';
+const FLAG_TIMEOUT_MS = 5000;
+const NOT_LAUNCHED = 'Many Oars has not launched yet: pass --issuer-url or set OARS_ISSUER_URL.';
+/** True only for a 200 answer whose JSON is an object with `launched: true`; every other answer, or none, means not launched. */
+const hasLaunched = async (deps) => {
+    try {
+        const response = await fetch(LAUNCH_FLAG_URL, {
+            headers: { 'User-Agent': `oars/${deps.version}`, Accept: 'application/json' },
+            redirect: 'error',
+            signal: AbortSignal.timeout(FLAG_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return false;
+        const body = await response.json();
+        return typeof body === 'object' && body !== null && Reflect.get(body, 'launched') === true;
+    }
+    catch {
+        return false;
+    }
+};
+/** `--issuer-url`, else `OARS_ISSUER_URL`, else the built-in production issuer once the launch flag is on. */
+export const resolveIssuerUrl = async (deps, flag) => {
+    if (flag !== undefined)
+        return flag;
+    const fromEnv = deps.env.OARS_ISSUER_URL;
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    if (await hasLaunched(deps))
+        return PRODUCTION_ISSUER_URL;
+    throw new CliError(NOT_LAUNCHED, ExitCode.USAGE, 'usage');
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@manyoars/oars",
-  "version": "0.1.0",
-  "description": "The oars CLI: log in to Many Oars, list the starter templates and deploy an agent",
+  "version": "0.2.0",
+  "description": "The oars CLI: log in to Many Oars, list the starter templates, and deploy an agent",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

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

@@ -7,7 +7,7 @@
       "services": [
         {
           "name": "api",
-          "image": "ghcr.io/manyoars/paid-api@sha256:bc18de1da5b0a0fbdc18d6d68aa9da4f89a0ab118a2c18921a1247b09d9d4146",
+          "image": "ghcr.io/manyoars/paid-api@sha256:c24de301f3b29f912c6235046b1f964a213b8437e496ba4b9f9de362e094b13f",
           "port": 8080,
           "public": true,
           "cpuMillicores": 250,

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

@@ -7,7 +7,7 @@
       "services": [
         {
           "name": "agent",
-          "image": "ghcr.io/manyoars/per-task-agent@sha256:b88bb11504236ad97349f6a4ad820a98c16eef670e9aa2f93c157019406aecd6",
+          "image": "ghcr.io/manyoars/per-task-agent@sha256:3dfe58ccacfcf8bf136e487e0dd6152092d26e6349f9671a2c46f78a097c07b3",
           "port": 8080,
           "public": true,
           "cpuMillicores": 500,