hammerkit 1.5.1 → 1.6.0-alpha.2

package/dist/cache/auto-pull.spec.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const os_1 = require("os");
+const fs_1 = require("fs");
+const environment_mock_1 = require("../executer/environment-mock");
+const enqueue_next_1 = require("../executer/scheduler/enqueue-next");
+const local_cache_backend_1 = require("./backends/local-cache-backend");
+const state_1 = require("../executer/state");
+const cache_metadata_1 = require("../executer/cache-metadata");
+const get_cache_directory_1 = require("../optimizer/get-cache-directory");
+const get_work_cache_stats_1 = require("../optimizer/get-work-cache-stats");
+const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
+describe('checkCacheState auto-pull', () => {
+    let remoteDir;
+    let machineHome;
+    let originalHome;
+    beforeEach(() => {
+        remoteDir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-remote-'));
+        machineHome = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-home-'));
+        originalHome = process.env.HOME;
+        if (process.platform === 'darwin') {
+            // getHammerkitDirectory uses Library/Application Support on macOS
+            process.env.HOME = machineHome;
+        }
+        else if (process.platform === 'win32') {
+            process.env.APPDATA = machineHome;
+        }
+        else {
+            process.env.HOME = machineHome;
+        }
+    });
+    afterEach(() => {
+        (0, fs_1.rmSync)(remoteDir, { recursive: true, force: true });
+        (0, fs_1.rmSync)(machineHome, { recursive: true, force: true });
+        if (originalHome !== undefined) {
+            process.env.HOME = originalHome;
+        }
+        else {
+            delete process.env.HOME;
+        }
+    });
+    function makeBackend() {
+        return (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: remoteDir });
+    }
+    function makeWorkItem(cwd, resolved) {
+        const storedStateKey = null;
+        return {
+            id: () => 'demo-task',
+            name: 'demo-task',
+            status: { write: vi.fn() },
+            data: {
+                type: 'local-task',
+                name: 'demo-task',
+                cwd,
+                cmds: [],
+                generates: [],
+                src: [],
+                envs: { variables: {}, replacements: [] },
+                labels: {},
+                shell: '/bin/sh',
+                continuous: false,
+                caching: resolved,
+                description: null,
+                scope: {},
+            },
+            needs: [],
+            deps: [],
+            requiredBy: [],
+            state: new state_1.State({ type: 'pending', stateKey: null }),
+            runtime: {
+                async initialize() { },
+                async remove() { },
+                async execute() { },
+                async stop() { },
+                async archive() { },
+                async restore() {
+                    // simulate a successful artifact restore
+                },
+                async currentStateKey() {
+                    return storedStateKey;
+                },
+            },
+        };
+    }
+    it('reports cached:true on the second machine after the first pushed', async () => {
+        // Machine A: produce cache + push to remote
+        const machineAScratch = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-machine-a-'));
+        const envA = (0, environment_mock_1.environmentMock)(machineAScratch);
+        const backend = makeBackend();
+        const resolved = { name: 'remote', method: 'checksum', backend, implicit: false };
+        const itemA = makeWorkItem(machineAScratch, resolved);
+        const stats = await (0, get_work_cache_stats_1.getWorkCacheStats)(itemA.data, envA);
+        const stateKey = (0, get_work_cache_stats_1.getStateKey)(stats, 'checksum');
+        await (0, cache_metadata_1.writeCacheMetadata)(envA, itemA.id(), stats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(itemA.data));
+        const cacheDir = (0, get_cache_directory_1.getCacheDirectory)(itemA.id());
+        await backend.push(itemA.id(), stateKey, cacheDir, envA);
+        (0, fs_1.rmSync)(machineAScratch, { recursive: true, force: true });
+        // Machine B (different HOME = fresh local cache): same task, same sources → same stateKey
+        const machineBScratch = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-machine-b-'));
+        const envB = (0, environment_mock_1.environmentMock)(machineBScratch);
+        // simulate a *different* machine: reset the HOME again
+        const machineBHome = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-home-b-'));
+        process.env.HOME = machineBHome;
+        const itemB = makeWorkItem(machineBScratch, resolved);
+        const cacheState = await (0, enqueue_next_1.checkCacheState)(itemB, 'checksum', envB);
+        expect(cacheState.stateKey).toBe(stateKey);
+        expect(cacheState.cached).toBe(true);
+        (0, fs_1.rmSync)(machineBScratch, { recursive: true, force: true });
+        (0, fs_1.rmSync)(machineBHome, { recursive: true, force: true });
+    });
+    it('reports cached:false when remote has nothing', async () => {
+        const scratch = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-machine-c-'));
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = makeBackend();
+        const resolved = { name: 'remote', method: 'checksum', backend, implicit: false };
+        const item = makeWorkItem(scratch, resolved);
+        const cacheState = await (0, enqueue_next_1.checkCacheState)(item, 'checksum', env);
+        expect(cacheState.cached).toBe(false);
+        (0, fs_1.rmSync)(scratch, { recursive: true, force: true });
+    });
+});
+//# sourceMappingURL=auto-pull.spec.js.map

