@offsida/cli 0.1.1 → 0.2.0

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+import { type AuthOpts } from './auth.js';
+export type Api = {
+    url: string;
+    org: string;
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+};
+export type Res = {
+    status: number;
+    body: unknown;
+};
+export declare function connect(opts: AuthOpts, fetchImpl?: typeof fetch): 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 isRetryable(res: Res): boolean;
+export declare function withRetry(send: () => Promise<Res>, sleep: (ms: number) => Promise<void>): Promise<Res>;

package/dist/api.js

@@ -0,0 +1,74 @@
+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 };
+}
+// 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) {
+    const headers = { ...api.headers, ...init?.headers };
+    if (init?.body !== undefined)
+        headers['content-type'] = 'application/json';
+    const res = await api.fetch(`${api.url}/api${path}`, {
+        method,
+        headers,
+        body: init?.body === undefined ? undefined : JSON.stringify(init.body),
+    });
+    const text = await res.text();
+    let body = undefined;
+    try {
+        body = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        body = undefined;
+    }
+    return { status: res.status, body };
+}
+export function errorCode(res) {
+    const b = (res.body ?? {});
+    if (b.error && typeof b.error === 'object' && typeof b.error.code === 'string') {
+        return b.error.code;
+    }
+    return typeof b.code === 'string' ? b.code : undefined;
+}
+// Reads both error envelopes: AppError `{ error: { code, message } }`, and the idempotency/validation
+// `{ error: string, code?, field? }`.
+export function failure(operation, res) {
+    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`);
+    let message = `${operation} failed (HTTP ${res.status})`;
+    const b = (res.body ?? {});
+    if (b.error && typeof b.error === 'object') {
+        const e = b.error;
+        message += `: ${String(e.code)}: ${String(e.message)}`;
+    }
+    else if (typeof b.error === 'string') {
+        message += `: ${b.error}`;
+        if (typeof b.field === 'string')
+            message += ` (field: ${b.field})`;
+    }
+    return new Error(message);
+}
+export function isRetryable(res) {
+    if (errorCode(res) === 'idempotency_in_progress')
+        return true;
+    if (res.status !== 503 && res.status !== 409)
+        return false;
+    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();
+    for (const ms of BACKOFF_MS) {
+        if (!isRetryable(res))
+            break;
+        await sleep(ms);
+        res = await send();
+    }
+    return res;
+}

package/dist/auth.d.ts

@@ -0,0 +1,11 @@
+export type AuthOpts = {
+    url: string;
+    org: string;
+    token?: string;
+    email?: string;
+    code?: string;
+    allowRemote?: boolean;
+};
+export declare function isLocal(url: string): boolean;
+export declare function assertTarget(opts: AuthOpts): void;
+export declare function authHeaders(opts: AuthOpts, fetchImpl?: typeof fetch): Promise<Record<string, string>>;

package/dist/auth.js

@@ -0,0 +1,40 @@
+export function isLocal(url) {
+    try {
+        const h = new URL(url).hostname;
+        return h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0';
+    }
+    catch {
+        return false;
+    }
+}
+// A non-local URL is refused without an explicit opt-in, so a stray OFFSIDA_URL cannot quietly
+// push to production.
+export function assertTarget(opts) {
+    if (!opts.org)
+        throw new Error('set --org or OFFSIDA_ORG');
+    if (!opts.token && !(opts.email && opts.code)) {
+        throw new Error('set OFFSIDA_TOKEN (CI), or OFFSIDA_EMAIL and OFFSIDA_CODE (interactive)');
+    }
+    if (!isLocal(opts.url) && !opts.allowRemote) {
+        throw new Error(`refusing to push to non-local URL ${opts.url} without --allow-remote (or OFFSIDA_ALLOW_REMOTE=1)`);
+    }
+}
+// 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`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ email: opts.email, code: opts.code }),
+        redirect: 'manual',
+    });
+    if (!verify.ok)
+        throw new Error(`login failed: HTTP ${verify.status}`);
+    const cookie = (verify.headers.get('set-cookie') ?? '').match(/session=[^;]+/)?.[0];
+    if (!cookie)
+        throw new Error('login did not return a session cookie');
+    return { cookie };
+}

package/dist/bundle.d.ts

@@ -1,3 +1,6 @@
 export declare function bundlePackage(dir: string, opts?: {
     alias?: Record<string, string>;
 }): Promise<string>;
