@ethlete/cli 2.1.0-next.4 → 2.1.0-next.6

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @ethlete/cli
 
+## 2.1.0-next.6
+
+### Minor Changes
+
+- [`a1c489e`](https://github.com/ethlete-io/ethdk/commit/a1c489e0a1da4b479fd6e47743dec4c1bad0152f) Thanks [@TomTomB](https://github.com/TomTomB)! - `et api up` now refuses a port another program holds and prints a per-service state table instead of
+  the engine's output. New `et api clear` removes a managed checkout, and offers to take its containers down first.
+
+- [`12dcd51`](https://github.com/ethlete-io/ethdk/commit/12dcd5118ca8d2089cc3e9379efe4e9d0502a0f6) Thanks [@TomTomB](https://github.com/TomTomB)! - Every `et api` command now takes a comma-separated list of names, so `et api up hub,platform` starts
+  both APIs.
+
+- [`0e060b2`](https://github.com/ethlete-io/ethdk/commit/0e060b28436e9444726a35a93264a046242e348e) Thanks [@TomTomB](https://github.com/TomTomB)! - `et api help <name>` now answers for one API: the commands it accepts, what each one runs, its url
+  and services, and the state of its checkout. `--help` after a known API name prints the same text.
+
+- [`0e060b2`](https://github.com/ethlete-io/ethdk/commit/0e060b28436e9444726a35a93264a046242e348e) Thanks [@TomTomB](https://github.com/TomTomB)! - `et api` now runs an API's `setupCommand` itself: `et api setup <name>` on its own, or as an offer
+  when a command finds the `envFile` missing. `--setup` accepts that offer without the question.
+
+- [`c3dd7c3`](https://github.com/ethlete-io/ethdk/commit/c3dd7c3d7e0e2a060e081c7fe820f9774537418b) Thanks [@TomTomB](https://github.com/TomTomB)! - `et auth <token>` writes a GitLab token into composer's `auth.json`, which the API containers mount. It asks the host whether the token can download code before it writes anything.
+
+### Patch Changes
+
+- [`0e060b2`](https://github.com/ethlete-io/ethdk/commit/0e060b28436e9444726a35a93264a046242e348e) Thanks [@TomTomB](https://github.com/TomTomB)! - An unknown API name in `et api` now names the closest match and the APIs there are, in place of the
+  whole help text. An unknown command suggests the closest command the same way.
+
+- [`c3dd7c3`](https://github.com/ethlete-io/ethdk/commit/c3dd7c3d7e0e2a060e081c7fe820f9774537418b) Thanks [@TomTomB](https://github.com/TomTomB)! - A failing `et api` exec command no longer always blames a private dependency. That hint is kept for a command that installs dependencies; any other one suggests running the install command first.
+
+- [`0e060b2`](https://github.com/ethlete-io/ethdk/commit/0e060b28436e9444726a35a93264a046242e348e) Thanks [@TomTomB](https://github.com/TomTomB)! - `et api setup` keeps the setup command's own output back and prints one line for the result. The output is only shown when the command fails, so a checkout's advice about its Makefile no longer competes with the CLI.
+
+- [`0e060b2`](https://github.com/ethlete-io/ethdk/commit/0e060b28436e9444726a35a93264a046242e348e) Thanks [@TomTomB](https://github.com/TomTomB)! - Every `et` message now names a command the reader can type, for example `yarn api` or `npx et api`,
+  in place of a bare `et`. `et doctor` names the `et api` command that fixes each problem.
+
+## 2.1.0-next.5
+
+### Minor Changes
+
+- [`612d735`](https://github.com/ethlete-io/ethdk/commit/612d73563e1689bbfcf948d26ebe7c59d2420781) Thanks [@TomTomB](https://github.com/TomTomB)! - `et api` now clones a missing API checkout from a `repoUrl` in `ethlete.apis.js`, making
+  `apiRepoPaths` optional. `runApiCommand` is async as a result.
+
+- [#3072](https://github.com/ethlete-io/ethdk/pull/3072) [`4bbbb51`](https://github.com/ethlete-io/ethdk/commit/4bbbb5167989a1c3ef2ffeba09fcfd18ba953fba) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add `et doctor` to check this machine's config, container engine and API checkouts, `et api
+checkout` and `et api pull` (with `--force`) to move an API checkout to the branch it should be on,
+  and `et api --help`.
+
+### Patch Changes
+
+- [#3072](https://github.com/ethlete-io/ethdk/pull/3072) [`0fd8ba3`](https://github.com/ethlete-io/ethdk/commit/0fd8ba3dd61cc78409c397c8180f0a675282642f) Thanks [@github-actions](https://github.com/apps/github-actions)! - `et doctor` now says when a directory has neither config file rather than reporting no problems.
+
 ## 2.1.0-next.4
 
 ### Minor Changes

package/README.md

@@ -16,22 +16,61 @@ yarn et release
 
 Turns pending changesets into a tagged, pushed release commit (version → tag → commit → push).
 
+## `et auth`
+
+Writes a GitLab token into composer's `auth.json`, so a private PHP dependency can be downloaded.
+The compose file of each API mounts `$HOME/.composer` into its container, so this is the token the
+composer inside the container reads.
+
+```bash
+yarn et auth glpat-xxxxxxxxxxxxxxxxxxxx                     # the host comes from ethlete.apis.js
+yarn et auth gitlab.example.com glpat-xxxxxxxxxxxxxxxxxxxx  # name it when more than one is in use
+```
+
+The token is checked against the host first: once for the token itself, and once by downloading one
+byte of a project archive. A token that can read the API but not fetch code answers `403` there, and
+nothing is written. `--force` writes it anyway.
+
 ## `et api`
 
 Runs the API an app in this repo talks to, from a checkout on your own machine.
 
 ```bash
-yarn et api up hub          # start the containers
-yarn et api down hub        # stop them
-yarn et api logs hub        # follow the API's log
-yarn et api shell hub       # a shell in the API container
-yarn et api install hub     # an entry from that API's own "exec" map
-yarn et api up hub --host   # also print the address other devices can reach
+yarn et api --help              # the commands, the APIs and what each one accepts
+yarn et api help hub            # what hub accepts, and where its checkout is
+yarn et api up hub              # start the containers
+yarn et api up hub,platform     # the same, for both APIs
+yarn et api down hub            # stop them
+yarn et api logs hub            # follow the API's log
+yarn et api shell hub           # a shell in the API container
+yarn et api install hub         # an entry from that API's own "exec" map
+yarn et api up hub --host       # also print the address other devices can reach
+yarn et api checkout hub        # switch the checkout to the branch apiRepoBranches names
+yarn et api pull hub            # fetch and fast-forward the checked-out branch
+yarn et api pull hub --force    # the same, discarding local commits and tracked changes
+yarn et api clone hub           # clone the API into .ethlete/hub
+yarn et api setup hub           # run the API's own setupCommand, which writes its .env
 ```
 
+Every command takes a comma-separated list of names, and acts on each API in turn.
+
+`checkout`, `pull` and `setup` act on the checkout itself, so they work before the API has an `.env`
+and need no container engine. `pull` refuses to run on a checkout with uncommitted changes unless you pass
+`--force`. `--force` resets the branch to its remote and throws away local commits and tracked
+changes; it never touches untracked or ignored files, so a `vendor/` directory or a `.env` survives.
+
 The first container tool that answers is used, in this order: `docker compose`,
 `container compose`, `podman-compose`, `podman compose`.
 
+## `et doctor`
+
+```bash
+yarn et doctor
+```
+
+Checks `ethlete.config.local.json`, reports the container engine it would use, and resolves every
+API declared in `ethlete.apis.js`. It exits non-zero when it finds a problem, so CI can run it.
+
 ### Declaring the APIs
 
 `ethlete.apis.js` at the repo root describes each API's compose setup. It is a module rather
@@ -64,8 +103,10 @@ Adding an API is an entry in this map. Nothing else changes.
 
 ### Where the checkouts live
 
-The paths differ per machine, so they live in a gitignored `ethlete.config.local.json` at the
-repo root. `@ethlete/agent-rules` reads the same file, so its skills and `et` agree on where a
+Give an API a `repoUrl` and `et api` clones it into a gitignored `.ethlete/<name>` when you have no
+checkout of your own, asking first (or use `--clone`). To point at a checkout you already have - which
+you want whenever you work in the backend, since compose mounts it into the container - set
+`apiRepoPaths` in a gitignored `ethlete.config.local.json` at the repo root. `@ethlete/agent-rules` reads the same file, so its skills and `et` agree on where a
 checkout is:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/cli",
-  "version": "2.1.0-next.4",
+  "version": "2.1.0-next.6",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/index.js

@@ -2,12 +2,40 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const lib_1 = require("./lib");
-const USAGE = `et — Ethlete repo tooling
-
-  et release            Turn pending changesets into a tagged, pushed release commit
-  et api <cmd> <api>    Run an API from this repo's ethlete.apis.js locally
-                        (up, down, logs, shell, plus that API's own exec entries)
-`;
+const USAGE_ROWS = [
+    { subcommand: 'release', args: '', lines: ['Turn pending changesets into a tagged, pushed release commit'] },
+    {
+        subcommand: 'api',
+        args: ' <cmd> <api>',
+        lines: [
+            "Run an API from this repo's ethlete.apis.js locally",
+            "(up, down, logs, shell, setup, plus that API's own exec entries)",
+        ],
+    },
+    {
+        subcommand: 'auth',
+        args: ' [host] <token>',
+        lines: [
+            "Write a GitLab token into composer's auth.json, which the",
+            'API containers mount, after checking it can download code',
+        ],
+    },
+    {
+        subcommand: 'doctor',
+        args: '',
+        lines: ["Check this machine's ethlete.config.local.json, container engine", 'and every API checkout'],
+    },
+];
+const usage = (root) => {
+    const rows = USAGE_ROWS.map((row) => (Object.assign(Object.assign({}, row), { command: `${(0, lib_1.repoInvocation)({ root, subcommand: row.subcommand })}${row.args}` })));
+    const width = Math.max(...rows.map((row) => row.command.length));
+    return [
+        'et — Ethlete repo tooling',
+        '',
+        ...rows.flatMap((row) => row.lines.map((line, index) => `  ${(index === 0 ? row.command : '').padEnd(width)}  ${line}`)),
+        '',
+    ].join('\n');
+};
 const cli = (args) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
     switch (args[0]) {
         case 'release':
@@ -16,9 +44,25 @@ const cli = (args) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
             yield (0, lib_1.release)(args.join('=').split('='));
             return 0;
         case 'api':
-            return (0, lib_1.apiCommand)({ root: process.cwd(), argv: args.slice(1) });
+            return (0, lib_1.apiCommand)({
+                root: process.cwd(),
+                argv: args.slice(1),
+                invocation: (0, lib_1.repoInvocation)({ root: process.cwd(), subcommand: 'api' }),
+            });
+        case 'auth':
+            return (0, lib_1.authCommand)({
+                root: process.cwd(),
+                argv: args.slice(1),
+                invocation: (0, lib_1.repoInvocation)({ root: process.cwd(), subcommand: 'auth' }),
+            });
+        case 'doctor':
+            // Every fix it names is an `et api` command, so it needs that script rather than its own.
+            return (0, lib_1.doctorCommand)({
+                root: process.cwd(),
+                apiInvocation: (0, lib_1.repoInvocation)({ root: process.cwd(), subcommand: 'api' }),
+            });
         default:
-            console.log(USAGE);
+            console.log(usage(process.cwd()));
             return args[0] === undefined || args[0] === '--help' || args[0] === '-h' ? 0 : 1;
     }
 });

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/cli/src/index.ts"],"names":[],"mappings":";;;AAAA,+BAA4C;AAE5C,MAAM,KAAK,GAAG;;;;;CAKb,CAAC;AAEF,MAAM,GAAG,GAAG,CAAO,IAAc,EAAmB,EAAE;IACpD,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,KAAK,SAAS;YACZ,0FAA0F;YAC1F,wDAAwD;YACxD,MAAM,IAAA,aAAO,EAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAEzC,OAAO,CAAC,CAAC;QAEX,KAAK,KAAK;YACR,OAAO,IAAA,gBAAU,EAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAElE;YACE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAEnB,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;AACH,CAAC,CAAA,CAAC;AAEF,gDAAsB;AAEtB,oFAAoF;AACpF,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACvB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC9D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/cli/src/index.ts"],"names":[],"mappings":"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"}

package/src/lib/api/api-command.d.ts

@@ -1,4 +1,5 @@
-export declare const apiCommand: ({ root, argv }: {
+export declare const apiCommand: ({ root, argv, invocation }: {
     root: string;
     argv: string[];
-}) => number;
+    invocation?: string;
+}) => 1 | Promise<number>;

package/src/lib/api/api-command.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiCommand = void 0;
 const load_definitions_1 = require("./load-definitions");
 const run_1 = require("./run");
-const apiCommand = ({ root, argv }) => {
+const apiCommand = ({ root, argv, invocation }) => {
     const { found, apis } = (0, load_definitions_1.loadApiDefinitions)(root);
     if (!found) {
         console.error(`No API definitions found. Create ${load_definitions_1.API_DEFINITIONS_FILE_NAMES[0]} in the repo root:\n\n` +
@@ -21,7 +21,7 @@ const apiCommand = ({ root, argv }) => {
             `  };`);
         return 1;
     }
-    return (0, run_1.runApiCommand)({ apis, argv, root });
+    return (0, run_1.runApiCommand)({ apis, argv, root, invocation });
 };
 exports.apiCommand = apiCommand;
 //# sourceMappingURL=api-command.js.map

package/src/lib/api/api-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-command.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/api-command.ts"],"names":[],"mappings":";;;AAAA,yDAAoF;AACpF,+BAAsC;AAE/B,MAAM,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAoC,EAAE,EAAE;IAC7E,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAA,qCAAkB,EAAC,IAAI,CAAC,CAAC;IAEjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CACX,oCAAoC,6CAA0B,CAAC,CAAC,CAAC,wBAAwB;YACvF,uDAAuD;YACvD,wBAAwB;YACxB,cAAc;YACd,oCAAoC;YACpC,wCAAwC;YACxC,6BAA6B;YAC7B,qBAAqB;YACrB,0BAA0B;YAC1B,qCAAqC;YACrC,qDAAqD;YACrD,UAAU;YACV,MAAM,CACT,CAAC;QAEF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,IAAA,mBAAa,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC,CAAC;AAxBW,QAAA,UAAU,cAwBrB"}
+{"version":3,"file":"api-command.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/api-command.ts"],"names":[],"mappings":";;;AAAA,yDAAoF;AACpF,+BAAsC;AAE/B,MAAM,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAyD,EAAE,EAAE;IAC9G,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAA,qCAAkB,EAAC,IAAI,CAAC,CAAC;IAEjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CACX,oCAAoC,6CAA0B,CAAC,CAAC,CAAC,wBAAwB;YACvF,uDAAuD;YACvD,wBAAwB;YACxB,cAAc;YACd,oCAAoC;YACpC,wCAAwC;YACxC,6BAA6B;YAC7B,qBAAqB;YACrB,0BAA0B;YAC1B,qCAAqC;YACrC,qDAAqD;YACrD,UAAU;YACV,MAAM,CACT,CAAC;QAEF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,IAAA,mBAAa,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;AACzD,CAAC,CAAC;AAxBW,QAAA,UAAU,cAwBrB"}

package/src/lib/api/auth-hint.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export declare const printPrivateDependencyHint: (options: {
+    repoHost?: string;
+}) => void;
+/** The host of a git url, for naming it in the hint. Undefined when the url has no host. */
+export declare const gitUrlHost: (repoUrl: string) => string | undefined;
+/** The `group/project` part of a git url, for addressing the project in a host's own API. */
+export declare const gitUrlProjectPath: (repoUrl: string) => string | undefined;

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitUrlProjectPath = 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 `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,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":";;;;AAAA,2BAA4B;AAC5B,oCAAmC;AAEnC,+BAA4D;AAC5D,yDAA6E;AAc7E,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,uFAAuF;AACvF,MAAM,MAAM,GAAG,CAAC,KAAe,EAAE,EAAE,CACjC;IACE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACxD,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG,UAAU,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAClF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAaf;;;GAGG;AACI,MAAM,YAAY,GAAG,CAAC,OAA4B,EAAoB,EAAE;IAC7E,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAExE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAEvB,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QAEpB,MAAM,QAAQ,GAAG,IAAA,qCAAkB,EAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAExE,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QAE5B,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC;QACpD,MAAM,OAAO,GAAG,IAAA,sCAAmB,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEhD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;YACzB,OAAO;gBACL;oBACE,IAAI;oBACJ,QAAQ;oBACR,WAAW;oBACX,aAAa,EAAE,KAAK;oBACpB,QAAQ,EAAE;wBACR,GAAG,QAAQ,sCAAsC,UAAU,YAAY;4BACrE,4CAA4C,IAAI,SAAS;qBAC5D;iBACF;aACF,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,IAAA,wBAAkB,EAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAA,qBAAe,EAAC,QAAQ,CAAC,CAAC;QAE3C,OAAO;YACL;gBACE,IAAI;gBACJ,QAAQ;gBACR,WAAW;gBACX,aAAa,EAAE,aAAa,CAAC,WAAW,CAAC;gBACzC,QAAQ,EAAE;oBACR,GAAG,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;wBAC9B,CAAC,CAAC;4BACE,GAAG,QAAQ,gCAAgC,MAAM,CAAC,OAAO,CAAC,MAAM;gCAC9D,4CAA4C;yBAC/C;wBACH,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;wBAC/B,CAAC,CAAC;4BACE,GAAG,QAAQ,oCAAoC,MAAM,CAAC,QAAQ,CAAC,MAAM;gCACnE,0CAA0C;yBAC7C;wBACH,CAAC,CAAC,EAAE,CAAC;iBACR;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAxDW,QAAA,YAAY,gBAwDvB;AAOF;;;GAGG;AACI,MAAM,iBAAiB,GAAG,CAAO,OAAwB,EAAmB,EAAE;IACnF,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,OAAO,GAAG,IAAA,oBAAY,EAAC,OAAO,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IAE1E,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,OAAO,EAAE,CAAC;QACnC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE1C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,UAAU,WAAW,CAAC,CAAC;QAC/F,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC/F,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,IAAA,eAAO,EAAC;QAC7B,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,OAAO,2BAA2B,KAAK,EAAE,CAAC,CAAC,CAAC,oBAAoB,KAAK,EAAE;QACnH,QAAQ,EACN,OAAO,CAAC,MAAM,GAAG,CAAC;YAChB,CAAC,CAAC,QAAQ,OAAO,oBAAoB,SAAS,GAAG;YACjD,CAAC,CAAC,UAAU,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC/D,IAAI,EACF,OAAO,CAAC,MAAM,GAAG,CAAC;YAChB,CAAC,CAAC,wDAAwD,UAAU,SAAS,OAAO,mBAAmB;gBACrG,uBAAuB;YACzB,CAAC,CAAC,kFAAkF;QACxF,aAAa,EAAE,KAAK;KACrB,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IAExB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,SAAS,EAAE,CAAC;QACvE,IAAI,aAAa,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,kBAAkB,IAAI,aAAa,QAAQ,SAAS,CAAC,CAAC;YACpE,MAAM,IAAI,CAAC,CAAC;YAEZ,SAAS;QACX,CAAC;QAED,IAAA,WAAM,EAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,WAAW,QAAQ,UAAU,UAAU,UAAU,IAAI,mBAAmB,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC,CAAA,CAAC;AAvDW,QAAA,iBAAiB,qBAuD5B"}

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

@@ -15,3 +15,32 @@ export declare const engineEnv: (engine: string) => {
 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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sshKeyPath = exports.lanAddress = exports.engineEnv = exports.composeToolNames = exports.resolveComposeTool = exports.composeBinary = void 0;
+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");
@@ -55,4 +55,47 @@ 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