@sensigo/realm-cli 0.1.0

package/dist/commands/watch.js

@@ -0,0 +1,112 @@
+// realm workflow watch <path> — watches a workflow YAML and re-registers on change.
+import { watch, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { Command } from 'commander';
+import { loadWorkflowFromFile, WorkflowError } from '@sensigo/realm';
+/**
+ * Attempts to load and register a workflow YAML file.
+ * Logs the result (success or validation error) to stdout/stderr.
+ * @param filePath Path to the workflow YAML file.
+ * @param store    The registrar to register into.
+ */
+async function registerFile(filePath, store) {
+    const timestamp = new Date().toISOString();
+    try {
+        const definition = loadWorkflowFromFile(filePath);
+        await store.register(definition);
+        console.log(`[${timestamp}] Registered: ${definition.id} v${definition.version} (${Object.keys(definition.steps).length} steps)`);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError) {
+            console.error(`[${timestamp}] Invalid: ${err.message}`);
+        }
+        else {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[${timestamp}] Error: ${message}`);
+        }
+    }
+}
+/**
+ * Watches a workflow YAML file and re-registers it into the given store on every change.
+ * Also watches the profiles directory alongside the YAML — any file change there triggers
+ * re-registration. If the profiles directory does not exist, only the YAML is watched.
+ * Performs an initial registration before entering the watch loop.
+ * Resolves when the watcher is closed (e.g. when the AbortSignal fires).
+ *
+ * @param filePath    Path to the workflow YAML file.
+ * @param store       The workflow registrar to register into — injected, never instantiated here.
+ * @param signal      Optional AbortSignal; when aborted the watcher stops and the promise resolves.
+ * @param profilesDir Optional override for the profiles directory path. Defaults to
+ *                    `<workflow-dir>/profiles` (or `profiles_dir` declared in the YAML).
+ */
+export async function watchWorkflow(filePath, store, signal, profilesDir) {
+    await registerFile(filePath, store);
+    // Derive the profiles directory: caller override → YAML profiles_dir → default.
+    let resolvedProfilesDir = profilesDir;
+    if (resolvedProfilesDir === undefined) {
+        const workflowDir = dirname(resolve(filePath));
+        try {
+            const definition = loadWorkflowFromFile(filePath);
+            resolvedProfilesDir =
+                definition.profiles_dir !== undefined
+                    ? resolve(workflowDir, definition.profiles_dir)
+                    : join(workflowDir, 'profiles');
+        }
+        catch {
+            // If the YAML is invalid on startup we still run the YAML watcher.
+            resolvedProfilesDir = join(workflowDir, 'profiles');
+        }
+    }
+    const watchYaml = new Promise((resolve, reject) => {
+        const watcher = watch(filePath, { persistent: false, signal });
+        watcher.on('change', (eventType) => {
+            if (eventType === 'change') {
+                void registerFile(filePath, store);
+            }
+        });
+        watcher.on('error', (err) => {
+            reject(err);
+        });
+        watcher.on('close', () => {
+            resolve();
+        });
+    });
+    // Only watch the profiles directory if it exists.
+    if (!existsSync(resolvedProfilesDir)) {
+        return watchYaml;
+    }
+    const profilesDirPath = resolvedProfilesDir;
+    const watchProfiles = new Promise((resolve, reject) => {
+        const watcher = watch(profilesDirPath, { persistent: false, signal });
+        watcher.on('change', () => {
+            void registerFile(filePath, store);
+        });
+        watcher.on('error', (err) => {
+            reject(err);
+        });
+        watcher.on('close', () => {
+            resolve();
+        });
+    });
+    await Promise.all([watchYaml, watchProfiles]);
+}
+export const watchCommand = new Command('watch')
+    .argument('<path>', 'Path to workflow directory or workflow.yaml file')
+    .description('Watch a workflow YAML file and re-register it on every change')
+    .action(async (inputPath) => {
+    const filePath = inputPath.endsWith('.yaml') || inputPath.endsWith('.yml')
+        ? inputPath
+        : join(inputPath, 'workflow.yaml');
+    const { JsonWorkflowStore } = await import('@sensigo/realm');
+    const store = new JsonWorkflowStore();
+    console.log(`Watching ${filePath} — press Ctrl+C to stop`);
+    try {
+        await watchWorkflow(filePath, store);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=watch.js.map

package/dist/commands/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/commands/watch.ts"],"names":[],"mappings":"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"}

package/dist/commands/webhook.d.ts

@@ -0,0 +1,51 @@
+import { type Server } from 'node:http';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { Command } from 'commander';
+import type { WorkflowDefinition, WorkflowRegistrar, RunStore } from '@sensigo/realm';
+/**
+ * Checks a GitHub webhook HMAC-SHA256 signature using timing-safe comparison.
+ * Returns true only if the header is present, uses the sha256= prefix, and
+ * the HMAC matches byte-for-byte. Pads both buffers to equal length before
+ * comparison to avoid length-based timing leaks.
+ */
+export declare function checkWebhookSignature(rawBody: Buffer, signatureHeader: string | undefined, secret: string): boolean;
+/**
+ * Checks whether a delivery ID is a duplicate within the TTL window.
+ * Evicts stale entries and enforces a capacity cap on each call.
+ * Returns true if the delivery was already seen; records it and returns false otherwise.
+ */
+export declare function isDuplicate(deliveryCache: Map<string, number>, deliveryId: string): boolean;
+/** An event:action pair used to filter incoming webhook deliveries. */
+export interface EventFilter {
+    event: string;
+    action: string;
+}
+/** Options for startWebhookServer — all I/O dependencies are injectable for testing. */
+export interface StartWebhookServerOptions {
+    port: number;
+    secret: string;
+    definition: WorkflowDefinition;
+    events: EventFilter[];
+    provider?: string;
+    model?: string;
+    /** Custom run store — avoids writing to disk in tests. */
+    runStore?: RunStore;
+    /** Custom workflow registrar — avoids writing to disk in tests. */
+    workflowStore?: WorkflowRegistrar;
+    /** Override spawn — injectable for test isolation. */
+    spawnFn?: typeof nodeSpawn;
+}
+/**
+ * Creates and starts the webhook HTTP server. Resolves once the server is listening.
+ * The caller is responsible for calling server.close() when done.
+ *
+ * Security-first request handling order:
+ * 1. Buffer body  2. Verify HMAC  3. Filter event/action  4. Dedup  5. Create run  6. Spawn agent
+ */
+export declare function startWebhookServer(options: StartWebhookServerOptions): Promise<Server>;
+/**
+ * `realm webhook` — starts an HTTP server that creates runs from GitHub webhook deliveries.
+ * Verifies HMAC-SHA256 signatures, deduplicates deliveries, and spawns realm agent children.
+ */
+export declare const webhookCommand: Command;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/commands/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/commands/webhook.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAKtF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,GACb,OAAO,CAcT;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAgB3F;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mEAAmE;IACnE,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,SAAS,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4H5F;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,SAqExB,CAAC"}

package/dist/commands/webhook.js

@@ -0,0 +1,227 @@
+// webhook.ts — realm webhook command
+// Receives GitHub webhook POST requests, verifies HMAC-SHA256 signatures,
+// deduplicates deliveries by X-Github-Delivery ID, creates runs, and spawns
+// realm agent as a detached child process for each new delivery.
+import { createServer } from 'node:http';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { loadWorkflowFromFile, JsonFileStore, JsonWorkflowStore } from '@sensigo/realm';
+const DEDUP_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const CACHE_MAX_SIZE = 1000;
+/**
+ * Checks a GitHub webhook HMAC-SHA256 signature using timing-safe comparison.
+ * Returns true only if the header is present, uses the sha256= prefix, and
+ * the HMAC matches byte-for-byte. Pads both buffers to equal length before
+ * comparison to avoid length-based timing leaks.
+ */
+export function checkWebhookSignature(rawBody, signatureHeader, secret) {
+    if (!signatureHeader?.startsWith('sha256='))
+        return false;
+    const provided = signatureHeader.slice(7);
+    const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+    const a = Buffer.from(provided, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    const maxLen = Math.max(a.length, b.length);
+    const aa = Buffer.alloc(maxLen);
+    const bb = Buffer.alloc(maxLen);
+    a.copy(aa);
+    b.copy(bb);
+    // Compare in constant time AND require equal length — pads prevent length-leak
+    // from short-circuiting timingSafeEqual, but lengths must still match for validity.
+    return timingSafeEqual(aa, bb) && a.length === b.length;
+}
+/**
+ * Checks whether a delivery ID is a duplicate within the TTL window.
+ * Evicts stale entries and enforces a capacity cap on each call.
+ * Returns true if the delivery was already seen; records it and returns false otherwise.
+ */
+export function isDuplicate(deliveryCache, deliveryId) {
+    const now = Date.now();
+    // Evict stale entries on every request
+    for (const [id, ts] of deliveryCache) {
+        if (now - ts > DEDUP_TTL_MS)
+            deliveryCache.delete(id);
+    }
+    // Enforce capacity cap — evict oldest entry when at limit
+    if (deliveryCache.size >= CACHE_MAX_SIZE) {
+        const oldest = [...deliveryCache.entries()].sort((a, b) => a[1] - b[1])[0];
+        deliveryCache.delete(oldest[0]);
+    }
+    if (deliveryCache.has(deliveryId) && now - deliveryCache.get(deliveryId) < DEDUP_TTL_MS) {
+        return true;
+    }
+    deliveryCache.set(deliveryId, now);
+    return false;
+}
+/**
+ * Creates and starts the webhook HTTP server. Resolves once the server is listening.
+ * The caller is responsible for calling server.close() when done.
+ *
+ * Security-first request handling order:
+ * 1. Buffer body  2. Verify HMAC  3. Filter event/action  4. Dedup  5. Create run  6. Spawn agent
+ */
+export async function startWebhookServer(options) {
+    const runStore = options.runStore ?? new JsonFileStore();
+    const workflowStore = options.workflowStore ?? new JsonWorkflowStore();
+    const spawnFn = options.spawnFn ?? nodeSpawn;
+    const deliveryCache = new Map();
+    const server = createServer(async (req, res) => {
+        // 1. Buffer raw body before any other logic
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        const rawBody = Buffer.concat(chunks);
+        // 2. HMAC signature check — mandatory before any event filtering (oracle-attack prevention)
+        const sigHeader = req.headers['x-hub-signature-256'];
+        if (!checkWebhookSignature(rawBody, sigHeader, options.secret)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid signature' }));
+            return;
+        }
+        // 3. Parse JSON body
+        let payload;
+        try {
+            payload = JSON.parse(rawBody.toString('utf-8'));
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        // 4. Check X-Github-Event header against configured event types
+        const githubEvent = req.headers['x-github-event'];
+        const matchingEvents = options.events.filter((e) => e.event === githubEvent);
+        if (matchingEvents.length === 0) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, skipped: 'event' }));
+            return;
+        }
+        // 5. Check payload.action against configured action types
+        const payloadAction = payload.action;
+        const matchingActions = matchingEvents.filter((e) => e.action === payloadAction);
+        if (matchingActions.length === 0) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, skipped: 'action' }));
+            return;
+        }
+        // 6. Deduplication check — returns 200 to prevent GitHub retries on ignores
+        const deliveryId = req.headers['x-github-delivery'];
+        if (deliveryId !== undefined && isDuplicate(deliveryCache, deliveryId)) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, skipped: 'duplicate' }));
+            return;
+        }
+        // 7. Extract params from payload using the standard PR event field mapping
+        const pr = payload.pull_request ?? {};
+        const repo = payload.repository ?? {};
+        const sender = payload.sender ?? {};
+        const prBase = pr.base ?? {};
+        const prHead = pr.head ?? {};
+        const repoOwner = repo.owner ?? {};
+        const params = {
+            pr_number: pr.number,
+            pr_url: pr.html_url,
+            repo: repo.full_name,
+            repo_owner: repoOwner.login,
+            repo_name: repo.name,
+            pr_title: pr.title,
+            base_sha: prBase.sha,
+            head_sha: prHead.sha,
+            author: sender.login,
+            pr_action: payload['action'],
+            github_delivery_id: deliveryId,
+        };
+        // 8. Register workflow definition with the store
+        await workflowStore.register(options.definition);
+        // 9. Create run record
+        const run = await runStore.create({
+            workflowId: options.definition.id,
+            workflowVersion: options.definition.version,
+            params,
+        });
+        // 10. Spawn realm agent as detached child — inherits full env (API keys, tokens, etc.)
+        const realmBin = process.argv[1];
+        const providerArgs = [];
+        if (options.provider !== undefined)
+            providerArgs.push('--provider', options.provider);
+        if (options.model !== undefined)
+            providerArgs.push('--model', options.model);
+        const child = spawnFn(process.execPath, [realmBin, 'agent', '--run-id', run.id, ...providerArgs], { detached: true, stdio: 'inherit' });
+        child.unref();
+        // 11. Log spawn event for visibility in server logs
+        console.log(`realm agent spawned for run ${run.id} (pid: ${child.pid ?? 'unknown'})`);
+        // 12. Respond 202 Accepted — run is created, agent is running in background
+        res.writeHead(202, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, run_id: run.id }));
+    });
+    return new Promise((resolve, reject) => {
+        let isListening = false;
+        server.on('error', (err) => {
+            if (!isListening) {
+                reject(err);
+            }
+            else {
+                console.error('Realm webhook server error:', err);
+            }
+        });
+        server.listen(options.port, () => {
+            isListening = true;
+            resolve(server);
+        });
+    });
+}
+/**
+ * `realm webhook` — starts an HTTP server that creates runs from GitHub webhook deliveries.
+ * Verifies HMAC-SHA256 signatures, deduplicates deliveries, and spawns realm agent children.
+ */
+export const webhookCommand = new Command('webhook')
+    .description('Start a webhook server that creates runs from GitHub events')
+    .requiredOption('--workflow <path>', 'Path to workflow directory or workflow.yaml file')
+    .requiredOption('--port <port>', 'Port to listen on')
+    .option('--secret <secret>', 'GitHub webhook secret (overrides GITHUB_WEBHOOK_SECRET env var)')
+    .option('--event <filters>', 'Comma-separated event:action pairs to handle', 'pull_request:opened')
+    .option('--provider <provider>', 'LLM provider forwarded to spawned realm agent')
+    .option('--model <model>', 'Model name forwarded to spawned realm agent')
+    .action(async (opts) => {
+    // 1. Resolve secret — CLI flag overrides env var; refuse to start if neither set
+    const secret = opts.secret ?? process.env['GITHUB_WEBHOOK_SECRET'];
+    if (!secret) {
+        console.error('Error: webhook secret is required. Pass --secret or set GITHUB_WEBHOOK_SECRET.');
+        process.exit(1);
+        return;
+    }
+    // 2. Load and validate workflow before binding the port
+    const inputPath = opts.workflow;
+    const filePath = inputPath.endsWith('.yaml') || inputPath.endsWith('.yml')
+        ? inputPath
+        : join(inputPath, 'workflow.yaml');
+    let definition;
+    try {
+        definition = loadWorkflowFromFile(filePath);
+    }
+    catch (err) {
+        console.error(`Error: failed to load workflow: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return;
+    }
+    // 3. Parse event filters from comma-separated event:action string
+    const events = opts.event.split(',').map((token) => {
+        const [event, action] = token.trim().split(':');
+        return { event: event ?? '', action: action ?? '' };
+    });
+    // 4. Start server — only reached after secret and workflow are validated
+    const port = parseInt(opts.port, 10);
+    const server = await startWebhookServer({
+        port,
+        secret,
+        definition,
+        events,
+        ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+    });
+    const addr = server.address();
+    console.log(`Realm webhook server listening on port ${addr.port}`);
+});
+//# sourceMappingURL=webhook.js.map

