hammerkit 1.6.0 → 1.8.0

package/dist/testing/test-case.js

@@ -1,75 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTestCase = exports.getTestRunId = void 0;
-const path_1 = require("path");
-const get_file_context_1 = require("../file/get-file-context");
-const log_1 = require("../log");
-const work_item_status_1 = require("../planner/work-item-status");
-const program_1 = require("../program");
-const yaml_1 = require("yaml");
-const run_program_1 = require("../run-program");
-const test_streams_1 = require("./test-streams");
-function getTestRunId(name) {
-    const base = process.env.HAMMERKIT_TEST_RUN_ID ?? `local-${process.pid}`;
-    return `${base}-${name}`
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 63);
-}
-exports.getTestRunId = getTestRunId;
-function createTestCase(name, files) {
-    const runId = getTestRunId(name);
-    return {
-        runId,
-        async shell(args) {
-            await this.setup(async (cwd, env) => {
-                await (0, run_program_1.runProgram)(env, args, true);
-            });
-        },
-        async setup(fn) {
-            const path = (0, path_1.join)(process.cwd(), 'temp', name);
-            const file = (0, get_file_context_1.getFileContext)(path);
-            const statusStream = (0, test_streams_1.memoryStream)();
-            try {
-                await file.remove(path);
-                await file.createDirectory(path);
-                const environment = {
-                    processEnvs: { ...process.env, HAMMERKIT_TEST_RUN_ID: runId },
-                    abortCtrl: new AbortController(),
-                    cwd: path,
-                    file,
-                    console: (0, log_1.consoleContext)((0, test_streams_1.emptyStream)()),
-                    status: (0, work_item_status_1.statusConsole)(statusStream.stream),
-                    stdout: (0, test_streams_1.emptyStream)(),
-                    stderr: (0, test_streams_1.emptyStream)(),
-                    stdoutColumns: 80,
-                };
-                for (const [fileName, fileContent] of Object.entries(files)) {
-                    await file.createDirectory((0, path_1.dirname)((0, path_1.join)(path, fileName)));
-                    await file.writeFile((0, path_1.join)(path, fileName), typeof fileContent === 'string' ? fileContent : (0, yaml_1.stringify)(fileContent));
-                }
-                await fn(path, environment);
-            }
-            catch (e) {
-                process.stdout.write(statusStream.read());
-                throw e;
-            }
-        },
-        async cli(scope, fn) {
-            return this.setup(async (cwd, environment) => {
-                const fileName = (0, path_1.join)(cwd, '.hammerkit.yaml');
-                environment.processEnvs = { ...environment.processEnvs, ...(scope.envs ?? {}) };
-                const cli = await (0, program_1.createCli)(fileName, environment, scope);
-                // also clear the persistent backend cache (~/.hammerkit/remote-cache)
-                // so results don't leak between test runs on the same machine.
-                await cli.clean({ cache: true });
-                if (fn) {
-                    await fn(cli, environment);
-                }
-            });
-        },
-    };
-}
-exports.createTestCase = createTestCase;
-//# sourceMappingURL=test-case.js.map

package/dist/testing/test-streams.js

@@ -1,28 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryStream = exports.emptyStream = void 0;
-const stream_1 = require("stream");
-function emptyStream() {
-    const stream = new stream_1.Writable();
-    stream._write = function (_chunk, _encoding, done) {
-        done();
-    };
-    return stream;
-}
-exports.emptyStream = emptyStream;
-function memoryStream() {
-    const stream = new stream_1.Writable();
-    const chunks = [];
-    stream._write = function (chunk, encoding, done) {
-        chunks.push(chunk.toString());
-        done();
-    };
-    return {
-        stream,
-        read() {
-            return chunks.join('');
-        },
-    };
-}
-exports.memoryStream = memoryStream;
-//# sourceMappingURL=test-streams.js.map

package/dist/testing/test-suite-setup.js

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

package/dist/testing/test-suite.js

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

