hammerkit 1.6.0 → 1.7.0

package/dist/program.js

@@ -10,6 +10,10 @@ const ci_1 = require("./utils/ci");
 const parse_label_arguments_1 = require("./parser/parse-label-arguments");
 const cli_1 = require("./cli");
 const log_1 = require("./log");
+const empty_writable_1 = require("./utils/empty-writable");
+const explain_1 = require("./cache/explain");
+const run_summary_1 = require("./executer/run-summary");
+const dry_run_1 = require("./executer/dry-run");
 const label_values_1 = require("./executer/label-values");
 const default_build_file_1 = require("./parser/default-build-file");
 const schema_parser_1 = require("./schema/schema-parser");
@@ -17,6 +21,9 @@ const work_scope_parser_1 = require("./schema/work-scope-parser");
 const reference_parser_1 = require("./schema/reference-parser");
 const colors_1 = __importDefault(require("colors"));
 const version_1 = require("./version");
+const read_only_1 = require("./cache/read-only");
+const units_1 = require("./utils/units");
+const cache_inventory_1 = require("./cache/cache-inventory");
 async function createCli(fileName, environment, workScope) {
     const { ctx, scope } = await (0, schema_parser_1.createParseContext)(fileName, environment);
     const referencedScope = await (0, reference_parser_1.parseReferences)(ctx, scope, environment);
@@ -233,6 +240,179 @@ async function getProgram(environment, argv) {
                 program.error('Detected errors in the hammerkit configuration', { exitCode: 1 });
             }
         });
