@sequenceholdings/studio-cli 0.1.9

package/dist/process/simulate.js

@@ -0,0 +1,328 @@
+/**
+ * In-process orchestrator walker with stubbed runners. Lets process
+ * authors verify their graph topology + routing locally without
+ * deploying to Trigger.dev.
+ *
+ * Mirrors the production orchestrator's `verifyAndAdvance` loop but:
+ *   - Skips DB persistence
+ *   - Stubs agent runner with the first outgoing edge + synthetic payload
+ *   - Stubs human runner identically (or accepts caller-supplied decisions)
+ *   - Stubs automation runner identically — native handlers live in the
+ *     Atlas image and can't execute here
+ */
+import { DEFAULT_MAX_FANOUT_WIDTH, } from '@sequenceholdings/lattice/define';
+import { extractOutputState, mergeRunState } from '@sequenceholdings/lattice';
+const DEFAULT_MAX_ITERATIONS = 1000;
+const DEFAULT_MAX_REVISITS = 100;
+export async function simulateProcess(opts) {
+    const proc = opts.process;
+    const startId = opts.startNodeId ?? proc.start_node_id;
+    const startNode = proc.nodes.find((n) => n.id === startId);
+    if (!startNode) {
+        return {
+            steps: [],
+            status: 'failed',
+            error: `start_node_id "${startId}" not found in process "${proc.id}"`,
+        };
+    }
+    const maxIterations = opts.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const maxRevisits = opts.maxRevisits ?? DEFAULT_MAX_REVISITS;
+    const visits = new Map();
+    const steps = [];
+    const upstream = {};
+    let runState = opts.state ?? {};
+    const processesById = opts.processesById ??
+        new Map([[proc.id, proc]]);
+    let current = startNode;
+    let iteration = 0;
+    try {
+        for (;;) {
+            iteration += 1;
+            if (iteration > maxIterations) {
+                throw new Error(`iteration cap (${maxIterations}) exceeded`);
+            }
+            const visitsForNode = (visits.get(current.id) ?? 0) + 1;
+            visits.set(current.id, visitsForNode);
+            if (visitsForNode > maxRevisits) {
+                throw new Error(`revisit cap (${maxRevisits}) exceeded for node "${current.id}"`);
+            }
+            const ctx = {
+                entity: opts.entity ? { type: opts.entity.type, id: opts.entity.id } : null,
+                upstream: upstream,
+                state: runState,
+                run: {
+                    id: 'sim',
+                    process_id: proc.id,
+                    version: 'simulate',
+                    started_at: new Date().toISOString(),
+                    started_by: 'simulator',
+                    metadata: opts.metadata ?? {},
+                },
+            };
+            const input = await runInputMapperIfAny(current, ctx);
+            const output = await dispatchInProcess({
+                node: current,
+                input,
+                ctx,
+                humanDecisions: opts.humanDecisions ?? {},
+                iteration,
+                processesById,
+                record: (step) => steps.push(step),
+            });
+            const statePatch = extractOutputState(output);
+            if (statePatch)
+                runState = mergeRunState(runState, statePatch);
+            const outgoing = current.outgoing_edges;
+            let nextEdgeId;
+            let toNodeId;
+            if (outgoing.length === 0) {
+                steps.push({
+                    iteration,
+                    node_id: current.id,
+                    kind: current.kind,
+                    input,
+                    output,
+                });
+                upstream[current.id] = output;
+                break;
+            }
+            else if (outgoing.length === 1) {
+                nextEdgeId = output.edge_id ?? outgoing[0].id;
+                toNodeId = outgoing[0].to;
+            }
+            else {
+                if (!output.edge_id) {
+                    throw new Error(`node "${current.id}" has ${outgoing.length} outgoing edges but output did not include edge_id`);
+                }
+                const edge = outgoing.find((e) => e.id === output.edge_id);
+                if (!edge) {
+                    throw new Error(`node "${current.id}" returned edge_id "${output.edge_id}" not in outgoing_edges [${outgoing.map((e) => e.id).join(', ')}]`);
+                }
+                nextEdgeId = edge.id;
+                toNodeId = edge.to;
+            }
+            steps.push({
+                iteration,
+                node_id: current.id,
+                kind: current.kind,
+                input,
+                output,
+                next_edge_id: nextEdgeId,
+                to_node_id: toNodeId,
+            });
+            upstream[current.id] = output;
+            if (!toNodeId)
+                break;
+            const nextNode = proc.nodes.find((n) => n.id === toNodeId);
+            if (!nextNode) {
+                throw new Error(`target node "${toNodeId}" not found in process`);
+            }
+            current = nextNode;
+        }
+        return { steps, status: 'completed' };
+    }
+    catch (err) {
+        return {
+            steps,
+            status: 'failed',
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function runInputMapperIfAny(node, ctx) {
+    const mapper = node.input;
+    if (typeof mapper !== 'function')
+        return ctx;
+    return Promise.resolve(mapper(ctx));
+}
+async function dispatchInProcess(args) {
+    switch (args.node.kind) {
+        case 'automation': {
+            // Native automation handlers run server-side from the Atlas image and
+            // can't execute in the simulator. Stub like an agent: take the first
+            // declared edge with a synthetic payload so topology + routing still walk.
+            const auto = args.node;
+            return {
+                edge_id: auto.outgoing_edges[0]?.id,
+                payload: { _simulated: true, function: auto.registered_function_id },
+            };
+        }
+        case 'agent': {
+            const agent = args.node;
+            return {
+                edge_id: agent.outgoing_edges[0]?.id,
+                payload: { _simulated: true, agent_id: agent.agent.id },
+            };
+        }
+        case 'human': {
+            const human = args.node;
+            const supplied = args.humanDecisions[human.id];
+            if (supplied)
+                return supplied;
+            return {
+                edge_id: human.outgoing_edges[0]?.id,
+                payload: { _simulated: true, decision: 'approved' },
+            };
+        }
+        case 'parallel': {
+            return simulateParallel(args, args.node);
+        }
+        case 'subprocess': {
+            return simulateSubprocess(args, args.node);
+        }
+        case 'delay': {
+            // No real wait in simulation — a delay just continues to its single
+            // outgoing edge (auto-taken by the router).
+            const delay = args.node;
+            return { edge_id: delay.outgoing_edges[0]?.id };
+        }
+        case 'managed_function': {
+            // Simulation cannot call live managed functions — route to success with a stub payload.
+            return {
+                edge_id: 'success',
+                payload: { _simulated: true, kind: 'managed_function' },
+            };
+        }
+        default: {
+            const _exhaustive = args.node;
+            void _exhaustive;
+            throw new Error(`unknown node kind`);
+        }
+    }
+}
+/**
+ * Resolve a parallel block's branches, run each sub-node in-process (recursing
+ * for nested parallels), record each as a branch sub-step, then run the
+ * author's `join` reducer to produce the parallel node's single output —
+ * mirroring runtime semantics (all branches complete, then join; no early
+ * exit). Dynamic fan-out branch ids are positional (`"0"`, `"1"`, …), matching
+ * the runtime/idempotency convention.
+ */
+async function simulateParallel(args, node) {
+    const branches = [];
+    if (node.branches) {
+        node.branches.forEach((b, i) => branches.push({ branchId: b.branch_id, index: i, item: null, sub: b.node }));
+    }
+    else {
+        const items = node.fan_out(args.ctx) ?? [];
+        const cap = node.max_fanout ?? DEFAULT_MAX_FANOUT_WIDTH;
+        if (items.length > cap) {
+            throw new Error(`parallel node "${node.id}" fan_out produced ${items.length} items; ` +
+                `exceeds max_fanout=${cap}`);
+        }
+        items.forEach((item, i) => branches.push({ branchId: String(i), index: i, item, sub: node.branch }));
+    }
+    const results = [];
+    for (const br of branches) {
+        const branchCtx = {
+            ...args.ctx,
+            branch: { id: br.branchId, index: br.index, item: br.item },
+        };
+        const subInput = await runInputMapperIfAny(br.sub, branchCtx);
+        const subOutput = await dispatchInProcess({
+            node: br.sub,
+            input: subInput,
+            ctx: branchCtx,
+            humanDecisions: args.humanDecisions,
+            iteration: args.iteration,
+            processesById: args.processesById,
+            record: args.record,
+        });
+        args.record({
+            iteration: args.iteration,
+            node_id: br.sub.id,
+            kind: br.sub.kind,
+            input: subInput,
+            output: subOutput,
+            branch_id: br.branchId,
+            parent_node_id: node.id,
+        });
+        results.push({
+            branch_id: br.branchId,
+            node_id: br.sub.id,
+            index: br.index,
+            status: 'completed',
+            output: subOutput,
+            item: br.item,
+        });
+    }
+    const joinOutput = node.join(results, args.ctx);
+    return foldBranchState(joinOutput, results);
+}
+/**
+ * Mirror the runtime parallel runner's `mergeBranchState`: fold each branch's
+ * `output.state` onto the join output (branch order, the join's own state last)
+ * so branch state patches reach run state in simulation exactly as production
+ * folds them. The simulator runs every branch fresh, so there is no cached
+ * branch to skip.
+ */
+function foldBranchState(joinOutput, branches) {
+    const merged = {};
+    const fold = (s) => {
+        if (!s)
+            return;
+        for (const [k, v] of Object.entries(s))
+            merged[k] = v;
+    };
+    for (const b of branches) {
+        if (b.status === 'failed')
+            continue;
+        fold(b.output.state);
+    }
+    fold(joinOutput.state);
+    if (Object.keys(merged).length === 0)
+        return joinOutput;
+    return { ...joinOutput, state: merged };
+}
+async function simulateSubprocess(args, node) {
+    const child = args.processesById.get(node.process);
+    if (!child) {
+        throw new Error(`subprocess node "${node.id}" references process "${node.process}" which is not loaded — ` +
+            `include it in the same bundle roots`);
+    }
+    const childMetadata = node.input &&
+        typeof args.input === 'object' &&
+        args.input !== null &&
+        !Array.isArray(args.input)
+        ? args.input
+        : {};
+    const childResult = await simulateProcess({
+        process: child,
+        processesById: args.processesById,
+        entity: args.ctx.entity
+            ? { type: String(args.ctx.entity.type ?? 'unknown'), id: String(args.ctx.entity.id ?? 'sim') }
+            : undefined,
+        metadata: childMetadata,
+        humanDecisions: args.humanDecisions,
+    });
+    const childFailed = childResult.status === 'failed';
+    if (childFailed && node.on_child_error === 'fail') {
+        throw new Error(childResult.error ?? `child process "${node.process}" simulation failed`);
+    }
+    const childOutput = childResult.steps.at(-1)?.output;
+    return node.output({
+        run_id: 'sim-child',
+        process_id: node.process,
+        version: node.version ?? 'simulate',
+        status: childFailed ? 'failed' : 'completed',
+        output: childOutput,
+        ...(childResult.error ? { error: childResult.error } : {}),
+    }, args.ctx);
+}
+export function formatSimulateResult(result) {
+    const lines = [];
+    for (const step of result.steps) {
+        const isBranch = step.parent_node_id !== undefined;
+        const indent = isBranch ? '      ↳ ' : '';
+        const label = isBranch ? `[${step.branch_id}] ${step.node_id}` : step.node_id;
+        const routing = isBranch
+            ? '' // branch sub-steps route internally; only the parallel join routes
+            : step.next_edge_id
+                ? `  →  ${step.next_edge_id} → ${step.to_node_id}`
+                : '  (terminal)';
+        lines.push(`${String(step.iteration).padStart(3)} ${indent}${step.kind.padEnd(10)} ${label}${routing}`);
+    }
+    lines.push('');
+    lines.push(`status: ${result.status}${result.error ? ' — ' + result.error : ''}`);
+    return lines.join('\n');
+}

package/dist/prompt.d.ts

@@ -0,0 +1,35 @@
+export declare const LOG = "[seq-studio]";
+export type PromptFn = (question: string) => Promise<string>;
+/** Visible TTY prompt (echo on). */
+export declare function promptVisible(question: string, promptFn?: PromptFn): Promise<string>;
+/**
+ * Print a preview block and require exact `yes` before proceeding.
+ * Pass `confirmed: true` (--yes) for non-interactive automation.
+ */
+export declare function confirmYes({ preview, prompt, confirmed, promptFn, }: {
+    preview: string[];
+    prompt?: string;
+    confirmed?: boolean;
+    promptFn?: PromptFn;
+}): Promise<boolean>;
+export interface PromptChoice {
+    /** Single-character selector, e.g. `y`. */
+    key: string;
+    /** Human-readable line shown under the preview. */
+    label: string;
+    /** Token returned when this choice is selected. */
+    value: string;
+}
+/**
+ * Print a preview block plus a keyed multi-choice menu and return the chosen
+ * option's `value` (or `null` when aborted / unrecognized). The multi-way
+ * analogue of `confirmYes`, used by `secrets pin` (pin+redeploy / pin-only /
+ * cancel). Pass `auto` (resolved from flags) to skip the prompt for CI.
+ */
+export declare function confirmChoice({ preview, choices, prompt, auto, promptFn, }: {
+    preview: string[];
+    choices: PromptChoice[];
+    prompt?: string;
+    auto?: string;
+    promptFn?: PromptFn;
+}): Promise<string | null>;

package/dist/prompt.js

@@ -0,0 +1,65 @@
+import { createInterface } from 'node:readline';
+export const LOG = '[seq-studio]';
+/** Visible TTY prompt (echo on). */
+export async function promptVisible(question, promptFn) {
+    if (promptFn)
+        return promptFn(question);
+    if (!process.stdin.isTTY) {
+        throw new Error('stdin is not a TTY — re-run with --yes to confirm non-interactively');
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((resolvePrompt) => {
+        rl.question(question, (value) => resolvePrompt(value));
+    });
+    rl.close();
+    return answer.trim();
+}
+/**
+ * Print a preview block and require exact `yes` before proceeding.
+ * Pass `confirmed: true` (--yes) for non-interactive automation.
+ */
+export async function confirmYes({ preview, prompt = 'Type "yes" to confirm: ', confirmed = false, promptFn, }) {
+    for (const line of preview) {
+        console.log(line);
+    }
+    if (confirmed)
+        return true;
+    if (!process.stdin.isTTY && !promptFn) {
+        console.error(`${LOG} re-run with --yes to confirm non-interactively`);
+        return false;
+    }
+    const answer = await promptVisible(prompt, promptFn);
+    if (answer !== 'yes') {
+        console.error(`${LOG} aborted — answer was not "yes"`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Print a preview block plus a keyed multi-choice menu and return the chosen
+ * option's `value` (or `null` when aborted / unrecognized). The multi-way
+ * analogue of `confirmYes`, used by `secrets pin` (pin+redeploy / pin-only /
+ * cancel). Pass `auto` (resolved from flags) to skip the prompt for CI.
+ */
+export async function confirmChoice({ preview, choices, prompt, auto, promptFn, }) {
+    for (const line of preview) {
+        console.log(line);
+    }
+    for (const choice of choices) {
+        console.log(`  [${choice.key}] ${choice.label}`);
+    }
+    if (auto !== undefined)
+        return auto;
+    if (!process.stdin.isTTY && !promptFn) {
+        console.error(`${LOG} not a TTY — re-run with --yes (add --no-redeploy to skip redeploy) to choose non-interactively`);
+        return null;
+    }
+    const keyPrompt = prompt ?? `Choose [${choices.map((c) => c.key).join('/')}]: `;
+    const answer = (await promptVisible(keyPrompt, promptFn)).trim().toLowerCase();
+    const match = choices.find((c) => c.key.toLowerCase() === answer);
+    if (!match) {
+        console.error(`${LOG} aborted — unrecognized choice`);
+        return null;
+    }
+    return match.value;
+}

package/dist/repos/commands.d.ts

@@ -0,0 +1,49 @@
+import type { ParsedArgs } from '../process/commands.js';
+import { type CommandContext } from '../functions/commands.js';
+import { type RunGitClone } from './git-clone.js';
+import { type ResolvedEnv } from '../config.js';
+export declare function parseRepoPath(input: string | undefined): {
+    namespace: string;
+    name: string;
+};
+/**
+ * A value-taking flag given without a value parses as `true` (parseArgs
+ * semantics) — silently ignoring it would make the command do something other
+ * than what was asked (e.g. `list --namespace --mine` printing the FULL repo
+ * list, or `pull --ref --out x` fetching the default branch). Error instead.
+ */
+export declare function stringFlag(flags: ParsedArgs['flags'], key: string): string | undefined;
+/** Smart-HTTP clone base (aligned with PLA-83: `…/repos/<id>/git`). */
+export declare function cloneUrl(ctx: CommandContext, repoId: string): string;
+/**
+ * `--force` may recursively delete `destDir`. Refuse cwd / home / filesystem
+ * roots / ancestors of cwd so a typo like `--out . --force` cannot wipe the
+ * working tree.
+ */
+export declare function assertSafeForceDest(destDir: string): void;
+export declare function reposNamespacesCommand(args: ParsedArgs): Promise<number>;
+export declare function reposListCommand(args: ParsedArgs): Promise<number>;
+export declare function reposShowCommand(args: ParsedArgs): Promise<number>;
+export declare function reposCreateCommand(args: ParsedArgs): Promise<number>;
+export declare function reposPullCommand(args: ParsedArgs): Promise<number>;
+/**
+ * Preferred clone verb.
+ *
+ * With `ATLAS_GIT_PAT`:
+ *   - `--url <clone-url>` or `--id <repo-uuid>` → smart-HTTP clone with no seqapi
+ *   - `<ns>/<name>` → needs Auth0 to resolve the UUID, then smart-HTTP clone
+ * Without a PAT: JSON materialize (needs Auth0) + PAT setup hints.
+ *
+ * `gitClone` is injectable for tests.
+ */
+export declare function reposCloneCommand(args: ParsedArgs, deps?: {
+    gitClone?: RunGitClone;
+}): Promise<number>;
+/**
+ * Validate clone URL shape and that the origin matches the resolved Atlas env
+ * so askpass never sends ATLAS_GIT_PAT to an attacker-controlled host.
+ */
+export declare function normalizeCloneUrl(raw: string, env: ResolvedEnv): string;
+export declare function reposDeleteCommand(args: ParsedArgs): Promise<number>;
+export declare const REPOS_USAGE = "usage:\n  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment\n  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces\n  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)\n  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo\n  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n  seq-studio repos clone --url <https://\u2026/repos/<id>/git> [-e env] [--ref r] [--out dir]\n  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]\n                                                                    smart-HTTP when ATLAS_GIT_PAT is set;\n                                                                    otherwise JSON materialize (<ns>/<name>)\n  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n                                                                    materialize the tree at a ref (JSON API)\n  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)\n\n  Flags: -e/--env <local|staging|production|banksouth>\n\n  clone prefers real git clone (PAT via askpass \u2014 never written into the remote\n  URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints\n  how to get a PAT (Atlas UI /settings/tokens \u2014 no seqapi required).\n  No seqapi + PAT: use --url from Repositories \u2192 Clone (or --id <uuid>).\n  --ref accepts a branch, tag, or commit SHA (SHA \u2192 clone then checkout).\n\n  Authenticate JSON API calls with: seqapi login\n  Authenticate git clone/push with: ATLAS_GIT_PAT (from Atlas Settings \u2192 Tokens)\n";
+export declare function runReposCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;