@davidorex/pi-workflows 0.2.0 → 0.3.0

package/src/expression.ts

@@ -1,332 +0,0 @@
-import type { StepResult } from "./types.ts";
-import { formatDuration, formatCost } from "./format.ts";
-
-const EXPR_PATTERN = /\$\{\{\s*(.*?)\s*\}\}/g;
-
-/**
- * Built-in filters for expressions.
- * Applied via pipe syntax: ${{ totalDurationMs | duration }}
- */
-const FILTERS: Record<string, (value: unknown) => unknown> = {
-  duration: (v) => formatDuration(Number(v)),
-  currency: (v) => formatCost(Number(v)),
-  json: (v) => JSON.stringify(v, null, 2),
-  length: (v) => Array.isArray(v) ? v.length : typeof v === "string" ? v.length : 0,
-  keys: (v) => typeof v === "object" && v !== null ? Object.keys(v) : [],
-  filter: (v) => Array.isArray(v) ? v.filter(Boolean) : v,
-};
-
-/** Filter names derived from the FILTERS registry — add a filter above, this updates automatically. */
-export const FILTER_NAMES = Object.keys(FILTERS);
-
-/** Known root-level expression scope keys. */
-export const EXPRESSION_ROOTS = ["input", "steps"] as const;
-
-/**
- * Error class for expression resolution failures.
- * Contains the original expression and a diagnostic reason.
- */
-export class ExpressionError extends Error {
-  readonly expression: string;
-  readonly reason: string;
-
-  constructor(expression: string, reason: string) {
-    super(`Expression error in '\${{ ${expression} }}': ${reason}`);
-    this.name = "ExpressionError";
-    this.expression = expression;
-    this.reason = reason;
-  }
-}
-
-/**
- * Resolve a single expression string (without the ${{ }} delimiters).
- * E.g. "steps.diagnose.output.rootCause" walks scope.steps.diagnose.output.rootCause
- *
- * Supports pipe filters: "totalDurationMs | duration"
- *
- * Scope is Record<string, unknown> — accepts ExpressionScope, CompletionScope, or any object.
- *
- * Throws ExpressionError if any segment of the path is undefined or null,
- * or if a filter name is unknown.
- */
-export function resolveExpression(expr: string, scope: Record<string, unknown>): unknown {
-  // Parse optional filter: "path | filterName"
-  const pipeIdx = expr.indexOf("|");
-  let pathExpr: string;
-  let filterName: string | undefined;
-  if (pipeIdx !== -1) {
-    pathExpr = expr.slice(0, pipeIdx).trim();
-    filterName = expr.slice(pipeIdx + 1).trim();
-  } else {
-    pathExpr = expr;
-  }
-
-  const segments = pathExpr.split(".");
-  let current: unknown = scope;
-  const traversed: string[] = [];
-
-  for (const segment of segments) {
-    // Container is undefined/null — can't traverse further. This is a broken reference.
-    if (current === undefined || current === null) {
-      const reason = buildErrorReason(segments, traversed, scope);
-      throw new ExpressionError(expr, reason);
-    }
-
-    current = (current as Record<string, unknown>)[segment];
-    traversed.push(segment);
-
-    // Property doesn't exist on the container — return undefined (optional field).
-    // But if this is the first segment (root lookup like "steps" or "input"),
-    // or if we're looking up a step name that hasn't executed, that's an error.
-    if (current === undefined) {
-      // Root-level miss (e.g. "typo.something") — always an error
-      if (traversed.length === 1) {
-        const reason = buildErrorReason(segments, traversed, scope);
-        throw new ExpressionError(expr, reason);
-      }
-      // Step reference that doesn't exist (e.g. "steps.nonexistent") — error
-      if (segments[0] === "steps" && traversed.length === 2) {
-        const reason = buildErrorReason(segments, traversed, scope);
-        throw new ExpressionError(expr, reason);
-      }
-      // Otherwise: optional field on an existing object — return undefined
-      return undefined;
-    }
-  }
-
-  // Apply filter if specified
-  if (filterName) {
-    const filterFn = FILTERS[filterName];
-    if (!filterFn) {
-      throw new ExpressionError(expr, `unknown filter '${filterName}'`);
-    }
-    current = filterFn(current);
-  }
-
-  return current;
-}
-
-/**
- * Resolve all ${{ }} expressions in a value.
- *
- * - If `value` is a string containing `${{ expr }}`, resolve the expression.
- * - If `value` is a string that IS entirely `${{ expr }}`, return the resolved value
- *   (preserving its type -- object, array, number, etc.).
- * - If `value` is a string with `${{ expr }}` embedded in other text,
- *   stringify the resolved value and interpolate.
- * - If `value` is an object, recursively resolve all values.
- * - If `value` is an array, recursively resolve all elements.
- * - If `value` is anything else (number, boolean, null), return as-is.
- *
- * Throws ExpressionError if a property path doesn't resolve.
- */
-export function resolveExpressions(value: unknown, scope: Record<string, unknown>): unknown {
-  if (typeof value === "string") {
-    return resolveStringExpressions(value, scope);
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((element) => resolveExpressions(element, scope));
-  }
-
-  if (value !== null && typeof value === "object") {
-    const result: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      result[key] = resolveExpressions(val, scope);
-    }
-    return result;
-  }
-
-  // number, boolean, null, undefined — pass through
-  return value;
-}
-
-/**
- * Resolve expressions within a string value.
- * Handles whole-value expressions (type-preserving) and embedded expressions (string interpolation).
- */
-function resolveStringExpressions(value: string, scope: Record<string, unknown>): unknown {
-  // Check if the entire string is a single whole-value expression
-  const wholeMatch = value.match(/^\$\{\{\s*(.*?)\s*\}\}$/);
-  if (wholeMatch) {
-    return resolveExpression(wholeMatch[1], scope);
-  }
-
-  // Check if there are any expressions at all
-  if (!value.includes("${{")) {
-    return value;
-  }
-
-  // Embedded expressions: resolve each and interpolate as strings
-  return value.replace(EXPR_PATTERN, (_match, expr: string) => {
-    const resolved = resolveExpression(expr, scope);
-    if (resolved === undefined || resolved === null) return "";
-    return stringify(resolved);
-  });
-}
-
-/**
- * Comparison operators, ordered from longest to shortest.
- * Order matters: the first-match scan in evaluateCondition must try
- * longer operators before shorter ones to avoid matching "!=" when
- * the actual operator is "!==" (or "==" when "===" is intended).
- */
-const COMPARISON_OPS = ["!==", "===", "!=", "==", ">=", "<=", ">", "<"] as const;
-type ComparisonOp = typeof COMPARISON_OPS[number];
-
-/**
- * Parse a right-hand operand string into a typed value.
- * Supports: string literals ('value' or "value"), number literals, boolean literals (true/false),
- * null, undefined, or expression paths resolved against scope.
- */
-export function parseRightOperand(str: string, scope: Record<string, unknown>): unknown {
-  // String literals (single or double quoted)
-  if ((str.startsWith("'") && str.endsWith("'")) || (str.startsWith('"') && str.endsWith('"'))) {
-    return str.slice(1, -1);
-  }
-
-  // Boolean literals
-  if (str === "true") return true;
-  if (str === "false") return false;
-
-  // null / undefined
-  if (str === "null") return null;
-  if (str === "undefined") return undefined;
-
-  // Number literals
-  const num = Number(str);
-  if (!Number.isNaN(num) && str !== "") return num;
-
-  // Otherwise treat as expression path
-  return resolveExpression(str, scope);
-}
-
-/**
- * Compare two values using a comparison operator.
- * == and === both use strict equality (===).
- */
-export function compare(left: unknown, right: unknown, op: string): boolean {
-  switch (op) {
-    case "==":
-    case "===":
-      return left === right;
-    case "!=":
-    case "!==":
-      return left !== right;
-    case ">":
-      return (left as number) > (right as number);
-    case "<":
-      return (left as number) < (right as number);
-    case ">=":
-      return (left as number) >= (right as number);
-    case "<=":
-      return (left as number) <= (right as number);
-    default:
-      throw new ExpressionError(op, `unknown comparison operator '${op}'`);
-  }
-}
-
-/**
- * Evaluate a condition expression for boolean truthiness.
- *
- * Supports:
- * - Simple path expressions: truthy/falsy evaluation of the resolved value
- * - Negation with ! prefix
- * - Comparison operators: ==, !=, ===, !==, >, <, >=, <=
- * - Right operands: string literals, number literals, boolean literals, null, undefined, or expression paths
- *
- * JS truthiness rules: undefined, null, false, 0, "" are falsy; everything else is truthy.
- */
-export function evaluateCondition(expr: string, scope: Record<string, unknown>): boolean {
-  const trimmed = expr.trim();
-
-  // Check for comparison operators (split on first occurrence)
-  for (const op of COMPARISON_OPS) {
-    const opIdx = trimmed.indexOf(op);
-    if (opIdx !== -1) {
-      const leftExpr = trimmed.slice(0, opIdx).trim();
-      const rightStr = trimmed.slice(opIdx + op.length).trim();
-
-      // Resolve left side
-      let leftValue: unknown;
-      if (leftExpr.startsWith("!")) {
-        leftValue = !resolveExpressionSafe(leftExpr.slice(1).trim(), scope);
-      } else {
-        leftValue = resolveExpressionSafe(leftExpr, scope);
-      }
-
-      const rightValue = parseRightOperand(rightStr, scope);
-      return compare(leftValue, rightValue, op);
-    }
-  }
-
-  // No comparison operator — evaluate as truthy/falsy
-  if (trimmed.startsWith("!")) {
-    const innerExpr = trimmed.slice(1).trim();
-    const value = resolveExpressionSafe(innerExpr, scope);
-    return !value;
-  }
-
-  const value = resolveExpressionSafe(trimmed, scope);
-  return !!value;
-}
-
-/**
- * Resolve an expression, returning undefined for missing optional fields
- * instead of throwing. Root-level misses and missing step references still throw.
- */
-function resolveExpressionSafe(expr: string, scope: Record<string, unknown>): unknown {
-  return resolveExpression(expr, scope);
-}
-
-/**
- * Stringify a resolved value for embedding in a larger string.
- * Objects and arrays use JSON.stringify; primitives use String().
- */
-function stringify(value: unknown): string {
-  if (value !== null && typeof value === "object") {
-    return JSON.stringify(value);
-  }
-  return String(value);
-}
-
-/**
- * Build a diagnostic error reason based on the path traversal state.
- * Provides context about step status when the path starts with "steps.".
- */
-function buildErrorReason(
-  segments: string[],
-  traversed: string[],
-  scope: Record<string, unknown>,
-): string {
-  const failedSegment = traversed[traversed.length - 1];
-  const parentPath = traversed.slice(0, -1).join(".");
-
-  // Special case: referencing a step that doesn't exist in scope.steps
-  if (segments[0] === "steps" && traversed.length === 2) {
-    const stepName = segments[1];
-    const stepsObj = scope.steps as Record<string, StepResult | undefined> | undefined;
-    if (stepsObj && !(stepName in stepsObj)) {
-      return `step '${stepName}' has not been executed yet`;
-    }
-  }
-
-  // When the path starts with "steps.", include step status context if available
-  if (segments[0] === "steps" && segments.length >= 2) {
-    const stepName = segments[1];
-    const stepsObj = scope.steps as Record<string, StepResult | undefined> | undefined;
-    if (stepsObj) {
-      const stepResult = stepsObj[stepName];
-      if (stepResult && parentPath) {
-        return `property '${failedSegment}' is undefined on ${parentPath} (step '${stepName}' status: ${stepResult.status})`;
-      }
-    }
-  }
-
-  if (parentPath) {
-    return `property '${failedSegment}' is undefined on ${parentPath}`;
-  }
-
-  return `property '${failedSegment}' is undefined`;
-}
-