+        program
+            .command('graph [task]')
+            .description('serialize the build graph (tasks, services, deps/needs edges) as mermaid or dot')
+            .addOption(new commander_1.Option('-f, --filter <labels...>', 'filter task and services with labels'))
+            .addOption(new commander_1.Option('-e, --exclude <labels...>', 'exclude task and services with labels'))
+            .addOption(new commander_1.Option('--env <name>', 'environment'))
+            .addOption(new commander_1.Option('--format <format>', 'output format').default('mermaid').choices(['mermaid', 'dot']))
+            .action(async (task, options) => {
+            try {
+                const cli = await createCli(fileName, environment, task ? { taskName: task, environmentName: options.env ?? null } : parseWorkLabelScope(options));
+                const serialization = cli.graph(options.format);
+                environment.stdout.write(`${serialization.output}\n`);
+                if (serialization.cycle) {
+                    environment.console.warn(`cycle detected: ${serialization.cycle.join(' -> ')}`);
+                }
+            }
+            catch (e) {
+                if (e instanceof commander_1.CommanderError) {
+                    throw e;
+                }
+                environment.console.error((0, log_1.getErrorMessage)(e));
+                program.error('Graph was not successful', { exitCode: 1 });
+            }
+        });
+        program
+            .command('explain [task]')
+            .description('explain whether tasks would be a cache hit or miss, without running them')
+            .addOption(new commander_1.Option('-f, --filter <labels...>', 'filter task and services with labels'))
+            .addOption(new commander_1.Option('-e, --exclude <labels...>', 'exclude task and services with labels'))
+            .addOption(new commander_1.Option('--env <name>', 'environment'))
+            .addOption(new commander_1.Option('--cache <method>', 'caching method to compare')
+            .default('checksum')
+            .choices(['checksum', 'modify-date', 'none']))
+            .addOption(new commander_1.Option('--json', 'emit the explanation as JSON').default(false))
+            .action(async (task, options) => {
+            try {
+                const cli = await createCli(fileName, environment, task ? { taskName: task, environmentName: options.env ?? null } : parseWorkLabelScope(options));
+                const explanations = await cli.explain({ cacheDefault: options.cache });
+                if (options.json) {
+                    environment.stdout.write(`${JSON.stringify(explanations, null, 2)}\n`);
+                    return;
+                }
+                for (const explanation of explanations) {
+                    const label = explanation.status === 'hit'
+                        ? colors_1.default.green('cache hit')
+                        : explanation.status === 'uncacheable'
+                            ? colors_1.default.grey('uncacheable')
+                            : colors_1.default.yellow('cache miss');
+                    environment.stdout.write(`• ${explanation.taskName}: ${label}\n`);
+                    for (const cause of explanation.causes) {
+                        (0, log_1.printProperty)(environment, 'cause', (0, explain_1.describeCause)(cause));
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof commander_1.CommanderError) {
+                    throw e;
+                }
+                environment.console.error((0, log_1.getErrorMessage)(e));
+                program.error('Explain was not successful', { exitCode: 1 });
+            }
+        });
+        const cacheCommand = program.command('cache').description('inspect, prune and move cache entries');
+        for (const direction of ['pull', 'push']) {
+            cacheCommand
+                .command(`${direction} [task]`)
+                .description(direction === 'pull'
+                ? 'fetch the cache entries of the current state from a remote cache, without running tasks'
+                : 'upload the locally cached entries of the current state to a remote cache, without running tasks')
+                .addOption(new commander_1.Option('--remote <name>', 'remote cache declared in the caches block').makeOptionMandatory())
+                .addOption(new commander_1.Option('-f, --filter <labels...>', 'filter task and services with labels'))
+                .addOption(new commander_1.Option('-e, --exclude <labels...>', 'exclude task and services with labels'))
+                .addOption(new commander_1.Option('--env <name>', 'environment'))
+                .addOption(new commander_1.Option('--cache <method>', 'caching method to compare')
+                .default('checksum')
+                .choices(['checksum', 'modify-date', 'none']))
+                .action(async (task, options) => {
+                try {
+                    if (direction === 'push' && (0, read_only_1.isCacheReadOnly)(false, environment.processEnvs)) {
+                        program.error(`cache is read-only (${read_only_1.CACHE_READ_ONLY_ENV} is set), refusing to push`, { exitCode: 1 });
+                        return;
+                    }
+                    const cli = await createCli(fileName, environment, task ? { taskName: task, environmentName: options.env ?? null } : parseWorkLabelScope(options));
+                    const results = await cli.syncCache({ direction, remote: options.remote, cacheDefault: options.cache });
+                    const labels = {
+                        transferred: colors_1.default.green(direction === 'pull' ? 'pulled' : 'pushed'),
+                        present: colors_1.default.grey('already present'),
+                        missing: colors_1.default.yellow(direction === 'pull' ? 'not in remote' : 'not in local cache'),
+                        skipped: colors_1.default.grey('skipped'),
+                    };
+                    for (const result of results) {
+                        environment.stdout.write(`• ${result.taskName}: ${labels[result.status]}\n`);
+                    }
+                    const moved = results.filter((r) => r.status === 'transferred').length;
+                    environment.stdout.write(`${moved}/${results.length} entries ${direction === 'pull' ? 'pulled' : 'pushed'}\n`);
+                }
+                catch (e) {
+                    if (e instanceof commander_1.CommanderError) {
+                        throw e;
+                    }
+                    environment.console.error((0, log_1.getErrorMessage)(e));
+                    program.error(`Cache ${direction} was not successful: ${(0, log_1.getErrorMessage)(e)}`, { exitCode: 1 });
+                }
+            });
+        }
+        const describeEntry = (entry) => `${entry.taskName ?? colors_1.default.grey(entry.taskId.substring(0, 12))} ${colors_1.default.grey(entry.stateKey.substring(0, 12))} ` +
+            `${entry.size === null ? '?' : (0, units_1.formatSize)(entry.size)}` +
+            (entry.lastAccessedAt ?? entry.createdAt
+                ? colors_1.default.grey(` last used ${(0, units_1.formatDuration)(Date.now() - (entry.lastAccessedAt ?? entry.createdAt ?? 0))} ago`)
+                : '');
+        const totalSize = (entries) => (0, units_1.formatSize)(entries.reduce((sum, entry) => sum + (entry.size ?? 0), 0));
+        const countOf = (count) => `${count} ${count === 1 ? 'entry' : 'entries'}`;
+        cacheCommand
+            .command('ls')
+            .description('list the entries of a cache (default: the local default cache)')
+            .addOption(new commander_1.Option('--remote <name>', 'cache declared in the caches block to list'))
+            .addOption(new commander_1.Option('--json', 'emit the entries as JSON').default(false))
+            .action(async (options) => {
+            try {
+                const cli = await createCli(fileName, environment, parseWorkLabelScope({}));
+                const entries = await cli.listCache(options.remote);
+                if (options.json) {
+                    environment.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+                    return;
+                }
+                for (const entry of entries) {
+                    environment.stdout.write(`• ${describeEntry(entry)}\n`);
+                }
+                environment.stdout.write(`${countOf(entries.length)}, ${totalSize(entries)} total\n`);
+            }
+            catch (e) {
+                if (e instanceof commander_1.CommanderError) {
+                    throw e;
+                }
+                program.error(`Cache ls was not successful: ${(0, log_1.getErrorMessage)(e)}`, { exitCode: 1 });
+            }
+        });
+        cacheCommand
+            .command('prune')
+            .description('remove cache entries by retention policy (default: the local default cache)')
+            .addOption(new commander_1.Option('--remote <name>', 'cache declared in the caches block to prune'))
+            .addOption(new commander_1.Option('--max-age <duration>', 'remove entries not used within this long (e.g. 30d)').argParser(units_1.parseDuration))
+            .addOption(new commander_1.Option('--max-size <size>', 'remove least recently used entries above this size (e.g. 5Gi)').argParser(units_1.parseSize))
+            .addOption(new commander_1.Option('--keep <count>', 'keep only the newest versions per task').argParser((v) => parseInt(v, 10)))
+            .addOption(new commander_1.Option('--dry-run', 'show what would be removed without removing it').default(false))
+            .action(async (options) => {
+            try {
+                const cli = await createCli(fileName, environment, parseWorkLabelScope({}));
+                const policy = cli.retentionPolicy(options.remote, {
+                    maxAge: options.maxAge,
+                    maxSize: options.maxSize,
+                    keepPerTask: options.keep,
+                });
+                if (!(0, cache_inventory_1.hasPolicy)(policy)) {
+                    program.error('no retention policy: pass --max-age, --max-size or --keep, or declare retention on the cache', { exitCode: 1 });
+                    return;
+                }
+                const plan = await cli.pruneCache(options.remote, policy, options.dryRun);
+                for (const entry of plan.evict) {
+                    environment.stdout.write(`• ${options.dryRun ? 'would remove' : 'removed'} ${describeEntry(entry)}\n`);
+                }
+                for (const note of plan.unavailable) {
+                    environment.console.warn(note);
+                }
+                environment.stdout.write(`${options.dryRun ? 'would remove' : 'removed'} ${countOf(plan.evict.length)} (${totalSize(plan.evict)}), ` + `kept ${countOf(plan.keep.length)} (${totalSize(plan.keep)})\n`);
+            }
+            catch (e) {
+                if (e instanceof commander_1.CommanderError) {
+                    throw e;
+                }
+                program.error(`Cache prune was not successful: ${(0, log_1.getErrorMessage)(e)}`, { exitCode: 1 });
+            }
+        });
         program
             .command('up')
             .description('start services(s)')
@@ -248,6 +428,8 @@ async function getProgram(environment, argv) {
             .addOption(new commander_1.Option('--cache <method>', 'caching method to compare')
             .default('checksum')
             .choices(['checksum', 'modify-date', 'none']))
+            .addOption(new commander_1.Option('--cache-read-only', `restore from cache backends but never push to them (or set ${read_only_1.CACHE_READ_ONLY_ENV}=1)`).default(false))
+            .addOption(new commander_1.Option('--timeout <duration>', 'fail tasks without their own timeout after this long (e.g. 10m)').argParser(units_1.parseDuration))
             .action(async (options) => {
             try {
                 const scope = parseWorkLabelScope(options);
@@ -258,6 +440,8 @@ async function getProgram(environment, argv) {
                     workers: options.concurrency,
                     logMode: options.log,
                     daemon: options.daemon,
+                    cacheReadOnly: (0, read_only_1.isCacheReadOnly)(options.cacheReadOnly, environment.processEnvs),
+                    timeout: options.timeout ?? null,
                 });
                 if (!result.success) {
                     program.error('Up was not successful', { exitCode: 1 });
@@ -311,22 +495,72 @@ async function getProgram(environment, argv) {
             .addOption(new commander_1.Option('--cache <method>', 'caching method to compare')
             .default('checksum')
             .choices(['checksum', 'modify-date', 'none']))
+            .addOption(new commander_1.Option('--no-summary', 'do not print the end-of-run summary'))
+            .addOption(new commander_1.Option('--summary-json', 'emit the end-of-run summary as JSON').default(false))
+            .addOption(new commander_1.Option('--explain', 'print the cache-miss cause when a task rebuilds').default(false))
+            .addOption(new commander_1.Option('--dry-run', 'print the execution plan with predicted cache hits/misses without running').default(false))
+            .addOption(new commander_1.Option('--cache-read-only', `restore from cache backends but never push to them (or set ${read_only_1.CACHE_READ_ONLY_ENV}=1)`).default(false))
+            .addOption(new commander_1.Option('--timeout <duration>', 'fail tasks without their own timeout after this long (e.g. 10m)').argParser(units_1.parseDuration))
+            .addOption(new commander_1.Option('--no-skip-deps', 'run dependencies even when every task needing them is a cache hit'))
             .action(async (task, options) => {
             try {
-                const cli = await createCli(fileName, environment, task ? { taskName: task, environmentName: options.env } : parseWorkLabelScope(options));
+                // For machine-readable JSON, suppress the human progress logger (which
+                // also writes to stdout) so the only thing on stdout is the JSON.
+                const runEnvironment = options.summaryJson
+                    ? { ...environment, stdout: (0, empty_writable_1.emptyWritable)(), console: (0, log_1.consoleContext)((0, empty_writable_1.emptyWritable)()) }
+                    : environment;
+                const cli = await createCli(fileName, runEnvironment, task ? { taskName: task, environmentName: options.env } : parseWorkLabelScope(options));
                 if (cli.tasks().length === 0) {
                     program.error('No tasks found', { exitCode: 127 });
                     return;
                 }
+                if (options.dryRun) {
+                    const plan = await cli.dryRun({ cacheDefault: options.cache });
+                    if (plan.cycle) {
+                        program.error(`task cycle detected ${plan.cycle.join(' -> ')}`, { exitCode: 1 });
+                        return;
+                    }
+                    (0, dry_run_1.printDryRun)(environment, plan);
+                    return;
+                }
+                const runStart = Date.now();
                 const result = await cli.runExec({
                     cacheDefault: options.cache,
                     watch: options.watch,
                     workers: options.concurrency,
                     logMode: options.log,
+                    explain: options.explain,
+                    cacheReadOnly: (0, read_only_1.isCacheReadOnly)(options.cacheReadOnly, environment.processEnvs),
+                    timeout: options.timeout ?? null,
+                    skipDeps: options.skipDeps !== false,
                 });
+                // Reporting only: the summary never changes the exit code or behavior.
+                if (!options.watch) {
+                    const summary = (0, run_summary_1.summarizeRun)(result.state, Date.now() - runStart);
+                    if (options.summaryJson) {
+                        environment.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+                    }
+                    else if (options.summary !== false) {
+                        (0, run_summary_1.printRunSummary)(environment, summary);
+                    }
+                }
                 if (!result.success) {
                     program.error('Execution was not successful', { exitCode: 1 });
                 }
+                // Declared retention keeps local caches bounded without anyone having
+                // to remember `cache prune`. Never on remotes, never in read-only mode.
+                if (!options.watch && !(0, read_only_1.isCacheReadOnly)(options.cacheReadOnly, environment.processEnvs)) {
+                    try {
+                        for (const { cacheName, plan } of await cli.autoPrune()) {
+                            if (plan.evict.length > 0) {
+                                runEnvironment.console.info(`pruned ${plan.evict.length} old ${plan.evict.length === 1 ? 'entry' : 'entries'} from cache "${cacheName}"`);
+                            }
+                        }
+                    }
+                    catch (e) {
+                        runEnvironment.console.warn(`automatic cache prune failed: ${(0, log_1.getErrorMessage)(e)}`);
+                    }
+                }
             }
             catch (e) {
                 if (e instanceof commander_1.CommanderError) {

package/dist/schema/build-file-base-task-schema.js

@@ -8,6 +8,7 @@ const labels_schema_1 = require("./labels-schema");
 const cache_schema_1 = require("./cache-schema");
 const build_file_task_command_schema_1 = require("./build-file-task-command-schema");
 const build_file_volume_schema_1 = require("./build-file-volume-schema");
+const duration_schema_1 = require("./duration-schema");
 exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     deps: (0, zod_1.array)((0, zod_1.string)()).optional(),
     needs: (0, zod_1.array)(build_file_need_schema_1.buildFileNeedSchema).optional(),
@@ -23,5 +24,8 @@ exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     // A task that watches its own sources and restarts itself (e.g. `ng serve`,
     // `tsc -w`). In watch mode hammerkit then does not watch/restart it itself.
     continuous: (0, zod_1.boolean)().optional(),
+    // Maximum execution time, e.g. `30s`, `10m`, `1h30m`. The task fails when it
+    // runs longer. Does not affect the cache key (ADR-0002).
+    timeout: duration_schema_1.durationSchema.optional(),
 });
 //# sourceMappingURL=build-file-base-task-schema.js.map

package/dist/schema/cache-schema.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheSchema = exports.taskCacheRefSchema = exports.buildFileCacheSchema = exports.cacheBackendSchema = exports.cacheBackendS3Schema = exports.cacheBackendLocalSchema = exports.cacheMethodSchema = void 0;
+exports.cacheSchema = exports.taskCacheRefSchema = exports.buildFileCacheSchema = exports.cacheRetentionSchema = exports.cacheBackendSchema = exports.cacheBackendRegistrySchema = exports.cacheBackendS3Schema = exports.cacheBackendLocalSchema = exports.cacheMethodSchema = void 0;
 const zod_1 = require("zod");
+const duration_schema_1 = require("./duration-schema");
+const size_schema_1 = require("./size-schema");
 exports.cacheMethodSchema = (0, zod_1.union)([(0, zod_1.literal)('checksum'), (0, zod_1.literal)('modify-date'), (0, zod_1.literal)('none')]);
 exports.cacheBackendLocalSchema = (0, zod_1.object)({
     type: (0, zod_1.literal)('local'),
@@ -15,10 +17,27 @@ exports.cacheBackendS3Schema = (0, zod_1.object)({
     prefix: (0, zod_1.string)().optional(),
     forcePathStyle: zod_1.z.boolean().optional(),
 }).strict();
-exports.cacheBackendSchema = (0, zod_1.union)([exports.cacheBackendLocalSchema, exports.cacheBackendS3Schema]);
+exports.cacheBackendRegistrySchema = (0, zod_1.object)({
+    type: (0, zod_1.literal)('registry'),
+    // repository to store entries in, e.g. `ghcr.io/org/hammerkit-cache`
+    repository: (0, zod_1.string)(),
+    // talk plain http (defaults to true only for localhost registries)
+    insecure: zod_1.z.boolean().optional(),
+}).strict();
+exports.cacheBackendSchema = (0, zod_1.union)([exports.cacheBackendLocalSchema, exports.cacheBackendS3Schema, exports.cacheBackendRegistrySchema]);
+exports.cacheRetentionSchema = (0, zod_1.object)({
+    // evict entries not used within this long, e.g. `30d`
+    maxAge: duration_schema_1.durationSchema.optional(),
+    // evict least recently used entries until the cache is at most this big, e.g. `5Gi`
+    maxSize: size_schema_1.sizeSchema.optional(),
+    // keep only the newest N versions per task
+    keepPerTask: zod_1.z.number().int().positive().optional(),
+}).strict();
 exports.buildFileCacheSchema = (0, zod_1.object)({
     method: exports.cacheMethodSchema,
     backend: exports.cacheBackendSchema,
+    // applied by `cache prune`, and automatically after a run for local caches
+    retention: exports.cacheRetentionSchema.optional(),
 }).strict();
 exports.taskCacheRefSchema = (0, zod_1.union)([
     exports.cacheMethodSchema,

package/dist/schema/duration-schema.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.durationSchema = void 0;
+const zod_1 = require("zod");
+const units_1 = require("../utils/units");
+function isDuration(value) {
+    try {
+        (0, units_1.parseDuration)(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+exports.durationSchema = (0, zod_1.string)().refine(isDuration, (value) => ({
+    message: `invalid duration "${value}", expected e.g. 30s, 5m, 1h30m or 30d`,
+}));
+//# sourceMappingURL=duration-schema.js.map

package/dist/schema/reference-parser.js

@@ -8,6 +8,7 @@ const read_env_file_1 = require("../parser/read-env-file");
 const label_values_1 = require("../executer/label-values");
 const merge_environment_variables_1 = require("../environment/merge-environment-variables");
 const resolve_cache_1 = require("../cache/resolve-cache");
+const project_root_1 = require("../planner/project-root");
 function combinePath(namePrefix, name) {
     return namePrefix.length > 0 ? `${namePrefix}:${name}` : name;
 }
@@ -20,6 +21,7 @@ async function parseReferences(ctx, mainScope, environment) {
         envFiles: {},
         environments: {},
         caches: {},
+        projectRoot: await (0, project_root_1.findProjectRoot)(mainScope.cwd, environment),
     };
     for (const file of Object.values(ctx.files)) {
         if (!reference.envFiles[file.cwd]) {
@@ -97,6 +99,7 @@ function applySchemaExtension(reference, task) {
     applySchemaExtension(reference, extend);
     task.schema.shell = task.schema.shell ?? extend.schema.shell;
     task.schema.cache = task.schema.cache ?? extend.schema.cache;
+    task.schema.timeout = task.schema.timeout ?? extend.schema.timeout;
     task.schema.cmds = extendArray(task.schema.cmds, extend.schema.cmds);
     task.schema.src = extendArray(task.schema.src, extend.schema.src);
     task.schema.generates = extendArray(task.schema.generates, extend.schema.generates);

package/dist/schema/size-schema.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sizeSchema = void 0;
+const zod_1 = require("zod");
+const units_1 = require("../utils/units");
+function isSize(value) {
+    try {
+        (0, units_1.parseSize)(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+exports.sizeSchema = (0, zod_1.string)().refine(isSize, (value) => ({
+    message: `invalid size "${value}", expected e.g. 500Mi, 5Gi or 2G`,
+}));
+//# sourceMappingURL=size-schema.js.map

package/dist/schema/work-scope-parser.js

@@ -17,8 +17,20 @@ function defaultEnvironment(context) {
 }
 exports.defaultEnvironment = defaultEnvironment;
 function getWorkContext(context, scope, environment) {
-    const workTree = { services: {}, environment: defaultEnvironment(context), tasks: {} };
-    const filteredWorkTree = { services: {}, environment: defaultEnvironment(context), tasks: {} };
+    const workTree = {
+        services: {},
+        environment: defaultEnvironment(context),
+        tasks: {},
+        caches: context.caches,
+    };
+    const filteredWorkTree = {
+        services: {},
+        environment: defaultEnvironment(context),
+        tasks: {},
+        caches: context.caches,
+    };
+    const requested = [];
+    filteredWorkTree.requested = requested;
     for (const [envName, env] of Object.entries(context.environments)) {
         if (envName === scope.environmentName) {
             filteredWorkTree.environment = (0, append_work_environment_1.appendWorkEnvironment)(env);
@@ -28,6 +40,7 @@ function getWorkContext(context, scope, environment) {
     for (const task of Object.values(context.tasks)) {
         const item = (0, append_work_task_1.appendWorkTask)(workTree, task.cwd, task, environment, context);
         if (matchesTaskWorkScope(item, scope)) {
+            requested.push(item.name);
             applyTask(filteredWorkTree, item);
         }
     }

package/dist/utils/units.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSize = exports.parseSize = exports.formatDuration = exports.parseDuration = void 0;
+const DURATION_UNITS = {
+    ms: 1,
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000,
+};
+// Parse a duration such as `500ms`, `30s`, `5m`, `1h30m` or `30d` into
+// milliseconds. Every component needs a unit, and the total must be positive.
+function parseDuration(value) {
+    const pattern = /(\d+(?:\.\d+)?)(ms|s|m|h|d)/y;
+    let total = 0;
+    let offset = 0;
+    while (offset < value.length) {
+        pattern.lastIndex = offset;
+        const match = pattern.exec(value);
+        if (!match) {
+            throw new Error(`invalid duration "${value}", expected e.g. 30s, 5m, 1h30m or 30d`);
+        }
+        total += parseFloat(match[1]) * DURATION_UNITS[match[2]];
+        offset = pattern.lastIndex;
+    }
+    if (total <= 0) {
+        throw new Error(`invalid duration "${value}", expected e.g. 30s, 5m, 1h30m or 30d`);
+    }
+    return Math.round(total);
+}
+exports.parseDuration = parseDuration;
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    let remaining = Math.round(ms / 1000);
+    const parts = [];
+    for (const [unit, seconds] of [
+        ['d', 86400],
+        ['h', 3600],
+        ['m', 60],
+        ['s', 1],
+    ]) {
+        if (remaining >= seconds) {
+            parts.push(`${Math.floor(remaining / seconds)}${unit}`);
+            remaining %= seconds;
+        }
+    }
+    return parts.join('');
+}
+exports.formatDuration = formatDuration;
+const SIZE_UNITS = {
+    '': 1,
+    K: 1000,
+    M: 1000 ** 2,
+    G: 1000 ** 3,
+    T: 1000 ** 4,
+    Ki: 1024,
+    Mi: 1024 ** 2,
+    Gi: 1024 ** 3,
+    Ti: 1024 ** 4,
+};
+// Parse a size such as `500Mi`, `5Gi` or `2G` (Kubernetes-style suffixes;
+// binary `Ki/Mi/Gi/Ti`, decimal `K/M/G/T`, none for bytes) into bytes.
+function parseSize(value) {
+    const match = /^(\d+(?:\.\d+)?)(Ki|Mi|Gi|Ti|K|M|G|T)?$/.exec(value);
+    if (!match) {
+        throw new Error(`invalid size "${value}", expected e.g. 500Mi, 5Gi or 2G`);
+    }
+    return Math.round(parseFloat(match[1]) * SIZE_UNITS[match[2] ?? '']);
+}
+exports.parseSize = parseSize;
+function formatSize(bytes) {
+    for (const [unit, factor] of [
+        ['Ti', 1024 ** 4],
+        ['Gi', 1024 ** 3],
+        ['Mi', 1024 ** 2],
+        ['Ki', 1024],
+    ]) {
+        if (bytes >= factor) {
+            return `${(bytes / factor).toFixed(1).replace(/\.0$/, '')}${unit}`;
+        }
+    }
+    return `${bytes}B`;
+}
+exports.formatSize = formatSize;
+//# sourceMappingURL=units.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hammerkit",
   "description": "Containerized build tool with incremental caching that runs the same build file locally, in Docker and on Kubernetes.",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "keywords": [
     "build",
     "build-tool",
@@ -14,6 +14,13 @@
   ],
   "homepage": "https://no0dles.gitbook.io/hammerkit/",
   "bin": "dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*",
+    "!dist/testing",
+    "!dist/**/*.map",
+    "build.schema.json"
+  ],
   "bugs": {
     "url": "https://github.com/no0dles/hammerkit/issues"
   },
@@ -34,6 +41,7 @@
     "build": "tsc -b tsconfig.json",
     "test": "vitest run",
     "test:integration": "vitest run --mode integration",
+    "test:mutation": "stryker run",
     "format": "prettier -w src/** && eslint . --fix --ext .ts",
     "lint": "eslint . --ext .ts"
   },
@@ -51,6 +59,8 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/dockerode": "^3.3.23",
     "@types/minimatch": "^5.1.2",
     "@types/node": "^24.0.0",
@@ -60,6 +70,7 @@
     "@vitest/coverage-istanbul": "^2.1.8",
     "@yao-pkg/pkg": "^6.20.0",
     "eslint": "^8.56.0",
+    "fast-check": "^4.10.2",
     "prettier": "^3.1.1",
     "typescript": "^5.3.3",
     "vitest": "^2.1.8",

package/.agents/FEEDBACK.md

@@ -1,74 +0,0 @@
-# Feedback log
-
-Durable record of corrections and preferences the user has given AI agents working
-in this repo. The point of this file is that the user should **not have to repeat
-himself**.
-
-**Contract — every agent, every session:**
-
-1. **Read this file before you start working.** Apply every rule here without being
-   reminded.
-2. **Don't re-ask anything already answered here.** If a rule covers the situation,
-   follow it instead of asking.
-3. **When the user corrects you or states a preference, append an entry here
-   immediately** — same session, before moving on — so it is captured for next
-   time. Keep entries short: a rule, **Why**, **How to apply**, and a date.
-
-Related: the companion `do-the-work` skill explains the behavior; this file is the
-running record.
-
----
-
-## Rules
-
-### Do the work — don't propose avoiding it _(2026-05-25)_
-
-Skipping, disabling, excluding, `.skip` / `it.skip` / `xfail`, commenting-out,
-deleting, loosening/weakening an assertion, or stopping early is **never** an
-acceptable way to resolve a failing test or a red build. Fix the root cause.
-
-- **Why:** The user asked for the thing to be *fixed*. Avoiding the work is not a
-  smaller version of the job — it's not doing the job, and it hides a regression.
-  Avoidance being the agent's default reflex is what the user finds worrying.
-- **How to apply:** Diagnose the underlying cause (timing, environment,
-  file-watching, resource leaks, ordering, a real bug) and fix it so the check
-  passes legitimately. Only ever skip/disable something if the user *explicitly*
-  asks for it in that conversation.
-
-### "Fix CI" means fix the failure, not remove the test _(2026-05-25)_
-
-When the task is to get CI green, the deliverable is a green run achieved by
-fixing what is broken — not by removing, skipping, or muting the failing check.
-
-- **Why:** Fixing CI *is* the requested work. Removing the test makes CI green
-  while leaving the actual problem in place.
-- **How to apply:** Use the `fix-ci` skill loop (diagnose → fix → verify →
-  commit → push → watch). If a failure is genuinely container/k8s/infra-only and
-  cannot be reproduced on this host, say so explicitly and rely on CI to confirm
-  the fix — that is not the same as skipping the test.
-
-### Prefer configurable timeouts over skips or huge fixed values _(2026-05-25)_
-
-When a test hangs or flakes, make the timeout configurable (e.g. via env var)
-rather than skipping the test or hardcoding a giant timeout.
-
-- **Why:** CI is slower than local; a configurable budget lets local fail fast
-  (surfacing hangs quickly) while CI gets the time it needs. Reducing flake is
-  always desirable; skipping never is.
-- **How to apply:** Drive the timeout from an env var with a sensible local
-  default and a longer CI value; fix the underlying cause of the hang/flake.
-
-### Ask implementation questions freely; never ask permission to avoid work _(2026-05-25)_
-
-Questions about *how* to implement something — design, approach, ambiguity,
-trade-offs — are welcome and encouraged. Questions that are really requests to
-*not do* the assigned work are not.
-
-- **Why:** The user repeatedly got asked variants of "can I skip/stop/disable
-  this?" instead of getting the work done. He doesn't want to keep saying "no, do
-  it."
-- **How to apply:** If a question's effect is to avoid the work (skip a test,
-  drop a requirement, leave the failure), don't ask it — do the work. Only
-  escalate when *genuinely* blocked: missing access/credentials, a product
-  decision only the user can make, or contradictory requirements — and even then,
-  propose the fix path, not the avoidance.