@lemonadecms/client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,71 @@
 # Changelog
 
-## 0.1.0 — initial npm candidate (unpublished)
+## Unreleased
+
+## 0.1.1 — prepared release
+
+- Add a native terminal environment picker for online `types generate` using
+  validated configured targets and their credential variables. Explicit settings,
+  CI, JSON/check/offline and piped runs stay noninteractive. Cancellation restores
+  the terminal and preserves files without network work. No dependencies added.
+
+- Add bounded nested `and`/`or`/`not` filters, `ne`/`not_in`, literal text patterns
+  and case-insensitive matching. Existing arrays and scalar/choice operators stay
+  supported. Sort by 1–3 ordered fields with stable NULL/tie/backward pagination.
+- Add typed paginated `search()` and reusable search options for reads, counts,
+  existence and lazy iteration. Uses the requested publication/locale snapshot
+  and PostgreSQL plain full-text relevance, with additive REST/RPC/GraphQL support.
+  Existing cursor forms and single-sort syntax remain compatible. No runtime,
+  optional or peer dependency was added; the updated CMS backend is required.
+
+- `count()` and `exists()` query matching authorized snapshots directly without
+  downloading entries. `getMany()` reads at most 100 IDs in one request and
+  preserves order/duplicates with nullable missing entries. `findOneOrThrow()`
+  raises the exported `CMSNotFoundError` only for a successful empty match. All
+  support public/server-preview reads, typed options and existing cancellation,
+  deadline and error behavior; the updated CMS REST endpoints are required.
+
+- `content(model).findOne()` returns the first typed matching entry or null using
+  one bounded query; preserves projections, metadata, filters, preview isolation
+  and existing error/cancellation/deadline behavior.
+- `richTextToHtml()` and `richTextToPlainText()` render version-1 rich-text values
+  in browsers/servers with bounded traversal, escaped HTML, safe URLs and matching
+  expanded resources. Plain text excludes embeds and link URLs.
+
+- Staff Admin manages release versions and notes in this Markdown file, with
+  exact-source preparation, durable activity and explicit npm publication through
+  a protected GitHub Actions job. Operator setup and live publishing qualification
+  remain separate; `--from-changelog` also selects this version locally.
+
+- Repository maintainers can run `npm run release:sdk` to manage stable versions,
+  changelog notes, validation and exact archive preparation. `--publish` explicitly
+  enables npm upload and installed-registry verification; `--current` resumes the
+  selected version. The source package remains private.
+
+- Entries include content-type identity, workspace/environment and locale beside
+  their existing ID, modeled fields and publication time. Optional TypeScript
+  metadata preserves existing entry fixtures; request identity supports older
+  CMS servers, while malformed/conflicting metadata is rejected safely.
+- Expanded reference types describe additive raw REST context metadata. The
+  generated `Models` map still describes only custom fields, not entry envelopes.
+
+- `lemonade types generate` loads the current project's `.env`, defaults to
+  `CMS_PROJECT_ID` / `CMS_PUBLIC_KEY`, Production and `src/types/cms-models.ts`.
+  Explicit flags, named targets and legacy `LEMONADE_*` settings still take
+  precedence; offline/management commands retain their credential boundaries.
+  C# and Python defaults use matching filenames in `src/types`.
+
+- Keep CLI request deadlines bounded when Node 22's response-body transport
+  ignores native abort; best-effort stream cancellation cannot delay completion.
+
+- Release preparation reads the selected version from package metadata, checks
+  package-lock/changelog agreement, and supports future stable/prerelease versions.
+- Explicit public-registry verification checks archive integrity and isolated
+  npm/pnpm installations, runtime/types, both CLIs and browser-preview guards.
+- Current installation documentation uses the published npm package. These
+  checkout changes do not replace the existing immutable registry artifact.
+
+## 0.1.0 — published package
 
 - Framework-independent ESM client and TypeScript declarations for published REST
   collection/item reads, field selection, bounded pagination, filters, sorting,
@@ -14,6 +79,6 @@
 - MIT license for this client package. This does not license the rest of the repository.
 
 New applications import `@lemonadecms/client`. Existing local `@cms/client` imports
-can use the documented file alias to the same archive. No package has been
-published by this preparation; registry availability and scope ownership are
-separate release gates.
+can use the documented file alias to a reviewed archive. Public availability of
+0.1.0 is verified separately from publisher access, provenance and authorization
+for a future release. Local preparation never publishes.

