@offsida/cli 0.2.0 → 0.3.0

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.d.ts

@@ -1,6 +1,18 @@
+import type { ArtifactFile } from './resolve-package.js';
 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>;
+/**
+ * The generated entry for `<name>.action.ts`: its default export, as the one action of a definePackage
+ * named after the file. definePackage is what turns Zod schemas into JSON Schema; the guard turns a
+ * missing or wrong default export into the publish probe's failure reason instead of a run-time miss.
+ */
+export declare function actionWrapper(dir: string, artifact: ArtifactFile): string;
+export type BundledArtifact = {
+    code: string;
+    inputs: string[];
+};
+export declare function bundleArtifact(dir: string, artifact: ArtifactFile): Promise<BundledArtifact>;

package/dist/bundle.js

@@ -1,5 +1,5 @@
 import * as esbuild from 'esbuild-wasm';
-import { join } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 let initialized = false;
 async function ensureInit() {
     if (initialized)
@@ -7,33 +7,65 @@ async function ensureInit() {
     await esbuild.initialize({});
     initialized = true;
 }
+const OPTIONS = {
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    mainFields: ['module', 'main'],
+    conditions: ['workerd', 'worker', 'browser', 'default'],
+    external: ['cloudflare:workers', 'cloudflare:test', 'node:*', 'fs', 'fs/promises', 'path'],
+    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,
+};
+function outputText(result) {
+    const out = result.outputFiles?.[0]?.text;
+    if (!out)
+        throw new Error('esbuild produced no output');
+    return out;
+}
 // Bundle <dir>/index.ts (and its local imports) into a single ESM module string,
-// preserving the package's `export default {...}`. Used by `offsida build` and by
-// the platform conformance test. `opts.alias` lets callers resolve bare import
+// preserving the package's `export default {...}`. Used by the platform conformance
+// test and `pushPackage`. `opts.alias` lets callers resolve bare import
 // 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).
+// Bundle one entry file (and its local imports).
 export async function bundleEntry(entryFile, opts) {
     await ensureInit();
-    const result = await esbuild.build({
-        entryPoints: [entryFile],
-        bundle: true,
-        format: 'esm',
-        platform: 'neutral',
-        mainFields: ['module', 'main'],
-        conditions: ['workerd', 'worker', 'browser', 'default'],
-        external: ['cloudflare:workers', 'cloudflare:test', 'node:*', 'fs', 'fs/promises', 'path'],
-        alias: opts?.alias,
-        target: 'es2022',
-        write: false,
-        legalComments: 'none',
-    });
-    const out = result.outputFiles?.[0]?.text;
-    if (!out)
-        throw new Error('esbuild produced no output');
-    return out;
+    return outputText(await esbuild.build({ ...OPTIONS, entryPoints: [entryFile], alias: opts?.alias }));
+}
+/**
+ * The generated entry for `<name>.action.ts`: its default export, as the one action of a definePackage
+ * named after the file. definePackage is what turns Zod schemas into JSON Schema; the guard turns a
+ * missing or wrong default export into the publish probe's failure reason instead of a run-time miss.
+ */
+export function actionWrapper(dir, artifact) {
+    const rel = relative(dir, artifact.file).split(sep).join('/');
+    return [
+        `import { definePackage } from '@offsida/sdk';`,
+        `import action from ${JSON.stringify(`./${rel}`)};`,
+        `if (!action || typeof action.run !== 'function') {`,
+        `\tthrow new Error(${JSON.stringify(`${rel} must default-export defineAction({ … run … })`)});`,
+        `}`,
+        `export default definePackage({ actions: { ${JSON.stringify(artifact.name)}: action } });`,
+        ``,
+    ].join('\n');
+}
+// Bundle one artifact file. `inputs` lists every source file in the bundle (absolute), so a caller can
+// see what a package file pulls in.
+export async function bundleArtifact(dir, artifact) {
+    await ensureInit();
+    const entry = artifact.kind === 'action'
+        ? { stdin: { contents: actionWrapper(dir, artifact), resolveDir: dir, sourcefile: `<offsida:${artifact.name}>`, loader: 'ts' } }
+        : { entryPoints: [artifact.file] };
+    const result = await esbuild.build({ ...OPTIONS, ...entry, absWorkingDir: dir, metafile: true });
+    const inputs = Object.keys(result.metafile.inputs)
+        .filter((p) => !p.startsWith('<'))
+        .map((p) => resolve(dir, p));
+    return { code: outputText(result), inputs };
 }

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-dir <dir>]\n\ndir defaults to the current directory and must contain a package.json.\n\nEvery file below dir is one artifact, named after the file:\n  <name>.action.ts   default-exports defineAction(\u2026); uploaded as a package holding that\n                     one action, also called <name>. Names are kebab-case (a-z, 0-9, -).\n  <name>.package.ts  default-exports definePackage(\u2026) \u2014 for connections, triggers, config,\n                     or several actions sharing one revision. Letters, digits, . _ -.\nNames are per org: two packages pushing the same name overwrite each other's artifact.\nA package file may not import an action file (that action would be published twice).\n\npush uploads every package file, then every action file (so an action requiring a\npackage's connection gets the one just pushed), then every *.workflow.json as that\nworkflow's draft, replacing edits made in the Offsida editor. A failed upload skips\nthe workflows. Subfolders with their own package.json are separate packages and are\nskipped, as are node_modules, dist and dot-folders. A workflow file's optional \"id\"\npins one workflow in one org; without it the workflow is matched by name or created.\n--publish also publishes each workflow; \"latest\" steps lock to the code just pushed.\n\nbuild bundles every artifact without uploading: with --out-dir it writes <name>.js\nfor each; without, it prints each artifact's size against the cap.\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 revision of every artifact, so --publish republishes \"latest\" workflows\n(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

