@commercelayer/agent-cli 0.8.1 → 1.0.0-dev.1

package/dist/help.js

@@ -0,0 +1,81 @@
+// Help, as JSON in the envelope like everything else. It follows the conversational rule: it says
+// what a command does and what it returns, never that a human should run something. The agent
+// reads it and offers to do the work.
+import { toFlag } from './argv.js';
+import { EXIT } from './errors.js';
+export const USAGE = 'c11r <noun> <verb> [id] [--field value ...]';
+export const GLOBAL_FLAG_HELP = {
+    '--json': 'Output as JSON. The default, and the only format: one object on stdout, { data, state, warnings, next } or { error, state }.',
+    '--dry-run': 'On a write, the API checks everything and says what would change, and changes nothing. Reads ignore it.',
+    '--yes': 'Confirms a destructive verb in advance. Without it a destructive verb asks in the terminal, or, with no terminal, stops with confirmation_required.',
+    '--org <slug>': 'The organization to act on, by its stored token. Without it: C11R_ORG, then the folder\'s .c11r.json, then the only stored organization.',
+    '--live': 'Acts on live data, on a claimed organization. Without it every command works in test mode.',
+    '--help': 'Describes the noun or verb it follows, from its schema.',
+};
+export const EXIT_CODE_HELP = {
+    [EXIT.ok]: 'done',
+    [EXIT.unexpected]: 'unexpected failure, a bug in c11r',
+    [EXIT.usage]: 'the command is not valid: unknown noun, verb or flag, a bad value, or no organization named',
+    [EXIT.confirmation]: 'a destructive verb needs confirmation (--yes)',
+    [EXIT.requirement]: 'the organization needs another state or plan, has expired, or reached a limit',
+    [EXIT.not_found]: 'no such resource',
+    [EXIT.rejected]: 'the API or Commerce Layer refused the request as it is',
+    [EXIT.unavailable]: 'the API did not answer, is busy, or answered with an error of its own',
+    [EXIT.auth]: 'a wrong or revoked token, or no token stored for the organization named',
+};
+export function indexHelp(builtins, api) {
+    return {
+        usage: USAGE,
+        description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
+        nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
+        standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01; in takes values separated by commas). A dotted flag sets part of an object (--customer.email). An array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        global_flags: GLOBAL_FLAG_HELP,
+        exit_codes: EXIT_CODE_HELP,
+        more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',
+    };
+}
+export function nounHelp(s) {
+    return {
+        noun: s.noun,
+        description: s.description,
+        ...(s.skill ? { skill: s.skill } : {}),
+        ...(s.id?.accepts.length ? { id: `The id, or ${s.id.accepts.filter((a) => a !== 'id').join(' or ')}${s.id.example ? `, as in ${s.id.example}` : ''}.` } : {}),
+        verbs: Object.values(s.verbs).map((v) => ({ verb: v.name, usage: usageOf(s.noun, v), description: v.description, ...(v.destructive ? { destructive: true } : {}), ...(v.loopable ? { loopable: true } : {}), ...(v.refused ? { served: false, refused_by: v.refused.by } : {}) })),
+        ...(s.waiting ? { waiting: s.waiting } : {}),
+        ...(s.loop ? { loop: s.loop } : {}),
+    };
+}
+export function verbHelp(s, v) {
+    return {
+        usage: usageOf(s.noun, v),
+        description: v.description,
+        state: v.state,
+        ...(v.plan ? { plan: v.plan } : {}),
+        ...(v.refused ? { served: false, refused_by: v.refused.by } : {}),
+        ...(v.destructive ? { destructive: true, confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
+        ...(v.loopable ? { loopable: 'A loop policy may allow this verb.' } : {}),
+        ...(v.live ? {} : { live: 'Not in live mode.' }),
+        flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f)),
+    };
+}
+function flagHelp(key, f) {
+    return {
+        flag: toFlag(key),
+        type: f.type === 'array' ? `array of ${f.items ?? 'string'}` : f.type === 'ref' ? `${f.noun ?? 'resource'} id` : f.type === 'money' ? 'amount in major units' : f.type,
+        ...(f.required || (f.input?.kind === 'secret' && f.input.required) ? { required: true } : {}),
+        ...(f.input ? { reads: f.input.kind === 'secret' ? `${f.input.target}, a secret: never a flag value, never printed` : `${f.input.target}, a JSON document` } : {}),
+        ...(f.values ? { values: f.values } : {}),
+        ...(f.filter ? { filter: f.filter.op } : {}),
+        ...(f.description ? { description: f.description } : {}),
+    };
+}
+export function usageOf(noun, v) {
+    const needed = (f) => f.required || (f.input?.kind === 'secret' && f.input.required);
+    const required = Object.entries(v.flags)
+        .filter(([, f]) => needed(f))
+        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' ? f.values?.join('|') : f.type}>`);
+    const optional = Object.entries(v.flags).some(([k, f]) => !needed(f) && !v.idAlternative.includes(k));
+    const id = v.id ? (v.idAlternative.length ? `<id | ${v.idAlternative.map((k) => `${toFlag(k)} <${v.flags[k].type}>`).join(' ')}>` : '<id>') : '';
+    return [`c11r ${noun} ${v.name}`, id, ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');
+}

package/dist/http.js

@@ -0,0 +1,117 @@
+// Requests to the c11r API (contract sections 1, 2, 3 and 8). C11R_API_URL points the CLI at
+// another API, such as wrangler dev on http://localhost:8787/v1 (a URL without /v1 gets it).
+// Every answer is the envelope { data, state, warnings, next }; every error { error, state }.
+//
+// Query flags: --live sends mode=live on every request, --dry-run sends dry_run=true on writes,
+// and a confirmed destructive verb sends confirm=true (the form that works on every verb).
+//
+// Retries, as the PM ruled: rate_limited means nothing was processed, so reads and writes are
+// retried twice with a short backoff. commercelayer_busy and commercelayer_unavailable are
+// retried for reads only: a write that may have reached Commerce Layer fails with its next step.
+// The exception is a write with an Idempotency-Key (sandbox create): the API answers the same key
+// with the same result, so it is repeated with that key after any 5xx or a lost connection too.
+import { CliError, errorBody, fail, kindOfStatus } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const DEFAULT_API_URL = 'https://api.commercelayer.ai/v1';
+export function apiUrl() {
+    const raw = (process.env.C11R_API_URL || DEFAULT_API_URL).replace(/\/+$/, '');
+    return /\/v\d+$/.test(raw) ? raw : `${raw}/v1`;
+}
+/** An answer of the CLI's own, in the API's shape. state null: the CLI cannot tell it. */
+export const envelope = (data, extra = {}) => ({ data, state: null, warnings: [], next: [], ...extra });
+const RETRY_ALWAYS = new Set(['rate_limited']);
+const RETRY_READS = new Set(['commercelayer_busy', 'commercelayer_unavailable']);
+const TRIES = 3;
+export function urlOf(req, ctx) {
+    const q = new URLSearchParams(req.query ?? {});
+    if (ctx.live)
+        q.set('mode', 'live');
+    if (req.dryRun && req.method !== 'GET')
+        q.set('dry_run', 'true');
+    if (req.confirm)
+        q.set('confirm', 'true');
+    const qs = q.toString();
+    return `${apiUrl()}${req.path}${qs ? `?${qs}` : ''}`;
+}
+/** Sends the request: the envelope, or the API's error as a CliError. */
+export async function request(req, ctx) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await once(req, ctx);
+        }
+        catch (e) {
+            const safe = req.method === 'GET' || req.idempotencyKey !== undefined;
+            const retryable = e instanceof CliError && (RETRY_ALWAYS.has(e.code) || (safe && (RETRY_READS.has(e.code) || (req.idempotencyKey !== undefined && (e.code === 'api_unreachable' || e.kind === 'unavailable')))));
+            if (!retryable || attempt >= TRIES)
+                throw e;
+            // The API's retry_after (seconds, in the error or the Retry-After header) is waited for, up
+            // to the cap. Longer than the cap: no wait here, the error goes to the agent to plan around.
+            const after = retryAfterMs(e);
+            if (after !== null && after > retryCapMs())
+                throw e;
+            const wait = after ?? backoffMs() * 3 ** (attempt - 1);
+            process.stderr.write(JSON.stringify({ retrying: { code: e.code, attempt, of: TRIES - 1, in_ms: wait } }) + '\n');
+            await new Promise((r) => setTimeout(r, wait));
+        }
+    }
+}
+async function once(req, ctx) {
+    const headers = { 'user-agent': USER_AGENT, accept: 'application/json' };
+    if (req.body !== undefined)
+        headers['content-type'] = 'application/json';
+    if (ctx.token)
+        headers.authorization = `Bearer ${ctx.token}`;
+    if (req.idempotencyKey)
+        headers['idempotency-key'] = req.idempotencyKey;
+    const url = urlOf(req, ctx);
+    const timeout = req.timeoutMs ?? timeoutMs();
+    let res;
+    try {
+        res = await fetch(url, { method: req.method, headers, body: req.body === undefined ? undefined : JSON.stringify(req.body), redirect: 'manual', signal: AbortSignal.timeout(timeout) });
+    }
+    catch (e) {
+        const why = e.name === 'TimeoutError' ? `no answer in ${timeout / 1000} s` : e.message;
+        fail('api_unreachable', `The c11r API at ${new URL(url).origin} did not answer: ${why}.${process.env.C11R_API_URL ? ` C11R_API_URL is set to ${process.env.C11R_API_URL}.` : ''}`, {
+            // A write may have arrived before the answer was lost: never "retry" it blindly.
+            next_step: req.method === 'GET' ? { action: 'retry_later' } : { action: 'none' },
+        });
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        fail('invalid_response', `The API answered ${res.status} with something that is not JSON.`, { details: { status: res.status } }, res.ok ? 'unavailable' : kindOfStatus(res.status));
+    }
+    if (!res.ok)
+        throw apiError(res.status, data, res.headers.get('retry-after'));
+    if (!data || typeof data !== 'object' || Array.isArray(data) || !('data' in data)) {
+        fail('invalid_response', `The API answered ${res.status} without the envelope (data, state).`, { details: { status: res.status } });
+    }
+    return { data: data.data, state: data.state ?? null, warnings: data.warnings ?? [], next: data.next ?? [] };
+}
+/** The API's error, kept as the API wrote it, with the HTTP status in details. */
+function apiError(status, data, retryAfterHeader = null) {
+    const e = data?.error;
+    if (!e || typeof e !== 'object' || typeof e.code !== 'string') {
+        return new CliError(errorBody(status >= 500 ? 'api_error' : 'invalid_response', `The API answered ${status} without an error object.`, { details: { status } }), kindOfStatus(status), data?.state ?? null);
+    }
+    const body = {
+        ...errorBody(e.code, String(e.message ?? `The API answered ${status} (${e.code}).`)),
+        ...e,
+        details: { ...(e.details ?? {}), status, ...(retryAfterHeader !== null && e.retry_after === undefined && /^\d+(\.\d+)?$/.test(retryAfterHeader) ? { retry_after: Number(retryAfterHeader) } : {}) },
+    };
+    const known = new CliError(body, undefined, data.state ?? null);
+    return known.kind === 'unexpected' ? new CliError(body, kindOfStatus(status), data.state ?? null) : known;
+}
+/** retry_after in seconds, from the error or the Retry-After header, in ms; null when absent. */
+function retryAfterMs(e) {
+    const raw = e.body.retry_after ?? e.body.details?.retry_after;
+    const n = Number(raw);
+    return raw === undefined || raw === null || !Number.isFinite(n) || n < 0 ? null : n * 1000;
+}
+/** The longest wait for one retry: 30 s, C11R_RETRY_CAP_S to change it. */
+export const retryCapMs = () => (process.env.C11R_RETRY_CAP_S === undefined ? 30 : Number(process.env.C11R_RETRY_CAP_S)) * 1000;
+const timeoutMs = () => Number(process.env.C11R_TIMEOUT_MS) || 30_000;
+const backoffMs = () => (process.env.C11R_RETRY_MS === undefined ? 1000 : Number(process.env.C11R_RETRY_MS));

