import commaner, { Command, CommanderError, InvalidArgumentError, Option } from 'commander' import { parseSetArguments } from './parse-set-arguments' import { join, relative, resolve } from 'path' import { Environment } from './executer/environment' import { isCI } from './utils/ci' import { parseLabelArguments } from './parser/parse-label-arguments' import { Cli, CliServiceItem, CliTaskItem, getCli, isCliService, isCliTask } from './cli' import { TaskDefinition } from './planner/describe-task' import { WorkEnvOrigin } from './planner/work-task' import { WorkLabelScope, WorkScope } from './executer/work-scope' import { consoleContext, getErrorMessage, printItem, printProperty, printTitle } from './log' import { emptyWritable } from './utils/empty-writable' import { describeCause } from './cache/explain' import { printRunSummary, summarizeRun } from './executer/run-summary' import { printDryRun } from './executer/dry-run' import { hasLabels } from './executer/label-values' import { getBuildFilename } from './parser/default-build-file' import { createParseContext } from './schema/schema-parser' import { getWorkContext } from './schema/work-scope-parser' import { parseReferences } from './schema/reference-parser' import colors from 'colors' import { WorkItemValidation } from './planner/work-item-validation' import { getVersion } from './version' import { CACHE_READ_ONLY_ENV, isCacheReadOnly } from './cache/read-only' import { formatDuration, formatSize, parseDuration, parseSize } from './utils/units' import { hasPolicy, NamedCacheEntry } from './cache/cache-inventory' import { registerRemoteCommands } from './remote/remote-commands' import { registerServerCommand } from './server/server-command' import { registerRunWorkerCommand, registerSandboxPodCommand } from './server/run-worker-command' import { registerGithubAppTokenCommand } from './secrets/github-app-token-command' import { parseNetworkOption, WorkNetwork } from './planner/work-network' import { getArgumentsTarget } from './planner/utils/task-arguments' export async function createCli(fileName: string, environment: Environment, workScope: WorkScope): Promise { const { ctx, scope } = await createParseContext(fileName, environment) const referencedScope = await parseReferences(ctx, scope, environment) const workTree = getWorkContext(referencedScope, workScope, environment) return getCli(workTree, environment) } const ENV_ORIGINS: { [origin in WorkEnvOrigin]: (includedAs: string) => string } = { task: () => 'task', input: (includedAs) => `input of include ${includedAs}`, 'build-file': () => 'build file', extend: () => 'extended task', } function printTaskDefinition(environment: Environment, definition: TaskDefinition) { environment.stdout.write(`• ${definition.name}\n`) const source = definition.source if (source.git) { printProperty( environment, 'defined in', `${source.file} of ${source.git} at ${source.ref ?? 'HEAD'} (commit ${(source.commit ?? '').slice(0, 12)})` ) } else { printProperty(environment, 'defined in', source.file) } if (source.includedAs) { printProperty(environment, 'included as', source.includedAs) } if (definition.description) { printProperty(environment, 'description', definition.description) } if (definition.image) { printProperty(environment, 'image', definition.image) } for (const [name, values] of [ ['deps', definition.deps], ['needs', definition.needs], ['src', definition.src], ['generates', definition.generates], ['mounts', definition.mounts], ] as const) { if (values.length > 0) { printProperty(environment, name, values.join(', ')) } } for (const cmd of definition.cmds) { printProperty(environment, 'cmd', cmd) } for (const env of definition.envs) { printProperty( environment, `env ${env.name}`, `${env.value} ${colors.grey(`(${ENV_ORIGINS[env.origin](source.includedAs)})`)}` ) } for (const reference of definition.envReferences) { printProperty( environment, `env ${reference.name}`, `from $${reference.from} ${colors.grey(reference.available ? '(set)' : '(not set)')}` ) } } // `ls --json`: what a caller (an agent picking a task) needs to know, with the // command that arguments after `--` are appended to (null: it takes none) and // `args` as the build file says it (false: it refuses them). function getListJson(tasks: CliTaskItem[], services: CliServiceItem[]) { return { tasks: tasks.map(({ item }) => ({ name: item.name, description: item.data.description, type: item.data.type, ...(item.data.type === 'container-task' ? { image: item.data.image } : {}), deps: item.deps.map((d) => d.name), needs: item.needs.map((n) => n.name), labels: item.data.labels, command: getArgumentsTarget(item.data)?.cmd ?? null, args: item.data.args, })), services: services.map(({ item }) => ({ name: item.name, description: item.data.description, type: item.data.type, ...(item.data.type === 'container-service' ? { image: item.data.image } : {}), ports: item.data.ports.map((p) => ({ host: p.hostPort, container: p.containerPort })), labels: item.data.labels, command: getArgumentsTarget(item.data)?.cmd ?? null, args: item.data.type === 'container-service' ? item.data.args : null, })), } } // `up` and `down` select by name or by label, not both: a name outside the labels would // silently select nothing function parseWorkNameScope(names: string[], options: unknown): WorkLabelScope { const scope = parseWorkLabelScope(options) if (names.length === 0) { return scope } if (scope.filterLabels || scope.excludeLabels) { throw new Error('name tasks and services or select them with --filter/--exclude, not both') } return { ...scope, names } } function parseWorkLabelScope(options: unknown): WorkLabelScope { const scope: WorkLabelScope = { environmentName: null, } if (typeof options !== 'object') { return scope } if (options === undefined || options === null) { return scope } for (const [key, value] of Object.entries(options)) { if (key === 'filter' && value instanceof Array) { scope.filterLabels = parseLabelArguments(value) } else if (key === 'exclude' && value instanceof Array) { scope.excludeLabels = parseLabelArguments(value) } else if (key === 'env') { scope.environmentName = `${value}` } } return scope } // A task given arguments after -- skips the cache, unless the caller asks for a // cache method on the command line. function keepsCache(command: commaner.Command): boolean { return command.getOptionValueSource('cache') === 'cli' } export async function getProgram( environment: Environment, argv: string[] ): Promise<{ program: commaner.Command; args: string[] }> { const program = new Command() registerServerCommand(program, environment) registerRunWorkerCommand(program, environment) registerSandboxPodCommand(program, environment) registerGithubAppTokenCommand(program, environment) // What follows `--` belongs to the one task or service of a run or up, not to // hammerkit: a `--set` or `--file` there is an argument like any other. const separator = argv.indexOf('--') const passthrough = separator >= 0 ? argv.slice(separator + 1) : [] const parsed = parseSetArguments(separator >= 0 ? argv.slice(0, separator) : argv) const args = parsed.args environment.processEnvs = { ...environment.processEnvs, ...parsed.values } const remote = args.indexOf('remote') if (remote >= 0 && args[remote + 1] === 'mcp') { // `remote mcp` speaks its protocol on stdout: a warning there would break it environment.console = consoleContext(environment.stderr) } const fileIndex = args.indexOf('--file') const fileName = fileIndex >= 0 ? join(environment.cwd, args[fileIndex + 1]) : await getBuildFilename(environment.cwd, environment) if (fileIndex >= 0) { args.splice(fileIndex, 2) } registerRemoteCommands(program, environment, fileName, passthrough) program.hook('preAction', (_, actionCommand) => { const takesArguments = (actionCommand.parent === program && ['run', 'up'].includes(actionCommand.name())) || (actionCommand.parent?.name() === 'remote' && actionCommand.name() === 'run') if (passthrough.length > 0 && !takesArguments) { program.error(`${actionCommand.name()} takes no arguments after --, only run, up and remote run do`, { exitCode: 1, }) } }) if (await environment.file.exists(fileName)) { program .command('ls') .description('list all tasks') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--json', 'emit the tasks and services as JSON').default(false)) .action(async (options) => { const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) const items = cli.ls() const tasks = items.filter(isCliTask) const services = items.filter(isCliService) if (options.json) { environment.stdout.write(`${JSON.stringify(getListJson(tasks, services), null, 2)}\n`) return } if (services.length > 0) { printTitle(environment, 'Services') for (const service of services) { printItem(environment, service.item.data) printProperty( environment, 'ports', service.item.data.ports.map((p) => `127.0.0.1:${p.hostPort} -> ${p.containerPort}`).join(', ') ) if (service.item.data.type === 'kubernetes-service') { printProperty(environment, 'context', service.item.data.context) printProperty( environment, 'selector', `${service.item.data.selector.type}/${service.item.data.selector.name}` ) } else { printProperty(environment, 'image', service.item.data.image) } } } if (tasks.length > 0 && services.length > 0) { environment.stdout.write('\n') } if (tasks.length > 0) { printTitle(environment, 'Tasks') for (const task of tasks) { printItem(environment, task.item.data) if (task.item.needs.length > 0) { printProperty(environment, 'needs', task.item.needs.map((d) => d.name).join(', ')) } if (task.item.deps.length > 0) { printProperty(environment, 'deps', task.item.deps.map((d) => d.name).join(', ')) } if (task.item.data.type === 'container-task') { printProperty(environment, 'image', task.item.data.image) } if (task.item.data.caching) { const c = task.item.data.caching printProperty(environment, 'caching', `${c.name} (${c.method}, ${c.backend.type})`) } if (hasLabels(task.item.data.labels)) { printProperty( environment, 'labels', `${Object.keys(task.item.data.labels) .map((key) => `${key}=${task.item.data.labels[key].join(',')}`) .join(' ')}` ) } if (task.item.data.src.length > 0) { printProperty( environment, 'src', task.item.data.src.map((d) => relative(task.item.data.cwd, d.absolutePath)).join(' ') ) } if (task.item.data.generates.length > 0) { printProperty( environment, 'generates', task.item.data.generates.map((d) => relative(task.item.data.cwd, d.path)).join(' ') ) } } } environment.stdout.write('\n') }) program .command('clean') .description('clear cache and generated') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption( new Option( '--cache', 'also clear stored cache results from the backend (e.g. the local ~/.hammerkit/remote-cache or a configured remote bucket)' ) ) .action(async (options) => { try { const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) await cli.clean({ cache: !!options.cache }) } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Clean was not successful', { exitCode: 1 }) } }) program .command('store ') .description('save task outputs into ') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .action(async (path, options) => { try { const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) await cli.store(resolve(path)) } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Store was not successful', { exitCode: 1 }) } }) program .command('restore ') .description('restore task outputs from ') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .action(async (path, options) => { try { const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) await cli.restore(resolve(path)) } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Restore was not successful', { exitCode: 1 }) } }) program .command('package ') .description('package services into a docker image') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--push', 'push image to registry').default(false)) .addOption(new Option('--build-override-user', 'set a dedicated user (uid/gid)').default(false)) .addOption(new Option('-t, --tag ', 'image tag').default('latest')) .addOption(new Option('--platform ', 'target build platform, e.g. linux/amd64')) .addOption(new Option('-u, --user, --username', 'registry username')) .addOption(new Option('-p, --password', 'registry password')) .action(async (registry, options) => { try { const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) await cli.package({ registry, push: options.push, overrideUser: !!options.overrideUser, username: options.username, password: options.password, tag: options.tag, platform: options.platform, }) } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Package was not successful', { exitCode: 1 }) } }) program .command('validate') .description('validate hammerkit configurations') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .action(async (options) => { let errors = 0 const cli = await createCli(fileName, environment, parseWorkLabelScope(options)) const fileErrors: { [buildFileName: string]: WorkItemValidation[] } = {} for await (const validation of cli.validate()) { if (!fileErrors[validation.item.scope.fileName]) { fileErrors[validation.item.scope.fileName] = [validation] } else { fileErrors[validation.item.scope.fileName].push(validation) } if (validation.type === 'error') { errors++ } } for (const [buildFilename, errors] of Object.entries(fileErrors)) { environment.stdout.write(`${colors.underline(colors.gray(buildFilename))}\n`) for (const error of errors) { environment.stdout.write( ` ${colors.underline(colors.blue(error.type))} at ${colors.gray(error.item.name)} ${error.message}\n` ) } environment.stdout.write('\n') } if (errors !== 0) { 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 Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--env ', 'environment')) .addOption(new Option('--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 CommanderError) { throw e } environment.console.error(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 Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--env ', 'environment')) .addOption( new Option('--cache ', 'caching method to compare') .default('checksum') .choices(['checksum', 'modify-date', 'none']) ) .addOption(new Option('--json', 'emit the explanation as JSON').default(false)) .addOption(new Option('--check', 'exit with code 1 when any task would be a cache miss').default(false)) .addOption( new Option('--definition', 'show the resolved definition of the tasks and where it came from instead').default( false ) ) .action(async (task, options) => { try { const cli = await createCli( fileName, environment, task ? { taskName: task, environmentName: options.env ?? null } : parseWorkLabelScope(options) ) if (options.definition) { const definitions = cli.explainDefinition() if (options.json) { environment.stdout.write(`${JSON.stringify(definitions, null, 2)}\n`) } else { for (const definition of definitions) { printTaskDefinition(environment, definition) } } return } const explanations = await cli.explain({ cacheDefault: options.cache }) const missed = explanations.filter((explanation) => explanation.status === 'miss') if (options.json) { environment.stdout.write(`${JSON.stringify(explanations, null, 2)}\n`) if (options.check && missed.length > 0) { program.error('', { exitCode: 1 }) } return } for (const explanation of explanations) { const label = explanation.status === 'hit' ? colors.green('cache hit') : explanation.status === 'uncacheable' ? colors.grey('uncacheable') : colors.yellow('cache miss') environment.stdout.write(`• ${explanation.taskName}: ${label}\n`) for (const cause of explanation.causes) { printProperty(environment, 'cause', describeCause(cause)) } } if (options.check && missed.length > 0) { program.error(`${missed.length} of ${explanations.length} tasks would be a cache miss`, { exitCode: 1 }) } } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Explain was not successful', { exitCode: 1 }) } }) program .command('includes') .description('manage remote includes (includes pull)') .command('pull') .description('fetch the git repositories of remote includes again, picking up new commits of branches and tags') .action(async () => { try { const { ctx } = await createParseContext(fileName, environment, { refresh: true }) const refreshed = [...(ctx.refreshed?.values() ?? [])] for (const source of refreshed) { const name = `${source.git} at ${source.ref ?? 'HEAD'}` const commit = source.commit.slice(0, 12) if (source.pinned) { environment.stdout.write(`${name}: pinned to ${commit}\n`) } else if (source.previous === source.commit) { environment.stdout.write(`${name}: up to date at ${commit}\n`) } else if (source.previous === null) { environment.stdout.write(`${name}: fetched ${commit}\n`) } else { environment.stdout.write(`${name}: ${source.previous.slice(0, 12)} -> ${commit}\n`) } } if (refreshed.length === 0) { environment.stdout.write('no remote includes\n') } } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Includes pull was not successful', { exitCode: 1 }) } }) const cacheCommand = program.command('cache').description('inspect, prune and move cache entries') for (const direction of ['pull', 'push'] as const) { 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 Option('--remote ', 'remote cache declared in the caches block').makeOptionMandatory()) .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--env ', 'environment')) .addOption( new Option('--cache ', 'caching method to compare') .default('checksum') .choices(['checksum', 'modify-date', 'none']) ) .action(async (task, options) => { try { if (direction === 'push' && isCacheReadOnly(false, environment.processEnvs)) { program.error(`cache is read-only (${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.green(direction === 'pull' ? 'pulled' : 'pushed'), present: colors.grey('already present'), missing: colors.yellow(direction === 'pull' ? 'not in remote' : 'not in local cache'), skipped: colors.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 CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error(`Cache ${direction} was not successful: ${getErrorMessage(e)}`, { exitCode: 1 }) } }) } const describeEntry = (entry: NamedCacheEntry) => `${entry.taskName ?? colors.grey(entry.taskId.substring(0, 12))} ${colors.grey( entry.stateKey.substring(0, 12) )} ` + `${entry.size === null ? '?' : formatSize(entry.size)}` + (entry.lastAccessedAt ?? entry.createdAt ? colors.grey(` last used ${formatDuration(Date.now() - (entry.lastAccessedAt ?? entry.createdAt ?? 0))} ago`) : '') const totalSize = (entries: NamedCacheEntry[]) => formatSize(entries.reduce((sum, entry) => sum + (entry.size ?? 0), 0)) const countOf = (count: number) => `${count} ${count === 1 ? 'entry' : 'entries'}` cacheCommand .command('ls') .description('list the entries of a cache (default: the local default cache)') .addOption(new Option('--remote ', 'cache declared in the caches block to list')) .addOption(new 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 CommanderError) { throw e } program.error(`Cache ls was not successful: ${getErrorMessage(e)}`, { exitCode: 1 }) } }) cacheCommand .command('prune') .description('remove cache entries by retention policy (default: the local default cache)') .addOption(new Option('--remote ', 'cache declared in the caches block to prune')) .addOption( new Option('--max-age ', 'remove entries not used within this long (e.g. 30d)').argParser( parseDuration ) ) .addOption( new Option('--max-size ', 'remove least recently used entries above this size (e.g. 5Gi)').argParser( parseSize ) ) .addOption( new Option('--keep ', 'keep only the newest versions per task').argParser((v) => parseInt(v, 10)) ) .addOption(new 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 (!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 CommanderError) { throw e } program.error(`Cache prune was not successful: ${getErrorMessage(e)}`, { exitCode: 1 }) } }) program .command('up [names...]') .description( "start services(s), all or the named tasks and services, with the arguments after -- appended to the selected service's cmd" ) .usage('[options] [names...] [-- args...]') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption( new Option( '-c, --concurrency ', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)' ).argParser(parseInt) ) .addOption( new Option('--skip-resource-check', 'start even when a task with its services requests more than the host has') ) .addOption(new Option('-w, --watch', 'watch tasks').default(false)) .addOption(new Option('-d, --daemon', 'run services in background').default(false)) .addOption( new Option('--wait ', 'with --daemon, return once services are ready or once they started') .default('ready') .choices(['ready', 'start']) ) .addOption(new Option('--env ', 'environment')) .addOption( new Option('-l, --log ', 'log mode') .default(isCI ? 'live' : 'interactive') .choices(['interactive', 'live', 'grouped']) ) .addOption( new Option('--cache ', 'caching method to compare') .default('checksum') .choices(['checksum', 'modify-date', 'none']) ) .addOption( new Option( '--cache-read-only', `restore from cache backends but never push to them (or set ${CACHE_READ_ONLY_ENV}=1)` ).default(false) ) .addOption( new Option('--timeout ', 'fail tasks without their own timeout after this long (e.g. 10m)').argParser( parseDuration ) ) .addOption( new Option( '--max-timeout ', 'fail any task after this long, also one with a longer timeout of its own (e.g. 2m)' ).argParser(parseDuration) ) .addOption( new Option( '--network ', 'the most any task or service reaches besides its needs: none, open or allow:,' ).argParser(parseNetworkArgument) ) .action(async (names: string[], options, command: commaner.Command) => { try { const scope = { ...parseWorkNameScope(names, options), args: { values: passthrough, services: true, cache: keepsCache(command) }, } const cli = await createCli(fileName, environment, scope) const result = await cli.runUp({ cacheDefault: options.cache, watch: options.watch, workers: options.concurrency ?? cli.defaultWorkers(), resourceCheck: !options.skipResourceCheck, logMode: options.log, daemon: options.daemon, wait: options.wait, cacheReadOnly: isCacheReadOnly(options.cacheReadOnly, environment.processEnvs), timeout: options.timeout ?? null, maxTimeout: options.maxTimeout ?? null, network: options.network ?? null, }) if (!result.success) { program.error('Up was not successful', { exitCode: 1 }) } else { process.exit() } } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Up was not successful', { exitCode: 1 }) } }) program .command('down [names...]') .description('stop services(s), all or the named services and the services the named tasks need') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption(new Option('--env ', 'environment')) .action(async (names: string[], options) => { try { const scope = { ...parseWorkNameScope(names, options), stop: true } const cli = await createCli(fileName, environment, scope) const result = await cli.runDown() if (!result.success) { program.error('Shutdown was not successful', { exitCode: 1 }) } } catch (e) { if (e instanceof CommanderError) { throw e } environment.console.error(getErrorMessage(e)) program.error('Shutdown was not successful', { exitCode: 1 }) } }) program .command('run [task]', { isDefault: true }) .description('execute task, with the arguments after -- appended to its last command') .usage('[options] [task] [-- args...]') .addOption(new Option('-f, --filter ', 'filter task and services with labels')) .addOption(new Option('-e, --exclude ', 'exclude task and services with labels')) .addOption( new Option( '-c, --concurrency ', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)' ).argParser(parseInt) ) .addOption( new Option('--skip-resource-check', 'start even when a task with its services requests more than the host has') ) .addOption(new Option('-w, --watch', 'watch tasks').default(false)) .addOption(new Option('--env ', 'environment')) .addOption( new Option('-l, --log ', 'log mode') .default(isCI ? 'live' : 'interactive') .choices(['interactive', 'live', 'grouped']) ) .addOption( new Option('--cache ', 'caching method to compare') .default('checksum') .choices(['checksum', 'modify-date', 'none']) ) .addOption(new Option('--no-summary', 'do not print the end-of-run summary')) .addOption(new Option('--summary-json', 'emit the end-of-run summary as JSON').default(false)) .addOption(new Option('--explain', 'print the cache-miss cause when a task rebuilds').default(false)) .addOption( new Option('--dry-run', 'print the execution plan with predicted cache hits/misses without running').default( false ) ) .addOption( new Option( '--cache-read-only', `restore from cache backends but never push to them (or set ${CACHE_READ_ONLY_ENV}=1)` ).default(false) ) .addOption( new Option('--timeout ', 'fail tasks without their own timeout after this long (e.g. 10m)').argParser( parseDuration ) ) .addOption( new Option( '--max-timeout ', 'fail any task after this long, also one with a longer timeout of its own (e.g. 2m)' ).argParser(parseDuration) ) .addOption( new Option( '--network ', 'the most any task or service reaches besides its needs: none, open or allow:,' ).argParser(parseNetworkArgument) ) .addOption(new Option('--no-skip-deps', 'run dependencies even when nothing needing them has to run')) .addOption( new Option( '--no-restore', 'only look cache hits up, download their outputs only when a task that runs needs them' ) ) .action(async (task, options, command: commaner.Command) => { try { // 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: Environment = options.summaryJson ? { ...environment, stdout: emptyWritable(), console: consoleContext(emptyWritable()) } : environment const args = { values: passthrough, services: false, cache: keepsCache(command) } const cli = await createCli( fileName, runEnvironment, task ? { taskName: task, environmentName: options.env, args } : { ...parseWorkLabelScope(options), args } ) 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 } printDryRun(environment, plan) return } const runStart = Date.now() const result = await cli.runExec({ cacheDefault: options.cache, watch: options.watch, workers: options.concurrency ?? cli.defaultWorkers(), resourceCheck: !options.skipResourceCheck, logMode: options.log, explain: options.explain, cacheReadOnly: isCacheReadOnly(options.cacheReadOnly, environment.processEnvs), timeout: options.timeout ?? null, maxTimeout: options.maxTimeout ?? null, network: options.network ?? null, skipDeps: options.skipDeps !== false, restore: options.restore !== false, }) // Reporting only: the summary never changes the exit code or behavior. if (!options.watch) { const summary = summarizeRun(result.state, Date.now() - runStart) if (options.summaryJson) { environment.stdout.write(`${JSON.stringify(summary, null, 2)}\n`) } else if (options.summary !== false) { 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 && !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: ${getErrorMessage(e)}`) } } } catch (e) { if (e instanceof CommanderError) { throw e } program.error(getErrorMessage(e), { exitCode: 1 }) } }) } else { if (fileIndex >= 0) { environment.console.warn(`unable to find build file ${fileName}`) } program .command('init') .description('creates default .hammerkit.yaml') .action(async () => { const content = `envs: {} tasks: example: image: alpine cmds: - echo "it's Hammer Time!" ` await environment.file.writeFile(fileName, content) environment.console.info(`created ${fileName}`) }) } program.version(getVersion()) program.option('--verbose', 'log debugging information', false) program.option('--file', 'set build file', '.hammerkit.yaml') program.option('--set ', 'value for $NAME / ${NAME} references, ahead of the shell and .env (repeatable)') program.configureOutput({ // --version and --help as they are, so `VERSION=$(hammerkit --version)` works writeOut: (str) => environment.stdout.write(str), writeErr: (str) => { environment.console.error(str) }, }) return { program, args } } function parseNetworkArgument(value: string): WorkNetwork { try { return parseNetworkOption(value) } catch (e) { throw new InvalidArgumentError(getErrorMessage(e)) } }