@amalgm/automations 0.1.0

package/AXIOMS.md

@@ -0,0 +1,32 @@
+# Automations axioms
+
+1. Every automation record and CRUD decision has exactly one owner: this
+   product.
+2. The public control-plane contract is one auth-bound SDK. API, CLI, MCP, and
+   skill adapters translate inputs and call it; none accesses Supabase or owns
+   validation, authorization, or persistence rules.
+3. Every call is scoped by a resolved Amalgm principal. Public inputs never
+   contain a user id or raw credential; session, HMAC-refresh, and future API
+   key authentication all resolve to the same principal shape.
+4. An automation belongs to exactly one user and exactly one target. It may
+   have zero or more triggers and zero or one workflow.
+5. Scheduled triggers and webhook triggers are distinct first-class resources
+   with their own CRUD operations and validation rules.
+6. A workflow is the one script resource owned by its automation. It may be
+   created, read, updated, or deleted independently of the automation and its
+   triggers.
+7. An incomplete automation is valid configuration. Future execution behavior
+   must be derived from its persisted configuration rather than repaired by the
+   CRUD layer.
+8. Supabase is authoritative for automations, triggers, workflow source, and
+   permanent run history. A definition edit or deletion never rewrites prior
+   runs.
+9. Webhook secrets are persisted but write-only: normal reads reveal only that
+   a secret is configured.
+10. Run history is read-only in the control plane and always scoped to its
+    automation's owner.
+11. Storage records, Supabase RPCs, HTTP details, and MCP protocol details are
+    implementation concerns, not SDK concepts.
+12. During cutover, legacy and replacement implementations never write the
+    same authority concurrently. Completed cutover deletes the legacy
+    implementation.

package/PURPOSE.md

@@ -0,0 +1,35 @@
+# Amalgm Automations
+
+## Purpose
+
+Automations is the sole owner of Amalgm automation behavior and data. It lets an
+authenticated user create, inspect, change, and delete automation
+configuration — an automation belongs to one user and one target, may own any
+number of scheduled and webhook triggers, and may own one workflow script — and
+have each trigger occurrence run on the selected existing Amalgm machine.
+Supabase holds everything except execution: the automation, its triggers, the
+complete workflow, and permanent run history.
+
+The product has two composable halves over that one state:
+
+- **The configuration control plane** — one ergonomic, auth-bound SDK contract
+  for automation CRUD and run-history reads. The HTTP API, CLI, MCP server, and
+  skill are adapters over that contract; they do not access Supabase directly
+  or implement lifecycle rules.
+- **The delivery rail** — trigger admission, scheduling, and run state: the
+  receipt-before-auth, lease, retry, and idempotency laws that decide when a
+  run happens. When a machine is offline, new runs remain pending; when it
+  reconnects, every pending run is sent through Amalgm's existing transport and
+  started by the existing host runtime. Execution itself stays on the machine.
+
+Amalgm supplies a resolved authenticated principal from its user session or
+HMAC-refresh flow; future API keys resolve to the same principal capability.
+Core provides authenticated user identity, opaque machine identity,
+connectivity, and narrow host capabilities. The product receives identity and
+scopes — never raw credentials or Core storage — and neither side reaches into
+the other's storage or reimplements the other's decisions.
+
+This extraction is complete only when every Automations surface in Engine calls
+this product service, product state has one writer, migrated behavior has parity
+tests, and the legacy `amalgm-mcp` automation implementation and storage are
+deleted.

package/README.md

