@ethlete/cli 2.0.1-next.0 → 2.1.0-next.10

package/src/lib/api/auth-hint.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitUrlProjectPath = exports.gitHostFromInput = exports.gitUrlHost = exports.printPrivateDependencyHint = void 0;
+/**
+ * A private dependency that will not download is the most common way these commands fail, and git
+ * and the package managers report it as a bare 403 or a public-key error. This says what to check.
+ */
+const printPrivateDependencyHint = (options) => {
+    var _a;
+    const host = (_a = options.repoHost) !== null && _a !== void 0 ? _a : 'your git host';
+    console.error(`\nThat command may have failed because a private dependency could not be downloaded.\n` +
+        `Three things are worth checking:\n\n` +
+        `  1. A personal access token for ${host} with permission to DOWNLOAD code.\n` +
+        `     Read access is not enough for a clone, and the server reports the difference as 403.\n` +
+        `  2. An SSH key this machine offers to ${host}, when the dependency is fetched over SSH.\n` +
+        `  3. That the token is where the package manager looks for it, not only in your shell.\n` +
+        `     Composer, for example, reads ~/.composer/auth.json rather than the environment.`);
+};
+exports.printPrivateDependencyHint = printPrivateDependencyHint;
+/** The host of a git url, for naming it in the hint. Undefined when the url has no host. */
+const gitUrlHost = (repoUrl) => {
+    const scpLike = /^[^/]+@([^:]+):/.exec(repoUrl);
+    if (scpLike)
+        return scpLike[1];
+    try {
+        return new URL(repoUrl).hostname || undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
+exports.gitUrlHost = gitUrlHost;
+/**
+ * The host a user names on the command line, which is often pasted as a url: `https://git.example.com/`
+ * holds the same host as `git.example.com`. Undefined when there is no host name in it at all.
+ */
+const gitHostFromInput = (value) => {
+    var _a;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.startsWith('/'))
+        return undefined;
+    return (_a = (0, exports.gitUrlHost)(trimmed)) !== null && _a !== void 0 ? _a : (0, exports.gitUrlHost)(`https://${trimmed}`);
+};
+exports.gitHostFromInput = gitHostFromInput;
+/** The `group/project` part of a git url, for addressing the project in a host's own API. */
+const gitUrlProjectPath = (repoUrl) => {
+    var _a;
+    const scpLike = /^[^/]+@[^:]+:(.+)$/.exec(repoUrl);
+    if (scpLike)
+        return ((_a = scpLike[1]) !== null && _a !== void 0 ? _a : '').replace(/\.git$/, '') || undefined;
+    try {
+        return new URL(repoUrl).pathname.replace(/^\/+/, '').replace(/\.git$/, '') || undefined;
+    }
+    catch (_b) {
+        return undefined;
+    }
+};
+exports.gitUrlProjectPath = gitUrlProjectPath;
+//# sourceMappingURL=auth-hint.js.map

package/src/lib/api/auth-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-hint.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/auth-hint.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACI,MAAM,0BAA0B,GAAG,CAAC,OAA8B,EAAE,EAAE;;IAC3E,MAAM,IAAI,GAAG,MAAA,OAAO,CAAC,QAAQ,mCAAI,eAAe,CAAC;IAEjD,OAAO,CAAC,KAAK,CACX,wFAAwF;QACtF,sCAAsC;QACtC,oCAAoC,IAAI,sCAAsC;QAC9E,6FAA6F;QAC7F,0CAA0C,IAAI,8CAA8C;QAC5F,0FAA0F;QAC1F,sFAAsF,CACzF,CAAC;AACJ,CAAC,CAAC;AAZW,QAAA,0BAA0B,8BAYrC;AAEF,4FAA4F;AACrF,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,EAAE;IAC5C,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,IAAI,SAAS,CAAC;IAChD,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAVW,QAAA,UAAU,cAUrB;AAEF;;;GAGG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAE,EAAE;;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAE1D,OAAO,MAAA,IAAA,kBAAU,EAAC,OAAO,CAAC,mCAAI,IAAA,kBAAU,EAAC,WAAW,OAAO,EAAE,CAAC,CAAC;AACjE,CAAC,CAAC;AANW,QAAA,gBAAgB,oBAM3B;AAEF,6FAA6F;AACtF,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAE,EAAE;;IACnD,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEnD,IAAI,OAAO;QAAE,OAAO,CAAC,MAAA,OAAO,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC;IAE1E,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC;IAC1F,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAVW,QAAA,iBAAiB,qBAU5B"}

package/src/lib/api/clear.d.ts

@@ -0,0 +1,36 @@
+import { ApiDefinitions } from './definition';
+export type ApiClearTarget = {
+    name: string;
+    /** Absolute path that would be removed. */
+    repoPath: string;
+    /** Directory that holds the compose file. */
+    composePath: string;
+    /** Whether any container of its compose project still exists. Those are taken down before the removal. */
+    hasContainers: boolean;
+    /** Why it must stay. Empty when it can be removed. */
+    blockers: string[];
+};
+export type ApiClearPlanOptions = {
+    apis: ApiDefinitions;
+    names: string[];
+    root: string;
+    invocation: string;
+    /** Skips the checks on uncommitted changes and unpushed commits. */
+    force: boolean;
+    /** Whether any container of the API's compose project exists. */
+    hasContainers: (composePath: string) => boolean;
+};
+/**
+ * What `clear` would do to each named API: the path it would remove, and every reason it must stay.
+ * An API without a managed checkout is left out, because there is nothing of ours to remove.
+ */
+export declare const planApiClear: (options: ApiClearPlanOptions) => ApiClearTarget[];
+export type ApiClearOptions = ApiClearPlanOptions & {
+    /** Takes the containers of one compose project down. False when the compose command failed. */
+    takeDown: (composePath: string) => boolean;
+};
+/**
+ * Removes the managed checkout of each named API, after one question that defaults to no. It offers to
+ * take down the containers that still exist, and refuses an API with work only this checkout holds.
+ */
+export declare const clearApiCheckouts: (options: ApiClearOptions) => Promise<number>;

package/src/lib/api/clear.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearApiCheckouts = exports.planApiClear = void 0;
+const tslib_1 = require("tslib");
+const fs_1 = require("fs");
+const utils_1 = require("../utils");
+const git_1 = require("./git");
+const resolve_checkout_1 = require("./resolve-checkout");
+const MAX_LISTED = 5;
+/** The first few lines of a git listing, so a refusal shows what stands in the way. */
+const listed = (lines) => [
+    ...lines.slice(0, MAX_LISTED).map((line) => `  ${line}`),
+    ...(lines.length > MAX_LISTED ? [`  and ${lines.length - MAX_LISTED} more`] : []),
+].join('\n');
+/**
+ * What `clear` would do to each named API: the path it would remove, and every reason it must stay.
+ * An API without a managed checkout is left out, because there is nothing of ours to remove.
+ */
+const planApiClear = (options) => {
+    const { apis, names, root, invocation, force, hasContainers } = options;
+    return names.flatMap((name) => {
+        const api = apis[name];
+        if (!api)
+            return [];
+        const checkout = (0, resolve_checkout_1.resolveApiCheckout)({ root, name, api, needs: 'repo' });
+        if (!checkout.ok)
+            return [];
+        const { repoPath, composePath } = checkout.checkout;
+        const managed = (0, resolve_checkout_1.managedCheckoutPath)(root, name);
+        if (repoPath !== managed) {
+            return [
+                {
+                    name,
+                    repoPath,
+                    composePath,
+                    hasContainers: false,
+                    blockers: [
+                        `${repoPath} is your own checkout, not the one ${invocation} manages. ` +
+                            `Remove it yourself, or drop apiRepoPaths.${name} first.`,
+                    ],
+                },
+            ];
+        }
+        const changes = (0, git_1.uncommittedChanges)(repoPath);
+        const unpushed = (0, git_1.unpushedCommits)(repoPath);
+        return [
+            {
+                name,
+                repoPath,
+                composePath,
+                hasContainers: hasContainers(composePath),
+                blockers: [
+                    ...(!force && changes.length > 0
+                        ? [
+                            `${repoPath} has uncommitted changes:\n\n${listed(changes)}\n\n` +
+                                'Commit them, or pass --force to lose them.',
+                        ]
+                        : []),
+                    ...(!force && unpushed.length > 0
+                        ? [
+                            `${repoPath} has commits no remote holds:\n\n${listed(unpushed)}\n\n` +
+                                'Push them, or pass --force to lose them.',
+                        ]
+                        : []),
+                ],
+            },
+        ];
+    });
+};
+exports.planApiClear = planApiClear;
+/**
+ * Removes the managed checkout of each named API, after one question that defaults to no. It offers to
+ * take down the containers that still exist, and refuses an API with work only this checkout holds.
+ */
+const clearApiCheckouts = (options) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
+    const { names, invocation, takeDown } = options;
+    const targets = (0, exports.planApiClear)(options);
+    const blocked = targets.filter(({ blockers }) => blockers.length > 0);
+    const removable = targets.filter(({ blockers }) => blockers.length === 0);
+    for (const { blockers } of blocked) {
+        console.error(blockers.join('\n\n'));
+    }
+    if (blocked.length > 0)
+        console.error('');
+    if (removable.length === 0) {
+        if (blocked.length === 0) {
+            console.log(`Nothing to remove. ${names.join(', ')} has no checkout ${invocation} manages.`);
+        }
+        return blocked.length > 0 ? 1 : 0;
+    }
+    const paths = removable.map(({ repoPath }) => `  ${repoPath}`).join('\n');
+    const running = removable.filter(({ hasContainers }) => hasContainers).map(({ name }) => name);
+    const stopped = running.join(', ');
+    const checkouts = removable.length === 1 ? 'the checkout' : 'the checkouts';
+    const accepted = yield (0, utils_1.confirm)({
+        problem: running.length > 0 ? `This takes ${stopped} down, then removes:\n\n${paths}` : `This removes:\n\n${paths}`,
+        question: running.length > 0
+            ? `Take ${stopped} down and remove ${checkouts}?`
+            : `Remove ${removable.map(({ name }) => name).join(', ')}?`,
+        hint: running.length > 0
+            ? `Re-run in a terminal to answer the question, or run "${invocation} down ${stopped}" and remove the ` +
+                'directories yourself.'
+            : 'Re-run in a terminal to answer the question, or remove the directories yourself.',
+        defaultsToYes: false,
+    });
+    if (!accepted)
+        return 1;
+    let failed = 0;
+    for (const { name, repoPath, composePath, hasContainers } of removable) {
+        if (hasContainers && !takeDown(composePath)) {
+            console.error(`Could not take ${name} down, so ${repoPath} stays.`);
+            failed += 1;
+            continue;
+        }
+        (0, fs_1.rmSync)(repoPath, { recursive: true, force: true });
+        console.log(`Removed ${repoPath}. Run "${invocation} clone ${name}" to get it back.`);
+    }
+    return blocked.length > 0 || failed > 0 ? 1 : 0;
+});
+exports.clearApiCheckouts = clearApiCheckouts;
+//# sourceMappingURL=clear.js.map

