hammerkit 1.27.0-next.8 → 2.0.0-next.1

package/dist/server/plan.js

@@ -13,6 +13,7 @@ const work_scope_parser_1 = require("../schema/work-scope-parser");
 const work_task_1 = require("../planner/work-task");
 const work_service_1 = require("../planner/work-service");
 const hosted_volumes_1 = require("../planner/utils/hosted-volumes");
+const normalize_path_1 = require("../planner/utils/normalize-path");
 const log_1 = require("../log");
 const parse_error_1 = require("../schema/parse-error");
 const task_arguments_1 = require("../planner/utils/task-arguments");
@@ -39,50 +40,33 @@ const COMMIT_PATTERN = /^[0-9a-f]{40}([0-9a-f]{24})?$/i;
 // A hash alone can only name what is inside the bundle, so everything a build
 // file pulls in from elsewhere has to be pinned: a git include needs a commit
 // and a remote that is not a path on the server.
-function findLooseIncludes(bundle, noRemote = false) {
+function checkGitSource(path, where, source, noRemote) {
+    if (noRemote === 'proposal') {
+        throw new DefinitionError(`${path}: ${where}: a proposal may not include from git, the server would fetch it before anybody approved it`);
+    }
+    if (noRemote === 'check') {
+        throw new DefinitionError(`${path}: ${where}: checking a build file that includes from git needs builds: publish, the server would fetch it`);
+    }
     const problems = [];
-    for (const [path, content] of Object.entries(bundle.files)) {
-        if (!/\.ya?ml$/i.test(path)) {
-            continue;
-        }
-        let document;
-        try {
-            document = (0, yaml_1.parse)(content);
-        }
-        catch {
-            continue; // a file that isn't valid yaml is reported when the bundle is parsed
-        }
-        for (const block of ['includes', 'references']) {
-            for (const [name, include] of Object.entries(document?.[block] ?? {})) {
-                const source = include;
-                if (!source || typeof source !== 'object' || source.git === undefined) {
-                    continue;
-                }
-                if (noRemote) {
-                    problems.push(`${path}: ${block}.${name}: a proposal may not include from git, the server would fetch it before anybody approved it`);
-                    continue;
-                }
-                if (typeof source.git !== 'string' || !/^(https:\/\/|ssh:\/\/|git@[\w.-]+:)/.test(source.git)) {
-                    problems.push(`${path}: ${block}.${name}: git has to be an https:// or ssh:// address`);
-                }
-                if (typeof source.ref !== 'string' || !COMMIT_PATTERN.test(source.ref)) {
-                    problems.push(`${path}: ${block}.${name}: pin ref to a commit, a branch or tag can move`);
-                }
-            }
-        }
+    if (!/^(https:\/\/|ssh:\/\/|git@[\w.-]+:)/.test(source.git)) {
+        problems.push(`${path}: ${where}: git has to be an https:// or ssh:// address`);
+    }
+    if (typeof source.ref !== 'string' || !COMMIT_PATTERN.test(source.ref)) {
+        problems.push(`${path}: ${where}: pin ref to a commit, a branch or tag can move`);
+    }
+    if (problems.length > 0) {
+        throw new DefinitionError(problems.join('\n'));
     }
-    return problems;
 }
 // What a build file may not name on a server: the places it would run or store things
 // are the operator's. The docker host, a Kubernetes cluster and a remote cache are
 // credentials of the machine, not of the build file, and a project file that could carry
 // them could send runs, or the cache, anywhere.
-function findHostProblems(bundle) {
+// A file a server leaves out (`publish: false`) is not checked, and neither is a service
+// with `publish: false`: what is left out is never run there.
+function findHostProblems(files) {
     const problems = [];
-    for (const [path, content] of Object.entries(bundle.files)) {
-        if (!/\.ya?ml$/i.test(path)) {
-            continue;
-        }
+    for (const [path, content] of Object.entries(files)) {
         let document;
         try {
             document = (0, yaml_1.parse)(content);
@@ -104,6 +88,7 @@ function findHostProblems(bundle) {
         for (const [name, service] of Object.entries(document.services ?? {})) {
             if (service &&
                 typeof service === 'object' &&
+                service.publish !== false &&
                 ('selector' in service || 'kubeconfig' in service || 'context' in service)) {
                 problems.push(`${path}: services.${name}: Kubernetes services are not supported on a server`);
             }
@@ -111,6 +96,17 @@ function findHostProblems(bundle) {
     }
     return problems;
 }
+// The files of the bundle a server publishes, see getPublishedFiles
+function publishedBundleFiles(bundle, directory, entry) {
+    const files = {};
+    for (const scope of (0, reference_parser_1.getPublishedFiles)(entry)) {
+        const path = (0, path_1.relative)(directory, scope.fileName).split(path_1.sep).join('/');
+        if (!scope.remote && path in bundle.files) {
+            files[path] = bundle.files[path];
+        }
+    }
+    return files;
+}
 // What a build file may read while it is inspected: its own files. The rest of
 // the server is not its business (a missing file is "not there", not an error).
 function confined(files, root) {
@@ -165,101 +161,139 @@ function describeSecret(secret) {
 // server has no account, so nothing would stand between the build file and the
 // operator's own credentials.
 function findPolicyProblems(items, policy, root) {
-    const problems = [];
+    // the problems of each item, said once for the items of a directory that share one, such
+    // as the tasks of an included file that all mount the docker socket
+    const grouped = new Map();
     for (const item of items) {
-        const runtime = item.data.type === 'local-task' ? 'local' : 'docker';
-        if (policy.runtimes && !policy.runtimes.includes(runtime)) {
-            problems.push(`${item.name}: runs on the ${runtime} runtime, which this server does not allow (runtimes: ${policy.runtimes.join(', ')})`);
-        }
-        const data = item.data;
-        // what a task reads and writes is the bundle's: `src: ../..` would have the server
-        // copy its own files (its credentials, other callers' caches) into the task
-        for (const source of 'src' in data ? data.src : []) {
-            if (!source.inherited && insideBundle(root, data.cwd, source.absolutePath).length === 0) {
-                problems.push(`${item.name}: src ${source.source} is outside of the bundle`);
+        const prefix = `${item.name}: `;
+        for (const problem of findItemPolicyProblems(item, policy, root)) {
+            const said = problem.startsWith(prefix) ? problem.slice(prefix.length) : problem;
+            const key = `${item.data.cwd}\0${said}`;
+            const group = grouped.get(key);
+            if (group) {
+                group.names.push(item.name);
             }
-        }
-        for (const generate of (0, work_task_1.isWorkTask)(data) ? data.generates : []) {
-            if (!generate.inherited && insideBundle(root, data.cwd, generate.path).length === 0) {
-                problems.push(`${item.name}: generates ${generate.path}, which is outside of the bundle`);
+            else {
+                grouped.set(key, { names: [item.name], problem: said });
             }
         }
-        // what holds a credential gets at most `runs.secretNetwork`, so a tool it runs can't
-        // send the credential anywhere else
-        const reads = getCredentialReads({
-            secrets: secretsOf(item).map(describeSecret),
-            serverEnvs: 'envs' in data ? data.envs.processNames ?? [] : [],
-        });
-        const ceilings = [];
-        if (policy.network && (0, work_network_1.isLimitedNetwork)(policy.network)) {
-            ceilings.push({ ceiling: policy.network, setting: 'runs.network', reason: '' });
+    }
+    return [...grouped.values()].map(({ names: [name, ...others], problem }) => others.length > 0 ? `${name} (also ${others.join(', ')}): ${problem}` : `${name}: ${problem}`);
+}
+function findItemPolicyProblems(item, policy, root) {
+    const problems = [];
+    const runtime = item.data.type === 'local-task' ? 'local' : 'docker';
+    // an aggregate runs nothing, on no runtime
+    if (policy.runtimes && !(0, work_task_1.isAggregateTask)(item.data) && !policy.runtimes.includes(runtime)) {
+        problems.push(`${item.name}: runs on the ${runtime} runtime, which this server does not allow (runtimes: ${policy.runtimes.join(', ')})`);
+    }
+    const data = item.data;
+    // a capability holds in the sandboxed runtime the operator named for it, so only those
+    // the operator allows are added
+    const refused = policy.capabilities
+        ? ('capAdd' in data ? data.capAdd : []).filter((capability) => !policy.capabilities?.includes(capability))
+        : [];
+    if (refused.length > 0) {
+        const from = policy.capabilitiesFrom ?? 'backend.capabilities.allow';
+        problems.push(`${item.name}: adds the ${refused.length > 1 ? 'capabilities' : 'capability'} ${refused.join(', ')}, ` +
+            (policy.capabilities && policy.capabilities.length > 0
+                ? `which this server does not allow (${from}: ${policy.capabilities.join(', ')})`
+                : `and this server allows none (${from})`));
+    }
+    // what a task reads and writes is the bundle's: `src: ../..` would have the server
+    // copy its own files (its credentials, other callers' caches) into the task
+    for (const source of 'src' in data ? data.src : []) {
+        if (!source.inherited && insideBundle(root, data.cwd, source.absolutePath).length === 0) {
+            problems.push(`${item.name}: src ${source.source} is outside of the bundle`);
         }
-        if (reads.length > 0 && policy.secretNetwork && (0, work_network_1.isLimitedNetwork)(policy.secretNetwork)) {
-            ceilings.push({
-                ceiling: policy.secretNetwork,
-                setting: 'runs.secretNetwork',
-                reason: ` to what reads ${reads.join(', ')}`,
-            });
+    }
+    for (const generate of (0, work_task_1.isWorkTask)(data) ? data.generates : []) {
+        if (!generate.inherited && insideBundle(root, data.cwd, generate.path).length === 0) {
+            problems.push(`${item.name}: generates ${generate.path}, which is outside of the bundle`);
         }
-        for (const { ceiling, setting, reason } of ceilings) {
-            // on a cluster a local task is a pod of a pool's tool image, limited like any other
-            if (data.type === 'local-task' && policy.backend !== 'kubernetes') {
-                problems.push(`${item.name}: is a local task, which can't be limited to the network this server allows${reason} ` +
-                    `(${setting}: ${(0, work_network_1.formatNetwork)(ceiling)})`);
-            }
-            else if ('network' in data && (0, work_network_1.exceedsNetwork)(data.network, ceiling)) {
-                problems.push(`${item.name}: asks for network ${(0, work_network_1.formatNetwork)(data.network)}, more than this server allows${reason} ` +
-                    `(${setting}: ${(0, work_network_1.formatNetwork)(ceiling)})`);
-            }
+    }
+    // what holds a credential gets at most `runs.secretNetwork`, so a tool it runs can't
+    // send the credential anywhere else
+    const reads = getCredentialReads({
+        secrets: secretsOf(item).map(describeSecret),
+        serverEnvs: 'envs' in data ? data.envs.processNames ?? [] : [],
+    });
+    const ceilings = [];
+    if (policy.network && (0, work_network_1.isLimitedNetwork)(policy.network)) {
+        ceilings.push({ ceiling: policy.network, setting: 'runs.network', reason: '' });
+    }
+    if (reads.length > 0 && policy.secretNetwork && (0, work_network_1.isLimitedNetwork)(policy.secretNetwork)) {
+        ceilings.push({
+            ceiling: policy.secretNetwork,
+            setting: 'runs.secretNetwork',
+            reason: ` to what reads ${reads.join(', ')}`,
+        });
+    }
+    // an aggregate reaches nothing: it runs no command
+    for (const { ceiling, setting, reason } of (0, work_task_1.isAggregateTask)(data) ? [] : ceilings) {
+        // on a cluster a local task is a pod of a pool's tool image, limited like any other
+        if (data.type === 'local-task' && policy.backend !== 'kubernetes') {
+            problems.push(`${item.name}: is a local task, which can't be limited to the network this server allows${reason} ` +
+                `(${setting}: ${(0, work_network_1.formatNetwork)(ceiling)})`);
         }
-        if ((0, work_task_1.isContainerWorkTask)(data) || (0, work_service_1.isContainerWorkService)(data)) {
-            for (const mount of data.mounts) {
-                // a path of the server is not the build file's to mount: the docker socket, /etc, a home directory
-                if (insideBundle(root, data.cwd, mount.localPath).length === 0) {
-                    problems.push(`${item.name}: mounts ${mount.localPath}, which is outside of the bundle`);
-                }
-            }
+        else if ('network' in data && (0, work_network_1.exceedsNetwork)(data.network, ceiling)) {
+            problems.push(`${item.name}: asks for network ${(0, work_network_1.formatNetwork)(data.network)}, more than this server allows${reason} ` +
+                `(${setting}: ${(0, work_network_1.formatNetwork)(ceiling)})`);
         }
-        for (const volume of (0, work_service_1.isContainerWorkService)(data) ? data.volumes : []) {
-            // docker takes anything else for a path of the host, such as the docker socket
-            if (!(0, hosted_volumes_1.isVolumeName)(volume.name)) {
-                problems.push(`${item.name}: volume ${volume.name} is not a volume name, a path of the server can't be mounted`);
+    }
+    if ((0, work_task_1.isContainerWorkTask)(data) || (0, work_service_1.isContainerWorkService)(data)) {
+        for (const mount of data.mounts) {
+            // a path of the server is not the build file's to mount: the docker socket, /etc, a home directory
+            if (insideBundle(root, data.cwd, mount.localPath).length === 0) {
+                problems.push(`${item.name}: mounts ${describeMountSource(mount)}, which is outside of the bundle`);
             }
         }
-        for (const secret of secretsOf(item)) {
-            const source = secret.source;
-            if (policy.backend === 'kubernetes' && source.type === 'provider') {
-                // the server reads no secret of a provider on a cluster: the Job of a task does
-                if (!(0, work_task_1.isWorkTask)(item.data)) {
-                    problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read from ${source.provider}, which ` +
-                        'this server does for tasks only, a service on its cluster gets no provider secret yet');
-                }
-                else if (secret.cache) {
-                    problems.push(`${item.name}: the secret ${describeSecret(secret).target} has cache: true, its digest would need ` +
-                        'the value before the Job of the task reads it, which this server does not support yet');
-                }
-                else if ((0, work_network_1.isLimitedNetwork)(item.data.network) && !policy.proxiedProviders?.includes(source.provider)) {
-                    // the init containers that read it share the pod's NetworkPolicy, and reach the
-                    // provider only through the egress proxy
-                    problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read from ${source.provider} in the ` +
-                        `Job of the task, which network ${(0, work_network_1.formatNetwork)(item.data.network)} would cut off from it: ` +
-                        `this server names no endpoints of ${source.provider} in backend.providers.${source.provider}.allow ` +
-                        'for the egress proxy to let through, so the task keeps an open network');
-                }
-            }
-            if (source.type === 'provider' && policy.reserved?.includes(source.account)) {
-                problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read as ${source.account}, which the server uses to read repositories`);
+    }
+    for (const volume of (0, work_service_1.isContainerWorkService)(data) ? data.volumes : []) {
+        // docker takes anything else for a path of the host, such as the docker socket
+        if (!(0, hosted_volumes_1.isVolumeName)(volume.name)) {
+            problems.push(`${item.name}: volume ${volume.name} is not a volume name, a path of the server can't be mounted`);
+        }
+    }
+    for (const secret of secretsOf(item)) {
+        const source = secret.source;
+        if (policy.backend === 'kubernetes' && source.type === 'provider') {
+            // the server reads no secret of a provider on a cluster: the Job of a task does
+            if (!(0, work_task_1.isWorkTask)(item.data)) {
+                problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read from ${source.provider}, which ` +
+                    'this server does for tasks only, a service on its cluster gets no provider secret yet');
             }
-            else if (source.type === 'file') {
-                problems.push(`${item.name}: a secret can not read a file of the server (file:), use a secret provider`);
+            else if (secret.cache) {
+                problems.push(`${item.name}: the secret ${describeSecret(secret).target} has cache: true, its digest would need ` +
+                    'the value before the Job of the task reads it, which this server does not support yet');
             }
-            else if (source.type === 'env' && !policy.envs.includes(source.name)) {
-                problems.push(`${item.name}: the secret ${describeSecret(secret).target} reads env:${source.name}, which the server does not list in ${policy.envsFrom ?? 'runs.env.allow'}`);
+            else if ((0, work_network_1.isLimitedNetwork)(item.data.network) && !policy.proxiedProviders?.includes(source.provider)) {
+                // the init containers that read it share the pod's NetworkPolicy, and reach the
+                // provider only through the egress proxy
+                problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read from ${source.provider} in the ` +
+                    `Job of the task, which network ${(0, work_network_1.formatNetwork)(item.data.network)} would cut off from it: ` +
+                    `this server names no endpoints of ${source.provider} in backend.providers.${source.provider}.allow ` +
+                    'for the egress proxy to let through, so the task keeps an open network');
             }
         }
+        if (source.type === 'provider' && policy.reserved?.includes(source.account)) {
+            problems.push(`${item.name}: the secret ${describeSecret(secret).target} is read as ${source.account}, which the server uses to read repositories`);
+        }
+        else if (source.type === 'file') {
+            problems.push(`${item.name}: a secret can not read a file of the server (file:), use a secret provider`);
+        }
+        else if (source.type === 'env' && !policy.envs.includes(source.name)) {
+            problems.push(`${item.name}: the secret ${describeSecret(secret).target} reads env:${source.name}, which the server does not list in ${policy.envsFrom ?? 'runs.env.allow'}`);
+        }
     }
     return problems;
 }
+// A mount of the home directory says so: `$PWD` in a mount is the home directory, not the
+// project, which reads like a path of the checkout
+function describeMountSource(mount) {
+    const home = (0, normalize_path_1.getHomeReference)(mount.mount.split(':')[0]);
+    return home ? `${mount.localPath} (${home} is the home directory)` : mount.localPath;
+}
 function toPlan(root, item) {
     const data = item.data;
     const secrets = secretsOf(item).map(describeSecret);
@@ -272,7 +306,7 @@ function toPlan(root, item) {
         : [];
     const ports = 'ports' in data ? data.ports.map((port) => `${port.hostPort ?? ''}:${port.containerPort}`) : [];
     const flags = [];
-    if (data.type === 'local-task') {
+    if (data.type === 'local-task' && !(0, work_task_1.isAggregateTask)(data)) {
         flags.push('local-task');
     }
     if ('ports' in data && data.ports.some((port) => port.hostPort !== null)) {
@@ -281,10 +315,15 @@ function toPlan(root, item) {
     if (data.scope.remote) {
         flags.push('remote-include');
     }
+    const capAdd = (0, work_task_1.isContainerWorkTask)(data) ? data.capAdd : [];
+    if (capAdd.length > 0) {
+        flags.push('capabilities');
+    }
     const isTask = data.type === 'local-task' || data.type === 'container-task';
     return {
         kind: isTask ? 'task' : 'service',
-        runtime: data.type === 'local-task' ? 'local' : 'docker',
+        ...(data.description ? { description: data.description } : {}),
+        runtime: (0, work_task_1.isAggregateTask)(data) ? 'none' : data.type === 'local-task' ? 'local' : 'docker',
         ...((0, work_task_1.isContainerWorkTask)(data) || (0, work_service_1.isContainerWorkService)(data) ? { image: data.image } : {}),
         cmds: 'cmds' in data ? data.cmds.map((cmd) => cmd.cmd) : 'cmd' in data && data.cmd ? [data.cmd.cmd] : [],
         command: (0, task_arguments_1.getArgumentsTarget)(data)?.cmd ?? null,
@@ -298,6 +337,7 @@ function toPlan(root, item) {
         mounts,
         ports,
         generates: 'generates' in data ? data.generates.map((generate) => generate.path) : [],
+        ...(capAdd.length > 0 ? { capAdd: [...capAdd] } : {}),
         flags,
     };
 }
@@ -314,10 +354,6 @@ function describeFailure(e) {
 // when somebody wants to run it. The same function answers what a run will do,
 // with the scope of the run: which tasks, services and accounts it involves.
 async function planBundle(bundle, environment, options = {}) {
-    const problems = [...findLooseIncludes(bundle, options.noRemote), ...(options.policy ? findHostProblems(bundle) : [])];
-    if (problems.length > 0) {
-        throw new DefinitionError(problems.join('\n'));
-    }
     const directory = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), 'hammerkit-definition-'));
     try {
         for (const [path, content] of Object.entries(bundle.files)) {
@@ -330,7 +366,20 @@ async function planBundle(bundle, environment, options = {}) {
             file: confined((0, get_file_context_1.getFileContext)(directory), directory),
         };
         try {
-            const { ctx, scope } = await (0, schema_parser_1.createParseContext)((0, path_1.join)(directory, bundle.entry), inspected);
+            const { ctx, scope } = await (0, schema_parser_1.createParseContext)((0, path_1.join)(directory, bundle.entry), inspected, {
+                // a hash alone can only name what is inside the bundle, see checkGitSource
+                checkGitSource: (source, from, block, name) => checkGitSource(
+                // a file of a git include is named by its repository
+                from.remote
+                    ? `${from.remote.git} ${(0, path_1.relative)(from.remote.root, from.fileName).split(path_1.sep).join('/')}`
+                    : (0, path_1.relative)(directory, from.fileName), `${block}.${name}`, source, options.noRemote),
+            });
+            if (options.policy) {
+                const problems = findHostProblems(publishedBundleFiles(bundle, directory, scope));
+                if (problems.length > 0) {
+                    throw new DefinitionError(problems.join('\n'));
+                }
+            }
             const context = await (0, reference_parser_1.parseReferences)(ctx, scope, inspected);
             const workTree = (0, work_scope_parser_1.getWorkContext)(context, options.scope ?? { environmentName: null }, inspected);
             const items = itemsOf(workTree);

package/dist/server/policy.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decideRun = exports.sandboxRepos = exports.decideSandbox = exports.sandboxPushBranches = exports.sandboxBranchType = exports.getGrant = exports.usedAccounts = exports.mayYank = exports.canUse = exports.maySeeDefinitions = exports.mayPublish = exports.mayPropose = exports.mayRun = exports.matches = void 0;
+exports.decideRun = exports.sandboxRepos = exports.decideSandbox = exports.sandboxPushBranches = exports.sandboxBranchType = exports.endpointLevel = exports.getGrant = exports.usedAccounts = exports.mayYank = exports.canUse = exports.maySeeDefinitions = exports.mayPublish = exports.mayPropose = exports.mayReadChecks = exports.mayRun = exports.matches = void 0;
 const repo_1 = require("./repo");
 const BUILDS_ORDER = ['run', 'propose', 'publish'];
 function matches(entitlement, principal) {
@@ -22,6 +22,12 @@ function atLeast(grant, level) {
 }
 const mayRun = (grant) => atLeast(grant, 'run');
 exports.mayRun = mayRun;
+// Who may run from a repository's refs may see what passed for its files, and so may who
+// is entitled to just that (a CI job that only verifies).
+function mayReadChecks(grant, repo) {
+    return (grant.checks || grant.builds !== null) && (0, repo_1.matchesAnyRepo)(grant.repos, repo);
+}
+exports.mayReadChecks = mayReadChecks;
 const mayPropose = (grant) => atLeast(grant, 'propose');
 exports.mayPropose = mayPropose;
 const mayPublish = (grant) => atLeast(grant, 'publish');
@@ -55,12 +61,17 @@ function getGrant(entitlements, principal) {
     const accounts = {};
     const repos = [];
     const sandboxes = [];
+    const endpoints = [];
     let builds = null;
+    let checks = false;
+    let observe = false;
     entitlements.forEach((entitlement, index) => {
         if (!matches(entitlement, principal)) {
             return;
         }
         matched.push(index);
+        checks = checks || entitlement.checks === 'read';
+        observe = observe || entitlement.observe === true;
         for (const [account, level] of Object.entries(entitlement.accounts)) {
             if (accounts[account] !== 'use') {
                 accounts[account] = level;
@@ -85,10 +96,31 @@ function getGrant(entitlements, principal) {
                 known.branches[pattern] = higherType(known.branches[pattern], type);
             }
         }
+        for (const endpoint of entitlement.endpoints ?? []) {
+            const known = endpoints.find((entry) => entry.repo === endpoint.repo);
+            if (!known) {
+                endpoints.push({ ...endpoint });
+            }
+            else if (endpoint.level === 'publish') {
+                known.level = 'publish';
+            }
+        }
     });
-    return { accounts, repos, builds, sandboxes, matched };
+    return { accounts, repos, builds, sandboxes, endpoints, checks, observe, matched };
 }
 exports.getGrant = getGrant;
+// What the caller may do with the endpoints of service runs of a repository: the higher
+// level of the entries whose `repo` covers it, null for nothing.
+function endpointLevel(grant, repo) {
+    let found = null;
+    for (const endpoint of grant.endpoints) {
+        if ((0, repo_1.matchesRepo)(endpoint.repo, repo) && found !== 'publish') {
+            found = endpoint.level;
+        }
+    }
+    return found;
+}
+exports.endpointLevel = endpointLevel;
 const BRANCH_TYPES = ['pull', 'push'];
 function higherType(a, b) {
     return a !== undefined && BRANCH_TYPES.indexOf(a) > BRANCH_TYPES.indexOf(b) ? a : b;

package/dist/server/proposals-api.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleProposals = exports.mayApprove = void 0;
+exports.handleProposals = exports.decideProposal = exports.mayApprove = void 0;
 const zod_1 = require("zod");
 const bundle_1 = require("../remote/bundle");
 const definitions_1 = require("./definitions");
@@ -23,6 +23,21 @@ function toView(proposal, principal, grant) {
         canDecide: proposal.state === 'waiting' && (0, exports.mayApprove)(grant, proposal) && !same(proposal.proposedBy, principal),
     };
 }
+/**
+ * Approves (publishes) or rejects a proposal, for the API and the dashboard: who decides
+ * needs the permission to publish and the accounts its proposer lacked. Throws a
+ * DefinitionError when the files do not load.
+ */
+async function decideProposal(store, proposals, grant, principal, hash, outcome, reason) {
+    return proposals.decide(principal, hash, outcome, (proposed) => (0, exports.mayApprove)(grant, proposed), async (bundle) => {
+        const proposed = proposals.get(hash);
+        await store.publish(bundle, proposed?.proposedBy ?? principal, {
+            approvedBy: principal,
+            annotations: proposed?.annotations,
+        });
+    }, reason);
+}
+exports.decideProposal = decideProposal;
 /**
  * New versions of build files that wait for an approval. Whoever may only
  * propose a version (`builds: propose`), or publishes one that names accounts they
@@ -94,13 +109,7 @@ async function handleProposals(config, store, proposals, log, principal, req, re
     }
     const outcome = action === 'approve' ? 'approved' : 'rejected';
     try {
-        const result = await proposals.decide(principal, hash, outcome, (proposed) => (0, exports.mayApprove)(grant, proposed), async (bundle) => {
-            const proposed = proposals.get(hash);
-            await store.publish(bundle, proposed?.proposedBy ?? principal, {
-                approvedBy: principal,
-                annotations: proposed?.annotations,
-            });
-        }, body.data.reason);
+        const result = await decideProposal(store, proposals, grant, principal, hash, outcome, body.data.reason);
         log(`${action} proposal=${hash} iss=${principal.iss} sub=${principal.sub} result=${result.status}${body.data.reason ? ` reason=${(0, oauth_1.quote)(body.data.reason)}` : ''}`);
         switch (result.status) {
             case 'ok':

package/dist/server/repo-access.js

@@ -105,6 +105,11 @@ class RepoAccess {
         env.GIT_CONFIG_GLOBAL = '/dev/null';
         return { env, values: credentials.values };
     }
+    // A secret only the server reads, as an account no caller may use: the client secret of
+    // the sign-in at endpoints, read like the credential of a source.
+    serverSecret(secret) {
+        return this.token(secret);
+    }
     async token(secret) {
         const key = `${secret.account}\0${secret.from}`;
         const known = this.tokens.get(key);

package/dist/server/run-logs.js

@@ -106,6 +106,10 @@ class LogIndex {
     get size() {
         return this.lineStart.length;
     }
+    // the tasks, services and `hammerkit` that wrote to the log, in the order they first did
+    names() {
+        return [...this.taskLines.keys()];
+    }
     lines(task) {
         return this.taskLines.get(task) ?? [];
     }

package/dist/server/run-plan.js

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
+exports.describeArguments = exports.refuseArguments = exports.planRun = exports.getRunScopes = void 0;
 const parse_label_arguments_1 = require("../parser/parse-label-arguments");
 const plan_1 = require("./plan");
 function labels(values) {
     return values && values.length > 0 ? (0, parse_label_arguments_1.parseLabelArguments)(values) : undefined;
 }
-// The tasks in the order they were named, one scope each; by labels when none is.
+// The tasks in the order they were named, one scope each; by labels when none is. A
+// service run is one scope of its services.
 // The arguments, if any, go to the one task named (the request allows no more). That
 // task runs uncached unless the request names a `cache` method, as `run --cache` does.
-function getRunScopes(tasks, options) {
+function getRunScopes(tasks, options, services = []) {
+    if (services.length > 0) {
+        return [{ name: services.join(', '), scope: { serviceNames: services, environmentName: options.env ?? null } }];
+    }
     const args = options.args && options.args.length > 0
         ? { values: options.args, services: false, cache: options.cache !== undefined }
         : undefined;
@@ -37,7 +41,7 @@ exports.getRunScopes = getRunScopes;
  */
 async function planRun(bundle, run, environment, policy) {
     const plan = {};
-    for (const { scope } of getRunScopes(run.tasks, run.options)) {
+    for (const { scope } of getRunScopes(run.tasks, run.options, run.up?.services ?? run.services)) {
         Object.assign(plan, (await (0, plan_1.planBundle)(bundle, environment, { scope, policy })).plan);
     }
     return {
@@ -87,4 +91,34 @@ function refuseArguments(run, plan, policy = {}) {
     return null;
 }
 exports.refuseArguments = refuseArguments;
+/**
+ * For each task of a version, whether a run of it alone may pass arguments: null when it may,
+ * else why not, as {@link refuseArguments} answers a run. The plan is the one of the whole
+ * version: a task's run is the task with its dependencies and services.
+ */
+function describeArguments(plan, policy = {}) {
+    const described = {};
+    for (const [name, entry] of Object.entries(plan)) {
+        if (entry.kind !== 'task') {
+            continue;
+        }
+        const run = {};
+        const visit = (item) => {
+            if (run[item] || !plan[item]) {
+                return;
+            }
+            run[item] = plan[item];
+            for (const next of [...plan[item].deps, ...plan[item].needs]) {
+                visit(next);
+            }
+        };
+        visit(name);
+        described[name] =
+            entry.command === null
+                ? `${name} has no command to take arguments`
+                : refuseArguments({ tasks: [name], options: { args: ['-'] } }, run, policy);
+    }
+    return described;
+}
+exports.describeArguments = describeArguments;
 //# sourceMappingURL=run-plan.js.map