@@ -0,0 +1,130 @@
+# @amalgm/automations
+
+The Automations product extracted from `amalgm-mcp`: a Supabase-backed
+configuration control plane plus the delivery rail that decides when runs
+happen. Supabase owns everything except execution.
+
+## SDK contract (configuration control plane)
+
+The public control plane is an auth-bound SDK. API, CLI, MCP, and the
+automation skill adapt this contract; only the service implementation accesses
+Supabase.
+
+```ts
+const sdk = service.for(principal);
+
+await sdk.automations.create({ targetId: 'machine-1', name: 'Daily summary' });
+await sdk.triggers.schedule.create('automation-id', { cron: '0 9 * * 1-5' });
+await sdk.triggers.webhook.create('automation-id', {
+  source: 'github', event: 'push', secret: 'a-secret-at-least-16-characters',
+});
+await sdk.workflow.create('automation-id', {
+  script: 'export default workflow({ cells: [] });',
+});
+const history = await sdk.runs.list('automation-id');
+```
+
+An automation may have any number of scheduled and webhook triggers, and zero
+or one workflow. Every component can be created, read, changed, and deleted
+independently. Webhook secrets are write-only; reads return `secretConfigured`.
+Deleting configuration never deletes run history.
+
+### Composition
+
+```ts
+import {
+  AutomationCrudService,
+  SupabaseAutomationCrudRepository,
+  createAutomationApi,
+} from '@amalgm/automations';
+
+const service = new AutomationCrudService(
+  new SupabaseAutomationCrudRepository(supabaseRpcClient),
+);
+
+const api = createAutomationApi({
+  service,
+  authenticate: resolveAmalgmPrincipal,
+});
+```
+
+`authenticate` resolves the existing Amalgm session or HMAC-refresh credential
+to an `AutomationPrincipal`. Future API keys resolve to that same type. The
+SDK receives a principal with scopes and never raw credentials or a caller-
+supplied user ID.
+
+Use `createAutomationClient` to call the Fetch API from another process. The
+CLI and MCP server use this same client with
+`AMALGM_AUTOMATIONS_API_URL` and `AMALGM_AUTOMATIONS_AUTHORIZATION`.
+
+```sh
+amalgm-automations automations list
+amalgm-automations triggers schedule create automation-id schedule.json
+amalgm-automations triggers webhook create automation-id webhook.json
+amalgm-automations workflow update automation-id workflow.json
+```
+
+The MCP server command is `amalgm-automations-mcp`; it exposes one typed,
+atomic MCP tool for every SDK operation.
+
+## Delivery rail
+
+The Core boundary is deliberately small. Core translates its authenticated
+machine record into an opaque `AutomationTarget`; the product never queries a
+Core table. Core also supplies the existing machine transport:
+
+```ts
+import { Automations, SupabaseStore } from '@amalgm/automations';
+
+const automations = new Automations(new SupabaseStore(getSupabase()), {
+  isOnline: ({ targetId }) => existingTunnel.hasConnection(targetId),
+  send: (run) => existingTunnel.send(run.targetId, run),
+});
+
+await automations.save(authenticatedUser.id, definition);
+
+await automations.receiveEvent({
+  target: await core.resolveEventTarget(eventRef),
+  headers,
+  body,
+  payload,
+});
+
+await automations.targetOnline({ userId, targetId });
+
+await automations.updateRun({ userId, targetId }, runId, {
+  status: 'completed',
+  output,
+});
+
+const history = await automations.listRuns(userId, automationId);
+```
+
+`save`, `receiveEvent`, `fireDueCrons`, `targetOnline`, `updateRun`, and
+`listRuns` own the decisions.
+The surrounding Engine route, MCP tool, scheduler callback, and tunnel callback
+only translate and call them.
+
+Every firing stores an immutable run snapshot in Supabase. Delivery and machine
+execution update that record instead of deleting it. When a machine is offline,
+new runs remain pending; on reconnect every pending run drains through the
+existing transport.
+
+The current implementation covers Supabase definitions, cron and event
+admission, secret verification, permanent run history, and reconnect drain. The
+remaining extraction is the proven workflow definition, validation,
+orchestration, and public surface behavior still owned by `amalgm-mcp`; it must
+move behind this same service boundary before legacy code is removed.
+
+The purpose is in [PURPOSE.md](./PURPOSE.md), and the non-negotiable ownership
+rules are in [AXIOMS.md](./AXIOMS.md).
+
+## Verification
+
+```sh
+npm install
+npm run release:check
+```
+
+`release:check` includes deterministic unit tests and a real Postgres contract.
+Set `TEST_DATABASE_URL` to an empty Postgres 16 database for the latter.

package/dist/src/automations.d.ts