package/src/format.test.ts

@@ -1,80 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert";
-import { formatDuration, formatCost, formatTokens } from "./format.ts";
-
-describe("formatDuration", () => {
-  it("formats zero", () => {
-    assert.strictEqual(formatDuration(0), "0s");
-  });
-
-  it("formats sub-minute", () => {
-    assert.strictEqual(formatDuration(42000), "42s");
-  });
-
-  it("rounds to nearest second", () => {
-    assert.strictEqual(formatDuration(1500), "2s");
-    assert.strictEqual(formatDuration(1499), "1s");
-  });
-
-  it("formats minutes and seconds", () => {
-    assert.strictEqual(formatDuration(92000), "1m32s");
-  });
-
-  it("pads seconds in minute format", () => {
-    assert.strictEqual(formatDuration(60000), "1m00s");
-    assert.strictEqual(formatDuration(63000), "1m03s");
-  });
-
-  it("formats hours and minutes", () => {
-    assert.strictEqual(formatDuration(3720000), "1h02m");
-  });
-
-  it("formats exact hour", () => {
-    assert.strictEqual(formatDuration(3600000), "1h00m");
-  });
-});
-
-describe("formatCost", () => {
-  it("formats zero", () => {
-    assert.strictEqual(formatCost(0), "$0.00");
-  });
-
-  it("formats small cost", () => {
-    assert.strictEqual(formatCost(0.03), "$0.03");
-  });
-
-  it("formats larger cost", () => {
-    assert.strictEqual(formatCost(1.5), "$1.50");
-  });
-
-  it("rounds to two decimal places", () => {
-    assert.strictEqual(formatCost(0.999), "$1.00");
-    assert.strictEqual(formatCost(0.001), "$0.00");
-  });
-});
-
-describe("formatTokens", () => {
-  it("formats small counts as-is", () => {
-    assert.strictEqual(formatTokens(0), "0 tok");
-    assert.strictEqual(formatTokens(42), "42 tok");
-    assert.strictEqual(formatTokens(999), "999 tok");
-  });
-
-  it("formats 1k-10k with one decimal", () => {
-    assert.strictEqual(formatTokens(1000), "1.0k tok");
-    assert.strictEqual(formatTokens(1234), "1.2k tok");
-    assert.strictEqual(formatTokens(9999), "10.0k tok");
-  });
-
-  it("formats 10k-1M as rounded k", () => {
-    assert.strictEqual(formatTokens(10000), "10k tok");
-    assert.strictEqual(formatTokens(12345), "12k tok");
-    assert.strictEqual(formatTokens(999999), "1000k tok");
-  });
-
-  it("formats 1M+ with one decimal", () => {
-    assert.strictEqual(formatTokens(1000000), "1.0M tok");
-    assert.strictEqual(formatTokens(1500000), "1.5M tok");
-    assert.strictEqual(formatTokens(2345678), "2.3M tok");
-  });
-});

