@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/scriptlanes.d.ts

@@ -0,0 +1,182 @@
+/**
+ * scriptlanes.ts — the script lanes of the saddle engine: sh execution
+ * through the universal runner, yml and yaml workflow descriptors
+ * interpreted and compiled through babel into executable job plans,
+ * background execution through the house job queue, and docker-ready
+ * descriptors for the container lane.
+ *
+ * The lanes this file opens answer the modalities the registry declares
+ * (runner-universal for the bash lane, runner-babel for the compile lane,
+ * container-docker for the descriptor lane) and keep the owner's PR15
+ * mandate verbatim: "Implemente execução de SHs / interpretação de YML /
+ * YAML com compilação via Babel para permitir execução em segundo plano /
+ * Docker".
+ *
+ * The laws every lane below keeps:
+ * - sh scripts execute server-side through the engine (the bash lane),
+ *   never the visitor machine: every public run entry refuses a scope
+ *   that carries window or document (assertservercontext);
+ * - yml and yaml descriptors interpret into executable job plans through
+ *   the house yaml subset (documented at the parser), and the babel lane
+ *   compiles the descriptor through @babel/core into a regenerated
+ *   literal the engine parses back through node:vm — the roundtrip is
+ *   validated, never presumed;
+ * - background execution rides the house jobqueue and the runstatuses
+ *   vocabulary (created, submitted, running, succeeded, failed,
+ *   cancelled): the lane kicks the run detached from the caller and the
+ *   status stays observable through scriptRunStatus;
+ * - honest execution only: no faked results, a {code, message} shape on
+ *   every fallible path, and deadlines enforced with a timeout kill on
+ *   the child process.
+ */
+/**
+ * the server context law and the plan nouns: the types the lanes speak
+ * and the refusal every public run entry carries.
+ */
+/** one interpreted step of a script plan: the name the run reports, the
+ * sh text the bash lane executes, and the optional per-step deadline in
+ * milliseconds. */
+export type ScriptStep = {
+    name: string;
+    run: string;
+    timeoutms?: number;
+};
+/** an executable job plan: the steps in execution order, the descriptor
+ * source the plan was interpreted from, and the compile lane the plan
+ * rides (direct for the sh lane, babel for the yml and yaml lanes —
+ * compilewithbabel performs the babel lane and stamps it). */
+export type ScriptPlan = {
+    steps: ScriptStep[];
+    source: "sh" | "yml" | "yaml";
+    compiledvia: "babel" | "direct";
+};
+/** the run options the execution lanes accept: the storage handle is
+ * carried for the engine commit lane (the script lane itself executes
+ * and answers — it never pretends a commit), and deadlinems is the
+ * fallback deadline for steps that carry no timeoutms of their own. */
+export type ScriptRunOptions = {
+    storage?: unknown;
+    deadlinems?: number;
+};
+/** one honestly observed step execution: the exit code (null when the
+ * step never ran — skipped, killed or unspawnable), the captured
+ * streams, the measured duration, and the skip or timeout flags. */
+export type ScriptStepResult = {
+    name: string;
+    exitcode: number | null;
+    stdout: string;
+    stderr: string;
+    durationms: number;
+    skipped?: boolean;
+    timedout?: boolean;
+    signal?: string | null;
+    truncated?: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/** the honest result of one plan run: succeeded only when every step
+ * exited zero, failed with the first failure otherwise. */
+export type ScriptRunResult = {
+    status: "succeeded" | "failed";
+    steps: ScriptStepResult[];
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/** the observable record of one background run: the runstatuses
+ * vocabulary the transitions walk, plus the result once the detached run
+ * settles. */
+export type ScriptRunRecord = {
+    version: number;
+    requestid: string;
+    name: string;
+    status: string;
+    runid?: string;
+    attempt: number;
+    createdat: number;
+    updatedat: number;
+    history: Array<{
+        from: string;
+        to: string;
+        at: number;
+        reason?: string;
+    }>;
+    metadata: Record<string, unknown>;
+    result?: ScriptRunResult;
+};
+/** refuses a scope that carries window or document: the script lanes
+ * execute server-side only, and the visitor machine is never touched
+ * (the never-the-visitor-browser law). every public run entry calls
+ * this before any work. */
+export declare function assertservercontext(scope?: Record<string, unknown>): void;
+/**
+ * the interpretation lanes: interpretsh wraps a raw sh script as one
+ * direct step, and the house yaml subset parser reads the workflow
+ * descriptors (yml and yaml spellings) into step lists.
+ */
+/** wraps a raw sh script as a one-step plan: the script rides the bash
+ * lane directly, no compile step, so the plan declares the direct lane. */
+export declare function interpretsh(script: string): ScriptPlan;
+/** interprets a yml workflow descriptor into an executable job plan
+ * through the house yaml subset; the plan declares the babel compile
+ * lane (compilewithbabel performs it). a parse failure throws the honest
+ * YAML_INTERPRET_FAILED code. */
+export declare function interpretyml(text: string): ScriptPlan;
+/** interprets a yaml workflow descriptor — the same house subset under
+ * the yaml spelling, so both file extensions ride one lane. */
+export declare function interpretyaml(text: string): ScriptPlan;
+/** compiles a script plan through the babel lane: serialize the plan to
+ * a javascript literal, transform it through @babel/core (no presets,
+ * no config files — the minimal options the runtime carries), parse the
+ * regenerated source back through node:vm, validate the roundtrip kept
+ * every step and the source, and return the plan stamped
+ * compiledvia "babel". */
+export declare function compilewithbabel(plan: ScriptPlan): Promise<ScriptPlan>;
+/** executes a script plan sequentially server-side: each step runs
+ * through `bash -c` with the deadline `step.timeoutms ?? the caller
+ * deadlinems ?? ten seconds`, the exit code and both streams are
+ * captured, a failing step fails the plan honestly and every later step
+ * is skipped with a null exit code and the skipped flag. the storage
+ * option is carried for the engine commit lane — this lane executes and
+ * answers, it never pretends a commit. */
+export declare function runscript(plan: ScriptPlan, options?: ScriptRunOptions): Promise<ScriptRunResult>;
+/** kicks a script plan in the background: the run is registered as a
+ * house run record, queued through the house job queue and executed
+ * without awaiting — the call returns {runid, status} immediately and
+ * the statuses stay observable through scriptRunStatus (created,
+ * running, succeeded, failed — the runstatuses vocabulary). */
+export declare function runscriptbackground(plan: ScriptPlan, options?: ScriptRunOptions): {
+    runid: string;
+    status: string;
+};
+/** reads the observable record of one background run: the runstatuses
+ * vocabulary status, the auditable transition history, and the result
+ * once the detached run settled. an unknown runid refuses with the
+ * honest SCRIPT_RUN_NOT_FOUND code. */
+export declare function scriptRunStatus(runid: string): ScriptRunRecord & {
+    result?: ScriptRunResult;
+};
+/**
+ * the docker lane: dockerdescriptor emits the docker-ready descriptor
+ * the container modality (container-docker) consumes — a Dockerfile on
+ * the house node base with every step as an escaped RUN line, plus the
+ * verbatim plan script and the sh entrypoint.
+ */
+/** the house node base image the descriptor pins: the Dockerfile
+ * saddle-runtime stage rides FROM node:26.8.1-slim (the node-engine
+ * service image), so the descriptor asks for the base the house
+ * actually pins rather than a floating tag. */
+export declare const SCRIPTLANES_NODE_BASE = "node:26.8.1-slim";
+/** emits the docker-ready descriptor for the container lane: a
+ * Dockerfile on the house node base carrying every step as an escaped
+ * RUN line (bash -c with the quotes and dollars escaped), the verbatim
+ * plan script written through a quoted heredoc COPY, and the sh
+ * entrypoint that runs it. the returned entrypoint matches the
+ * ENTRYPOINT line of the emitted Dockerfile. */
+export declare function dockerdescriptor(plan: ScriptPlan): {
+    dockerfile: string;
+    entrypoint: string;
+};