package/dist/inputs.js

@@ -0,0 +1,112 @@
+// Values read from files before anything is sent (contract section 28.6 and 39).
+//
+// A secret field (secret_input: provider credentials) is taken only from --<name>-file, as JSON or
+// KEY=value lines, from a plain file only its owner can read; or, in a terminal, typed without
+// echo. Never from a flag value or --data, never printed: an error names the file, not the value.
+// A document field (file_input: price rules, rule filters) is also read from a JSON file, --file.
+import fs from 'node:fs';
+import { toFlag } from './argv.js';
+import { fail } from './errors.js';
+import { readPrivateFile } from './login.js';
+/** The flag a secret field is read from, if the key is one. */
+export function secretFileFlag(verb, key) {
+    const k = `${key}_file`;
+    return verb.flags[k]?.input?.kind === 'secret' ? k : null;
+}
+/** Reads the files given; with a prompter, also asks for a required secret not given (null: files only). */
+export async function readInputs(noun, verb, parsed, prompter) {
+    const cmd = `c11r ${noun} ${verb.name}`;
+    for (const [key, spec] of Object.entries(verb.flags)) {
+        const input = spec.input;
+        if (!input)
+            continue;
+        const file = parsed.values[key];
+        // The second pass only asks for a secret: the files were read in the first.
+        if (prompter !== null && (input.kind === 'document' || parsed.values[input.target] !== undefined))
+            continue;
+        if (input.kind === 'document') {
+            if (file === undefined)
+                continue;
+            if (parsed.values[input.target] !== undefined)
+                fail('invalid_value', `${cmd} takes ${input.target} from ${toFlag(input.target)} or from ${toFlag(key)}, not both.`, { path: key });
+            parsed.values[input.target] = documentOf(file, key, spec);
+            continue;
+        }
+        if (file !== undefined) {
+            parsed.values[input.target] = secretOf(readPrivateFile(file, key), file, key, input.target_type);
+            continue;
+        }
+        if (!input.required || prompter === null)
+            continue;
+        if (prompter.interactive && prompter.askSecret) {
+            const typed = (await prompter.askSecret(`${input.target} as JSON, or KEY=value pairs separated by spaces (not shown): `)).trim();
+            if (!typed)
+                fail('secret_required', `Nothing was typed: ${cmd} needs ${input.target}.`, { path: key });
+            parsed.values[input.target] = secretOf(typed.startsWith('{') ? typed : typed.split(/\s+/).join('\n'), null, key, input.target_type);
+            continue;
+        }
+        fail('secret_required', `${cmd} needs ${input.target}, and there is no terminal to type it in. Ask the human to save it in a file only they can read (mode 600), as JSON or KEY=value lines, then run the command with ${toFlag(key)} <file>. Do not open or print that file.`, {
+            path: key,
+            next_step: { action: 'human_step', command: null, url: null },
+        });
+    }
+}
+function documentOf(file, key, spec) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        fail('invalid_value', `${toFlag(key)} ${file}: ${e.code === 'ENOENT' ? 'no such file' : e.message}.`, { path: key });
+    }
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch (e) {
+        fail('invalid_value', `${file} is not valid JSON: ${e.message}.`, { path: key });
+    }
+    const want = spec.input.target_type;
+    if (want === 'object' && (!v || typeof v !== 'object' || Array.isArray(v)))
+        fail('invalid_value', `${file} is not a JSON object.`, { path: key });
+    if (want === 'array' && !Array.isArray(v))
+        fail('invalid_value', `${file} is not a JSON list.`, { path: key });
+    return v;
+}
+/** JSON, or KEY=value lines (keys lowercased: API_KEY is api_key). The value never goes in a message. */
+function secretOf(text, file, key, type) {
+    const where = file ?? 'What was typed';
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        let v;
+        try {
+            v = JSON.parse(trimmed);
+        }
+        catch {
+            fail('invalid_value', `${where} is not valid JSON.`, { path: key });
+        }
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            fail('invalid_value', `${where} is not a JSON object.`, { path: key });
+        return v;
+    }
+    const out = {};
+    for (const line of trimmed.split(/\r?\n/).map((l) => l.trim())) {
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq < 1)
+            fail('invalid_value', `${where} has a line that is not KEY=value.`, { path: key });
+        const value = line.slice(eq + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+        if (value)
+            out[line.slice(0, eq).trim().toLowerCase()] = value;
+    }
+    if (!Object.keys(out).length)
+        fail('secret_required', `${where} has no values.`, { path: key });
+    if (type !== 'object') {
+        const values = Object.values(out);
+        if (values.length !== 1)
+            fail('invalid_value', `${where} has to hold one value.`, { path: key });
+        return values[0];
+    }
+    return out;
+}