package/src/lib/api/clear.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/clear.ts"],"names":[],"mappings":"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"}

package/src/lib/api/clone.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_CHECKOUT_DIR = ".ethlete";
+/** True when git would ignore the path, so a cloned checkout cannot be committed by accident. */
+export declare const isGitIgnored: (root: string, path: string) => boolean;
+export type CloneRequest = {
+    repoUrl: string;
+    /** Absolute path to clone into. */
+    into: string;
+    /** Branch to check out, from `apiRepoBranches`. */
+    branch?: string;
+};
+/** Clones an API repo into its managed directory. Git's own output and failures are passed through. */
+export declare const cloneApiRepo: ({ repoUrl, into, branch }: CloneRequest) => number;

package/src/lib/api/clone.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneApiRepo = exports.isGitIgnored = exports.DEFAULT_CHECKOUT_DIR = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const fs_2 = require("fs");
+exports.DEFAULT_CHECKOUT_DIR = '.ethlete';
+/** True when git would ignore the path, so a cloned checkout cannot be committed by accident. */
+const isGitIgnored = (root, path) => (0, child_process_1.spawnSync)('git', ['check-ignore', '-q', path], { cwd: root }).status === 0;
+exports.isGitIgnored = isGitIgnored;
+/** Clones an API repo into its managed directory. Git's own output and failures are passed through. */
+const cloneApiRepo = ({ repoUrl, into, branch }) => {
+    var _a;
+    if ((0, fs_1.existsSync)(into)) {
+        console.error(`${into} already exists.`);
+        return 1;
+    }
+    (0, fs_2.mkdirSync)((0, path_1.dirname)(into), { recursive: true });
+    const args = ['clone', ...(branch ? ['--branch', branch] : []), '--', repoUrl, into];
+    return (_a = (0, child_process_1.spawnSync)('git', args, { stdio: 'inherit' }).status) !== null && _a !== void 0 ? _a : 1;
+};
+exports.cloneApiRepo = cloneApiRepo;
+//# sourceMappingURL=clone.js.map

