@offsida/cli 0.2.0 → 0.2.1

package/dist/api.d.ts

@@ -1,20 +1,23 @@
 import { type AuthOpts } from './auth.js';
+type Sleep = (ms: number) => Promise<void>;
 export type Api = {
     url: string;
     org: string;
     headers: Record<string, string>;
     fetch: typeof fetch;
+    sleep: Sleep;
 };
 export type Res = {
     status: number;
     body: unknown;
 };
-export declare function connect(opts: AuthOpts, fetchImpl?: typeof fetch): Promise<Api>;
+export declare function connect(opts: AuthOpts, fetchImpl?: typeof fetch, sleep?: Sleep): Promise<Api>;
 export declare function call(api: Api, method: string, path: string, init?: {
     body?: unknown;
     headers?: Record<string, string>;
 }): Promise<Res>;
 export declare function errorCode(res: Res): string | undefined;
-export declare function failure(operation: string, res: Res): Error;
+export declare function failure(operation: string, res: Res, scope?: string): Error;
 export declare function isRetryable(res: Res): boolean;
 export declare function withRetry(send: () => Promise<Res>, sleep: (ms: number) => Promise<void>): Promise<Res>;
+export {};

package/dist/api.js

@@ -1,16 +1,33 @@
 import { ORG_HEADER } from '@offsida/types';