@@ -0,0 +1,27 @@
+import type { AutomationDefinition, AutomationLog, AutomationRun, AutomationStore, AutomationTarget, AutomationTransport, Json, RunUpdate } from './types.js';
+export declare class EventRejectedError extends Error {
+    constructor();
+}
+export declare class Automations {
+    #private;
+    readonly store: AutomationStore;
+    readonly transport: AutomationTransport;
+    readonly log: AutomationLog;
+    constructor(store: AutomationStore, transport: AutomationTransport, log?: AutomationLog);
+    save(userId: string, definition: AutomationDefinition, now?: Date): Promise<void>;
+    delete(userId: string, automationId: string): Promise<boolean>;
+    listRuns(userId: string, automationId?: string): Promise<AutomationRun[]>;
+    receiveEvent(input: {
+        target: AutomationTarget;
+        headers: Record<string, string>;
+        body: Buffer;
+        payload: Json;
+        source?: string;
+        event?: string;
+        now?: Date;
+    }): Promise<AutomationRun[]>;
+    fireDueCrons(now?: Date): Promise<AutomationRun[]>;
+    targetOnline(target: AutomationTarget): Promise<number>;
+    updateRun(target: AutomationTarget, runId: string, update: RunUpdate): Promise<AutomationRun | null>;
+    drain(target: AutomationTarget): Promise<number>;
+}

package/dist/src/automations.js

@@ -0,0 +1,199 @@
+import { nextCronAt, validateCron } from './schedule.js';
+import { eventReferences, matchesEvent, verifyEventSecret } from './webhook.js';
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+const noop = () => { };
+export class EventRejectedError extends Error {
+    constructor() {
+        super('Event was not authenticated');
+        this.name = 'EventRejectedError';
+    }
+}
+export class Automations {
+    store;
+    transport;
+    log;
+    #drains = new Map();
+    constructor(store, transport, log = noop) {
+        this.store = store;
+        this.transport = transport;
+        this.log = log;
+    }
+    async save(userId, definition, now = new Date()) {
+        const automation = prepareAutomation(userId, definition, now);
+        await this.store.saveAutomation(automation);
+    }
+    delete(userId, automationId) {
+        return this.store.deleteAutomation(userId, automationId);
+    }
+    listRuns(userId, automationId) {
+        return this.store.listRuns(userId, automationId);
+    }
+    async receiveEvent(input) {
+        assertJson(input.payload, 'Event payload');
+        const candidates = await this.store.eventTriggers(input.target);
+        const authenticated = candidates.filter((trigger) => (verifyEventSecret(trigger.secret, input.headers, input.body)));
+        if (authenticated.length === 0) {
+            this.log('event.rejected', { targetId: input.target.targetId });
+            throw new EventRejectedError();
+        }
+        const references = input.source && input.event
+            ? { primary: { source: input.source, event: input.event } }
+            : eventReferences(input.headers, input.payload);
+        let reference = references.primary;
+        let triggers = authenticated.filter((trigger) => matchesEvent(trigger, reference.source, reference.event));
+        if (triggers.length === 0 && references.fallback) {
+            reference = references.fallback;
+            triggers = authenticated.filter((trigger) => matchesEvent(trigger, reference.source, reference.event));
+        }
+        if (triggers.length === 0)
+            return [];
+        const now = input.now || new Date();
+        const runInput = { kind: 'event', ...reference, payload: input.payload };
+        const runs = (await Promise.all(triggers.map((trigger) => (this.store.enqueueEvent(trigger, runInput, now))))).filter((run) => run !== null);
+        await this.#drainCreated(runs);
+        return runs;
+    }
+    async fireDueCrons(now = new Date()) {
+        const created = [];
+        for (const trigger of await this.store.dueCronTriggers(now)) {
+            let scheduledFor = trigger.nextRunAt;
+            while (new Date(scheduledFor) <= now) {
+                const nextRunAt = nextCronAt(trigger.cron, trigger.timezone, scheduledFor);
+                const run = await this.store.enqueueCron({ ...trigger, nextRunAt: scheduledFor }, nextRunAt, now);
+                if (!run)
+                    break;
+                created.push(run);
+                scheduledFor = nextRunAt;
+            }
+        }
+        await this.#drainCreated(created);
+        return created;
+    }
+    targetOnline(target) {
+        return this.drain(target);
+    }
+    updateRun(target, runId, update) {
+        if (update.output !== undefined)
+            assertJson(update.output, 'Run output');
+        return this.store.updateRun(target, runId, update);
+    }
+    drain(target) {
+        const key = `${target.userId}:${target.targetId}`;
+        const active = this.#drains.get(key);
+        if (active)
+            return active;
+        const drain = this.#drain(target).finally(() => {
+            if (this.#drains.get(key) === drain)
+                this.#drains.delete(key);
+        });
+        this.#drains.set(key, drain);
+        return drain;
+    }
+    async #drainCreated(runs) {
+        for (const run of runs) {
+            this.log('run.pending', {
+                runId: run.id,
+                targetId: run.targetId,
+                automationId: run.automationId,
+            });
+        }
+        const targets = new Map(runs.map((run) => [
+            `${run.userId}:${run.targetId}`,
+            { userId: run.userId, targetId: run.targetId },
+        ]));
+        await Promise.all([...targets.values()].map((target) => this.drain(target)));
+    }
+    async #drain(target) {
+        if (!this.transport.isOnline(target))
+            return 0;
+        this.log('drain.started', { targetId: target.targetId });
+        let sent = 0;
+        const failed = new Set();
+        while (this.transport.isOnline(target)) {
+            const runs = (await this.store.pendingRuns(target)).filter(({ id }) => !failed.has(id));
+            if (runs.length === 0)
+                return sent;
+            for (const run of runs) {
+                if (!this.transport.isOnline(target))
+                    return sent;
+                try {
+                    if (!await this.transport.send(run)) {
+                        this.log('run.failed', { runId: run.id, targetId: target.targetId });
+                        failed.add(run.id);
+                        continue;
+                    }
+                    if (await this.store.markSent(run.id, target, new Date()))
+                        sent += 1;
+                    this.log('run.sent', { runId: run.id, targetId: target.targetId });
+                }
+                catch {
+                    this.log('run.failed', { runId: run.id, targetId: target.targetId });
+                    failed.add(run.id);
+                }
+            }
+        }
+        return sent;
+    }
+}
+function prepareAutomation(userId, definition, now) {
+    if (!ID.test(definition.id))
+        throw new Error('Automation id is invalid');
+    if (!userId)
+        throw new Error('Automation userId is required');
+    if (!definition.targetId)
+        throw new Error('Automation targetId is required');
+    if (!ID.test(definition.trigger.id))
+        throw new Error('Trigger id is invalid');
+    if (!ID.test(definition.workflow.id))
+        throw new Error('Workflow id is invalid');
+    if (!definition.workflow.script.trim())
+        throw new Error('Workflow script is required');
+    if (definition.workflow.compiled !== undefined) {
+        assertJson(definition.workflow.compiled, 'Compiled workflow');
+    }
+    if (definition.workflow.allowlist !== undefined) {
+        assertJson(definition.workflow.allowlist, 'Workflow allowlist');
+    }
+    if (definition.workflow.limits !== undefined) {
+        assertJson(definition.workflow.limits, 'Workflow limits');
+    }
+    const trigger = definition.trigger.kind === 'event'
+        ? prepareEventTrigger(definition.trigger)
+        : prepareCronTrigger(definition.trigger, now);
+    return { ...definition, userId, enabled: definition.enabled !== false, trigger };
+}
+function prepareEventTrigger(trigger) {
+    if (trigger.secret.length < 16)
+        throw new Error(`Event trigger ${trigger.id} secret is too short`);
+    return {
+        ...trigger,
+        enabled: trigger.enabled !== false,
+        source: trigger.source || '*',
+        event: trigger.event || '*',
+    };
+}
+function prepareCronTrigger(trigger, now) {
+    const timezone = trigger.timezone || 'UTC';
+    validateCron(trigger.cron, timezone);
+    return {
+        ...trigger,
+        enabled: trigger.enabled !== false,
+        timezone,
+        nextRunAt: nextCronAt(trigger.cron, timezone, now),
+    };
+}
+function assertJson(value, label) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item) => assertJson(item, label));
+        return;
+    }
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        Object.values(value).forEach((item) => assertJson(item, label));
+        return;
+    }
+    throw new Error(`${label} must be JSON`);
+}

