adispatchd 0.0.0-stage → 0.1.0

package/dist/config/loader.d.ts

@@ -0,0 +1,32 @@
+import { type Clock } from '../core/index.js';
+import type { ConfigIssue, LoadedConfig } from './model.js';
+/** Sub-directory with one file per workflow. */
+export declare const WORKFLOWS_DIR = "workflows";
+/** Sub-directory with one file per view. */
+export declare const VIEWS_DIR = "views";
+/** Maximum accepted size of a single YAML file. */
+export declare const MAX_CONFIG_FILE_BYTES: number;
+/** Options for {@link loadConfig}. */
+export interface LoadConfigOptions {
+    /** Data directory; used for the default `workspace.base_dir` (`${dataDir}/workspaces`). */
+    dataDir: string;
+    /** Version number stored in the result (default 1). */
+    version?: number;
+    clock?: Clock;
+}
+/** Result of {@link loadConfig}. Warnings never prevent loading. */
+export type LoadConfigResult = {
+    ok: true;
+    config: LoadedConfig;
+    warnings: ConfigIssue[];
+} | {
+    ok: false;
+    errors: ConfigIssue[];
+    warnings: ConfigIssue[];
+};
+/** Load and validate the configuration in `configDir`. Never throws for config problems. */
+export declare function loadConfig(configDir: string, options: LoadConfigOptions): Promise<LoadConfigResult>;
+/** Canonical JSON (sorted object keys) for hashing. */
+export declare function canonicalJson(value: unknown): string;
+/** Recursively freeze an object graph. */
+export declare function deepFreeze<T>(value: T): T;

package/dist/config/loader.js

