gcb-host 0.0.0 → 0.0.1

package/lib/commands/init.d.ts

@@ -0,0 +1,153 @@
+import { type DeploymentMode } from '../config.ts';
+import type { BrokerConfig, GithubAppHostConfig } from 'gcb-core';
+import type { BrokerPaths } from './deployment.ts';
+/** The environment `init` reasons about, injectable so the guard rails can be tested. */
+export interface InitEnvironment {
+    /** Whether this process is inside the container. */
+    readonly isInsideContainer?: () => boolean;
+    /** The home directory whose mounts must not contain the key. */
+    readonly home?: string;
+    /** The directories the container shares, when the caller already has them. */
+    readonly mounts?: readonly string[];
+}
+/** Everything `init` needs, resolved. */
+export interface InitInput {
+    /** The private key GitHub gave you. Required on the first run; optional afterwards. */
+    readonly cert?: string;
+    /** Where the key, config and audit log live on the host. Must be outside every container mount. */
+    readonly dir: string;
+    /** The configuration file itself. Defaults to `<dir>/broker.config.yml`. */
+    readonly configPath?: string;
+    /** Repositories to ensure are in the allowlist. */
+    readonly allow?: readonly string[];
+    /** Repositories to remove from the allowlist. */
+    readonly removeAllow?: readonly string[];
+    /** Replace the allowlist with `allow` instead of adding to it. */
+    readonly replaceAllow?: boolean;
+    /**
+     * Socket path a host process should use. Optional: omitted in sidecar mode, and left as-is in
+     * an existing host config unless you pass it. Supplying a conflicting value in sidecar mode is
+     * an error rather than ignored.
+     */
+    readonly hostSocketPath?: string;
+    /** Which deployment the recorded paths must suit. Must match an existing config. */
+    readonly mode?: DeploymentMode;
+    /** App client ID; required on the first run. */
+    readonly clientId?: string;
+    /** App ID; required on the first run. */
+    readonly appId?: number;
+    /** Permission map; left as-is unless given. */
+    readonly permissions?: Readonly<Record<string, string>>;
+    /** Audit log path override, `host` mode only. */
+    readonly auditPath?: string;
+    /** Regenerate from these flags, discarding the existing file. */
+    readonly force: boolean;
+    /** Injectable environment; defaults to the real one. */
+    readonly env?: InitEnvironment;
+}
+/** What `init` produced. */
+export interface InitResult {
+    /** Host path of the installed key. */
+    readonly keyPath: string;
+    /** Host path of the written config. */
+    readonly configPath: string;
+    readonly config: BrokerConfig;
+    readonly mode: DeploymentMode;
+    /** The configuration that was replaced, when this was an update. */
+    readonly previous?: BrokerConfig;
+}
+/**
+ * The github-app block of a configuration.
+ *
+ * @param config - a validated configuration.
+ * @returns the block for github.com.
+ * @throws {Error} when there is none, which means the file is not one of ours.
+ */
+export declare function appBlock(config: BrokerConfig): GithubAppHostConfig;
+/**
+ * Compute the new allowlist from the existing one and the flags given.
+ *
+ * @param existing - the current entries.
+ * @param input - the resolved options.
+ * @returns the new entries, order preserved, additions deduplicated case-insensitively.
+ * @throws {Error} when a given entry is malformed.
+ */
+export declare function mergeAllowList(existing: readonly string[], input: InitInput): string[];
+/**
+ * Build a fresh configuration from the flags.
+ *
+ * @param input - the resolved options.
+ * @returns the validated configuration.
+ * @throws {Error} when the configuration would be rejected by the daemon.
+ */
+export declare function buildBrokerConfig(input: InitInput): BrokerConfig;
+/**
+ * Merge the flags into an existing configuration, changing only what was asked for.
+ *
+ * The paths come from `paths` rather than from `existing`, because the caller has already decided
+ * whether to carry them over: on a deployment switch the old ones belong to the other layout and
+ * must not survive. (Carrying the sidecar's auditPath into a host config, for instance, points the
+ * daemon at `/var/log/git-cred-broker/` on a host that has no such directory.)
+ *
+ * @param existing - the configuration on disk.
+ * @param input - the resolved options.
+ * @param paths - the paths the broker will resolve.
+ * @returns the validated configuration to write.
+ * @throws {Error} when the result would be rejected by the daemon.
+ */
+export declare function mergeBrokerConfig(existing: BrokerConfig, input: InitInput, paths: BrokerPaths): BrokerConfig;
+/**
+ * Read and validate an existing configuration.
+ *
+ * @param path - the config file.
+ * @returns the configuration, or null when the file does not exist.
+ * @throws {Error} when the file exists but is not a valid configuration.
+ */
+/** One path whose value the user explicitly changed. */
+export interface ConfigChange {
+    readonly path: readonly (string | number)[];
+    readonly value: unknown;
+}
+/**
+ * Install the key and create or update the configuration.
+ *
+ * @param input - the resolved options.
+ * @returns where things landed.
+ * @throws {Error} for any guard-rail violation.
+ */
+export declare function performInit(input: InitInput): InitResult;
+/** Usage text for `init`. */
+export declare const INIT_USAGE: string;
+/**
+ * Parse `--permissions contents=write,pull_requests=write`.
+ *
+ * @param raw - the raw flag value, if any.
+ * @returns the permission map, or undefined when the flag was not given.
+ * @throws {Error} when an entry is not `name=level`.
+ */
+export declare function parsePermissions(raw: string | undefined): Record<string, string> | undefined;
+/**
+ * Resolve which deployment directory and configuration file an init invokes.
+ *
+ * Without --dir, the config is the file the broker reads: --config, else GIT_BROKER_CONFIG, else
+ * the default name. With --dir, the default name inside that directory is used.
+ *
+ * @param args - the two path flags.
+ * @param env - the environment, injectable for tests.
+ * @returns the directory and, when explicit, the config path.
+ */
+export declare function resolveInitSelection(args: {
+    readonly config?: string;
+    readonly dir?: string;
+}, env?: NodeJS.ProcessEnv): {
+    readonly dir: string;
+    readonly configPath: string | undefined;
+};
+/**
+ * Run the `init` command.
+ *
+ * @param argv - arguments after the command name.
+ * @returns the process exit code.
+ */
+export declare function runInit(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/lib/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/lib/commands/init.js

@@ -0,0 +1,510 @@
+/**
+ * `init` — create or update the broker configuration, on the host.
+ *
+ * The configuration file is the source of truth: the daemon only ever reads it, it is meant to
+ * be reviewed and kept, and it can be edited by hand. This command therefore **merges** into an
+ * existing file instead of rewriting it: only the flags you pass change anything, and anything
+ * else — including edits you made yourself — is preserved.
+ *
+ * That matters most for the allowlist, the thing people actually iterate on. Adding one
+ * repository used to mean re-supplying every flag, and `--force` then silently *replaced* the
+ * list, so adding `b/two` could quietly drop `a/one`. Now `--allow b/two` adds it and nothing
+ * else moves.
+ *
+ * `--force` still exists, for regenerating from flags when the file is beyond editing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { parseDocument, stringify } from 'yaml';
+import { deploymentDir, inferMode, loadConfig, resolveConfigPath, SIDECAR, validateConfig, } from '../config.js';
+import { parseAllowEntry } from '../policy.js';
+import { brokerPaths, DEPLOYMENT_MODES, hostArtifacts, HOST_SOCKET_PATH_DEFAULT, requireFixedInSidecar, } from './deployment.js';
+import { fail, insideMountedPath, isInsideContainer, parseArgs, say, writeSecretFile } from 'gcb-core';
+/**
+ * The github-app block of a configuration.
+ *
+ * @param config - a validated configuration.
+ * @returns the block for github.com.
+ * @throws {Error} when there is none, which means the file is not one of ours.
+ */
+export function appBlock(config) {
+    const block = config.hosts['github.com'];
+    if (block?.provider !== 'github-app') {
+        throw new Error('the configuration has no github-app block for github.com');
+    }
+    return block;
+}
+/**
+ * Compute the new allowlist from the existing one and the flags given.
+ *
+ * @param existing - the current entries.
+ * @param input - the resolved options.
+ * @returns the new entries, order preserved, additions deduplicated case-insensitively.
+ * @throws {Error} when a given entry is malformed.
+ */
+export function mergeAllowList(existing, input) {
+    const additions = input.allow ?? [];
+    for (const entry of [...additions, ...(input.removeAllow ?? [])]) {
+        if (!parseAllowEntry(entry)) {
+            throw new Error(`--allow ${JSON.stringify(entry)} is not a valid "owner/repo" pattern (a whole segment may be "*")`);
+        }
+    }
+    const canonical = (entry) => entry.trim().toLowerCase();
+    const removed = new Set((input.removeAllow ?? []).map(canonical));
+    const kept = input.replaceAllow ? [] : existing.filter((entry) => !removed.has(canonical(entry)));
+    const seen = new Set(kept.map(canonical));
+    const result = [...kept];
+    for (const entry of additions) {
+        const key = canonical(entry);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(entry.trim());
+    }
+    if (result.length === 0) {
+        throw new Error('that would leave the allowlist empty; the broker is default-deny, so there would be nothing it could authorize');
+    }
+    return result;
+}
+/**
+ * Build a fresh configuration from the flags.
+ *
+ * @param input - the resolved options.
+ * @returns the validated configuration.
+ * @throws {Error} when the configuration would be rejected by the daemon.
+ */
+export function buildBrokerConfig(input) {
+    const paths = brokerPaths(input.mode ?? 'host', input.dir, input.hostSocketPath);
+    return validateConfig({
+        socketPath: paths.socketPath,
+        auditPath: input.auditPath ?? paths.auditPath,
+        hosts: {
+            'github.com': {
+                provider: 'github-app',
+                allow: [...(input.allow ?? [])],
+                clientId: input.clientId,
+                appId: input.appId,
+                privateKeyPath: paths.privateKeyPath,
+                permissions: input.permissions,
+            },
+        },
+    });
+}
+/**
+ * Merge the flags into an existing configuration, changing only what was asked for.
+ *
+ * The paths come from `paths` rather than from `existing`, because the caller has already decided
+ * whether to carry them over: on a deployment switch the old ones belong to the other layout and
+ * must not survive. (Carrying the sidecar's auditPath into a host config, for instance, points the
+ * daemon at `/var/log/git-cred-broker/` on a host that has no such directory.)
+ *
+ * @param existing - the configuration on disk.
+ * @param input - the resolved options.
+ * @param paths - the paths the broker will resolve.
+ * @returns the validated configuration to write.
+ * @throws {Error} when the result would be rejected by the daemon.
+ */
+export function mergeBrokerConfig(existing, input, paths) {
+    const block = appBlock(existing);
+    return validateConfig({
+        socketPath: paths.socketPath,
+        auditPath: paths.auditPath,
+        hosts: {
+            ...existing.hosts,
+            'github.com': {
+                provider: 'github-app',
+                allow: mergeAllowList(block.allow, input),
+                clientId: input.clientId ?? block.clientId,
+                appId: input.appId ?? block.appId,
+                privateKeyPath: paths.privateKeyPath,
+                permissions: input.permissions ?? block.permissions,
+            },
+        },
+    });
+}
+/**
+ * Write a configuration. A fresh file is serialized from the merged object; an existing file is
+ * edited only at the paths the user changed, so comments, other hosts and unknown keys survive.
+ *
+ * @param configPath - the destination.
+ * @param config - the configuration to write when the file is new or forced.
+ * @param force - replace the file instead of editing it.
+ * @param changes - explicit edits for the existing-document path.
+ */
+function writeConfig(configPath, config, force, changes) {
+    if (force || !fs.existsSync(configPath)) {
+        writeSecretFile(configPath, `# Broker configuration for gcb. See README.md.\n${stringify(config, { lineWidth: 0 })}`);
+        return;
+    }
+    if (changes.length === 0)
+        return;
+    const document = parseDocument(fs.readFileSync(configPath, 'utf8'), {
+        schema: 'core',
+        uniqueKeys: true,
+        prettyErrors: true,
+    });
+    if (document.errors.length > 0) {
+        throw new Error(`cannot update ${configPath}: ${document.errors.map((error) => error.message).join('; ')}`);
+    }
+    for (const change of changes)
+        document.setIn(change.path, change.value);
+    const text = document.toString();
+    writeSecretFile(configPath, text.endsWith('\n') ? text : `${text}\n`);
+}
+function readExistingConfig(path) {
+    if (!fs.existsSync(path))
+        return null;
+    return loadConfig(path);
+}
+/**
+ * Install the key and create or update the configuration.
+ *
+ * @param input - the resolved options.
+ * @returns where things landed.
+ * @throws {Error} for any guard-rail violation.
+ */
+export function performInit(input) {
+    if (input.mode !== undefined && !DEPLOYMENT_MODES.includes(input.mode)) {
+        throw new Error(`--mode must be one of ${DEPLOYMENT_MODES.join(', ')}; got ${input.mode}`);
+    }
+    const insideContainer = (input.env?.isInsideContainer ?? isInsideContainer)();
+    if (insideContainer) {
+        throw new Error('this looks like the agent container; the broker must run outside it, on the host');
+    }
+    const home = input.env?.home ?? (process.env['HOME'] ?? '');
+    const mounted = insideMountedPath(input.dir, home, input.env?.mounts);
+    if (mounted) {
+        throw new Error(`${input.dir} is inside ${mounted}, which is mounted into the container; the private key must live outside every mount`);
+    }
+    const artifacts = hostArtifacts(input.dir);
+    const configPath = input.configPath ?? artifacts.configPath;
+    // --config may point into a directory that does not exist yet; the deployment directory is
+    // created below either way, so do it once here.
+    fs.mkdirSync(deploymentDir(configPath), { recursive: true });
+    const previous = input.force ? null : readExistingConfig(configPath);
+    // ---------------------------------------------------------------- update in place
+    if (previous) {
+        const existingMode = inferMode(previous);
+        // Switching deployment is allowed, but only when asked for by name. The recorded paths are
+        // what decide whether a broker can find its own key, so this must never happen implicitly.
+        const mode = input.mode ?? existingMode;
+        const switching = mode !== existingMode;
+        if (switching && mode === 'host' && input.hostSocketPath === undefined) {
+            throw new Error(`${configPath} records the sidecar's socket path (${previous.socketPath}), which a host process cannot bind; ` +
+                'pass --socket-path <the path the host process binds and the pusher reaches>');
+        }
+        requireFixedInSidecar('--socket-path', input.hostSocketPath, SIDECAR.socketPath, mode);
+        requireFixedInSidecar('--audit-path', input.auditPath, SIDECAR.auditPath, mode);
+        // The key the *host* must have is always <dir>/app.pem. In sidecar mode the config records a
+        // different path, because that is where the sidecar sees the same file — checking the
+        // recorded path here would fail on every update.
+        if (input.cert !== undefined) {
+            writeSecretFile(artifacts.keyPath, readPrivateKey(input.cert));
+        }
+        else if (!fs.existsSync(artifacts.keyPath)) {
+            throw new Error(`${artifacts.keyPath} is missing; pass --cert to install the key`);
+        }
+        let paths;
+        if (mode === 'sidecar') {
+            paths = brokerPaths('sidecar', input.dir, '');
+        }
+        else {
+            // Staying in host mode: keep whatever this deployment chose. Switching *to* host mode: the
+            // old socket and audit paths are the sidecar's container-side ones, so carrying them over
+            // would produce a config that looks fine and cannot work.
+            const carried = switching ? undefined : previous;
+            paths = brokerPaths('host', input.dir, input.hostSocketPath ?? carried?.socketPath ?? HOST_SOCKET_PATH_DEFAULT);
+            const carriedAudit = carried?.auditPath ?? undefined;
+            if (input.auditPath !== undefined)
+                paths = { ...paths, auditPath: input.auditPath };
+            else if (carriedAudit !== undefined)
+                paths = { ...paths, auditPath: carriedAudit };
+        }
+        const config = mergeBrokerConfig(previous, input, paths);
+        const block = appBlock(previous);
+        const mergedBlock = appBlock(config);
+        const allowChanged = (input.allow?.length ?? 0) > 0 || (input.removeAllow?.length ?? 0) > 0 || input.replaceAllow === true;
+        const changes = [];
+        if (paths.socketPath !== previous.socketPath)
+            changes.push({ path: ['socketPath'], value: paths.socketPath });
+        if (paths.auditPath !== previous.auditPath)
+            changes.push({ path: ['auditPath'], value: paths.auditPath });
+        if (paths.privateKeyPath !== block.privateKeyPath) {
+            changes.push({ path: ['hosts', 'github.com', 'privateKeyPath'], value: paths.privateKeyPath });
+        }
+        if (allowChanged && !isDeepStrictEqual(mergedBlock.allow, block.allow)) {
+            changes.push({ path: ['hosts', 'github.com', 'allow'], value: mergedBlock.allow });
+        }
+        if (input.clientId !== undefined && input.clientId !== block.clientId) {
+            changes.push({ path: ['hosts', 'github.com', 'clientId'], value: input.clientId });
+        }
+        if (input.appId !== undefined && input.appId !== block.appId) {
+            changes.push({ path: ['hosts', 'github.com', 'appId'], value: input.appId });
+        }
+        if (input.permissions !== undefined && !isDeepStrictEqual(input.permissions, block.permissions)) {
+            changes.push({ path: ['hosts', 'github.com', 'permissions'], value: input.permissions });
+        }
+        fs.mkdirSync(artifacts.auditDir, { recursive: true });
+        writeConfig(configPath, config, input.force, changes);
+        return { keyPath: artifacts.keyPath, configPath, config, mode, previous };
+    }
+    // ---------------------------------------------------------------- create (or regenerate)
+    const mode = input.mode ?? 'host';
+    const allow = input.allow ?? [];
+    if (allow.length === 0) {
+        throw new Error('at least one --allow <owner/repo> is required when creating the configuration (the broker is default-deny)');
+    }
+    for (const entry of allow) {
+        if (!parseAllowEntry(entry)) {
+            throw new Error(`--allow ${JSON.stringify(entry)} is not a valid "owner/repo" pattern (a whole segment may be "*")`);
+        }
+    }
+    // Captured into locals: narrowing of `input.x` is invalidated by the calls in between, so
+    // reading the property again afterwards is `string | undefined` to the compiler.
+    const certPath = input.cert;
+    const clientId = input.clientId;
+    const appId = input.appId;
+    if (certPath === undefined)
+        throw new Error('--cert is required when creating the configuration');
+    if (clientId === undefined || clientId === '') {
+        throw new Error('--client-id is required when creating the configuration');
+    }
+    if (appId === undefined || appId <= 0) {
+        throw new Error('--app-id is required when creating the configuration');
+    }
+    requireFixedInSidecar('--socket-path', input.hostSocketPath, SIDECAR.socketPath, mode);
+    requireFixedInSidecar('--audit-path', input.auditPath, SIDECAR.auditPath, mode);
+    const pem = readPrivateKey(certPath);
+    const config = buildBrokerConfig({ ...input, mode, cert: certPath, clientId, appId });
+    writeSecretFile(artifacts.keyPath, pem);
+    fs.mkdirSync(artifacts.auditDir, { recursive: true });
+    writeConfig(configPath, config, input.force, []);
+    return { keyPath: artifacts.keyPath, configPath, config, mode };
+}
+/**
+ * Read and sanity-check a PEM private key.
+ *
+ * @param cert - the path GitHub gave you.
+ * @returns the file contents.
+ * @throws {Error} when it is missing or is not a PEM private key.
+ */
+function readPrivateKey(cert) {
+    if (!fs.existsSync(cert))
+        throw new Error(`no such file: ${cert}`);
+    const pem = fs.readFileSync(cert, 'utf8');
+    if (!pem.includes('PRIVATE KEY'))
+        throw new Error(`${cert} does not look like a PEM private key`);
+    return pem;
+}
+/** Usage text for `init`. */
+export const INIT_USAGE = `Usage: gcb init [options]
+
+Create or update the broker configuration. Run this on the HOST.
+
+The configuration file is the source of truth. Re-running init updates it in place and changes
+only what you pass, so hand edits survive and the allowlist is never silently replaced.
+
+First run:
+  --cert <path>         GitHub App private key (.pem)                    [required]
+  --allow <owner/repo>  Repository to authorize; repeatable or comma-separated  [required]
+  --client-id <id>      App client ID (preferred JWT issuer)             [required]
+  --app-id <id>         App ID (fallback issuer)                         [required]
+
+Every run:
+  --allow <owner/repo>  Add to the allowlist (deduplicated); repeatable or comma-separated
+  --remove-allow <r>    Remove from the allowlist; repeatable or comma-separated
+  --replace-allow       Replace the whole allowlist with --allow, instead of adding
+  --cert <path>         Replace the installed key
+  --client-id <id>      Change the client ID
+  --app-id <id>         Change the App ID
+  --permissions <list>  name=level pairs, e.g. contents=write,pull_requests=write
+  --dir <path>          Where the key, config and audit log live (default: the config's directory)
+  --config <path>       Configuration file (default: $GIT_BROKER_CONFIG, else ./broker.config.yml)
+  --mode <host|sidecar> Which deployment the paths must suit (default: host; must match an
+                        existing config, because it decides where the broker looks for things)
+  --socket-path <path>  Socket path a host process uses (default: /run/git-cred-broker/broker.sock)
+  --audit-path <path>   Audit log path override (host mode only)
+  --force               Regenerate from these flags, discarding the existing file
+  -h, --help            Show this help
+
+--mode matters because the paths inside the configuration are resolved by the broker process,
+not by this one. In --mode sidecar they are fixed by the compose file (socketPath
+${SIDECAR.socketPath}, privateKeyPath ${SIDECAR.keyPath}, auditPath ${SIDECAR.auditPath}),
+so a different --socket-path or --audit-path is rejected rather than silently recorded.
+`;
+/**
+ * Parse `--permissions contents=write,pull_requests=write`.
+ *
+ * @param raw - the raw flag value, if any.
+ * @returns the permission map, or undefined when the flag was not given.
+ * @throws {Error} when an entry is not `name=level`.
+ */
+export function parsePermissions(raw) {
+    if (raw === undefined)
+        return undefined;
+    const out = {};
+    for (const pair of raw.split(',')) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const equals = trimmed.indexOf('=');
+        if (equals <= 0)
+            throw new Error(`--permissions expects name=level pairs, got ${JSON.stringify(trimmed)}`);
+        out[trimmed.slice(0, equals)] = trimmed.slice(equals + 1);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Render the permissions the broker will actually request, in a stable order.
+ *
+ * An absent map means the provider's default, which is `contents=write` — worth printing, because
+ * "I did not pass anything" and "I passed something that did not stick" otherwise look identical.
+ *
+ * @param permissions - the configured map, if any.
+ * @returns a `name=level` list.
+ */
+function formatPermissions(permissions) {
+    const effective = permissions ?? { contents: 'write' };
+    return (Object.entries(effective)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, level]) => `${name}=${level}`)
+        .join(' ') || '(none)');
+}
+/**
+ * Split a repeatable, comma-separated flag.
+ *
+ * @param args - the parsed arguments.
+ * @param name - the flag name.
+ * @returns the entries.
+ */
+function list(args, name) {
+    return args
+        .values(name)
+        .flatMap((value) => value.split(','))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+/**
+ * Resolve which deployment directory and configuration file an init invokes.
+ *
+ * Without --dir, the config is the file the broker reads: --config, else GIT_BROKER_CONFIG, else
+ * the default name. With --dir, the default name inside that directory is used.
+ *
+ * @param args - the two path flags.
+ * @param env - the environment, injectable for tests.
+ * @returns the directory and, when explicit, the config path.
+ */
+export function resolveInitSelection(args, env = process.env) {
+    const dir = path.resolve(args.dir ?? deploymentDir(resolveConfigPath(args.config, env)));
+    const configPath = args.config !== undefined
+        ? path.resolve(args.config)
+        : args.dir === undefined
+            ? resolveConfigPath(undefined, env)
+            : undefined;
+    return { dir, configPath };
+}
+/**
+ * Run the `init` command.
+ *
+ * @param argv - arguments after the command name.
+ * @returns the process exit code.
+ */
+export async function runInit(argv) {
+    const args = parseArgs(argv, { booleans: ['force', 'replace-allow', 'help'] });
+    if (args.has('help') || args.has('h')) {
+        say(INIT_USAGE);
+        return 0;
+    }
+    const clientId = args.value('client-id');
+    const appIdRaw = args.value('app-id');
+    const appId = appIdRaw === undefined ? undefined : Number(appIdRaw);
+    if (appId !== undefined && (!Number.isInteger(appId) || appId <= 0)) {
+        fail('--app-id must be a positive integer');
+    }
+    const mode = args.value('mode');
+    if (mode !== undefined && !DEPLOYMENT_MODES.includes(mode)) {
+        fail(`--mode must be one of ${DEPLOYMENT_MODES.join(', ')}`);
+    }
+    const selection = resolveInitSelection({ config: args.value('config'), dir: args.value('dir') });
+    try {
+        const result = performInit({
+            cert: args.value('cert'),
+            dir: selection.dir,
+            configPath: selection.configPath,
+            allow: list(args, 'allow'),
+            removeAllow: list(args, 'remove-allow'),
+            replaceAllow: args.has('replace-allow'),
+            hostSocketPath: args.value('socket-path'),
+            mode: mode,
+            clientId,
+            appId,
+            permissions: parsePermissions(args.value('permissions')),
+            auditPath: args.value('audit-path'),
+            force: args.has('force'),
+        });
+        const verb = result.previous ? 'updated' : 'created';
+        const wasMode = result.previous ? inferMode(result.previous) : undefined;
+        const modeLabel = wasMode !== undefined && wasMode !== result.mode ? `${wasMode} -> ${result.mode}` : result.mode;
+        say(`mode           : ${modeLabel}`);
+        say(`${verb.padEnd(15)}: ${result.configPath} (mode 600, validation passed)`);
+        say(`installed key  : ${result.keyPath} (mode 600)`);
+        const block = appBlock(result.config);
+        if (result.previous) {
+            const beforeBlock = appBlock(result.previous);
+            say('');
+            say(`allowlist      : ${beforeBlock.allow.join(' ')}`);
+            say(`              -> ${block.allow.join(' ')}`);
+        }
+        else {
+            say(`allowlist      : ${block.allow.join(' ')}`);
+        }
+        // Always, not only when it changed: without this, "did --permissions take effect?" could only be
+        // answered by re-reading the file, and a run that did nothing looks exactly like one that worked.
+        say(`permissions    : ${formatPermissions(block.permissions)}${block.permissions ? '' : ' (the default)'}`);
+        say('');
+        say('paths inside the configuration, from the broker\'s point of view:');
+        say(`  socketPath     : ${result.config.socketPath}`);
+        say(`  privateKeyPath : ${block.privateKeyPath}${block.privateKeyPath === result.keyPath ? '' : `  (= ${result.keyPath} on the host)`}`);
+        say(`  auditPath      : ${result.config.auditPath}`);
+        say('');
+        if (result.previous) {
+            say('Restart the broker to pick this up:');
+            if (result.mode === 'sidecar') {
+                say('  docker compose -f docker-compose.broker.yml up -d    # sidecar');
+            }
+            else {
+                say(`  gcb daemon --config ${result.configPath}    # host process`);
+            }
+            if (wasMode !== undefined && wasMode !== result.mode) {
+                say('');
+                say(`NOTE: the recorded paths changed from the ${wasMode} layout to the ${result.mode} layout.`);
+                say(result.mode === 'host'
+                    ? '      Stop the sidecar and start the host process; the socket file is the same one.'
+                    : '      Stop the host process and start the sidecar; the socket file is the same one.');
+            }
+        }
+        else {
+            say('Two things only you can do:');
+            say('  1. Install the app on the account that owns those repositories, granting access to just them.');
+            say('     A private app owned by an organisation can only be installed on that organisation.');
+            say('  2. Confirm the app grants every permission requested above; the broker checks on first use.');
+            say('');
+            if (result.mode === 'sidecar') {
+                say('Then start the sidecar, which mounts those paths exactly as recorded:');
+                say(`  gcb compose --dir ${path.dirname(result.keyPath)} --config ${result.configPath} --socket-dir <a directory the pusher mounts> \\`);
+                say('    > docker-compose.broker.yml && docker compose -f docker-compose.broker.yml up -d');
+            }
+            else {
+                say('Then start the broker as a host process:');
+                say(`  gcb daemon --config ${result.configPath} --check   # validate, bind nothing`);
+                say(`  gcb daemon --config ${result.configPath}`);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        fail(error.message);
+    }
+}
+//# sourceMappingURL=init.js.map