-import { assertTarget, authHeaders } from './auth.js';
-export async function connect(opts, fetchImpl = fetch) {
-    assertTarget(opts);
-    const auth = await authHeaders(opts, fetchImpl);
-    return { url: opts.url, org: opts.org, headers: { ...auth, [ORG_HEADER]: opts.org }, fetch: fetchImpl };
+import { assertTarget, authHeaders, reach } from './auth.js';
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function connect(opts, fetchImpl = fetch, sleep = realSleep) {
+    const url = opts.url.replace(/\/+$/, '');
+    assertTarget({ ...opts, url });
+    const auth = await authHeaders({ ...opts, url }, fetchImpl);
+    return { url, org: opts.org, headers: { ...auth, [ORG_HEADER]: opts.org }, fetch: fetchImpl, sleep };
 }
+const BACKOFF_MS = [500, 1500];
+const MAX_RETRY_AFTER_MS = 60_000;
+// A 429 is refused before the route runs (token-auth throttle, per-route limits), so resending is safe
+// for every method. Waits the server's Retry-After (capped), else the backoff; three attempts in all.
 // Never throws on status: callers branch on it. A non-JSON body (a proxy's HTML 502) reads as undefined.
 export async function call(api, method, path, init) {
+    let res = await send(api, method, path, init);
+    for (const backoff of BACKOFF_MS) {
+        if (res.status !== 429)
+            break;
+        const after = Number(res.retryAfter);
+        await api.sleep(res.retryAfter && Number.isFinite(after) ? Math.min(after * 1000, MAX_RETRY_AFTER_MS) : backoff);
+        res = await send(api, method, path, init);
+    }
+    return { status: res.status, body: res.body };
+}
+async function send(api, method, path, init) {
     const headers = { ...api.headers, ...init?.headers };
     if (init?.body !== undefined)
         headers['content-type'] = 'application/json';
-    const res = await api.fetch(`${api.url}/api${path}`, {
+    const res = await reach(api.fetch, `${api.url}/api${path}`, {
         method,
         headers,
         body: init?.body === undefined ? undefined : JSON.stringify(init.body),
@@ -23,7 +40,7 @@ export async function call(api, method, path, init) {
     catch {
         body = undefined;
     }
-    return { status: res.status, body };
+    return { status: res.status, body, retryAfter: res.headers.get('retry-after') };
 }
 export function errorCode(res) {
     const b = (res.body ?? {});
@@ -34,11 +51,12 @@ export function errorCode(res) {
 }
 // Reads both error envelopes: AppError `{ error: { code, message } }`, and the idempotency/validation
 // `{ error: string, code?, field? }`.
-export function failure(operation, res) {
+export function failure(operation, res, scope) {
     if (res.status === 401)
         return new Error('auth rejected (HTTP 401) — token invalid/revoked, or login expired');
-    if (res.status === 403)
-        return new Error(`forbidden (HTTP 403) — ${operation} needs a token with the right scope`);
+    if (res.status === 403) {
+        return new Error(`forbidden (HTTP 403) — ${operation} needs a token with ${scope ? `the ${scope}` : 'the right'} scope`);
+    }
     let message = `${operation} failed (HTTP ${res.status})`;
     const b = (res.body ?? {});
     if (b.error && typeof b.error === 'object') {
@@ -60,7 +78,6 @@ export function isRetryable(res) {
     const e = res.body?.error;
     return !!e && typeof e === 'object' && e.retryable === true;
 }
-const BACKOFF_MS = [500, 1500];
 // Up to three attempts. The caller's `send` reuses one Idempotency-Key, so the server deduplicates.
 export async function withRetry(send, sleep) {
     let res = await send();

package/dist/auth.d.ts

@@ -8,4 +8,5 @@ export type AuthOpts = {
 };
 export declare function isLocal(url: string): boolean;
 export declare function assertTarget(opts: AuthOpts): void;
+export declare function reach(fetchImpl: typeof fetch, url: string, init: RequestInit): Promise<Response>;
 export declare function authHeaders(opts: AuthOpts, fetchImpl?: typeof fetch): Promise<Record<string, string>>;

package/dist/auth.js

@@ -1,7 +1,7 @@
 export function isLocal(url) {
     try {
         const h = new URL(url).hostname;
-        return h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0';
+        return h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0' || h === '[::1]';
     }
     catch {
         return false;
@@ -19,13 +19,24 @@ export function assertTarget(opts) {
         throw new Error(`refusing to push to non-local URL ${opts.url} without --allow-remote (or OFFSIDA_ALLOW_REMOTE=1)`);
     }
 }
+// fetch rejects with a bare "fetch failed"; name the URL and the socket error (ECONNREFUSED, ENOTFOUND…).
+export async function reach(fetchImpl, url, init) {
+    try {
+        return await fetchImpl(url, init);
+    }
+    catch (e) {
+        const cause = e.cause;
+        const detail = typeof cause?.code === 'string' ? cause.code : e.message;
+        throw new Error(`cannot reach ${url} (${detail})`);
+    }
+}
 // Two auth modes:
 //   • token      — non-interactive (CI): `Authorization: Bearer <osk_…>`, an org API token (Story 022).
 //   • email+code — interactive: exchange an emailed login code for a session cookie.
 export async function authHeaders(opts, fetchImpl = fetch) {
     if (opts.token)
         return { authorization: `Bearer ${opts.token}` };
-    const verify = await fetchImpl(`${opts.url}/api/auth/verify`, {
+    const verify = await reach(fetchImpl, `${opts.url}/api/auth/verify`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ email: opts.email, code: opts.code }),

package/dist/bundle.js

@@ -31,6 +31,8 @@ export async function bundleEntry(entryFile, opts) {
         target: 'es2022',
         write: false,
         legalComments: 'none',
+        // Halves an SDK package (most of it is zod) against the platform's 1 MiB cap (push.ts CODE_SIZE_LIMIT).
+        minify: true,
     });
     const out = result.outputFiles?.[0]?.text;
     if (!out)

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type PushDirectoryDeps } from './push-directory.js';
-export declare const USAGE = "usage:\n  offsida push  [dir] [--publish] [--url <u>] [--org <id>] [--allow-remote]\n  offsida build [dir] [--out <file>]\n\ndir defaults to the current directory and must contain a package.json.\n\npush uploads the package's code (its \"exports\"/\"main\", else src/index.ts or index.ts)\nas artifact <package name without scope> (override: \"offsida\": { \"name\": \"\u2026\" }),\nthen every *.workflow.json as that workflow's draft, replacing edits made in the\nOffsida editor. A file's optional \"id\" pins one workflow in one org; without it the\nworkflow is matched by name or created. --publish also publishes each workflow;\n\"latest\" steps lock to the code just pushed.\n\nA first publish goes live with no capability confirmation (offsida.web#14). A later\npublish that adds access is left for confirming in Offsida (exit 2). Every push mints\na new code revision, so --publish republishes \"latest\" workflows (offsida.web#15).\n\nAuth (environment only): OFFSIDA_TOKEN, or OFFSIDA_EMAIL + OFFSIDA_CODE.\nScopes: code:publish; workflows:list, :get, :create, :update; workflows:publish with --publish.\nAlso: OFFSIDA_URL (default http://localhost:3808), OFFSIDA_ORG, OFFSIDA_ALLOW_REMOTE=1.\n\nLimits: name matching reads a list that lags a few seconds, so two quick pushes of a\nnew workflow can create two. Same-named workflows in different packages overwrite\neach other without \"id\". Deleting a *.workflow.json leaves its workflow live.\n\nExit codes: 0 done, 1 something failed, 2 something needs confirming in Offsida.";
+export declare const USAGE = "usage:\n  offsida push  [dir] [--publish] [--url <u>] [--org <id>] [--allow-remote]\n  offsida build [dir] [--out <file>]\n\ndir defaults to the current directory and must contain a package.json.\n\npush uploads the package's code (its \"exports\"/\"main\", else src/index.ts or index.ts)\nas artifact <package name without scope> (override: \"offsida\": { \"name\": \"\u2026\" }),\nthen every *.workflow.json as that workflow's draft, replacing edits made in the\nOffsida editor. Subfolders with their own package.json are separate packages and\nare skipped. A file's optional \"id\" pins one workflow in one org; without it the\nworkflow is matched by name or created. --publish also publishes each workflow;\n\"latest\" steps lock to the code just pushed.\n\nA first publish goes live with no capability confirmation (offsida.web#14). A later\npublish that adds access is left for confirming in Offsida (exit 2). Every push mints\na new code revision, so --publish republishes \"latest\" workflows (offsida.web#15).\n\nAuth (environment only): OFFSIDA_TOKEN, or OFFSIDA_EMAIL + OFFSIDA_CODE.\nScopes: code:publish; workflows:list, :get, :create, :update; workflows:publish with --publish.\nAlso: OFFSIDA_URL (default http://localhost:3808), OFFSIDA_ORG, OFFSIDA_ALLOW_REMOTE=1.\n\nLimits: name matching reads a list that lags a few seconds, so two quick pushes of a\nnew workflow can create two. Same-named workflows in different packages overwrite\neach other without \"id\". Deleting a *.workflow.json leaves its workflow live.\n\nBundles are minified and must stay under the platform's 1 MiB cap. A rate-limited\nrequest (429) waits out its Retry-After, up to a minute, and is retried.\n\nExit codes: 0 done, 1 something failed, 2 something needs confirming in Offsida.";
 type RunDeps = PushDirectoryDeps & {
     out?: (s: string) => void;
     err?: (s: string) => void;

package/dist/cli.js

@@ -14,7 +14,8 @@ dir defaults to the current directory and must contain a package.json.
 push uploads the package's code (its "exports"/"main", else src/index.ts or index.ts)
 as artifact <package name without scope> (override: "offsida": { "name": "…" }),
 then every *.workflow.json as that workflow's draft, replacing edits made in the
-Offsida editor. A file's optional "id" pins one workflow in one org; without it the
+Offsida editor. Subfolders with their own package.json are separate packages and
+are skipped. A file's optional "id" pins one workflow in one org; without it the
 workflow is matched by name or created. --publish also publishes each workflow;
 "latest" steps lock to the code just pushed.
 
@@ -30,6 +31,9 @@ Limits: name matching reads a list that lags a few seconds, so two quick pushes
 new workflow can create two. Same-named workflows in different packages overwrite
 each other without "id". Deleting a *.workflow.json leaves its workflow live.
 
+Bundles are minified and must stay under the platform's 1 MiB cap. A rate-limited
+request (429) waits out its Retry-After, up to a minute, and is retried.
+
 Exit codes: 0 done, 1 something failed, 2 something needs confirming in Offsida.`;
 // Each command's flags: `true` takes a value, `false` is a switch. Anything else is refused — in
 // particular `--token`/`--code`, so a secret never has to sit in argv or shell history.

package/dist/push-directory.js

@@ -36,7 +36,7 @@ export async function pushDirectory(opts, deps = {}) {
             workflowDeps.pinned.add(f.id);
     if (!pkg.entry && files.length === 0)
         throw new Error(`${opts.dir}: nothing to push — no code entry and no *.workflow.json files`);
-    const api = await connect(opts, deps.fetch);
+    const api = await connect(opts, deps.fetch, workflowDeps.sleep);
     // Code first, so `latest` resolves to it. A failed build stops here: publishing workflows now would
     // lock them to the previous revision.
     if (pkg.entry) {

package/dist/push.d.ts

@@ -9,6 +9,7 @@ export type PushOpts = {
     name?: string;
     allowRemote?: boolean;
 };
+export declare const CODE_SIZE_LIMIT: number;
 export declare function pushCode(api: Api, name: string, code: string): Promise<{
     revision: string;
 }>;

package/dist/push.js

@@ -1,12 +1,18 @@
 import { basename } from 'node:path';
 import { bundlePackage } from './bundle.js';
 import { call, connect, failure } from './api.js';
+// The platform's cap on an artifact's modules, counted in string length (MAX_TOTAL_MODULES_BYTES in
+// apps/workflows/src/services/codeArtifacts.ts). Checked here so an oversized bundle fails before upload.
+export const CODE_SIZE_LIMIT = 1024 * 1024;
 // Upload one bundle as a new revision of artifact `name`. The build runs synchronously server-side:
 // the response is `ready` or `failed`.
 export async function pushCode(api, name, code) {
+    if (code.length > CODE_SIZE_LIMIT) {
+        throw new Error(`${name} bundle is ${code.length} characters; the platform cap is ${CODE_SIZE_LIMIT} (1 MiB) — trim dependencies`);
+    }
     const res = await call(api, 'POST', '/code', { body: { name, modules: { 'index.js': code } } });
     if (res.status === 401 || res.status === 403)
-        throw failure('pushing code', res);
+        throw failure('pushing code', res, 'code:publish');
     const body = (res.body ?? {});
     if (res.status !== 201 || !body.ok || !body.revision) {
         throw new Error(`code push failed (${body.status ?? res.status}): ${body.failureReason ?? 'unknown'}`);

package/dist/resolve-package.d.ts

@@ -7,6 +7,6 @@ export type ResolvedPackage = {
 /**
  * A package directory → what `offsida push` uploads. Artifact name: `offsida.name`, else the npm name
  * without its scope. Code entry: exports["."] → main → src/index.ts → index.ts (first that exists;
- * null = no code). Workflows: every *.workflow.json below, skipping node_modules, dist and dot-dirs.
+ * null = no code). Workflows: every *.workflow.json below, skipping node_modules, dist, dot-dirs and nested packages.
  */
 export declare function resolvePackage(dirArg: string): Promise<ResolvedPackage>;

package/dist/resolve-package.js

@@ -23,13 +23,16 @@ function exportsEntry(exp) {
     }
     return undefined;
 }
+// A subdirectory with its own package.json is another package: its workflows go with its own push, not
+// this one's (pushing them from a monorepo root would upload them without their code).
 async function findWorkflowFiles(dir) {
     const out = [];
     for (const e of await readdir(dir, { withFileTypes: true })) {
         const path = join(dir, e.name);
         if (e.isDirectory()) {
-            if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.'))
-                out.push(...(await findWorkflowFiles(path)));
+            if (SKIP_DIRS.has(e.name) || e.name.startsWith('.') || (await isFile(join(path, 'package.json'))))
+                continue;
+            out.push(...(await findWorkflowFiles(path)));
         }
         else if (e.isFile() && e.name.endsWith('.workflow.json'))
             out.push(path);
@@ -39,7 +42,7 @@ async function findWorkflowFiles(dir) {
 /**
  * A package directory → what `offsida push` uploads. Artifact name: `offsida.name`, else the npm name
  * without its scope. Code entry: exports["."] → main → src/index.ts → index.ts (first that exists;
- * null = no code). Workflows: every *.workflow.json below, skipping node_modules, dist and dot-dirs.
+ * null = no code). Workflows: every *.workflow.json below, skipping node_modules, dist, dot-dirs and nested packages.
  */
 export async function resolvePackage(dirArg) {
     const dir = resolve(dirArg);
@@ -49,7 +52,7 @@ export async function resolvePackage(dirArg) {
         raw = await readFile(pkgPath, 'utf8');
     }
     catch {
-        throw new Error(`${dirArg}: no package.json — offsida push runs in a package directory`);
+        throw new Error(`${dirArg}: no package.json — run offsida in a package directory`);
     }
     let pkg;
     try {

package/dist/workflows.js

@@ -12,7 +12,7 @@ export async function listWorkflows(api) {
     for (;;) {
         const res = await call(api, 'GET', `/workflows?limit=${PAGE}${cursor === undefined ? '' : `&cursor=${cursor}`}`);
         if (res.status !== 200)
-            throw failure('listing workflows', res);
+            throw failure('listing workflows', res, 'workflows:list');
         const items = (res.body?.items ?? []);
         const before = rows.size;
         for (const r of items)
@@ -41,7 +41,7 @@ export async function findWorkflow(api, file, rows, pinned = new Set()) {
             throw new Error(`no workflow ${file.id} in this org — "id" ties a file to one org; fix it, or remove it to match by name`);
         }
         if (res.status !== 200 || !wf)
-            throw failure('reading workflow', res);
+            throw failure('reading workflow', res, 'workflows:get');
         return { kind: 'existing', id: wf.id, currentName: wf.name };
     }
     const matches = rows.filter((r) => r.name === file.name);
@@ -57,7 +57,7 @@ export async function findWorkflow(api, file, rows, pinned = new Set()) {
     }
     const { res, wf } = await readWorkflow(api, id);
     if (res.status !== 200 || !wf)
-        throw failure('reading workflow', res);
+        throw failure('reading workflow', res, 'workflows:get');
     if (wf.name !== file.name)
         throw new Error(`workflow ${id} changed while resolving "${file.name}" — retry`);
     return { kind: 'existing', id: wf.id, currentName: wf.name };
@@ -90,12 +90,12 @@ async function saveAndPublish(api, file, rows, publish, deps, say) {
         const key = deps.idempotencyKey();
         res = await withRetry(() => call(api, 'POST', '/workflows', { body, headers: { 'Idempotency-Key': key } }), deps.sleep);
         if (res.status !== 201)
-            throw failure('saving workflow', res);
+            throw failure('saving workflow', res, 'workflows:create');
     }
     else {
         res = await call(api, 'PUT', `/workflows/${encodeURIComponent(target.id)}`, { body });
         if (res.status !== 200)
-            throw failure('saving workflow', res);
+            throw failure('saving workflow', res, 'workflows:update');
     }
     const saved = res.body;
     const id = saved.workflow.id;
@@ -144,5 +144,5 @@ async function saveAndPublish(api, file, rows, publish, deps, say) {
         say(`confirm and publish at ${editorUrl}`);
         return 'confirm';
     }
-    throw failure('publishing workflow', res);
+    throw failure('publishing workflow', res, 'workflows:publish');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offsida/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "The `offsida` CLI — bundle an integration package and publish it to a running Offsida environment.",
   "license": "MIT",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "esbuild-wasm": "^0.25.12",
-    "@offsida/types": "0.1.1"
+    "@offsida/types": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",