package/src/lib/api/clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/clone.ts"],"names":[],"mappings":";;;AAAA,iDAA0C;AAC1C,2BAAgC;AAChC,+BAA+B;AAC/B,2BAA+B;AAElB,QAAA,oBAAoB,GAAG,UAAU,CAAC;AAE/C,iGAAiG;AAC1F,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,EAAE,CACzD,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AADhE,QAAA,YAAY,gBACoD;AAU7E,uGAAuG;AAChG,MAAM,YAAY,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAgB,EAAE,EAAE;;IACtE,IAAI,IAAA,eAAU,EAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,kBAAkB,CAAC,CAAC;QAEzC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAA,cAAS,EAAC,IAAA,cAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAErF,OAAO,MAAA,IAAA,yBAAS,EAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,mCAAI,CAAC,CAAC;AAClE,CAAC,CAAC;AAZW,QAAA,YAAY,gBAYvB"}

package/src/lib/api/compose.d.ts

@@ -0,0 +1,46 @@
+export type ComposeTool = {
+    engine: string;
+    /** The binary and its fixed arguments. Non-empty, so the first entry is always the binary. */
+    compose: [string, ...string[]];
+};
+export declare const composeBinary: (compose: string[]) => string[];
+/** Finds the first container tool on this machine that answers `<compose> version`. */
+export declare const resolveComposeTool: (tools?: ComposeTool[]) => ComposeTool | undefined;
+export declare const composeToolNames: (tools?: ComposeTool[]) => string[];
+export declare const engineEnv: (engine: string) => {
+    CONTAINERS_REGISTRIES_CONF: string;
+} | {
+    CONTAINERS_REGISTRIES_CONF?: undefined;
+};
+export declare const lanAddress: () => string | undefined;
+/** Path of this machine's SSH key, for a compose file that mounts one into the API container. */
+export declare const sshKeyPath: () => string | undefined;
+export type ComposeCall = {
+    tool: ComposeTool;
+    /** Directory that holds the compose file. */
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+};
+/** Runs a compose command and captures its stdout. `undefined` when the tool itself failed. */
+export declare const composeOutput: (options: ComposeCall & {
+    args: string[];
+}) => string | undefined;
+/** Container ids of a compose project, or `undefined` when the tool could not answer. */
+export declare const composeContainerIds: (call: ComposeCall) => string[] | undefined;
+export type PortMapping = {
+    host: number;
+    container: number;
+};
+export type ContainerState = {
+    id: string;
+    name: string;
+    /** Compose service, empty for a container compose did not start. */
+    service: string;
+    /** The engine's own words, for example `Up 42 minutes` or `Exited (1) 3 seconds ago`. */
+    status: string;
+    ports: PortMapping[];
+};
+/** True for a status the engine prints while the container runs. */
+export declare const isRunningStatus: (status: string) => boolean;
+/** Every container the engine knows, with its compose service and published ports. */
+export declare const containerStates: (engine: string) => ContainerState[];