package/dist/cache/backends/local-cache-backend.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalCacheBackend = void 0;
+const path_1 = require("path");
+const os_1 = require("os");
+function createLocalCacheBackend(spec) {
+    const root = spec.path ?? (0, path_1.join)((0, os_1.homedir)(), '.hammerkit', 'remote-cache');
+    return {
+        type: 'local',
+        async has(taskId, stateKey, environment) {
+            const statsPath = (0, path_1.join)(root, taskId, stateKey, 'stats.json');
+            try {
+                return await environment.file.exists(statsPath);
+            }
+            catch {
+                return false;
+            }
+        },
+        async pull(taskId, stateKey, into, environment) {
+            const remoteDir = (0, path_1.join)(root, taskId, stateKey);
+            const statsPath = (0, path_1.join)(remoteDir, 'stats.json');
+            if (!(await environment.file.exists(statsPath))) {
+                return false;
+            }
+            await environment.file.createDirectory(into);
+            try {
+                for (const file of await environment.file.listFiles(remoteDir)) {
+                    await environment.file.copy((0, path_1.join)(remoteDir, file), (0, path_1.join)(into, file));
+                }
+                return true;
+            }
+            catch (e) {
+                return false;
+            }
+        },
+        async push(taskId, stateKey, from, environment) {
+            const remoteDir = (0, path_1.join)(root, taskId, stateKey);
+            await environment.file.createDirectory(remoteDir);
+            // Write data files first; stats.json last so a partial push is invisible to has()/pull().
+            const files = await environment.file.listFiles(from);
+            const ordered = [
+                ...files.filter((f) => f !== 'stats.json' && f !== 'description.json'),
+                ...files.filter((f) => f === 'description.json'),
+                ...files.filter((f) => f === 'stats.json'),
+            ];
+            for (const file of ordered) {
+                await environment.file.copy((0, path_1.join)(from, file), (0, path_1.join)(remoteDir, file));
+            }
+        },
+        async clear(taskId, environment) {
+            await environment.file.remove((0, path_1.join)(root, taskId));
+        },
+    };
+}
+exports.createLocalCacheBackend = createLocalCacheBackend;
+//# sourceMappingURL=local-cache-backend.js.map