package/dist/commands/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/commands/webhook.ts"],"names":[],"mappings":"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"}

package/dist/commands-registry.d.ts

@@ -0,0 +1,7 @@
+/** Commands that operate on workflow definitions (realm workflow <cmd>). */
+export declare const workflowCommands: import("commander").Command[];
+/** Commands that operate on run instances (realm run <cmd>). */
+export declare const runCommands: import("commander").Command[];
+/** Top-level commands not nested under a subgroup. */
+export declare const topLevelCommands: import("commander").Command[];
+//# sourceMappingURL=commands-registry.d.ts.map

package/dist/commands-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands-registry.d.ts","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAsBA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,+BAQ5B,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,WAAW,+BAQvB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,+BAA2D,CAAC"}

package/dist/commands-registry.js

@@ -0,0 +1,44 @@
+// commands-registry.ts — exports all CLI commands grouped by category.
+// Consumed by @sensigo/realm-cli itself and by realm-cloud/packages/cli-cloud,
+// which adds cloud-specific commands on top.
+import { validateCommand } from './commands/validate.js';
+import { registerCommand } from './commands/register.js';
+import { runCommand } from './commands/run.js';
+import { resumeCommand } from './commands/resume.js';
+import { cleanupCommand } from './commands/cleanup.js';
+import { respondCommand } from './commands/respond.js';
+import { inspectCommand } from './commands/inspect.js';
+import { replayCommand } from './commands/replay.js';
+import { diffCommand } from './commands/diff.js';
+import { initCommand } from './commands/init.js';
+import { testCommand } from './commands/test.js';
+import { watchCommand } from './commands/watch.js';
+import { listCommand } from './commands/list.js';
+import { mcpCommand } from './commands/mcp.js';
+import { serveCommand } from './commands/serve.js';
+import { migrateCommand } from './commands/migrate.js';
+import { agentCommand } from './commands/agent.js';
+import { webhookCommand } from './commands/webhook.js';
+/** Commands that operate on workflow definitions (realm workflow <cmd>). */
+export const workflowCommands = [
+    initCommand,
+    validateCommand,
+    registerCommand,
+    watchCommand,
+    runCommand,
+    testCommand,
+    migrateCommand,
+];
+/** Commands that operate on run instances (realm run <cmd>). */
+export const runCommands = [
+    listCommand,
+    inspectCommand,
+    replayCommand,
+    diffCommand,
+    resumeCommand,
+    respondCommand,
+    cleanupCommand,
+];
+/** Top-level commands not nested under a subgroup. */
+export const topLevelCommands = [mcpCommand, serveCommand, agentCommand, webhookCommand];
+//# sourceMappingURL=commands-registry.js.map

