adispatchd 0.0.0-stage → 0.1.0

package/dist/lifecycle/context.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Run context for lifecycle actions: the run's configuration snapshot
+ * (Spec §12, §19), placeholder values/scope for hook actions (WI-02 table
+ * "Platzhalter-Scopes") and the JSON context handed to `shell` actions.
+ */
+import { WORKER_PROTOCOL_VERSION, type HookName, type IdentityRef, type SourceItem, type TemplateScope, type TemplateValues } from '../core/index.js';
+import { type LifecycleActionConfig, type WorkflowSnapshot } from '../config/index.js';
+import type { RunRecord } from '../persistence/index.js';
+/**
+ * Validate and return the workflow snapshot stored with a run
+ * (`runs.config_snapshot`). Hooks always run against this snapshot, never
+ * against the currently active configuration.
+ *
+ * @throws LifecycleError `lifecycle_invalid_snapshot`
+ */
+export declare function parseRunSnapshot(value: unknown, runId?: string): WorkflowSnapshot;
+/** True for workflows whose runs are bound to a source item (WI-02: `trigger.type: source`). */
+export declare function isSourceWorkflow(snapshot: WorkflowSnapshot): boolean;
+/**
+ * Write identity of an action: action `identity` (only `source.comment`) →
+ * workflow `identity` → source `identity` (WI-02, Spec §5.2).
+ */
+export declare function resolveActionIdentity(action: LifecycleActionConfig, snapshot: WorkflowSnapshot): IdentityRef | null;
+/** Placeholder scope of hook actions (WI-02): `result` everywhere except `on_start`. */
+export declare function hookTemplateScope(snapshot: WorkflowSnapshot, hook: HookName): TemplateScope;
+/** Minimal item derived from the run when the source item is not available. */
+export declare function itemFromRun(run: RunRecord): SourceItem | null;
+/** Input for {@link buildHookTemplateValues}. */
+export interface HookValueInput {
+    run: RunRecord;
+    snapshot: WorkflowSnapshot;
+    hook: HookName;
+    /** Item (fresh or derived from the run); `null` for sourceless runs. */
+    item: SourceItem | null;
+    /** `{source.repository}` (adapter's value); defaults to `owner/repository` of the snapshot source. */
+    repository?: string;
+    now: Date;
+}
+/** Placeholder values for a hook action of `run`. Result values only outside `on_start`. */
+export declare function buildHookTemplateValues(input: HookValueInput): TemplateValues;
+/**
+ * Render a hook-action text template. Unknown placeholders and placeholders
+ * outside the hook's scope (e.g. `{result.message}` in `on_start`) are
+ * rejected with a `TemplateError`, even if config validation was bypassed.
+ */
+export declare function renderHookText(template: string, values: TemplateValues, scope: TemplateScope): string;
+/** JSON context written to `ADISPATCH_CONTEXT_FILE` for `shell` actions. */
+export type ShellActionContext = {
+    schema_version: typeof WORKER_PROTOCOL_VERSION;
+    kind: 'lifecycle_action';
+    run: {
+        id: string;
+        trigger: string;
+        status: string;
+        started_at: string | null;
+        finished_at: string | null;
+    };
+    workflow: {
+        id: string;
+        name: string;
+    };
+    hook: HookName;
+    action: {
+        id: number;
+        name: string | null;
+        ordinal: number;
+        type: 'shell';
+        attempt: number;
+    };
+    /** Shape of `WorkerContext.source` (sets `ADISPATCH_SOURCE_*`). */
+    source?: {
+        id: string;
+        type: string;
+        item_id: string;
+        item_key: string;
+        url: string;
+        attributes: Record<string, unknown>;
+    };
+    parameters: Record<string, string | number | boolean>;
+    workspace: {
+        path: string | null;
+        base_dir: string;
+    };
+    /** Final run outcome and worker result; `null` in `on_start`. */
+    result: {
+        status: string | null;
+        result: string | null;
+        reason: string | null;
+        message: string | null;
+        details: unknown;
+        artifacts: unknown;
+    } | null;
+};
+/** Build the context of a `shell` action. Contains no secrets. */
+export declare function buildShellActionContext(input: {
+    run: RunRecord;
+    snapshot: WorkflowSnapshot;
+    hook: HookName;
+    item: SourceItem | null;
+    action: {
+        id: number;
+        name: string | null;
+        ordinal: number;
+        attempt: number;
+    };
+}): ShellActionContext;