@@ -0,0 +1,250 @@
+/**
+ * Config loader (Spec §19): reads the config directory, parses YAML,
+ * validates schemas and cross-file semantics, collects **all** problems with
+ * file and path, and produces an immutable {@link LoadedConfig}.
+ *
+ * The loader never reads environment variables, so no secret value can end
+ * up in the loaded model or in issue messages.
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { isMap, isSeq, LineCounter, parseDocument } from 'yaml';
+import { systemClock, toAbsolutePath } from '../core/index.js';
+import { formatIssuePath, IssueCollector, sortIssues } from './issues.js';
+import { normalizeGlobal, normalizeIdentities, normalizeSources, normalizeView, normalizeWorkflow, } from './normalize.js';
+import { globalConfigSchema, identitiesFileSchema, sourcesFileSchema, viewSchema, workflowSchema, } from './schemas.js';
+import { CONFIG_FILE, IDENTITIES_FILE, SOURCES_FILE, validateSemantics, } from './validate.js';
+/** Sub-directory with one file per workflow. */
+export const WORKFLOWS_DIR = 'workflows';
+/** Sub-directory with one file per view. */
+export const VIEWS_DIR = 'views';
+/** Maximum accepted size of a single YAML file. */
+export const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+/** Load and validate the configuration in `configDir`. Never throws for config problems. */
+export async function loadConfig(configDir, options) {
+    const dir = toAbsolutePath(configDir);
+    const issues = new IssueCollector();
+    const files = new Map();
+    const clock = options.clock ?? systemClock;
+    try {
+        const st = await stat(dir);
+        if (!st.isDirectory())
+            issues.error('.', [], `Config path "${dir}" is not a directory`);
+    }
+    catch {
+        issues.error('.', [], `Config directory "${dir}" does not exist or is not readable`);
+    }
+    if (issues.hasErrors)
+        return finish(issues, files);
+    const readTop = async (name, warnIfMissing) => {
+        const parsed = await readYaml(dir, name, issues);
+        if (parsed === null) {
+            if (warnIfMissing)
+                issues.warning(name, [], `${name} not found, using defaults`);
+            return undefined;
+        }
+        if (parsed)
+            files.set(name, parsed);
+        return parsed;
+    };
+    const configFile = await readTop(CONFIG_FILE, true);
+    const sourcesFile = await readTop(SOURCES_FILE, false);
+    const identitiesFile = await readTop(IDENTITIES_FILE, false);
+    const workflowFiles = await readDir(dir, WORKFLOWS_DIR, issues, files);
+    const viewFiles = await readDir(dir, VIEWS_DIR, issues, files);
+    const rawGlobal = parseWith(globalConfigSchema, configFile, CONFIG_FILE, issues);
+    const rawSources = parseWith(sourcesFileSchema, sourcesFile, SOURCES_FILE, issues);
+    const rawIdentities = parseWith(identitiesFileSchema, identitiesFile, IDENTITIES_FILE, issues);
+    // Without valid global settings, workflows can still be checked against defaults.
+    const global = normalizeGlobal(rawGlobal ?? globalConfigSchema.parse({}), dir, options.dataDir);
+    const sources = rawSources ? normalizeSources(rawSources) : {};
+    const identities = rawIdentities ? normalizeIdentities(rawIdentities) : {};
+    const workflowEntries = [];
+    for (const parsed of workflowFiles) {
+        const raw = parseWith(workflowSchema, parsed, parsed.file, issues);
+        if (raw) {
+            workflowEntries.push({ workflow: normalizeWorkflow(raw, parsed.file, global, dir), rawParameters: raw.parameters });
+        }
+    }
+    const viewEntries = [];
+    for (const parsed of viewFiles) {
+        const raw = parseWith(viewSchema, parsed, parsed.file, issues);
+        if (raw)
+            viewEntries.push({ view: normalizeView(raw, parsed.file), hasShellFilter: raw.shell_filter !== undefined });
+    }
+    validateSemantics({ global, sources, identities, workflows: workflowEntries, views: viewEntries }, issues);
+    if (issues.hasErrors)
+        return finish(issues, files);
+    const workflows = {};
+    const workflowHashes = {};
+    for (const { workflow } of workflowEntries) {
+        workflows[workflow.id] = workflow;
+        workflowHashes[workflow.id] = hashOf(workflow);
+    }
+    const views = {};
+    for (const { view } of viewEntries)
+        views[view.id] = view;
+    const content = { global, sources, identities, workflows, views };
+    const config = {
+        configDir: dir,
+        version: options.version ?? 1,
+        hash: hashOf(content),
+        loadedAt: new Date(clock.now()).toISOString(),
+        ...content,
+        workflowHashes,
+    };
+    const result = finish(issues, files);
+    return { ok: true, config: deepFreeze(config), warnings: result.warnings };
+}
+function finish(issues, files) {
+    const resolved = issues.items.map((item) => {
+        const line = item.line ?? lineOf(files.get(item.file), item.path);
+        return {
+            severity: item.severity,
+            file: item.file,
+            path: formatIssuePath(item.path),
+            message: item.message,
+            ...(line !== undefined ? { line } : {}),
+        };
+    });
+    const sorted = sortIssues(resolved);
+    return {
+        ok: false,
+        errors: sorted.filter((i) => i.severity === 'error'),
+        warnings: sorted.filter((i) => i.severity === 'warning'),
+    };
+}
+/**
+ * Read and parse one YAML file. Returns `null` if the file does not exist,
+ * `undefined` if it exists but is unusable (issue recorded).
+ */
+async function readYaml(dir, file, issues) {
+    const full = path.join(dir, file);
+    let text;
+    try {
+        const st = await stat(full);
+        if (!st.isFile()) {
+            issues.error(file, [], 'Not a regular file');
+            return undefined;
+        }
+        if (st.size > MAX_CONFIG_FILE_BYTES) {
+            issues.error(file, [], `File is larger than ${MAX_CONFIG_FILE_BYTES} bytes`);
+            return undefined;
+        }
+        text = await readFile(full, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        issues.error(file, [], `Cannot read file: ${err.code ?? 'error'}`);
+        return undefined;
+    }
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(text, { lineCounter, prettyErrors: false, uniqueKeys: true });
+    for (const err of doc.errors) {
+        issues.error(file, [], `YAML syntax error: ${firstLine(err.message)}`, lineCounter.linePos(err.pos[0]).line);
+    }
+    if (doc.errors.length > 0)
+        return undefined;
+    for (const warn of doc.warnings) {
+        issues.warning(file, [], `YAML: ${firstLine(warn.message)}`, lineCounter.linePos(warn.pos[0]).line);
+    }
+    let data;
+    try {
+        data = doc.toJS({ maxAliasCount: 100 });
+    }
+    catch (err) {
+        issues.error(file, [], `YAML error: ${firstLine(err.message)}`);
+        return undefined;
+    }
+    return { file, doc, lineCounter, data: data ?? {} };
+}
+function firstLine(message) {
+    return message.split('\n')[0] ?? message;
+}
+async function readDir(dir, sub, issues, files) {
+    let names;
+    try {
+        names = await readdir(path.join(dir, sub));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        issues.error(sub, [], `Cannot read directory: ${err.code ?? 'error'}`);
+        return [];
+    }
+    const out = [];
+    for (const name of names.filter((n) => /\.ya?ml$/.test(n) && !n.startsWith('.')).sort()) {
+        const file = `${sub}/${name}`;
+        const parsed = await readYaml(dir, file, issues);
+        if (parsed) {
+            files.set(file, parsed);
+            out.push(parsed);
+        }
+    }
+    return out;
+}
+function parseWith(schema, parsed, file, issues) {
+    const data = parsed ? parsed.data : {};
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        issues.error(file, [], 'Top level must be a mapping');
+        return undefined;
+    }
+    const result = schema.safeParse(data);
+    if (result.success)
+        return result.data;
+    for (const issue of result.error.issues) {
+        const at = issue.path.filter((p) => typeof p !== 'symbol');
+        let message = issue.message;
+        if (issue.code === 'unrecognized_keys') {
+            message = `Unknown key(s): ${issue.keys.map((k) => `"${k}"`).join(', ')}`;
+        }
+        issues.error(file, at, message);
+    }
+    return undefined;
+}
+/** Find the 1-based line of the deepest existing node along `issuePath`. */
+function lineOf(parsed, issuePath) {
+    if (!parsed?.doc)
+        return undefined;
+    let node = parsed.doc.contents;
+    let found = node;
+    for (const segment of issuePath) {
+        if (isMap(node))
+            node = node.get(segment, true);
+        else if (isSeq(node) && typeof segment === 'number')
+            node = node.get(segment, true);
+        else
+            break;
+        if (node === undefined || node === null)
+            break;
+        found = node;
+    }
+    const range = found?.range;
+    if (!range)
+        return undefined;
+    return parsed.lineCounter.linePos(range[0]).line;
+}
+/** Canonical JSON (sorted object keys) for hashing. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        }
+        return v;
+    });
+}
+function hashOf(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+/** Recursively freeze an object graph. */
+export function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

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

