hammerkit 1.27.0-next.2 → 1.27.0-next.21

package/dist/run-program.js

@@ -7,6 +7,8 @@ exports.runProgram = void 0;
 const program_1 = require("./program");
 const parse_error_1 = require("./schema/parse-error");
 const colors_1 = __importDefault(require("colors"));
+const commander_1 = require("commander");
+const log_1 = require("./log");
 function runProgram(env, argv, exitOverride) {
     return (0, program_1.getProgram)(env, argv)
         .then(({ program, args }) => {
@@ -18,8 +20,15 @@ function runProgram(env, argv, exitOverride) {
             for (const error of err.zod.errors) {
                 env.stderr.write(` ${colors_1.default.underline(colors_1.default.blue(`error`))} at ${colors_1.default.gray(error.path.join('.'))} ${error.message}  ${colors_1.default.gray(error.code)}\n`);
             }
+            // printed, but still a failure: CI must not pass on a build file that doesn't parse
+            throw err;
         }
         else {
+            // what commander reports (program.error, a wrong option) is printed already; anything
+            // else, such as a build file that is no YAML, would otherwise end the process silently
+            if (!(err instanceof commander_1.CommanderError)) {
+                env.stderr.write(`${colors_1.default.red('error')}: ${(0, log_1.getErrorMessage)(err)}\n`);
+            }
             throw err;
         }
     });

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

@@ -40,8 +40,12 @@ exports.buildFileBaseTaskSchema = (0, zod_1.object)({
     account: (0, zod_1.string)().optional(),
     // CPU and memory limits of the container; a local task is not limited
     resources: resources_schema_1.resourcesSchema.optional(),
-    // what the container reaches besides its needs; a local task can't be limited
+    // what the container reaches besides its needs; a local task can be limited only where
+    // it runs in a container, on a server's cluster
     network: network_schema_1.networkSchema.optional(),
+    // whether its last command takes the arguments after `--`: false refuses them, true
+    // says it is meant to, which a server with `runs.args: declared` requires
+    args: (0, zod_1.boolean)().optional(),
     // Name of the server (see `hammerkit remote`) the task has to run on; defaults
     // to the build file's `runner`. Never a local fallback when it is unknown.
     runner: runner_schema_1.runnerSchema.optional(),

package/dist/schema/build-file-container-service-schema.js

@@ -45,6 +45,8 @@ exports.buildFileContainerServiceSchema = (0, zod_1.object)({
     volumeSize: size_schema_1.sizeSchema.describe('size of its claim on Kubernetes, e.g. 10Gi').optional(),
     // what the service reaches besides its needs; tasks needing it always reach it
     network: network_schema_1.networkSchema.optional(),
+    // whether its `cmd` takes the arguments after `--` of `up`: false refuses them
+    args: (0, zod_1.boolean)().optional(),
 })
     .strict()
     .describe('container service');

package/dist/schema/build-file-include-schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isGitSource = exports.buildFileIncludeSchema = exports.buildFileGitSourceSchema = void 0;
+exports.isGitSource = exports.buildFileIncludeSchema = exports.buildFileLocalSourceSchema = exports.buildFileGitSourceSchema = void 0;
 const zod_1 = require("zod");
 const envs_schema_1 = require("./envs-schema");
 // A repo URL or ref starting with `-` would be read by git as an option
@@ -22,10 +22,16 @@ exports.buildFileGitSourceSchema = (0, zod_1.object)({
     // overrides for the top-level `envs` the included file declares as its inputs
     with: envs_schema_1.envsSchema.optional(),
 }).strict();
-// A string is a local path; an object is a git source (ADR-0004).
-exports.buildFileIncludeSchema = (0, zod_1.union)([(0, zod_1.string)(), exports.buildFileGitSourceSchema]);
+// A local path with values for the inputs of the file it names, like `with` of a git
+// source. A value may pass on an `envs` value of the including file as `${NAME}`.
+exports.buildFileLocalSourceSchema = (0, zod_1.object)({
+    path: (0, zod_1.string)().min(1).describe('Build file or directory, relative to the including file'),
+    with: envs_schema_1.envsSchema.optional(),
+}).strict();
+// A string is a local path; an object is a local path with inputs, or a git source (ADR-0004).
+exports.buildFileIncludeSchema = (0, zod_1.union)([(0, zod_1.string)(), exports.buildFileLocalSourceSchema, exports.buildFileGitSourceSchema]);
 function isGitSource(include) {
-    return typeof include !== 'string';
+    return typeof include !== 'string' && 'git' in include;
 }
 exports.isGitSource = isGitSource;
 //# sourceMappingURL=build-file-include-schema.js.map

package/dist/schema/reference-parser.js

@@ -129,6 +129,7 @@ function applySchemaExtension(reference, task) {
     task.schema.timeout = task.schema.timeout ?? extend.schema.timeout;
     task.schema.runner = task.schema.runner ?? extend.schema.runner;
     task.schema.network = task.schema.network ?? extend.schema.network;
+    task.schema.args = task.schema.args ?? extend.schema.args;
     if (!reset.has('cmds'))
         task.schema.cmds = extendArray(task.schema.cmds, extend.schema.cmds);
     if (!reset.has('src'))
@@ -209,7 +210,9 @@ function resolveNeeds(reference, taskOrService, scope, schema) {
     for (const needName of schema.needs || []) {
         if (typeof needName === 'string') {
             taskOrService.needs.push({
-                relativeName: needName,
+                // the host name it is reached by: a service of an include, `services:postgres`, as
+                // `services-postgres`, since Docker and DNS take no colon
+                relativeName: needName.replace(/:/g, '-'),
                 service: findService(reference, scope, needName),
             });
         }
@@ -220,6 +223,11 @@ function resolveNeeds(reference, taskOrService, scope, schema) {
             });
         }
     }
+    const names = taskOrService.needs.map((need) => need.relativeName);
+    const twice = names.find((name, index) => names.indexOf(name) !== index);
+    if (twice) {
+        throw new Error(`${taskOrService.relativeName} needs two services as ${twice}, give one another name with name:`);
+    }
 }
 function findTask(ctx, scope, name, type) {
     const ref = (0, split_name_1.splitName)(name);

package/dist/schema/schema-parser.js

@@ -89,13 +89,45 @@ async function locateInclude(ctx, scope, include, base, environment) {
         if (!(0, resolve_git_source_1.isWithin)(remote.root, path)) {
             throw new Error(`${include.path} in ${include.git} points outside the repository`);
         }
-        return { fileName: await (0, default_build_file_1.getBuildFilename)(path, environment), remote, inputs: include.with };
+        return { fileName: await (0, default_build_file_1.getBuildFilename)(path, environment), remote, inputs: passEnvs(include.with, scope) };
     }
-    const path = (0, path_1.join)(base, include);
+    const localPath = typeof include === 'string' ? include : include.path;
+    const path = (0, path_1.join)(base, localPath);
     if (scope.remote && !(0, resolve_git_source_1.isWithin)(scope.remote.root, path)) {
-        throw new Error(`${include} in ${scope.fileName} points outside ${scope.remote.git}`);
+        throw new Error(`${localPath} in ${scope.fileName} points outside ${scope.remote.git}`);
     }
-    return { fileName: await (0, default_build_file_1.getBuildFilename)(path, environment), remote: scope.remote };
+    const inputs = typeof include === 'string' ? undefined : passEnvs(include.with, scope);
+    return { fileName: await (0, default_build_file_1.getBuildFilename)(path, environment), remote: scope.remote, inputs };
+}
+// `${NAME}` (or `${NAME:-default}`) in a `with` value reads as it does in the including
+// file: the environment or a `.env` file first, then that file's own `envs` value. So one
+// file holds a value such as NODE_VERSION for all it includes, and CI can still set it. A
+// name the file does not declare is left to the included file, which reads it the same way.
+function passEnvs(inputs, scope) {
+    if (!inputs) {
+        return undefined;
+    }
+    const envs = scope.schema.envs ?? {};
+    const result = {};
+    for (const [key, value] of Object.entries(inputs)) {
+        result[key] =
+            typeof value === 'string'
+                ? value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (match, name, fallback) => name in envs ? passEnv(name, `${envs[name]}`, fallback) : match)
+                : value;
+    }
+    return result;
+}
+// The including file's value as an interpolation the included file resolves in the same
+// order. A value built from other variables is passed on as it is written.
+function passEnv(name, value, fallback) {
+    const reference = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+    if (reference) {
+        return fallback === undefined ? `\${${reference[1]}}` : `\${${reference[1]}:-${fallback}}`;
+    }
+    if (value.includes('$') || value.includes('}')) {
+        return value;
+    }
+    return `\${${name}:-${value}}`;
 }
 // `includes pull` fetches each source once, however often the build files name it.
 async function resolveRemote(ctx, source, environment) {

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

@@ -47,19 +47,27 @@ function getWorkContext(context, scope, environment) {
     // its init task's need on it, which narrowing follows
     const tasks = Object.values(context.tasks).map((task) => (0, append_work_task_1.appendWorkTask)(workTree, task.cwd, task, environment, context));
     const services = Object.values(context.services).map((service) => (0, append_work_service_1.appendWorkService)(workTree, service, environment, context));
+    const apply = { servicesAlone: !(0, work_scope_1.isContextTaskFilter)(scope) && !!scope.names && !!scope.stop };
     const selectedTasks = [];
     const selectedServices = [];
     for (const item of tasks) {
         if (matchesTaskWorkScope(item, scope)) {
             requested.push(item.name);
             selectedTasks.push(item.data);
-            applyTask(filteredWorkTree, item);
+            applyTask(filteredWorkTree, item, apply);
         }
     }
     for (const item of services) {
         if (matchesServiceWorkScope(item.data, scope)) {
             selectedServices.push(item.data);
-            applyService(filteredWorkTree, item);
+            applyService(filteredWorkTree, item, apply);
+        }
+    }
+    if (!(0, work_scope_1.isContextTaskFilter)(scope) && scope.names) {
+        const known = new Set([...tasks.map((task) => task.name), ...services.map((service) => service.data.name)]);
+        const unknown = scope.names.filter((name) => !known.has(name));
+        if (unknown.length > 0) {
+            throw new Error(`no task or service named ${unknown.join(', ')}, see hammerkit ls`);
         }
     }
     if (scope.args) {
@@ -86,43 +94,58 @@ function keepRequirersInScope(workTree) {
         }
     }
 }
-function applyTask(workTree, item) {
+function applyTask(workTree, item, options) {
     if (workTree.tasks[item.name]) {
         return;
     }
     workTree.tasks[item.name] = item;
-    applyNeedsAndDeps(workTree, item);
+    applyNeedsAndDeps(workTree, item, options);
 }
-function applyService(workTree, need) {
+function applyService(workTree, need, options) {
     const item = (0, append_work_service_1.getPlannedService)(need);
     if (workTree.services[item.name]) {
         return;
     }
     workTree.services[item.name] = item;
-    applyNeedsAndDeps(workTree, item);
+    if (options.servicesAlone) {
+        return;
+    }
+    applyNeedsAndDeps(workTree, item, options);
     // a service in the run brings its init task, which runs once it is healthy
     if (item.data.type === 'container-service' && item.data.init) {
-        applyTask(workTree, item.data.init.task);
+        applyTask(workTree, item.data.init.task, options);
     }
 }
-function applyNeedsAndDeps(workTree, item) {
+function applyNeedsAndDeps(workTree, item, options) {
     for (const dep of item.deps) {
-        applyTask(workTree, dep);
+        applyTask(workTree, dep, options);
     }
     for (const need of item.needs) {
-        applyService(workTree, need.service);
+        applyService(workTree, need.service, options);
     }
 }
 function matchesTaskWorkScope(task, scope) {
     if ((0, work_scope_1.isContextTaskFilter)(scope)) {
         return task.name === scope.taskName;
     }
+    if (scope.serviceNames) {
+        return false;
+    }
+    if (scope.names) {
+        return scope.names.includes(task.name);
+    }
     return (0, label_values_1.appliesToLabels)(task.data.labels, scope);
 }
 function matchesServiceWorkScope(service, scope) {
     if ((0, work_scope_1.isContextTaskFilter)(scope)) {
         return false;
     }
+    if (scope.serviceNames) {
+        return scope.serviceNames.includes(service.name);
+    }
+    if (scope.names) {
+        return scope.names.includes(service.name);
+    }
     return (0, label_values_1.appliesToLabels)(service.labels, scope);
 }
 //# sourceMappingURL=work-scope-parser.js.map

package/dist/secrets/github-app-token-command.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerGithubAppTokenCommand = void 0;
+const commander_1 = require("commander");
 const log_1 = require("../log");
 const github_app_token_1 = require("./github-app-token");
 // `hammerkit github-app-token <owner/repo>`: a secret provider command for the token a
@@ -18,7 +19,8 @@ function registerGithubAppTokenCommand(program, environment) {
         }
         catch (e) {
             environment.stderr.write(`github-app-token: ${(0, log_1.getErrorMessage)(e)}\n`);
-            throw e;
+            // said already: the CLI does not print it again
+            throw new commander_1.CommanderError(1, 'hammerkit.githubAppToken', (0, log_1.getErrorMessage)(e));
         }
     });
 }

package/dist/server/accounts-api.js

@@ -6,7 +6,7 @@ const policy_1 = require("./policy");
 /**
  * Who the caller is and what they may do:
  *
- *   GET /v1/me         identity, accounts with their level, repositories, the builds level and the sandbox grants
+ *   GET /v1/me         identity, accounts with their level, repositories, the builds level the sandbox and endpoint grants
  *   GET /v1/accounts   the accounts the caller has a level on, with what the operator says about them
  */
 async function handleAccounts(config, log, principal, req, res, url) {
@@ -31,7 +31,9 @@ async function handleAccounts(config, log, principal, req, res, url) {
             accounts,
             repos: grant.repos,
             builds: grant.builds,
+            checks: grant.checks || grant.builds !== null ? 'read' : null,
             sandboxes: grant.sandboxes,
+            endpoints: grant.endpoints,
         });
         return true;
     }

package/dist/server/approvals-api.js

@@ -13,7 +13,7 @@ function toApprovalView(run) {
     return {
         id: run.id,
         state: run.state,
-        requestedBy: run.owner,
+        requestedBy: { iss: run.owner.iss, sub: run.owner.sub },
         createdAt: run.createdAt,
         definition: run.definition,
         tasks: run.tasks,

package/dist/server/checks-api.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleChecks = exports.MAX_LOOKUP_KEYS = void 0;
+const zod_1 = require("zod");
+const http_1 = require("./http");
+const policy_1 = require("./policy");
+const checks_1 = require("./checks");
+const repo_1 = require("./repo");
+// the tasks one lookup may ask about
+exports.MAX_LOOKUP_KEYS = 100;
+const lookupSchema = zod_1.z
+    .object({
+    repo: zod_1.z.string().transform((value, ctx) => {
+        const repo = (0, repo_1.normalizeRepo)(value);
+        if (!repo) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'expected a repository like github.com/corp/payments' });
+            return zod_1.z.NEVER;
+        }
+        return repo;
+    }),
+    keys: zod_1.z
+        .array(zod_1.z
+        .object({
+        task: zod_1.z.string().min(1).max(200),
+        key: zod_1.z.string().regex(checks_1.CHECK_KEY_PATTERN, 'expected a check key, 64 hex digits'),
+    })
+        .strict())
+        .min(1)
+        .max(exports.MAX_LOOKUP_KEYS),
+})
+    .strict();
+/**
+ * What runs passed, for CI that verifies instead of running (`hammerkit remote verify`):
+ *
+ *   POST /v1/checks/lookup   { repo, keys: [{ task, key }] }  the newest passed run per key
+ *
+ * The caller computed the keys from its own checkout (check-key.ts); a key nothing passed
+ * for, or whose version of the build file was yanked since, is answered with none.
+ */
+async function handleChecks(config, checks, definitions, log, principal, req, res, url) {
+    if (url.pathname !== '/v1/checks/lookup') {
+        return false;
+    }
+    if (req.method !== 'POST') {
+        (0, http_1.send)(res, 405, { error: 'method not allowed' }, { allow: 'POST' });
+        return true;
+    }
+    const parsed = lookupSchema.safeParse(await (0, http_1.readJson)(req));
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        (0, http_1.send)(res, 400, { error: `${issue.path.join('.') || 'request'}: ${issue.message}` });
+        return true;
+    }
+    const { repo, keys } = parsed.data;
+    const grant = (0, policy_1.getGrant)(config.entitlements, principal);
+    if (!(0, policy_1.mayReadChecks)(grant, repo)) {
+        log(`refuse checks iss=${principal.iss} sub=${principal.sub} repo=${repo}`);
+        (0, http_1.send)(res, 403, { error: `you may not read the checks of ${repo}` });
+        return true;
+    }
+    const answers = await Promise.all(keys.map(async ({ task, key }) => {
+        const record = await checks.find(repo, key);
+        const yanked = record ? definitions.find(record.definition)?.yanked : undefined;
+        if (!record || yanked) {
+            return {
+                task,
+                key,
+                passed: null,
+                ...(yanked ? { reason: `it passed with ${record?.definition}, which was yanked since` } : {}),
+            };
+        }
+        const { repo: _repo, key: _key, accounts: _accounts, ...view } = record;
+        void _repo;
+        void _key;
+        void _accounts;
+        return { task, key, passed: view };
+    }));
+    log(`checks iss=${principal.iss} sub=${principal.sub} repo=${repo} passed=${answers.filter((a) => a.passed).length}/${answers.length}`);
+    (0, http_1.send)(res, 200, { checks: answers });
+    return true;
+}
+exports.handleChecks = handleChecks;
+//# sourceMappingURL=checks-api.js.map

