@db-lyon/flowkit 0.13.0 → 0.15.0

package/docs/releases.md

@@ -0,0 +1,59 @@
+# Release notes
+
+## 0.15.0
+
+Flowkit now exposes a generic execution-lifecycle contract on every task:
+
+```typescript
+type ExecutionPhase =
+  | 'task'
+  | 'on_start'
+  | 'on_success'
+  | 'on_failure'
+  | 'finally'
+  | 'rollback';
+
+// Inside a task:
+protected get executionPhase(): ExecutionPhase;
+```
+
+The runner derives a fresh context for each invocation. Ordinary work,
+including nested flows, direct task calls, task-to-task calls, agents, and
+tools, receives `task`; hooks and rollback invocations receive their matching
+phase. A nested flow or sub-agent cannot carry its caller's phase into its own
+ordinary work.
+
+This is additive for hosts, including at the type level. `executionPhase` is
+**optional** on `TaskContext`, so a host context interface built on it stays
+constructible without naming a phase:
+
+```typescript
+interface FlowContext extends TaskContext, ToolContext {}
+const ctx: FlowContext = { bridge, project }; // still compiles
+```
+
+Making the field required would have broken every downstream context type that
+extends `TaskContext`, which is why it is not. Inside a task, read
+`this.executionPhase` rather than `this.ctx.executionPhase`: the accessor is
+typed `ExecutionPhase` with no `undefined`, because Flowkit resolves the value
+before any task observes it. `ResolvedTaskContext` names that resolved shape for
+code that needs the type directly.
+
+`TaskRegistry.create()` accepts host-style context without an `executionPhase`
+and derives `task` before construction. Code that calls `registry.resolve()` and
+directly instantiates the returned constructor gets the same defaulting from
+`BaseTask`, so it does not need to supply a phase either.
+
+Guard hosts are unaffected: `DiscoverTaskGuardsOptions.contextFor` returns
+`TaskContext`, unchanged from 0.14.0.
+
+The context a host passes is no longer copied when it already carries a phase,
+which is every path through `FlowRunner`. A host may therefore pass a class
+instance or service object as its context and keep its prototype methods and
+object identity; previously each invocation shallow-copied it. `Flowkit` exports
+`resolveTaskContext` and `DEFAULT_EXECUTION_PHASE` for hosts that construct
+tasks themselves and want the same normalization.
+
+A string `when:` condition now receives the phase of the step it gates, so a
+`finally` hook gating on `context.executionPhase` sees `'finally'` rather than
+the runner's seed value.

package/package.json