package/dist/cache/backends/local-cache-backend.spec.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const os_1 = require("os");
+const fs_1 = require("fs");
+const local_cache_backend_1 = require("./local-cache-backend");
+const environment_mock_1 = require("../../executer/environment-mock");
+describe('local cache backend', () => {
+    let root;
+    let scratch;
+    beforeEach(() => {
+        root = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-local-cache-'));
+        scratch = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-local-cache-scratch-'));
+    });
+    afterEach(() => {
+        (0, fs_1.rmSync)(root, { recursive: true, force: true });
+        (0, fs_1.rmSync)(scratch, { recursive: true, force: true });
+    });
+    it('reports no hit when nothing pushed yet', async () => {
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: root });
+        expect(await backend.has('taskA', 'key1', env)).toBe(false);
+        expect(await backend.pull('taskA', 'key1', (0, path_1.join)(scratch, 'pull'), env)).toBe(false);
+    });
+    it('round-trips a task through push and pull', async () => {
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: root });
+        const sourceDir = (0, path_1.join)(scratch, 'src');
+        await env.file.createDirectory(sourceDir);
+        await env.file.writeFile((0, path_1.join)(sourceDir, 'stats.json'), '{"files":{}}');
+        await env.file.writeFile((0, path_1.join)(sourceDir, 'description.json'), '{}');
+        await env.file.writeFile((0, path_1.join)(sourceDir, 'dist-generates.tgz'), 'tarball-bytes');
+        await backend.push('taskA', 'key1', sourceDir, env);
+        expect(await backend.has('taskA', 'key1', env)).toBe(true);
+        const into = (0, path_1.join)(scratch, 'pull');
+        const ok = await backend.pull('taskA', 'key1', into, env);
+        expect(ok).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'stats.json'))).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'description.json'))).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'dist-generates.tgz'))).toBe(true);
+        expect(await env.file.read((0, path_1.join)(into, 'dist-generates.tgz'))).toBe('tarball-bytes');
+    });
+    it('isolates entries by stateKey', async () => {
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: root });
+        const sourceDir = (0, path_1.join)(scratch, 'src');
+        await env.file.createDirectory(sourceDir);
+        await env.file.writeFile((0, path_1.join)(sourceDir, 'stats.json'), '{}');
+        await backend.push('taskA', 'key1', sourceDir, env);
+        expect(await backend.has('taskA', 'key2', env)).toBe(false);
+    });
+    it('clear removes every state key of a task without touching others', async () => {
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: root });
+        const sourceDir = (0, path_1.join)(scratch, 'src');
+        await env.file.createDirectory(sourceDir);
+        await env.file.writeFile((0, path_1.join)(sourceDir, 'stats.json'), '{}');
+        await backend.push('taskA', 'key1', sourceDir, env);
+        await backend.push('taskA', 'key2', sourceDir, env);
+        await backend.push('taskB', 'key1', sourceDir, env);
+        await backend.clear('taskA', env);
+        expect(await backend.has('taskA', 'key1', env)).toBe(false);
+        expect(await backend.has('taskA', 'key2', env)).toBe(false);
+        expect(await backend.has('taskB', 'key1', env)).toBe(true);
+    });
+    it('clear is a no-op when the task has nothing cached', async () => {
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        const backend = (0, local_cache_backend_1.createLocalCacheBackend)({ type: 'local', path: root });
+        await expect(backend.clear('missing', env)).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=local-cache-backend.spec.js.map

package/dist/cache/backends/s3-cache-backend.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createS3CacheBackend = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const stream_1 = require("stream");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+// S3 object keys are arbitrary strings (unlike filesystem listings), so a
+// poisoned/shared bucket can return a key whose suffix contains `../` and escape
+// the restore directory once joined. Resolve the target and confirm it stays
+// within `into`; anything outside is dropped rather than written.
+function isWithin(into, filename) {
+    const base = (0, path_1.resolve)(into);
+    const target = (0, path_1.resolve)(base, filename);
+    return target === base || target.startsWith(base + path_1.sep);
+}
+function createS3CacheBackend(spec) {
+    const client = new client_s3_1.S3Client({
+        region: spec.region,
+        endpoint: spec.endpoint,
+        forcePathStyle: spec.forcePathStyle ?? !!spec.endpoint,
+    });
+    const prefix = (spec.prefix ?? '').replace(/^\/+|\/+$/g, '');
+    function keyFor(taskId, stateKey, filename) {
+        return [prefix, taskId, stateKey, filename].filter((p) => p.length > 0).join('/');
+    }
+    function dirPrefix(taskId, stateKey) {
+        return [prefix, taskId, stateKey].filter((p) => p.length > 0).join('/') + '/';
+    }
+    function taskPrefix(taskId) {
+        return [prefix, taskId].filter((p) => p.length > 0).join('/') + '/';
+    }
+    return {
+        type: 's3',
+        async has(taskId, stateKey) {
+            try {
+                await client.send(new client_s3_1.HeadObjectCommand({
+                    Bucket: spec.bucket,
+                    Key: keyFor(taskId, stateKey, 'stats.json'),
+                }));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async pull(taskId, stateKey, into, environment) {
+            try {
+                const head = await client
+                    .send(new client_s3_1.HeadObjectCommand({
+                    Bucket: spec.bucket,
+                    Key: keyFor(taskId, stateKey, 'stats.json'),
+                }))
+                    .catch(() => null);
+                if (!head) {
+                    return false;
+                }
+                await environment.file.createDirectory(into);
+                const listed = await client.send(new client_s3_1.ListObjectsV2Command({
+                    Bucket: spec.bucket,
+                    Prefix: dirPrefix(taskId, stateKey),
+                }));
+                for (const obj of listed.Contents ?? []) {
+                    if (!obj.Key)
+                        continue;
+                    const filename = obj.Key.substring(dirPrefix(taskId, stateKey).length);
+                    if (!filename)
+                        continue;
+                    if (!isWithin(into, filename)) {
+                        environment.console.warn(`skipping cache object outside restore dir: ${obj.Key}`);
+                        continue;
+                    }
+                    const body = await client.send(new client_s3_1.GetObjectCommand({
+                        Bucket: spec.bucket,
+                        Key: obj.Key,
+                    }));
+                    if (body.Body instanceof stream_1.Readable) {
+                        await environment.file.writeStream((0, path_1.join)(into, filename), body.Body);
+                    }
+                }
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async push(taskId, stateKey, from, environment) {
+            const files = await environment.file.listFiles(from);
+            const ordered = [
+                ...files.filter((f) => f !== 'stats.json' && f !== 'description.json'),
+                ...files.filter((f) => f === 'description.json'),
+                ...files.filter((f) => f === 'stats.json'),
+            ];
+            for (const file of ordered) {
+                const body = await (0, promises_1.readFile)((0, path_1.join)(from, file));
+                await client.send(new client_s3_1.PutObjectCommand({
+                    Bucket: spec.bucket,
+                    Key: keyFor(taskId, stateKey, file),
+                    Body: body,
+                }));
+            }
+        },
+        async clear(taskId) {
+            let token;
+            do {
+                const listed = await client.send(new client_s3_1.ListObjectsV2Command({
+                    Bucket: spec.bucket,
+                    Prefix: taskPrefix(taskId),
+                    ContinuationToken: token,
+                }));
+                const objects = (listed.Contents ?? []).filter((o) => o.Key).map((o) => ({ Key: o.Key }));
+                if (objects.length > 0) {
+                    await client.send(new client_s3_1.DeleteObjectsCommand({
+                        Bucket: spec.bucket,
+                        Delete: { Objects: objects },
+                    }));
+                }
+                token = listed.IsTruncated ? listed.NextContinuationToken : undefined;
+            } while (token);
+        },
+    };
+}
+exports.createS3CacheBackend = createS3CacheBackend;
+//# sourceMappingURL=s3-cache-backend.js.map

package/dist/cache/backends/s3-cache-backend.spec.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stream_1 = require("stream");
+// vi.hoisted: vi.mock is hoisted above this file's top-level code, so the factory
+// below can only reference variables that are themselves hoisted.
+const { sendMock } = vi.hoisted(() => ({ sendMock: vi.fn() }));
+vi.mock('@aws-sdk/client-s3', () => {
+    class S3ClientMock {
+        constructor() {
+            this.send = sendMock;
+        }
+    }
+    class GetObjectCommand {
+        constructor(input) {
+            this.input = input;
+        }
+    }
+    class PutObjectCommand {
+        constructor(input) {
+            this.input = input;
+        }
+    }
+    class HeadObjectCommand {
+        constructor(input) {
+            this.input = input;
+        }
+    }
+    class ListObjectsV2Command {
+        constructor(input) {
+            this.input = input;
+        }
+    }
+    return {
+        S3Client: S3ClientMock,
+        GetObjectCommand,
+        PutObjectCommand,
+        HeadObjectCommand,
+        ListObjectsV2Command,
+    };
+});
+const s3_cache_backend_1 = require("./s3-cache-backend");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const environment_mock_1 = require("../../executer/environment-mock");
+describe('s3 cache backend', () => {
+    let scratch;
+    beforeEach(() => {
+        sendMock.mockReset();
+        scratch = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-s3-spec-'));
+    });
+    afterEach(() => {
+        (0, fs_1.rmSync)(scratch, { recursive: true, force: true });
+    });
+    it('returns false from has() when HeadObject rejects', async () => {
+        sendMock.mockRejectedValueOnce(new Error('not found'));
+        const backend = (0, s3_cache_backend_1.createS3CacheBackend)({ type: 's3', bucket: 'b', region: 'us-east-1' });
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        expect(await backend.has('task', 'state', env)).toBe(false);
+    });
+    it('returns true when HeadObject resolves', async () => {
+        sendMock.mockResolvedValueOnce({});
+        const backend = (0, s3_cache_backend_1.createS3CacheBackend)({ type: 's3', bucket: 'b', region: 'us-east-1' });
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        expect(await backend.has('task', 'state', env)).toBe(true);
+    });
+    it('uploads files via PutObject with prefix + task + stateKey path', async () => {
+        sendMock.mockResolvedValue({});
+        const backend = (0, s3_cache_backend_1.createS3CacheBackend)({ type: 's3', bucket: 'b', prefix: 'p/', region: 'us-east-1' });
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        await env.file.writeFile((0, path_1.join)(scratch, 'stats.json'), '{}');
+        await env.file.writeFile((0, path_1.join)(scratch, 'description.json'), '{}');
+        await env.file.writeFile((0, path_1.join)(scratch, 'a-generates.tgz'), 'bytes');
+        await backend.push('task1', 'key1', scratch, env);
+        const keys = sendMock.mock.calls.map(([cmd]) => cmd.input.Key);
+        expect(keys).toContain('p/task1/key1/a-generates.tgz');
+        expect(keys).toContain('p/task1/key1/description.json');
+        expect(keys).toContain('p/task1/key1/stats.json');
+        // stats.json must be uploaded last so a partial push is invisible to has()/pull()
+        expect(keys[keys.length - 1]).toBe('p/task1/key1/stats.json');
+    });
+    it('downloads files into the local cache dir on pull', async () => {
+        const backend = (0, s3_cache_backend_1.createS3CacheBackend)({ type: 's3', bucket: 'b', region: 'us-east-1' });
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        // Order: Head, then List, then a Get per object
+        sendMock.mockResolvedValueOnce({}); // head
+        sendMock.mockResolvedValueOnce({
+            Contents: [{ Key: 'task/state/stats.json' }, { Key: 'task/state/dist.tgz' }],
+        });
+        sendMock.mockResolvedValueOnce({ Body: stream_1.Readable.from(['{}']) });
+        sendMock.mockResolvedValueOnce({ Body: stream_1.Readable.from(['tarball']) });
+        const into = (0, path_1.join)(scratch, 'pulled');
+        const ok = await backend.pull('task', 'state', into, env);
+        expect(ok).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'stats.json'))).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'dist.tgz'))).toBe(true);
+    });
+    it('does not write objects whose key escapes the restore dir on pull', async () => {
+        const backend = (0, s3_cache_backend_1.createS3CacheBackend)({ type: 's3', bucket: 'b', region: 'us-east-1' });
+        const env = (0, environment_mock_1.environmentMock)(scratch);
+        sendMock.mockResolvedValueOnce({}); // head
+        sendMock.mockResolvedValueOnce({
+            // a poisoned bucket can list a key whose suffix traverses out of the dir
+            Contents: [{ Key: 'task/state/../escape.txt' }, { Key: 'task/state/safe.txt' }],
+        });
+        // only the safe object should be fetched; the traversal entry is skipped before Get
+        sendMock.mockResolvedValueOnce({ Body: stream_1.Readable.from(['ok']) });
+        const into = (0, path_1.join)(scratch, 'pulled');
+        const ok = await backend.pull('task', 'state', into, env);
+        expect(ok).toBe(true);
+        expect(await env.file.exists((0, path_1.join)(into, 'safe.txt'))).toBe(true);
+        // ../escape.txt would resolve to scratch/escape.txt, outside `into`
+        expect(await env.file.exists((0, path_1.join)(scratch, 'escape.txt'))).toBe(false);
+        // the traversal entry must not trigger a GetObject (head + list + 1 get = 3)
+        expect(sendMock).toHaveBeenCalledTimes(3);
+    });
+});
+//# sourceMappingURL=s3-cache-backend.spec.js.map