package/dist/lifecycle/context.js

@@ -0,0 +1,170 @@
+/**
+ * Run context for lifecycle actions: the run's configuration snapshot
+ * (Spec §12, §19), placeholder values/scope for hook actions (WI-02 table
+ * "Platzhalter-Scopes") and the JSON context handed to `shell` actions.
+ */
+import { WORKER_PROTOCOL_VERSION, buildTemplateValues, parseSourceItemKey, renderTemplate, } from '../core/index.js';
+import { WORKFLOW_SNAPSHOT_VERSION } from '../config/index.js';
+import { LifecycleError } from './errors.js';
+/**
+ * Validate and return the workflow snapshot stored with a run
+ * (`runs.config_snapshot`). Hooks always run against this snapshot, never
+ * against the currently active configuration.
+ *
+ * @throws LifecycleError `lifecycle_invalid_snapshot`
+ */
+export function parseRunSnapshot(value, runId) {
+    const s = value;
+    const ok = typeof s === 'object' &&
+        s !== null &&
+        s.schemaVersion === WORKFLOW_SNAPSHOT_VERSION &&
+        typeof s.workflow === 'object' &&
+        s.workflow !== null &&
+        typeof s.workflow.id === 'string' &&
+        typeof s.workflow.hooks === 'object' &&
+        s.workflow.hooks !== null &&
+        typeof s.workspace === 'object' &&
+        s.workspace !== null;
+    if (!ok) {
+        throw new LifecycleError('invalid_snapshot', `${runId !== undefined ? `Run ${runId}` : 'Run'} has no valid workflow configuration snapshot`, {
+            details: runId !== undefined ? { runId } : {},
+        });
+    }
+    return s;
+}
+/** True for workflows whose runs are bound to a source item (WI-02: `trigger.type: source`). */
+export function isSourceWorkflow(snapshot) {
+    return snapshot.workflow.trigger.type === 'source';
+}
+/**
+ * Write identity of an action: action `identity` (only `source.comment`) →
+ * workflow `identity` → source `identity` (WI-02, Spec §5.2).
+ */
+export function resolveActionIdentity(action, snapshot) {
+    if (action.type === 'source.comment' && action.identity)
+        return action.identity;
+    return snapshot.workflow.identity ?? snapshot.source?.identity ?? null;
+}
+/** Placeholder scope of hook actions (WI-02): `result` everywhere except `on_start`. */
+export function hookTemplateScope(snapshot, hook) {
+    return {
+        run: true,
+        workspace: true,
+        source: isSourceWorkflow(snapshot),
+        result: hook !== 'on_start',
+        parameters: Object.keys(snapshot.workflow.parameters ?? {}),
+    };
+}
+/** Minimal item derived from the run when the source item is not available. */
+export function itemFromRun(run) {
+    if (!run.sourceItemKey)
+        return null;
+    const { sourceId, itemId } = parseSourceItemKey(run.sourceItemKey);
+    return { sourceId, itemId, key: run.sourceItemKey, url: run.sourceUrl ?? '', type: 'unknown', fields: {} };
+}
+/** The worker result (`runs.result_json`) as plain object, if any. */
+function runResult(run) {
+    return typeof run.result === 'object' && run.result !== null ? run.result : null;
+}
+function scalarParameters(run) {
+    const out = {};
+    for (const [k, v] of Object.entries(run.parameters ?? {})) {
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+            out[k] = v;
+    }
+    return out;
+}
+/** Placeholder values for a hook action of `run`. Result values only outside `on_start`. */
+export function buildHookTemplateValues(input) {
+    const { run, snapshot, hook, item } = input;
+    const source = isSourceWorkflow(snapshot) ? snapshot.source : null;
+    const result = runResult(run);
+    const title = item?.fields.title;
+    return buildTemplateValues({
+        workflow: { id: snapshot.workflow.id, name: snapshot.workflow.name },
+        workspace: { baseDir: snapshot.workspace.baseDir, ...(run.workspacePath ? { path: run.workspacePath } : {}) },
+        run: {
+            id: run.id,
+            trigger: run.triggerType,
+            ...(run.startedAt ? { startedAt: new Date(run.startedAt) } : {}),
+        },
+        ...(source
+            ? { source: { id: source.id, type: source.type, repository: input.repository ?? `${source.owner}/${source.repository}` } }
+            : {}),
+        ...(source && item
+            ? {
+                item: {
+                    id: item.itemId,
+                    key: item.key,
+                    ...(/^\d+$/.test(item.itemId) ? { number: item.itemId } : {}),
+                    ...(item.url ? { url: item.url } : {}),
+                    ...(typeof title === 'string' ? { title } : {}),
+                },
+            }
+            : {}),
+        ...(hook !== 'on_start'
+            ? {
+                result: {
+                    ...(run.finalStatus ? { status: run.finalStatus } : {}),
+                    result: run.businessResult,
+                    ...(typeof result?.message === 'string' ? { message: result.message } : {}),
+                },
+            }
+            : {}),
+        parameters: scalarParameters(run),
+        now: input.now,
+    });
+}
+/**
+ * Render a hook-action text template. Unknown placeholders and placeholders
+ * outside the hook's scope (e.g. `{result.message}` in `on_start`) are
+ * rejected with a `TemplateError`, even if config validation was bypassed.
+ */
+export function renderHookText(template, values, scope) {
+    return renderTemplate(template, values, { mode: 'text', scope });
+}
+/** Build the context of a `shell` action. Contains no secrets. */
+export function buildShellActionContext(input) {
+    const { run, snapshot, hook, item } = input;
+    const result = runResult(run);
+    const source = isSourceWorkflow(snapshot) ? snapshot.source : null;
+    return {
+        schema_version: WORKER_PROTOCOL_VERSION,
+        kind: 'lifecycle_action',
+        run: {
+            id: run.id,
+            trigger: run.triggerType,
+            status: run.status,
+            started_at: run.startedAt,
+            finished_at: run.finishedAt,
+        },
+        workflow: { id: snapshot.workflow.id, name: snapshot.workflow.name },
+        hook,
+        action: { ...input.action, type: 'shell' },
+        ...(source && item
+            ? {
+                source: {
+                    id: source.id,
+                    type: source.type,
+                    item_id: item.itemId,
+                    item_key: item.key,
+                    url: item.url,
+                    attributes: { ...item.fields },
+                },
+            }
+            : {}),
+        parameters: scalarParameters(run),
+        workspace: { path: run.workspacePath, base_dir: snapshot.workspace.baseDir },
+        result: hook === 'on_start'
+            ? null
+            : {
+                status: run.finalStatus,
+                result: run.businessResult,
+                reason: run.finalReason,
+                message: typeof result?.message === 'string' ? result.message : null,
+                details: result?.details ?? null,
+                artifacts: result?.artifacts ?? null,
+            },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/lifecycle/context.js.map

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

package/dist/lifecycle/engine.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Lifecycle engine (Spec §10): journaled, sequential hook chains with
+ * per-action retries, manual retry/skip, chain continuation and recovery.
+ *
+ * Invariants:
+ * - Every action state change is persisted before work continues
+ *   (journal = `run_actions`, every attempt = `action_attempts`).
+ * - `succeeded`/`skipped` actions are never executed again.
+ * - Hooks always use the run's configuration snapshot (journal
+ *   `action_config_json` + `runs.config_snapshot`), never the live config.
+ * - Notifications and change callbacks are published only after commit.
+ */
+import { type Clock, type Executor, type HookName, type LifecycleStatus, type Logger, type Notifier, type SourceItem, type Timers, type Redactor } from '../core/index.js';
+import type { LifecycleActionConfig, RetryPolicy, WorkflowSnapshot } from '../config/index.js';
+import type { Repositories, RunActionRecord, RunRecord } from '../persistence/index.js';
+import { type ActionErrorInfo } from './errors.js';
+import { type SourceResolver } from './performers.js';
+/** Event type persisted in `run_events` for every action state change. */
+export declare const LIFECYCLE_ACTION_EVENT = "lifecycle.action";
+/** Event type persisted in `run_events` when a hook chain starts/ends. */
+export declare const LIFECYCLE_CHAIN_EVENT = "lifecycle.chain";
+/** Default retry policy if a journaled action carries none (Spec §5.1: 3 × 30 s). */
+export declare const DEFAULT_ACTION_RETRY: RetryPolicy;
+/** Outcome of executing (or continuing) one hook chain. */
+export interface HookResult {
+    runId: string;
+    hook: HookName;
+    /**
+     * - `succeeded`: every action is `succeeded`/`skipped` or failed with `continue_on_error`.
+     * - `failed`: the chain stopped at {@link HookResult.failedAction}; later actions stay `pending`.
+     * - `interrupted`: aborted via signal; the current action was reset to `pending` (resumable).
+     */
+    status: 'succeeded' | 'failed' | 'interrupted';
+    /** Final journal state of the hook (ordinal order). */
+    actions: RunActionRecord[];
+    /** Action that stopped the chain (`status === 'failed'`). */
+    failedAction: RunActionRecord | null;
+}
+/** Per-call options. */
+export interface HookContext {
+    /**
+     * Freshly read source item (WI-08 re-reads it before starting, Spec §7).
+     * Optional: if missing, source actions read the item via the adapter.
+     */
+    item?: SourceItem;
+    /** Aborts retry delays and running shell actions (shutdown). */
+    signal?: AbortSignal;
+    /**
+     * If another chain of the same run is executing: `true` = queue behind it
+     * (internal callers, e.g. WI-08 `runHook` while a manual retry runs);
+     * default `false` = reject immediately with {@link LifecycleBusyError} (API calls).
+     */
+    wait?: boolean;
+}
+/** Payload of the `lifecycle_action_failed` notification. */
+export interface LifecycleActionFailedPayload extends Record<string, unknown> {
+    runId: string;
+    workflowId: string;
+    hook: HookName;
+    actionId: number;
+    actionName: string | null;
+    actionType: string;
+    ordinal: number;
+    attempts: number;
+    error: ActionErrorInfo | null;
+    sourceItemKey: string | null;
+    sourceUrl: string | null;
+}
+/** Dependencies of {@link LifecycleEngine}. */
+export interface LifecycleEngineOptions {
+    /** Persistence (WI-03). */
+    repositories: Pick<Repositories, 'runs' | 'actions' | 'events' | 'transaction' | 'afterCommit'>;
+    /** Source adapters by configured source ID. */
+    sources: SourceResolver;
+    /** Data directory (context/log files of `shell` actions below `runs/<id>/actions`, `logs/<id>/actions`). */
+    dataDir: string;
+    /** Executor for `shell` actions; default `new ShellExecutor({ clock, logger })` (minimal env, no controller env). */
+    executor?: Executor;
+    clock?: Clock;
+    /** Timers for retry delays (FakeClock in tests). */
+    timers?: Timers;
+    logger?: Logger;
+    /** Receives `lifecycle_action_failed` after commit (delivery: WI-10). Must not throw/block. */
+    notifier?: Notifier;
+    /** Called after commit for every persisted action change (event bus / SSE in WI-08/WI-10). */
+    onActionChange?: (action: RunActionRecord) => void;
+    /** Best-effort redaction of persisted error texts (e.g. `SecretRedactor.asRedactor`). */
+    redact?: Redactor;
+    /** SIGTERM → SIGKILL grace for `shell` actions. Default 5 s. */
+    shellCancelGraceMs?: number;
+    /** Log limit per `shell` action attempt (stdout + stderr). Default 10 MiB. */
+    maxShellLogBytes?: number;
+}
+/** See module docs. One instance per process; chains of one run never execute concurrently. */
+export declare class LifecycleEngine {
+    private readonly options;
+    private readonly repos;
+    private readonly clock;
+    private readonly timers;
+    private readonly logger;
+    private readonly redact;
+    private readonly performerDeps;
+    /** Tail of the per-run execution queue (present while a chain of the run runs or waits). */
+    private readonly tails;
+    constructor(options: LifecycleEngineOptions);
+    /** True while a chain of `runId` is executing in this process. */
+    isBusy(runId: string): boolean;
+    /**
+     * Run hook `hook` of a run: creates the journal for all actions of the hook
+     * from the snapshot (stable IDs, ordinals, `action_config_json`) and
+     * executes them sequentially. Idempotent/resumable: an existing journal is
+     * reused and only `pending` actions run (a `failed` action without
+     * `continue_on_error` keeps the chain stopped — use {@link retryAction}).
+     *
+     * @param snapshot defaults to `run.configSnapshot` (must be the run's snapshot, never the live config)
+     * @throws LifecycleBusyError if a chain of this run is already executing
+     */
+    runHook(run: RunRecord | string, hook: HookName, snapshot?: WorkflowSnapshot, context?: HookContext): Promise<HookResult>;
+    /**
+     * Manual retry (GUI "Retry Action"): the `failed` action gets a fresh round
+     * of attempts (its retry policy), then the chain continues from there. The
+     * main worker is not involved; `succeeded` actions are never repeated.
+     *
+     * @throws LifecycleError `lifecycle_not_retryable` if the action is not `failed`
+     */
+    retryAction(actionId: number, context?: HookContext): Promise<HookResult>;
+    /**
+     * Operator skips a `failed` (or `pending`) action; the chain then continues
+     * after it (e.g. the operator fixed the item manually).
+     */
+    skipAction(actionId: number, context?: HookContext): Promise<HookResult>;
+    /**
+     * Recovery after a controller restart (WI-08, Spec §14): actions left
+     * `running` are brought into a safe state, then every incomplete chain of
+     * the run is continued (in journal order). Safe state:
+     * - `source.comment`: marker lookup; found → `succeeded` (no duplicate), else `pending`
+     *   (the next attempt looks up the marker again before posting).
+     * - `source.update`: `pending` (re-applied idempotently after re-reading the item).
+     * - `shell`: with an unfinished attempt the outcome is unknown and the old process
+     *   may still run → `failed` (chain stops, manual retry); otherwise `pending`.
+     *
+     * @param options.hooks only continue these hooks (others are only made safe)
+     */
+    resumeIncomplete(run: RunRecord | string, options?: HookContext & {
+        hooks?: readonly HookName[];
+    }): Promise<HookResult[]>;
+    /**
+     * Abandon the rest of a hook chain (WI-08 recovery, e.g. an interrupted
+     * `on_start` of a run that is now finalized as `crashed`): interrupted
+     * actions are made safe (comment marker lookup), all `pending` ones become `skipped`.
+     */
+    abandonHook(run: RunRecord | string, hook: HookName, context?: Pick<HookContext, 'item' | 'wait'>): Promise<HookResult>;
+    /**
+     * Serialize chain executions per run. Without `wait` a busy run is rejected
+     * immediately ({@link LifecycleBusyError}, API callers); with `wait` the call
+     * is queued behind the running/queued ones (internal callers such as WI-08).
+     */
+    private exclusive;
+    private executeChain;
+    private executeActions;
+    private hookResult;
+    /** Execute one action with its retry policy. The action is `pending` on entry. */
+    private executeAction;
+    private perform;
+    /** Bring an action left `running` (crash/restart) into a safe state, see {@link resumeIncomplete}. */
+    private makeSafe;
+    private persistActionStatus;
+    private appendActionEvent;
+    private publishChange;
+    private queueFailureNotification;
+    /** Recompute `runs.lifecycle_status` from the whole journal of the run. */
+    private refreshLifecycleStatus;
+    /** Hooks of a run in journal order. */
+    private hooksInOrder;
+}
+/** Action config persisted in the journal (`action_config_json`). */
+export declare function actionConfig(action: RunActionRecord): LifecycleActionConfig;
+/** First `failed` action without `continue_on_error` (the chain stops there), else `null`. */
+export declare function stoppedAt(journal: readonly RunActionRecord[]): RunActionRecord | null;
+/**
+ * Aggregate `runs.lifecycle_status` over all hook chains of a run:
+ * `running` if an action runs, else `failed` if any chain stopped at a failed
+ * action, else `pending` if actions wait, else `succeeded`; `null` without journal.
+ */
+export declare function aggregateLifecycleStatus(actions: readonly RunActionRecord[]): LifecycleStatus | null;