package/dist/config/manager.d.ts

@@ -0,0 +1,153 @@
+/**
+ * ConfigManager (Spec §19): holds the active configuration, reloads it
+ * atomically (all-or-nothing) and manages non-persistent runtime overrides.
+ */
+import { OrchestratorError, type Clock, type Logger, type Unsubscribe } from '../core/index.js';
+import { type LoadConfigOptions, type LoadConfigResult } from './loader.js';
+import type { ConfigIssue, LoadedConfig, WorkflowConfig } from './model.js';
+import { type ParameterValidationResult } from './parameters.js';
+import { type WorkflowSnapshot } from './snapshot.js';
+/** Runtime overrides of one workflow (not persisted, Spec §19). */
+export interface WorkflowOverrides {
+    enabled?: boolean;
+    priority?: number;
+    maxConcurrent?: number;
+}
+/** Runtime overrides of global settings. */
+export interface GlobalOverrides {
+    maxConcurrent?: number;
+}
+/** A workflow with its effective (override-applied) scheduling values. */
+export interface EffectiveWorkflow {
+    config: WorkflowConfig;
+    enabled: boolean;
+    priority: number;
+    maxConcurrent: number;
+    /** Currently active overrides (empty object if none). */
+    overrides: Readonly<WorkflowOverrides>;
+}
+/** Changes detected by a successful reload. */
+export interface ConfigDiff {
+    addedWorkflows: string[];
+    removedWorkflows: string[];
+    changedWorkflows: string[];
+}
+/** Result of {@link ConfigManager.reload}. */
+export type ReloadResult = {
+    ok: true;
+    config: LoadedConfig;
+    previous: LoadedConfig;
+    /** False if the content hash is unchanged (the version still increases). */
+    changed: boolean;
+    diff: ConfigDiff;
+    /**
+     * Workflows with at least one reset override (a field is reset when its
+     * configured value changed or the workflow was removed), plus `"*"` if the
+     * global override was reset.
+     */
+    resetOverrides: string[];
+    warnings: ConfigIssue[];
+} | {
+    ok: false;
+    errors: ConfigIssue[];
+    warnings: ConfigIssue[];
+};
+/** Event delivered to {@link ConfigManager.onChange} listeners. */
+export type ConfigChangeEvent = {
+    kind: 'reload';
+    config: LoadedConfig;
+    previous: LoadedConfig;
+    diff: ConfigDiff;
+    resetOverrides: string[];
+} | {
+    kind: 'overrides';
+    workflowId: string | null;
+};
+/** Listener for configuration changes. Must not throw (errors are logged). */
+export type ConfigChangeListener = (event: ConfigChangeEvent) => void;
+/** Thrown by {@link ConfigManager.create} when the initial configuration is invalid. */
+export declare class ConfigLoadError extends OrchestratorError {
+    readonly errors: ConfigIssue[];
+    readonly warnings: ConfigIssue[];
+    constructor(errors: ConfigIssue[], warnings: ConfigIssue[]);
+}
+/** Loader signature (injectable for tests). */
+export type ConfigLoader = (configDir: string, options: LoadConfigOptions) => Promise<LoadConfigResult>;
+/** Options for {@link ConfigManager}. */
+export interface ConfigManagerOptions {
+    configDir: string;
+    dataDir: string;
+    clock?: Clock;
+    logger?: Logger;
+    loader?: ConfigLoader;
+}
+/**
+ * Holds the active {@link LoadedConfig}. Use {@link ConfigManager.create} to
+ * load the initial configuration.
+ */
+export declare class ConfigManager {
+    private readonly options;
+    private active;
+    private workflowOverrides;
+    private globalOverrides;
+    private readonly listeners;
+    private reloadChain;
+    private readonly clock;
+    private readonly logger;
+    private readonly loader;
+    /** Use {@link ConfigManager.create} unless you already have a loaded config. */
+    constructor(initial: LoadedConfig, options: ConfigManagerOptions);
+    /**
+     * Load the configuration and create a manager.
+     * @throws ConfigLoadError if the configuration is invalid.
+     */
+    static create(options: ConfigManagerOptions): Promise<ConfigManager>;
+    /** The active configuration (immutable). */
+    get current(): LoadedConfig;
+    /**
+     * Reload the whole configuration. Only if loading and validation succeed
+     * completely is the new configuration activated (atomically); otherwise the
+     * active configuration stays untouched and the errors are returned.
+     * Concurrent calls are serialized.
+     */
+    reload(): Promise<ReloadResult>;
+    private doReload;
+    /** Register a change listener. */
+    onChange(listener: ConfigChangeListener): Unsubscribe;
+    private emit;
+    private requireWorkflow;
+    /** Workflow with effective values, or `undefined` if unknown. */
+    getWorkflow(workflowId: string): EffectiveWorkflow | undefined;
+    /** All workflows with effective values, sorted by ID. */
+    listWorkflows(): EffectiveWorkflow[];
+    private effective;
+    /** Effective global limit for automatic starts. */
+    get maxConcurrent(): number;
+    /** Current overrides (copies). */
+    getOverrides(): {
+        global: GlobalOverrides;
+        workflows: Record<string, WorkflowOverrides>;
+    };
+    /**
+     * Merge runtime overrides into the workflow's existing overrides. A key
+     * with value `undefined` removes that override.
+     * @throws UnknownWorkflowError, ValidationError
+     */
+    setWorkflowOverrides(workflowId: string, overrides: WorkflowOverrides): EffectiveWorkflow;
+    /** Remove all overrides of a workflow. */
+    clearWorkflowOverrides(workflowId: string): void;
+    /**
+     * Override (number) or reset (`undefined`) the global `max_concurrent`.
+     * @throws ValidationError
+     */
+    setGlobalMaxConcurrent(value: number | undefined): void;
+    /** Snapshot of a workflow of the active configuration (see {@link snapshotWorkflow}). */
+    snapshotWorkflow(workflowId: string): WorkflowSnapshot;
+    /**
+     * Validate manual-start parameters against the workflow's parameter schema.
+     * @throws UnknownWorkflowError
+     */
+    validateParameters(workflowId: string, input: Readonly<Record<string, unknown>> | undefined): ParameterValidationResult;
+}
+/** Compare the workflows of two configurations by their hashes. */
+export declare function diffWorkflows(previous: LoadedConfig, next: LoadedConfig): ConfigDiff;