@lemonadecms/client 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,87 @@
 # Changelog
 
-## 0.1.0 — initial npm candidate (unpublished)
+## Unreleased
+
+## 0.2.0
+
+- Use `https://api.lemonadecms.com` for new SDK/CLI defaults. The server's strict
+  hostname mode intentionally returns 404 for old main-domain API URLs; upgrade
+  installed clients and configured targets before using that deployment.
+  Explicit CLI flags and environment precedence remain unchanged.
+  Studio/preview message origins stay separate; no redirect, fallback retry or
+  runtime dependency. Package publication and server deployment are separate.
+
+- Add the optional zero-dependency `@lemonadecms/client/composer` browser bridge:
+  versioned website capabilities, stable section/slot locators, selection and
+  arrangement commands, cancellable serial rendering and latest-only commits.
+  Requires an explicitly opted-in private CMS destination and website renderer.
+- Generate three-level nested component unions and localized text leaves in
+  TypeScript, Python and C#, retaining legacy flat schemas and CLI behavior.
+
+## 0.1.1 — published package
+
+- 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 +95,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
@@ -30,7 +30,7 @@ runtime library or framework dependency is required.
 
 ## Configure and read content
 
-The SDK connects to `https://lemonadecms.com` automatically. Configure your
+Version 0.2.0 connects to `https://api.lemonadecms.com` automatically. Strict hostname routing returns 404 for API URLs on `https://lemonadecms.com`. Upgrade earlier clients to 0.2.0 and change explicit CLI/configured-target URLs to `https://api.lemonadecms.com`. Explicit CLI settings still take precedence; no redirect or fallback is attempted. Configure your
 workspace and delivery key; there is no URL or local CMS option. Your website
 can run locally while reading content from Lemonade production. Installing the
 package does not create an account, workspace or delivery key.
@@ -63,6 +63,15 @@ if (first) {
 ```
 
 Entry values are under `fields`; metadata includes `id` and `publishedAt`.
+The client also exposes `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 methods require the current 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://api.lemonadecms.com",
+      "workspace": "YOUR_WORKSPACE_UUID",
+      "environment": "production",
+      "credentialEnv": "CMS_PUBLIC_KEY"
+    },
+    "dev": {
+      "url": "https://api.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
+```
+
+Version 0.2.0 includes the picker; historical 0.1.0 does not.
+It uses native Node APIs and retains zero runtime, peer or optional dependencies.
+
 ## Private previews
 
 For draft reads, use `createCMSPreviewClient` from
@@ -115,3 +303,16 @@ fetch client.
 
 This SDK package is licensed under the [MIT License](LICENSE). Its license does
 not grant a license to the entire CMS repository or the separate native clients.
+
+
+## Visual Composer
+
+The optional Visual Composer adds approved nested sections, inspector editing and
+private live updates. A developer connects the website registry and explicitly
+enables unsaved projection on its trusted preview destination. Save draft and
+Publish remain separate. Component text can be translated by stable block ID;
+each language keeps its live tree until explicitly published. Existing form and
+saved-draft previews remain supported. The browser helper is the dependency-free
+`@lemonadecms/client/composer` export.
+
+See [setup, editor workflow, Astro reference and protocol](https://github.com/ilara-booqself/lemonadecms/blob/main/docs/visual-composer.md).

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,
+    url: opts.url || target.url || env.LEMONADE_URL || 'https://api.lemonadecms.com',
+    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();
+    }
+  });
+}