@kb-labs/workflow-steps 2.96.0

package/README.md

@@ -0,0 +1,23 @@
+# @kb-labs/workflow-builtins
+
+Built-in workflow handlers (shell, etc.)
+
+## Installation
+
+```bash
+pnpm add @kb-labs/workflow-builtins
+```
+
+## Usage
+
+```typescript
+import { ... } from '@kb-labs/workflow-builtins';
+```
+
+## API
+
+See TypeScript types for detailed API documentation.
+
+## License
+
+MIT

package/dist/approval.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module @kb-labs/workflow-steps/approval
+ * Types and handler for builtin:approval step
+ *
+ * Approval steps pause the pipeline and wait for human decision.
+ * The worker handles polling; resolveApproval() on the engine resumes execution.
+ */
+/**
+ * Input for builtin:approval step (spec.with)
+ */
+interface ApprovalInput {
+    /** Display title for the approval request */
+    title: string;
+    /** Contextual data shown to the approver (already interpolated) */
+    context?: Record<string, unknown>;
+    /** Optional instructions for the approver */
+    instructions?: string;
+}
+/**
+ * Output produced by a resolved approval step
+ */
+interface ApprovalOutput {
+    /** Whether the approval was granted */
+    approved: boolean;
+    /** Action taken: "approve" or "reject" */
+    action: 'approve' | 'reject';
+    /** Optional comment from the approver */
+    comment?: string;
+    /** Additional data provided by the approver */
+    [key: string]: unknown;
+}
+/**
+ * ApprovalHandler — signals the worker to pause and wait for human approval.
+ * The worker owns the polling loop; this handler only marks the intent.
+ */
+declare class ApprovalHandler {
+    static readonly uses = "builtin:approval";
+    handle(_input: ApprovalInput): {
+        status: 'waiting';
+        reason: 'approval';
+    };
+}
+
+export { ApprovalHandler, type ApprovalInput, type ApprovalOutput };

package/dist/approval.js

@@ -0,0 +1,11 @@
+// src/approval.ts
+var ApprovalHandler = class {
+  static uses = "builtin:approval";
+  handle(_input) {
+    return { status: "waiting", reason: "approval" };
+  }
+};
+
+export { ApprovalHandler };
+//# sourceMappingURL=approval.js.map
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/approval.ts"],"names":[],"mappings":";AA2CO,IAAM,kBAAN,MAAsB;AAAA,EAC3B,OAAgB,IAAA,GAAO,kBAAA;AAAA,EAEvB,OAAO,MAAA,EAAkE;AACvE,IAAA,OAAO,EAAE,MAAA,EAAQ,SAAA,EAAW,MAAA,EAAQ,UAAA,EAAW;AAAA,EACjD;AACF","file":"approval.js","sourcesContent":["/**\n * @module @kb-labs/workflow-steps/approval\n * Types and handler for builtin:approval step\n *\n * Approval steps pause the pipeline and wait for human decision.\n * The worker handles polling; resolveApproval() on the engine resumes execution.\n */\n\n/**\n * Input for builtin:approval step (spec.with)\n */\nexport interface ApprovalInput {\n  /** Display title for the approval request */\n  title: string;\n\n  /** Contextual data shown to the approver (already interpolated) */\n  context?: Record<string, unknown>;\n\n  /** Optional instructions for the approver */\n  instructions?: string;\n}\n\n/**\n * Output produced by a resolved approval step\n */\nexport interface ApprovalOutput {\n  /** Whether the approval was granted */\n  approved: boolean;\n\n  /** Action taken: \"approve\" or \"reject\" */\n  action: 'approve' | 'reject';\n\n  /** Optional comment from the approver */\n  comment?: string;\n\n  /** Additional data provided by the approver */\n  [key: string]: unknown;\n}\n\n/**\n * ApprovalHandler — signals the worker to pause and wait for human approval.\n * The worker owns the polling loop; this handler only marks the intent.\n */\nexport class ApprovalHandler {\n  static readonly uses = 'builtin:approval';\n\n  handle(_input: ApprovalInput): { status: 'waiting'; reason: 'approval' } {\n    return { status: 'waiting', reason: 'approval' };\n  }\n}\n"]}

package/dist/gate.d.ts

