hammerkit 1.24.0 → 1.26.0

package/dist/executer/container-task-state.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeContainerTaskState = exports.writeContainerTaskState = exports.readContainerTaskState = exports.getContainerTaskStateFile = void 0;
 const path_1 = require("path");
 const get_cache_directory_1 = require("../optimizer/get-cache-directory");
-const work_instance_id_1 = require("../planner/work-instance-id");
+const work_state_record_1 = require("../planner/work-state-record");
 // The record says "the outputs of this container task belong to this state
-// key", like the state file of a local task. It lives in the hammerkit
-// directory, not the project, so writing it never touches a task's src.
+// key", like the state file of a local task (see work-state-record.ts). It lives
+// in the hammerkit directory, not the project, so writing it never touches a
+// task's src; the record name folds in the project root, so two checkouts keep
+// their own.
 function getContainerTaskStateFile(task) {
-    return (0, path_1.join)((0, get_cache_directory_1.getHammerkitDirectory)(), 'state', (0, work_instance_id_1.getWorkInstanceId)(task));
+    return (0, path_1.join)((0, get_cache_directory_1.getHammerkitDirectory)(), 'state', (0, work_state_record_1.getStateRecordName)(task));
 }
 exports.getContainerTaskStateFile = getContainerTaskStateFile;
 async function readContainerTaskState(environment, task) {
@@ -16,12 +18,12 @@ async function readContainerTaskState(environment, task) {
     if (!(await environment.file.exists(stateFile))) {
         return null;
     }
-    return (await environment.file.read(stateFile)).trim() || null;
+    return (0, work_state_record_1.parseStateRecord)(task, await environment.file.read(stateFile));
 }
 exports.readContainerTaskState = readContainerTaskState;
 async function writeContainerTaskState(environment, task, stateKey) {
     await environment.file.createDirectory((0, path_1.join)((0, get_cache_directory_1.getHammerkitDirectory)(), 'state'));
-    await environment.file.writeFile(getContainerTaskStateFile(task), stateKey);
+    await environment.file.writeFile(getContainerTaskStateFile(task), (0, work_state_record_1.formatStateRecord)(task, stateKey));
 }
 exports.writeContainerTaskState = writeContainerTaskState;
 async function removeContainerTaskState(environment, task) {

package/dist/kubernetes/ensure-kubernetes-deployment-exists.js

@@ -30,7 +30,7 @@ async function ensureKubernetesDeploymentExists(instance, env, service, persiste
     const envs = (0, replace_env_variables_1.getEnvironmentVariables)(service.data.envs);
     const name = (0, resources_1.getResourceName)(service);
     const healthcheckCommand = (0, work_service_1.getHealthcheckCommand)(service.data);
-    const serviceCommand = (0, work_service_1.getServiceCommand)(service.data);
+    const serviceCommand = (0, work_service_1.getServiceCommand)(service.data, { kubernetes: true });
     const probe = healthcheckCommand
         ? {
             exec: {

package/dist/optimizer/get-cache-directory.js

@@ -14,7 +14,12 @@ function getCacheStatsFile(cacheId) {
     return (0, path_1.join)(getCacheDirectory(cacheId), 'stats.json');
 }
 exports.getCacheStatsFile = getCacheStatsFile;
+// `HAMMERKIT_DIR` puts hammerkit's directory (the cache) elsewhere than below the home directory;
+// a server uses it to keep the caches of runs apart.
 function getHammerkitDirectory() {
+    if (process.env.HAMMERKIT_DIR) {
+        return process.env.HAMMERKIT_DIR;
+    }
     if (process.platform === 'win32') {
         return (0, path_1.join)(process.env.APPDATA, 'hammerkit');
     }

package/dist/planner/service-definition.js

@@ -4,6 +4,7 @@ exports.getServiceDefinitionHash = void 0;
 const crypto_1 = require("crypto");
 const work_secret_1 = require("./work-secret");
 const work_service_1 = require("./work-service");
+const work_cache_id_1 = require("./work-cache-id");
 // Everything a running container of the service was created from, plus the
 // definitions of the services it needs: a dependent links to the container it
 // started with, so a recreated need means a recreated dependent too. Stored as
@@ -30,8 +31,8 @@ function getServiceDefinitionHash(item) {
             ? `provider:${(0, work_secret_1.getSecretName)(s)}:${(0, work_secret_1.describeSecretSource)(s)}`
             : `${s.source.type}:${(0, work_secret_1.getSecretName)(s)}`),
         // the init task's id covers its image, commands, envs and mounts: a changed
-        // init recreates the service, so it runs again
-        init: service.init ? service.init.task.id() : null,
+        // init recreates the service, so it runs again (arguments after -- don't)
+        init: service.init ? (0, work_cache_id_1.getDeclaredWorkTaskId)(service.init.task) : null,
         needs: item.needs
             .filter((need) => (0, work_service_1.isContainerWorkService)(need.service.data))
             .map((need) => `${need.name}=${getServiceDefinitionHash(need.service)}`),

package/dist/planner/utils/task-arguments.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRefusedByWindowsPowerShell = exports.applyArguments = exports.getArgumentsTarget = exports.getKubernetesCommandArgs = exports.getKubernetesCommandText = exports.escapeKubernetesText = exports.appendArguments = exports.quoteArgument = exports.getShellQuoting = void 0;
+const os_1 = require("os");
+const POSIX_SHELLS = ['sh', 'bash', 'zsh', 'dash', 'ash', 'ksh', 'mksh'];
+const POWERSHELLS = ['powershell', 'pwsh'];
+// The quoting of a shell, by the name of its program; null for a shell whose
+// quoting isn't known (fish, cmd.exe, …). Guessing would let shell syntax in an
+// argument run as a second command, so such a shell takes no arguments.
+function getShellQuoting(shell) {
+    const program = shell.trim().split(/\s+/)[0] ?? '';
+    const name = (program.split(/[\\/]/).pop() ?? '').toLowerCase().replace(/\.exe$/, '');
+    if (POSIX_SHELLS.includes(name)) {
+        return 'posix';
+    }
+    if (POWERSHELLS.includes(name)) {
+        return 'powershell';
+    }
+    return null;
+}
+exports.getShellQuoting = getShellQuoting;
+// Single quotes take everything literally in both shells. In sh a quote ends the
+// string, so it is closed, escaped and reopened; PowerShell doubles it, and reads
+// the typographic single quotes as quotes too.
+function quoteArgument(arg, quoting) {
+    if (quoting === 'powershell') {
+        return `'${arg.replace(/['‘’‚‛]/g, (quote) => quote + quote)}'`;
+    }
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+exports.quoteArgument = quoteArgument;
+function appendArguments(command, args, quoting) {
+    // an exec-form command is shown as sh would read it; it runs from `parsed`
+    const display = quoting === 'exec' ? 'posix' : quoting;
+    return {
+        cwd: command.cwd,
+        cmd: [command.cmd, ...args.map((arg) => quoteArgument(arg, display))].join(' '),
+        parsed: {
+            command: command.parsed.command,
+            args: [...command.parsed.args, ...args],
+        },
+        arguments: { cmd: command.cmd.length, args: command.parsed.args.length },
+    };
+}
+exports.appendArguments = appendArguments;
+// Kubernetes expands `$(NAME)` with the container's env and turns `$$` into `$`
+// in a container's command and args, before any shell sees them, so a quoted
+// argument isn't text there unless its `$` is doubled. The part of the command
+// the build file declares keeps its meaning.
+function escapeKubernetesText(text) {
+    return text.replace(/\$/g, '$$$$');
+}
+exports.escapeKubernetesText = escapeKubernetesText;
+function getKubernetesCommandText(command) {
+    if (!command.arguments) {
+        return command.cmd;
+    }
+    const from = command.arguments.cmd;
+    return command.cmd.slice(0, from) + escapeKubernetesText(command.cmd.slice(from));
+}
+exports.getKubernetesCommandText = getKubernetesCommandText;
+function getKubernetesCommandArgs(command) {
+    const from = command.arguments?.args ?? command.parsed.args.length;
+    return command.parsed.args.map((arg, index) => (index >= from ? escapeKubernetesText(arg) : arg));
+}
+exports.getKubernetesCommandArgs = getKubernetesCommandArgs;
+// The command arguments after `--` land in: the last command of a task, the
+// `cmd` of a container service. Null when there is none.
+function getArgumentsTarget(item) {
+    if (item.type === 'local-task' || item.type === 'container-task') {
+        return item.cmds[item.cmds.length - 1] ?? null;
+    }
+    if (item.type === 'container-service') {
+        return item.cmd;
+    }
+    return null;
+}
+exports.getArgumentsTarget = getArgumentsTarget;
+// Appends the arguments to the one task or service a run selects, before
+// anything asks for its id: the last command is part of the task id, so the
+// arguments are part of its cache key. A run with arguments is a one-off (one
+// test, one flag), so the task skips the cache unless `keepCache`; even then the
+// key keeps runs with other arguments apart. Dependencies and needed services
+// are planned items of their own and keep their commands and caching. No
+// arguments change nothing, so a task run without them keeps its cache entries.
+function applyArguments(selection, args, keepCache = false) {
+    if (args.length === 0) {
+        return;
+    }
+    const selected = [...selection.tasks, ...selection.services];
+    if (selected.length === 0) {
+        return;
+    }
+    if (selected.length > 1) {
+        throw new Error(`arguments after -- go to one task or service, but this run selects ${selected.map((s) => s.name).join(', ')}`);
+    }
+    if (args.some((arg) => arg.includes('\0'))) {
+        throw new Error('an argument after -- contains a NUL character');
+    }
+    const item = selected[0];
+    if (item.type === 'kubernetes-service') {
+        throw new Error(`service ${item.name} is a kubernetes service and has no cmd for the arguments after --`);
+    }
+    const target = getArgumentsTarget(item);
+    if (!target) {
+        throw new Error(item.type === 'container-service'
+            ? `service ${item.name} has no cmd for the arguments after --`
+            : `task ${item.name} has no command for the arguments after --`);
+    }
+    const quoting = getItemQuoting(item);
+    if (item.type === 'local-task' && quoting === 'powershell') {
+        const refused = args.find(isRefusedByWindowsPowerShell);
+        if (refused !== undefined) {
+            throw new Error(`task ${item.name} runs in Windows PowerShell, which would split or run the argument ${JSON.stringify(refused)}, so it is refused: an empty argument, a ", the characters & | < > ^ % !, line breaks, and a space with a trailing \\`);
+        }
+    }
+    if (item.type === 'container-service') {
+        item.cmd = appendArguments(target, args, quoting);
+    }
+    else {
+        item.cmds = [...item.cmds.slice(0, -1), appendArguments(target, args, quoting)];
+        if (!keepCache) {
+            // not implicit, so the run's --cache default doesn't bring the method back
+            item.caching = { ...item.caching, method: 'none', implicit: false };
+        }
+    }
+}
+exports.applyArguments = applyArguments;
+// Windows PowerShell 5.1 builds a new command line for a native program, and
+// starts a .cmd or .bat shim (yarn.cmd, most of node_modules/.bin) through
+// cmd.exe. There an empty argument is dropped, a " splits or joins arguments,
+// an argument with a space that ends in \ is quoted as "a b\" and so escapes
+// its own closing quote, and cmd reads & | < > ^ % ! and a line break as
+// syntax, so such an argument can't be passed as text.
+function isRefusedByWindowsPowerShell(arg) {
+    return arg === '' || /["&|<>^%!\r\n]/.test(arg) || (/\s/.test(arg) && arg.endsWith('\\'));
+}
+exports.isRefusedByWindowsPowerShell = isRefusedByWindowsPowerShell;
+function getItemQuoting(item) {
+    if (item.type === 'local-task') {
+        // what executeCommand runs a local command in
+        return (0, os_1.platform)() === 'win32' ? 'powershell' : 'posix';
+    }
+    const shell = item.type === 'kubernetes-service' ? null : item.shell;
+    if (shell === null) {
+        return 'exec';
+    }
+    const quoting = getShellQuoting(shell);
+    if (!quoting) {
+        throw new Error(`${item.type === 'container-task' ? 'task' : 'service'} ${item.name} runs in ${shell}, whose quoting hammerkit ` +
+            `doesn't know, so it takes no arguments after --; use sh, bash, zsh, dash, ash, ksh, mksh or PowerShell`);
+    }
+    return quoting;
+}
+//# sourceMappingURL=task-arguments.js.map

package/dist/planner/work-cache-id.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getWorkTaskId = void 0;
+exports.getDeclaredWorkTaskId = exports.getWorkTaskId = void 0;
 const crypto_1 = require("crypto");
 const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
 function getWorkTaskId(item) {
@@ -9,4 +9,18 @@ function getWorkTaskId(item) {
     return (0, crypto_1.createHash)('sha1').update(jsonData).digest('hex');
 }
 exports.getWorkTaskId = getWorkTaskId;
+// The id of the task as the build file declares it: without the arguments
+// after -- a run appended to its last command. A service's definition takes its
+// init task by this id, so `run <init> -- ...` leaves a running service as it is.
+function getDeclaredWorkTaskId(item) {
+    const description = (0, work_task_cache_description_1.getWorkTaskCacheDescription)(item);
+    const cmds = description.cmds?.map((cmd, index) => {
+        const declared = item.data.cmds[index];
+        return declared.arguments ? { ...cmd, cmd: declared.cmd.slice(0, declared.arguments.cmd) } : cmd;
+    });
+    return (0, crypto_1.createHash)('sha1')
+        .update(JSON.stringify({ ...description, cmds }))
+        .digest('hex');
+}
+exports.getDeclaredWorkTaskId = getDeclaredWorkTaskId;
 //# sourceMappingURL=work-cache-id.js.map

package/dist/planner/work-runtime-docker.js

@@ -39,6 +39,8 @@ function dockerTaskRuntime(task, workEnvironment) {
             });
         },
         async restore(environment, path) {
+            // the restored outputs aren't the ones the record names any more
+            await (0, container_task_state_1.removeContainerTaskState)(environment, task);
             await restoreContainer(docker, environment, task, path);
         },
         async archive(environment, path) {

package/dist/planner/work-runtime-kubernetes.js

@@ -22,6 +22,7 @@ const ensure_http_route_1 = require("../kubernetes/ensure-http-route");
 const find_process_1 = __importDefault(require("find-process"));
 const log_1 = require("../log");
 const version_1 = require("../version");
+const task_arguments_1 = require("./utils/task-arguments");
 const restore_kubernetes_data_1 = require("../kubernetes/restore-kubernetes-data");
 const store_kubernetes_data_1 = require("../kubernetes/store-kubernetes-data");
 const remove_persistent_data_1 = require("../kubernetes/remove-persistent-data");
@@ -110,7 +111,7 @@ function kubernetesTaskRuntime(task, kubernetes) {
                                         image: task.data.image,
                                         // through the task's shell, as on Docker
                                         command: [task.data.shell, '-c'],
-                                        args: [cmd.cmd],
+                                        args: [(0, task_arguments_1.getKubernetesCommandText)(cmd)],
                                         workingDir: cmd.cwd,
                                         env: [
                                             ...Object.entries(envs).map(([key, value]) => ({ name: key, value })),

package/dist/planner/work-runtime-local.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLocalWorkRuntime = void 0;
+exports.getLocalWorkRuntime = exports.getStateFilename = void 0;
 const tar_1 = require("tar");
 const path_1 = require("path");
 const local_task_1 = require("../executer/local-task");
@@ -11,9 +11,11 @@ const event_cache_1 = require("../executer/event-cache");
 const get_outputs_to_reset_1 = require("./utils/get-outputs-to-reset");
 const find_process_1 = __importDefault(require("find-process"));
 const stream_1 = require("stream");
+const work_state_record_1 = require("./work-state-record");
 function getStateFilename(task) {
-    return (0, path_1.join)(task.data.cwd, '.hammerkit', `${task.id()}`);
+    return (0, path_1.join)(task.data.cwd, '.hammerkit', 'state', (0, work_state_record_1.getStateRecordName)(task));
 }
+exports.getStateFilename = getStateFilename;
 function getPidFilename(task) {
     return (0, path_1.join)(task.data.cwd, '.hammerkit', `${task.id()}.pid`);
 }
@@ -39,6 +41,8 @@ function getLocalWorkRuntime(task) {
             // pidfile check happens in execute (initialize has no Environment in scope)
         },
         async restore(environment, path) {
+            // the restored outputs aren't the ones the record names any more
+            await removeStateFile(environment, task);
             await restoreLocal(environment, task.data, path);
         },
         async archive(environment, path) {
@@ -54,7 +58,7 @@ function getLocalWorkRuntime(task) {
                 });
                 return;
             }
-            await environment.file.createDirectory((0, path_1.join)(task.data.cwd, '.hammerkit'));
+            await environment.file.createDirectory((0, path_1.join)(task.data.cwd, '.hammerkit', 'state'));
             const pidFile = getPidFilename(task);
             await environment.file.writeFile(pidFile, `${process.pid}`);
             try {
@@ -62,16 +66,14 @@ function getLocalWorkRuntime(task) {
                 // fails overwrites outputs, so the previous record goes first, and only
                 // a run that succeeded writes a new one.
                 const stateFile = getStateFilename(task);
-                if (await environment.file.exists(stateFile)) {
-                    await environment.file.remove(stateFile);
-                }
+                await removeStateFile(environment, task);
                 for (const generate of (0, get_outputs_to_reset_1.getOutputsToReset)(task.data)) {
                     await environment.file.remove(generate.path);
                 }
                 await (0, local_task_1.localTask)(task, environment, options);
                 const failed = ['crash', 'error', 'canceled'].includes(options.state.current.type);
                 if (!failed) {
-                    await environment.file.writeFile(stateFile, options.stateKey);
+                    await environment.file.writeFile(stateFile, (0, work_state_record_1.formatStateRecord)(task, options.stateKey));
                 }
             }
             finally {
@@ -95,7 +97,7 @@ function getLocalWorkRuntime(task) {
                     return null;
                 }
             }
-            return await environment.file.read(stateFileName);
+            return (0, work_state_record_1.parseStateRecord)(task, await environment.file.read(stateFileName));
         },
         async remove(environment) {
             for (const generate of task.data.generates) {
@@ -109,6 +111,12 @@ function getLocalWorkRuntime(task) {
     };
 }
 exports.getLocalWorkRuntime = getLocalWorkRuntime;
+async function removeStateFile(environment, task) {
+    const stateFile = getStateFilename(task);
+    if (await environment.file.exists(stateFile)) {
+        await environment.file.remove(stateFile);
+    }
+}
 async function archiveLocal(environment, task, path) {
     for (const generatedArchive of (0, event_cache_1.getArchivePaths)(task.data, path)) {
         await environment.file.writeStream(generatedArchive.filename, 

package/dist/planner/work-secret.js

@@ -66,9 +66,13 @@ function parseSecretSource(secret, ref, cwd, envs, catalog, taskAccount, label)
     if (providerRef.length === 0 || providerRef.startsWith('-')) {
         throw new Error(`${label}: a reference for ${kind} must not be empty or start with -`);
     }
-    const accountName = secret.account ?? taskAccount ?? Object.values(catalog.accounts).find((a) => a.default)?.name;
+    const accountName = catalog.explicitAccounts
+        ? secret.account
+        : secret.account ?? taskAccount ?? Object.values(catalog.accounts).find((a) => a.default)?.name;
     if (!accountName) {
-        throw new Error(`${label}: ${kind}:${providerRef} needs an account, and none is named or marked default: true`);
+        throw new Error(catalog.explicitAccounts
+            ? `${label}: ${kind}:${providerRef} needs account: on the secret, a server uses neither a task's account nor a default`
+            : `${label}: ${kind}:${providerRef} needs an account, and none is named or marked default: true`);
     }
     const account = catalog.accounts[accountName];
     if (!account) {

package/dist/planner/work-service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getHealthcheckCommand = exports.getServiceCommand = exports.getServiceWorkingDir = exports.isContainerWorkService = void 0;
+const task_arguments_1 = require("./utils/task-arguments");
 const isContainerWorkService = (svc) => 'image' in svc && svc.type === 'container-service';
 exports.isContainerWorkService = isContainerWorkService;
 // The container's working directory: the declared `workdir`, else the build
@@ -10,14 +11,17 @@ exports.getServiceWorkingDir = getServiceWorkingDir;
 // The container's entrypoint and command for a service: with a `shell`, its
 // `cmd` runs as `<shell> -c "<cmd>"` in place of the image entrypoint; without
 // one the tokenized `cmd` becomes the command and the image entrypoint stays.
-function getServiceCommand(service) {
+// For Kubernetes, the arguments after -- are escaped so they stay text there.
+function getServiceCommand(service, options = {}) {
     if (!service.cmd) {
         return { entrypoint: null, cmd: null };
     }
     if (service.shell) {
-        return { entrypoint: [service.shell, '-c'], cmd: [service.cmd.cmd] };
+        const cmd = options.kubernetes ? (0, task_arguments_1.getKubernetesCommandText)(service.cmd) : service.cmd.cmd;
+        return { entrypoint: [service.shell, '-c'], cmd: [cmd] };
     }
-    return { entrypoint: null, cmd: [service.cmd.parsed.command, ...service.cmd.parsed.args] };
+    const args = options.kubernetes ? (0, task_arguments_1.getKubernetesCommandArgs)(service.cmd) : service.cmd.parsed.args;
+    return { entrypoint: null, cmd: [service.cmd.parsed.command, ...args] };
 }
 exports.getServiceCommand = getServiceCommand;
 // The healthcheck as an exec command, through the service's `shell` if it has one.

package/dist/planner/work-state-record.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStateRecord = exports.formatStateRecord = exports.getStateRecordName = void 0;
+const crypto_1 = require("crypto");
+// The state record says "the outputs at this task's paths were made by this
+// variant of the task (its id), from this state key". It is kept per task
+// *name*, because every variant of a task (other arguments after --, another
+// --set value) writes the same output paths: a record per id would let a run of
+// one variant overwrite the outputs while the record of another one still
+// claims them. The id stored with the key makes the next run of that other
+// variant a miss.
+function getStateRecordName(task) {
+    return (0, crypto_1.createHash)('sha1').update(`${task.name}\0${task.data.projectRoot}`).digest('hex');
+}
+exports.getStateRecordName = getStateRecordName;
+function formatStateRecord(task, stateKey) {
+    return `${task.id()}:${stateKey}`;
+}
+exports.formatStateRecord = formatStateRecord;
+// The state key of the record when this variant made the outputs, else null.
+function parseStateRecord(task, content) {
+    const record = content.trim();
+    const separator = record.indexOf(':');
+    if (separator < 0 || record.slice(0, separator) !== task.id()) {
+        return null;
+    }
+    return record.slice(separator + 1) || null;
+}
+exports.parseStateRecord = parseStateRecord;
+//# sourceMappingURL=work-state-record.js.map

package/dist/program.js

@@ -27,6 +27,8 @@ const units_1 = require("./utils/units");
 const cache_inventory_1 = require("./cache/cache-inventory");
 const remote_commands_1 = require("./remote/remote-commands");
 const server_command_1 = require("./server/server-command");
+const run_worker_command_1 = require("./server/run-worker-command");
+const task_arguments_1 = require("./planner/utils/task-arguments");
 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);
@@ -79,6 +81,31 @@ function printTaskDefinition(environment, definition) {
         (0, log_1.printProperty)(environment, `env ${reference.name}`, `from $${reference.from} ${colors_1.default.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).
+function getListJson(tasks, services) {
+    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: (0, task_arguments_1.getArgumentsTarget)(item.data)?.cmd ?? null,
+        })),
+        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: (0, task_arguments_1.getArgumentsTarget)(item.data)?.cmd ?? null,
+        })),
+    };
+}
 function parseWorkLabelScope(options) {
     const scope = {
         environmentName: null,
@@ -102,10 +129,20 @@ function parseWorkLabelScope(options) {
     }
     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) {
+    return command.getOptionValueSource('cache') === 'cli';
+}
 async function getProgram(environment, argv) {
     const program = new commander_1.Command();
     (0, server_command_1.registerServerCommand)(program, environment);
-    const parsed = (0, parse_set_arguments_1.parseSetArguments)(argv);
+    (0, run_worker_command_1.registerRunWorkerCommand)(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 = (0, parse_set_arguments_1.parseSetArguments)(separator >= 0 ? argv.slice(0, separator) : argv);
     const args = parsed.args;
     environment.processEnvs = { ...environment.processEnvs, ...parsed.values };
     const fileIndex = args.indexOf('--file');
@@ -114,17 +151,28 @@ async function getProgram(environment, argv) {
         args.splice(fileIndex, 2);
     }
     (0, remote_commands_1.registerRemoteCommands)(program, environment, fileName);
+    program.hook('preAction', (_, actionCommand) => {
+        const takesArguments = actionCommand.parent === program && ['run', 'up'].includes(actionCommand.name());
+        if (passthrough.length > 0 && !takesArguments) {
+            program.error(`${actionCommand.name()} takes no arguments after --, only run and up do`, { exitCode: 1 });
+        }
+    });
     if (await environment.file.exists(fileName)) {
         program
             .command('ls')
             .description('list all tasks')
             .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('--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(cli_1.isCliTask);
             const services = items.filter(cli_1.isCliService);
+            if (options.json) {
+                environment.stdout.write(`${JSON.stringify(getListJson(tasks, services), null, 2)}\n`);
+                return;
+            }
             if (services.length > 0) {
                 (0, log_1.printTitle)(environment, 'Services');
                 for (const service of services) {
@@ -525,7 +573,8 @@ async function getProgram(environment, argv) {
         });
         program
             .command('up')
-            .description('start services(s)')
+            .description("start services(s), with the arguments after -- appended to the selected service's cmd")
+            .usage('[options] [-- args...]')
             .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('-c, --concurrency <number>', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)').argParser(parseInt))
@@ -544,9 +593,12 @@ async function getProgram(environment, argv) {
             .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) => {
+            .action(async (options, command) => {
             try {
-                const scope = parseWorkLabelScope(options);
+                const scope = {
+                    ...parseWorkLabelScope(options),
+                    args: { values: passthrough, services: true, cache: keepsCache(command) },
+                };
                 const cli = await createCli(fileName, environment, scope);
                 const result = await cli.runUp({
                     cacheDefault: options.cache,
@@ -599,7 +651,8 @@ async function getProgram(environment, argv) {
         });
         program
             .command('run [task]', { isDefault: true })
-            .description('execute task')
+            .description('execute task, with the arguments after -- appended to its last command')
+            .usage('[options] [task] [-- args...]')
             .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('-c, --concurrency <number>', 'parallel worker count (default 4, unbounded when every task and service requests cpus and memory)').argParser(parseInt))
@@ -619,14 +672,15 @@ async function getProgram(environment, argv) {
             .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 nothing needing them has to run'))
-            .action(async (task, options) => {
+            .action(async (task, options, 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 = 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));
+                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;

package/dist/remote/remote-commands.js

@@ -108,7 +108,7 @@ function registerRemoteCommands(program, environment, buildFile) {
             const me = await (0, server_client_1.getMe)(server, result.accessToken);
             environment.stdout.write(`signed in to ${name} as ${me.sub}\n`);
             environment.stdout.write(me.accounts.length > 0
-                ? `service accounts: ${me.accounts.join(', ')}\n`
+                ? `service accounts: ${me.accounts.map((a) => `${(0, server_client_1.printable)(a.name)} (${a.level})`).join(', ')}\n`
                 : 'you have no service accounts on this server\n');
         }
         catch (e) {
@@ -131,21 +131,25 @@ function registerRemoteCommands(program, environment, buildFile) {
         const chosen = await getServer(name);
         const token = await (0, credentials_1.getAccessToken)(environment, chosen.name, chosen.server);
         const me = await (0, server_client_1.getMe)(chosen.server, token);
-        environment.stdout.write(`${chosen.name}: ${me.sub} (${me.iss})\n`);
-        if (me.accounts.length === 0 && !(me.request && me.request.length > 0)) {
+        const { body } = await (0, server_client_1.callServer)(chosen.server, token, 'GET', '/v1/accounts');
+        environment.stdout.write(`${chosen.name}: ${(0, server_client_1.printable)(me.sub)} (${(0, server_client_1.printable)(me.iss)})\n`);
+        if (body.accounts.length === 0) {
             environment.stdout.write('no service accounts\n');
         }
-        for (const account of me.accounts) {
-            environment.stdout.write(`${account}${account === me.default ? colors_1.default.green(' (default)') : ''}\n`);
+        for (const account of body.accounts) {
+            const level = account.level === 'use' ? 'use' : 'request, somebody who uses it approves';
+            environment.stdout.write(`${colors_1.default.bold((0, server_client_1.printable)(account.name))}  ${level}${account.description ? `  ${(0, server_client_1.printable)(account.description)}` : ''}  from ${account.sources.map(server_client_1.printable).join(', ')}\n`);
         }
-        if (me.publish && me.publish.length > 0) {
-            environment.stdout.write(`may publish build files: ${me.publish.join(', ')}\n`);
+        if (me.builds) {
+            const may = {
+                run: 'run published build files',
+                propose: 'propose build files, which somebody who publishes approves',
+                publish: 'publish build files',
+            }[me.builds];
+            environment.stdout.write(`you may ${may}\n`);
         }
-        if (me.propose && me.propose.length > 0) {
-            environment.stdout.write(`may propose build files, which need an approval: ${me.propose.join(', ')}\n`);
-        }
-        if (me.request && me.request.length > 0) {
-            environment.stdout.write(`may request runs, which an admin approves: ${me.request.join(', ')}\n`);
+        if (me.repos.length > 0) {
+            environment.stdout.write(`repositories: ${me.repos.map(server_client_1.printable).join(', ')}\n`);
         }
     }));
     (0, remote_work_commands_1.registerWorkCommands)(remote, { environment, buildFile, getServer, guarded });