@@ -1,26 +1,41 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { bundleEntry } from './bundle.js';
+import { prepareArtifacts } from './prepare.js';
+import { CODE_SIZE_LIMIT } from './push.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>]
+  offsida build [dir] [--out-dir <dir>]
 
 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.
+Every file below dir is one artifact, named after the file:
+  <name>.action.ts   default-exports defineAction(…); uploaded as a package holding that
+                     one action, also called <name>. Names are kebab-case (a-z, 0-9, -).
+  <name>.package.ts  default-exports definePackage(…) — for connections, triggers, config,
+                     or several actions sharing one revision. Letters, digits, . _ -.
+Names are per org: two packages pushing the same name overwrite each other's artifact.
+A package file may not import an action file (that action would be published twice).
+
+push uploads every package file, then every action file (so an action requiring a
+package's connection gets the one just pushed), then every *.workflow.json as that
+workflow's draft, replacing edits made in the Offsida editor. A failed upload skips
+the workflows. Subfolders with their own package.json are separate packages and are
+skipped, as are node_modules, dist and dot-folders. A workflow 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.
+
+build bundles every artifact without uploading: with --out-dir it writes <name>.js
+for each; without, it prints each artifact's size against the cap.
 
 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).
+a new revision of every artifact, 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.
@@ -30,19 +45,23 @@ 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.
 const FLAGS = {
     push: { '--publish': false, '--url': true, '--org': true, '--allow-remote': false },
-    build: { '--out': true },
+    build: { '--out-dir': 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',
+    '--name': 'name the file <name>.action.ts or <name>.package.ts',
+    '--out': 'use --out-dir <dir>, which writes one <name>.js per artifact',
 };
 class UsageError extends Error {
 }
@@ -88,16 +107,28 @@ export async function run(argv, env, deps = {}) {
         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}`);
+            for (const w of pkg.warnings)
+                err(`warning: ${w}`);
+            if (pkg.artifacts.length === 0)
+                throw new Error(`${dir}: no *.action.ts or *.package.ts files to build`);
+            const artifacts = await prepareArtifacts(pkg);
+            const outDir = flags.get('--out-dir');
+            if (typeof outDir === 'string') {
+                await mkdir(outDir, { recursive: true });
+                for (const a of artifacts) {
+                    const file = join(outDir, `${a.name}.js`);
+                    await writeFile(file, a.code);
+                    out(`wrote ${file}`);
+                }
+            }
+            else {
+                const rows = artifacts.map((a) => [a.name, relative(pkg.dir, a.file), a.code.length]);
+                const w0 = Math.max(...rows.map((r) => r[0].length));
+                const w1 = Math.max(...rows.map((r) => r[1].length));
+                for (const [name, file, size] of rows) {
+                    out(`${name.padEnd(w0)}  ${file.padEnd(w1)}  ${size} chars (${Math.round((size / CODE_SIZE_LIMIT) * 100)}% of 1 MiB)`);
+                }
             }
-            else
-                out(code);
             return 0;
         }
         const url = flags.get('--url');

package/dist/prepare.d.ts

@@ -0,0 +1,11 @@
+import type { ArtifactFile, ResolvedPackage } from './resolve-package.js';
+export type PreparedArtifact = ArtifactFile & {
+    code: string;
+};
+/**
+ * Bundle every artifact and run every check that needs a bundle, before anything is uploaded: the SDK
+ * an action file's wrapper imports (reported once, however many action files), a build that fails, a bundle over the platform cap, and a package
+ * file that pulls in an action file (which would publish that action twice). Every problem is reported
+ * in one error. Returned in the package's artifact order.
+ */
+export declare function prepareArtifacts(pkg: ResolvedPackage): Promise<PreparedArtifact[]>;

package/dist/prepare.js

@@ -0,0 +1,65 @@
+import { basename, relative } from 'node:path';
+import { bundleArtifact } from './bundle.js';
+import { CODE_SIZE_LIMIT } from './push.js';
+const ACTION_SUFFIX = '.action.ts';
+const WRAPPER = '<offsida:';
+// esbuild reports each error with a location relative to the package; the generated wrapper's is a
+// pseudo-path, so it is named instead.
+function buildMessage(e) {
+    const errors = e.errors;
+    if (!errors?.length)
+        return e.message;
+    return errors
+        .map((x) => {
+        if (!x.location)
+            return x.text;
+        const where = x.location.file.includes(WRAPPER) ? 'generated wrapper' : `${x.location.file}:${x.location.line}`;
+        return `${x.text} (${where})`;
+    })
+        .join('; ');
+}
+// The wrapper's own `import … from '@offsida/sdk'` failed: resolution is left to esbuild, the same
+// resolver the bundle uses (Node's would also search NODE_PATH, which pnpm sets for every script).
+const sdkMissing = (e) => !!e.errors?.some((x) => x.text === 'Could not resolve "@offsida/sdk"' && x.location?.file.includes(WRAPPER));
+/**
+ * Bundle every artifact and run every check that needs a bundle, before anything is uploaded: the SDK
+ * an action file's wrapper imports (reported once, however many action files), a build that fails, a bundle over the platform cap, and a package
+ * file that pulls in an action file (which would publish that action twice). Every problem is reported
+ * in one error. Returned in the package's artifact order.
+ */
+export async function prepareArtifacts(pkg) {
+    const problems = [];
+    let noSdk = false;
+    const prepared = [];
+    for (const artifact of pkg.artifacts) {
+        const rel = relative(pkg.dir, artifact.file);
+        let bundled;
+        try {
+            bundled = await bundleArtifact(pkg.dir, artifact);
+        }
+        catch (e) {
+            if (artifact.kind === 'action' && sdkMissing(e)) {
+                noSdk = true;
+                continue;
+            }
+            problems.push(`${rel}: ${buildMessage(e)}`);
+            continue;
+        }
+        if (artifact.kind === 'package') {
+            for (const input of bundled.inputs.filter((p) => p.endsWith(ACTION_SUFFIX))) {
+                const shared = basename(input).slice(0, -ACTION_SUFFIX.length);
+                problems.push(`${rel} imports ${relative(pkg.dir, input)}, which is already its own artifact — move the shared code into a plain module (e.g. ${shared}.ts) that both import`);
+            }
+        }
+        if (bundled.code.length > CODE_SIZE_LIMIT) {
+            problems.push(`${rel} bundles to ${bundled.code.length} characters; the platform cap is ${CODE_SIZE_LIMIT} (1 MiB) — trim dependencies`);
+        }
+        prepared.push({ ...artifact, code: bundled.code });
+    }
+    if (noSdk) {
+        problems.unshift(`@offsida/sdk is not installed in ${pkg.dir} — action files are wrapped in its definePackage; add it as a dependency`);
+    }
+    if (problems.length > 0)
+        throw new Error(problems.join('\n'));
+    return prepared;
+}

package/dist/push-directory.d.ts

@@ -10,8 +10,8 @@ export type PushDirectoryDeps = {
     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
+ * `offsida push [dir]`: each *.package.ts / *.action.ts as its own artifact, 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.
  */

package/dist/push-directory.js

@@ -1,6 +1,6 @@
 import { relative } from 'node:path';
 import { connect } from './api.js';
-import { bundleEntry } from './bundle.js';
+import { prepareArtifacts } from './prepare.js';
 import { pushCode } from './push.js';
 import { resolvePackage } from './resolve-package.js';
 import { assertNoDuplicates, readWorkflowFile } from './workflow-file.js';
@@ -13,8 +13,8 @@ const SUMMARY = [
     ['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
+ * `offsida push [dir]`: each *.package.ts / *.action.ts as its own artifact, 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.
  */
@@ -27,6 +27,8 @@ export async function pushDirectory(opts, deps = {}) {
     };
     // Pre-flight: everything that can be checked locally, before any request.
     const pkg = await resolvePackage(opts.dir);
+    for (const w of pkg.warnings)
+        log(`warning: ${w}`);
     const files = [];
     for (const path of pkg.workflowFiles)
         files.push(await readWorkflowFile(path));
@@ -34,21 +36,28 @@ export async function pushDirectory(opts, deps = {}) {
     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) {
+    if (pkg.artifacts.length === 0 && files.length === 0) {
+        throw new Error(`${opts.dir}: nothing to push — no *.action.ts, *.package.ts or *.workflow.json files`);
+    }
+    const artifacts = await prepareArtifacts(pkg);
+    const api = await connect(opts, deps.fetch, workflowDeps.sleep);
+    // Code first, so `latest` resolves to it; packages before actions, so an action requiring a package's
+    // connection resolves to the one just pushed. The artifacts are independent uploads, so one failing
+    // doesn't stop the rest — but it stops the workflows: publishing them now would lock their steps to
+    // that artifact's previous revision.
+    let codeFailed = false;
+    for (const a of artifacts) {
         try {
-            const { revision } = await pushCode(api, pkg.artifactName, await bundleEntry(pkg.entry));
-            log(`pushed code ${pkg.artifactName}@${revision}`);
+            const { revision } = await pushCode(api, a.name, a.code);
+            log(`pushed code ${a.name}@${revision}`);
         }
         catch (e) {
-            log(`error: ${e.message}`);
-            return 1;
+            log(`error: ${a.name}: ${e.message}`);
+            codeFailed = true;
         }
     }
+    if (codeFailed)
+        return 1;
     if (files.length === 0)
         return 0;
     // One list per run, and only when some file is matched by name.

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

@@ -1,12 +1,20 @@
+export type ArtifactKind = 'action' | 'package';
+/** One artifact file: `<name>.action.ts` (one defineAction) or `<name>.package.ts` (a definePackage). */
+export type ArtifactFile = {
+    name: string;
+    kind: ArtifactKind;
+    file: string;
+};
 export type ResolvedPackage = {
     dir: string;
-    artifactName: string;
-    entry: string | null;
+    artifacts: ArtifactFile[];
     workflowFiles: string[];
+    warnings: 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.
+ * A package directory → what `offsida push` uploads. Artifacts: every `<name>.action.ts` and
+ * `<name>.package.ts` below, each named after its file, packages first (an action may require a
+ * package's connection) then by name. Workflows: every *.workflow.json below. Both skip node_modules,
+ * dist, dot-dirs and nested packages. Every naming problem is reported in one error.
  */
 export declare function resolvePackage(dirArg: string): Promise<ResolvedPackage>;

package/dist/resolve-package.js

@@ -1,7 +1,14 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { join, relative, 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}$/;
+// An action file's name is also its action's name, which the manifest schema holds to kebab-case
+// (lib/contracts/src/schemas/connections.ts actionDefinitionSchema).
+const ACTION_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+const SUFFIXES = [
+    ['.action.ts', 'action'],
+    ['.package.ts', 'package'],
+];
 const SKIP_DIRS = new Set(['node_modules', 'dist']);
 async function isFile(path) {
     try {
@@ -11,35 +18,39 @@ async function isFile(path) {
         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 = [];
+// A subdirectory with its own package.json is another package: its files go with its own push, not
+// this one's (pushing them from a monorepo root would upload them without their dependencies).
+async function walk(dir, 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;
+            await walk(path, out);
+        }
+        else if (e.isFile()) {
+            if (e.name.endsWith('.workflow.json'))
+                out.workflowFiles.push(path);
+            const match = SUFFIXES.find(([suffix]) => e.name.endsWith(suffix));
+            if (match)
+                out.artifacts.push({ name: e.name.slice(0, -match[0].length), kind: match[1], file: path });
         }
-        else if (e.isFile() && e.name.endsWith('.workflow.json'))
-            out.push(path);
     }
-    return out;
 }
+function suggestActionName(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^[^a-z]+/, '')
+        .replace(/-+$/, '');
+    return s || 'my-action';
+}
+const byKindThenName = (a, b) => (a.kind === b.kind ? 0 : a.kind === 'package' ? -1 : 1) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 /**
- * 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.
+ * A package directory → what `offsida push` uploads. Artifacts: every `<name>.action.ts` and
+ * `<name>.package.ts` below, each named after its file, packages first (an action may require a
+ * package's connection) then by name. Workflows: every *.workflow.json below. Both skip node_modules,
+ * dist, dot-dirs and nested packages. Every naming problem is reported in one error.
  */
 export async function resolvePackage(dirArg) {
     const dir = resolve(dirArg);
@@ -49,7 +60,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 {
@@ -58,22 +69,30 @@ export async function resolvePackage(dirArg) {
     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 warnings = [];
+    if (pkg.offsida?.name !== undefined) {
+        warnings.push('package.json: "offsida.name" is ignored — artifacts are named after their *.action.ts / *.package.ts files');
     }
-    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 found = { artifacts: [], workflowFiles: [] };
+    await walk(dir, found);
+    const artifacts = found.artifacts.sort(byKindThenName);
+    const problems = [];
+    const seen = new Map();
+    for (const a of artifacts) {
+        const rel = relative(dir, a.file);
+        if (a.kind === 'action' && !ACTION_NAME.test(a.name)) {
+            problems.push(`${rel}: an action file name must be kebab-case (a-z, 0-9, -; starting with a letter; max 64) — it is also the action's name. Try ${suggestActionName(a.name)}.action.ts`);
+        }
+        else if (!ARTIFACT_NAME.test(a.name)) {
+            problems.push(`${rel}: "${a.name}" is not a valid artifact name (letters, digits, . _ -, max 64)`);
         }