+export declare function bundleEntry(entryFile: string, opts?: {
+    alias?: Record<string, string>;
+}): Promise<string>;

package/dist/bundle.js

@@ -13,9 +13,14 @@ async function ensureInit() {
 // prefixes (e.g. the `@core` workspace alias) — esbuild rewrites subpaths, so
 // `{ '@core': '/abs/lib/core/src' }` maps `@core/services/x` → `/abs/lib/core/src/services/x`.
 export async function bundlePackage(dir, opts) {
+    return bundleEntry(join(dir, 'index.ts'), opts);
+}
+// Bundle one entry file (and its local imports). Used by the package-rooted `push` / `build`, whose
+// entry comes from package.json or the src/index.ts convention (resolve-package.ts).
+export async function bundleEntry(entryFile, opts) {
     await ensureInit();
     const result = await esbuild.build({
-        entryPoints: [join(dir, 'index.ts')],
+        entryPoints: [entryFile],
         bundle: true,
         format: 'esm',
         platform: 'neutral',

package/dist/cli.d.ts

@@ -1,2 +1,9 @@
 #!/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.";
+type RunDeps = PushDirectoryDeps & {
+    out?: (s: string) => void;
+    err?: (s: string) => void;
+};
+export declare function run(argv: string[], env: NodeJS.ProcessEnv, deps?: RunDeps): Promise<number>;
 export {};

package/dist/cli.js

@@ -1,47 +1,134 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
-import { bundlePackage } from './bundle.js';
-import { pushPackage } from './push.js';
-function arg(flags, name) {
-    const i = flags.indexOf(`--${name}`);
-    return i >= 0 ? flags[i + 1] : undefined;
+import { fileURLToPath } from 'node:url';
+import { bundleEntry } from './bundle.js';
+import { pushDirectory } from './push-directory.js';
+import { resolvePackage } from './resolve-package.js';
+export const USAGE = `usage:
+  offsida push  [dir] [--publish] [--url <u>] [--org <id>] [--allow-remote]
+  offsida build [dir] [--out <file>]
+
+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
+workflow is matched by name or created. --publish also publishes each workflow;
+"latest" steps lock to the code just pushed.
+
+A first publish goes live with no capability confirmation (offsida.web#14). A later
+publish that adds access is left for confirming in Offsida (exit 2). Every push mints
+a new code revision, so --publish republishes "latest" workflows (offsida.web#15).
+
+Auth (environment only): OFFSIDA_TOKEN, or OFFSIDA_EMAIL + OFFSIDA_CODE.
+Scopes: code:publish; workflows:list, :get, :create, :update; workflows:publish with --publish.
+Also: OFFSIDA_URL (default http://localhost:3808), OFFSIDA_ORG, OFFSIDA_ALLOW_REMOTE=1.
+
+Limits: name matching reads a list that lags a few seconds, so two quick pushes of a
+new workflow can create two. Same-named workflows in different packages overwrite
+each other without "id". Deleting a *.workflow.json leaves its workflow live.
+
+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.
+const FLAGS = {
+    push: { '--publish': false, '--url': true, '--org': true, '--allow-remote': false },
+    build: { '--out': true },
+};
+// Flags the package-rooted `push` dropped, and where each one went.
+const REMOVED = {
+    '--token': 'set OFFSIDA_TOKEN (or OFFSIDA_EMAIL + OFFSIDA_CODE) in the environment',
+    '--email': 'set OFFSIDA_EMAIL and OFFSIDA_CODE in the environment',
+    '--code': 'set OFFSIDA_EMAIL and OFFSIDA_CODE in the environment',
+    '--name': 'set "offsida": { "name": "…" } in package.json',
+};
+class UsageError extends Error {
 }
-async function main() {
-    const [cmd, dir, ...flags] = process.argv.slice(2);
-    if (cmd === 'build') {
-        if (!dir)
-            throw new Error('usage: offsida build <dir> [--out <file>]');
-        const code = await bundlePackage(dir);
-        const out = arg(flags, 'out');
-        if (out) {
-            await writeFile(out, code);
-            process.stdout.write(`wrote ${out}\n`);
+function parse(command, args) {
+    const known = FLAGS[command];
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const flag = a.split('=')[0]; // never echo a `--token=…` value back
+        if (!a.startsWith('--'))
+            positional.push(a);
+        else if (flag in REMOVED)
+            throw new UsageError(`${flag} was removed: ${REMOVED[flag]}`);
+        else if (!(a in known))
+            throw new UsageError(`unknown flag: ${flag}`);
+        else if (known[a]) {
+            const v = args[++i];
+            if (v === undefined)
+                throw new Error(`${a} needs a value`);
+            flags.set(a, v);
         }
-        else {
-            process.stdout.write(code);
-        }
-        return;
+        else
+            flags.set(a, true);
+    }
+    if (positional.length > 1)
+        throw new Error(`unknown argument: ${positional[1]}`);
+    return { dir: positional[0] ?? process.cwd(), flags };
+}
+export async function run(argv, env, deps = {}) {
+    const out = deps.out ?? ((s) => void process.stdout.write(`${s}\n`));
+    const err = deps.err ?? ((s) => void process.stderr.write(`${s}\n`));
+    const [command, ...args] = argv;
+    if (!command || argv.includes('--help') || argv.includes('-h')) {
+        out(USAGE);
+        return 0;
     }
-    if (cmd === 'push') {
-        if (!dir)
-            throw new Error('usage: offsida push <dir> --url <u> --org <id> [--token <t> | --email <e> --code <c>]');
-        await pushPackage({
+    if (!(command in FLAGS)) {
+        err(`unknown command: ${command}\n\n${USAGE}`);
+        return 1;
+    }
+    try {
+        const { dir, flags } = parse(command, args);
+        if (command === 'build') {
+            const pkg = await resolvePackage(dir);
+            if (!pkg.entry)
+                throw new Error(`${dir}: no code entry to build`);
+            const code = await bundleEntry(pkg.entry);
+            const file = flags.get('--out');
+            if (typeof file === 'string') {
+                await writeFile(file, code);
+                out(`wrote ${file}`);
+            }
+            else
+                out(code);
+            return 0;
+        }
+        const url = flags.get('--url');
+        const org = flags.get('--org');
+        return await pushDirectory({
             dir,
-            url: arg(flags, 'url') ?? process.env.OFFSIDA_URL ?? 'http://localhost:3808',
-            org: arg(flags, 'org') ?? process.env.OFFSIDA_ORG ?? '',
-            // Non-interactive CI auth (preferred for automation): a publish token. Takes precedence.
-            token: arg(flags, 'token') ?? process.env.OFFSIDA_TOKEN,
-            // Interactive fallback: emailed login code → session cookie.
-            email: arg(flags, 'email') ?? process.env.OFFSIDA_EMAIL,
-            code: arg(flags, 'code') ?? process.env.OFFSIDA_CODE,
-            name: arg(flags, 'name'),
-            allowRemote: flags.includes('--allow-remote') || process.env.OFFSIDA_ALLOW_REMOTE === '1',
-        });
-        return;
+            publish: flags.has('--publish'),
+            url: typeof url === 'string' ? url : (env.OFFSIDA_URL ?? 'http://localhost:3808'),
+            org: typeof org === 'string' ? org : (env.OFFSIDA_ORG ?? ''),
+            allowRemote: flags.has('--allow-remote') || env.OFFSIDA_ALLOW_REMOTE === '1',
+            token: env.OFFSIDA_TOKEN,
+            email: env.OFFSIDA_EMAIL,
+            code: env.OFFSIDA_CODE,
+        }, deps);
     }
-    throw new Error(`unknown command: ${cmd ?? '(none)'} — use "build" or "push"`);
+    catch (e) {
+        err(e instanceof UsageError ? `${e.message}\n\n${USAGE}` : e.message);
+        return 1;
+    }
+}
+// Run only when executed as the binary (which may be a symlink), not when imported by a test.
+function isMain() {
+    try {
+        return !!process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    run(process.argv.slice(2), process.env).then((code) => {
+        process.exitCode = code;
+    });
 }
-main().catch((e) => {
-    process.stderr.write(`${e.message}\n`);
-    process.exit(1);
-});

package/dist/push-directory.d.ts

@@ -0,0 +1,18 @@
+import type { AuthOpts } from './auth.js';
+export type PushDirectoryOpts = AuthOpts & {
+    dir: string;
+    publish?: boolean;
+};
+export type PushDirectoryDeps = {
+    fetch?: typeof fetch;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    idempotencyKey?: () => string;
+};
+/**
+ * `offsida push [dir]`: the package's code, then each *.workflow.json as its workflow's draft (and,
+ * with `publish`, published — `latest` steps lock to the code just pushed). Throws only before anything
+ * is pushed (pre-flight, target, auth). After that every problem is reported and the result is the worst
+ * outcome: 1 failed, 2 needs confirming in Offsida, 0 done.
+ */
+export declare function pushDirectory(opts: PushDirectoryOpts, deps?: PushDirectoryDeps): Promise<0 | 1 | 2>;

package/dist/push-directory.js

@@ -0,0 +1,86 @@
+import { relative } from 'node:path';
+import { connect } from './api.js';
+import { bundleEntry } from './bundle.js';
+import { pushCode } from './push.js';
+import { resolvePackage } from './resolve-package.js';
+import { assertNoDuplicates, readWorkflowFile } from './workflow-file.js';
+import { listWorkflows, pushWorkflow } from './workflows.js';
+const SUMMARY = [
+    ['saved', 'saved'],
+    ['published', 'published'],
+    ['unchanged', 'unchanged'],
+    ['confirm', 'needs confirming in Offsida'],
+    ['failed', 'failed'],
+];
+/**
+ * `offsida push [dir]`: the package's code, then each *.workflow.json as its workflow's draft (and,
+ * with `publish`, published — `latest` steps lock to the code just pushed). Throws only before anything
+ * is pushed (pre-flight, target, auth). After that every problem is reported and the result is the worst
+ * outcome: 1 failed, 2 needs confirming in Offsida, 0 done.
+ */
+export async function pushDirectory(opts, deps = {}) {
+    const log = deps.log ?? ((line) => void process.stdout.write(`${line}\n`));
+    const workflowDeps = {
+        sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+        idempotencyKey: deps.idempotencyKey ?? (() => crypto.randomUUID()),
+        pinned: new Set(),
+    };
+    // Pre-flight: everything that can be checked locally, before any request.
+    const pkg = await resolvePackage(opts.dir);
+    const files = [];
+    for (const path of pkg.workflowFiles)
+        files.push(await readWorkflowFile(path));
+    assertNoDuplicates(files);
+    for (const f of files)
+        if (f.id !== undefined)
+            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);
+    // 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) {
+        try {
+            const { revision } = await pushCode(api, pkg.artifactName, await bundleEntry(pkg.entry));
+            log(`pushed code ${pkg.artifactName}@${revision}`);
+        }
+        catch (e) {
+            log(`error: ${e.message}`);
+            return 1;
+        }
+    }
+    if (files.length === 0)
+        return 0;
+    // One list per run, and only when some file is matched by name.
+    let rows = [];
+    let listError;
+    if (files.some((f) => f.id === undefined)) {
+        try {
+            rows = await listWorkflows(api);
+        }
+        catch (e) {
+            listError = e;
+        }
+    }
+    const outcomes = [];
+    for (const file of files) {
+        if (listError && file.id === undefined) {
+            log(relative(process.cwd(), file.path));
+            log(`  error: ${listError.message}`);
+            outcomes.push('failed');
+            continue;
+        }
+        const { outcome, lines } = await pushWorkflow(api, file, rows, !!opts.publish, workflowDeps);
+        for (const line of lines)
+            log(line);
+        outcomes.push(outcome);
+    }
+    const counts = SUMMARY.map(([o, label]) => [outcomes.filter((x) => x === o).length, label]).filter(([n]) => n > 0);
+    const n = outcomes.length;
+    log(`${n} workflow${n === 1 ? '' : 's'}: ${counts.map(([c, label]) => `${c} ${label}`).join(', ')}`);
+    if (outcomes.includes('failed'))
+        return 1;
+    if (outcomes.includes('confirm'))
+        return 2;
+    return 0;
+}

package/dist/push.d.ts

@@ -1,3 +1,4 @@
+import { type Api } from './api.js';
 export type PushOpts = {
     dir: string;
     url: string;
@@ -8,4 +9,7 @@ export type PushOpts = {
     name?: string;
     allowRemote?: boolean;
 };
+export declare function pushCode(api: Api, name: string, code: string): Promise<{
+    revision: string;
+}>;
 export declare function pushPackage(opts: PushOpts): Promise<void>;

package/dist/push.js

@@ -1,58 +1,24 @@
 import { basename } from 'node:path';
-import { ORG_HEADER } from '@offsida/types';
 import { bundlePackage } from './bundle.js';
-function isLocal(url) {
-    try {
-        const h = new URL(url).hostname;
-        return h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0';
-    }
-    catch {
-        return false;
+import { call, connect, failure } from './api.js';
+// 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) {
+    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);
+    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'}`);
     }
+    return { revision: body.revision };
 }
-// Two auth modes:
-//   • token   — non-interactive (CI): send `Authorization: Bearer <osk_…>`; no login round-trip. The
-//     token must hold the `code:publish` scope (an org API token, Story 022).
-//   • email+code — interactive: exchange an emailed login code for a session cookie, then upload.
-// A non-local --url is refused without an explicit --allow-remote opt-in (both modes).
+// Low-level: bundle <dir>/index.ts and push it as artifact `name` (default: the dir's basename). No
+// package.json involved — used by lib/integrations/scripts/dev-push.ts. The CLI's `push` command is
+// package-rooted instead (push-directory.ts).
 export async function pushPackage(opts) {
-    if (!opts.org)
-        throw new Error('--org is required');
-    if (!opts.token && !(opts.email && opts.code))
-        throw new Error('provide --token (CI), or --email and --code (interactive)');
-    if (!isLocal(opts.url) && !opts.allowRemote) {
-        throw new Error(`refusing to push to non-local URL ${opts.url} without --allow-remote (or OFFSIDA_ALLOW_REMOTE=1)`);
-    }
+    const api = await connect(opts);
     const name = opts.name ?? basename(opts.dir);
-    const code = await bundlePackage(opts.dir);
-    // Resolve the auth header: a bearer token, or a session cookie from the emailed-code exchange.
-    const authHeaders = {};
-    if (opts.token) {
-        authHeaders['authorization'] = `Bearer ${opts.token}`;
-    }
-    else {
-        const verify = await fetch(`${opts.url}/api/auth/verify`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ email: opts.email, code: opts.code }),
-            redirect: 'manual',
-        });
-        if (!verify.ok)
-            throw new Error(`login failed: HTTP ${verify.status}`);
-        const cookie = (verify.headers.get('set-cookie') ?? '').match(/session=[^;]+/)?.[0];
-        if (!cookie)
-            throw new Error('login did not return a session cookie');
-        authHeaders['cookie'] = cookie;
-    }
-    const res = await fetch(`${opts.url}/api/code`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', [ORG_HEADER]: opts.org, ...authHeaders },
-        body: JSON.stringify({ name, modules: { 'index.js': code } }),
-    });
-    if (res.status === 401)
-        throw new Error('auth rejected (HTTP 401) — token invalid/revoked, or login expired');
-    const body = (await res.json());
-    if (!body.ok)
-        throw new Error(`publish failed (${body.status ?? res.status}): ${body.failureReason ?? 'unknown'}`);
-    process.stdout.write(`pushed ${name}@${body.version} — ${body.status}\n`);
+    const { revision } = await pushCode(api, name, await bundlePackage(opts.dir));
+    process.stdout.write(`pushed ${name}@${revision} — ready\n`);
 }