package/src/lib/api/compose.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containerStates = exports.isRunningStatus = exports.composeContainerIds = exports.composeOutput = exports.sshKeyPath = exports.lanAddress = exports.engineEnv = exports.composeToolNames = exports.resolveComposeTool = exports.composeBinary = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * SELinux denies a container read access to a bind mount that carries the host's own label, and API
+ * repos mount their checkout without the `:z` that would relabel it. Disabling the label from here
+ * keeps those checkouts untouched.
+ */
+const PODMAN_COMPOSE_ARGS = ['--podman-run-args=--security-opt label=disable'];
+const COMPOSE_TOOLS = [
+    { engine: 'docker', compose: ['docker', 'compose'] },
+    { engine: 'container', compose: ['container', 'compose'] },
+    { engine: 'podman', compose: ['podman-compose', ...PODMAN_COMPOSE_ARGS] },
+    { engine: 'podman', compose: ['podman', 'compose', ...PODMAN_COMPOSE_ARGS] },
+];
+/**
+ * Podman refuses to resolve a short image name such as `mysql:8.0` without a TTY prompt when several
+ * unqualified search registries are configured. API compose files use short names, so point podman
+ * at one registry and turn the prompt off.
+ */
+const PODMAN_REGISTRIES_CONF = `unqualified-search-registries = ["docker.io"]\nshort-name-mode = "disabled"\n`;
+let podmanRegistriesConfPath;
+const writePodmanRegistriesConf = () => {
+    podmanRegistriesConfPath !== null && podmanRegistriesConfPath !== void 0 ? podmanRegistriesConfPath : (podmanRegistriesConfPath = (0, path_1.join)((0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'ethlete-api-')), 'registries.conf'));
+    (0, fs_1.writeFileSync)(podmanRegistriesConfPath, PODMAN_REGISTRIES_CONF, 'utf8');
+    return podmanRegistriesConfPath;
+};
+const composeBinary = (compose) => compose.filter((part) => !part.startsWith('--'));
+exports.composeBinary = composeBinary;
+const canRun = (command, args) => {
+    const result = (0, child_process_1.spawnSync)(command, args, { stdio: 'ignore' });
+    return result.error === undefined && result.status === 0;
+};
+/** Finds the first container tool on this machine that answers `<compose> version`. */
+const resolveComposeTool = (tools = COMPOSE_TOOLS) => tools.find(({ compose }) => {
+    const [binary, ...rest] = (0, exports.composeBinary)(compose);
+    return binary !== undefined && canRun(binary, [...rest, 'version']);
+});
+exports.resolveComposeTool = resolveComposeTool;
+const composeToolNames = (tools = COMPOSE_TOOLS) => tools.map(({ compose }) => (0, exports.composeBinary)(compose).join(' '));
+exports.composeToolNames = composeToolNames;
+const engineEnv = (engine) => engine === 'podman' ? { CONTAINERS_REGISTRIES_CONF: writePodmanRegistriesConf() } : {};
+exports.engineEnv = engineEnv;
+const lanAddress = () => {
+    var _a;
+    return (_a = Object.values((0, os_1.networkInterfaces)())
+        .flat()
+        .find((networkInterface) => (networkInterface === null || networkInterface === void 0 ? void 0 : networkInterface.family) === 'IPv4' && !networkInterface.internal)) === null || _a === void 0 ? void 0 : _a.address;
+};
+exports.lanAddress = lanAddress;
+/** Path of this machine's SSH key, for a compose file that mounts one into the API container. */
+const sshKeyPath = () => [(0, path_1.join)((0, os_1.homedir)(), '.ssh/id_ed25519'), (0, path_1.join)((0, os_1.homedir)(), '.ssh/id_rsa')].find((path) => (0, fs_1.existsSync)(path));
+exports.sshKeyPath = sshKeyPath;
+/** Runs a compose command and captures its stdout. `undefined` when the tool itself failed. */
+const composeOutput = (options) => {
+    var _a;
+    const { tool, cwd, env, args } = options;
+    const [binary, ...prefix] = tool.compose;
+    const result = (0, child_process_1.spawnSync)(binary, [...prefix, ...args], { cwd, env, encoding: 'utf8' });
+    return result.error || result.status !== 0 ? undefined : ((_a = result.stdout) !== null && _a !== void 0 ? _a : '');
+};
+exports.composeOutput = composeOutput;
+/** Container ids of a compose project, or `undefined` when the tool could not answer. */
+const composeContainerIds = (call) => {
+    const stdout = (0, exports.composeOutput)(Object.assign(Object.assign({}, call), { args: ['ps', '-q'] }));
+    return stdout === undefined ? undefined : stdout.split('\n').filter((id) => id.trim() !== '');
+};
+exports.composeContainerIds = composeContainerIds;
+const PUBLISHED_MAPPING = /(\d+)->(\d+)/g;
+const parsePortMappings = (ports) => [...ports.matchAll(PUBLISHED_MAPPING)].map(([, host, container]) => ({
+    host: Number(host),
+    container: Number(container),
+}));
+const PS_FORMAT = '{{.ID}}\t{{.Names}}\t{{.Label "com.docker.compose.service"}}\t{{.Status}}\t{{.Ports}}';
+/** True for a status the engine prints while the container runs. */
+const isRunningStatus = (status) => /^up\b/i.test(status);
+exports.isRunningStatus = isRunningStatus;
+/** Every container the engine knows, with its compose service and published ports. */
+const containerStates = (engine) => {
+    var _a;
+    const result = (0, child_process_1.spawnSync)(engine, ['ps', '-a', '--format', PS_FORMAT], { encoding: 'utf8' });
+    if (result.error || result.status !== 0)
+        return [];
+    return ((_a = result.stdout) !== null && _a !== void 0 ? _a : '')
+        .split('\n')
+        .map((line) => line.split('\t'))
+        .filter((columns) => columns.length >= 5 && columns[0])
+        .map(([id, name, service, status, ports]) => ({
+        id: id !== null && id !== void 0 ? id : '',
+        name: name !== null && name !== void 0 ? name : '',
+        service: service !== null && service !== void 0 ? service : '',
+        status: status !== null && status !== void 0 ? status : '',
+        ports: parsePortMappings(ports !== null && ports !== void 0 ? ports : ''),
+    }));
+};
+exports.containerStates = containerStates;
+//# sourceMappingURL=compose.js.map