+        const first = seen.get(a.name);
+        if (first)
+            problems.push(`"${a.name}" is declared by both ${first} and ${rel} — artifact names are per org, so each file name must be unique`);
+        else
+            seen.set(a.name, rel);
     }
-    const workflowFiles = (await findWorkflowFiles(dir)).sort();
-    return { dir, artifactName, entry, workflowFiles };
+    if (problems.length > 0)
+        throw new Error(problems.join('\n'));
+    return { dir, artifacts, workflowFiles: found.workflowFiles.sort(), warnings };
 }

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,12 +57,66 @@ 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 };
 }
-const CAPABILITIES = ['secrets', 'connections', 'egressDomains', 'artifacts', 'containerImages'];
+const CAPABILITIES = ['secrets', 'connections', 'egressDomains', 'artifacts', 'containerImages', 'fileStores'];
+/** `${stepId}:${storeId}:${mode}` (the CLI stays free of the contracts package, so this mirrors `parseFileStoreEntry`). */
+function parseGrant(entry) {
+    const parts = entry.split(':');
+    const mode = parts.pop() ?? '';
+    const store = parts.pop() ?? '';
+    return { stepId: parts.join(':'), store, mode };
+}
+/** Every store id the definition binds, at any depth (nested steps included). */
+function boundStoreIds(node, into = new Set()) {
+    if (Array.isArray(node))
+        for (const v of node)
+            boundStoreIds(v, into);
+    else if (node && typeof node === 'object') {
+        for (const [k, v] of Object.entries(node)) {
+            if (k === 'fileStoreBindings' && v && typeof v === 'object') {
+                for (const b of Object.values(v)) {
+                    const id = b?.storeId;
+                    if (typeof id === 'string')
+                        into.add(id);
+                }
+            }
+            else
+                boundStoreIds(v, into);
+        }
+    }
+    return into;
+}
+/**
+ * The org's stores by id, best effort: `undefined` when the list cannot be read (a token without `files:list`, a network
+ * error) — the escalation is then still shown, by store id, with no SENSITIVE marker and a note that sensitivity is unknown.
+ */
+async function loadStores(api) {
+    try {
+        const res = await call(api, 'GET', '/files');
+        const items = res.body?.items;
+        if (res.status !== 200 || !Array.isArray(items))
+            return undefined;
+        return new Map(items.map((s) => [s.storeId, { name: s.name, sensitive: s.sensitive }]));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One file-store grant, readably: `step <id>: <store name | run store> — <mode>`, with a SENSITIVE marker on a sensitive
+ * store and on a run-store grant in a workflow that holds a sensitive binding.
+ */
+function grantLine(entry, stores, workflowSensitive) {
+    const { stepId, store, mode } = parseGrant(entry);
+    const info = stores.get(store);
+    const isRun = store === 'run';
+    const sensitive = isRun ? workflowSensitive : (info?.sensitive ?? false);
+    return `step ${stepId}: ${isRun ? 'run store' : (info?.name ?? store)} — ${mode}${sensitive ? '  [SENSITIVE]' : ''}`;
+}
 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
@@ -90,12 +144,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;
@@ -138,11 +192,23 @@ async function saveAndPublish(api, file, rows, publish, deps, say) {
         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)
+            if (!added.length)
+                continue;
+            if (c !== 'fileStores') {
                 say(`  ${c}: ${added.join(', ')}`);
+                continue;
+            }
+            const loaded = await loadStores(api);
+            const stores = loaded ?? new Map();
+            const workflowSensitive = [...boundStoreIds(file.definition)].some((id) => stores.get(id)?.sensitive);
+            say(`  ${c}:`);
+            for (const e of added)
+                say(`    ${grantLine(e, stores, workflowSensitive)}`);
+            if (!loaded)
+                say('    (the store list could not be read, so sensitivity is unknown — confirm in the web UI)');
         }
         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.3.0",
   "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",