package/dist/server/checks.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckStore = exports.getCheckRecords = exports.isCheckRun = exports.CHECK_KEY_PATTERN = void 0;
+const crypto_1 = require("crypto");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+exports.CHECK_KEY_PATTERN = /^[0-9a-f]{64}$/;
+// The runs whose results are checks: those of a commit the server checked out, and those
+// on a copy of the files of a sandbox, which hold nothing a commit of them would not. A run
+// with arguments ran something other than the task, and is no check of it.
+function isCheckRun(run) {
+    // a run of services keeps them up, it passes nothing
+    if ((run.options.args ?? []).length > 0 || run.up) {
+        return false;
+    }
+    return run.source.type === 'ref' || (run.source.type === 'sandbox' && run.source.check === true);
+}
+exports.isCheckRun = isCheckRun;
+// What a run that ended passed, with the keys its executor reported before the tasks ran.
+function getCheckRecords(run, keys) {
+    if (!isCheckRun(run) || run.source.type === 'upload') {
+        return [];
+    }
+    const source = run.source.type === 'ref'
+        ? { type: 'ref', ref: run.source.ref, commit: run.source.commit }
+        : { type: 'sandbox', sandbox: run.source.id, commit: run.source.commit, tree: run.source.tree };
+    const records = [];
+    for (const [task, result] of Object.entries(run.results ?? {})) {
+        const key = keys[task];
+        if (!key || !exports.CHECK_KEY_PATTERN.test(key) || (result.status !== 'succeeded' && result.status !== 'cached')) {
+            continue;
+        }
+        records.push({
+            repo: run.source.repo,
+            key,
+            task,
+            status: result.status,
+            run: run.id,
+            by: { iss: run.owner.iss, sub: run.owner.sub },
+            source,
+            definition: run.definition,
+            accounts: [...run.accounts],
+            finishedAt: result.finishedAt ?? run.finishedAt ?? new Date().toISOString(),
+            ...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
+        });
+    }
+    return records;
+}
+exports.getCheckRecords = getCheckRecords;
+/**
+ * One file per repository and key, the newest run's: `<directory>/<repo hash>/<key>.json`,
+ * written to a temporary file and renamed. A record older than `keep` is not found and is
+ * removed by `sweep`.
+ */
+class CheckStore {
+    constructor(directory, options) {
+        this.directory = directory;
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    async save(records) {
+        for (const record of records) {
+            const folder = (0, path_1.join)(this.directory, repoFolder(record.repo));
+            await (0, promises_1.mkdir)(folder, { recursive: true, mode: 0o700 });
+            const file = (0, path_1.join)(folder, `${record.key}.json`);
+            const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            await (0, promises_1.writeFile)(temporary, JSON.stringify(record), { mode: 0o600 });
+            await (0, promises_1.rename)(temporary, file);
+        }
+    }
+    async find(repo, key) {
+        if (!exports.CHECK_KEY_PATTERN.test(key)) {
+            return undefined;
+        }
+        let record;
+        try {
+            record = JSON.parse(await (0, promises_1.readFile)((0, path_1.join)(this.directory, repoFolder(repo), `${key}.json`), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+        if (record.repo !== repo || record.key !== key || this.expired(record)) {
+            return undefined;
+        }
+        return record;
+    }
+    // Removes the records that are older than `keep`.
+    async sweep() {
+        let folders;
+        try {
+            folders = await (0, promises_1.readdir)(this.directory);
+        }
+        catch {
+            return;
+        }
+        for (const folder of folders) {
+            const path = (0, path_1.join)(this.directory, folder);
+            for (const name of await (0, promises_1.readdir)(path).catch(() => [])) {
+                const file = (0, path_1.join)(path, name);
+                const stats = await (0, promises_1.stat)(file).catch(() => undefined);
+                if (stats && this.now() - stats.mtimeMs > this.options.keep) {
+                    await (0, promises_1.rm)(file, { force: true });
+                }
+            }
+        }
+    }
+    expired(record) {
+        const at = Date.parse(record.finishedAt);
+        return !Number.isFinite(at) || this.now() - at > this.options.keep;
+    }
+}
+exports.CheckStore = CheckStore;
+function repoFolder(repo) {
+    return (0, crypto_1.createHash)('sha256').update(repo).digest('hex').slice(0, 32);
+}
+//# sourceMappingURL=checks.js.map

package/dist/server/definitions-api.js

@@ -5,6 +5,7 @@ const zod_1 = require("zod");
 const bundle_1 = require("../remote/bundle");
 const definitions_1 = require("./definitions");
 const http_1 = require("./http");
+const run_plan_1 = require("./run-plan");
 const oauth_1 = require("./oauth");
 const policy_1 = require("./policy");
 const proposals_1 = require("./proposals");
@@ -19,7 +20,8 @@ const MAX_PUBLISH_BYTES = bundle_1.MAX_BUNDLE_BYTES * 2;
  *                                        `annotations`, which are not part of the hash
  *   GET  /v1/definitions                 the versions, newest first; `?<key>=<value>`
  *                                        keeps the ones with those annotations
- *   GET  /v1/definitions/<hash>          one version
+ *   GET  /v1/definitions/<hash>          one version, with `arguments`: per task null when
+ *                                        a run of it may pass arguments, else why not
  *   GET  /v1/definitions/<hash>/files    its files
  *   POST /v1/definitions/<hash>/yank     pull it back (body: optional {reason})
  *   POST /v1/definitions/<hash>/unyank   let it go on
@@ -72,7 +74,7 @@ async function handleDefinitions(config, store, proposals, log, principal, req,
         bundle ? (0, http_1.send)(res, 200, bundle) : (0, http_1.send)(res, 404, { error: 'not found' });
     }
     else {
-        (0, http_1.send)(res, 200, found);
+        (0, http_1.send)(res, 200, found.plan ? { ...found, arguments: (0, run_plan_1.describeArguments)(found.plan, config.runs) } : found);
     }
     return true;
 }