package/dist/cache/cache-backend-registry.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCacheBackend = exports.registerCacheBackend = void 0;
+const local_cache_backend_1 = require("./backends/local-cache-backend");
+const s3_cache_backend_1 = require("./backends/s3-cache-backend");
+const factories = new Map();
+function registerCacheBackend(type, factory) {
+    factories.set(type, factory);
+}
+exports.registerCacheBackend = registerCacheBackend;
+function createCacheBackend(spec) {
+    const factory = factories.get(spec.type);
+    if (!factory) {
+        throw new Error(`unknown cache backend type: ${spec.type}`);
+    }
+    return factory(spec);
+}
+exports.createCacheBackend = createCacheBackend;
+registerCacheBackend('local', (spec) => (0, local_cache_backend_1.createLocalCacheBackend)(spec));
+registerCacheBackend('s3', (spec) => (0, s3_cache_backend_1.createS3CacheBackend)(spec));
+//# sourceMappingURL=cache-backend-registry.js.map

package/dist/cache/cache-backend-registry.spec.js

@@ -0,0 +1,22 @@
+"use strict";
+// The factory registry registers `local` and `s3` at import time. We can
+// exercise createCacheBackend for both registered types and the unknown-type
+// failure without needing the AWS SDK at runtime (`local` is real; for `s3`
+// we register a fake under a fresh type name).
+Object.defineProperty(exports, "__esModule", { value: true });
+const cache_backend_registry_1 = require("./cache-backend-registry");
+describe('createCacheBackend', () => {
+    it('builds a local backend from a {type:"local"} spec', () => {
+        const backend = (0, cache_backend_registry_1.createCacheBackend)({ type: 'local' });
+        expect(backend.type).toBe('local');
+    });
+    it('throws on an unknown backend type', () => {
+        expect(() => (0, cache_backend_registry_1.createCacheBackend)({ type: 'unknown-backend-xyz' })).toThrow(/unknown cache backend type: unknown-backend-xyz/);
+    });
+    it('dispatches to a registered custom factory', () => {
+        const fakeBackend = { type: 'fake' };
+        (0, cache_backend_registry_1.registerCacheBackend)('fake-backend', () => fakeBackend);
+        expect((0, cache_backend_registry_1.createCacheBackend)({ type: 'fake-backend' })).toBe(fakeBackend);
+    });
+});
+//# sourceMappingURL=cache-backend-registry.spec.js.map