package/dist/commands-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands-registry.js","sourceRoot":"","sources":["../src/commands-registry.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,+EAA+E;AAC/E,6CAA6C;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW;IACX,eAAe;IACf,eAAe;IACf,YAAY;IACZ,UAAU;IACV,WAAW;IACX,cAAc;CACf,CAAC;AAEF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,cAAc;CACf,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// @sensigo/realm-cli — command-line interface for Realm
+import 'dotenv/config';
+import { Command } from 'commander';
+import { workflowCommands, runCommands, topLevelCommands } from './commands-registry.js';
+const program = new Command();
+program.name('realm').description('Realm workflow engine CLI').version('0.1.0');
+// realm workflow — operations on workflow definitions
+const workflowCmd = new Command('workflow').description('Manage workflow definitions');
+for (const cmd of workflowCommands)
+    workflowCmd.addCommand(cmd);
+// realm run — operations on run instances
+const runCmd = new Command('run').description('Manage workflow run instances');
+for (const cmd of runCommands)
+    runCmd.addCommand(cmd);
+program.addCommand(workflowCmd);
+program.addCommand(runCmd);
+for (const cmd of topLevelCommands)
+    program.addCommand(cmd);
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,wDAAwD;AACxD,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhF,sDAAsD;AACtD,MAAM,WAAW,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC,6BAA6B,CAAC,CAAC;AACvF,KAAK,MAAM,GAAG,IAAI,gBAAgB;IAAE,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAEhE,0CAA0C;AAC1C,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,+BAA+B,CAAC,CAAC;AAC/E,KAAK,MAAM,GAAG,IAAI,WAAW;IAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAEtD,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,KAAK,MAAM,GAAG,IAAI,gBAAgB;IAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAE5D,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/store/replay-store.d.ts