package/src/lib/api/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/compose.ts"],"names":[],"mappings":"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"}

package/src/lib/api/definition.d.ts

@@ -0,0 +1,37 @@
+/** One API this repo can run locally. Everything here describes the API's own compose setup. */
+export type ApiDefinition = {
+    /** Directory inside the API checkout that holds the compose file, for example `development`. */
+    composeDir: string;
+    /** Compose services to start. Leave out a service the app does not need, such as a bundled frontend. */
+    services: string[];
+    /** Service that `shell`, `logs` and every `exec` entry run in. */
+    execService: string;
+    /** Published host port, not the port inside the container. Used for the printed url. */
+    port: number;
+    /** File that must exist in `composeDir` before the API can start, for example `.env`. */
+    envFile?: string;
+    /** Command that creates `envFile`, run by `setup` in `composeDir`. */
+    setupCommand?: string;
+    /** External container network to create before the first `up`. */
+    network?: string;
+    /** Example path shown in the error that asks the developer to configure this API's checkout. */
+    examplePath?: string;
+    /** Where to clone this API from when the developer has no checkout of their own. */
+    repoUrl?: string;
+    /** localStorage key the app reads to pick its API. Printed by `--host`. */
+    envKey?: string;
+    /** Extra environment for every compose call. An undefined value is dropped rather than passed as "undefined". */
+    env?: () => Record<string, string | undefined>;
+    /** Named commands run in `execService`, for example `{ install: ['composer', 'install'] }`. */
+    exec?: Record<string, string[]>;
+};
+export type ApiDefinitions = Record<string, ApiDefinition>;
+export declare const BUILT_IN_API_COMMANDS: readonly ["up", "down", "logs", "shell", "clone", "clear", "checkout", "pull", "setup"];
+/** These act on the checkout itself, so they run before `setupCommand` and need no container engine. */
+export declare const GIT_API_COMMANDS: string[];
+/** Whether an exec entry downloads dependencies, which is the only failure the private-dependency hint explains. */
+export declare const installsDependencies: (execCommand: readonly string[]) => boolean;
+/** The exec entry that installs dependencies, so a failure in another entry can point at it. */
+export declare const dependencyInstallCommandName: (api: ApiDefinition) => string | undefined;
+/** `setup` is dropped for an API that declares no `setupCommand`, so nothing lists a command it cannot run. */
+export declare const apiCommandNames: (api: ApiDefinition) => string[];