@@ -1,53 +1,59 @@
-{
-  "name": "@db-lyon/flowkit",
-  "version": "0.13.0",
-  "description": "YAML-configured task and flow orchestration engine",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./config": "./dist/config/index.js",
-    "./task": "./dist/task/index.js",
-    "./flow": "./dist/flow/index.js",
-    "./dag": "./dist/dag/index.js"
-  },
-  "files": [
-    "/dist",
-    "/docs"
-  ],
-  "scripts": {
-    "build": "tsc -b",
-    "prepublishOnly": "tsc -b",
-    "test": "vitest run",
-    "test:package-api": "npm run build && tsc -p test/tsconfig.public-api.json",
-    "test:watch": "vitest"
-  },
-  "keywords": [
-    "task",
-    "flow",
-    "orchestration",
-    "yaml",
-    "pipeline",
-    "engine"
-  ],
-  "author": "David Lyon",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/db-lyon/flowkit.git"
-  },
-  "dependencies": {
-    "js-yaml": "^4",
-    "zod": "^3"
-  },
-  "devDependencies": {
-    "@types/js-yaml": "^4",
-    "@types/node": "^20",
-    "typescript": "^5",
-    "vitest": "^2"
-  },
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "@db-lyon/flowkit",
+  "version": "0.15.0",
+  "description": "YAML-configured task and flow orchestration engine",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./config": "./dist/config/index.js",
+    "./task": "./dist/task/index.js",
+    "./flow": "./dist/flow/index.js",
+    "./dag": "./dist/dag/index.js",
+    "./guard": "./dist/guard/index.js"
+  },
+  "files": [
+    "/dist",
+    "/docs"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepublishOnly": "tsc -b",
+    "test": "vitest run",
+    "test:package-api": "npm run build && tsc -p test/tsconfig.public-api.json",
+    "test:types": "tsc -p test/tsconfig.json",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "task",
+    "flow",
+    "orchestration",
+    "yaml",
+    "pipeline",
+    "engine"
+  ],
+  "author": "David Lyon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/db-lyon/flowkit.git"
+  },
+  "dependencies": {
+    "js-yaml": "^4",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4",
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3.2.7"
+  },
+  "overrides": {
+    "postcss": "8.5.26",
+    "vite": "6.4.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/dist/flow/references.d.ts

@@ -1,39 +0,0 @@
-/**
- * Reference resolution for flow option values.
- *
- * Option values may contain `${<namespace>.<path>}` references:
- *
- *   ${steps.<id>.<path>}  → value from a previously completed step
- *   ${error.<path>}       → error info, only inside on_failure / finally hooks
- *   ${<ns>.<path>}        → value from a host-supplied namespace in `namespaces`
- *                           (e.g. ${project.package.namespace}, ${org.username},
- *                           ${env.HOME}) — the resolver is namespace-extensible,
- *                           symmetric with the pluggable `conditionEvaluator`.
- *
- * For `steps`, `<id>` is a step number ("3") or a task name ("level.place_actor");
- * task names match the most recently completed step with that name, longest-prefix
- * wins. A reference filling the entire string yields the raw value (preserving
- * object/array/number types); embedded references are stringified. A reference to
- * an UNREGISTERED namespace is left untouched (so non-reference `${...}` survives).
- */
-export interface ReferenceableStep {
-    stepNumber: number;
-    name: string;
-    result?: {
-        data?: unknown;
-    };
-}
-export interface ReferenceContext {
-    steps: ReferenceableStep[];
-    /** Present inside on_failure / finally hooks. */
-    error?: {
-        message: string;
-        name: string;
-        stack?: string;
-        step?: string;
-    };
-    /** Host-supplied reference namespaces, e.g. { project, org, env }. */
-    namespaces?: Record<string, unknown>;
-}
-export declare function resolveReferences<T>(value: T, ctx: ReferenceContext): T;
-//# sourceMappingURL=references.d.ts.map

package/dist/flow/references.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../src/flow/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAQD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,CAAC,CAcvE"}

package/dist/flow/references.js

@@ -1,102 +0,0 @@
-/**
- * Reference resolution for flow option values.
- *
- * Option values may contain `${<namespace>.<path>}` references:
- *
- *   ${steps.<id>.<path>}  → value from a previously completed step
- *   ${error.<path>}       → error info, only inside on_failure / finally hooks
- *   ${<ns>.<path>}        → value from a host-supplied namespace in `namespaces`
- *                           (e.g. ${project.package.namespace}, ${org.username},
- *                           ${env.HOME}) — the resolver is namespace-extensible,
- *                           symmetric with the pluggable `conditionEvaluator`.
- *
- * For `steps`, `<id>` is a step number ("3") or a task name ("level.place_actor");
- * task names match the most recently completed step with that name, longest-prefix
- * wins. A reference filling the entire string yields the raw value (preserving
- * object/array/number types); embedded references are stringified. A reference to
- * an UNREGISTERED namespace is left untouched (so non-reference `${...}` survives).
- */
-/** Returned by resolveRef when the namespace is unregistered — leave the text literal. */
-const LITERAL = Symbol('literal');
-const WHOLE_VALUE = /^\$\{(\w+)\.([^}]+)\}$/;
-const EMBEDDED = /\$\{(\w+)\.([^}]+)\}/g;
-export function resolveReferences(value, ctx) {
-    if (value == null)
-        return value;
-    if (typeof value === 'string')
-        return resolveString(value, ctx);
-    if (Array.isArray(value)) {
-        return value.map((v) => resolveReferences(v, ctx));
-    }
-    if (typeof value === 'object') {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            out[k] = resolveReferences(v, ctx);
-        }
-        return out;
-    }
-    return value;
-}
-function resolveString(str, ctx) {
-    const whole = str.match(WHOLE_VALUE);
-    if (whole) {
-        const v = resolveRef(whole[1], whole[2], ctx);
-        return v === LITERAL ? str : v;
-    }
-    if (!str.includes('${'))
-        return str;
-    return str.replace(EMBEDDED, (match, ns, ref) => {
-        const v = resolveRef(ns, ref, ctx);
-        if (v === LITERAL)
-            return match; // unregistered namespace — leave untouched
-        if (v == null)
-            return '';
-        if (typeof v === 'object')
-            return JSON.stringify(v);
-        return String(v);
-    });
-}
-function resolveRef(namespace, ref, ctx) {
-    if (namespace === 'error') {
-        if (!ctx.error) {
-            throw new Error(`\${error.${ref}} referenced outside on_failure/finally — error context not available`);
-        }
-        return getPath(ctx.error, ref.split('.'));
-    }
-    if (namespace === 'steps') {
-        const segments = ref.split('.');
-        for (let i = segments.length; i >= 1; i--) {
-            const idCandidate = segments.slice(0, i).join('.');
-            const match = findStep(idCandidate, ctx.steps);
-            if (match)
-                return getPath(match.result?.data, segments.slice(i));
-        }
-        throw new Error(`Unresolvable step reference: \${steps.${ref}} — no completed step matches "${segments[0]}"`);
-    }
-    // Host-supplied namespace (project / org / env / ...). Missing path → undefined.
-    if (ctx.namespaces && namespace in ctx.namespaces) {
-        return getPath(ctx.namespaces[namespace], ref.split('.'));
-    }
-    // Unregistered namespace — not a reference we own; leave it literal.
-    return LITERAL;
-}
-function findStep(id, steps) {
-    if (/^\d+$/.test(id)) {
-        return steps.find((s) => String(s.stepNumber) === id);
-    }
-    for (let i = steps.length - 1; i >= 0; i--) {
-        if (steps[i].name === id)
-            return steps[i];
-    }
-    return undefined;
-}
-function getPath(obj, segments) {
-    let cur = obj;
-    for (const seg of segments) {
-        if (cur == null || typeof cur !== 'object')
-            return undefined;
-        cur = cur[seg];
-    }
-    return cur;
-}
-//# sourceMappingURL=references.js.map

package/dist/flow/references.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"references.js","sourceRoot":"","sources":["../../src/flow/references.ts"],"names":[],"mappings":"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"}