@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/workflow/discovery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Workflow definition discovery.
+ *
+ * Workflows are packaged as directories: each workflow lives under its
+ * own directory containing a `workflow.yaml` (or `workflow.yml`)
+ * manifest plus optional sibling resources like a `skills/` subdir.
+ *
+ *   src/workflow/workflows/<name>/workflow.yaml      (bundled)
+ *   ~/.ironcurtain/workflows/<name>/workflow.yaml    (user)
+ *
+ * The directory shape is what allows skills (and other future co-packaged
+ * resources) to travel with the workflow definition. Single-file and
+ * JSON manifest forms are not accepted as inputs; JSON remains an
+ * internal serialization format used by workflow-resume checkpointing.
+ */
+export type WorkflowSource = 'bundled' | 'user' | 'custom';
+export interface WorkflowEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly path: string;
+    readonly source: WorkflowSource;
+}
+/**
+ * Parses a workflow definition file. Dispatches on extension:
+ *   - `.yaml` / `.yml` -> YAML parse with alias expansion disabled
+ *     (prevents YAML-bomb DoS via reference amplification)
+ *   - `.json`          -> JSON parse
+ *
+ * Returns the parsed value unvalidated — the workflow definition Zod
+ * schema enforces structure downstream.
+ *
+ * Note on the JSON branch: user-facing manifests must be YAML; the
+ * discovery layer (`discoverWorkflows`, `resolveWorkflowPath`) only
+ * looks for `workflow.{yaml,yml}` and rejects JSON path-style refs.
+ * The JSON branch survives only for internal serialization — the
+ * resume path reads `<runDir>/definition.json` written at workflow
+ * start, which is JSON for compactness and because it round-trips a
+ * validated `WorkflowDefinition` rather than user-authored markup.
+ *
+ * @throws if the file cannot be read or parsed
+ */
+export declare function parseDefinitionFile(filePath: string): unknown;
+/**
+ * Returns the path to the bundled workflows directory.
+ * Works in both dev (src/workflow/workflows/) and production (dist/workflow/workflows/).
+ */
+export declare function getBundledWorkflowsDir(): string;
+/**
+ * Returns the directory containing a workflow's package, given the
+ * absolute path to its manifest. Co-packaged resources (currently the
+ * optional `skills/` subdir) live here.
+ */
+export declare function getWorkflowPackageDir(workflowFilePath: string): string;
+/**
+ * Discovers all available workflow definitions from bundled and user
+ * directories. User workflows override bundled ones on name collision.
+ * Returned entries are sorted alphabetically by name.
+ */
+export declare function discoverWorkflows(): WorkflowEntry[];
+/**
+ * Resolves a workflow reference to an absolute manifest path. User-facing
+ * refs are YAML-only — JSON path-style refs are silently dropped because
+ * `definition.json` is an internal serialization format produced by
+ * workflow-resume checkpointing, not a manifest authors should reference.
+ *
+ * Resolution matrix:
+ *  - bare name (`my-flow`)       → probe user dir then bundled dir for
+ *                                  `<root>/<ref>/workflow.{yaml,yml}`
+ *  - path with no extension      → treat as a package directory, probe
+ *    (`./my-flow`, `/abs/foo`)     `<ref>/workflow.{yaml,yml}`
+ *  - explicit `.yaml` / `.yml`   → return as-is when the file exists
+ *  - any other extension         → undefined (JSON refs included; the
+ *                                  resume path reads `definition.json`
+ *                                  directly, not via this resolver)
+ *
+ * Returns `undefined` when the reference cannot be resolved.
+ */
+export declare function resolveWorkflowPath(ref: string): string | undefined;

package/dist/workflow/discovery.js