package/src/lib/api/definition.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCommandNames = exports.dependencyInstallCommandName = exports.installsDependencies = exports.GIT_API_COMMANDS = exports.BUILT_IN_API_COMMANDS = void 0;
+exports.BUILT_IN_API_COMMANDS = [
+    'up',
+    'down',
+    'logs',
+    'shell',
+    'clone',
+    'clear',
+    'checkout',
+    'pull',
+    'setup',
+];
+/** These act on the checkout itself, so they run before `setupCommand` and need no container engine. */
+exports.GIT_API_COMMANDS = ['clone', 'checkout', 'pull'];
+const DEPENDENCY_INSTALLERS = ['composer', 'npm', 'yarn', 'pnpm', 'bun', 'bundle', 'pip', 'pip3'];
+/** Whether an exec entry downloads dependencies, which is the only failure the private-dependency hint explains. */
+const installsDependencies = (execCommand) => { var _a; return DEPENDENCY_INSTALLERS.includes((_a = execCommand[0]) !== null && _a !== void 0 ? _a : ''); };
+exports.installsDependencies = installsDependencies;
+/** The exec entry that installs dependencies, so a failure in another entry can point at it. */
+const dependencyInstallCommandName = (api) => { var _a; return Object.keys((_a = api.exec) !== null && _a !== void 0 ? _a : {}).find((name) => { var _a, _b; return (0, exports.installsDependencies)((_b = (_a = api.exec) === null || _a === void 0 ? void 0 : _a[name]) !== null && _b !== void 0 ? _b : []); }); };
+exports.dependencyInstallCommandName = dependencyInstallCommandName;
+/** `setup` is dropped for an API that declares no `setupCommand`, so nothing lists a command it cannot run. */
+const apiCommandNames = (api) => {
+    var _a;
+    return [
+        ...exports.BUILT_IN_API_COMMANDS.filter((command) => command !== 'setup' || api.setupCommand),
+        ...Object.keys((_a = api.exec) !== null && _a !== void 0 ? _a : {}),
+    ];
+};
+exports.apiCommandNames = apiCommandNames;
+//# sourceMappingURL=definition.js.map