package/src/format.ts

@@ -1,41 +0,0 @@
-/**
- * Shared formatting utilities for duration and cost display.
- * Used by state.ts (formatResult), expression.ts (filters), and tui.ts (widget).
- */
-
-/**
- * Format duration in milliseconds to human-readable string.
- * <60s -> "42s", <60m -> "1m32s", >=60m -> "1h02m"
- */
-export function formatDuration(ms: number): string {
-  const totalSeconds = Math.round(ms / 1000);
-  if (totalSeconds < 60) {
-    return `${totalSeconds}s`;
-  }
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  if (minutes < 60) {
-    return `${minutes}m${seconds.toString().padStart(2, "0")}s`;
-  }
-  const hours = Math.floor(minutes / 60);
-  const remainingMinutes = minutes % 60;
-  return `${hours}h${remainingMinutes.toString().padStart(2, "0")}m`;
-}
-
-/**
- * Format cost as a dollar string.
- */
-export function formatCost(cost: number): string {
-  return `$${cost.toFixed(2)}`;
-}
-
-/**
- * Format token count as compact human-readable string.
- * <1000 -> "123 tok", <10000 -> "1.2k tok", <1000000 -> "42k tok", >=1000000 -> "1.2M tok"
- */
-export function formatTokens(count: number): string {
-  if (count < 1000) return `${count} tok`;
-  if (count < 10000) return `${(count / 1000).toFixed(1)}k tok`;
-  if (count < 1000000) return `${Math.round(count / 1000)}k tok`;
-  return `${(count / 1000000).toFixed(1)}M tok`;
-}