package/dist/cache/cache-backend.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cache-backend.js.map

package/dist/cache/resolve-cache.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCache = exports.withBuiltinCaches = exports.builtinCaches = exports.NONE_CACHE_NAME = exports.DEFAULT_CACHE_NAME = void 0;
+const cache_backend_registry_1 = require("./cache-backend-registry");
+exports.DEFAULT_CACHE_NAME = 'default';
+exports.NONE_CACHE_NAME = 'none';
+// `default` caches to the local backend at its default path
+// (`~/.hammerkit/remote-cache`), so results are shared across checkouts on the
+// same machine. To use a different location or a shared/remote cache, redeclare
+// `caches.default` or add a named cache backed by `local`/`s3`/etc and reference
+// it from the task. `none` disables skipping entirely (its backend is inert).
+exports.builtinCaches = {
+    [exports.DEFAULT_CACHE_NAME]: { method: 'checksum', backend: { type: 'local' } },
+    [exports.NONE_CACHE_NAME]: { method: 'none', backend: { type: 'local' } },
+};
+function withBuiltinCaches(declared) {
+    const merged = { ...exports.builtinCaches };
+    if (declared) {
+        for (const [name, value] of Object.entries(declared)) {
+            merged[name] = value;
+        }
+    }
+    return merged;
+}
+exports.withBuiltinCaches = withBuiltinCaches;
+const backendInstances = new WeakMap();
+function getBackend(spec) {
+    let instance = backendInstances.get(spec);
+    if (!instance) {
+        instance = (0, cache_backend_registry_1.createCacheBackend)(spec.backend);
+        backendInstances.set(spec, instance);
+    }
+    return instance;
+}
+function isMethodShorthand(value) {
+    return typeof value === 'string';
+}
+function resolveCache(ref, catalog, taskName) {
+    if (ref === undefined || ref === null) {
+        return resolveByName(exports.DEFAULT_CACHE_NAME, undefined, catalog, taskName, true);
+    }
+    if (isMethodShorthand(ref)) {
+        return resolveByName(exports.DEFAULT_CACHE_NAME, ref, catalog, taskName, false);
+    }
+    return resolveByName(ref.name, ref.method, catalog, taskName, false);
+}
+exports.resolveCache = resolveCache;
+function resolveByName(name, methodOverride, catalog, taskName, implicit) {
+    const spec = catalog[name];
+    if (!spec) {
+        throw new Error(`cache "${name}" referenced by task "${taskName}" is not defined`);
+    }
+    return {
+        name,
+        method: methodOverride ?? spec.method,
+        backend: getBackend(spec),
+        implicit,
+    };
+}
+//# sourceMappingURL=resolve-cache.js.map