package/dist/src/cli-main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli-main.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createAutomationClient } from './client.js';
+import { automationCliHelp, runAutomationCli } from './cli.js';
+const baseUrl = process.env.AMALGM_AUTOMATIONS_API_URL;
+const authorization = process.env.AMALGM_AUTOMATIONS_AUTHORIZATION;
+const argv = process.argv.slice(2);
+const help = argv.length === 0 || argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h';
+if (help) {
+    process.stdout.write(automationCliHelp);
+}
+else if (!baseUrl || !authorization) {
+    process.stderr.write('AMALGM_AUTOMATIONS_API_URL and AMALGM_AUTOMATIONS_AUTHORIZATION are required.\n');
+    process.exitCode = 1;
+}
+else {
+    const code = await runAutomationCli(argv, createAutomationClient({
+        baseUrl,
+        authorization: () => authorization,
+    }));
+    process.exitCode = code;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,10 @@
+import type { AutomationCrud } from './contract.js';
+interface Output {
+    write(chunk: string): unknown;
+}
+export declare const automationCliHelp = "Usage: amalgm-automations <resource> <action>\n\nautomations  create|list|get|update|delete\ntriggers     list | schedule <create|list|get|update|delete> | webhook <create|list|get|update|delete>\nworkflow     create|get|update|delete\nruns         list|get\n\nList filters:\n  automations list [--target-id ID] [--enabled true|false] [--limit N] [--offset N]\n  triggers schedule|webhook list AUTOMATION_ID [--limit N] [--offset N]\n  runs list AUTOMATION_ID [--status STATUS] [--limit N] [--offset N]\n";
+export declare function runAutomationCli(argv: string[], sdk: AutomationCrud, output?: {
+    stdout?: Output;
+    stderr?: Output;
+}): Promise<number>;
+export {};

package/dist/src/cli.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs/promises';
+export const automationCliHelp = `Usage: amalgm-automations <resource> <action>
+
+automations  create|list|get|update|delete
+triggers     list | schedule <create|list|get|update|delete> | webhook <create|list|get|update|delete>
+workflow     create|get|update|delete
+runs         list|get
+
+List filters:
+  automations list [--target-id ID] [--enabled true|false] [--limit N] [--offset N]
+  triggers schedule|webhook list AUTOMATION_ID [--limit N] [--offset N]
+  runs list AUTOMATION_ID [--status STATUS] [--limit N] [--offset N]
+`;
+export async function runAutomationCli(argv, sdk, output = {}) {
+    const stdout = output.stdout || process.stdout;
+    const stderr = output.stderr || process.stderr;
+    try {
+        const [resource, action, ...rest] = argv;
+        if (!resource || resource === 'help' || resource === '--help' || resource === '-h') {
+            stdout.write(automationCliHelp);
+            return 0;
+        }
+        const result = await command(resource, action, rest, sdk);
+        stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+async function command(resource, action, args, sdk) {
+    if (resource === 'automations')
+        return automationCommand(action, args, sdk);
+    if (resource === 'triggers')
+        return triggerCommand(action, args, sdk);
+    if (resource === 'workflow')
+        return workflowCommand(action, args, sdk);
+    if (resource === 'runs')
+        return runsCommand(action, args, sdk);
+    throw new Error(`Unknown resource: ${resource}`);
+}
+async function automationCommand(action, args, sdk) {
+    if (action === 'create')
+        return sdk.automations.create(await jsonFile(required(args, 0, 'automation JSON file')));
+    if (action === 'list')
+        return sdk.automations.list(automationListOptions(args));
+    if (action === 'get')
+        return sdk.automations.get(required(args, 0, 'automation id'));
+    if (action === 'update')
+        return sdk.automations.update(required(args, 0, 'automation id'), await jsonFile(required(args, 1, 'automation patch JSON file')));
+    if (action === 'delete') {
+        const automationId = required(args, 0, 'automation id');
+        await sdk.automations.delete(automationId);
+        return { deleted: automationId };
+    }
+    throw new Error('Usage: automations <create|list|get|update|delete>');
+}
+async function triggerCommand(action, args, sdk) {
+    if (action === 'list')
+        return sdk.triggers.list(required(args, 0, 'automation id'));
+    const [operation, automationId, ...rest] = args;
+    const automation = requiredValue(automationId, 'automation id');
+    if (action === 'schedule') {
+        if (operation === 'create')
+            return sdk.triggers.schedule.create(automation, await jsonFile(required(rest, 0, 'schedule JSON file')));
+        if (operation === 'list')
+            return sdk.triggers.schedule.list(automation, pageOptions(rest));
+        if (operation === 'get')
+            return sdk.triggers.schedule.get(automation, required(rest, 0, 'schedule trigger id'));
+        if (operation === 'update')
+            return sdk.triggers.schedule.update(automation, required(rest, 0, 'schedule trigger id'), await jsonFile(required(rest, 1, 'schedule patch JSON file')));
+        if (operation === 'delete') {
+            const id = required(rest, 0, 'schedule trigger id');
+            await sdk.triggers.schedule.delete(automation, id);
+            return { deleted: id };
+        }
+    }
+    if (action === 'webhook') {
+        if (operation === 'create')
+            return sdk.triggers.webhook.create(automation, await jsonFile(required(rest, 0, 'webhook JSON file')));
+        if (operation === 'list')
+            return sdk.triggers.webhook.list(automation, pageOptions(rest));
+        if (operation === 'get')
+            return sdk.triggers.webhook.get(automation, required(rest, 0, 'webhook trigger id'));
+        if (operation === 'update')
+            return sdk.triggers.webhook.update(automation, required(rest, 0, 'webhook trigger id'), await jsonFile(required(rest, 1, 'webhook patch JSON file')));
+        if (operation === 'delete') {
+            const id = required(rest, 0, 'webhook trigger id');
+            await sdk.triggers.webhook.delete(automation, id);
+            return { deleted: id };
+        }
+    }
+    throw new Error('Usage: triggers <list|schedule|webhook>');
+}
+async function workflowCommand(action, args, sdk) {
+    const automationId = required(args, 0, 'automation id');
+    if (action === 'create')
+        return sdk.workflow.create(automationId, await jsonFile(required(args, 1, 'workflow JSON file')));
+    if (action === 'get')
+        return sdk.workflow.get(automationId);
+    if (action === 'update')
+        return sdk.workflow.update(automationId, await jsonFile(required(args, 1, 'workflow patch JSON file')));
+    if (action === 'delete') {
+        await sdk.workflow.delete(automationId);
+        return { deleted: automationId };
+    }
+    throw new Error('Usage: workflow <create|get|update|delete>');
+}
+async function runsCommand(action, args, sdk) {
+    const automationId = required(args, 0, 'automation id');
+    if (action === 'list')
+        return sdk.runs.list(automationId, runListOptions(args.slice(1)));
+    if (action === 'get')
+        return sdk.runs.get(automationId, required(args, 1, 'run id'));
+    throw new Error('Usage: runs <list|get>');
+}
+function automationListOptions(args) {
+    const options = readOptions(args, new Set(['--target-id', '--enabled', '--limit', '--offset']));
+    return {
+        ...pageOptionsFrom(options),
+        ...(options['--target-id'] ? { targetId: options['--target-id'] } : {}),
+        ...(options['--enabled'] === undefined ? {} : { enabled: booleanOption(options['--enabled'], '--enabled') }),
+    };
+}
+function runListOptions(args) {
+    const options = readOptions(args, new Set(['--status', '--limit', '--offset']));
+    return {
+        ...pageOptionsFrom(options),
+        ...(options['--status'] ? { status: options['--status'] } : {}),
+    };
+}
+function pageOptions(args) {
+    return pageOptionsFrom(readOptions(args, new Set(['--limit', '--offset'])));
+}
+function pageOptionsFrom(options) {
+    return {
+        ...(options['--limit'] === undefined ? {} : { limit: numberOption(options['--limit'], '--limit') }),
+        ...(options['--offset'] === undefined ? {} : { offset: numberOption(options['--offset'], '--offset') }),
+    };
+}
+function readOptions(args, allowed) {
+    const result = {};
+    for (let index = 0; index < args.length; index += 2) {
+        const flag = args[index];
+        const value = args[index + 1];
+        if (!flag || !allowed.has(flag) || value === undefined)
+            throw new Error(`Unknown or incomplete list option: ${flag || ''}`);
+        if (result[flag] !== undefined)
+            throw new Error(`List option may be provided once: ${flag}`);
+        result[flag] = value;
+    }
+    return result;
+}
+function numberOption(value, name) {
+    const number = Number(value);
+    if (!Number.isInteger(number))
+        throw new Error(`${name} must be an integer`);
+    return number;
+}
+function booleanOption(value, name) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    throw new Error(`${name} must be true or false`);
+}
+async function jsonFile(filename) {
+    try {
+        return JSON.parse(await fs.readFile(filename, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Cannot read JSON file ${filename}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function required(values, index, label) {
+    return requiredValue(values[index], label);
+}
+function requiredValue(value, label) {
+    if (!value)
+        throw new Error(`${label} is required`);
+    return value;
+}

package/dist/src/client.d.ts

@@ -0,0 +1,7 @@
+import type { AutomationCrud } from './contract.js';
+export type AutomationAuthorization = () => string | undefined | Promise<string | undefined>;
+export declare function createAutomationClient(options: {
+    baseUrl: string;
+    authorization: AutomationAuthorization;
+    fetch?: typeof globalThis.fetch;
+}): AutomationCrud;