@@ -0,0 +1,203 @@
+/**
+ * Workflow definition discovery.
+ *
+ * Workflows are packaged as directories: each workflow lives under its
+ * own directory containing a `workflow.yaml` (or `workflow.yml`)
+ * manifest plus optional sibling resources like a `skills/` subdir.
+ *
+ *   src/workflow/workflows/<name>/workflow.yaml      (bundled)
+ *   ~/.ironcurtain/workflows/<name>/workflow.yaml    (user)
+ *
+ * The directory shape is what allows skills (and other future co-packaged
+ * resources) to travel with the workflow definition. Single-file and
+ * JSON manifest forms are not accepted as inputs; JSON remains an
+ * internal serialization format used by workflow-resume checkpointing.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, resolve, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import { getUserWorkflowsDir } from '../config/paths.js';
+// ---------------------------------------------------------------------------
+// File format support
+// ---------------------------------------------------------------------------
+/** Manifest filenames probed inside a workflow package directory. */
+const MANIFEST_BASENAMES = ['workflow.yaml', 'workflow.yml'];
+/** Recognized YAML extensions for ad-hoc file-path workflow refs. */
+const YAML_EXTENSIONS = new Set(['.yaml', '.yml']);
+/**
+ * Parses a workflow definition file. Dispatches on extension:
+ *   - `.yaml` / `.yml` -> YAML parse with alias expansion disabled
+ *     (prevents YAML-bomb DoS via reference amplification)
+ *   - `.json`          -> JSON parse
+ *
+ * Returns the parsed value unvalidated — the workflow definition Zod
+ * schema enforces structure downstream.
+ *
+ * Note on the JSON branch: user-facing manifests must be YAML; the
+ * discovery layer (`discoverWorkflows`, `resolveWorkflowPath`) only
+ * looks for `workflow.{yaml,yml}` and rejects JSON path-style refs.
+ * The JSON branch survives only for internal serialization — the
+ * resume path reads `<runDir>/definition.json` written at workflow
+ * start, which is JSON for compactness and because it round-trips a
+ * validated `WorkflowDefinition` rather than user-authored markup.
+ *
+ * @throws if the file cannot be read or parsed
+ */
+export function parseDefinitionFile(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const content = readFileSync(filePath, 'utf-8');
+    if (ext === '.yaml' || ext === '.yml') {
+        return YAML.parse(content, { maxAliasCount: 0 });
+    }
+    if (ext === '.json') {
+        return JSON.parse(content);
+    }
+    throw new Error(`Unsupported workflow file extension: ${ext}`);
+}
+// ---------------------------------------------------------------------------
+// Directory helpers
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Returns the path to the bundled workflows directory.
+ * Works in both dev (src/workflow/workflows/) and production (dist/workflow/workflows/).
+ */
+export function getBundledWorkflowsDir() {
+    return resolve(__dirname, 'workflows');
+}
+/**
+ * Returns the directory containing a workflow's package, given the
+ * absolute path to its manifest. Co-packaged resources (currently the
+ * optional `skills/` subdir) live here.
+ */
+export function getWorkflowPackageDir(workflowFilePath) {
+    return dirname(workflowFilePath);
+}
+/**
+ * Locates the manifest file inside a workflow package directory.
+ * Returns the absolute path to `workflow.yaml` or `workflow.yml` if
+ * present (yaml takes precedence on collision), `undefined` otherwise.
+ */
+function findManifest(packageDir) {
+    for (const basename of MANIFEST_BASENAMES) {
+        const candidate = resolve(packageDir, basename);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+/**
+ * Scans a workflows root for package directories and returns one entry
+ * per directory that contains a valid manifest. Subdirectories without
+ * a `workflow.yaml`/`workflow.yml`, or whose manifest fails to parse,
+ * are skipped silently — the same forgiving posture other discovery
+ * paths in this project take (e.g., `discoverSkills`).
+ *
+ * The entry's `name` is the package directory's name, NOT the
+ * manifest's `name:` field. This matches `resolveWorkflowPath`, which
+ * looks up workflows by directory name.
+ */
+function scanDirectory(dir, source) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        const packageDir = resolve(dir, name);
+        let stats;
+        try {
+            stats = statSync(packageDir);
+        }
+        catch {
+            continue;
+        }
+        if (!stats.isDirectory())
+            continue;
+        const manifest = findManifest(packageDir);
+        if (!manifest)
+            continue;
+        let description = '';
+        try {
+            const raw = parseDefinitionFile(manifest);
+            if (typeof raw.description === 'string')
+                description = raw.description;
+        }
+        catch {
+            // Skip packages with unparseable manifests
+            continue;
+        }
+        out.push({ name, description, path: manifest, source });
+    }
+    return out;
+}
+/**
+ * Discovers all available workflow definitions from bundled and user
+ * directories. User workflows override bundled ones on name collision.
+ * Returned entries are sorted alphabetically by name.
+ */
+export function discoverWorkflows() {
+    const bundled = scanDirectory(getBundledWorkflowsDir(), 'bundled');
+    const user = scanDirectory(getUserWorkflowsDir(), 'user');
+    // User entries override bundled on name collision
+    const byName = new Map();
+    for (const entry of bundled) {
+        byName.set(entry.name, entry);
+    }
+    for (const entry of user) {
+        byName.set(entry.name, entry);
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolves a workflow reference to an absolute manifest path. User-facing
+ * refs are YAML-only — JSON path-style refs are silently dropped because
+ * `definition.json` is an internal serialization format produced by
+ * workflow-resume checkpointing, not a manifest authors should reference.
+ *
+ * Resolution matrix:
+ *  - bare name (`my-flow`)       → probe user dir then bundled dir for
+ *                                  `<root>/<ref>/workflow.{yaml,yml}`
+ *  - path with no extension      → treat as a package directory, probe
+ *    (`./my-flow`, `/abs/foo`)     `<ref>/workflow.{yaml,yml}`
+ *  - explicit `.yaml` / `.yml`   → return as-is when the file exists
+ *  - any other extension         → undefined (JSON refs included; the
+ *                                  resume path reads `definition.json`
+ *                                  directly, not via this resolver)
+ *
+ * Returns `undefined` when the reference cannot be resolved.
+ */
+export function resolveWorkflowPath(ref) {
+    const ext = extname(ref).toLowerCase();
+    const isPathStyle = ref.includes('/') || ref.includes('\\');
+    if (YAML_EXTENSIONS.has(ext)) {
+        const resolved = resolve(ref);
+        return existsSync(resolved) ? resolved : undefined;
+    }
+    if (isPathStyle) {
+        // No extension → package directory. A non-yaml extension (e.g.
+        // `.json`) on a path-style ref falls through to undefined: not a
+        // user-facing form.
+        if (ext === '') {
+            return findManifest(resolve(ref));
+        }
+        return undefined;
+    }
+    const userManifest = findManifest(resolve(getUserWorkflowsDir(), ref));
+    if (userManifest)
+        return userManifest;
+    const bundledManifest = findManifest(resolve(getBundledWorkflowsDir(), ref));
+    if (bundledManifest)
+        return bundledManifest;
+    return undefined;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/workflow/discovery.js.map

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

package/dist/workflow/errors.d.ts

@@ -0,0 +1,66 @@
+import type { AgentConversationId } from '../session/types.js';
+import { type TransientFailureKind } from '../docker/agent-adapter.js';
+/**
+ * Wraps an error thrown from within `executeAgentState()` so the XState
+ * error handler can recover the `agentConversationId` that was minted for
+ * the failing invocation and persist it into `context.agentConversationsByState`.
+ *
+ * Without this, states that error mid-invocation drop their conversation
+ * id on the floor — the `onDone` path stamps the id into context, but
+ * `onError` used to record only `lastError`. For states configured with
+ * `freshSession: false`, that silently broke resume on the next visit.
+ */
+export interface AgentInvocationErrorOptions {
+    readonly stateId: string;
+    readonly agentConversationId: AgentConversationId;
+    readonly cause: unknown;
+}
+export declare class AgentInvocationError extends Error {
+    readonly stateId: string;
+    readonly agentConversationId: AgentConversationId;
+    readonly cause: unknown;
+    constructor(options: AgentInvocationErrorOptions);
+}
+export declare function isAgentInvocationError(err: unknown): err is AgentInvocationError;
+/**
+ * Thrown when the agent adapter reports upstream quota exhaustion for a
+ * state's turn. Distinct from a generic `Error` so M4's paused-phase
+ * handling (follow-up work) can intercept it cleanly and drive a
+ * `paused` terminal instead of the current `aborted` terminal.
+ *
+ * `resetAt` is the provider-advertised reset time when the adapter
+ * could parse one; `rawMessage` is the original provider/CLI text.
+ */
+export interface WorkflowQuotaExhaustedOptions {
+    readonly stateId: string;
+    readonly resetAt?: Date;
+    readonly rawMessage: string;
+}
+export declare class WorkflowQuotaExhaustedError extends Error {
+    readonly stateId: string;
+    readonly resetAt?: Date;
+    readonly rawMessage: string;
+    constructor(options: WorkflowQuotaExhaustedOptions);
+}
+export declare function isWorkflowQuotaExhaustedError(err: unknown): err is WorkflowQuotaExhaustedError;
+/**
+ * Thrown when the agent adapter reports a transient upstream failure
+ * (see `AgentResponse.transientFailure`). Sibling of
+ * `WorkflowQuotaExhaustedError`: both signal terminal-but-resumable
+ * conditions. Consumers MUST NOT remove the on-disk checkpoint; the
+ * orchestrator forces `phase: 'aborted'` so `isCheckpointResumable`
+ * returns true regardless of which terminal `findErrorTarget` resolved
+ * to.
+ */
+export interface WorkflowTransientFailureOptions {
+    readonly stateId: string;
+    readonly kind: TransientFailureKind;
+    readonly rawMessage: string;
+}
+export declare class WorkflowTransientFailureError extends Error {
+    readonly stateId: string;
+    readonly kind: TransientFailureKind;
+    readonly rawMessage: string;
+    constructor(options: WorkflowTransientFailureOptions);
+}
+export declare function isWorkflowTransientFailureError(err: unknown): err is WorkflowTransientFailureError;

package/dist/workflow/errors.js

@@ -0,0 +1,49 @@
+import { describeTransientFailureKind } from '../docker/agent-adapter.js';
+export class AgentInvocationError extends Error {
+    stateId;
+    agentConversationId;
+    cause;
+    constructor(options) {
+        const message = options.cause instanceof Error ? options.cause.message : String(options.cause);
+        super(message);
+        this.name = 'AgentInvocationError';
+        this.stateId = options.stateId;
+        this.agentConversationId = options.agentConversationId;
+        this.cause = options.cause;
+    }
+}
+export function isAgentInvocationError(err) {
+    return err instanceof AgentInvocationError;
+}
+export class WorkflowQuotaExhaustedError extends Error {
+    stateId;
+    resetAt;
+    rawMessage;
+    constructor(options) {
+        const resetHint = options.resetAt ? ` (resets at ${options.resetAt.toISOString()})` : '';
+        super(`Agent turn aborted: upstream quota exhausted${resetHint}`);
+        this.name = 'WorkflowQuotaExhaustedError';
+        this.stateId = options.stateId;
+        this.resetAt = options.resetAt;
+        this.rawMessage = options.rawMessage;
+    }
+}
+export function isWorkflowQuotaExhaustedError(err) {
+    return err instanceof WorkflowQuotaExhaustedError;
+}
+export class WorkflowTransientFailureError extends Error {
+    stateId;
+    kind;
+    rawMessage;
+    constructor(options) {
+        super(`Agent turn aborted: transient upstream failure — ${describeTransientFailureKind(options.kind)}`);
+        this.name = 'WorkflowTransientFailureError';
+        this.stateId = options.stateId;
+        this.kind = options.kind;
+        this.rawMessage = options.rawMessage;
+    }
+}
+export function isWorkflowTransientFailureError(err) {
+    return err instanceof WorkflowTransientFailureError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/workflow/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/workflow/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAA6B,MAAM,4BAA4B,CAAC;AAkBrG,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,OAAO,CAAS;IAChB,mBAAmB,CAAsB;IAChC,KAAK,CAAU;IAEjC,YAAY,OAAoC;QAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC/F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;QACvD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,GAAG,YAAY,oBAAoB,CAAC;AAC7C,CAAC;AAiBD,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAC3C,OAAO,CAAS;IAChB,OAAO,CAAQ;IACf,UAAU,CAAS;IAE5B,YAAY,OAAsC;QAChD,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,KAAK,CAAC,+CAA+C,SAAS,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;CACF;AAED,MAAM,UAAU,6BAA6B,CAAC,GAAY;IACxD,OAAO,GAAG,YAAY,2BAA2B,CAAC;AACpD,CAAC;AAiBD,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAC7C,OAAO,CAAS;IAChB,IAAI,CAAuB;IAC3B,UAAU,CAAS;IAE5B,YAAY,OAAwC;QAClD,KAAK,CAAC,oDAAoD,4BAA4B,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxG,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;CACF;AAED,MAAM,UAAU,+BAA+B,CAAC,GAAY;IAC1D,OAAO,GAAG,YAAY,6BAA6B,CAAC;AACtD,CAAC"}

package/dist/workflow/guards.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowContext, WorkflowEvent } from './types.js';
+export type GuardFunction = (params: {
+    readonly context: WorkflowContext;
+    readonly event: WorkflowEvent;
+}) => boolean;
+export declare const guardImplementations: Readonly<Record<string, GuardFunction>>;
+/** Set of all registered guard names. Used by validation to check definitions. */
+export declare const REGISTERED_GUARDS: ReadonlySet<string>;

package/dist/workflow/guards.js

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// Guard implementations
+// ---------------------------------------------------------------------------
+/**
+ * Per-state round limit check. Compares the maximum visit count
+ * across all states against maxRounds. This fires when any state
+ * has been visited enough times to hit the limit.
+ *
+ * In the typical coder-critic loop, this checks whether the loop
+ * has iterated enough times to warrant escalation.
+ */
+const isRoundLimitReached = ({ context }) => {
+    const counts = Object.values(context.visitCounts);
+    if (counts.length === 0)
+        return false;
+    const maxVisits = Math.max(...counts);
+    return maxVisits >= context.maxRounds;
+};
+// Stubs for guards whose real logic lives in machine-builder.ts (they need
+// closure over per-state config or invoke-result data). These exist so the
+// names pass REGISTERED_GUARDS validation.
+const isStalled = () => false;
+const isStateVisitLimitReached = () => false;
+const isPassed = ({ event }) => {
+    return event.type === 'VALIDATION_PASSED';
+};
+// ---------------------------------------------------------------------------
+// Guard registry
+// ---------------------------------------------------------------------------
+export const guardImplementations = {
+    isRoundLimitReached,
+    isStalled,
+    isStateVisitLimitReached,
+    isPassed,
+};
+/** Set of all registered guard names. Used by validation to check definitions. */
+export const REGISTERED_GUARDS = new Set(Object.keys(guardImplementations));
+//# sourceMappingURL=guards.js.map

package/dist/workflow/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/workflow/guards.ts"],"names":[],"mappings":"AAQA,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAkB,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;IACzD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IACtC,OAAO,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;AACxC,CAAC,CAAC;AAEF,2EAA2E;AAC3E,2EAA2E;AAC3E,2CAA2C;AAC3C,MAAM,SAAS,GAAkB,GAAG,EAAE,CAAC,KAAK,CAAC;AAC7C,MAAM,wBAAwB,GAAkB,GAAG,EAAE,CAAC,KAAK,CAAC;AAE5D,MAAM,QAAQ,GAAkB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;IAC5C,OAAO,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC;AAC5C,CAAC,CAAC;AAEF,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,oBAAoB,GAA4C;IAC3E,mBAAmB;IACnB,SAAS;IACT,wBAAwB;IACxB,QAAQ;CACT,CAAC;AAEF,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC"}

package/dist/workflow/lint-integration.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared pre-flight lint integration used by both the CLI and the daemon.
+ * UI-agnostic: returns a `PreflightResult` that callers format themselves
+ * (stderr for CLI, JSON-RPC error data for the daemon).
+ */
+import { type Diagnostic, type LintContext } from './lint.js';
+import type { WorkflowDefinition } from './types.js';
+/**
+ * Default `LintContext` shared by both the CLI and the daemon. Backed by the
+ * real filesystem-resolving `personaExists` from `src/persona/resolve.ts`.
+ */
+export declare const defaultLintContext: LintContext;
+/**
+ * How strict the pre-flight should be:
+ * - `off`   : skip linting entirely; always ok.
+ * - `warn`  : fail only on error-severity diagnostics; warnings pass.
+ * - `strict`: fail on any diagnostic, including warnings.
+ */
+export type LintMode = 'off' | 'warn' | 'strict';
+export interface PreflightResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function preflightLint(definition: WorkflowDefinition, context: LintContext, mode: LintMode): PreflightResult;
+/**
+ * Discriminated result for {@link runPreflight}. Three variants:
+ *
+ * - `{ ok: true, ... }`: the definition loaded and lint either had no
+ *   diagnostics or had only diagnostics tolerated by `mode`. `warnings`
+ *   counts the (passing) warnings present.
+ * - `{ ok: false, kind: 'load', ... }`: the definition file could not be
+ *   parsed or did not validate. `loadKind` distinguishes the two.
+ * - `{ ok: false, kind: 'lint', ... }`: the definition loaded but lint
+ *   produced diagnostics that fail `mode`. The definition is still returned
+ *   so callers can render it alongside the diagnostics.
+ */
+export type RunPreflightResult = {
+    ok: true;
+    definition: WorkflowDefinition;
+    diagnostics: readonly Diagnostic[];
+    warnings: number;
+} | {
+    ok: false;
+    kind: 'load';
+    loadKind: 'parse' | 'validate';
+    message: string;
+} | {
+    ok: false;
+    kind: 'lint';
+    definition: WorkflowDefinition;
+    diagnostics: readonly Diagnostic[];
+    errors: number;
+    warnings: number;
+};
+/**
+ * Loads + validates a definition from `definitionPath`, then runs
+ * {@link preflightLint} with a {@link LintContext} derived from
+ * {@link defaultLintContext} but bound to `definitionPath` so
+ * package-relative checks (currently WF010 — skill references) can
+ * resolve sibling resources. Never throws — returns a discriminated
+ * result that callers map to their own error surfaces (stderr+exit
+ * for CLI, RpcError for the daemon).
+ */
+export declare function runPreflight(definitionPath: string, mode: LintMode): RunPreflightResult;

package/dist/workflow/lint-integration.js

@@ -0,0 +1,56 @@
+/**
+ * Shared pre-flight lint integration used by both the CLI and the daemon.
+ * UI-agnostic: returns a `PreflightResult` that callers format themselves
+ * (stderr for CLI, JSON-RPC error data for the daemon).
+ */
+import { countBySeverity, lintWorkflow } from './lint.js';
+import { personaExists } from '../persona/resolve.js';
+import { loadDefinition } from './definition-loader.js';
+/**
+ * Default `LintContext` shared by both the CLI and the daemon. Backed by the
+ * real filesystem-resolving `personaExists` from `src/persona/resolve.ts`.
+ */
+export const defaultLintContext = { personaExists };
+export function preflightLint(definition, context, mode) {
+    if (mode === 'off')
+        return { ok: true, diagnostics: [] };
+    const diagnostics = lintWorkflow(definition, context);
+    const { errors } = countBySeverity(diagnostics);
+    const failed = mode === 'strict' ? diagnostics.length > 0 : errors > 0;
+    return { ok: !failed, diagnostics };
+}
+/**
+ * Loads + validates a definition from `definitionPath`, then runs
+ * {@link preflightLint} with a {@link LintContext} derived from
+ * {@link defaultLintContext} but bound to `definitionPath` so
+ * package-relative checks (currently WF010 — skill references) can
+ * resolve sibling resources. Never throws — returns a discriminated
+ * result that callers map to their own error surfaces (stderr+exit
+ * for CLI, RpcError for the daemon).
+ */
+export function runPreflight(definitionPath, mode) {
+    const loaded = loadDefinition(definitionPath);
+    if (!loaded.ok) {
+        return { ok: false, kind: 'load', loadKind: loaded.kind, message: loaded.message };
+    }
+    const ctx = { ...defaultLintContext, workflowFilePath: definitionPath };
+    const lintResult = preflightLint(loaded.definition, ctx, mode);
+    const { errors, warnings } = countBySeverity(lintResult.diagnostics);
+    if (lintResult.ok) {
+        return {
+            ok: true,
+            definition: loaded.definition,
+            diagnostics: lintResult.diagnostics,
+            warnings,
+        };
+    }
+    return {
+        ok: false,
+        kind: 'lint',
+        definition: loaded.definition,
+        diagnostics: lintResult.diagnostics,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=lint-integration.js.map

package/dist/workflow/lint-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-integration.js","sourceRoot":"","sources":["../../src/workflow/lint-integration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAqC,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgB,EAAE,aAAa,EAAE,CAAC;AAejE,MAAM,UAAU,aAAa,CAAC,UAA8B,EAAE,OAAoB,EAAE,IAAc;IAChG,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAEzD,MAAM,WAAW,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAEvE,OAAO,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;AACtC,CAAC;AAoCD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,cAAsB,EAAE,IAAc;IACjE,MAAM,MAAM,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACrF,CAAC;IAED,MAAM,GAAG,GAAgB,EAAE,GAAG,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACrF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAErE,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,EAAE,EAAE,IAAI;YACR,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,MAAM;QACZ,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/workflow/lint.d.ts

@@ -0,0 +1,66 @@
+import type { WorkflowDefinition } from './types.js';
+/**
+ * Diagnostic codes.
+ *
+ * WF008 occupies the slot previously used for a raw-YAML check that
+ * `maxVisits` is only declared on agent states. That check now throws
+ * `WorkflowValidationError` before lint runs, so it never emits a WF code;
+ * the slot is reclaimed here for the visit-cap transition-ordering rule.
+ * WF009 is retired for the same reason (state-ID regex is a validation
+ * error) and must not be reused.
+ *
+ * WF005 (parallelKey + worktree needs gitRepoPath) is retired: the
+ * `parallelKey` schema field was removed as unused, so the trigger
+ * condition can no longer fire. Must not be reused.
+ *
+ * WF010 covers two related concerns under a single code:
+ *   1. State-scoped: an agent state's `skills:` entry is invalid or
+ *      doesn't match any discoverable skill in the package.
+ *   2. Package-scoped: a `SKILL.md` under the workflow package's
+ *      `skills/` tree is malformed, unreadable, or missing required
+ *      frontmatter fields. These are surfaced even when no state
+ *      references the broken skill, so authors get fast feedback on a
+ *      typo in frontmatter rather than discovering it via a "skill not
+ *      found" message at runtime.
+ *
+ * Both concerns are skipped cleanly when the lint caller did not
+ * supply a `workflowFilePath` (the package dir is the only place skill
+ * manifests can live).
+ */
+export type DiagnosticCode = 'WF001' | 'WF002' | 'WF003' | 'WF004' | 'WF006' | 'WF007' | 'WF008' | 'WF010';
+export type DiagnosticSeverity = 'error' | 'warning';
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly stateId?: string;
+    readonly hint?: string;
+}
+/**
+ * Injected facts the linter cannot derive from the definition alone.
+ *
+ * Kept minimal: methods/fields are added only when a new check
+ * genuinely needs external context.
+ */
+export interface LintContext {
+    /** Returns true iff the named persona is installed locally. */
+    personaExists(name: string): boolean;
+    /**
+     * Absolute path to the workflow file being linted, when known. Used
+     * by checks that resolve co-packaged resources off the manifest's
+     * directory (currently WF010 — skill references). Lint callers that
+     * do not have a path on hand (e.g., synthesized definitions in tests)
+     * may omit this; rules that need it skip cleanly when absent.
+     */
+    readonly workflowFilePath?: string;
+}
+export type LintResult = readonly Diagnostic[];
+/**
+ * Runs all registered checks against `def`. Pure: same input => same
+ * output. Diagnostics come back in stable order (WF001 first, WF007 last).
+ */
+export declare function lintWorkflow(def: WorkflowDefinition, ctx: LintContext): LintResult;
+export declare function countBySeverity(diagnostics: readonly Diagnostic[]): {
+    errors: number;
+    warnings: number;
+};