@@ -0,0 +1,29 @@
+import type { ReplayStepResult } from '../commands/replay.js';
+/** A persisted replay snapshot: the result of replayRun() + the metadata that produced it. */
+export interface ReplayRecord {
+    /** Unique ID, always starts with "rpl_". */
+    id: string;
+    /** The run ID that was replayed. */
+    origin_run_id: string;
+    /** The workflow ID of the origin run. */
+    workflow_id: string;
+    /** The overrides that were applied: ["step.field=value", ...] — raw string form. */
+    overrides: string[];
+    /** The step-level results from replayRun(). */
+    results: ReplayStepResult[];
+    /** ISO 8601 creation timestamp. */
+    created_at: string;
+}
+export interface ReplayStore {
+    /** Persist a replay record. Returns the stored record with its assigned ID. */
+    save(record: Omit<ReplayRecord, 'id' | 'created_at'>): Promise<ReplayRecord>;
+    /** Get a replay record by ID. Throws a plain Error if not found (not a WorkflowError). */
+    get(replayId: string): Promise<ReplayRecord>;
+}
+export declare class JsonFileReplayStore implements ReplayStore {
+    private readonly replaysDir;
+    constructor(replaysDir?: string);
+    save(record: Omit<ReplayRecord, 'id' | 'created_at'>): Promise<ReplayRecord>;
+    get(replayId: string): Promise<ReplayRecord>;
+}
+//# sourceMappingURL=replay-store.d.ts.map