@@ -0,0 +1,97 @@
+import { ExpressionContext } from '@kb-labs/workflow-contracts';
+
+/**
+ * @module @kb-labs/workflow-steps/gate
+ * Types and handler for builtin:gate step
+ *
+ * Gate steps act as automatic routers — they read a decision value
+ * from previous step outputs and route the pipeline accordingly:
+ * - continue: proceed to next step
+ * - fail: fail the pipeline
+ * - restart: reset steps back to target and re-schedule with context
+ * - skip: mark intermediate steps as skipped and jump forward to a target step
+ */
+
+/**
+ * Route action for a gate decision
+ */
+type GateRouteAction = 'continue' | 'fail' | {
+    /** Step ID to restart from (go backward) */
+    restartFrom: string;
+    /** Additional context to pass (merged into trigger.payload) */
+    context?: Record<string, unknown>;
+} | {
+    /** Step ID to skip forward to — all steps between gate and target are marked skipped */
+    skipTo: string;
+};
+/**
+ * Input for builtin:gate step (spec.with)
+ */
+interface GateInput {
+    /** Expression path to the decision value (e.g. "steps.review.outputs.passed") */
+    decision: string;
+    /** Route map: decision value → action */
+    routes: Record<string, GateRouteAction>;
+    /** Default action if decision value doesn't match any route */
+    default?: 'continue' | 'fail';
+    /** Maximum number of restart iterations before failing (default: 3) */
+    maxIterations?: number;
+}
+/**
+ * Output produced by a resolved gate step
+ */
+interface GateOutput {
+    /** The decision value that was evaluated */
+    decisionValue: unknown;
+    /** The action that was taken */
+    action: 'continue' | 'fail' | 'restart' | 'skip';
+    /** Step ID that was restarted from (if restart) */
+    restartFrom?: string;
+    /** Step ID that was skipped to (if skip) */
+    skipTo?: string;
+    /** Current iteration count */
+    iteration: number;
+    /** Set to true when the gate exhausted its maxIterations budget */
+    maxIterationsReached?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Pure decision result from GateHandler.
+ * Worker applies the state mutations based on the action.
+ */
+type GateDecision = {
+    action: 'continue';
+    outputs: GateOutput;
+} | {
+    action: 'fail';
+    error: Error;
+    outputs: GateOutput;
+} | {
+    action: 'restart';
+    restartFrom: string;
+    context?: Record<string, unknown>;
+    outputs: GateOutput;
+    nextIteration: number;
+} | {
+    action: 'skip';
+    skipTo: string;
+    outputs: GateOutput;
+};
+/**
+ * GateHandler — pure decision function.
+ * No I/O, no state mutations. Worker owns the side effects.
+ */
+declare class GateHandler {
+    static readonly uses = "builtin:gate";
+    /**
+     * @param validRestartTargets Identifiers the worker can reset on restart —
+     *   step ids/spec.ids within the gate's own job AND other job names (for
+     *   cross-job restart). When provided and `restartFrom` matches none of them,
+     *   the gate FAILS instead of attempting a restart the worker cannot apply —
+     *   which would otherwise silently degrade into "complete the gate and
+     *   proceed" (a false green).
+     */
+    handle(input: GateInput, exprCtx: ExpressionContext, currentIteration: number, validRestartTargets?: string[]): GateDecision;
+}
+
+export { type GateDecision, GateHandler, type GateInput, type GateOutput, type GateRouteAction };

package/dist/gate.js

@@ -0,0 +1,95 @@
+import { resolveValue } from '@kb-labs/workflow-contracts';
+
+// src/gate.ts
+var GateHandler = class {
+  static uses = "builtin:gate";
+  /**
+   * @param validRestartTargets Identifiers the worker can reset on restart —
+   *   step ids/spec.ids within the gate's own job AND other job names (for
+   *   cross-job restart). When provided and `restartFrom` matches none of them,
+   *   the gate FAILS instead of attempting a restart the worker cannot apply —
+   *   which would otherwise silently degrade into "complete the gate and
+   *   proceed" (a false green).
+   */
+  handle(input, exprCtx, currentIteration, validRestartTargets) {
+    const maxIterations = input.maxIterations ?? 3;
+    const decisionValue = resolveValue(input.decision, exprCtx);
+    const decisionKey = String(decisionValue);
+    const route = input.routes[decisionKey] ?? input.routes[decisionValue];
+    const action = route ?? input.default ?? "fail";
+    if (action === "continue") {
+      return {
+        action: "continue",
+        outputs: { decisionValue, action: "continue", iteration: currentIteration }
+      };
+    }
+    if (action === "fail") {
+      const failReason = route?.message ?? `No matching route for value "${decisionKey}"`;
+      return {
+        action: "fail",
+        error: new Error(`Gate failed: ${failReason}`),
+        outputs: { decisionValue, action: "fail", iteration: currentIteration }
+      };
+    }
+    if (typeof action === "object" && "skipTo" in action) {
+      if (validRestartTargets && !validRestartTargets.includes(action.skipTo)) {
+        return {
+          action: "fail",
+          error: new Error(
+            `Gate skipTo "${action.skipTo}" matches no step in this job \u2014 cannot skip.`
+          ),
+          outputs: { decisionValue, action: "fail", iteration: currentIteration }
+        };
+      }
+      return {
+        action: "skip",
+        skipTo: action.skipTo,
+        outputs: {
+          decisionValue,
+          action: "skip",
+          skipTo: action.skipTo,
+          iteration: currentIteration
+        }
+      };
+    }
+    const restartAction = action;
+    if (validRestartTargets && !validRestartTargets.includes(restartAction.restartFrom)) {
+      return {
+        action: "fail",
+        error: new Error(
+          `Gate restartFrom "${restartAction.restartFrom}" matches no step in this job or any job in the run \u2014 cannot restart. Failing instead of silently passing.`
+        ),
+        outputs: { decisionValue, action: "fail", iteration: currentIteration }
+      };
+    }
+    const nextIteration = currentIteration + 1;
+    if (nextIteration >= maxIterations) {
+      return {
+        action: "fail",
+        error: new Error(`Gate max iterations reached (${maxIterations}) for step`),
+        outputs: {
+          decisionValue,
+          action: "fail",
+          iteration: currentIteration,
+          maxIterationsReached: true
+        }
+      };
+    }
+    return {
+      action: "restart",
+      restartFrom: restartAction.restartFrom,
+      context: restartAction.context,
+      outputs: {
+        decisionValue,
+        action: "restart",
+        restartFrom: restartAction.restartFrom,
+        iteration: nextIteration
+      },
+      nextIteration
+    };
+  }
+};
+
+export { GateHandler };
+//# sourceMappingURL=gate.js.map
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/gate.ts"],"names":[],"mappings":"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","file":"gate.js","sourcesContent":["/**\n * @module @kb-labs/workflow-steps/gate\n * Types and handler for builtin:gate step\n *\n * Gate steps act as automatic routers — they read a decision value\n * from previous step outputs and route the pipeline accordingly:\n * - continue: proceed to next step\n * - fail: fail the pipeline\n * - restart: reset steps back to target and re-schedule with context\n * - skip: mark intermediate steps as skipped and jump forward to a target step\n */\n\nimport { resolveValue, type ExpressionContext } from '@kb-labs/workflow-contracts';\n\n/**\n * Route action for a gate decision\n */\nexport type GateRouteAction =\n  | 'continue'\n  | 'fail'\n  | {\n      /** Step ID to restart from (go backward) */\n      restartFrom: string;\n      /** Additional context to pass (merged into trigger.payload) */\n      context?: Record<string, unknown>;\n    }\n  | {\n      /** Step ID to skip forward to — all steps between gate and target are marked skipped */\n      skipTo: string;\n    };\n\n/**\n * Input for builtin:gate step (spec.with)\n */\nexport interface GateInput {\n  /** Expression path to the decision value (e.g. \"steps.review.outputs.passed\") */\n  decision: string;\n\n  /** Route map: decision value → action */\n  routes: Record<string, GateRouteAction>;\n\n  /** Default action if decision value doesn't match any route */\n  default?: 'continue' | 'fail';\n\n  /** Maximum number of restart iterations before failing (default: 3) */\n  maxIterations?: number;\n}\n\n/**\n * Output produced by a resolved gate step\n */\nexport interface GateOutput {\n  /** The decision value that was evaluated */\n  decisionValue: unknown;\n\n  /** The action that was taken */\n  action: 'continue' | 'fail' | 'restart' | 'skip';\n\n  /** Step ID that was restarted from (if restart) */\n  restartFrom?: string;\n\n  /** Step ID that was skipped to (if skip) */\n  skipTo?: string;\n\n  /** Current iteration count */\n  iteration: number;\n\n  /** Set to true when the gate exhausted its maxIterations budget */\n  maxIterationsReached?: boolean;\n\n  [key: string]: unknown;\n}\n\n/**\n * Pure decision result from GateHandler.\n * Worker applies the state mutations based on the action.\n */\nexport type GateDecision =\n  | { action: 'continue'; outputs: GateOutput }\n  | { action: 'fail'; error: Error; outputs: GateOutput }\n  | {\n      action: 'restart';\n      restartFrom: string;\n      context?: Record<string, unknown>;\n      outputs: GateOutput;\n      nextIteration: number;\n    }\n  | {\n      action: 'skip';\n      skipTo: string;\n      outputs: GateOutput;\n    };\n\n/**\n * GateHandler — pure decision function.\n * No I/O, no state mutations. Worker owns the side effects.\n */\nexport class GateHandler {\n  static readonly uses = 'builtin:gate';\n\n  /**\n   * @param validRestartTargets Identifiers the worker can reset on restart —\n   *   step ids/spec.ids within the gate's own job AND other job names (for\n   *   cross-job restart). When provided and `restartFrom` matches none of them,\n   *   the gate FAILS instead of attempting a restart the worker cannot apply —\n   *   which would otherwise silently degrade into \"complete the gate and\n   *   proceed\" (a false green).\n   */\n  handle(\n    input: GateInput,\n    exprCtx: ExpressionContext,\n    currentIteration: number,\n    validRestartTargets?: string[],\n  ): GateDecision {\n    const maxIterations = input.maxIterations ?? 3;\n    const decisionValue = resolveValue(input.decision, exprCtx);\n    const decisionKey = String(decisionValue);\n\n    const route: GateRouteAction | undefined =\n      input.routes[decisionKey] ?? input.routes[decisionValue as string];\n    const action = route ?? input.default ?? 'fail';\n\n    if (action === 'continue') {\n      return {\n        action: 'continue',\n        outputs: { decisionValue, action: 'continue', iteration: currentIteration },\n      };\n    }\n\n    if (action === 'fail') {\n      const failReason =\n        (route as { message?: string } | undefined)?.message ??\n        `No matching route for value \"${decisionKey}\"`;\n      return {\n        action: 'fail',\n        error: new Error(`Gate failed: ${failReason}`),\n        outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n      };\n    }\n\n    // skipTo action — jump forward, marking intermediate steps as skipped\n    if (typeof action === 'object' && 'skipTo' in action) {\n      if (validRestartTargets && !validRestartTargets.includes(action.skipTo)) {\n        return {\n          action: 'fail',\n          error: new Error(\n            `Gate skipTo \"${action.skipTo}\" matches no step in this job — cannot skip.`,\n          ),\n          outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n        };\n      }\n      return {\n        action: 'skip',\n        skipTo: action.skipTo,\n        outputs: {\n          decisionValue,\n          action: 'skip',\n          skipTo: action.skipTo,\n          iteration: currentIteration,\n        },\n      };\n    }\n\n    // restart action\n    const restartAction = action as { restartFrom: string; context?: Record<string, unknown> };\n\n    // Guard: restartFrom must name something the worker can reset — a step in\n    // this job or another job by name. If it matches neither, the gate cannot\n    // recover; fail honestly rather than let the worker silently complete the\n    // gate and proceed (which would ship unverified work as a false green).\n    if (validRestartTargets && !validRestartTargets.includes(restartAction.restartFrom)) {\n      return {\n        action: 'fail',\n        error: new Error(\n          `Gate restartFrom \"${restartAction.restartFrom}\" matches no step in this job ` +\n            `or any job in the run — cannot restart. Failing instead of silently passing.`,\n        ),\n        outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n      };\n    }\n\n    const nextIteration = currentIteration + 1;\n\n    if (nextIteration >= maxIterations) {\n      return {\n        action: 'fail',\n        error: new Error(`Gate max iterations reached (${maxIterations}) for step`),\n        outputs: {\n          decisionValue,\n          action: 'fail',\n          iteration: currentIteration,\n          maxIterationsReached: true,\n        },\n      };\n    }\n\n    return {\n      action: 'restart',\n      restartFrom: restartAction.restartFrom,\n      context: restartAction.context,\n      outputs: {\n        decisionValue,\n        action: 'restart',\n        restartFrom: restartAction.restartFrom,\n        iteration: nextIteration,\n      },\n      nextIteration,\n    };\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ShellInput, ShellOutput, default as shell } from './shell.js';
+export { ApprovalHandler, ApprovalInput, ApprovalOutput } from './approval.js';
+export { GateDecision, GateHandler, GateInput, GateOutput, GateRouteAction } from './gate.js';
+import '@kb-labs/plugin-contracts';
+import '@kb-labs/workflow-contracts';

package/dist/index.js

@@ -0,0 +1,323 @@
+import { execaCommand } from 'execa';
+import { resolveValue } from '@kb-labs/workflow-contracts';
+
+// src/shell.ts
+var BLOCKED_COMMANDS = [
+  "rm -rf /",
+  "rm -rf /*",
+  "mkfs",
+  "dd if=",
+  ":(){:|:&};:",
+  // Fork bomb
+  "chmod -R 777 /",
+  "chown -R",
+  "> /dev/sda",
+  "mv /* ",
+  "fdisk"
+];
+var OUTPUT_MARKER = "::kb-output::";
+var OUTPUT_MARKER_B64 = "::kb-output:base64::";
+function parseOutputMarkerLine(line) {
+  const b64Idx = line.indexOf(OUTPUT_MARKER_B64);
+  if (b64Idx !== -1) {
+    const raw = line.slice(b64Idx + OUTPUT_MARKER_B64.length).trim();
+    let decoded;
+    try {
+      decoded = Buffer.from(raw, "base64").toString("utf8");
+    } catch {
+      throw new Error(`::kb-output:base64:: payload is not valid base64`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(decoded);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`::kb-output:base64:: malformed JSON payload after decode: ${detail}`);
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error(`::kb-output:base64:: JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+  }
+  const idx = line.indexOf(OUTPUT_MARKER);
+  if (idx !== -1) {
+    const raw = line.slice(idx + OUTPUT_MARKER.length);
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`::kb-output:: malformed JSON payload: ${detail}`);
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error(`::kb-output:: JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+  }
+  return null;
+}
+function mergeJsonOutputs(output, warn) {
+  const base = { ...output };
+  const trimmed = output.stdout.trim();
+  if (!trimmed) {
+    return base;
+  }
+  const lines = output.stdout.split("\n");
+  let foundMarker = false;
+  for (const line of lines) {
+    if (!line.includes("::kb-output")) {
+      continue;
+    }
+    foundMarker = true;
+    try {
+      const parsed = parseOutputMarkerLine(line);
+      if (parsed) {
+        Object.assign(base, parsed);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warn?.(`Malformed ::kb-output:: marker (outputs not populated): ${msg}`);
+    }
+  }
+  if (foundMarker) {
+    return base;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      Object.assign(base, parsed);
+    }
+  } catch {
+  }
+  return base;
+}
+async function shellHandler(ctx, input) {
+  const { command, env = {}, timeout = 3e5, throwOnError = false } = input;
+  const normalizedCommand = command.toLowerCase().trim();
+  for (const blocked of BLOCKED_COMMANDS) {
+    if (normalizedCommand.includes(blocked.toLowerCase())) {
+      throw new Error(
+        `Dangerous command blocked: "${blocked}". Command attempted: ${command.slice(0, 100)}`
+      );
+    }
+  }
+  const cwd = ctx.cwd;
+  const mergedEnv = {
+    ...process.env,
+    ...env
+  };
+  ctx.platform.logger.info("Executing shell command", {
+    command: command.slice(0, 200),
+    cwd,
+    timeout
+  });
+  try {
+    const proc = execaCommand(command, {
+      cwd,
+      env: mergedEnv,
+      shell: true,
+      stdio: "pipe",
+      reject: false,
+      // We handle exit codes ourselves
+      detached: true
+    });
+    let lineNo = 0;
+    let stdoutBuf = "";
+    let stderrBuf = "";
+    let stdoutFull = "";
+    let stderrFull = "";
+    const emitLine = (stream, line) => {
+      lineNo++;
+      void ctx.api.events.emit("log.line", { stream, line, lineNo, level: stream === "stderr" ? "error" : "info" });
+    };
+    proc.stdout?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdoutFull += text;
+      stdoutBuf += text;
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) {
+        emitLine("stdout", line);
+      }
+    });
+    proc.stderr?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrFull += text;
+      stderrBuf += text;
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) {
+        emitLine("stderr", line);
+      }
+    });
+    let timedOut = false;
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      const pid = proc.pid;
+      if (pid !== void 0) {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {
+        }
+      }
+    }, timeout);
+    const result = await proc;
+    clearTimeout(killTimer);
+    if (stdoutBuf) {
+      emitLine("stdout", stdoutBuf);
+    }
+    if (stderrBuf) {
+      emitLine("stderr", stderrBuf);
+    }
+    if (timedOut) {
+      throw new Error(`Shell command timed out after ${timeout}ms`);
+    }
+    const output = {
+      // Use our accumulated buffers — result.stdout/stderr are empty because
+      // we consumed the streams via 'data' listeners above.
+      stdout: stdoutFull || result.stdout,
+      stderr: stderrFull || result.stderr,
+      exitCode: result.exitCode ?? 0,
+      ok: (result.exitCode ?? 0) === 0
+    };
+    if (output.ok) {
+      ctx.platform.logger.info("Shell command completed successfully", {
+        exitCode: output.exitCode,
+        stdoutLines: output.stdout.split("\n").length
+      });
+    } else {
+      ctx.platform.logger.warn("Shell command failed", {
+        exitCode: output.exitCode,
+        stderrLines: output.stderr.split("\n").length
+      });
+      if (throwOnError) {
+        throw new Error(`Shell command failed with exit code ${output.exitCode}: ${output.stderr.slice(0, 500)}`);
+      }
+    }
+    return mergeJsonOutputs(output, (msg) => ctx.platform.logger.warn(`[shell] ${msg}`));
+  } catch (error) {
+    if (error && typeof error === "object" && "timedOut" in error && error.timedOut) {
+      throw new Error(`Shell command timed out after ${timeout}ms`);
+    }
+    if (error && typeof error === "object" && "exitCode" in error) {
+      const execError = error;
+      const output = {
+        stdout: execError.stdout ?? "",
+        stderr: execError.stderr ?? "",
+        exitCode: execError.exitCode ?? 1,
+        ok: false
+      };
+      ctx.platform.logger.error("Shell command execution failed", void 0, {
+        exitCode: output.exitCode,
+        stderr: output.stderr.slice(0, 500)
+      });
+      if (!throwOnError) {
+        return { ...output };
+      }
+    }
+    throw error;
+  }
+}
+var shell_default = {
+  execute: shellHandler
+};
+
+// src/approval.ts
+var ApprovalHandler = class {
+  static uses = "builtin:approval";
+  handle(_input) {
+    return { status: "waiting", reason: "approval" };
+  }
+};
+var GateHandler = class {
+  static uses = "builtin:gate";
+  /**
+   * @param validRestartTargets Identifiers the worker can reset on restart —
+   *   step ids/spec.ids within the gate's own job AND other job names (for
+   *   cross-job restart). When provided and `restartFrom` matches none of them,
+   *   the gate FAILS instead of attempting a restart the worker cannot apply —
+   *   which would otherwise silently degrade into "complete the gate and
+   *   proceed" (a false green).
+   */
+  handle(input, exprCtx, currentIteration, validRestartTargets) {
+    const maxIterations = input.maxIterations ?? 3;
+    const decisionValue = resolveValue(input.decision, exprCtx);
+    const decisionKey = String(decisionValue);
+    const route = input.routes[decisionKey] ?? input.routes[decisionValue];
+    const action = route ?? input.default ?? "fail";
+    if (action === "continue") {
+      return {
+        action: "continue",
+        outputs: { decisionValue, action: "continue", iteration: currentIteration }
+      };
+    }
+    if (action === "fail") {
+      const failReason = route?.message ?? `No matching route for value "${decisionKey}"`;
+      return {
+        action: "fail",
+        error: new Error(`Gate failed: ${failReason}`),
+        outputs: { decisionValue, action: "fail", iteration: currentIteration }
+      };
+    }
+    if (typeof action === "object" && "skipTo" in action) {
+      if (validRestartTargets && !validRestartTargets.includes(action.skipTo)) {
+        return {
+          action: "fail",
+          error: new Error(
+            `Gate skipTo "${action.skipTo}" matches no step in this job \u2014 cannot skip.`
+          ),
+          outputs: { decisionValue, action: "fail", iteration: currentIteration }
+        };
+      }
+      return {
+        action: "skip",
+        skipTo: action.skipTo,
+        outputs: {
+          decisionValue,
+          action: "skip",
+          skipTo: action.skipTo,
+          iteration: currentIteration
+        }
+      };
+    }
+    const restartAction = action;
+    if (validRestartTargets && !validRestartTargets.includes(restartAction.restartFrom)) {
+      return {
+        action: "fail",
+        error: new Error(
+          `Gate restartFrom "${restartAction.restartFrom}" matches no step in this job or any job in the run \u2014 cannot restart. Failing instead of silently passing.`
+        ),
+        outputs: { decisionValue, action: "fail", iteration: currentIteration }
+      };
+    }
+    const nextIteration = currentIteration + 1;
+    if (nextIteration >= maxIterations) {
+      return {
+        action: "fail",
+        error: new Error(`Gate max iterations reached (${maxIterations}) for step`),
+        outputs: {
+          decisionValue,
+          action: "fail",
+          iteration: currentIteration,
+          maxIterationsReached: true
+        }
+      };
+    }
+    return {
+      action: "restart",
+      restartFrom: restartAction.restartFrom,
+      context: restartAction.context,
+      outputs: {
+        decisionValue,
+        action: "restart",
+        restartFrom: restartAction.restartFrom,
+        iteration: nextIteration
+      },
+      nextIteration
+    };
+  }
+};
+
+export { ApprovalHandler, GateHandler, shell_default as shell };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shell.ts","../src/approval.ts","../src/gate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/workflow-runtime/builtin-handlers/shell\n * Built-in shell execution handler for workflows\n *\n * Security features:\n * - Blocks dangerous commands (rm -rf /, fork bombs, etc.)\n * - Timeout enforcement (default 5 minutes)\n * - Environment variable isolation\n * - Working directory restrictions\n */\n\nimport { execaCommand } from 'execa';\nimport type { PluginContextV3 } from '@kb-labs/plugin-contracts';\n\n/**\n * Commands that are always blocked (dangerous)\n */\nconst BLOCKED_COMMANDS = [\n  'rm -rf /',\n  'rm -rf /*',\n  'mkfs',\n  'dd if=',\n  ':(){:|:&};:', // Fork bomb\n  'chmod -R 777 /',\n  'chown -R',\n  '> /dev/sda',\n  'mv /* ',\n  'fdisk',\n];\n\n/**\n * Split string into chunks of specified size\n */\nfunction chunkString(str: string, chunkSize: number): string[] {\n  const chunks: string[] = [];\n  for (let i = 0; i < str.length; i += chunkSize) {\n    chunks.push(str.slice(i, i + chunkSize));\n  }\n  return chunks;\n}\n\n/**\n * Shell handler input\n */\nexport interface ShellInput {\n  /** Command to execute */\n  command: string;\n\n  /** Additional environment variables */\n  env?: Record<string, string>;\n\n  /** Timeout in milliseconds (default: 300000 = 5 min) */\n  timeout?: number;\n\n  /** Throw on non-zero exit code (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Shell handler output\n */\nexport interface ShellOutput {\n  /** Standard output */\n  stdout: string;\n\n  /** Standard error */\n  stderr: string;\n\n  /** Exit code */\n  exitCode: number;\n\n  /** Whether command succeeded (exitCode === 0) */\n  ok: boolean;\n}\n\n/**\n * Plain-JSON output marker.\n *   echo '::kb-output::{\"passed\":true}'\n *\n * Only safe for values without embedded newlines, quotes, or control chars.\n * For multi-line text, binary data, or any value produced by a sub-command,\n * prefer the base64 variant below.\n */\nconst OUTPUT_MARKER = '::kb-output::';\n\n/**\n * Base64-encoded JSON output marker — JSON-safe for any payload.\n *\n * Usage (shell):\n *   PAYLOAD=$(jq -cn --arg plan \"$(cat /tmp/plan.md)\" '{plan: $plan}' | base64 -w0)\n *   echo \"::kb-output:base64::${PAYLOAD}\"\n *\n * This handles multi-line text, special chars, and any binary-safe content.\n * The base64 string is decoded and JSON-parsed by the runtime.\n */\nconst OUTPUT_MARKER_B64 = '::kb-output:base64::';\n\n/**\n * Parse a single ::kb-output:: or ::kb-output:base64:: marker line into key-value pairs.\n *\n * Returns the parsed object, or null if the line is not a recognized marker.\n * Throws a descriptive error if the marker payload is malformed so callers can warn.\n */\nexport function parseOutputMarkerLine(line: string): Record<string, unknown> | null {\n  // Base64-encoded variant — JSON-safe for any payload\n  const b64Idx = line.indexOf(OUTPUT_MARKER_B64);\n  if (b64Idx !== -1) {\n    const raw = line.slice(b64Idx + OUTPUT_MARKER_B64.length).trim();\n    let decoded: string;\n    try {\n      decoded = Buffer.from(raw, 'base64').toString('utf8');\n    } catch {\n      throw new Error(`::kb-output:base64:: payload is not valid base64`);\n    }\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(decoded);\n    } catch (err) {\n      const detail = err instanceof Error ? err.message : String(err);\n      throw new Error(`::kb-output:base64:: malformed JSON payload after decode: ${detail}`);\n    }\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    throw new Error(`::kb-output:base64:: JSON must be an object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);\n  }\n\n  // Plain-JSON variant — only safe for simple scalar values\n  const idx = line.indexOf(OUTPUT_MARKER);\n  if (idx !== -1) {\n    const raw = line.slice(idx + OUTPUT_MARKER.length);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch (err) {\n      const detail = err instanceof Error ? err.message : String(err);\n      throw new Error(`::kb-output:: malformed JSON payload: ${detail}`);\n    }\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    throw new Error(`::kb-output:: JSON must be an object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);\n  }\n\n  return null;\n}\n\n/**\n * Extract structured outputs from shell stdout.\n *\n * Priority:\n * 1. ::kb-output:base64:: marker lines — JSON-safe, recommended for complex values\n * 2. ::kb-output:: marker lines — plain JSON, ok for simple scalars\n * 3. Entire stdout as JSON — fallback for backward compat (simple commands)\n *\n * Malformed markers emit a warning instead of silently dropping the output.\n * Logs and other stdout content are ignored for output purposes.\n */\nexport function mergeJsonOutputs(output: ShellOutput, warn?: (msg: string) => void): Record<string, unknown> {\n  const base: Record<string, unknown> = { ...output };\n  const trimmed = output.stdout.trim();\n  if (!trimmed) {return base;}\n\n  // Priority 1 + 2: Look for ::kb-output:: or ::kb-output:base64:: marker lines\n  const lines = output.stdout.split('\\n');\n  let foundMarker = false;\n  for (const line of lines) {\n    if (!line.includes('::kb-output')) {continue;}\n    foundMarker = true;\n    try {\n      const parsed = parseOutputMarkerLine(line);\n      if (parsed) {\n        Object.assign(base, parsed);\n      }\n    } catch (err) {\n      // Malformed marker — warn instead of silently dropping\n      const msg = err instanceof Error ? err.message : String(err);\n      warn?.(`Malformed ::kb-output:: marker (outputs not populated): ${msg}`);\n    }\n  }\n\n  if (foundMarker) {return base;}\n\n  // Priority 3: Fallback — entire stdout as JSON (backward compat)\n  try {\n    const parsed: unknown = JSON.parse(trimmed);\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      Object.assign(base, parsed as Record<string, unknown>);\n    }\n  } catch {\n    // Not JSON — return as-is\n  }\n\n  return base;\n}\n\n/**\n * Built-in shell execution handler.\n *\n * Executes shell commands with safety checks and timeout enforcement.\n *\n * @param ctx - Handler execution context\n * @param input - Shell command input\n * @returns Shell execution result\n * @throws Error if dangerous command detected or timeout exceeded\n */\nasync function shellHandler(\n  ctx: PluginContextV3,\n  input: ShellInput,\n): Promise<Record<string, unknown>> {\n  const { command, env = {}, timeout = 300000, throwOnError = false } = input;\n\n  // Security: Check for dangerous commands\n  const normalizedCommand = command.toLowerCase().trim();\n  for (const blocked of BLOCKED_COMMANDS) {\n    if (normalizedCommand.includes(blocked.toLowerCase())) {\n      throw new Error(\n        `Dangerous command blocked: \"${blocked}\". Command attempted: ${command.slice(0, 100)}`,\n      );\n    }\n  }\n\n  // Get working directory from context (workflow workspace)\n  const cwd = ctx.cwd;\n\n  // Merge environment variables\n  const mergedEnv = {\n    ...process.env,\n    ...env,\n  };\n\n  ctx.platform.logger.info('Executing shell command', {\n    command: command.slice(0, 200),\n    cwd,\n    timeout,\n  });\n\n  try {\n    // detached: true puts the subprocess in its own process group. On timeout we kill\n    // the entire group (process.kill(-pid, 'SIGKILL')), which takes down both the shell\n    // and any children it spawned. Without this, SIGTERM reaches only the shell; child\n    // processes (e.g. `sleep N`) inherit the pipe write-end and block await indefinitely.\n    const proc = execaCommand(command, {\n      cwd,\n      env: mergedEnv,\n      shell: true,\n      stdio: 'pipe',\n      reject: false, // We handle exit codes ourselves\n      detached: true,\n    });\n\n    // Stream stdout/stderr line-by-line in real-time.\n    // We consume the streams ourselves via 'data' events for live log streaming.\n    // Because attaching a 'data' listener drains the stream, execa's result.stdout\n    // will be empty — we must reconstruct the full output from collected chunks.\n    let lineNo = 0;\n    let stdoutBuf = '';\n    let stderrBuf = '';\n    let stdoutFull = '';\n    let stderrFull = '';\n\n    const emitLine = (stream: 'stdout' | 'stderr', line: string) => {\n      lineNo++;\n      void ctx.api.events.emit('log.line', { stream, line, lineNo, level: stream === 'stderr' ? 'error' : 'info' });\n    };\n\n    proc.stdout?.on('data', (chunk: Buffer) => {\n      const text = chunk.toString();\n      stdoutFull += text;\n      stdoutBuf += text;\n      const lines = stdoutBuf.split('\\n');\n      stdoutBuf = lines.pop() ?? '';\n      for (const line of lines) {emitLine('stdout', line);}\n    });\n\n    proc.stderr?.on('data', (chunk: Buffer) => {\n      const text = chunk.toString();\n      stderrFull += text;\n      stderrBuf += text;\n      const lines = stderrBuf.split('\\n');\n      stderrBuf = lines.pop() ?? '';\n      for (const line of lines) {emitLine('stderr', line);}\n    });\n\n    // Self-managed timeout: kill the entire process group so orphaned children\n    // release the pipe write-end and await proc resolves immediately.\n    let timedOut = false;\n    const killTimer = setTimeout(() => {\n      timedOut = true;\n      const pid = proc.pid;\n      if (pid !== undefined) {\n        try {\n          process.kill(-pid, 'SIGKILL');\n        } catch {\n          // process already exited\n        }\n      }\n    }, timeout);\n\n    const result = await proc;\n    clearTimeout(killTimer);\n\n    // Flush remaining buffered content\n    if (stdoutBuf) {emitLine('stdout', stdoutBuf);}\n    if (stderrBuf) {emitLine('stderr', stderrBuf);}\n\n    if (timedOut) {\n      throw new Error(`Shell command timed out after ${timeout}ms`);\n    }\n\n    const output: ShellOutput = {\n      // Use our accumulated buffers — result.stdout/stderr are empty because\n      // we consumed the streams via 'data' listeners above.\n      stdout: stdoutFull || result.stdout,\n      stderr: stderrFull || result.stderr,\n      exitCode: result.exitCode ?? 0,\n      ok: (result.exitCode ?? 0) === 0,\n    };\n\n    if (output.ok) {\n      ctx.platform.logger.info('Shell command completed successfully', {\n        exitCode: output.exitCode,\n        stdoutLines: output.stdout.split('\\n').length,\n      });\n    } else {\n      ctx.platform.logger.warn('Shell command failed', {\n        exitCode: output.exitCode,\n        stderrLines: output.stderr.split('\\n').length,\n      });\n\n      if (throwOnError) {\n        throw new Error(`Shell command failed with exit code ${output.exitCode}: ${output.stderr.slice(0, 500)}`);\n      }\n    }\n\n    return mergeJsonOutputs(output, (msg) => ctx.platform.logger.warn(`[shell] ${msg}`));\n  } catch (error) {\n    // Handle timeout\n    if (error && typeof error === 'object' && 'timedOut' in error && error.timedOut) {\n      throw new Error(`Shell command timed out after ${timeout}ms`);\n    }\n\n    // Handle execution error\n    if (error && typeof error === 'object' && 'exitCode' in error) {\n      const execError = error as { exitCode?: number; stdout?: string; stderr?: string };\n      const output: ShellOutput = {\n        stdout: execError.stdout ?? '',\n        stderr: execError.stderr ?? '',\n        exitCode: execError.exitCode ?? 1,\n        ok: false,\n      };\n\n      ctx.platform.logger.error('Shell command execution failed', undefined, {\n        exitCode: output.exitCode,\n        stderr: output.stderr.slice(0, 500),\n      });\n\n      if (!throwOnError) {\n        return { ...output };\n      }\n    }\n\n    throw error;\n  }\n}\n\n// Export handler in format expected by ExecutionBackend\nexport default {\n  execute: shellHandler,\n};\n","/**\n * @module @kb-labs/workflow-steps/approval\n * Types and handler for builtin:approval step\n *\n * Approval steps pause the pipeline and wait for human decision.\n * The worker handles polling; resolveApproval() on the engine resumes execution.\n */\n\n/**\n * Input for builtin:approval step (spec.with)\n */\nexport interface ApprovalInput {\n  /** Display title for the approval request */\n  title: string;\n\n  /** Contextual data shown to the approver (already interpolated) */\n  context?: Record<string, unknown>;\n\n  /** Optional instructions for the approver */\n  instructions?: string;\n}\n\n/**\n * Output produced by a resolved approval step\n */\nexport interface ApprovalOutput {\n  /** Whether the approval was granted */\n  approved: boolean;\n\n  /** Action taken: \"approve\" or \"reject\" */\n  action: 'approve' | 'reject';\n\n  /** Optional comment from the approver */\n  comment?: string;\n\n  /** Additional data provided by the approver */\n  [key: string]: unknown;\n}\n\n/**\n * ApprovalHandler — signals the worker to pause and wait for human approval.\n * The worker owns the polling loop; this handler only marks the intent.\n */\nexport class ApprovalHandler {\n  static readonly uses = 'builtin:approval';\n\n  handle(_input: ApprovalInput): { status: 'waiting'; reason: 'approval' } {\n    return { status: 'waiting', reason: 'approval' };\n  }\n}\n","/**\n * @module @kb-labs/workflow-steps/gate\n * Types and handler for builtin:gate step\n *\n * Gate steps act as automatic routers — they read a decision value\n * from previous step outputs and route the pipeline accordingly:\n * - continue: proceed to next step\n * - fail: fail the pipeline\n * - restart: reset steps back to target and re-schedule with context\n * - skip: mark intermediate steps as skipped and jump forward to a target step\n */\n\nimport { resolveValue, type ExpressionContext } from '@kb-labs/workflow-contracts';\n\n/**\n * Route action for a gate decision\n */\nexport type GateRouteAction =\n  | 'continue'\n  | 'fail'\n  | {\n      /** Step ID to restart from (go backward) */\n      restartFrom: string;\n      /** Additional context to pass (merged into trigger.payload) */\n      context?: Record<string, unknown>;\n    }\n  | {\n      /** Step ID to skip forward to — all steps between gate and target are marked skipped */\n      skipTo: string;\n    };\n\n/**\n * Input for builtin:gate step (spec.with)\n */\nexport interface GateInput {\n  /** Expression path to the decision value (e.g. \"steps.review.outputs.passed\") */\n  decision: string;\n\n  /** Route map: decision value → action */\n  routes: Record<string, GateRouteAction>;\n\n  /** Default action if decision value doesn't match any route */\n  default?: 'continue' | 'fail';\n\n  /** Maximum number of restart iterations before failing (default: 3) */\n  maxIterations?: number;\n}\n\n/**\n * Output produced by a resolved gate step\n */\nexport interface GateOutput {\n  /** The decision value that was evaluated */\n  decisionValue: unknown;\n\n  /** The action that was taken */\n  action: 'continue' | 'fail' | 'restart' | 'skip';\n\n  /** Step ID that was restarted from (if restart) */\n  restartFrom?: string;\n\n  /** Step ID that was skipped to (if skip) */\n  skipTo?: string;\n\n  /** Current iteration count */\n  iteration: number;\n\n  /** Set to true when the gate exhausted its maxIterations budget */\n  maxIterationsReached?: boolean;\n\n  [key: string]: unknown;\n}\n\n/**\n * Pure decision result from GateHandler.\n * Worker applies the state mutations based on the action.\n */\nexport type GateDecision =\n  | { action: 'continue'; outputs: GateOutput }\n  | { action: 'fail'; error: Error; outputs: GateOutput }\n  | {\n      action: 'restart';\n      restartFrom: string;\n      context?: Record<string, unknown>;\n      outputs: GateOutput;\n      nextIteration: number;\n    }\n  | {\n      action: 'skip';\n      skipTo: string;\n      outputs: GateOutput;\n    };\n\n/**\n * GateHandler — pure decision function.\n * No I/O, no state mutations. Worker owns the side effects.\n */\nexport class GateHandler {\n  static readonly uses = 'builtin:gate';\n\n  /**\n   * @param validRestartTargets Identifiers the worker can reset on restart —\n   *   step ids/spec.ids within the gate's own job AND other job names (for\n   *   cross-job restart). When provided and `restartFrom` matches none of them,\n   *   the gate FAILS instead of attempting a restart the worker cannot apply —\n   *   which would otherwise silently degrade into \"complete the gate and\n   *   proceed\" (a false green).\n   */\n  handle(\n    input: GateInput,\n    exprCtx: ExpressionContext,\n    currentIteration: number,\n    validRestartTargets?: string[],\n  ): GateDecision {\n    const maxIterations = input.maxIterations ?? 3;\n    const decisionValue = resolveValue(input.decision, exprCtx);\n    const decisionKey = String(decisionValue);\n\n    const route: GateRouteAction | undefined =\n      input.routes[decisionKey] ?? input.routes[decisionValue as string];\n    const action = route ?? input.default ?? 'fail';\n\n    if (action === 'continue') {\n      return {\n        action: 'continue',\n        outputs: { decisionValue, action: 'continue', iteration: currentIteration },\n      };\n    }\n\n    if (action === 'fail') {\n      const failReason =\n        (route as { message?: string } | undefined)?.message ??\n        `No matching route for value \"${decisionKey}\"`;\n      return {\n        action: 'fail',\n        error: new Error(`Gate failed: ${failReason}`),\n        outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n      };\n    }\n\n    // skipTo action — jump forward, marking intermediate steps as skipped\n    if (typeof action === 'object' && 'skipTo' in action) {\n      if (validRestartTargets && !validRestartTargets.includes(action.skipTo)) {\n        return {\n          action: 'fail',\n          error: new Error(\n            `Gate skipTo \"${action.skipTo}\" matches no step in this job — cannot skip.`,\n          ),\n          outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n        };\n      }\n      return {\n        action: 'skip',\n        skipTo: action.skipTo,\n        outputs: {\n          decisionValue,\n          action: 'skip',\n          skipTo: action.skipTo,\n          iteration: currentIteration,\n        },\n      };\n    }\n\n    // restart action\n    const restartAction = action as { restartFrom: string; context?: Record<string, unknown> };\n\n    // Guard: restartFrom must name something the worker can reset — a step in\n    // this job or another job by name. If it matches neither, the gate cannot\n    // recover; fail honestly rather than let the worker silently complete the\n    // gate and proceed (which would ship unverified work as a false green).\n    if (validRestartTargets && !validRestartTargets.includes(restartAction.restartFrom)) {\n      return {\n        action: 'fail',\n        error: new Error(\n          `Gate restartFrom \"${restartAction.restartFrom}\" matches no step in this job ` +\n            `or any job in the run — cannot restart. Failing instead of silently passing.`,\n        ),\n        outputs: { decisionValue, action: 'fail', iteration: currentIteration },\n      };\n    }\n\n    const nextIteration = currentIteration + 1;\n\n    if (nextIteration >= maxIterations) {\n      return {\n        action: 'fail',\n        error: new Error(`Gate max iterations reached (${maxIterations}) for step`),\n        outputs: {\n          decisionValue,\n          action: 'fail',\n          iteration: currentIteration,\n          maxIterationsReached: true,\n        },\n      };\n    }\n\n    return {\n      action: 'restart',\n      restartFrom: restartAction.restartFrom,\n      context: restartAction.context,\n      outputs: {\n        decisionValue,\n        action: 'restart',\n        restartFrom: restartAction.restartFrom,\n        iteration: nextIteration,\n      },\n      nextIteration,\n    };\n  }\n}\n"]}

package/dist/shell.d.ts

@@ -0,0 +1,74 @@
+import { PluginContextV3 } from '@kb-labs/plugin-contracts';
+
+/**
+ * @module @kb-labs/workflow-runtime/builtin-handlers/shell
+ * Built-in shell execution handler for workflows
+ *
+ * Security features:
+ * - Blocks dangerous commands (rm -rf /, fork bombs, etc.)
+ * - Timeout enforcement (default 5 minutes)
+ * - Environment variable isolation
+ * - Working directory restrictions
+ */
+
+/**
+ * Shell handler input
+ */
+interface ShellInput {
+    /** Command to execute */
+    command: string;
+    /** Additional environment variables */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds (default: 300000 = 5 min) */
+    timeout?: number;
+    /** Throw on non-zero exit code (default: false) */
+    throwOnError?: boolean;
+}
+/**
+ * Shell handler output
+ */
+interface ShellOutput {
+    /** Standard output */
+    stdout: string;
+    /** Standard error */
+    stderr: string;
+    /** Exit code */
+    exitCode: number;
+    /** Whether command succeeded (exitCode === 0) */
+    ok: boolean;
+}
+/**
+ * Parse a single ::kb-output:: or ::kb-output:base64:: marker line into key-value pairs.
+ *
+ * Returns the parsed object, or null if the line is not a recognized marker.
+ * Throws a descriptive error if the marker payload is malformed so callers can warn.
+ */
+declare function parseOutputMarkerLine(line: string): Record<string, unknown> | null;
+/**
+ * Extract structured outputs from shell stdout.
+ *
+ * Priority:
+ * 1. ::kb-output:base64:: marker lines — JSON-safe, recommended for complex values
+ * 2. ::kb-output:: marker lines — plain JSON, ok for simple scalars
+ * 3. Entire stdout as JSON — fallback for backward compat (simple commands)
+ *
+ * Malformed markers emit a warning instead of silently dropping the output.
+ * Logs and other stdout content are ignored for output purposes.
+ */
+declare function mergeJsonOutputs(output: ShellOutput, warn?: (msg: string) => void): Record<string, unknown>;
+/**
+ * Built-in shell execution handler.
+ *
+ * Executes shell commands with safety checks and timeout enforcement.
+ *
+ * @param ctx - Handler execution context
+ * @param input - Shell command input
+ * @returns Shell execution result
+ * @throws Error if dangerous command detected or timeout exceeded
+ */
+declare function shellHandler(ctx: PluginContextV3, input: ShellInput): Promise<Record<string, unknown>>;
+declare const _default: {
+    execute: typeof shellHandler;
+};
+
+export { type ShellInput, type ShellOutput, _default as default, mergeJsonOutputs, parseOutputMarkerLine };

package/dist/shell.js

@@ -0,0 +1,226 @@
+import { execaCommand } from 'execa';
+
+// src/shell.ts
+var BLOCKED_COMMANDS = [
+  "rm -rf /",
+  "rm -rf /*",
+  "mkfs",
+  "dd if=",
+  ":(){:|:&};:",
+  // Fork bomb
+  "chmod -R 777 /",
+  "chown -R",
+  "> /dev/sda",
+  "mv /* ",
+  "fdisk"
+];
+var OUTPUT_MARKER = "::kb-output::";
+var OUTPUT_MARKER_B64 = "::kb-output:base64::";
+function parseOutputMarkerLine(line) {
+  const b64Idx = line.indexOf(OUTPUT_MARKER_B64);
+  if (b64Idx !== -1) {
+    const raw = line.slice(b64Idx + OUTPUT_MARKER_B64.length).trim();
+    let decoded;
+    try {
+      decoded = Buffer.from(raw, "base64").toString("utf8");
+    } catch {
+      throw new Error(`::kb-output:base64:: payload is not valid base64`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(decoded);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`::kb-output:base64:: malformed JSON payload after decode: ${detail}`);
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error(`::kb-output:base64:: JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+  }
+  const idx = line.indexOf(OUTPUT_MARKER);
+  if (idx !== -1) {
+    const raw = line.slice(idx + OUTPUT_MARKER.length);
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`::kb-output:: malformed JSON payload: ${detail}`);
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    throw new Error(`::kb-output:: JSON must be an object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`);
+  }
+  return null;
+}
+function mergeJsonOutputs(output, warn) {
+  const base = { ...output };
+  const trimmed = output.stdout.trim();
+  if (!trimmed) {
+    return base;
+  }
+  const lines = output.stdout.split("\n");
+  let foundMarker = false;
+  for (const line of lines) {
+    if (!line.includes("::kb-output")) {
+      continue;
+    }
+    foundMarker = true;
+    try {
+      const parsed = parseOutputMarkerLine(line);
+      if (parsed) {
+        Object.assign(base, parsed);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warn?.(`Malformed ::kb-output:: marker (outputs not populated): ${msg}`);
+    }
+  }
+  if (foundMarker) {
+    return base;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      Object.assign(base, parsed);
+    }
+  } catch {
+  }
+  return base;
+}
+async function shellHandler(ctx, input) {
+  const { command, env = {}, timeout = 3e5, throwOnError = false } = input;
+  const normalizedCommand = command.toLowerCase().trim();
+  for (const blocked of BLOCKED_COMMANDS) {
+    if (normalizedCommand.includes(blocked.toLowerCase())) {
+      throw new Error(
+        `Dangerous command blocked: "${blocked}". Command attempted: ${command.slice(0, 100)}`
+      );
+    }
+  }
+  const cwd = ctx.cwd;
+  const mergedEnv = {
+    ...process.env,
+    ...env
+  };
+  ctx.platform.logger.info("Executing shell command", {
+    command: command.slice(0, 200),
+    cwd,
+    timeout
+  });
+  try {
+    const proc = execaCommand(command, {
+      cwd,
+      env: mergedEnv,
+      shell: true,
+      stdio: "pipe",
+      reject: false,
+      // We handle exit codes ourselves
+      detached: true
+    });
+    let lineNo = 0;
+    let stdoutBuf = "";
+    let stderrBuf = "";
+    let stdoutFull = "";
+    let stderrFull = "";
+    const emitLine = (stream, line) => {
+      lineNo++;
+      void ctx.api.events.emit("log.line", { stream, line, lineNo, level: stream === "stderr" ? "error" : "info" });
+    };
+    proc.stdout?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdoutFull += text;
+      stdoutBuf += text;
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) {
+        emitLine("stdout", line);
+      }
+    });
+    proc.stderr?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrFull += text;
+      stderrBuf += text;
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) {
+        emitLine("stderr", line);
+      }
+    });
+    let timedOut = false;
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      const pid = proc.pid;
+      if (pid !== void 0) {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {
+        }
+      }
+    }, timeout);
+    const result = await proc;
+    clearTimeout(killTimer);
+    if (stdoutBuf) {
+      emitLine("stdout", stdoutBuf);
+    }
+    if (stderrBuf) {
+      emitLine("stderr", stderrBuf);
+    }
+    if (timedOut) {
+      throw new Error(`Shell command timed out after ${timeout}ms`);
+    }
+    const output = {
+      // Use our accumulated buffers — result.stdout/stderr are empty because
+      // we consumed the streams via 'data' listeners above.
+      stdout: stdoutFull || result.stdout,
+      stderr: stderrFull || result.stderr,
+      exitCode: result.exitCode ?? 0,
+      ok: (result.exitCode ?? 0) === 0
+    };
+    if (output.ok) {
+      ctx.platform.logger.info("Shell command completed successfully", {
+        exitCode: output.exitCode,
+        stdoutLines: output.stdout.split("\n").length
+      });
+    } else {
+      ctx.platform.logger.warn("Shell command failed", {
+        exitCode: output.exitCode,
+        stderrLines: output.stderr.split("\n").length
+      });
+      if (throwOnError) {
+        throw new Error(`Shell command failed with exit code ${output.exitCode}: ${output.stderr.slice(0, 500)}`);
+      }
+    }
+    return mergeJsonOutputs(output, (msg) => ctx.platform.logger.warn(`[shell] ${msg}`));
+  } catch (error) {
+    if (error && typeof error === "object" && "timedOut" in error && error.timedOut) {
+      throw new Error(`Shell command timed out after ${timeout}ms`);
+    }
+    if (error && typeof error === "object" && "exitCode" in error) {
+      const execError = error;
+      const output = {
+        stdout: execError.stdout ?? "",
+        stderr: execError.stderr ?? "",
+        exitCode: execError.exitCode ?? 1,
+        ok: false
+      };
+      ctx.platform.logger.error("Shell command execution failed", void 0, {
+        exitCode: output.exitCode,
+        stderr: output.stderr.slice(0, 500)
+      });
+      if (!throwOnError) {
+        return { ...output };
+      }
+    }
+    throw error;
+  }
+}
+var shell_default = {
+  execute: shellHandler
+};
+
+export { shell_default as default, mergeJsonOutputs, parseOutputMarkerLine };
+//# sourceMappingURL=shell.js.map
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shell.ts"],"names":[],"mappings":"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","file":"shell.js","sourcesContent":["/**\n * @module @kb-labs/workflow-runtime/builtin-handlers/shell\n * Built-in shell execution handler for workflows\n *\n * Security features:\n * - Blocks dangerous commands (rm -rf /, fork bombs, etc.)\n * - Timeout enforcement (default 5 minutes)\n * - Environment variable isolation\n * - Working directory restrictions\n */\n\nimport { execaCommand } from 'execa';\nimport type { PluginContextV3 } from '@kb-labs/plugin-contracts';\n\n/**\n * Commands that are always blocked (dangerous)\n */\nconst BLOCKED_COMMANDS = [\n  'rm -rf /',\n  'rm -rf /*',\n  'mkfs',\n  'dd if=',\n  ':(){:|:&};:', // Fork bomb\n  'chmod -R 777 /',\n  'chown -R',\n  '> /dev/sda',\n  'mv /* ',\n  'fdisk',\n];\n\n/**\n * Split string into chunks of specified size\n */\nfunction chunkString(str: string, chunkSize: number): string[] {\n  const chunks: string[] = [];\n  for (let i = 0; i < str.length; i += chunkSize) {\n    chunks.push(str.slice(i, i + chunkSize));\n  }\n  return chunks;\n}\n\n/**\n * Shell handler input\n */\nexport interface ShellInput {\n  /** Command to execute */\n  command: string;\n\n  /** Additional environment variables */\n  env?: Record<string, string>;\n\n  /** Timeout in milliseconds (default: 300000 = 5 min) */\n  timeout?: number;\n\n  /** Throw on non-zero exit code (default: false) */\n  throwOnError?: boolean;\n}\n\n/**\n * Shell handler output\n */\nexport interface ShellOutput {\n  /** Standard output */\n  stdout: string;\n\n  /** Standard error */\n  stderr: string;\n\n  /** Exit code */\n  exitCode: number;\n\n  /** Whether command succeeded (exitCode === 0) */\n  ok: boolean;\n}\n\n/**\n * Plain-JSON output marker.\n *   echo '::kb-output::{\"passed\":true}'\n *\n * Only safe for values without embedded newlines, quotes, or control chars.\n * For multi-line text, binary data, or any value produced by a sub-command,\n * prefer the base64 variant below.\n */\nconst OUTPUT_MARKER = '::kb-output::';\n\n/**\n * Base64-encoded JSON output marker — JSON-safe for any payload.\n *\n * Usage (shell):\n *   PAYLOAD=$(jq -cn --arg plan \"$(cat /tmp/plan.md)\" '{plan: $plan}' | base64 -w0)\n *   echo \"::kb-output:base64::${PAYLOAD}\"\n *\n * This handles multi-line text, special chars, and any binary-safe content.\n * The base64 string is decoded and JSON-parsed by the runtime.\n */\nconst OUTPUT_MARKER_B64 = '::kb-output:base64::';\n\n/**\n * Parse a single ::kb-output:: or ::kb-output:base64:: marker line into key-value pairs.\n *\n * Returns the parsed object, or null if the line is not a recognized marker.\n * Throws a descriptive error if the marker payload is malformed so callers can warn.\n */\nexport function parseOutputMarkerLine(line: string): Record<string, unknown> | null {\n  // Base64-encoded variant — JSON-safe for any payload\n  const b64Idx = line.indexOf(OUTPUT_MARKER_B64);\n  if (b64Idx !== -1) {\n    const raw = line.slice(b64Idx + OUTPUT_MARKER_B64.length).trim();\n    let decoded: string;\n    try {\n      decoded = Buffer.from(raw, 'base64').toString('utf8');\n    } catch {\n      throw new Error(`::kb-output:base64:: payload is not valid base64`);\n    }\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(decoded);\n    } catch (err) {\n      const detail = err instanceof Error ? err.message : String(err);\n      throw new Error(`::kb-output:base64:: malformed JSON payload after decode: ${detail}`);\n    }\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    throw new Error(`::kb-output:base64:: JSON must be an object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);\n  }\n\n  // Plain-JSON variant — only safe for simple scalar values\n  const idx = line.indexOf(OUTPUT_MARKER);\n  if (idx !== -1) {\n    const raw = line.slice(idx + OUTPUT_MARKER.length);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch (err) {\n      const detail = err instanceof Error ? err.message : String(err);\n      throw new Error(`::kb-output:: malformed JSON payload: ${detail}`);\n    }\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    throw new Error(`::kb-output:: JSON must be an object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);\n  }\n\n  return null;\n}\n\n/**\n * Extract structured outputs from shell stdout.\n *\n * Priority:\n * 1. ::kb-output:base64:: marker lines — JSON-safe, recommended for complex values\n * 2. ::kb-output:: marker lines — plain JSON, ok for simple scalars\n * 3. Entire stdout as JSON — fallback for backward compat (simple commands)\n *\n * Malformed markers emit a warning instead of silently dropping the output.\n * Logs and other stdout content are ignored for output purposes.\n */\nexport function mergeJsonOutputs(output: ShellOutput, warn?: (msg: string) => void): Record<string, unknown> {\n  const base: Record<string, unknown> = { ...output };\n  const trimmed = output.stdout.trim();\n  if (!trimmed) {return base;}\n\n  // Priority 1 + 2: Look for ::kb-output:: or ::kb-output:base64:: marker lines\n  const lines = output.stdout.split('\\n');\n  let foundMarker = false;\n  for (const line of lines) {\n    if (!line.includes('::kb-output')) {continue;}\n    foundMarker = true;\n    try {\n      const parsed = parseOutputMarkerLine(line);\n      if (parsed) {\n        Object.assign(base, parsed);\n      }\n    } catch (err) {\n      // Malformed marker — warn instead of silently dropping\n      const msg = err instanceof Error ? err.message : String(err);\n      warn?.(`Malformed ::kb-output:: marker (outputs not populated): ${msg}`);\n    }\n  }\n\n  if (foundMarker) {return base;}\n\n  // Priority 3: Fallback — entire stdout as JSON (backward compat)\n  try {\n    const parsed: unknown = JSON.parse(trimmed);\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      Object.assign(base, parsed as Record<string, unknown>);\n    }\n  } catch {\n    // Not JSON — return as-is\n  }\n\n  return base;\n}\n\n/**\n * Built-in shell execution handler.\n *\n * Executes shell commands with safety checks and timeout enforcement.\n *\n * @param ctx - Handler execution context\n * @param input - Shell command input\n * @returns Shell execution result\n * @throws Error if dangerous command detected or timeout exceeded\n */\nasync function shellHandler(\n  ctx: PluginContextV3,\n  input: ShellInput,\n): Promise<Record<string, unknown>> {\n  const { command, env = {}, timeout = 300000, throwOnError = false } = input;\n\n  // Security: Check for dangerous commands\n  const normalizedCommand = command.toLowerCase().trim();\n  for (const blocked of BLOCKED_COMMANDS) {\n    if (normalizedCommand.includes(blocked.toLowerCase())) {\n      throw new Error(\n        `Dangerous command blocked: \"${blocked}\". Command attempted: ${command.slice(0, 100)}`,\n      );\n    }\n  }\n\n  // Get working directory from context (workflow workspace)\n  const cwd = ctx.cwd;\n\n  // Merge environment variables\n  const mergedEnv = {\n    ...process.env,\n    ...env,\n  };\n\n  ctx.platform.logger.info('Executing shell command', {\n    command: command.slice(0, 200),\n    cwd,\n    timeout,\n  });\n\n  try {\n    // detached: true puts the subprocess in its own process group. On timeout we kill\n    // the entire group (process.kill(-pid, 'SIGKILL')), which takes down both the shell\n    // and any children it spawned. Without this, SIGTERM reaches only the shell; child\n    // processes (e.g. `sleep N`) inherit the pipe write-end and block await indefinitely.\n    const proc = execaCommand(command, {\n      cwd,\n      env: mergedEnv,\n      shell: true,\n      stdio: 'pipe',\n      reject: false, // We handle exit codes ourselves\n      detached: true,\n    });\n\n    // Stream stdout/stderr line-by-line in real-time.\n    // We consume the streams ourselves via 'data' events for live log streaming.\n    // Because attaching a 'data' listener drains the stream, execa's result.stdout\n    // will be empty — we must reconstruct the full output from collected chunks.\n    let lineNo = 0;\n    let stdoutBuf = '';\n    let stderrBuf = '';\n    let stdoutFull = '';\n    let stderrFull = '';\n\n    const emitLine = (stream: 'stdout' | 'stderr', line: string) => {\n      lineNo++;\n      void ctx.api.events.emit('log.line', { stream, line, lineNo, level: stream === 'stderr' ? 'error' : 'info' });\n    };\n\n    proc.stdout?.on('data', (chunk: Buffer) => {\n      const text = chunk.toString();\n      stdoutFull += text;\n      stdoutBuf += text;\n      const lines = stdoutBuf.split('\\n');\n      stdoutBuf = lines.pop() ?? '';\n      for (const line of lines) {emitLine('stdout', line);}\n    });\n\n    proc.stderr?.on('data', (chunk: Buffer) => {\n      const text = chunk.toString();\n      stderrFull += text;\n      stderrBuf += text;\n      const lines = stderrBuf.split('\\n');\n      stderrBuf = lines.pop() ?? '';\n      for (const line of lines) {emitLine('stderr', line);}\n    });\n\n    // Self-managed timeout: kill the entire process group so orphaned children\n    // release the pipe write-end and await proc resolves immediately.\n    let timedOut = false;\n    const killTimer = setTimeout(() => {\n      timedOut = true;\n      const pid = proc.pid;\n      if (pid !== undefined) {\n        try {\n          process.kill(-pid, 'SIGKILL');\n        } catch {\n          // process already exited\n        }\n      }\n    }, timeout);\n\n    const result = await proc;\n    clearTimeout(killTimer);\n\n    // Flush remaining buffered content\n    if (stdoutBuf) {emitLine('stdout', stdoutBuf);}\n    if (stderrBuf) {emitLine('stderr', stderrBuf);}\n\n    if (timedOut) {\n      throw new Error(`Shell command timed out after ${timeout}ms`);\n    }\n\n    const output: ShellOutput = {\n      // Use our accumulated buffers — result.stdout/stderr are empty because\n      // we consumed the streams via 'data' listeners above.\n      stdout: stdoutFull || result.stdout,\n      stderr: stderrFull || result.stderr,\n      exitCode: result.exitCode ?? 0,\n      ok: (result.exitCode ?? 0) === 0,\n    };\n\n    if (output.ok) {\n      ctx.platform.logger.info('Shell command completed successfully', {\n        exitCode: output.exitCode,\n        stdoutLines: output.stdout.split('\\n').length,\n      });\n    } else {\n      ctx.platform.logger.warn('Shell command failed', {\n        exitCode: output.exitCode,\n        stderrLines: output.stderr.split('\\n').length,\n      });\n\n      if (throwOnError) {\n        throw new Error(`Shell command failed with exit code ${output.exitCode}: ${output.stderr.slice(0, 500)}`);\n      }\n    }\n\n    return mergeJsonOutputs(output, (msg) => ctx.platform.logger.warn(`[shell] ${msg}`));\n  } catch (error) {\n    // Handle timeout\n    if (error && typeof error === 'object' && 'timedOut' in error && error.timedOut) {\n      throw new Error(`Shell command timed out after ${timeout}ms`);\n    }\n\n    // Handle execution error\n    if (error && typeof error === 'object' && 'exitCode' in error) {\n      const execError = error as { exitCode?: number; stdout?: string; stderr?: string };\n      const output: ShellOutput = {\n        stdout: execError.stdout ?? '',\n        stderr: execError.stderr ?? '',\n        exitCode: execError.exitCode ?? 1,\n        ok: false,\n      };\n\n      ctx.platform.logger.error('Shell command execution failed', undefined, {\n        exitCode: output.exitCode,\n        stderr: output.stderr.slice(0, 500),\n      });\n\n      if (!throwOnError) {\n        return { ...output };\n      }\n    }\n\n    throw error;\n  }\n}\n\n// Export handler in format expected by ExecutionBackend\nexport default {\n  execute: shellHandler,\n};\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kb-labs/workflow-steps",
+  "description": "Built-in workflow step handlers (shell, approval, gate)",
+  "version": "2.96.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./shell": {
+      "types": "./dist/shell.d.ts",
+      "import": "./dist/shell.js"
+    },
+    "./approval": {
+      "types": "./dist/approval.d.ts",
+      "import": "./dist/approval.js"
+    },
+    "./gate": {
+      "types": "./dist/gate.d.ts",
+      "import": "./dist/gate.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "execa": "^9.5.3",
+    "@kb-labs/plugin-contracts": "2.96.0",
+    "@kb-labs/workflow-contracts": "2.96.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.6",
+    "@kb-labs/devkit": "2.96.0"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsup --config tsup.config.ts",
+    "clean": "rimraf dist",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}