package/dist/resolve-package.d.ts

@@ -0,0 +1,12 @@
+export type ResolvedPackage = {
+    dir: string;
+    artifactName: string;
+    entry: string | null;
+    workflowFiles: string[];
+};
+/**
+ * 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.
+ */
+export declare function resolvePackage(dirArg: string): Promise<ResolvedPackage>;

package/dist/resolve-package.js

@@ -0,0 +1,79 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+// The platform's artifact name rule (lib/contracts/src/schemas/code.ts publishBody).
+const ARTIFACT_NAME = /^[a-zA-Z0-9._-]{1,64}$/;
+const SKIP_DIRS = new Set(['node_modules', 'dist']);
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function exportsEntry(exp) {
+    const dot = exp && typeof exp === 'object' && '.' in exp ? exp['.'] : exp;
+    if (typeof dot === 'string')
+        return dot;
+    if (dot && typeof dot === 'object') {
+        const c = dot;
+        for (const k of ['import', 'default'])
+            if (typeof c[k] === 'string')
+                return c[k];
+    }
+    return undefined;
+}
+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)));
+        }
+        else if (e.isFile() && e.name.endsWith('.workflow.json'))
+            out.push(path);
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+export async function resolvePackage(dirArg) {
+    const dir = resolve(dirArg);
+    const pkgPath = join(dir, 'package.json');
+    let raw;
+    try {
+        raw = await readFile(pkgPath, 'utf8');
+    }
+    catch {
+        throw new Error(`${dirArg}: no package.json — offsida push runs in a package directory`);
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${pkgPath}: not valid JSON`);
+    }
+    const override = pkg.offsida && typeof pkg.offsida.name === 'string' ? pkg.offsida.name : undefined;
+    const npmName = typeof pkg.name === 'string' ? pkg.name.replace(/^@[^/]+\//, '') : undefined;
+    const artifactName = override ?? npmName;
+    if (!artifactName)
+        throw new Error(`${pkgPath}: no "name" (or "offsida.name") to name the artifact`);
+    if (!ARTIFACT_NAME.test(artifactName)) {
+        throw new Error(`artifact name "${artifactName}" is not allowed (letters, digits, . _ -, max 64) — set "offsida": { "name": "…" } in package.json`);
+    }
+    const candidates = [exportsEntry(pkg.exports), typeof pkg.main === 'string' ? pkg.main : undefined, 'src/index.ts', 'index.ts'];
+    let entry = null;
+    for (const c of candidates) {
+        if (c && (await isFile(join(dir, c)))) {
+            entry = join(dir, c);
+            break;
+        }
+    }
+    const workflowFiles = (await findWorkflowFiles(dir)).sort();
+    return { dir, artifactName, entry, workflowFiles };
+}

package/dist/workflow-file.d.ts

@@ -0,0 +1,9 @@
+/** A `*.workflow.json` file. `id` pins one workflow in one org; only `name` + `definition` are sent. */
+export type WorkflowFile = {
+    path: string;
+    id?: string;
+    name: string;
+    definition: Record<string, unknown>;
+};
+export declare function readWorkflowFile(path: string): Promise<WorkflowFile>;
+export declare function assertNoDuplicates(files: WorkflowFile[]): void;

package/dist/workflow-file.js

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// Shape checks only — the server owns full definition validation. The name is trimmed, as the server
+// trims it, so matching by name and the duplicate check compare what Offsida actually stores.
+export async function readWorkflowFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        throw new Error(`${path}: cannot read`);
+    }
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${path}: not valid JSON`);
+    }
+    if (!isObject(v))
+        throw new Error(`${path}: expected a JSON object`);
+    if (typeof v.name !== 'string' || !v.name.trim())
+        throw new Error(`${path}: "name" must be a non-empty string`);
+    if (!isObject(v.definition))
+        throw new Error(`${path}: "definition" must be an object`);
+    if ('id' in v && (typeof v.id !== 'string' || !v.id))
+        throw new Error(`${path}: "id", when present, must be a non-empty string`);
+    return { path, ...(typeof v.id === 'string' ? { id: v.id } : {}), name: v.name.trim(), definition: v.definition };
+}
+// Two files aimed at the same workflow would silently overwrite each other, so refuse the run.
+export function assertNoDuplicates(files) {
+    const byId = new Map();
+    const byName = new Map();
+    for (const f of files) {
+        if (f.id !== undefined) {
+            const prev = byId.get(f.id);
+            if (prev)
+                throw new Error(`${prev.path} and ${f.path} both have "id": "${f.id}"`);
+            byId.set(f.id, f);
+        }
+        else {
+            const prev = byName.get(f.name);
+            if (prev)
+                throw new Error(`${prev.path} and ${f.path} are both named "${f.name}" — add "id" to one, or rename it`);
+            byName.set(f.name, f);
+        }
+    }
+}

