adispatchd 0.0.0-stage → 0.1.0

package/dist/core/logger.js

@@ -0,0 +1,207 @@
+/**
+ * Minimal structured logging with secret redaction (Spec §20.4).
+ *
+ * Log records are JSON lines: `{ time, level, msg, ...bindings, ...fields }`.
+ * Every record passes through a redaction hook before it is written, so known
+ * secret values and secret-looking keys never reach the sink.
+ */
+import { systemClock } from './clock.js';
+/** Replacement text for redacted values. */
+export const REDACTED = '[REDACTED]';
+const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * Keys whose values are always redacted, regardless of content. Matched
+ * against the key's last segment (camelCase is split first), so `GH_TOKEN`,
+ * `accessToken`, `x-api-key`, `privateKey`, `password` match, while
+ * `passed`, `bypass` or `tokens_used` do not.
+ */
+const SECRET_KEY_PATTERN = /(^|[_.-])(pass(word|wd)?|secret|token|private[_-]?key|authorization|api[_-]?key|credentials?|cookie)$/i;
+/** True if values under `key` must always be redacted. */
+export function isSecretKey(key) {
+    return SECRET_KEY_PATTERN.test(key.replace(/([a-z0-9])([A-Z])/g, '$1_$2'));
+}
+/** Minimum length of a registered secret; shorter values would cause excessive false positives. */
+const MIN_SECRET_LENGTH = 4;
+/**
+ * Registry of known secret values (tokens, keys) that are replaced by
+ * {@link REDACTED} in any text passed through {@link SecretRedactor.redact}.
+ * Best-effort only: a secret that is transformed (e.g. base64) is not detected (Spec §24.8).
+ */
+export class SecretRedactor {
+    secrets = new Set();
+    /** Register a secret value. Values shorter than 4 characters are ignored. */
+    add(secret) {
+        if (!secret || secret.length < MIN_SECRET_LENGTH)
+            return;
+        this.secrets.add(secret);
+        // PEM keys are often passed with literal "\n" escapes; register both forms.
+        if (secret.includes('\n'))
+            this.secrets.add(secret.replace(/\n/g, '\\n'));
+    }
+    /** Forget a secret value (e.g. after token expiry). */
+    remove(secret) {
+        this.secrets.delete(secret);
+        this.secrets.delete(secret.replace(/\n/g, '\\n'));
+    }
+    /** Number of registered secrets. */
+    get size() {
+        return this.secrets.size;
+    }
+    /** Replace every registered secret occurring in `text`. Longest secrets are replaced first. */
+    redact(text) {
+        if (this.secrets.size === 0 || text.length === 0)
+            return text;
+        let out = text;
+        const ordered = [...this.secrets].sort((a, b) => b.length - a.length);
+        for (const secret of ordered) {
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        }
+        return out;
+    }
+    /** The redactor as a plain function, suitable for {@link ConsoleLoggerOptions.redact}. */
+    asRedactor = (text) => this.redact(text);
+}
+/**
+ * Deep-copy `value`, replacing values under secret-looking keys and applying
+ * `redact` to every string. Handles cycles and Error objects.
+ */
+export function redactValue(value, redact = (s) => s, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return redact(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    // `seen` tracks only the current path: shared (non-cyclic) references are
+    // rendered every time, true cycles become "[Circular]".
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    try {
+        if (value instanceof Error) {
+            const out = { name: value.name, message: redact(value.message) };
+            const { code, details } = value;
+            if (code !== undefined)
+                out.code = code;
+            if (details !== undefined)
+                out.details = redactValue(details, redact, seen);
+            if (value.stack)
+                out.stack = redact(value.stack);
+            if (value.cause !== undefined)
+                out.cause = redactValue(value.cause, redact, seen);
+            return out;
+        }
+        if (Array.isArray(value))
+            return value.map((v) => redactValue(v, redact, seen));
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            out[key] =
+                isSecretKey(key) && v !== null && v !== undefined && typeof v !== 'boolean'
+                    ? REDACTED
+                    : redactValue(v, redact, seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Logger writing one JSON object per line (default: stderr). */
+export class ConsoleLogger {
+    level;
+    clock;
+    redact;
+    sink;
+    bindings;
+    constructor(options = {}) {
+        this.level = options.level ?? 'info';
+        this.clock = options.clock ?? systemClock;
+        this.redact = options.redact ?? ((s) => s);
+        this.sink = options.sink ?? ((line) => process.stderr.write(`${line}\n`));
+        this.bindings = options.bindings ?? {};
+    }
+    debug(msg, fields) {
+        this.write('debug', msg, fields);
+    }
+    info(msg, fields) {
+        this.write('info', msg, fields);
+    }
+    warn(msg, fields) {
+        this.write('warn', msg, fields);
+    }
+    error(msg, fields) {
+        this.write('error', msg, fields);
+    }
+    child(bindings) {
+        return new ConsoleLogger({
+            level: this.level,
+            clock: this.clock,
+            redact: this.redact,
+            sink: this.sink,
+            bindings: { ...this.bindings, ...bindings },
+        });
+    }
+    write(level, msg, fields) {
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[this.level])
+            return;
+        const record = {
+            time: this.clock.now().toISOString(),
+            level,
+            msg,
+            ...this.bindings,
+            ...(fields ?? {}),
+        };
+        let line;
+        try {
+            line = JSON.stringify(redactValue(record, this.redact));
+        }
+        catch {
+            line = JSON.stringify({ time: record.time, level, msg: this.redact(msg), logError: 'unserialisable fields' });
+        }
+        this.sink(line);
+    }
+}
+/** Logger that keeps (redacted) records in memory; intended for tests. */
+export class MemoryLogger {
+    redact;
+    bindings;
+    /** Shared record list (children append to the root's list). */
+    records;
+    constructor(redact = (s) => s, bindings = {}, records) {
+        this.redact = redact;
+        this.bindings = bindings;
+        this.records = records ?? [];
+    }
+    debug(msg, fields) {
+        this.push('debug', msg, fields);
+    }
+    info(msg, fields) {
+        this.push('info', msg, fields);
+    }
+    warn(msg, fields) {
+        this.push('warn', msg, fields);
+    }
+    error(msg, fields) {
+        this.push('error', msg, fields);
+    }
+    child(bindings) {
+        return new MemoryLogger(this.redact, { ...this.bindings, ...bindings }, this.records);
+    }
+    push(level, msg, fields) {
+        this.records.push({
+            level,
+            msg: this.redact(msg),
+            fields: redactValue({ ...this.bindings, ...(fields ?? {}) }, this.redact),
+        });
+    }
+}
+/** Logger that discards everything. */
+export const noopLogger = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+    child: () => noopLogger,
+};
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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

package/dist/core/paths.d.ts

@@ -0,0 +1,84 @@
+/** Resolve `p` to a normalised absolute path (relative to `cwd`, default `process.cwd()`). */
+export declare function toAbsolutePath(p: string, cwd?: string): string;
+/** True when `target` equals `base` or lies below it (both are resolved first; purely lexical). */
+export declare function isWithin(base: string, target: string): boolean;
+/**
+ * Resolve `rel` against the absolute directory `base` and guarantee that the
+ * result stays inside `base` (or equals it).
+ *
+ * - `base` must be absolute; it is normalised.
+ * - `rel` may be relative or absolute; an absolute `rel` is accepted only if it
+ *   lies within `base`.
+ * - `..` segments are allowed only as long as the normalised result stays inside.
+ * - NUL bytes are rejected.
+ *
+ * The check is lexical; use {@link assertRealPathWithin} before destructive
+ * operations on existing paths to also catch symlink escapes.
+ *
+ * @throws PathTraversalError
+ */
+export declare function resolveWithin(base: string, rel: string): string;
+/**
+ * Like {@link resolveWithin}, but additionally requires the result to be
+ * strictly below `base` (never `base` itself). Use for per-run directories
+ * that may be deleted.
+ */
+export declare function resolveStrictlyWithin(base: string, rel: string): string;
+/**
+ * Verify (following symlinks) that the existing path `target` lies within the
+ * existing directory `base`. Intended as a guard before deleting workspaces.
+ *
+ * @throws PathTraversalError if the real path escapes `base`
+ */
+export declare function assertRealPathWithin(base: string, target: string): Promise<string>;
+/**
+ * Validate a single path segment (file or directory name) without
+ * transforming it: non-empty, no separators, not `.`/`..`, no NUL.
+ *
+ * @throws PathTraversalError
+ */
+export declare function assertSafeSegment(segment: string): string;
+/** Maximum length of a sanitised path segment. */
+export declare const MAX_SEGMENT_LENGTH = 128;
+/**
+ * Turn an arbitrary value into a single safe path segment: every character
+ * outside `[A-Za-z0-9._@+=,-]` (including `/`, `\`, NUL, whitespace) becomes
+ * `_`; a result consisting only of dots becomes underscores; empty becomes `_`;
+ * length is capped at {@link MAX_SEGMENT_LENGTH}.
+ */
+export declare function sanitizeSegment(value: string): string;
+/** Per-run file locations below `data-dir` (Spec §4). */
+export interface RunPaths {
+    /** `runs/<run-id>/` */
+    runDir: string;
+    /** `runs/<run-id>/context.json` (`ADISPATCH_CONTEXT_FILE`) */
+    contextFile: string;
+    /** `runs/<run-id>/result.json` (`ADISPATCH_RESULT_FILE`) */
+    resultFile: string;
+    /** `logs/<run-id>/` */
+    logDir: string;
+    /** `logs/<run-id>/stdout.log` */
+    stdoutLog: string;
+    /** `logs/<run-id>/stderr.log` */
+    stderrLog: string;
+}
+/** Canonical `data-dir` layout (Spec §4). All paths are absolute. */
+export interface DataPaths {
+    dataDir: string;
+    /** `adispatchd.sqlite` */
+    database: string;
+    /** Instance lock file next to the database. */
+    instanceLock: string;
+    /** `logs/` */
+    logsDir: string;
+    /** `runs/` */
+    runsDir: string;
+    /** Default `workspace.base_dir`: `workspaces/` */
+    defaultWorkspacesDir: string;
+    /** `backups/` */
+    backupsDir: string;
+    /** Paths of one run; `runId` must be a safe path segment. */
+    run(runId: string): RunPaths;
+}
+/** Build the {@link DataPaths} for an (absolute or cwd-relative) `dataDir`. */
+export declare function dataPaths(dataDir: string): DataPaths;

package/dist/core/paths.js

@@ -0,0 +1,138 @@
+/**
+ * Path helpers with path-traversal protection (Spec §4, §9, §20) and the
+ * canonical `data-dir` layout shared by persistence, executor, API and CLI.
+ */
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { PathTraversalError } from './errors.js';
+function assertNoNul(value, what) {
+    if (value.includes('\0'))
+        throw new PathTraversalError(`${what} contains a NUL byte`);
+}
+/** Resolve `p` to a normalised absolute path (relative to `cwd`, default `process.cwd()`). */
+export function toAbsolutePath(p, cwd = process.cwd()) {
+    assertNoNul(p, 'Path');
+    if (p.trim() === '')
+        throw new PathTraversalError('Path must not be empty');
+    return path.resolve(cwd, p);
+}
+/** True when `target` equals `base` or lies below it (both are resolved first; purely lexical). */
+export function isWithin(base, target) {
+    const b = path.resolve(base);
+    const t = path.resolve(b, target);
+    const rel = path.relative(b, t);
+    return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+/**
+ * Resolve `rel` against the absolute directory `base` and guarantee that the
+ * result stays inside `base` (or equals it).
+ *
+ * - `base` must be absolute; it is normalised.
+ * - `rel` may be relative or absolute; an absolute `rel` is accepted only if it
+ *   lies within `base`.
+ * - `..` segments are allowed only as long as the normalised result stays inside.
+ * - NUL bytes are rejected.
+ *
+ * The check is lexical; use {@link assertRealPathWithin} before destructive
+ * operations on existing paths to also catch symlink escapes.
+ *
+ * @throws PathTraversalError
+ */
+export function resolveWithin(base, rel) {
+    assertNoNul(base, 'Base path');
+    assertNoNul(rel, 'Path');
+    if (!path.isAbsolute(base))
+        throw new PathTraversalError(`Base path must be absolute: ${base}`, { base });
+    const normBase = path.resolve(base);
+    const resolved = path.resolve(normBase, rel);
+    if (!isWithin(normBase, resolved)) {
+        throw new PathTraversalError(`Path "${rel}" escapes base directory "${normBase}"`, { base: normBase, path: rel });
+    }
+    return resolved;
+}
+/**
+ * Like {@link resolveWithin}, but additionally requires the result to be
+ * strictly below `base` (never `base` itself). Use for per-run directories
+ * that may be deleted.
+ */
+export function resolveStrictlyWithin(base, rel) {
+    const resolved = resolveWithin(base, rel);
+    if (resolved === path.resolve(base)) {
+        throw new PathTraversalError(`Path "${rel}" must not be the base directory itself`, { base, path: rel });
+    }
+    return resolved;
+}
+/**
+ * Verify (following symlinks) that the existing path `target` lies within the
+ * existing directory `base`. Intended as a guard before deleting workspaces.
+ *
+ * @throws PathTraversalError if the real path escapes `base`
+ */
+export async function assertRealPathWithin(base, target) {
+    const lexical = resolveWithin(base, target);
+    const [realBase, realTarget] = await Promise.all([realpath(base), realpath(lexical)]);
+    if (!isWithin(realBase, realTarget)) {
+        throw new PathTraversalError(`Path "${target}" resolves outside "${base}" via symlink`, { base, path: target });
+    }
+    return realTarget;
+}
+/**
+ * Validate a single path segment (file or directory name) without
+ * transforming it: non-empty, no separators, not `.`/`..`, no NUL.
+ *
+ * @throws PathTraversalError
+ */
+export function assertSafeSegment(segment) {
+    assertNoNul(segment, 'Path segment');
+    if (segment === '' || segment === '.' || segment === '..' || /[/\\]/.test(segment)) {
+        throw new PathTraversalError(`Unsafe path segment "${segment}"`, { segment });
+    }
+    return segment;
+}
+/** Maximum length of a sanitised path segment. */
+export const MAX_SEGMENT_LENGTH = 128;
+/**
+ * Turn an arbitrary value into a single safe path segment: every character
+ * outside `[A-Za-z0-9._@+=,-]` (including `/`, `\`, NUL, whitespace) becomes
+ * `_`; a result consisting only of dots becomes underscores; empty becomes `_`;
+ * length is capped at {@link MAX_SEGMENT_LENGTH}.
+ */
+export function sanitizeSegment(value) {
+    let out = value.replace(/[^A-Za-z0-9._@+=,-]/g, '_');
+    if (/^\.*$/.test(out))
+        out = out.replace(/\./g, '_');
+    if (out === '')
+        out = '_';
+    if (out.length > MAX_SEGMENT_LENGTH)
+        out = out.slice(0, MAX_SEGMENT_LENGTH);
+    return out;
+}
+/** Build the {@link DataPaths} for an (absolute or cwd-relative) `dataDir`. */
+export function dataPaths(dataDir) {
+    const root = toAbsolutePath(dataDir);
+    const logsDir = path.join(root, 'logs');
+    const runsDir = path.join(root, 'runs');
+    return {
+        dataDir: root,
+        database: path.join(root, 'adispatchd.sqlite'),
+        instanceLock: path.join(root, 'adispatchd.lock'),
+        logsDir,
+        runsDir,
+        defaultWorkspacesDir: path.join(root, 'workspaces'),
+        backupsDir: path.join(root, 'backups'),
+        run(runId) {
+            assertSafeSegment(runId);
+            const runDir = path.join(runsDir, runId);
+            const logDir = path.join(logsDir, runId);
+            return {
+                runDir,
+                contextFile: path.join(runDir, 'context.json'),
+                resultFile: path.join(runDir, 'result.json'),
+                logDir,
+                stdoutLog: path.join(logDir, 'stdout.log'),
+                stderrLog: path.join(logDir, 'stderr.log'),
+            };
+        },
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

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

package/dist/core/template.d.ts

@@ -0,0 +1,136 @@
+import { OrchestratorError } from './errors.js';
+import type { BusinessResult, TerminalStatus, TriggerType } from './types.js';
+/** Interpolation mode, see module docs. */
+export type TemplateMode = 'text' | 'path';
+/**
+ * Availability group of a placeholder:
+ * - `always`: every workflow context
+ * - `run`: once a run exists (not in filters/conditions before reservation)
+ * - `workspace`: after the workspace path is known (not in `working_directory` itself)
+ * - `source`: only for source-bound runs (source trigger or manual with item)
+ * - `result`: only in completion hooks (`on_success`, `on_failure`, ...)
+ * - `parameters`: declared manual-start parameters, `{parameters.<name>}`
+ */
+export type PlaceholderGroup = 'always' | 'run' | 'workspace' | 'source' | 'result' | 'parameters';
+/** Definition of a whitelisted placeholder. */
+export interface PlaceholderDefinition {
+    name: string;
+    group: PlaceholderGroup;
+    description: string;
+    /** Trusted absolute directory; in `path` mode only allowed at the start of a template. */
+    pathRoot?: boolean;
+}
+/** The fixed placeholder whitelist (Spec §5.4, §9, §20.5). */
+export declare const PLACEHOLDERS: readonly PlaceholderDefinition[];
+/** Prefix of parameter placeholders: `{parameters.<name>}`. */
+export declare const PARAMETER_PLACEHOLDER_PREFIX = "parameters.";
+/** Error thrown for template syntax errors, unknown/unavailable placeholders or unsafe values. */
+export declare class TemplateError extends OrchestratorError {
+    readonly placeholder?: string | undefined;
+    constructor(code: TemplateIssueCode, message: string, placeholder?: string | undefined);
+}
+/** Problem codes reported by {@link validateTemplate}. */
+export type TemplateIssueCode = 'syntax' | 'unknown_placeholder' | 'unavailable_placeholder' | 'path_root_position' | 'missing_value' | 'unsafe_value';
+/** One validation problem. */
+export interface TemplateIssue {
+    code: TemplateIssueCode;
+    message: string;
+    placeholder?: string;
+}
+/** Parsed template part. */
+export type TemplatePart = {
+    kind: 'literal';
+    text: string;
+} | {
+    kind: 'placeholder';
+    name: string;
+    index: number;
+};
+/** Parse a template into literal and placeholder parts. Throws {@link TemplateError} (`syntax`). */
+export declare function parseTemplate(template: string): TemplatePart[];
+/** Distinct placeholder names used in `template`, in order of first use. Throws on syntax errors. */
+export declare function extractPlaceholders(template: string): string[];
+/**
+ * Which placeholder groups are available in a given config context.
+ * Omitted flags default to `false`; `always` placeholders are always available.
+ */
+export interface TemplateScope {
+    run?: boolean;
+    workspace?: boolean;
+    source?: boolean;
+    result?: boolean;
+    /** Declared parameter names usable as `{parameters.<name>}`. */
+    parameters?: readonly string[];
+}
+/** Scope with every group enabled (parameters: none). */
+export declare const FULL_TEMPLATE_SCOPE: Readonly<TemplateScope>;
+/** True if `name` is on the whitelist (parameters: any syntactically valid name). */
+export declare function isKnownPlaceholder(name: string): boolean;
+/** Options for {@link validateTemplate} and {@link renderTemplate}. */
+export interface TemplateOptions {
+    mode: TemplateMode;
+    /** Available placeholder groups; default {@link FULL_TEMPLATE_SCOPE}. */
+    scope?: TemplateScope;
+}
+/**
+ * Validate a template without values (for config validation). Returns all
+ * problems; an empty array means valid.
+ */
+export declare function validateTemplate(template: string, options: TemplateOptions): TemplateIssue[];
+/** Scalar value of a placeholder. */
+export type TemplateScalar = string | number | boolean | null;
+/** Flat map from placeholder name (e.g. `run.id`, `parameters.version`) to value. */
+export type TemplateValues = Readonly<Record<string, TemplateScalar | undefined>>;
+/** Options for {@link renderTemplate}. */
+export interface RenderOptions extends TemplateOptions {
+    /**
+     * Behaviour for whitelisted placeholders without a value: `error` (default
+     * in `path` mode) or `empty` (default in `text` mode).
+     */
+    missing?: 'error' | 'empty';
+}
+/**
+ * Interpolate `template` with `values`.
+ *
+ * @throws TemplateError for syntax errors, unknown/unavailable placeholders,
+ *   missing values (per `missing`), misplaced/relative path roots or NUL bytes.
+ */
+export declare function renderTemplate(template: string, values: TemplateValues, options: RenderOptions): string;
+/** Structured input for {@link buildTemplateValues}. */
+export interface TemplateInput {
+    workflow: {
+        id: string;
+        name?: string;
+    };
+    workspace?: {
+        baseDir?: string;
+        path?: string;
+    };
+    run?: {
+        id: string;
+        trigger?: TriggerType;
+        startedAt?: Date;
+    };
+    source?: {
+        id: string;
+        type: string;
+        repository?: string;
+    };
+    item?: {
+        id: string;
+        key?: string;
+        number?: number | string;
+        url?: string;
+        title?: string;
+    };
+    result?: {
+        status?: TerminalStatus;
+        result?: BusinessResult;
+        message?: string;
+    };
+    parameters?: Readonly<Record<string, string | number | boolean>>;
+    /** Time used for `{timestamp}`. */
+    now: Date;
+}
+/** Build the flat {@link TemplateValues} map from structured run data. */
+export declare function buildTemplateValues(input: TemplateInput): TemplateValues;