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

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @ethlete/cli
 
+## 2.1.0-next.10
+
+### Patch Changes
+
+- A design call now lists its drawings as `variants` in `variant-<key>.ts` files, and `et design check` takes `--variant`; the old `options` key and `--option` flag are gone.
+
+## 2.1.0-next.9
+
+### Minor Changes
+
+- `et update` now writes the new range into every `package.json` in the repo, not only the root one, and refuses a dist tag that points at an older version than the repo is on.
+- `et design [checkout]` serves the design page of any repository that keeps a `.ethlete/design`
+  folder, and `et design check` says why a call does not render.
+
+### Patch Changes
+
+- `et release` now works with Changesets 3 and aborts when there are no pending changesets.
+- `et design` now rules a drawing with its own Tailwind 4 pipeline, so a repository on Tailwind 3, or none at all, can hold design calls.
+- `et design check --call` now reports `NO BROWSER` when neither the checkout nor the package
+  resolves `playwright`, instead of throwing the module loader's own error.
+
+## 2.1.0-next.8
+
+### Minor Changes
+
+- [#3075](https://github.com/ethlete-io/ethdk/pull/3075) [`004c32d`](https://github.com/ethlete-io/ethdk/commit/004c32d0ada3d7862947843dd6e8b204876160fe) Thanks [@github-actions](https://github.com/apps/github-actions)! - `doctorCommand` accepts an optional `composeTools` override for the container-engine check.
+
+- [#3075](https://github.com/ethlete-io/ethdk/pull/3075) [`1d38e7e`](https://github.com/ethlete-io/ethdk/commit/1d38e7e0a025769f065d8ca7d506cb75ad89139a) Thanks [@github-actions](https://github.com/apps/github-actions)! - `et update` moves the `@ethlete/*` packages to a newer version, runs the codemods those versions
+  declare in their own `migrations.json`, and reports what needs a decision or an agent.
+
+## 2.1.0-next.7
+
+### Patch Changes
+
+- [#3074](https://github.com/ethlete-io/ethdk/pull/3074) [`63a528a`](https://github.com/ethlete-io/ethdk/commit/63a528a0ab1b1e7163e71c1cf5f65415bdda32d9) Thanks [@github-actions](https://github.com/apps/github-actions)! - `et auth` now takes a host written as a url, and asks before it replaces a token `auth.json`
+  already holds for that host.
+
+## 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
+
+- [`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
+
+- [`edea44b`](https://github.com/ethlete-io/ethdk/commit/edea44bf1c494420f02b545202f4b24db9a6395c) Thanks [@TomTomB](https://github.com/TomTomB)! - Update to angular 22
+
 ## 2.0.1-next.2
 
 ### Patch Changes

package/README.md

@@ -1,11 +1,178 @@
-# 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 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 host may be written as a url. Only its host name is used.
+
+The token is checked against the host first: once for the token itself, and once with the request
+`git clone` makes for a private dependency. A token that can read the API but not fetch code answers
+`403` there, and nothing is written. A token the file already holds for that host is replaced only
+after a question. `--force` skips both.
+
+## `et update`
+
+Moves this repo's `@ethlete/*` dependencies to a newer version and runs the migrations those versions
+ship.
+
+```bash
+yarn et update --check                    # what would change; exits 1 while an update is pending
+yarn et update                            # bump, install, run the codemods, report the rest
+yarn et update core                       # only @ethlete/core
+yarn et update --tag latest               # leave the prerelease line
+yarn et update core --to 5.0.0-next.55    # an exact version for the package you name
+yarn et update --continue                 # finish a run that stopped
+yarn et update --ai                       # hand every agent-assisted task to an agent
+```
+
+The target follows the dist tag the installed version is on, so a repo on a `-next` prerelease stays
+on `next`. The working tree must be clean, because the codemods rewrite files; `--force` skips that
+check.
+
+The install runs before the migrations are read, because the migrations of a version ship inside that
+version. A run that stops leaves `.ethlete/update/pending.json` behind, and `--continue` picks it up -
+starting over would skip every migration the stopped run had not reached.
+
+Everything a codemod cannot decide is written to `.ethlete/update`: `tasks.md` for you, `tasks.json`
+for an agent, and one file per task holding the instructions the package ships. A task is `manual` (it
+needs a decision), `assisted` (written as a prompt for an agent) or `unsupported` (a codemod this repo
+has no Nx to run, with the command to run it by hand).
+
+`--ai` hands each assisted task to the command in `updateAgentCommand` in
+`ethlete.config.local.json`, one run per task. No agent is detected automatically.
+
+A package declares its migrations in `migrations.json` at its own root, pointed at from `package.json`
+with `"ethlete": { "migrations": "./migrations.json" }`. The full format is on the docs site.
+
+## `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 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 clear hub           # remove that clone again
+yarn et api clear --all         # remove every managed clone
+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.
+
+`clone`, `checkout`, `pull`, `setup` and `clear` 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.
+
+`clear` removes a managed checkout in `.ethlete/<name>`, and only that one: a path you set in
+`apiRepoPaths` is your own. It asks one question for every API you named, takes their containers down
+first, and refuses a checkout that holds uncommitted changes or commits no remote holds. `--force`
+skips those two git checks.
+
+Before it starts anything, `up` reads the host ports the requested services publish and checks
+whether something already holds them. In a terminal it offers to stop the containers that hold them.
+`--force` skips the check and lets the engine report the conflict itself.
+
+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/)
+- [Updating the SDK](https://ethlete-sdk-docs.web.app/cli/update)

package/design/define-call.ts

@@ -0,0 +1,92 @@
+/**
+ * A value inside a template. An array joins with nothing between, and `null`, `undefined` and
+ * `false` write nothing, so `${rows.map(row)}` and `${isOn && html`…`}` both read as they look.
+ */
+const flatten = (value: unknown): string => {
+  if (Array.isArray(value)) return value.map(flatten).join('');
+  if (value === null || value === undefined || value === false) return '';
+
+  return String(value);
+};
+
+const join = (strings: TemplateStringsArray, values: unknown[]) =>
+  strings.reduce((out, part, index) => out + flatten(values[index - 1]) + part);
+
+/**
+ * Marks a template literal as HTML, so Prettier formats it and an editor highlights it. It escapes
+ * nothing: a drawing writes its own markup, and nothing a call draws comes from outside the
+ * repository.
+ */
+export const html = (strings: TemplateStringsArray, ...values: unknown[]) => join(strings, values);
+
+/** Marks a template literal as CSS, for the same reason `html` does it for markup. */
+export const css = (strings: TemplateStringsArray, ...values: unknown[]) => join(strings, values);
+
+/**
+ * One drawn answer, as the frame renders it: the markup that goes in the frame root, and the CSS
+ * that styles it. A drawing runs no logic, so it is a value the module builds when the frame
+ * imports it, not a component the frame has to instantiate.
+ */
+export type Drawing = {
+  body: string;
+  styles: string;
+};
+
+/** Types a drawing where it is written, so a mistake reads in its own file and not in `call.ts`. */
+export const drawing = (drawn: Drawing): Drawing => drawn;
+
+/**
+ * One drawn answer to a call. `load` resolves the module whose default export is the
+ * drawing that answers it, so a broken variant breaks its own frame only.
+ */
+export type CallVariant = {
+  key: string;
+  name: string;
+  /** Left out by a view: a single drawing answers no question, so it argues nothing. */
+  claim?: string;
+  cost?: string;
+  /** Left out while the call is open. The user sets it, never the drawing. */
+  verdict?: 'chosen' | 'rejected';
+  /** The `key` of the round that drew it. Left out by a call that runs no rounds. */
+  round?: string;
+  load: () => Promise<{ default: Drawing }>;
+};
+
+/**
+ * One pass over a call: the variants drawn together, and what came out of them. A round
+ * whose variants all carry a verdict is settled, and the page folds it down to its winner.
+ */
+export type CallRound = {
+  key: string;
+  /** What this pass asked, in a few words. */
+  title: string;
+  /** What it answered. Write it once the user has ruled, so the next round reads as a reply. */
+  note: string;
+};
+
+/**
+ * How a call is drawn. A wireframe shows the bare workflow with mocked values, and draws no
+ * logic and no interaction state. A design call draws the real thing.
+ */
+export type CallMode = 'wireframe' | 'design';
+
+/**
+ * One open question of an exploration, with every variant drawn at the same geometry.
+ * A call with one variant and no claim is a view: one reference picture, drawn full width.
+ */
+export type Call = {
+  /** The feature this call belongs to, for example 'the hour strip'. Left out by a loose call. */
+  feature?: string;
+  eyebrow: string;
+  headline: string;
+  intro: string;
+  /** The width every variant frame gets, in px. The geometry the thing ships in. */
+  frameWidth: number;
+  /** Left out by a call that draws the real thing, which is what `design` means. */
+  mode?: CallMode;
+  /** Left out by a short call. With rounds, the intro says only what the call is about. */
+  rounds?: CallRound[];
+  variants: CallVariant[];
+};
+
+export const defineCall = (call: Call): Call => call;

package/design/web/env.d.ts

@@ -0,0 +1,11 @@
+declare module 'virtual:design-explore' {
+  import type { Call } from '@design-explore';
+
+  export const calls: Record<string, () => Promise<{ default: Call }>>;
+  export const defaultCall: string | null;
+}
+
+declare module 'virtual:design-explore/env' {
+  /** Loads the stylesheet the project draws under. A project the config names not draws bare. */
+  export const loadEnv: (project: string) => Promise<unknown>;
+}

package/design/web/frame.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <!--head-->
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./frame.ts"></script>
+  </body>
+</html>

package/design/web/frame.ts

@@ -0,0 +1,38 @@
+import { calls } from 'virtual:design-explore';
+import { loadEnv } from 'virtual:design-explore/env';
+
+const params = new URLSearchParams(location.search);
+const slug = params.get('call') ?? '';
+const key = params.get('variant') ?? '';
+
+await loadEnv(slug.split('/')[0] ?? '');
+
+const root = document.querySelector('#root') as HTMLElement;
+
+const fail = (message: string) => {
+  root.textContent = message;
+  root.setAttribute('style', 'padding:16px;font:14px monospace;color:#f0a0a0;background:#1a1414');
+};
+
+const call = calls[slug];
+if (!call) fail(`design-explore: no call "${slug}"`);
+else {
+  const variant = (await call()).default.variants.find((o) => o.key === key);
+  if (!variant) fail(`design-explore: call "${slug}" has no variant "${key}"`);
+  else {
+    const loaded = (await variant.load()).default;
+    const style = document.createElement('style');
+
+    style.textContent = loaded.styles;
+    document.head.append(style);
+    root.innerHTML = loaded.body;
+  }
+}
+
+const report = () => {
+  const height = Math.ceil(document.documentElement.getBoundingClientRect().height);
+  parent.postMessage({ type: 'design-explore:height', variant: key, height }, '*');
+};
+
+new ResizeObserver(report).observe(document.documentElement);
+report();