package/README.md

@@ -6,7 +6,7 @@ declarations, schema type generation and the `lemonade` developer CLI.
 
 ## Install
 
-For a version that has been published to npm:
+Install the published package in your application:
 
 ```sh
 npm install @lemonadecms/client
@@ -14,13 +14,13 @@ npm install @lemonadecms/client
 pnpm add @lemonadecms/client
 ```
 
-Before a version is published, install its reviewed candidate archive instead.
+Maintainers can test a future version using its reviewed candidate archive.
 Check the supplied `SHA256SUMS`, then use the actual archive path:
 
 ```sh
-npm install --ignore-scripts /absolute/path/to/lemonadecms-client-0.1.0.tgz
+npm install --ignore-scripts /absolute/path/to/reviewed-client.tgz
 # or
-pnpm add /absolute/path/to/lemonadecms-client-0.1.0.tgz
+pnpm add /absolute/path/to/reviewed-client.tgz
 ```
 
 The package uses ESM and declares Node.js 22+. TypeScript consumers need
@@ -63,6 +63,15 @@ if (first) {
 ```
 
 Entry values are under `fields`; metadata includes `id` and `publishedAt`.
+Unreleased source builds also expose `contentType` (ID/key/name), `projectId`,
+`environment` (ID/key) and resolved `locale`. Field projections retain metadata.
+For older CMS responses, the SDK derives only the request's model key/workspace
+and explicit locale; unavailable metadata stays absent. Metadata properties are
+optional in TypeScript for compatibility with existing manually constructed
+entries. Use `entry.contentType?.key`, not a custom `fields.contentType` field.
+Generated `Models` describes fields; `ContentEntry<Models['content_item'],
+'content_item'>` from the SDK describes the complete entry. Expanded reference
+metadata remains raw snake_case. Published `0.1.0` does not include these additions.
 An empty collection is `data: []`. Historical or selected fields can be missing
 or `null`, so handle both when rendering. Continue a collection using
 `page.meta.nextCursor` as the next request's `after` value while keeping the
@@ -76,6 +85,131 @@ environment override. Ask your Owner for a credential belonging to the intended
 environment. The server rechecks current access, expiry and revocation on every
 request.
 
+## Find one entry
+
+In the updated source build, `findOne()` returns the first matching complete
+entry or `null`. It makes one request with `limit=1` and preserves existing
+filters, search, sort, select, locale, includeRemote and signal options. It does not check
+uniqueness. Pagination/limit options are rejected; HTTP/authorization, transport,
+cancellation/deadline and malformed-response errors still reject. `get(id)` keeps
+its existing UUID lookup and 404 behavior. Published `0.1.0` lacks these helpers.
+
+```js
+const entry = await cms.content('content_item').findOne({
+  filters: [{ field: 'title', op: 'eq', value: 'Welcome' }],
+  select: ['title'],
+});
+console.log(entry?.fields.title ?? 'No matching content');
+```
+
+## Counts, existence and bulk reads
+
+These unreleased methods require the updated SDK and CMS backend. They are
+available in both published and server preview clients:
+
+```js
+import { CMSNotFoundError } from '@lemonadecms/client';
+
+const content = cms.content('content_item');
+const filters = [{ field: 'title', op: 'eq', value: 'Welcome' }];
+const total = await content.count({ filters });
+const available = await content.exists({ filters });
+try {
+  const required = await content.findOneOrThrow({ filters, select: ['title'] });
+  const entries = await content.getMany([required.id], { select: ['title'] });
+  console.log(total, available, entries[0]?.fields.title);
+} catch (error) {
+  if (!(error instanceof CMSNotFoundError)) throw error;
+  console.log('Required content is unavailable');
+}
+```
+
+`count()`/`exists()` accept filters, search, locale and signal, using direct database
+queries without downloading entries or expanding references. Count includes all
+matches across pages; separate requests can see different publication states.
+`getMany()` accepts up to 100 UUIDs and select/locale/includeRemote/signal. One
+request returns entries in input order, preserving duplicate positions and using
+`null` for missing/unpublished/foreign IDs in an otherwise authorized model.
+Empty input returns `[]` without I/O after validation. Split larger ID sets into
+batches; use the existing lazy `entries()`/`pages()` methods for collections.
+`findOneOrThrow()` shares findOne options and throws `CMSNotFoundError` only for
+a successful empty match. Authorization, HTTP, malformed-response, network,
+cancellation and deadline failures retain their existing errors. Preview fields
+may still be missing/null. No automatic collection-download fallback occurs.
+
+## Advanced filters, search and sorting
+
+Updated source builds support nested `and`/`or`/`not`, `ne`/`not_in`, and text
+`eqi`, `contains`/`containsi`, `starts_with`/`starts_withi`, `ends_with`/`ends_withi`.
+Existing filter arrays remain AND. Limits are ten leaves, 31 nodes, depth four
+and 4 KiB; groups are nonempty. SQL wildcard characters are treated literally.
+Positive comparisons on missing values are false; NOT and ne/not_in complement
+them, including missing values. Use eq/ne null for explicit null checks.
+
+```js
+const matches = await cms.content('content_item').search('welcome', {
+  fields: ['title'],
+  select: ['title'],
+  filters: {
+    or: [
+      { field: 'title', op: 'containsi', value: 'WELCOME' },
+      { not: { field: 'title', op: 'eq', value: 'Archived' } },
+    ],
+  },
+  sort: [
+    { field: 'position', direction: 'desc' },
+    { field: 'title', direction: 'asc' },
+  ],
+  limit: 10,
+});
+console.log(matches.data);
+```
+
+`fields` scopes matching to 1–24 text/long_text/markdown fields; `select` projects
+the returned fields. Omit fields to search all top-level fields of those types.
+Query accepts 1–200 Unicode codepoints, up to 512 UTF-8 bytes and 16 whitespace
+terms. PostgreSQL simple-config plain search requires every parsed term, with
+cover-density relevance order by default. Explicit 1–3 unique sort fields override
+relevance; NULLs stay last and UUID breaks ties. No stemming, fuzzy/prefix/phrase
+search or recursive rich-text/reference search is implied. Matching and ranking
+use only the authorized locale/fallback and published/preview snapshot.
+
+`search()` makes one normal paginated collection request. Pass the same
+`search: {query, fields}` object to list/findOne/findOneOrThrow/count/exists/pages/
+entries to count or traverse matches. Keep the full query and ordered sort fields
+unchanged when following cursors. Existing single-sort syntax remains supported.
+Signed cursors have an 8 KiB limit. Unusually large Unicode text anchors that
+exceed it after compression return `invalid_query`; choose more compact scalar
+sort fields in that case.
+These methods require the updated SDK/backend. Runtime/peer/optional dependencies
+remain empty; no external search service is used.
+
+## Rich-text helpers
+
+```js
+import { richTextToHtml, richTextToPlainText } from '@lemonadecms/client';
+
+// Replace rich_body with a rich_text field from your schema.
+const richEntry = await cms.content('content_item').findOne({ select: ['rich_body'] });
+const html = richTextToHtml(richEntry?.fields.rich_body);
+const plainText = richTextToPlainText(richEntry?.fields.rich_body);
+```
+
+Both accept nullable/unknown version-1 rich-text JSON and work in browsers or
+servers without a framework or DOM. HTML escapes text/attributes and renders only
+supported nodes/marks, safe links and matching expanded image/entry-caption
+resources. Unavailable embeds are omitted; entry routes are never invented.
+Plain text retains authored text with block/list/hard-break newlines, omitting
+embeds and link URLs. Plain text is not escaped HTML: use text interpolation.
+
+Traversal is bounded to 500 nodes, depth 8, 200 children per node, 20 embeds,
+20,000 UTF-8 bytes per text and 64 KiB of rendered source strings. Unsupported
+versions, invalid roots/containers or exhausted budgets return empty strings;
+unsupported parts are omitted. No raw HTML, resource-field recursion, I/O or
+automatic Markdown conversion is performed. HTML URL/alt bounds and exact
+preview-image conventions are documented in the SDK guide. The helpers are also
+exported from the server entry; preview authorization remains your responsibility.
+
 ## Types, queries and framework examples
 
 The [SDK guide](https://lemonadecms.com/guides/sdk) covers generated `Models`,
@@ -90,6 +224,60 @@ loading and error states, cache invalidation and safe HTML handling. Pass an
 `AbortSignal` to cancel a read. Optional `timeoutMs` sets a per-request deadline;
 combining a timeout with a caller signal requires `AbortSignal.any`.
 
+## Choose an environment for generated types
+
+The updated source CLI offers an interactive picker from configured targets:
+
+```sh
+npx lemonade types generate
+```
+
+Create `lemonade.config.json` in your application. Replace both workspace
+placeholders with your workspace UUID; the target labels distinguish environments.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "production": {
+      "url": "https://lemonadecms.com",
+      "workspace": "YOUR_WORKSPACE_UUID",
+      "environment": "production",
+      "credentialEnv": "CMS_PUBLIC_KEY"
+    },
+    "dev": {
+      "url": "https://lemonadecms.com",
+      "workspace": "YOUR_WORKSPACE_UUID",
+      "environment": "dev",
+      "credentialEnv": "CMS_DEV_PUBLIC_KEY"
+    }
+  }
+}
+```
+
+Keep actual credentials in your current directory's `.env` or process environment;
+process values win. A dev target needs a dev-scoped credential. The credential
+selects access; the CLI verifies the returned workspace/environment before writing.
+The picker lists configured targets, not environments discovered from the CMS.
+
+Use arrows and Enter. Production is initially selected when configured; otherwise
+the first target alphabetically. Escape/Ctrl+C/EOF exits 130 without network or
+output-file writes. Terminal input mode is restored on success, cancellation/error.
+Missing/revoked/mismatched credentials fail without replacing existing types.
+
+Explicit `--target`, `--environment`, `--url`, `--workspace` or `--credential-env`
+bypasses the picker, as do `LEMONADE_TARGET`, `LEMONADE_ENVIRONMENT` or
+`CMS_ENVIRONMENT`. CI, `--json`, `--check`, piped input/output, `--file` and other
+commands never prompt. `--config` can choose the target configuration file.
+Without configured targets, existing defaults remain unchanged. For automation:
+
+```sh
+npx lemonade types generate --target dev --check
+```
+
+This requires the updated source package; published 0.1.0 lacks the picker.
+It uses native Node APIs and retains zero runtime, peer or optional dependencies.
+
 ## Private previews
 
 For draft reads, use `createCMSPreviewClient` from

package/bin/cli/config.mjs

@@ -1,5 +1,6 @@
 import { access } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { parseEnv } from 'node:util';
 import { readText, parseJSON } from './io.mjs';
 import { fail } from './errors.mjs';
 import { languages } from '../codegen/definitions.mjs';
@@ -102,13 +103,20 @@ export function parseArgs(args) {
       [
         'schema pull',
         'schema export',
-        'types generate',
         'schema migrate plan',
         'schema migrate create',
       ].includes(command) &&
       !opts.out
     )
       fail(2, '--out is required.');
+    if (command === 'types generate' && !opts.out)
+      opts.out = `src/types/${
+        {
+          typescript: 'cms-models.ts',
+          csharp: 'cms-models.cs',
+          python: 'cms_models.py',
+        }[opts.language || 'typescript']
+      }`;
     if (
       [
         'schema validate',
@@ -138,7 +146,26 @@ export function parseArgs(args) {
     fail(2, 'Applying requires --file, --plan and --confirm REVIEWED_CHECKSUM.');
   return { command, opts };
 }
-export async function connection(opts, env, cwd, management = false) {
+export async function typeGenerationEnv(env, cwd) {
+  const path = resolve(cwd, '.env');
+  try {
+    await access(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return { ...env };
+    fail(2, 'Could not open project .env. Check file access.');
+  }
+  try {
+    // Parse data only: never source shell code or change process.env/startup settings.
+    return { ...parseEnv(await readText(path, 65536)), ...env };
+  } catch {
+    fail(
+      2,
+      'Could not read project .env. Use a UTF-8 regular file no larger than 64 KiB.',
+    );
+  }
+}
+
+export async function readConfiguration(opts, cwd) {
   const configPath = resolve(cwd, opts.config || 'lemonade.config.json');
   let config = {};
   let found = true;
@@ -185,19 +212,47 @@ export async function connection(opts, env, cwd, management = false) {
       safeURL(target.url);
     }
   }
+  return { configPath, targets: config.targets || {} };
+}
+
+export async function connection(
+  opts,
+  env,
+  cwd,
+  management = false,
+  defaults = {},
+  configuration,
+) {
+  const { configPath, targets } = configuration || (await readConfiguration(opts, cwd));
   const name = opts.target || env.LEMONADE_TARGET;
-  const target = name ? config.targets?.[name] : {};
-  if (name && !target) fail(2, 'Selected target is not configured.');
+  if (name && !Object.hasOwn(targets, name))
+    fail(2, 'Selected target is not configured.');
+  const target = name ? targets[name] : {};
   const selected = {
     url: opts.url || target.url || env.LEMONADE_URL || 'https://lemonadecms.com',
-    workspace: opts.workspace || target.workspace || env.LEMONADE_WORKSPACE,
-    environment: opts.environment || target.environment || env.LEMONADE_ENVIRONMENT,
+    workspace:
+      opts.workspace ||
+      target.workspace ||
+      env.LEMONADE_WORKSPACE ||
+      defaults.workspace,
+    environment:
+      opts.environment ||
+      target.environment ||
+      env.LEMONADE_ENVIRONMENT ||
+      defaults.environment,
     credentialEnv:
       opts['credential-env'] ||
       target.credentialEnv ||
-      (management ? 'LEMONADE_MANAGEMENT_TOKEN' : 'LEMONADE_TOKEN'),
+      (management
+        ? 'LEMONADE_MANAGEMENT_TOKEN'
+        : defaults.credentialEnv || 'LEMONADE_TOKEN'),
     configPath,
   };
+  if (defaults.credentialEnv && !selected.workspace)
+    fail(
+      2,
+      'Set CMS_PROJECT_ID in .env or the process environment, or pass --workspace UUID.',
+    );
   if (
     !uuid.test(selected.workspace || '') ||
     !(

package/bin/cli/network.mjs

@@ -1,6 +1,34 @@
 import { MAX_SCHEMA_BYTES, parseJSON } from './io.mjs';
 import { fail, CLIError } from './errors.mjs';
 import { validateSchema, schemaIdentity } from './schema.mjs';
+
+// Bound caller completion even when a transport/body ignores native abort.
+export function withinSignal(signal, operation) {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener('abort', abort);
+      reject(signal.reason);
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve()
+      .then(() => {
+        if (signal.aborted) throw signal.reason;
+        return operation();
+      })
+      .then(
+        (value) => {
+          signal.removeEventListener('abort', abort);
+          if (signal.aborted) reject(signal.reason);
+          else resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener('abort', abort);
+          reject(error);
+        },
+      );
+  });
+}
 export async function fetchSchema(target, fetcher = fetch) {
   const schema = validateSchema(
     await requestJSON(
@@ -35,19 +63,21 @@ export async function requestJSON(
   const timer = setTimeout(() => controller.abort(), 15000);
   let reader;
   try {
-    const response = await fetcher(`${target.url}${path}`, {
-      method,
-      headers: {
-        Accept: 'application/json',
-        Authorization: `Bearer ${target.key}`,
-        ...(requestBody ? { 'Content-Type': 'application/json' } : {}),
-      },
-      ...(requestBody ? { body: JSON.stringify(requestBody) } : {}),
-      redirect: 'error',
-      credentials: 'omit',
-      cache: 'no-store',
-      signal: controller.signal,
-    });
+    const response = await withinSignal(controller.signal, () =>
+      fetcher(`${target.url}${path}`, {
+        method,
+        headers: {
+          Accept: 'application/json',
+          Authorization: `Bearer ${target.key}`,
+          ...(requestBody ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(requestBody ? { body: JSON.stringify(requestBody) } : {}),
+        redirect: 'error',
+        credentials: 'omit',
+        cache: 'no-store',
+        signal: controller.signal,
+      }),
+    );
     if ([401, 403].includes(response.status))
       fail(
         4,
@@ -72,7 +102,9 @@ export async function requestJSON(
     const chunks = [];
     let bytes = 0;
     while (true) {
-      const { done, value } = await reader.read();
+      const { done, value } = await withinSignal(controller.signal, () =>
+        reader.read(),
+      );
       if (done) break;
       bytes += value.byteLength;
       if (bytes > MAX_SCHEMA_BYTES)
@@ -94,6 +126,9 @@ export async function requestJSON(
   } finally {
     clearTimeout(timer);
     controller.abort();
-    await reader?.cancel().catch(() => {});
+    // Cancellation is best effort: a stalled cleanup must not extend the deadline.
+    try {
+      reader?.cancel().catch(() => {});
+    } catch {}
   }
 }

package/bin/cli/picker.mjs

@@ -0,0 +1,118 @@
+import { emitKeypressEvents } from 'node:readline';
+import { CLIError } from './errors.mjs';
+
+export function canPickTarget(opts, env, { input, output, stdoutIsTTY }) {
+  return Boolean(
+    input.isTTY &&
+    output.isTTY &&
+    stdoutIsTTY &&
+    typeof input.setRawMode === 'function' &&
+    !env.CI &&
+    !opts.json &&
+    !opts.check &&
+    !['target', 'environment', 'url', 'workspace', 'credential-env'].some(
+      (key) => opts[key],
+    ) &&
+    !['LEMONADE_TARGET', 'LEMONADE_ENVIRONMENT', 'CMS_ENVIRONMENT'].some(
+      (key) => env[key],
+    ),
+  );
+}
+
+// Targets have already passed bounded configuration validation. Only safe target
+// names/environment identities reach the terminal, never URLs or credential data.
+export function pickTarget(targets, { input, output }) {
+  const production = (target) =>
+    target.environment === 'production' ||
+    target.environment.toLowerCase() === target.workspace.toLowerCase();
+  const choices = Object.entries(targets).sort(
+    ([a, left], [b, right]) =>
+      Number(production(right)) - Number(production(left)) ||
+      (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return new Promise((resolve, reject) => {
+    let selected = 0,
+      settled = false,
+      renderedLines = 0;
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing === true;
+    const cancelled = () =>
+      finish(
+        new CLIError(130, 'Environment selection cancelled. No output was written.'),
+      );
+    const failed = () =>
+      finish(
+        new CLIError(
+          2,
+          'Could not read the environment selection. No output was written.',
+        ),
+      );
+    const render = () => {
+      const width = Math.max(10, (output.columns || 80) - 1);
+      const visible = Math.min(choices.length, Math.max(1, (output.rows || 24) - 4));
+      const start = Math.min(
+        Math.max(0, selected - visible + 1),
+        choices.length - visible,
+      );
+      const lines = choices
+        .slice(start, start + visible)
+        .map(([name, target], index) => {
+          const label = `${index + start === selected ? '>' : ' '} ${name} (${target.environment})`;
+          return label.length > width ? label.slice(0, width - 3) + '...' : label;
+        });
+      if (renderedLines) output.write(`\x1b[${renderedLines}A\r`);
+      output.write(lines.map((line) => `\x1b[2K${line}\n`).join(''));
+      renderedLines = lines.length;
+    };
+    function finish(error) {
+      if (settled) return;
+      settled = true;
+      input.removeListener('keypress', onKey);
+      input.removeListener('end', cancelled);
+      input.removeListener('close', cancelled);
+      input.removeListener('error', failed);
+      output.removeListener('error', failed);
+      process.removeListener('SIGINT', cancelled);
+      try {
+        input.setRawMode(wasRaw);
+        if (!wasFlowing) input.pause();
+      } catch {
+        error ||= new CLIError(2, 'Could not restore terminal input.');
+      }
+      if (error) reject(error);
+      else resolve(choices[selected][0]);
+    }
+    function onKey(_, key = {}) {
+      if (settled) return;
+      if (key.name === 'escape' || (key.ctrl && ['c', 'd'].includes(key.name)))
+        return cancelled();
+      if (['return', 'enter'].includes(key.name)) return finish();
+      if (['up', 'down'].includes(key.name)) {
+        selected =
+          (selected + (key.name === 'up' ? -1 : 1) + choices.length) % choices.length;
+        try {
+          render();
+        } catch {
+          failed();
+        }
+      }
+    }
+    try {
+      if (input.destroyed || input.readableEnded) return cancelled();
+      if (output.destroyed || output.writableEnded) return failed();
+      emitKeypressEvents(input);
+      input.on('keypress', onKey);
+      input.once('end', cancelled);
+      input.once('close', cancelled);
+      input.once('error', failed);
+      output.once('error', failed);
+      process.once('SIGINT', cancelled);
+      input.setRawMode(true);
+      input.resume();
+      output.write('Select an environment (arrows, Enter; Esc/Ctrl+C to cancel):\n');
+      render();
+    } catch {
+      failed();
+    }
+  });
+}