package/dist/workflows.d.ts

@@ -0,0 +1,42 @@
+import { type Api } from './api.js';
+import type { WorkflowFile } from './workflow-file.js';
+export type WorkflowRow = {
+    workflow_id: string;
+    name: string;
+    updated_at: number;
+};
+export type Target = {
+    kind: 'existing';
+    id: string;
+    currentName: string;
+} | {
+    kind: 'new';
+};
+/**
+ * Every workflow row in the org (the D1 index — it can lag the DO by a few seconds). The list has no
+ * `nextCursor` and its cursor is a strict `updated_at <`, so rows sharing a timestamp could fall between
+ * pages; paging from `last + 1` makes the cursor inclusive and the overlap is de-duplicated by id.
+ */
+export declare function listWorkflows(api: Api): Promise<WorkflowRow[]>;
+/**
+ * Which workflow a file writes. An `id` is authoritative (a 404 fails — ids are minted per org, so there
+ * is nothing to create and a name fallback would defeat the pin). Without one, match the name exactly
+ * against `rows`, and confirm a single match against the workflow itself (DO-backed) before writing.
+ * `pinned` holds the ids other files in this run pin: a name match landing on one would overwrite it.
+ */
+export declare function findWorkflow(api: Api, file: WorkflowFile, rows: WorkflowRow[], pinned?: ReadonlySet<string>): Promise<Target>;
+export type Outcome = 'saved' | 'published' | 'unchanged' | 'confirm' | 'failed';
+export type WorkflowDeps = {
+    sleep: (ms: number) => Promise<void>;
+    idempotencyKey: () => string;
+    pinned?: ReadonlySet<string>;
+};
+/**
+ * Save one workflow file as its workflow's draft and, with `publish`, publish it. Never throws: every
+ * problem becomes `outcome: 'failed'` with an `error:` line, so one workflow can't stop the others.
+ * `lines[0]` is the file's path; the rest are indented under it.
+ */
+export declare function pushWorkflow(api: Api, file: WorkflowFile, rows: WorkflowRow[], publish: boolean, deps: WorkflowDeps): Promise<{
+    outcome: Outcome;
+    lines: string[];
+}>;

