jev-devtools 0.5.1 → 0.5.2

package/README.md

@@ -1,10 +1,10 @@
 # Jev DevTools
 
-[![npm version 0.5.1](https://img.shields.io/badge/npm-v0.5.1-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.1)
+[![npm version 0.5.2](https://img.shields.io/badge/npm-v0.5.2-E551BA?labelColor=0D0A0F&logo=npm)](https://www.npmjs.com/package/jev-devtools/v/0.5.2)
 
 A React drawer and Node adapter for inspecting TypeSafe Jev requests with animated diagrams. Includes request history, context, questions, typed answers, transport attempts, and raw snapshots.
 
-**Source version: 0.5.1.** Check the [release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for npm availability. If trying this source before publication, install the local archive below. **Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
+**Source version: 0.5.2 — pending publication.** npm currently provides 0.5.1. Check the [release history](https://github.com/diegoag64/jev-devtools/blob/main/CHANGELOG.md) for compatibility notes. To try this release candidate, install the local archive below. **Experimental (pre-1.0).** React 18/19 and Node 22.12+ are supported. APIs may change before 1.0. Verification uses sample responses through the real TypeSafe SDK, not live inference.
 
 [Website](https://jevtools.dev/) · [Documentation](https://docs.jevtools.dev/) · [Quick start](https://docs.jevtools.dev/getting-started/) · [API reference](https://docs.jevtools.dev/api/reference/) · [Release history](https://docs.jevtools.dev/changelog/)
 
@@ -48,25 +48,25 @@ To try local changes before a future release:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.5.1.tgz
+npm install /absolute/path/to/jev-devtools-0.5.2.tgz
 ```
 
 Mount once. The drawer loads its own styles; no CSS import is needed:
 
 ```tsx
-import { JevDevtools } from 'jev-devtools';
+import { JevDevtools } from "jev-devtools";
 
-<JevDevtools enabled={import.meta.env.DEV} defaultOpen={false} />
+<JevDevtools enabled={import.meta.env.DEV} defaultOpen={false} />;
 ```
 
 Create one shared Node adapter and instrumented client:
 
 ```ts
-import { createJevDevtools } from 'jev-devtools/server';
+import { createJevDevtools } from "jev-devtools/server";
 
 const inspector = createJevDevtools({
-  enabled: process.env.NODE_ENV === 'development',
-  origin: 'http://localhost:3000',
+  enabled: process.env.NODE_ENV === "development",
+  origin: "http://localhost:3000",
 });
 const jev = inspector.createClient({ apiKey: process.env.TYPESAFE_API_KEY });
 app.use(inspector.middleware); // Mount at root, before fallback handlers.
@@ -95,27 +95,49 @@ Define calls, conditions, parallel checks, and named outcomes with `jev-devtools
 On the server, reuse the instrumented `jev` client and `inspector` from the setup above:
 
 ```ts
-import { defineJevFlow } from 'jev-devtools/flow';
-
-const review = defineJevFlow<{ message: string }>('review', (flow) => {
-  const decision = flow.jev('readiness', {
-    state: flow.input,
-    questions: { ready: { type: 'noul', instructions: 'Is this ready for review?' } },
-  }, { title: 'Assess readiness' });
-
-  return flow.branch('route', {
-    when: decision.answer('ready').noul.gte(0.9), // Your application's policy.
-    then: (path) => path.output('ready', { probability: decision.answer('ready').noul }, {
-      title: 'Ready for review', description: 'Return readiness to the application.',
-    }),
-    else: (path) => path.output('manual-review', undefined, { title: 'Needs manual review' }),
-  }, { title: 'Require at least 90% readiness' });
+import { defineJevFlow } from "jev-devtools/flow";
+
+const review = defineJevFlow<{ message: string }>("review", (flow) => {
+  const decision = flow.jev(
+    "readiness",
+    {
+      state: flow.input,
+      questions: {
+        ready: { type: "noul", instructions: "Is this ready for review?" },
+      },
+    },
+    { title: "Assess readiness" },
+  );
+
+  return flow.branch(
+    "route",
+    {
+      when: decision.answer("ready").noul.gte(0.9), // Your application's policy.
+      then: (path) =>
+        path.output(
+          "ready",
+          { probability: decision.answer("ready").noul },
+          {
+            title: "Ready for review",
+            description: "Return readiness to the application.",
+          },
+        ),
+      else: (path) =>
+        path.output("manual-review", undefined, {
+          title: "Needs manual review",
+        }),
+    },
+    { title: "Require at least 90% readiness" },
+  );
 });
 
-const result = await review.run({ message: 'Please review my ticket.' }, {
-  client: jev,
-  devtools: inspector,
-});
+const result = await review.run(
+  { message: "Please review my ticket." },
+  {
+    client: jev,
+    devtools: inspector,
+  },
+);
 // Handle result.outcome in your app. The flow does not execute business actions.
 ```
 

package/lib/flow/index.d.ts

@@ -53,7 +53,7 @@ type Request<Q extends Questions> = Omit<SystemOneRequest<Q>, "state"> & {
     state: unknown;
 };
 /** Resolve nested references before invoking a server callback. */
-export type Resolved<T> = T extends FlowExpression<infer V> ? V : T extends readonly unknown[] ? {
+export type Resolved<T> = T extends FlowExpression<infer V> ? V : T extends string | number | boolean | null | undefined ? T : T extends readonly unknown[] ? {
     [K in keyof T]: Resolved<T[K]>;
 } : T extends object ? {
     [K in keyof T]: Resolved<T[K]>;
@@ -100,9 +100,11 @@ export interface FlowBuilder<T> {
     jev<const Q extends Questions>(id: string, request: Request<Q>, display?: FlowDisplay): AnswerRefs<Q>;
     jev<I, const Q extends Questions>(id: string, request: FlowRequestFactory<I, Q>, display?: FlowDisplay): AnswerRefs<Q>;
     task<I, O>(id: string, task: FlowTask<I, O>, display?: FlowDisplay): FlowExpression<Awaited<O>>;
-    /** Execute a reusable item program with bounded concurrency; return results in input order. */
+    /** References and scalar arrays already carry their resolved item type. */
     map<I, C, O>(id: string, options: {
-        items: FlowExpression<readonly I[]> | readonly I[];
+        items: FlowExpression<readonly I[]> | (readonly I[] & readonly (string | number | {
+            valueOf(): boolean;
+        } | null)[]);
         input: C;
         concurrency?: number;
         maxItems: number;
@@ -111,17 +113,43 @@ export interface FlowBuilder<T> {
         index: number;
         context: Resolved<C>;
     }>) => FlowExpression<O>, display?: FlowDisplay): FlowExpression<O[]>;
-    /** Pre-test loop with JSON state, explicit context and a required iteration limit. */
+    /** Execute a reusable program over resolved items; return results in input order. */
+    map<I, C, O>(id: string, options: {
+        items: FlowExpression<readonly I[]> | readonly I[];
+        input: C;
+        concurrency?: number;
+        maxItems: number;
+    }, build: (item: FlowBuilder<{
+        item: Resolved<I>;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<O>, display?: FlowDisplay): FlowExpression<O[]>;
+    /** References and scalar initial values preserve their generic state type. */
     loop<S, C>(id: string, options: {
         initial: S | FlowExpression<S>;
         input: C;
         while: (state: FlowExpression<NoInfer<S>>) => FlowExpression<boolean>;
         maxIterations: number;
+    } & {
+        initial: FlowExpression<S> | string | number | {
+            valueOf(): boolean;
+        } | null;
     }, build: (iteration: FlowBuilder<{
         state: S;
         index: number;
         context: Resolved<C>;
     }>) => FlowExpression<NoInfer<S>>, display?: FlowDisplay): FlowExpression<S>;
+    /** Pre-test loop over resolved JSON state, with explicit context and an iteration limit. */
+    loop<S, C>(id: string, options: {
+        initial: S | FlowExpression<S>;
+        input: C;
+        while: (state: FlowExpression<NoInfer<Resolved<S>>>) => FlowExpression<boolean>;
+        maxIterations: number;
+    }, build: (iteration: FlowBuilder<{
+        state: Resolved<S>;
+        index: number;
+        context: Resolved<C>;
+    }>) => FlowExpression<NoInfer<Resolved<S>>>, display?: FlowDisplay): FlowExpression<Resolved<S>>;
     /** Execute one value-returning path, then continue with its typed result. */
     if<A, B>(id: string, paths: {
         when: FlowExpression<boolean>;

package/lib/flow/index.js

@@ -6,21 +6,38 @@ export { flowFixture } from "../src/flow-fixture.js";
 export { compareWithFixture, formatComparison, } from "./compare.js";
 const owners = new WeakMap();
 const builderIds = new WeakMap();
+const astBudgets = new WeakMap();
 function freezeAst(ast, depth = 0) {
     if (depth > 80)
         throw new Error("Expression nesting exceeds 80");
-    if (Object.isFrozen(ast))
-        return;
+    const cached = astBudgets.get(ast);
+    if (cached) {
+        if (depth + cached.depth > 80)
+            throw new Error("Expression nesting exceeds 80");
+        return cached;
+    }
+    const budget = { depth: 0, nodes: 1 };
+    const include = (child) => {
+        const childBudget = freezeAst(child, depth + 1);
+        budget.depth = Math.max(budget.depth, childBudget.depth + 1);
+        // Visitors expand each occurrence, even when multiple operands share a child.
+        budget.nodes += childBudget.nodes;
+        if (budget.nodes > 4096)
+            throw new Error("Expression size exceeds 4096 expanded nodes");
+    };
     if (ast.op === "get")
-        freezeAst(ast.from, depth + 1);
+        include(ast.from);
     if ("args" in ast) {
         if (ast.args.length > 256)
             throw new Error("Too many condition operands");
         for (const child of ast.args)
-            freezeAst(child, depth + 1);
+            include(child);
         Object.freeze(ast.args);
     }
     Object.freeze(ast);
+    // Frozen caller-supplied ASTs still need validation; only our cache is trusted.
+    astBudgets.set(ast, budget);
+    return budget;
 }
 /** Inspectable expression, not an application callback. Use get() for input fields. */
 export class FlowExpression {
@@ -123,21 +140,47 @@ const inspectAst = (ast, ref) => {
         ast.args.forEach((a) => inspectAst(a, ref));
 };
 function describe(ast) {
-    if (ast.op === "input")
-        return "input";
-    if (ast.op === "ref")
-        return ast.id;
-    if (ast.op === "get")
-        return `${describe(ast.from)}.${ast.key}`;
-    if (ast.op === "literal")
-        return "[literal]";
-    return `${ast.op}(${ast.args.map(describe).join(", ")})`;
+    const limit = 4096;
+    const chunks = [];
+    let remaining = limit;
+    const append = (text) => {
+        chunks.push(text.slice(0, remaining));
+        const fits = text.length <= remaining;
+        remaining -= Math.min(text.length, remaining);
+        return fits;
+    };
+    const visit = (node) => {
+        if (node.op === "input")
+            return append("input");
+        if (node.op === "ref")
+            return append(node.id);
+        if (node.op === "get")
+            return visit(node.from) && append(".") && append(node.key);
+        if (node.op === "literal")
+            return append("[literal]");
+        if (!append(node.op) || !append("("))
+            return false;
+        for (let i = 0; i < node.args.length; i++) {
+            if (i > 0 && !append(", "))
+                return false;
+            if (!visit(node.args[i]))
+                return false;
+        }
+        return append(")");
+    };
+    const complete = visit(ast);
+    const text = chunks.join("");
+    const marker = "[condition truncated]";
+    return complete ? text : text.slice(0, limit - marker.length) + marker;
 }
 function conditionRule(ast, requests, tasks) {
     let remaining = 128;
+    const warnings = new Set();
     const visit = (node) => {
-        if (--remaining < 0)
+        if (--remaining < 0) {
+            warnings.add("Rule projection limit reached.");
             return { op: "literal", value: "[rule truncated]" };
+        }
         if (node.op === "input" || node.op === "ref" || node.op === "get") {
             const path = [];
             let base = node;
@@ -179,16 +222,20 @@ function conditionRule(ast, requests, tasks) {
                         : {}),
             };
         }
-        if (node.op === "literal")
+        if (node.op === "literal") {
+            const scalar = node.value === null ||
+                typeof node.value === "string" ||
+                typeof node.value === "boolean" ||
+                (typeof node.value === "number" && Number.isFinite(node.value));
+            if (!scalar)
+                warnings.add("Rule literal capture unavailable.");
             return {
                 op: "literal",
-                value: node.value === null ||
-                    typeof node.value === "string" ||
-                    typeof node.value === "boolean" ||
-                    (typeof node.value === "number" && Number.isFinite(node.value))
+                value: scalar
                     ? node.value
                     : "[value unavailable]",
             };
+        }
         const args = [];
         for (const arg of node.args) {
             args.push(visit(arg));
@@ -197,7 +244,8 @@ function conditionRule(ast, requests, tasks) {
         }
         return { op: node.op, args };
     };
-    return visit(ast);
+    const rule = visit(ast);
+    return { conditionRule: rule, conditionCaptureWarnings: [...warnings] };
 }
 function evaluate(ast, input, values) {
     if (ast.op === "input")
@@ -492,7 +540,7 @@ export function defineJevFlow(name, build) {
                         return { ...ast, args: ast.args.map(referenceState) };
                     return ast;
                 };
-                node.conditionRule = conditionRule(referenceState(when.ast), new Set(), new Set([id]));
+                Object.assign(node, conditionRule(referenceState(when.ast), new Set(), new Set([id])));
                 return new FlowExpression({ op: "ref", id }, owner);
             },
             if(id, paths, display) {
@@ -502,9 +550,11 @@ export function defineJevFlow(name, build) {
                 step.when = paths.when;
                 const node = nodes.find((n) => n.id === id);
                 node.condition = describe(paths.when.ast);
-                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
-                    .filter((n) => n.kind === "task" || n.kind === "merge" || n.kind === "loop")
-                    .map((n) => n.id)));
+                Object.assign(node, conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
+                    .filter((n) => n.kind === "task" ||
+                    n.kind === "merge" ||
+                    n.kind === "loop")
+                    .map((n) => n.id))));
                 step.then = block(paths.then, new Set(available), [...path, `${id}:then`], [id], depth + 1, false, true);
                 step.else = block(paths.else, new Set(available), [...path, `${id}:else`], [id], depth + 1, false, true);
                 // A separate merge keeps the diagram acyclic and gives downstream refs a
@@ -534,9 +584,11 @@ export function defineJevFlow(name, build) {
                     throw new Error("branch requires a condition expression");
                 const node = nodes.find((n) => n.id === id);
                 node.condition = describe(paths.when.ast);
-                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
-                    .filter((n) => n.kind === "task" || n.kind === "merge" || n.kind === "loop")
-                    .map((n) => n.id)));
+                Object.assign(node, conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)), new Set(nodes
+                    .filter((n) => n.kind === "task" ||
+                    n.kind === "merge" ||
+                    n.kind === "loop")
+                    .map((n) => n.id))));
                 step.then = block(paths.then, new Set(available), [...path, `${id}:then`], [id], depth + 1, true);
                 step.else = block(paths.else, new Set(available), [...path, `${id}:else`], [id], depth + 1, true);
                 terminal = true;
@@ -624,6 +676,7 @@ export function defineJevFlow(name, build) {
         if (node.lanes)
             Object.freeze(node.lanes);
         freezeRule(node.conditionRule);
+        freezeRule(node.conditionCaptureWarnings);
         freezeRule(node.itemDefinition);
         Object.freeze(node);
     }
@@ -684,49 +737,73 @@ export function defineJevFlow(name, build) {
                 if (value && typeof value === "object" && observerData.has(value))
                     return observerData.get(value);
                 let snapshot;
+                const warnings = [];
                 try {
                     snapshot = observerSnapshot(value);
                 }
                 catch {
                     // Direct flow outputs may be non-JSON; only their capture is unavailable.
                     snapshot = "[capture unavailable]";
+                    warnings.push("Observer capture unavailable.");
                 }
+                const captured = { data: snapshot, warnings };
                 if (value && typeof value === "object")
-                    observerData.set(value, snapshot);
-                return snapshot;
+                    observerData.set(value, captured);
+                return captured;
             };
             const emit = () => {
                 try {
                     if (observer) {
                         const { value, steps, ...metadata } = run;
+                        const outcome = value !== undefined ? snapshotData(value) : undefined;
                         observer.update({
                             ...structuredClone(metadata),
-                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => [
-                                id,
-                                {
-                                    ...step,
-                                    ...(step.data !== undefined
-                                        ? { data: snapshotData(step.data) }
-                                        : {}),
-                                    ...(step.loop ? { loop: { ...step.loop } } : {}),
-                                    ...(step.captureWarnings
-                                        ? { captureWarnings: [...step.captureWarnings] }
-                                        : {}),
-                                    ...(step.collection
-                                        ? {
-                                            collection: {
-                                                ...step.collection,
-                                                // Child runs have already crossed this snapshot boundary.
-                                                // Copy mutable collection metadata, reuse detached children.
-                                                items: step.collection.items.map((item) => ({
-                                                    ...item,
-                                                })),
-                                            },
-                                        }
-                                        : {}),
-                                },
-                            ])),
-                            ...(value !== undefined ? { value: snapshotData(value) } : {}),
+                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => {
+                                const data = step.data !== undefined
+                                    ? snapshotData(step.data)
+                                    : undefined;
+                                return [
+                                    id,
+                                    {
+                                        ...step,
+                                        ...(data ? { data: data.data } : {}),
+                                        ...(step.loop ? { loop: { ...step.loop } } : {}),
+                                        ...(data || step.captureWarnings
+                                            ? {
+                                                captureWarnings: [
+                                                    ...new Set([
+                                                        ...(step.captureWarnings ?? []),
+                                                        ...(data?.warnings ?? []),
+                                                    ]),
+                                                ],
+                                            }
+                                            : {}),
+                                        ...(step.collection
+                                            ? {
+                                                collection: {
+                                                    ...step.collection,
+                                                    // Child runs have already crossed this snapshot boundary.
+                                                    // Copy mutable collection metadata, reuse detached children.
+                                                    items: step.collection.items.map((item) => ({
+                                                        ...item,
+                                                    })),
+                                                },
+                                            }
+                                            : {}),
+                                    },
+                                ];
+                            })),
+                            ...(outcome
+                                ? {
+                                    value: outcome.data,
+                                    captureWarnings: [
+                                        ...new Set([
+                                            ...(run.captureWarnings ?? []),
+                                            ...outcome.warnings,
+                                        ]),
+                                    ],
+                                }
+                                : {}),
                         });
                     }
                 }
@@ -1004,6 +1081,7 @@ export function defineJevFlow(name, build) {
                             }
                             catch {
                                 state.data = "Selected value could not be captured as JSON.";
+                                state.captureWarnings = ["Selected value capture unavailable."];
                             }
                         }
                         else if (step.kind === "branch" || step.kind === "if") {

package/lib/server/flows.js

@@ -36,14 +36,17 @@ export class FlowRecorder {
                         redactRules(node.itemDefinition, [...prefix, node.id, "items"]);
                     if (node.conditionRule === undefined)
                         continue;
+                    const warnings = new Set(node.conditionCaptureWarnings);
                     try {
-                        node.conditionRule = capture(node.conditionRule, new Set(), this.options.redact
+                        node.conditionRule = capture(node.conditionRule, warnings, this.options.redact
                             ? (path, value) => this.options.redact(["conditions", ...prefix, node.id, ...path], value)
                             : undefined);
                     }
                     catch {
                         node.conditionRule = "[rule capture unavailable]";
+                        warnings.add("Rule capture unavailable.");
                     }
+                    node.conditionCaptureWarnings = [...warnings];
                 }
             };
             redactRules(stored);
@@ -117,20 +120,28 @@ export class FlowRecorder {
                     {
                         ...step,
                         data: captured.data,
-                        captureWarnings: captured.warnings,
+                        captureWarnings: [
+                            ...new Set([
+                                ...(step.captureWarnings ?? []),
+                                ...captured.warnings,
+                            ]),
+                        ],
                     },
                 ];
             })),
         };
         if ("value" in stored) {
+            const warnings = new Set(run.captureWarnings);
             try {
-                stored.value = capture(stored.value, new Set(), this.options.redact
+                stored.value = capture(stored.value, warnings, this.options.redact
                     ? (path, value) => this.options.redact([...prefix, ...path], value)
                     : undefined);
             }
             catch {
                 stored.value = "[capture unavailable]";
+                warnings.add("Outcome capture unavailable.");
             }
+            stored.captureWarnings = [...warnings];
         }
         if (prefix.length)
             this.itemCaptures.set(run, stored);

package/lib/server/recorder.js

@@ -36,10 +36,16 @@ export function capture(value, warnings, redact) {
     let budget = 96_000;
     const visit = (input, path, depth) => {
         const key = (path.at(-1) ?? "").replace(/[-_]/g, "").toLowerCase();
-        if (credentialKeys.has(key))
+        if (credentialKeys.has(key)) {
+            warnings.add("Capture contains redacted values.");
             return "[redacted]";
-        if (redact)
-            input = redact(path, input);
+        }
+        if (redact) {
+            const redacted = redact(path, input);
+            if (!Object.is(redacted, input))
+                warnings.add("Capture contains redacted values.");
+            input = redacted;
+        }
         budget -= 8 + (path.at(-1)?.length ?? 0);
         if (budget <= 0 || depth > 12) {
             warnings.add("Capture size/depth limit reached.");