package/dist/login.js

@@ -0,0 +1,136 @@
+// The human's login: their own Provisioning API application, client id and secret (contract
+// section 18). The secret never leaves this machine: the CLI exchanges it for a Provisioning
+// access token at Commerce Layer's auth endpoint and sends only that token to the c11r API. Both
+// stay in credentials.json, mode 600, and are printed never.
+//
+// The token lasts two hours. A command that needs the login takes the stored token while it has
+// more than a minute left, else mints a new one. C11R_PROVISIONING_TOKEN, for CI, is a ready token
+// used as is.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { authUrl, storedLogin, storeLogin } from './config.js';
+import { CliError, errorBody, fail } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const PROVISIONING_URL = 'https://dashboard.commercelayer.io/user/provisioning_api';
+const MARGIN_MS = 60_000;
+export { authUrl };
+/** Where the human saves the client id and secret when there is no terminal to type them in. */
+export function secretFileDefault() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(base, 'c11r', 'provisioning.secret');
+}
+/** client_credentials at Commerce Layer. A refusal is the human's to fix: new values in the dashboard. */
+export async function mint(clientId, clientSecret) {
+    let res;
+    try {
+        res = await fetch(authUrl(), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': USER_AGENT },
+            body: JSON.stringify({ grant_type: 'client_credentials', client_id: clientId, client_secret: clientSecret }),
+            signal: AbortSignal.timeout(Number(process.env.C11R_TIMEOUT_MS) || 30_000),
+        });
+    }
+    catch (e) {
+        fail('api_unreachable', `Commerce Layer's auth endpoint (${new URL(authUrl()).origin}) did not answer: ${e.message}.`, { next_step: { action: 'retry_later' } });
+    }
+    const body = (await res.json().catch(() => null));
+    if (res.status === 400 || res.status === 401) {
+        fail('unauthorized', 'Commerce Layer refused this client id and secret. They have to be the ones of the human\'s own Provisioning API application, from the dashboard.', {
+            path: 'client_secret',
+            next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL },
+        });
+    }
+    if (!res.ok || typeof body?.access_token !== 'string') {
+        fail('commercelayer_unavailable', `Commerce Layer's auth endpoint answered ${res.status} without a token.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    }
+    const seconds = Number(body.expires_in) || 7200;
+    return { token: body.access_token, expires_at: new Date(Date.now() + seconds * 1000).toISOString() };
+}
+export function loginRequired(message) {
+    return new CliError(errorBody('login_required', message, {
+        next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL },
+        details: { secret_file: secretFileDefault() },
+    }));
+}
+/** The token a login command sends; minted again when it is about to end. */
+export async function loginToken(opts = {}) {
+    if (process.env.C11R_PROVISIONING_TOKEN)
+        return process.env.C11R_PROVISIONING_TOKEN;
+    const login = storedLogin();
+    if (!login) {
+        throw loginRequired('This needs the human\'s Commerce Layer login, and this machine has none. Ask the human for the client id and secret of their Provisioning API application, from the dashboard, saved in the file named in details.secret_file; then c11r auth login reads it.');
+    }
+    if (!opts.fresh && login.token && login.expires_at && Date.parse(login.expires_at) - Date.now() > MARGIN_MS)
+        return login.token;
+    let minted;
+    try {
+        minted = await mint(login.client_id, login.client_secret);
+    }
+    catch (e) {
+        if (e instanceof CliError && e.code === 'unauthorized') {
+            throw loginRequired('The stored login no longer works: Commerce Layer refused its client id and secret, as when the Provisioning API application was deleted or changed. The human saves the new ones; then c11r auth login reads them.');
+        }
+        throw e;
+    }
+    storeLogin({ ...login, token: minted.token, expires_at: minted.expires_at });
+    return minted.token;
+}
+export const hasLogin = () => Boolean(process.env.C11R_PROVISIONING_TOKEN) || storedLogin() !== null;
+/** A secret file's text: a plain file only its owner can read, else insecure_file. */
+export function readPrivateFile(file, flagPath) {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch {
+        fail('invalid_value', `${file} does not exist.`, { path: flagPath });
+    }
+    if (st.isSymbolicLink() || !st.isFile())
+        fail('insecure_file', `${file} is not a plain file. c11r reads a secret only from a plain file.`, { path: flagPath });
+    if (st.mode & 0o077) {
+        fail('insecure_file', `${file} can be read by other users (mode ${(st.mode & 0o777).toString(8)}). c11r reads a secret only from a file that only its owner can read, mode 600.`, {
+            path: flagPath,
+            next_step: { action: 'human_step', command: null, url: null },
+            details: { file, mode: (st.mode & 0o777).toString(8) },
+        });
+    }
+    return fs.readFileSync(file, 'utf8');
+}
+/** The client id and secret, from a file the human saved: key=value lines, JSON, or the secret alone. */
+export function readSecretFile(file) {
+    const text = readPrivateFile(file, 'secret_file');
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    try {
+        const json = JSON.parse(text);
+        if (json && typeof json === 'object')
+            return { client_id: str(json.client_id), client_secret: str(json.client_secret) };
+    }
+    catch {
+        // Not JSON.
+    }
+    if (lines.length === 1 && !lines[0].includes('='))
+        return { client_secret: lines[0] };
+    const out = {};
+    for (const l of lines) {
+        const eq = l.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = l.slice(0, eq).trim().toLowerCase().replace(/^(cl_|commercelayer_)/, '');
+        const value = l.slice(eq + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+        if (key === 'client_id' && value)
+            out.client_id = value;
+        if (key === 'client_secret' && value)
+            out.client_secret = value;
+    }
+    return out;
+}
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+/** The two-line template for the human to complete, mode 600 from the start; an existing file is left as is. */
+export function writeSecretTemplate(file) {
+    if (fs.existsSync(file))
+        return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, 'client_id=\nclient_secret=\n', { mode: 0o600, flag: 'wx' });
+    return true;
+}

package/dist/resources.js

@@ -0,0 +1,42 @@
+// One URL grammar for every noun (contract section 1), so no noun has its own path code:
+//   list    GET    /<noun>                 filters as ?filter[<field>][<op>]=<value>
+//   get     GET    /<noun>/<id>
+//   create  POST   /<noun>
+//   update  PATCH  /<noun>/<id>
+//   delete  DELETE /<noun>/<id>
+//   <verb>  POST   /<noun>/<id>/<verb>, or /<noun>/<verb> for a verb on the collection
+// The schema's path wins when it has one. Each value goes where its flag says: the body, the
+// query, or a filter; a local flag (--out) is the CLI's and is never sent.
+export function resourceRequest(noun, verb, id, values) {
+    const base = `/${noun}`;
+    const one = id === undefined ? base : `${base}/${encodeURIComponent(id)}`;
+    const query = {};
+    const body = {};
+    for (const [key, value] of Object.entries(values)) {
+        const flag = verb.flags[key];
+        if (value === undefined)
+            continue;
+        if (!flag || flag.to === 'body')
+            body[key] = value;
+        else if (flag.to === 'local')
+            continue;
+        else if (flag.to === 'filter')
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+        else
+            query[key] = text(value);
+    }
+    // The schema's own route when it gives one (/plans/current, /members/invite), else the grammar.
+    const path = verb.path
+        ? // No id (one given by its id_alternative flags): the segment goes, /prices/{id}/tiers is /prices/tiers.
+            verb.path.replace(/\/\{[^}]+\}/, id === undefined ? '' : `/${encodeURIComponent(id)}`)
+        : ['list', 'get', 'create', 'update', 'delete'].includes(verb.name)
+            ? verb.name === 'list' || verb.name === 'create'
+                ? base
+                : one
+            : `${one}/${verb.name}`;
+    const req = { method: verb.method, path, query };
+    if (verb.method !== 'GET' && verb.method !== 'DELETE')
+        req.body = body;
+    return req;
+}
+const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));