package/dist/cache/resolve-cache.spec.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const resolve_cache_1 = require("./resolve-cache");
+describe('resolveCache', () => {
+    const catalog = (0, resolve_cache_1.withBuiltinCaches)({
+        s3: { method: 'modify-date', backend: { type: 'local', path: '/tmp/fake' } },
+    });
+    it('uses the default cache when no ref is given', () => {
+        const r = (0, resolve_cache_1.resolveCache)(undefined, catalog, 'taskA');
+        expect(r.name).toBe('default');
+        expect(r.method).toBe('checksum');
+        expect(r.backend.type).toBe('local');
+        expect(r.implicit).toBe(true);
+    });
+    it('treats a string ref as a method override on default', () => {
+        const r = (0, resolve_cache_1.resolveCache)('modify-date', catalog, 'taskA');
+        expect(r.name).toBe('default');
+        expect(r.method).toBe('modify-date');
+        expect(r.backend.type).toBe('local');
+        expect(r.implicit).toBe(false);
+    });
+    it('uses none method when "none" string shorthand is used', () => {
+        const r = (0, resolve_cache_1.resolveCache)('none', catalog, 'taskA');
+        expect(r.method).toBe('none');
+    });
+    it('resolves a named reference and keeps its declared method', () => {
+        const r = (0, resolve_cache_1.resolveCache)({ name: 's3' }, catalog, 'taskA');
+        expect(r.name).toBe('s3');
+        expect(r.method).toBe('modify-date');
+    });
+    it('overrides the named cache method when the task sets one', () => {
+        const r = (0, resolve_cache_1.resolveCache)({ name: 's3', method: 'checksum' }, catalog, 'taskA');
+        expect(r.name).toBe('s3');
+        expect(r.method).toBe('checksum');
+    });
+    it('throws when an unknown name is referenced', () => {
+        expect(() => (0, resolve_cache_1.resolveCache)({ name: 'missing' }, catalog, 'taskA')).toThrow(/cache "missing" referenced by task "taskA"/);
+    });
+    it('seeds default and none even when nothing is declared', () => {
+        const empty = (0, resolve_cache_1.withBuiltinCaches)(undefined);
+        expect(empty.default.backend.type).toBe('local');
+        expect(empty.none.backend.type).toBe('local');
+    });
+    it('lets the user override the built-in default', () => {
+        const cat = (0, resolve_cache_1.withBuiltinCaches)({
+            default: { method: 'modify-date', backend: { type: 'local', path: '/tmp/x' } },
+        });
+        const r = (0, resolve_cache_1.resolveCache)(undefined, cat, 'taskA');
+        expect(r.method).toBe('modify-date');
+    });
+});
+//# sourceMappingURL=resolve-cache.spec.js.map