package/src/lib/api/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/definition.ts"],"names":[],"mappings":";;;AA8Ba,QAAA,qBAAqB,GAAG;IACnC,IAAI;IACJ,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,OAAO;IACP,UAAU;IACV,MAAM;IACN,OAAO;CACC,CAAC;AAEX,wGAAwG;AAC3F,QAAA,gBAAgB,GAAa,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AAExE,MAAM,qBAAqB,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAElG,oHAAoH;AAC7G,MAAM,oBAAoB,GAAG,CAAC,WAA8B,EAAE,EAAE,WACrE,OAAA,qBAAqB,CAAC,QAAQ,CAAC,MAAA,WAAW,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC,CAAA,EAAA,CAAC;AAD1C,QAAA,oBAAoB,wBACsB;AAEvD,gGAAgG;AACzF,MAAM,4BAA4B,GAAG,CAAC,GAAkB,EAAE,EAAE,WACjE,OAAA,MAAM,CAAC,IAAI,CAAC,MAAA,GAAG,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,eAAC,OAAA,IAAA,4BAAoB,EAAC,MAAA,MAAA,GAAG,CAAC,IAAI,0CAAG,IAAI,CAAC,mCAAI,EAAE,CAAC,CAAA,EAAA,CAAC,CAAA,EAAA,CAAC;AAD9E,QAAA,4BAA4B,gCACkD;AAE3F,+GAA+G;AACxG,MAAM,eAAe,GAAG,CAAC,GAAkB,EAAE,EAAE;;IAAC,OAAA;QACrD,GAAG,6BAAqB,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC;QACrF,GAAG,MAAM,CAAC,IAAI,CAAC,MAAA,GAAG,CAAC,IAAI,mCAAI,EAAE,CAAC;KAC/B,CAAA;CAAA,CAAC;AAHW,QAAA,eAAe,mBAG1B"}

package/src/lib/api/git.d.ts

@@ -0,0 +1,25 @@
+export type GitResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare const currentBranch: (cwd: string) => string | undefined;
+/** Modified tracked files and untracked files, as git's own porcelain lines. */
+export declare const uncommittedChanges: (cwd: string) => string[];
+export declare const hasUncommittedChanges: (cwd: string) => boolean;
+/** Commits on any local branch that no remote holds, so work is never removed with a checkout. */
+export declare const unpushedCommits: (cwd: string) => string[];
+/** Switches the API checkout to the branch configured for it. Git's own refusal is passed through. */
+export declare const checkoutApiBranch: (options: {
+    repoPath: string;
+    branch: string;
+}) => number;
+/**
+ * Fast-forwards the checked-out branch. `force` throws away local commits and uncommitted tracked
+ * changes on it; untracked files such as `vendor/` and `.env` are never touched.
+ */
+export declare const pullApiBranch: (options: {
+    repoPath: string;
+    expectedBranch?: string;
+    force: boolean;
+}) => number;

