@ethlete/cli 2.1.0-next.3 → 2.1.0-next.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @ethlete/cli
 
+## 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
+
+- [`b6fe4be`](https://github.com/ethlete-io/ethdk/commit/b6fe4beae010aaa2e0e367d636f6759442983395) Thanks [@TomTomB](https://github.com/TomTomB)! - Add `et api` to run an app's backend from a local checkout, declared in `ethlete.apis.js`. The new
+  `ethlete.config.local.json` says where the sibling checkouts on this machine live.
+
 ## 2.1.0-next.3
 
 ### Minor Changes

package/README.md

@@ -1,11 +1,108 @@
-# cli
+# @ethlete/cli
 
-This library was generated with [Nx](https://nx.dev).
+Repo tooling - installs the `et` binary.
 
-## Building
+## Installation
 
-Run `nx build cli` to build the library.
+```bash
+yarn add --dev @ethlete/cli
+```
 
-## Running unit tests
+## `et release`
 
-Run `nx test cli` to execute the unit tests via [Jest](https://jestjs.io).
+```bash
+yarn et release
+```
+
+Turns pending changesets into a tagged, pushed release commit (version → tag → commit → push).
+
+## `et api`
+
+Runs the API an app in this repo talks to, from a checkout on your own machine.
+
+```bash
+yarn et api --help              # the commands, the APIs and what each one accepts
+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 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
+```
+
+`checkout` and `pull` act on the checkout itself, so they work before `make setup` has run 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
+than JSON because `env` is a function:
+
+```js
+const { sshKeyPath } = require('@ethlete/cli');
+
+module.exports = {
+  hub: {
+    composeDir: 'development',
+    services: ['app', 'database', 'mailhog'],
+    execService: 'app',
+    port: 8040,
+    envFile: '.env',
+    setupCommand: 'make setup',
+    network: 'shared-fut',
+    envKey: 'hubApiEnv',
+    examplePath: '../fut-hub-backend',
+    env: () => ({ SSH_PRIVATE_KEY: sshKeyPath() }),
+    exec: {
+      install: ['composer', 'install'],
+      'reset-db': ['make', 'reset-db-with-dev-fixtures'],
+    },
+  },
+};
+```
+
+Adding an API is an entry in this map. Nothing else changes.
+
+### Where the checkouts live
+
+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
+{
+  "sdkSourcePath": "/absolute/path/to/ethlete-sdk",
+  "apiRepoPaths": { "hub": "../fut-hub-backend", "*": "../shared-backend" },
+  "apiRepoBranches": { "hub": "develop", "*": "main" }
+}
+```
+
+Matching is exact; `"*"` is an explicit shared fallback. A relative path resolves from the repo
+root. These keys used to live in `ethlete-agents.config.local.json`, which is still read as a
+fallback with a warning. Add `ethlete.config.local.json` to your `.gitignore`.
+
+## Documentation
+
+Full command reference on the docs site:
+
+- [Overview & usage](https://ethlete-sdk-docs.web.app/cli/)

package/package.json

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

package/src/index.d.ts

@@ -1 +1 @@
-export {};
+export * from './lib';

package/src/index.js

@@ -2,19 +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)
+  et doctor             Check this machine's ethlete.config.local.json, container engine
+                        and every API checkout
+`;
 const cli = (args) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
-    const cliFunctionArg = args[0];
-    switch (cliFunctionArg) {
+    switch (args[0]) {
         case 'release':
-            yield (0, lib_1.release)(args);
-            break;
+            // `release` reads its flags from a list that was split on "=" before this switch existed.
+            // Keep that shape here so its own parsing is untouched.
+            yield (0, lib_1.release)(args.join('=').split('='));
+            return 0;
+        case 'api':
+            return (0, lib_1.apiCommand)({ root: process.cwd(), argv: args.slice(1) });
+        case 'doctor':
+            return (0, lib_1.doctorCommand)({ root: process.cwd() });
         default:
-            console.log(`No command found named ${cliFunctionArg}. Available commands are: release`);
-            break;
+            console.log(USAGE);
+            return args[0] === undefined || args[0] === '--help' || args[0] === '-h' ? 0 : 1;
     }
 });
-// Get the command line arguments and normalize them
-const args = process.argv.slice(2).join('=').split('=');
-cli(args);
-// Burst cache
+tslib_1.__exportStar(require("./lib"), exports);
+// Guarded so the package can also be imported as a library without running the CLI.
+if (require.main === module) {
+    cli(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/cli/src/index.ts"],"names":[],"mappings":";;;AAAA,+BAAgC;AAEhC,MAAM,GAAG,GAAG,CAAO,IAAc,EAAE,EAAE;IACnC,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAE/B,QAAQ,cAAc,EAAE,CAAC;QACvB,KAAK,SAAS;YACZ,MAAM,IAAA,aAAO,EAAC,IAAI,CAAC,CAAC;YACpB,MAAM;QAER;YACE,OAAO,CAAC,GAAG,CAAC,0BAA0B,cAAc,mCAAmC,CAAC,CAAC;YACzF,MAAM;IACV,CAAC;AACH,CAAC,CAAA,CAAC;AAEF,oDAAoD;AACpD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAExD,GAAG,CAAC,IAAI,CAAC,CAAC;AAEV,cAAc"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/cli/src/index.ts"],"names":[],"mappings":";;;AAAA,+BAA2D;AAE3D,MAAM,KAAK,GAAG;;;;;;;CAOb,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,KAAK,QAAQ;YACX,OAAO,IAAA,mBAAa,EAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAEhD;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"}

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

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

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

@@ -0,0 +1,27 @@
+"use strict";
+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 { 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` +
+            `  const { sshKeyPath } = require('@ethlete/cli');\n\n` +
+            `  module.exports = {\n` +
+            `    hub: {\n` +
+            `      composeDir: 'development',\n` +
+            `      services: ['app', 'database'],\n` +
+            `      execService: 'app',\n` +
+            `      port: 8040,\n` +
+            `      envFile: '.env',\n` +
+            `      setupCommand: 'make setup',\n` +
+            `      exec: { install: ['composer', 'install'] },\n` +
+            `    },\n` +
+            `  };`);
+        return 1;
+    }
+    return (0, run_1.runApiCommand)({ apis, argv, root });
+};
+exports.apiCommand = apiCommand;
+//# sourceMappingURL=api-command.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,9 @@
+/**
+ * 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;

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+//# 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"}

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,17 @@
+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;

package/src/lib/api/compose.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+//# 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,32 @@
+/** 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`. Named in the error when the file is missing. */
+    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", "checkout", "pull"];
+/** These act on the checkout itself, so they run before `make setup` and need no container engine. */
+export declare const GIT_API_COMMANDS: string[];
+export declare const apiCommandNames: (api: ApiDefinition) => string[];

package/src/lib/api/definition.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCommandNames = exports.GIT_API_COMMANDS = exports.BUILT_IN_API_COMMANDS = void 0;
+exports.BUILT_IN_API_COMMANDS = ['up', 'down', 'logs', 'shell', 'clone', 'checkout', 'pull'];
+/** These act on the checkout itself, so they run before `make setup` and need no container engine. */
+exports.GIT_API_COMMANDS = ['clone', 'checkout', 'pull'];
+const apiCommandNames = (api) => { var _a; return [...exports.BUILT_IN_API_COMMANDS, ...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,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAE3G,sGAAsG;AACzF,QAAA,gBAAgB,GAAa,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;AAEjE,MAAM,eAAe,GAAG,CAAC,GAAkB,EAAE,EAAE,WAAC,OAAA,CAAC,GAAG,6BAAqB,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,MAAA,GAAG,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAC,CAAA,EAAA,CAAC;AAArG,QAAA,eAAe,mBAAsF"}

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

@@ -0,0 +1,21 @@
+export type GitResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare const currentBranch: (cwd: string) => string | undefined;
+export declare const hasUncommittedChanges: (cwd: string) => boolean;
+/** 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,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pullApiBranch = exports.checkoutApiBranch = exports.hasUncommittedChanges = 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;
+const hasUncommittedChanges = (cwd) => git(cwd, ['status', '--porcelain']).stdout.length > 0;
+exports.hasUncommittedChanges = hasUncommittedChanges;
+/** 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,3 @@
+import { 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;

package/src/lib/api/help.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiHelp = void 0;
+const definition_1 = require("./definition");
+const BUILT_IN_DESCRIPTIONS = {
+    up: 'Start the containers of the API',
+    down: 'Stop them',
+    logs: 'Follow the log of the API container',
+    shell: 'Open a shell in the API container',
+    clone: 'Clone the API into .ethlete/<name> from its repoUrl',
+    checkout: 'Switch the checkout to the branch apiRepoBranches names',
+    pull: 'Fetch and fast-forward the checked-out branch',
+};
+const pad = (text, width) => text.padEnd(width);
+/** The help text for `et api`, listing the built-in commands and what each API adds to them. */
+const apiHelp = (apis, invocation) => {
+    const entries = Object.entries(apis);
+    const width = Math.max(8, ...entries.map(([name]) => name.length));
+    const apiLines = entries.map(([name, api]) => `  ${pad(name, width)}  ${(0, definition_1.apiCommandNames)(api).join(', ')}`);
+    const execNames = [...new Set(entries.flatMap(([, api]) => { var _a; return Object.keys((_a = api.exec) !== null && _a !== void 0 ? _a : {}); }))];
+    return [
+        `Usage: ${invocation} <command> <api> [--host]`,
+        '',
+        'Commands',
+        ...definition_1.BUILT_IN_API_COMMANDS.map((command) => `  ${pad(command, 8)}  ${BUILT_IN_DESCRIPTIONS[command]}`),
+        ...execNames.map((command) => `  ${pad(command, 8)}  Declared by the API itself`),
+        '',
+        'APIs',
+        ...(apiLines.length > 0 ? apiLines : ['  none — declare them in ethlete.apis.js']),
+        '',
+        'Options',
+        `  ${pad('--host', 8)}  Also print the address another device on this network can use`,
+        `  ${pad('--force', 8)}  With pull: discard local commits and tracked changes on the branch`,
+        `  ${pad('--clone', 8)}  Clone a missing checkout without asking first`,
+        `  ${pad('--help', 8)}  Show this text`,
+    ].join('\n');
+};
+exports.apiHelp = apiHelp;
+//# sourceMappingURL=help.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../../../../libs/cli/src/lib/api/help.ts"],"names":[],"mappings":";;;AAAA,6CAAsF;AAEtF,MAAM,qBAAqB,GAA2D;IACpF,EAAE,EAAE,iCAAiC;IACrC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,qCAAqC;IAC3C,KAAK,EAAE,mCAAmC;IAC1C,KAAK,EAAE,qDAAqD;IAC5D,QAAQ,EAAE,yDAAyD;IACnE,IAAI,EAAE,+CAA+C;CACtD,CAAC;AAEF,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEhE,gGAAgG;AACzF,MAAM,OAAO,GAAG,CAAC,IAAoB,EAAE,UAAkB,EAAE,EAAE;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAEnE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAA,4BAAe,EAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAE3G,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,WAAC,OAAA,MAAM,CAAC,IAAI,CAAC,MAAA,GAAG,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAA,EAAA,CAAC,CAAC,CAAC,CAAC;IAE1F,OAAO;QACL,UAAU,UAAU,2BAA2B;QAC/C,EAAE;QACF,UAAU;QACV,GAAG,kCAAqB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACpG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,8BAA8B,CAAC;QACjF,EAAE;QACF,MAAM;QACN,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC;QAClF,EAAE;QACF,SAAS;QACT,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,iEAAiE;QACtF,KAAK,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,sEAAsE;QAC5F,KAAK,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,iDAAiD;QACvE,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,kBAAkB;KACxC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC,CAAC;AAxBW,QAAA,OAAO,WAwBlB"}