package/dist/workflows.js

@@ -0,0 +1,148 @@
+import { relative } from 'node:path';
+import { call, failure, withRetry } from './api.js';
+const PAGE = 200; // the server's limit cap
+/**
+ * Every workflow row in the org (the D1 index — it can lag the DO by a few seconds). The list has no
+ * `nextCursor` and its cursor is a strict `updated_at <`, so rows sharing a timestamp could fall between
+ * pages; paging from `last + 1` makes the cursor inclusive and the overlap is de-duplicated by id.
+ */
+export async function listWorkflows(api) {
+    const rows = new Map();
+    let cursor;
+    for (;;) {
+        const res = await call(api, 'GET', `/workflows?limit=${PAGE}${cursor === undefined ? '' : `&cursor=${cursor}`}`);
+        if (res.status !== 200)
+            throw failure('listing workflows', res);
+        const items = (res.body?.items ?? []);
+        const before = rows.size;
+        for (const r of items)
+            rows.set(r.workflow_id, r);
+        if (items.length < PAGE || rows.size === before)
+            break;
+        cursor = items[items.length - 1].updated_at + 1;
+    }
+    return [...rows.values()];
+}
+async function readWorkflow(api, id) {
+    const res = await call(api, 'GET', `/workflows/${encodeURIComponent(id)}`);
+    const wf = res.body?.workflow;
+    return { res, wf };
+}
+/**
+ * Which workflow a file writes. An `id` is authoritative (a 404 fails — ids are minted per org, so there
+ * is nothing to create and a name fallback would defeat the pin). Without one, match the name exactly
+ * against `rows`, and confirm a single match against the workflow itself (DO-backed) before writing.
+ * `pinned` holds the ids other files in this run pin: a name match landing on one would overwrite it.
+ */
+export async function findWorkflow(api, file, rows, pinned = new Set()) {
+    if (file.id !== undefined) {
+        const { res, wf } = await readWorkflow(api, file.id);
+        if (res.status === 404) {
+            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);
+        return { kind: 'existing', id: wf.id, currentName: wf.name };
+    }
+    const matches = rows.filter((r) => r.name === file.name);
+    if (matches.length === 0)
+        return { kind: 'new' };
+    if (matches.length > 1) {
+        const lines = matches.map((m) => `  ${m.workflow_id} (updated ${new Date(m.updated_at).toISOString()})`);
+        throw new Error([`${matches.length} workflows are named "${file.name}" — add "id" to ${file.path} to pick one:`, ...lines].join('\n'));
+    }
+    const id = matches[0].workflow_id;
+    if (pinned.has(id)) {
+        throw new Error(`workflow ${id} (named "${file.name}") is pinned by another file's "id" — rename this one, or give it its own "id"`);
+    }
+    const { res, wf } = await readWorkflow(api, id);
+    if (res.status !== 200 || !wf)
+        throw failure('reading workflow', res);
+    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 };
+}
+const CAPABILITIES = ['secrets', 'connections', 'egressDomains', 'artifacts', 'containerImages'];
+const indent = (text) => text.split('\n').map((l) => `  ${l}`);
+/**
+ * Save one workflow file as its workflow's draft and, with `publish`, publish it. Never throws: every
+ * problem becomes `outcome: 'failed'` with an `error:` line, so one workflow can't stop the others.
+ * `lines[0]` is the file's path; the rest are indented under it.
+ */
+export async function pushWorkflow(api, file, rows, publish, deps) {
+    const lines = [relative(process.cwd(), file.path)];
+    const say = (text) => lines.push(...indent(text));
+    try {
+        const outcome = await saveAndPublish(api, file, rows, publish, deps, say);
+        return { outcome, lines };
+    }
+    catch (e) {
+        say(`error: ${e.message}`);
+        return { outcome: 'failed', lines };
+    }
+}
+async function saveAndPublish(api, file, rows, publish, deps, say) {
+    const target = await findWorkflow(api, file, rows, deps.pinned);
+    const body = { name: file.name, definition: file.definition };
+    // The file always wins: a full replace with no If-Match (spec decision 6).
+    let res;
+    if (target.kind === 'new') {
+        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);
+    }
+    else {
+        res = await call(api, 'PUT', `/workflows/${encodeURIComponent(target.id)}`, { body });
+        if (res.status !== 200)
+            throw failure('saving workflow', res);
+    }
+    const saved = res.body;
+    const id = saved.workflow.id;
+    const editorUrl = `${api.url}/org/${api.org}/workflows/${id}/edit`;
+    if (target.kind === 'new') {
+        say(`created workflow ${id} "${file.name}"`);
+        say(`add "id": "${id}" to this file so renames update this workflow (ids are per org)`);
+    }
+    else {
+        say(`updated workflow ${id} "${file.name}"${target.currentName !== file.name ? ` (renamed from "${target.currentName}")` : ''}`);
+    }
+    say(editorUrl);
+    for (const d of saved.diagnostics ?? [])
+        say(`warning: [${d.code}] ${d.path}: ${d.message}`);
+    if (!publish)
+        return 'saved';
+    // No body: the CLI never acknowledges a capability escalation (spec decision 7).
+    const key = deps.idempotencyKey();
+    res = await withRetry(() => call(api, 'POST', `/workflows/${encodeURIComponent(id)}/publish`, { headers: { 'Idempotency-Key': key } }), deps.sleep);
+    const b = (res.body ?? {});
+    if (res.status === 201) {
+        say(`published revision ${b.publishedRevision}`);
+        for (const a of b.resolvedArtifacts ?? []) {
+            const was = a.previousRevision !== null && a.previousRevision !== a.revision ? ` (was ${a.previousRevision})` : '';
+            say(`  ${a.stepId}: ${a.artifactName}@${a.revision}${was}`);
+        }
+        return 'published';
+    }
+    if (res.status === 200) {
+        say(`unchanged — already published as revision ${b.publishedRevision}`);
+        return 'unchanged';
+    }
+    if (res.status === 422 && Array.isArray(b.diagnostics)) {
+        say('publish blocked — the draft is uploaded but not live:');
+        for (const d of b.diagnostics.filter((x) => x.blocksPublish))
+            say(`  [${d.code}] ${d.path}: ${d.message}`);
+        return 'failed';
+    }
+    if (res.status === 428) {
+        say('needs confirming in Offsida — the draft is uploaded but adds access:');
+        for (const c of CAPABILITIES) {
+            const added = b.escalation?.[c]?.added ?? [];
+            if (added.length)
+                say(`  ${c}: ${added.join(', ')}`);
+        }
+        say(`confirm and publish at ${editorUrl}`);
+        return 'confirm';
+    }
+    throw failure('publishing workflow', res);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offsida/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "The `offsida` CLI — bundle an integration package and publish it to a running Offsida environment.",
   "license": "MIT",
@@ -20,6 +20,10 @@
     "./push": {
       "types": "./dist/push.d.ts",
       "default": "./dist/push.js"
+    },
+    "./push-directory": {
+      "types": "./dist/push-directory.d.ts",
+      "default": "./dist/push-directory.js"
     }
   },
   "files": [