package/src/lib/api/git.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pullApiBranch = exports.checkoutApiBranch = exports.unpushedCommits = exports.hasUncommittedChanges = exports.uncommittedChanges = exports.currentBranch = void 0;
+const child_process_1 = require("child_process");
+const git = (cwd, args) => {
+    var _a, _b, _c;
+    const result = (0, child_process_1.spawnSync)('git', args, { cwd, encoding: 'utf8' });
+    return {
+        status: (_a = result.status) !== null && _a !== void 0 ? _a : 1,
+        stdout: ((_b = result.stdout) !== null && _b !== void 0 ? _b : '').trim(),
+        stderr: ((_c = result.stderr) !== null && _c !== void 0 ? _c : '').trim(),
+    };
+};
+const gitInherit = (cwd, args) => { var _a; return (_a = (0, child_process_1.spawnSync)('git', args, { cwd, stdio: 'inherit' }).status) !== null && _a !== void 0 ? _a : 1; };
+const currentBranch = (cwd) => {
+    const result = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    return result.status === 0 ? result.stdout : undefined;
+};
+exports.currentBranch = currentBranch;
+/** Modified tracked files and untracked files, as git's own porcelain lines. */
+const uncommittedChanges = (cwd) => {
+    const { stdout } = git(cwd, ['status', '--porcelain']);
+    return stdout.length > 0 ? stdout.split('\n') : [];
+};
+exports.uncommittedChanges = uncommittedChanges;
+const hasUncommittedChanges = (cwd) => (0, exports.uncommittedChanges)(cwd).length > 0;
+exports.hasUncommittedChanges = hasUncommittedChanges;
+/** Commits on any local branch that no remote holds, so work is never removed with a checkout. */
+const unpushedCommits = (cwd) => {
+    const { status, stdout } = git(cwd, ['log', '--branches', '--not', '--remotes', '--oneline']);
+    return status === 0 && stdout.length > 0 ? stdout.split('\n') : [];
+};
+exports.unpushedCommits = unpushedCommits;
+/** Switches the API checkout to the branch configured for it. Git's own refusal is passed through. */
+const checkoutApiBranch = (options) => {
+    const { repoPath, branch } = options;
+    if ((0, exports.currentBranch)(repoPath) === branch) {
+        console.log(`Already on ${branch}.`);
+        return 0;
+    }
+    return gitInherit(repoPath, ['checkout', branch]);
+};
+exports.checkoutApiBranch = checkoutApiBranch;
+/**
+ * Fast-forwards the checked-out branch. `force` throws away local commits and uncommitted tracked
+ * changes on it; untracked files such as `vendor/` and `.env` are never touched.
+ */
+const pullApiBranch = (options) => {
+    const { repoPath, expectedBranch, force } = options;
+    const branch = (0, exports.currentBranch)(repoPath);
+    if (!branch) {
+        console.error(`${repoPath} is not a git checkout.`);
+        return 1;
+    }
+    if (expectedBranch && branch !== expectedBranch) {
+        console.warn(`On ${branch}, but apiRepoBranches expects ${expectedBranch}. Pulling ${branch}.\n`);
+    }
+    if (!force && (0, exports.hasUncommittedChanges)(repoPath)) {
+        console.error(`${repoPath} has uncommitted changes. Commit or stash them, or pass --force to discard them.`);
+        return 1;
+    }
+    const fetched = gitInherit(repoPath, ['fetch', 'origin', branch]);
+    if (fetched !== 0)
+        return fetched;
+    if (!force)
+        return gitInherit(repoPath, ['merge', '--ff-only', `origin/${branch}`]);
+    console.log(`Discarding local commits and tracked changes on ${branch}.`);
+    return gitInherit(repoPath, ['reset', '--hard', `origin/${branch}`]);
+};
+exports.pullApiBranch = pullApiBranch;
+//# sourceMappingURL=git.js.map

package/src/lib/api/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/git.ts"],"names":[],"mappings":"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"}

package/src/lib/api/help.d.ts

@@ -0,0 +1,11 @@
+import { ApiDefinition, ApiDefinitions } from './definition';
+/** The help text for `et api`, listing the built-in commands and what each API adds to them. */
+export declare const apiHelp: (apis: ApiDefinitions, invocation: string) => string;
+/** The help text for one API: every command it accepts, what each one runs, and where its files are. */
+export declare const singleApiHelp: (options: {
+    name: string;
+    api: ApiDefinition;
+    invocation: string;
+    /** Where the checkout is, or what is wrong with it. */
+    checkout?: string;
+}) => string;