@offsida/cli 0.3.0 → 0.4.0

package/dist/bundle.d.ts

@@ -1,4 +1,5 @@
 import type { ArtifactFile } from './resolve-package.js';
+export declare function ensureInit(): Promise<void>;
 export declare function bundlePackage(dir: string, opts?: {
     alias?: Record<string, string>;
 }): Promise<string>;

package/dist/bundle.js

@@ -1,7 +1,7 @@
 import * as esbuild from 'esbuild-wasm';
 import { join, relative, resolve, sep } from 'node:path';
 let initialized = false;
-async function ensureInit() {
+export async function ensureInit() {
     if (initialized)
         return;
     await esbuild.initialize({});

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-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.";
+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 \u2014 and every\n*.workflow.ts, compiled \u2014 as that workflow's draft, replacing edits made in the Offsida\neditor. 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\nA *.workflow.ts default-exports defineWorkflow(\u2026) from @offsida/sdk/workflow. It is\nbundled and run in Node at push (author code, like any build script); an import of a\n*.action.ts becomes that action's name, so the action's own code never runs.\n\nbuild bundles every artifact and compiles every *.workflow.ts without uploading: with\n--out-dir it writes <name>.js per artifact and <file>.json per typed workflow; without,\nit prints each artifact's size against the cap and each typed workflow's name.\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,8 +1,9 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { compileWorkflowFiles } from './compile-workflow.js';
 import { prepareArtifacts } from './prepare.js';
 import { CODE_SIZE_LIMIT } from './push.js';
 import { pushDirectory } from './push-directory.js';
@@ -22,15 +23,21 @@ Names are per org: two packages pushing the same name overwrite each other's art
 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
+package's connection gets the one just pushed), then every *.workflow.json — and every
+*.workflow.ts, compiled — 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 *.workflow.ts default-exports defineWorkflow(…) from @offsida/sdk/workflow. It is
+bundled and run in Node at push (author code, like any build script); an import of a
+*.action.ts becomes that action's name, so the action's own code never runs.
+
+build bundles every artifact and compiles every *.workflow.ts without uploading: with
+--out-dir it writes <name>.js per artifact and <file>.json per typed workflow; without,
+it prints each artifact's size against the cap and each typed workflow's name.
 
 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
@@ -109,9 +116,11 @@ export async function run(argv, env, deps = {}) {
             const pkg = await resolvePackage(dir);
             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`);
+            if (pkg.artifacts.length === 0 && pkg.workflowTsFiles.length === 0) {
+                throw new Error(`${dir}: no *.action.ts, *.package.ts or *.workflow.ts files to build`);
+            }
             const artifacts = await prepareArtifacts(pkg);
+            const workflows = await compileWorkflowFiles(pkg);
             const outDir = flags.get('--out-dir');
             if (typeof outDir === 'string') {
                 await mkdir(outDir, { recursive: true });
@@ -120,9 +129,19 @@ export async function run(argv, env, deps = {}) {
                     await writeFile(file, a.code);
                     out(`wrote ${file}`);
                 }
+                for (const w of workflows) {
+                    const file = join(outDir, `${basename(w.path, '.ts')}.json`);
+                    const { path: _path, ...json } = w;
+                    await writeFile(file, `${JSON.stringify(json, null, 2)}\n`);
+                    out(`wrote ${file}`);
+                }
             }
             else {
+                for (const w of workflows)
+                    out(`workflow "${w.name}"  ${relative(pkg.dir, w.path)}`);
                 const rows = artifacts.map((a) => [a.name, relative(pkg.dir, a.file), a.code.length]);
+                if (rows.length === 0)
+                    return 0;
                 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) {

package/dist/compile-workflow.d.ts

@@ -0,0 +1,11 @@
+import { type ResolvedPackage } from './resolve-package.js';
+import { type WorkflowFile } from './workflow-file.js';
+/**
+ * Compile one `*.workflow.ts`: bundle it for Node (packages stay external, so `@offsida/sdk` resolves from
+ * the package's own install), import it, and call its default export's `compile()`. The bundle is written
+ * under the package's `node_modules/.cache/offsida/` so bare imports resolve, and removed afterwards.
+ * Running the file is running author code — the same trust as any build script.
+ */
+export declare function compileWorkflowFile(pkg: ResolvedPackage, file: string): Promise<WorkflowFile>;
+/** Compile every `*.workflow.ts` in the package, reporting every failure in one error. */
+export declare function compileWorkflowFiles(pkg: ResolvedPackage): Promise<WorkflowFile[]>;

package/dist/compile-workflow.js

@@ -0,0 +1,122 @@
+import * as esbuild from 'esbuild-wasm';
+import { realpathSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ensureInit } from './bundle.js';
+import { ACTION_NAME } from './resolve-package.js';
+import { parseWorkflowFile } from './workflow-file.js';
+const ACTION_SUFFIX = '.action.ts';
+/**
+ * The plugin that makes a typed workflow cheap to compile: an import of a `*.action.ts` becomes a marker
+ * carrying the action's name (its file name), which `step.action` reads. TypeScript still checks the
+ * workflow against the real action; the compiled workflow never loads the action's code or dependencies.
+ */
+function actionMarkers(pkg) {
+    // esbuild reports real paths, so compare real paths (a temp dir or a checkout may sit behind a symlink).
+    const real = (p) => realpathSync(p);
+    const root = real(pkg.dir);
+    const actions = new Set(pkg.artifacts.filter((a) => a.kind === 'action').map((a) => real(a.file)));
+    return {
+        name: 'offsida-action-markers',
+        setup(build) {
+            build.onResolve({ filter: /\.action(\.ts)?$/ }, async (args) => {
+                if (args.pluginData === 'offsida-resolving')
+                    return undefined;
+                const r = await build.resolve(args.path, { resolveDir: args.resolveDir, kind: args.kind, pluginData: 'offsida-resolving' });
+                if (r.errors.length > 0 || !r.path.endsWith(ACTION_SUFFIX))
+                    return undefined;
+                return { path: r.path, namespace: 'offsida-action' };
+            });
+            build.onLoad({ filter: /.*/, namespace: 'offsida-action' }, (args) => {
+                const rel = relative(root, args.path);
+                const name = basename(args.path).slice(0, -ACTION_SUFFIX.length);
+                if (!actions.has(args.path)) {
+                    return { errors: [{ text: `${rel} is not an action of this package — a workflow can only call actions pushed with it` }] };
+                }
+                if (!ACTION_NAME.test(name))
+                    return { errors: [{ text: `${rel}: an action file name must be kebab-case` }] };
+                return { contents: `export default { [Symbol.for('offsida.action')]: { name: ${JSON.stringify(name)} } };`, loader: 'js' };
+            });
+        },
+    };
+}
+function buildMessage(e) {
+    const errors = e.errors;
+    if (!errors?.length)
+        return e.message;
+    return errors.map((x) => (x.location ? `${x.text} (${x.location.file}:${x.location.line})` : x.text)).join('; ');
+}
+/**
+ * Compile one `*.workflow.ts`: bundle it for Node (packages stay external, so `@offsida/sdk` resolves from
+ * the package's own install), import it, and call its default export's `compile()`. The bundle is written
+ * under the package's `node_modules/.cache/offsida/` so bare imports resolve, and removed afterwards.
+ * Running the file is running author code — the same trust as any build script.
+ */
+export async function compileWorkflowFile(pkg, file) {
+    const rel = relative(pkg.dir, file);
+    await ensureInit();
+    let code;
+    try {
+        const result = await esbuild.build({
+            entryPoints: [file],
+            bundle: true,
+            format: 'esm',
+            platform: 'node',
+            target: 'node20',
+            packages: 'external',
+            absWorkingDir: pkg.dir,
+            write: false,
+            logLevel: 'silent',
+            plugins: [actionMarkers(pkg)],
+        });
+        code = result.outputFiles[0].text;
+    }
+    catch (e) {
+        throw new Error(`${rel}: ${buildMessage(e)}`);
+    }
+    const cacheDir = join(pkg.dir, 'node_modules', '.cache', 'offsida');
+    await mkdir(cacheDir, { recursive: true });
+    const out = join(cacheDir, `${basename(file, '.ts')}-${process.pid}-${Date.now()}.mjs`);
+    await writeFile(out, code);
+    try {
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(out).href));
+        }
+        catch (e) {
+            throw new Error(`${rel}: ${e.message}`);
+        }
+        const workflow = mod.default;
+        if (!workflow || typeof workflow.compile !== 'function') {
+            throw new Error(`${rel}: must default-export defineWorkflow({ … }) from @offsida/sdk/workflow`);
+        }
+        let compiled;
+        try {
+            compiled = workflow.compile();
+        }
+        catch (e) {
+            throw new Error(`${rel}: ${e.message}`);
+        }
+        return parseWorkflowFile(file, compiled);
+    }
+    finally {
+        await rm(out, { force: true });
+    }
+}
+/** Compile every `*.workflow.ts` in the package, reporting every failure in one error. */
+export async function compileWorkflowFiles(pkg) {
+    const out = [];
+    const problems = [];
+    for (const file of pkg.workflowTsFiles) {
+        try {
+            out.push(await compileWorkflowFile(pkg, file));
+        }
+        catch (e) {
+            problems.push(e.message);
+        }
+    }
+    if (problems.length > 0)
+        throw new Error(problems.join('\n'));
+    return out;
+}

package/dist/push-directory.d.ts

@@ -11,7 +11,7 @@ export type PushDirectoryDeps = {
 };
 /**
  * `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
+ * and compiled *.workflow.ts 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,5 +1,6 @@
 import { relative } from 'node:path';
 import { connect } from './api.js';
+import { compileWorkflowFiles } from './compile-workflow.js';
 import { prepareArtifacts } from './prepare.js';
 import { pushCode } from './push.js';
 import { resolvePackage } from './resolve-package.js';
@@ -14,7 +15,7 @@ const SUMMARY = [
 ];
 /**
  * `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
+ * and compiled *.workflow.ts 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.
  */
@@ -32,12 +33,13 @@ export async function pushDirectory(opts, deps = {}) {
     const files = [];
     for (const path of pkg.workflowFiles)
         files.push(await readWorkflowFile(path));
+    files.push(...(await compileWorkflowFiles(pkg)));
     assertNoDuplicates(files);
     for (const f of files)
         if (f.id !== undefined)
             workflowDeps.pinned.add(f.id);
     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`);
+        throw new Error(`${opts.dir}: nothing to push — no *.action.ts, *.package.ts, *.workflow.json or *.workflow.ts files`);
     }
     const artifacts = await prepareArtifacts(pkg);
     const api = await connect(opts, deps.fetch, workflowDeps.sleep);

package/dist/resolve-package.d.ts

@@ -9,12 +9,14 @@ export type ResolvedPackage = {
     dir: string;
     artifacts: ArtifactFile[];
     workflowFiles: string[];
+    workflowTsFiles: string[];
     warnings: string[];
 };
+export declare const ACTION_NAME: RegExp;
 /**
  * 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,
+ * package's connection) then by name. Workflows: every *.workflow.json and *.workflow.ts 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

@@ -4,7 +4,7 @@ import { join, relative, resolve } from 'node:path';
 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}$/;
+export const ACTION_NAME = /^[a-z][a-z0-9-]{0,63}$/;
 const SUFFIXES = [
     ['.action.ts', 'action'],
     ['.package.ts', 'package'],
@@ -31,6 +31,8 @@ async function walk(dir, out) {
         else if (e.isFile()) {
             if (e.name.endsWith('.workflow.json'))
                 out.workflowFiles.push(path);
+            if (e.name.endsWith('.workflow.ts'))
+                out.workflowTsFiles.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 });
@@ -49,7 +51,7 @@ const byKindThenName = (a, b) => (a.kind === b.kind ? 0 : a.kind === 'package' ?
 /**
  * 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,
+ * package's connection) then by name. Workflows: every *.workflow.json and *.workflow.ts below. Both skip node_modules,
  * dist, dot-dirs and nested packages. Every naming problem is reported in one error.
  */
 export async function resolvePackage(dirArg) {
@@ -73,7 +75,7 @@ export async function resolvePackage(dirArg) {
     if (pkg.offsida?.name !== undefined) {
         warnings.push('package.json: "offsida.name" is ignored — artifacts are named after their *.action.ts / *.package.ts files');
     }
-    const found = { artifacts: [], workflowFiles: [] };
+    const found = { artifacts: [], workflowFiles: [], workflowTsFiles: [] };
     await walk(dir, found);
     const artifacts = found.artifacts.sort(byKindThenName);
     const problems = [];
@@ -94,5 +96,5 @@ export async function resolvePackage(dirArg) {
     }
     if (problems.length > 0)
         throw new Error(problems.join('\n'));
-    return { dir, artifacts, workflowFiles: found.workflowFiles.sort(), warnings };
+    return { dir, artifacts, workflowFiles: found.workflowFiles.sort(), workflowTsFiles: found.workflowTsFiles.sort(), warnings };
 }

package/dist/workflow-file.d.ts

@@ -1,4 +1,4 @@
-/** A `*.workflow.json` file. `id` pins one workflow in one org; only `name` + `definition` are sent. */
+/** A `*.workflow.json` file, or a compiled `*.workflow.ts`. `id` pins one workflow in one org; only `name` + `definition` are sent. */
 export type WorkflowFile = {
     path: string;
     id?: string;
@@ -6,4 +6,6 @@ export type WorkflowFile = {
     definition: Record<string, unknown>;
 };
 export declare function readWorkflowFile(path: string): Promise<WorkflowFile>;
+/** The shape checks, on an already-parsed value — shared by `*.workflow.json` and compiled `*.workflow.ts`. */
+export declare function parseWorkflowFile(path: string, v: unknown): WorkflowFile;
 export declare function assertNoDuplicates(files: WorkflowFile[]): void;

package/dist/workflow-file.js

@@ -17,6 +17,10 @@ export async function readWorkflowFile(path) {
     catch {
         throw new Error(`${path}: not valid JSON`);
     }
+    return parseWorkflowFile(path, v);
+}
+/** The shape checks, on an already-parsed value — shared by `*.workflow.json` and compiled `*.workflow.ts`. */
+export function parseWorkflowFile(path, v) {
     if (!isObject(v))
         throw new Error(`${path}: expected a JSON object`);
     if (typeof v.name !== 'string' || !v.name.trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offsida/cli",
-  "version": "0.3.0",
+  "version": "0.4.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.2.0"
+    "@offsida/types": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",