package/dist/store/replay-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-store.d.ts","sourceRoot":"","sources":["../../src/store/replay-store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7E,0FAA0F;IAC1F,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9C;AAID,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,UAAU,CAAC,EAAE,MAAM;IAIzB,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAS5E,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CASnD"}

package/dist/store/replay-store.js

@@ -0,0 +1,31 @@
+// ReplayStore — interface and JsonFileReplayStore for persisting replay results locally.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+const DEFAULT_REPLAYS_DIR = join(homedir(), '.realm', 'replays');
+export class JsonFileReplayStore {
+    replaysDir;
+    constructor(replaysDir) {
+        this.replaysDir = replaysDir ?? DEFAULT_REPLAYS_DIR;
+    }
+    async save(record) {
+        await mkdir(this.replaysDir, { recursive: true });
+        const id = `rpl_${randomUUID()}`;
+        const created_at = new Date().toISOString();
+        const full = { ...record, id, created_at };
+        await writeFile(join(this.replaysDir, `${id}.json`), JSON.stringify(full, null, 2), 'utf8');
+        return full;
+    }
+    async get(replayId) {
+        const filePath = join(this.replaysDir, `${replayId}.json`);
+        try {
+            const content = await readFile(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch {
+            throw new Error(`Replay not found: ${replayId}`);
+        }
+    }
+}
+//# sourceMappingURL=replay-store.js.map

package/dist/store/replay-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-store.js","sourceRoot":"","sources":["../../src/store/replay-store.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA0BzC,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEjE,MAAM,OAAO,mBAAmB;IACb,UAAU,CAAS;IAEpC,YAAY,UAAmB;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,IAAI,mBAAmB,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA+C;QACxD,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,EAAE,GAAG,OAAO,UAAU,EAAE,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAiB,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC;QACzD,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;CACF"}