package/dist/testing/testing-timeout.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.testingTimeout = void 0;
-const plan_work_tasks_1 = require("../planner/utils/plan-work-tasks");
-async function testingTimeout(exec, timeout) {
-    const timer = setTimeout(() => {
-        for (const task of (0, plan_work_tasks_1.iterateWorkTasks)(exec.state.current)) {
-            printWorkItem(task);
-        }
-        for (const service of (0, plan_work_tasks_1.iterateWorkServices)(exec.state.current)) {
-            printWorkItem(service);
-        }
-    }, (timeout || 45 * 1000) - 2000);
-    try {
-        return await exec.start();
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-exports.testingTimeout = testingTimeout;
-function printWorkItem(task) {
-    const messages = [` - ${task.name}: ${task.state.current.type}`];
-    for (const log of task.status.logs()) {
-        messages.push(` console ${log.console}: ${log.message}`);
-    }
-    for (const log of task.status.read()) {
-        messages.push(` status ${log.level}: ${log.message}`);
-    }
-    process.stdout.write(messages.join('\n'));
-}
-//# sourceMappingURL=testing-timeout.js.map

package/dist/utils/abort-event.spec.js

@@ -1,46 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const abort_event_1 = require("./abort-event");
-describe('abort-event', () => {
-    describe('listenOnAbort', () => {
-        it('fires immediately when the signal is already aborted', () => {
-            const ctrl = new AbortController();
-            ctrl.abort();
-            const cb = vi.fn();
-            const handle = (0, abort_event_1.listenOnAbort)(ctrl.signal, cb);
-            expect(cb).toHaveBeenCalledTimes(1);
-            // close on a pre-aborted listener is a no-op; calling it must not throw.
-            expect(() => handle.close()).not.toThrow();
-        });
-        it('fires when the signal is aborted later', () => {
-            const ctrl = new AbortController();
-            const cb = vi.fn();
-            (0, abort_event_1.listenOnAbort)(ctrl.signal, cb);
-            expect(cb).not.toHaveBeenCalled();
-            ctrl.abort();
-            expect(cb).toHaveBeenCalledTimes(1);
-        });
-        it('does not fire after close()', () => {
-            const ctrl = new AbortController();
-            const cb = vi.fn();
-            const handle = (0, abort_event_1.listenOnAbort)(ctrl.signal, cb);
-            handle.close();
-            ctrl.abort();
-            expect(cb).not.toHaveBeenCalled();
-        });
-    });
-    describe('waitOnAbort', () => {
-        it('resolves immediately when already aborted', async () => {
-            const ctrl = new AbortController();
-            ctrl.abort();
-            await expect((0, abort_event_1.waitOnAbort)(ctrl.signal)).resolves.toBeUndefined();
-        });
-        it('resolves when the signal is aborted later', async () => {
-            const ctrl = new AbortController();
-            const pending = (0, abort_event_1.waitOnAbort)(ctrl.signal);
-            ctrl.abort();
-            await expect(pending).resolves.toBeUndefined();
-        });
-    });
-});
-//# sourceMappingURL=abort-event.spec.js.map

package/dist/utils/buffer-context.spec.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const buffer_context_1 = require("./buffer-context");
-describe('BufferContext', () => {
-    it('returns null for current of an unknown id', () => {
-        const ctx = new buffer_context_1.BufferContext(10);
-        expect(ctx.current('missing')).toBeNull();
-    });
-    it('returns an empty array for get of an unknown id', () => {
-        const ctx = new buffer_context_1.BufferContext(10);
-        expect(ctx.get('missing')).toEqual([]);
-    });
-    it('tracks the latest value per id', () => {
-        const ctx = new buffer_context_1.BufferContext(10);
-        ctx.add('a', 1);
-        ctx.add('a', 2);
-        ctx.add('b', 9);
-        expect(ctx.current('a')).toBe(2);
-        expect(ctx.current('b')).toBe(9);
-    });
-    it('keeps per-id and global buffers', () => {
-        const ctx = new buffer_context_1.BufferContext(10);
-        ctx.add('a', 1);
-        ctx.add('b', 2);
-        expect(ctx.get('a')).toEqual([1]);
-        expect(ctx.get('b')).toEqual([2]);
-        expect(ctx.get()).toEqual([1, 2]);
-    });
-    it('evicts the oldest global entry once an id exceeds the limit', () => {
-        const ctx = new buffer_context_1.BufferContext(2);
-        ctx.add('a', 1);
-        ctx.add('a', 2);
-        ctx.add('a', 3);
-        expect(ctx.get()).toEqual([2, 3]);
-        expect(ctx.current('a')).toBe(3);
-    });
-});
-//# sourceMappingURL=buffer-context.spec.js.map

package/dist/utils/ci.spec.js

@@ -1,53 +0,0 @@
-"use strict";
-// Each `isCI` arm is evaluated once at module load, so the only way to cover
-// every branch of the OR chain is to load the module repeatedly under different
-// process.env. vi.resetModules + a fresh dynamic import gives us that.
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-const KEYS = ['CI', 'CONTINUOUS_INTEGRATION', 'BUILD_NUMBER', 'RUN_ID'];
-async function loadIsCI(set) {
-    for (const k of KEYS)
-        delete process.env[k];
-    if (set)
-        Object.assign(process.env, set);
-    vi.resetModules();
-    return (await Promise.resolve().then(() => __importStar(require('./ci')))).isCI;
-}
-describe('isCI', () => {
-    const original = { ...process.env };
-    afterEach(() => {
-        for (const k of KEYS)
-            delete process.env[k];
-        for (const k of KEYS)
-            if (k in original)
-                process.env[k] = original[k];
-    });
-    it('is false when no CI env var is set', async () => {
-        expect(await loadIsCI()).toBe(false);
-    });
-    it.each(KEYS)('is true when %s is set', async (key) => {
-        expect(await loadIsCI({ [key]: '1' })).toBe(true);
-    });
-});
-//# sourceMappingURL=ci.spec.js.map

package/dist/utils/debouncer.spec.js

@@ -1,58 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const debouncer_1 = require("./debouncer");
-const sleep_1 = require("./sleep");
-describe('utils/debouncer', () => {
-    it('should not trigger before start', async () => {
-        let called = false;
-        new debouncer_1.Debouncer(() => {
-            called = true;
-        }, 10);
-        await (0, sleep_1.sleep)(20);
-        expect(called).toBeFalsy();
-    });
-    it('should trigger after start', async () => {
-        let called = false;
-        const debouncer = new debouncer_1.Debouncer(() => {
-            called = true;
-        }, 10);
-        debouncer.start();
-        await (0, sleep_1.sleep)(20);
-        expect(called).toBeTruthy();
-    });
-    it('should delay trigger after bounce', async () => {
-        let called = false;
-        const debouncer = new debouncer_1.Debouncer(() => {
-            called = true;
-        }, 20);
-        debouncer.start();
-        await (0, sleep_1.sleep)(10);
-        debouncer.bounce();
-        await (0, sleep_1.sleep)(15);
-        expect(called).toBeFalsy();
-        await (0, sleep_1.sleep)(5);
-        expect(called).toBeTruthy();
-    });
-    it('should cancel trigger after clear', async () => {
-        let called = false;
-        const debouncer = new debouncer_1.Debouncer(() => {
-            called = true;
-        }, 20);
-        debouncer.start();
-        await (0, sleep_1.sleep)(10);
-        debouncer.clear();
-        await (0, sleep_1.sleep)(15);
-        expect(called).toBeFalsy();
-    });
-    it('should trigger on flush', async () => {
-        let called = false;
-        const debouncer = new debouncer_1.Debouncer(() => {
-            called = true;
-        }, 20);
-        debouncer.start();
-        await (0, sleep_1.sleep)(5);
-        debouncer.flush();
-        expect(called).toBeTruthy();
-    });
-});
-//# sourceMappingURL=debouncer.spec.js.map

package/dist/utils/emitter.spec.js

@@ -1,34 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const emitter_1 = require("./emitter");
-describe('emitter', () => {
-    it('invokes every registered listener on emit', () => {
-        const e = (0, emitter_1.emitter)();
-        const a = vi.fn();
-        const b = vi.fn();
-        e.on(a);
-        e.on(b);
-        e.emit(42);
-        expect(a).toHaveBeenCalledWith(42);
-        expect(b).toHaveBeenCalledWith(42);
-    });
-    it('emit with no listeners is a no-op', () => {
-        const e = (0, emitter_1.emitter)();
-        expect(() => e.emit('noop')).not.toThrow();
-    });
-    it('close() removes the listener from future emits', () => {
-        const e = (0, emitter_1.emitter)();
-        const cb = vi.fn();
-        const handle = e.on(cb);
-        handle.close();
-        e.emit(1);
-        expect(cb).not.toHaveBeenCalled();
-    });
-    it('close() called twice is safe (no listener to remove)', () => {
-        const e = (0, emitter_1.emitter)();
-        const handle = e.on(vi.fn());
-        handle.close();
-        expect(() => handle.close()).not.toThrow();
-    });
-});
-//# sourceMappingURL=emitter.spec.js.map

package/dist/utils/empty-writable.spec.js

@@ -1,18 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const empty_writable_1 = require("./empty-writable");
-describe('emptyWritable', () => {
-    it('accepts writes and invokes the callback', async () => {
-        const stream = (0, empty_writable_1.emptyWritable)();
-        await new Promise((resolve, reject) => {
-            stream.write('hello', (err) => (err ? reject(err) : resolve()));
-        });
-    });
-    it('ends cleanly after writes', async () => {
-        const stream = (0, empty_writable_1.emptyWritable)();
-        stream.write('a');
-        stream.write('b');
-        await new Promise((resolve) => stream.end(resolve));
-    });
-});
-//# sourceMappingURL=empty-writable.spec.js.map

package/dist/utils/environment-config.spec.js

@@ -1,26 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const environment_config_1 = require("./environment-config");
-const VAR = 'HAMMERKIT_TEST_ENV_CONFIG';
-describe('getEnvironmentConfig', () => {
-    afterEach(() => {
-        delete process.env[VAR];
-    });
-    it('returns the default when the variable is unset', () => {
-        delete process.env[VAR];
-        expect((0, environment_config_1.getEnvironmentConfig)(VAR, 7)).toBe(7);
-    });
-    it('parses an integer env value', () => {
-        process.env[VAR] = '42';
-        expect((0, environment_config_1.getEnvironmentConfig)(VAR, 7)).toBe(42);
-    });
-    it('falls back to the default when the env value is not a number', () => {
-        process.env[VAR] = 'not-a-number';
-        expect((0, environment_config_1.getEnvironmentConfig)(VAR, 7)).toBe(7);
-    });
-    it('treats an empty string env value as not-a-number and uses the default', () => {
-        process.env[VAR] = '';
-        expect((0, environment_config_1.getEnvironmentConfig)(VAR, 5)).toBe(5);
-    });
-});
-//# sourceMappingURL=environment-config.spec.js.map

package/dist/utils/fail-never.spec.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const fail_never_1 = require("./fail-never");
-describe('failNever', () => {
-    it('throws an error with the given message', () => {
-        expect(() => (0, fail_never_1.failNever)('value', 'unexpected')).toThrow('unexpected');
-    });
-});
-//# sourceMappingURL=fail-never.spec.js.map

package/dist/utils/sleep.spec.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const sleep_1 = require("./sleep");
-describe('utils/sleep', () => {
-    it('should resolve not before timeout', () => {
-        let called = false;
-        (0, sleep_1.sleep)(10).then(() => {
-            called = true;
-        });
-        expect(called).toBeFalsy();
-    });
-    it('should resolve after timeout', async () => {
-        let called = false;
-        (0, sleep_1.sleep)(10).then(() => {
-            called = true;
-        });
-        expect(called).toBeFalsy();
-        await (0, sleep_1.sleep)(10);
-        expect(called).toBeTruthy();
-    });
-});
-//# sourceMappingURL=sleep.spec.js.map

package/dist/version.spec.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const version_1 = require("./version");
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const pkg = require('../package.json');
-describe('getVersion', () => {
-    it('returns the version from package.json', () => {
-        expect((0, version_1.getVersion)()).toBe(pkg.version);
-        expect((0, version_1.getVersion)()).toMatch(/^\d+\.\d+\.\d+/);
-    });
-});
-//# sourceMappingURL=version.spec.js.map

package/specs/build-file/caches/spec.md

@@ -1,114 +0,0 @@
-# Feature Specification: Build File: Caches
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/caches.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Skip unchanged tasks using the default local cache (Priority: P1)
-
-A developer runs hammerkit for the first time. Results are stored in the local cache (`~/.hammerkit/remote-cache`). On subsequent runs, hammerkit compares source file checksums and skips tasks whose inputs have not changed, saving build time without any configuration.
-
-**Why this priority**: Local caching is the out-of-the-box experience for every hammerkit user; it is always active.
-
-**Independent Test**: Run a task twice without modifying source files. Confirm the second run skips execution. Modify a source file and confirm the task runs again.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `src:` files that have not changed since the last run, **When** the task is invoked, **Then** hammerkit skips execution and reports the task as up-to-date.
-2. **Given** a task with `src:` files where at least one has changed, **When** the task is invoked, **Then** hammerkit executes the task commands.
-
-### User Story 2 - Share build results across machines via a remote cache (Priority: P1)
-
-A team uses an S3 bucket as a shared cache. When a developer or CI job completes a task, the result is pushed to S3. The next machine to request the same task pulls the cached result and skips execution, dramatically reducing CI time.
-
-**Why this priority**: Remote caching is the primary new capability in 1.6.0 and a key differentiator for team and CI workflows.
-
-**Independent Test**: Declare an S3-backed cache, run a task on machine A and confirm the result is pushed. On machine B (with empty local cache), run the same task and confirm it is pulled and skipped.
-
-**Acceptance Scenarios**:
-
-1. **Given** a named cache with `type: s3` is declared and a task references it, **When** a task completes successfully, **Then** the result is pushed to the configured S3 bucket.
-2. **Given** the S3 bucket contains a cached result for the current source checksum, **When** the task is invoked on a machine without a local result, **Then** hammerkit pulls from the bucket and skips task execution.
-3. **Given** the S3 backend is unreachable, **When** a task runs, **Then** hammerkit emits a warning and continues — the pull or push failure does NOT fail the build.
-
-### User Story 3 - Override the default cache for all tasks (Priority: P2)
-
-A team wants all tasks to use a remote S3 bucket without modifying each task individually. They declare a `caches.default` entry in the build file, redirecting the implicit default cache to their S3 bucket.
-
-**Why this priority**: This is the recommended way to enable remote caching for an entire project with a single configuration change.
-
-**Independent Test**: Declare `caches.default` pointing to S3, run several tasks that do not explicitly reference any cache, and confirm each pushes results to the S3 bucket.
-
-**Acceptance Scenarios**:
-
-1. **Given** `caches.default` is declared with an S3 backend, **When** a task that does not reference any named cache runs and succeeds, **Then** its result is pushed to the S3 bucket specified in `caches.default`.
-
-### User Story 4 - Choose a change-detection method for a cache (Priority: P2)
-
-A developer with a large source tree wants faster change detection. They configure a named cache to use `modify-date` instead of `checksum`. A CI workflow that must always rebuild configures a cache with `none` method.
-
-**Why this priority**: Method selection lets users trade precision for speed or disable skipping entirely for correctness-critical pipelines.
-
-**Independent Test**: Configure a task with `method: none`; run it twice and confirm it always executes. Configure a task with `method: modify-date`; run it twice without touching files and confirm it is skipped.
-
-**Acceptance Scenarios**:
-
-1. **Given** a cache with `method: none`, **When** any task using that cache is invoked, **Then** the task always executes, regardless of source file state.
-2. **Given** a cache with `method: checksum` (default), **When** source file content is identical to the previous run, **Then** the task is skipped.
-3. **Given** a cache with `method: modify-date`, **When** source file modification timestamps are unchanged, **Then** the task is skipped without computing checksums.
-
-### Edge Cases
-
-- Two built-in caches are always available: `default` (local backend, checksum method) and `none` (disables skipping).
-- Declaring `caches.default` overrides the built-in `default` cache for all tasks that do not explicitly reference a cache.
-- The `--cache` CLI flag overrides the method for implicit (non-explicitly-referenced) tasks at runtime and takes precedence over what `caches.default` declares for the method.
-- S3 credentials are never stored in the build file; they are read from the AWS SDK credential chain.
-- Azure Blob Storage is explicitly unsupported through the built-in `s3` backend.
-- Any S3-compatible service (MinIO, Cloudflare R2, GCS via HMAC keys) can be used via the `endpoint` field.
-- `forcePathStyle` defaults to `true` when a custom `endpoint` is set.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `caches:` map where each entry declares a named cache with a `method` and a `backend`.
-- **FR-002**: Each cache entry MUST support a `method` field with values `checksum` (default), `modify-date`, or `none`.
-- **FR-003**: Each cache entry MUST support a `backend` field specifying the storage backend type (`local` or `s3`).
-- **FR-004**: The `local` backend MUST accept an optional `path` field; when omitted it MUST default to `~/.hammerkit/remote-cache`.
-- **FR-005**: The `s3` backend MUST require a `bucket` field and accept optional `region`, `endpoint`, `prefix`, and `forcePathStyle` fields.
-- **FR-006**: S3 credentials MUST be sourced from the AWS SDK credential chain and MUST NOT be stored in the build file.
-- **FR-007**: Before a task runs, the system MUST attempt to pull a cached result from the backend if no local result is present; if the sources are unchanged, the task MUST be skipped.
-- **FR-008**: After a task completes successfully, the system MUST push the result to the configured backend.
-- **FR-009**: Backend errors during pull or push MUST emit a warning and MUST NOT cause the build to fail.
-- **FR-010**: Declaring `caches.default` MUST override the built-in default cache for all tasks that do not explicitly reference a named cache.
-- **FR-011**: A built-in `none` cache MUST always be available, which disables task skipping entirely.
-- **FR-012**: A task MUST be able to reference a named cache by setting `cache.name` in its task configuration.
-
-### Key Entities
-
-- **Cache**: A named entry in the `caches:` map; contains a `method` (change detection strategy) and a `backend` (storage configuration).
-- **Local Backend**: Stores cache entries on the local filesystem; configurable via a `path` field.
-- **S3 Backend**: Stores cache entries in an S3-compatible bucket; configurable via `bucket`, `region`, `endpoint`, `prefix`, and `forcePathStyle`.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: An unchanged task is skipped on the second invocation when using the default local cache with `checksum` method.
-- **SC-002**: A task result pushed from one machine is pulled and skips execution on a second machine using the same S3-backed cache configuration.
-- **SC-003**: A build completes successfully even when the configured S3 backend is unreachable, with a warning visible in the output.
-- **SC-004**: Declaring `caches.default` with an S3 backend causes all tasks (that do not explicitly reference a different cache) to push their results to that S3 bucket.
-- **SC-005**: A task using `method: none` executes on every invocation regardless of whether source files have changed.
-
-## Assumptions
-
-- The `cache.name` field on a task (referencing a named cache) is the task-level hook into this feature; full task-level caching options are covered by the task/caching spec page.
-- The `--cache` CLI flag controls the method for tasks using the implicit default cache; it does not affect tasks that explicitly reference a named cache by name.
-- "Pulling" a cached result means restoring the task's `generates:` outputs so downstream tasks can use them without re-running the producing task.
-- The `checksum` method hashes file content; `modify-date` compares filesystem mtime; both apply to the files listed in the task's `src:` field.