@kitsi/cli 0.0.1

package/dist/engine/cache/coordinator.js

@@ -0,0 +1,800 @@
+import { join } from 'node:path';
+import { StepBuilder } from '../../dsl/step.js';
+import { OpErrors } from '../../ops/errors.js';
+import { CommandBuilder } from '../../ops/shell.js';
+import { isParamRef, isSecretRef, isValueRef } from '../../ops/types.js';
+import { VERSION } from '../../version.js';
+import { collectFiles, writeFiles } from '../executor/file-system.js';
+import { analyzeTaskSteps } from './analyze.js';
+import { hashFiles, hashNamedValues, hashObject, hashString } from './hasher.js';
+import { inferInputsFromCommand, inferOutputsFromCommand } from './inference.js';
+import { CacheStore } from './store.js';
+export class CacheCoordinator {
+    workspace;
+    settings;
+    logger;
+    reporter;
+    resolver;
+    params;
+    getTaskState;
+    findTask;
+    executeTask;
+    cacheStore;
+    pendingOpSaves = new Map();
+    taskCacheState = new Map();
+    constructor(opts) {
+        this.workspace = opts.workspace;
+        this.settings = opts.settings ?? {};
+        this.logger = opts.logger;
+        this.reporter = opts.reporter;
+        this.resolver = opts.resolver;
+        this.params = opts.params;
+        this.getTaskState = opts.getTaskState;
+        this.findTask = opts.findTask;
+        this.executeTask = opts.executeTask;
+        const cacheEnabled = this.settings.enabled !== false;
+        const cacheRoot = this.settings.directory ?? join(this.workspace, '.kitsi', 'cache');
+        this.cacheStore = cacheEnabled ? new CacheStore(cacheRoot) : null;
+    }
+    async beforeTask(task, env, state) {
+        if (!this.shouldAttemptTaskCache(task))
+            return null;
+        this.ensureCacheStore(task);
+        if (!this.cacheAllowedForTask(task)) {
+            return this.handleCacheDisabled(task);
+        }
+        const decision = await this.computeTaskCacheDecision(task, env);
+        if (!decision.cacheable) {
+            return await this.handleUncacheableDecision(task, decision);
+        }
+        return await this.tryRestoreTaskCache(task, decision, state);
+    }
+    async afterStep(task) {
+        if (!this.cacheAllowedForTask(task))
+            return;
+        await this.flushPendingOpSaves(task.config.name);
+    }
+    async afterTask(task, state, decision) {
+        if (!this.cacheAllowedForTask(task))
+            return;
+        await this.flushPendingOpSaves(task.config.name);
+        if (!decision?.cacheable || decision.hit || !this.cacheStore)
+            return;
+        const outputFiles = decision.outputPatterns.length > 0
+            ? await collectFiles(this.workspace, decision.outputPatterns)
+            : {};
+        const outputs = {};
+        for (const [key, value] of state.outputs.entries()) {
+            outputs[key] = value;
+        }
+        const meta = {
+            key: decision.key,
+            task: task.config.name,
+            createdAt: new Date().toISOString(),
+            components: decision.components,
+            inputs: decision.inputs,
+            outputs,
+            summaries: state.summaries,
+            bundles: Array.from(state.bundles.keys()),
+        };
+        await this.cacheStore.saveTask(task.config.name, decision.key, {
+            meta,
+            bundles: state.bundles,
+            outputFiles,
+        });
+        this.recordTaskCacheState(task.config.name, {
+            key: decision.key,
+            fingerprint: decision.key,
+        });
+    }
+    async tryExecuteOp(op, task, context, state, executeBaseOp, executeOp) {
+        if (op.kind === 'cache') {
+            const hit = await this.executeCacheOp(op, task, context, state);
+            return { handled: true, value: hit };
+        }
+        if (op.kind === 'cache-or') {
+            const hit = await this.executeCacheOrOp(op, task, context, state, executeOp);
+            return { handled: true, value: hit };
+        }
+        if (op.kind === 'command' && op.cache?.enabled === true) {
+            const result = await this.executeCachedCommand(op, task, context, state, executeBaseOp);
+            return { handled: true, value: result };
+        }
+        return null;
+    }
+    wasTaskCached(taskName) {
+        return this.taskCacheState.get(taskName)?.hit ?? false;
+    }
+    shouldAttemptTaskCache(task) {
+        if (this.settings.cacheOnly) {
+            return (task.config.cache !== undefined ||
+                task.config.cacheEnv.length > 0 ||
+                task.config.cacheBust !== undefined ||
+                task.config.inputs.length > 0 ||
+                Boolean(this.settings.inputs?.[task.config.name]?.length));
+        }
+        return true;
+    }
+    cacheAllowedForTask(task) {
+        if (!this.cacheStore)
+            return false;
+        if (this.settings.enabled === false)
+            return false;
+        if (task.config.cache?.enabled === false)
+            return false;
+        return true;
+    }
+    cacheExcludes() {
+        const defaults = ['.kitsi/**', '.git/**'];
+        const configExcludes = this.settings.exclude ?? [];
+        return [...defaults, ...configExcludes];
+    }
+    ensureCacheStore(task) {
+        if (this.settings.cacheOnly && !this.cacheStore) {
+            throw OpErrors.cache('Cache-only mode requires caching to be enabled')
+                .inTask(task.config.name)
+                .build();
+        }
+    }
+    handleCacheDisabled(task) {
+        if (this.settings.cacheOnly) {
+            throw OpErrors.cache(`Caching disabled for task "${task.config.name}"`)
+                .inTask(task.config.name)
+                .build();
+        }
+        return null;
+    }
+    async handleUncacheableDecision(task, decision) {
+        if (this.settings.cacheOnly) {
+            throw OpErrors.cache(decision.reason ?? 'Task cache is unavailable')
+                .inTask(task.config.name)
+                .build();
+        }
+        if (this.settings.debug) {
+            await this.emitCacheDebug(task.config.name, decision, 'SKIP');
+        }
+        return decision;
+    }
+    async tryRestoreTaskCache(task, decision, state) {
+        const entry = await this.cacheStore?.readTask(task.config.name, decision.key, decision.ttlMs);
+        const hit = Boolean(entry);
+        decision.hit = hit;
+        if (hit && entry) {
+            await this.restoreTaskCacheEntry(entry, state);
+            this.reporter?.emit('cache_hit', { cache: task.config.name, scope: 'task' });
+            this.recordTaskCacheState(task.config.name, {
+                key: decision.key,
+                hit: true,
+                fingerprint: decision.key,
+            });
+        }
+        else {
+            this.reporter?.emit('cache_miss', { cache: task.config.name, scope: 'task' });
+            this.recordTaskCacheState(task.config.name, { key: decision.key, hit: false });
+            if (this.settings.cacheOnly) {
+                throw OpErrors.cache(`Cache miss for task "${task.config.name}"`)
+                    .inTask(task.config.name)
+                    .build();
+            }
+        }
+        if (this.settings.debug) {
+            await this.emitCacheDebug(task.config.name, decision, hit ? 'HIT' : 'MISS');
+        }
+        return decision;
+    }
+    async restoreTaskCacheEntry(entry, state) {
+        if (!entry)
+            return;
+        state.outputs = new Map(Object.entries(entry.meta.outputs));
+        state.summaries = entry.meta.summaries ?? [];
+        state.bundles = entry.bundles;
+        if (Object.keys(entry.outputFiles).length > 0) {
+            await writeFiles(this.workspace, entry.outputFiles);
+        }
+    }
+    async flushPendingOpSaves(taskName) {
+        if (!this.cacheStore)
+            return;
+        const pending = this.pendingOpSaves.get(taskName);
+        if (!pending || pending.length === 0)
+            return;
+        this.pendingOpSaves.set(taskName, []);
+        for (const entry of pending) {
+            const existing = await this.cacheStore.readOp(entry.key, this.settings.ttlMs ?? null);
+            if (existing)
+                continue;
+            const files = await collectFiles(this.workspace, entry.paths);
+            await this.cacheStore.saveOp(entry.key, {
+                meta: {
+                    key: entry.key,
+                    createdAt: new Date().toISOString(),
+                    kind: 'cache',
+                    outputs: entry.paths,
+                },
+                files,
+            });
+        }
+    }
+    recordTaskCacheState(taskName, patch) {
+        const current = this.taskCacheState.get(taskName) ?? {};
+        const next = { ...current, ...patch };
+        this.taskCacheState.set(taskName, next);
+        return next;
+    }
+    async computeTaskCacheDecision(task, env) {
+        const analysis = analyzeTaskSteps(task, this.workspace);
+        const taskName = task.config.name;
+        if (analysis.dynamic) {
+            return {
+                key: '',
+                cacheable: false,
+                reason: 'Task uses runtime values to define operations',
+                components: {},
+                inputs: { patterns: [], files: {} },
+                outputPatterns: [],
+            };
+        }
+        const patterns = this.collectTaskInputPatterns(task, analysis, taskName);
+        const { inputPatterns, inputPatternsHash, inputs } = await this.resolveTaskInputs(taskName, patterns);
+        const envHash = this.hashCacheEnv(task, env);
+        const secrets = new Set(analysis.secrets);
+        const params = new Set(analysis.params);
+        const hasValueRefs = this.collectTaskRefs(task, secrets, params);
+        if (hasValueRefs) {
+            return {
+                key: '',
+                cacheable: false,
+                reason: 'Task env uses runtime values',
+                components: {},
+                inputs: { patterns: inputPatterns, files: inputs.files },
+                outputPatterns: task.config.cache?.outputs ?? [],
+            };
+        }
+        const secretsHash = hashString(Array.from(secrets).sort().join('\n'));
+        const paramsHash = this.hashParams(params);
+        const depsHash = await this.hashDependencies(task, analysis.dependencies);
+        const opsHash = hashObject(analysis.ops);
+        const imageRef = task.config.image?.config.ref ?? 'local';
+        const workdir = task.config.image?.config.workdir ?? '';
+        const envConfigHash = this.hashEnvConfig(task);
+        const outputPatterns = task.config.cache?.outputs ?? [];
+        const outputPatternsHash = hashString(outputPatterns.join('\n'));
+        const components = {
+            taskName,
+            image: imageRef,
+            workdir,
+            inputsHash: inputs.hash,
+            inputPatternsHash,
+            envHash,
+            envConfigHash,
+            secretsHash,
+            paramsHash,
+            depsHash,
+            opsHash,
+            cacheBust: this.buildCacheBust(task),
+            outputPatternsHash,
+            version: this.cacheVersion(),
+        };
+        const key = hashObject(components);
+        return {
+            key,
+            cacheable: true,
+            components,
+            inputs: { patterns: inputPatterns, files: inputs.files },
+            outputPatterns,
+            ttlMs: this.resolveTtl(task.config.cache?.ttl),
+        };
+    }
+    collectTaskInputPatterns(task, analysis, taskName) {
+        const explicitPatterns = new Set();
+        for (const pattern of task.config.inputs)
+            explicitPatterns.add(pattern);
+        for (const pattern of task.config.cache?.inputs ?? [])
+            explicitPatterns.add(pattern);
+        for (const pattern of analysis.inputs)
+            explicitPatterns.add(pattern);
+        for (const pattern of this.settings.inputs?.[taskName] ?? []) {
+            explicitPatterns.add(pattern);
+        }
+        if (explicitPatterns.size > 0)
+            return Array.from(explicitPatterns);
+        const inferred = new Set();
+        let hasUnknownCommand = false;
+        for (const signature of analysis.commandSignatures) {
+            const patterns = inferInputsFromCommand(signature);
+            if (patterns.length === 0) {
+                hasUnknownCommand = true;
+                continue;
+            }
+            for (const pattern of patterns)
+                inferred.add(pattern);
+        }
+        if (hasUnknownCommand) {
+            inferred.add('**/*');
+        }
+        return Array.from(inferred);
+    }
+    async resolveTaskInputs(taskName, patterns) {
+        const inputPatterns = patterns.length > 0 ? patterns : ['**/*'];
+        if (patterns.length === 0) {
+            this.logger.info(this.resolver.redactSecrets(`Cache inputs not detected for task "${taskName}". Consider declaring inputs.`));
+        }
+        const inputPatternsHash = hashString(inputPatterns.join('\n'));
+        const inputs = await hashFiles(this.workspace, inputPatterns, this.cacheExcludes());
+        return { inputPatterns, inputPatternsHash, inputs };
+    }
+    hashCacheEnv(task, env) {
+        const cacheEnv = new Set(task.config.cacheEnv);
+        for (const name of task.config.cache?.env ?? [])
+            cacheEnv.add(name);
+        const secretEnv = this.collectSecretEnvNames(task);
+        const envValues = {};
+        for (const name of cacheEnv) {
+            envValues[name] = secretEnv.has(name) ? '__secret__' : (env[name] ?? '__unset__');
+        }
+        return hashNamedValues(envValues);
+    }
+    buildCacheBust(task) {
+        const cacheBust = [this.settings.bust, task.config.cacheBust, task.config.cache?.key]
+            .filter(Boolean)
+            .join(':');
+        return cacheBust || '';
+    }
+    collectTaskRefs(task, secrets, params) {
+        let hasValueRef = false;
+        const collect = (value) => {
+            if (isSecretRef(value))
+                secrets.add(value.name);
+            if (isParamRef(value))
+                params.add(value.name);
+            if (isValueRef(value)) {
+                hasValueRef = true;
+            }
+        };
+        for (const value of Object.values(task.config.env)) {
+            collect(value);
+        }
+        for (const value of Object.values(task.config.image?.config.env ?? {})) {
+            collect(value);
+        }
+        return hasValueRef;
+    }
+    collectSecretEnvNames(task) {
+        const names = new Set();
+        for (const [key, value] of Object.entries(task.config.env)) {
+            if (isSecretRef(value))
+                names.add(key);
+        }
+        for (const [key, value] of Object.entries(task.config.image?.config.env ?? {})) {
+            if (isSecretRef(value))
+                names.add(key);
+        }
+        return names;
+    }
+    hashParams(params) {
+        const values = {};
+        for (const name of params) {
+            if (Object.prototype.hasOwnProperty.call(this.params, name)) {
+                values[name] = JSON.stringify(this.params[name]);
+            }
+            else {
+                values[name] = '__unset__';
+            }
+        }
+        return hashNamedValues(values);
+    }
+    hashEnvConfig(task) {
+        const normalize = (value) => {
+            if (typeof value === 'string' || typeof value === 'number')
+                return value;
+            if (isSecretRef(value))
+                return { kind: 'secret', name: value.name };
+            if (isParamRef(value))
+                return { kind: 'param', name: value.name };
+            if (isValueRef(value))
+                return { kind: 'value', name: value.name };
+            return String(value);
+        };
+        const taskEnv = {};
+        for (const [name, value] of Object.entries(task.config.env)) {
+            taskEnv[name] = normalize(value);
+        }
+        const imageEnv = {};
+        for (const [name, value] of Object.entries(task.config.image?.config.env ?? {})) {
+            imageEnv[name] = normalize(value);
+        }
+        return hashObject({ taskEnv, imageEnv });
+    }
+    async hashDependencies(task, discovered) {
+        const names = this.collectDependencyNames(task, discovered);
+        const fingerprints = {};
+        for (const name of names) {
+            fingerprints[name] = await this.resolveDependencyFingerprint(name);
+        }
+        return hashObject(fingerprints);
+    }
+    collectDependencyNames(task, discovered) {
+        const names = new Set(task.config.needs);
+        for (const name of discovered)
+            names.add(name);
+        return Array.from(names);
+    }
+    async resolveDependencyFingerprint(name) {
+        let state = this.getTaskState(name);
+        if (!state || state.status === 'pending' || state.status === 'running') {
+            const depTask = this.findTask(name);
+            if (depTask) {
+                await this.executeTask(depTask);
+            }
+            state = this.getTaskState(name);
+        }
+        if (!state)
+            return 'missing';
+        if (state.status === 'failed')
+            return 'failed';
+        const cacheState = this.taskCacheState.get(name);
+        if (cacheState?.key)
+            return cacheState.key;
+        if (!cacheState?.fingerprint) {
+            const fingerprint = this.computeStateFingerprint(state);
+            this.recordTaskCacheState(name, { fingerprint });
+        }
+        return this.taskCacheState.get(name)?.fingerprint ?? 'missing';
+    }
+    computeStateFingerprint(state) {
+        const outputs = {};
+        for (const [key, value] of state.outputs.entries()) {
+            outputs[key] = value;
+        }
+        const bundleHashes = {};
+        for (const [name, bundle] of state.bundles.entries()) {
+            const fileHashes = {};
+            for (const [path, content] of Object.entries(bundle.files)) {
+                fileHashes[path] = hashString(Buffer.from(content).toString('base64'));
+            }
+            bundleHashes[name] = hashObject(fileHashes);
+        }
+        return hashObject({ outputs, bundles: bundleHashes });
+    }
+    cacheVersion() {
+        const [major] = VERSION.split('.');
+        return major ?? VERSION;
+    }
+    resolveTtl(value) {
+        if (!value)
+            return this.settings.ttlMs ?? null;
+        const parsed = this.parseDuration(value);
+        return parsed ?? this.settings.ttlMs ?? null;
+    }
+    parseDuration(value) {
+        const match = value.trim().match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/);
+        if (!match)
+            return null;
+        const amount = Number(match[1]);
+        if (!Number.isFinite(amount))
+            return null;
+        const multipliers = {
+            ms: 1,
+            s: 1000,
+            m: 60_000,
+            h: 3_600_000,
+            d: 86_400_000,
+        };
+        const unit = match[2];
+        if (!unit)
+            return null;
+        return amount * (multipliers[unit] ?? 1);
+    }
+    async executeCacheOp(op, task, context, _state, recordPending = true) {
+        if (!this.cacheAllowedForTask(task)) {
+            if (this.settings.cacheOnly) {
+                throw OpErrors.cache(`Cache disabled for task "${task.config.name}"`)
+                    .inTask(context.task)
+                    .inStep(context.step)
+                    .build();
+            }
+            return false;
+        }
+        const decision = await this.computeCacheOpDecision(op, context, task);
+        const entry = await this.cacheStore?.readOp(decision.key, this.settings.ttlMs ?? null);
+        if (entry) {
+            if (Object.keys(entry.files).length > 0) {
+                await writeFiles(context.workspace, entry.files);
+            }
+            this.reporter?.emit('cache_hit', { cache: op.name, scope: 'op' });
+            return true;
+        }
+        this.reporter?.emit('cache_miss', { cache: op.name, scope: 'op' });
+        if (this.settings.cacheOnly) {
+            throw OpErrors.cache(`Cache miss for "${op.name}"`)
+                .inTask(context.task)
+                .inStep(context.step)
+                .build();
+        }
+        if (recordPending) {
+            this.enqueuePendingSave(task.config.name, {
+                key: decision.key,
+                name: op.name,
+                paths: op.paths,
+            });
+        }
+        return false;
+    }
+    async executeCacheOrOp(op, task, context, state, executeOp) {
+        if (!this.cacheAllowedForTask(task)) {
+            if (this.settings.cacheOnly) {
+                throw OpErrors.cache(`Cache disabled for task "${task.config.name}"`)
+                    .inTask(context.task)
+                    .inStep(context.step)
+                    .build();
+            }
+            await this.executeInline(op.compute, task, context, state, executeOp);
+            return false;
+        }
+        const cacheHit = await this.executeCacheOp(op, task, context, state, false);
+        if (cacheHit)
+            return true;
+        if (this.settings.cacheOnly) {
+            throw OpErrors.cache(`Cache miss for "${op.name}"`)
+                .inTask(context.task)
+                .inStep(context.step)
+                .build();
+        }
+        await this.executeInline(op.compute, task, context, state, executeOp);
+        await this.saveCacheOpSnapshot(op, context, task);
+        return false;
+    }
+    async executeCachedCommand(op, task, context, _state, executeBaseOp) {
+        if (!this.cacheAllowedForTask(task)) {
+            if (this.settings.cacheOnly) {
+                throw OpErrors.cache(`Cache disabled for task "${task.config.name}"`)
+                    .inTask(context.task)
+                    .inStep(context.step)
+                    .build();
+            }
+            return executeBaseOp(op);
+        }
+        const decision = await this.computeCommandCacheDecision(op, context, task);
+        if (!decision) {
+            return executeBaseOp(op);
+        }
+        const entry = await this.cacheStore?.readOp(decision.key, this.settings.ttlMs ?? null);
+        if (entry) {
+            if (Object.keys(entry.files).length > 0) {
+                await writeFiles(context.workspace, entry.files);
+            }
+            this.reporter?.emit('cache_hit', { cache: decision.name, scope: 'command' });
+            return entry.result;
+        }
+        this.reporter?.emit('cache_miss', { cache: decision.name, scope: 'command' });
+        if (this.settings.cacheOnly) {
+            throw OpErrors.cache(`Cache miss for command "${decision.name}"`)
+                .inTask(context.task)
+                .inStep(context.step)
+                .build();
+        }
+        const result = await executeBaseOp(op);
+        if (this.shouldCacheCommandResult(op, result)) {
+            const files = await collectFiles(context.workspace, decision.outputs);
+            await this.cacheStore?.saveOp(decision.key, {
+                meta: {
+                    key: decision.key,
+                    createdAt: new Date().toISOString(),
+                    kind: 'command',
+                    command: decision.command,
+                    inputs: decision.inputs,
+                    outputs: decision.outputs,
+                },
+                result,
+                files,
+            });
+        }
+        return result;
+    }
+    async executeInline(compute, task, context, state, executeOp) {
+        const iterator = compute({ task, workspace: this.workspace });
+        const inlineStep = new StepBuilder(context.step, () => iterator, []);
+        let cursor = iterator.next();
+        while (!cursor.done) {
+            const op = this.toOp(cursor.value);
+            const result = await executeOp(op, task, inlineStep, context.env, state);
+            cursor = iterator.next(result);
+        }
+    }
+    toOp(value) {
+        if (value instanceof CommandBuilder) {
+            return value.op;
+        }
+        if (value && typeof value === 'object' && 'op' in value) {
+            const maybeOp = value.op;
+            if (maybeOp && typeof maybeOp === 'object' && 'kind' in maybeOp) {
+                return maybeOp;
+            }
+        }
+        return value;
+    }
+    async computeCacheOpDecision(op, context, task) {
+        if (op.paths.length === 0) {
+            throw OpErrors.cache(`Cache "${op.name}" has no paths`)
+                .inTask(context.task)
+                .inStep(context.step)
+                .build();
+        }
+        const fileHash = op.key?.files
+            ? await hashFiles(this.workspace, op.key.files, this.cacheExcludes())
+            : { hash: hashString(''), files: {} };
+        const secretEnv = this.collectSecretEnvNames(task);
+        const envValues = {};
+        for (const name of op.key?.env ?? []) {
+            envValues[name] = secretEnv.has(name) ? '__secret__' : (context.env[name] ?? '__unset__');
+        }
+        const envHash = hashNamedValues(envValues);
+        const keyComponents = {
+            name: op.name,
+            paths: op.paths,
+            files: fileHash.hash,
+            filePatternsHash: hashString((op.key?.files ?? []).join('\n')),
+            env: envHash,
+            value: op.key?.value ?? '',
+            bust: this.settings.bust ?? '',
+            version: this.cacheVersion(),
+        };
+        return { key: hashObject(keyComponents) };
+    }
+    async saveCacheOpSnapshot(op, context, task) {
+        const decision = await this.computeCacheOpDecision(op, context, task);
+        const files = await collectFiles(this.workspace, op.paths);
+        await this.cacheStore?.saveOp(decision.key, {
+            meta: {
+                key: decision.key,
+                createdAt: new Date().toISOString(),
+                kind: 'cache',
+                outputs: op.paths,
+            },
+            files,
+        });
+    }
+    async computeCommandCacheDecision(op, context, task) {
+        const cacheOptions = op.cache;
+        if (!cacheOptions)
+            return null;
+        const { template, signature } = this.normalizeCommandTemplate(op.template);
+        const resolvedOutputs = this.resolveCommandOutputs(cacheOptions, signature);
+        if (resolvedOutputs.length === 0)
+            return null;
+        const uniqueInputs = this.resolveCommandInputs(cacheOptions, signature);
+        if (uniqueInputs.length === 0)
+            return null;
+        const inputs = await hashFiles(this.workspace, uniqueInputs, this.cacheExcludes());
+        const envHash = this.hashCommandEnv(cacheOptions, context.env, task);
+        const outputsHash = hashString(resolvedOutputs.join('\n'));
+        const keyComponents = {
+            task: context.task,
+            step: context.step,
+            capture: op.capture,
+            command: template,
+            inputs: inputs.hash,
+            inputPatternsHash: hashString(uniqueInputs.join('\n')),
+            outputsHash,
+            env: envHash,
+            value: cacheOptions.key?.value ?? '',
+            bust: this.settings.bust ?? '',
+            version: this.cacheVersion(),
+        };
+        return {
+            key: hashObject(keyComponents),
+            name: signature || `${context.task}:${context.step}`,
+            outputs: resolvedOutputs,
+            command: { capture: op.capture, template },
+            inputs: { patterns: uniqueInputs, files: inputs.files },
+        };
+    }
+    normalizeCommandTemplate(template) {
+        const normalized = template.map((part) => ({
+            type: part.type,
+            ...(part.type === 'text' || part.type === 'interpolated'
+                ? { value: part.value }
+                : part.type === 'secret'
+                    ? { name: part.name }
+                    : { name: part.ref.name }),
+        }));
+        const signature = template
+            .map((part) => {
+            if (part.type === 'text')
+                return part.value;
+            if (part.type === 'interpolated')
+                return String(part.value);
+            if (part.type === 'secret')
+                return `<secret:${part.name}>`;
+            if (part.type === 'param')
+                return `<param:${part.ref.name}>`;
+            return `<value:${part.ref.name}>`;
+        })
+            .join('')
+            .replace(/\s+/g, ' ')
+            .trim();
+        return { template: normalized, signature };
+    }
+    resolveCommandOutputs(cacheOptions, signature) {
+        if (cacheOptions.outputs && cacheOptions.outputs.length > 0) {
+            return cacheOptions.outputs;
+        }
+        return inferOutputsFromCommand(signature);
+    }
+    resolveCommandInputs(cacheOptions, signature) {
+        const inputPatterns = [...(cacheOptions.inputs ?? []), ...(cacheOptions.key?.files ?? [])];
+        const resolvedInputs = inputPatterns.length > 0 ? inputPatterns : inferInputsFromCommand(signature);
+        return Array.from(new Set(resolvedInputs));
+    }
+    hashCommandEnv(cacheOptions, env, task) {
+        const envValues = {};
+        const envNames = new Set(cacheOptions.env ?? []);
+        for (const name of cacheOptions.key?.env ?? [])
+            envNames.add(name);
+        const secretEnv = this.collectSecretEnvNames(task);
+        for (const name of envNames) {
+            envValues[name] = secretEnv.has(name) ? '__secret__' : (env[name] ?? '__unset__');
+        }
+        return hashNamedValues(envValues);
+    }
+    shouldCacheCommandResult(op, result) {
+        if (op.capture === 'ok')
+            return result === true;
+        if (op.capture === 'code')
+            return result === 0;
+        if (op.capture === 'result') {
+            return Boolean(result && typeof result === 'object' && result.ok);
+        }
+        return true;
+    }
+    async emitCacheDebug(taskName, decision, status) {
+        const meta = await this.cacheStore?.latestTaskMeta(taskName);
+        const changes = this.diffInputFiles(decision.inputs.files, meta?.inputs.files ?? {});
+        const lines = [
+            `Task: ${taskName}`,
+            `  Cache key: sha256:${decision.key}`,
+            '  Components:',
+            ...Object.entries(decision.components).map(([key, value]) => `    ${key}: sha256:${value}`),
+            `  Status: ${status}${decision.reason ? ` (${decision.reason})` : ''}`,
+        ];
+        if (changes.length > 0) {
+            lines.push('  Changed files:');
+            for (const change of changes) {
+                lines.push(`    - ${change}`);
+            }
+        }
+        if (this.reporter) {
+            this.reporter.emit('cache_debug', { task: taskName, lines });
+        }
+        else {
+            for (const line of lines) {
+                this.logger.info(this.resolver.redactSecrets(line));
+            }
+        }
+    }
+    diffInputFiles(current, previous) {
+        const changes = [];
+        const currentKeys = new Set(Object.keys(current));
+        const previousKeys = new Set(Object.keys(previous));
+        for (const key of currentKeys) {
+            if (!previousKeys.has(key)) {
+                changes.push(`${key} (added)`);
+            }
+            else if (current[key] !== previous[key]) {
+                changes.push(`${key} (modified)`);
+            }
+        }
+        for (const key of previousKeys) {
+            if (!currentKeys.has(key)) {
+                changes.push(`${key} (removed)`);
+            }
+        }
+        return changes;
+    }
+    enqueuePendingSave(taskName, entry) {
+        const existing = this.pendingOpSaves.get(taskName) ?? [];
+        existing.push(entry);
+        this.pendingOpSaves.set(taskName, existing);
+    }
+}
+//# sourceMappingURL=coordinator.js.map