synomem 0.2.0 → 0.4.0

package/src/configure.ts

@@ -0,0 +1,233 @@
+/**
+ * `synomem config` — the onboarding wizard, and its deterministic equivalent.
+ *
+ * Two rules shape this file. Every interactive step has a non-interactive
+ * counterpart, so an agent can configure a machine without a terminal. And the
+ * wizard refuses to run at all when nobody is there to answer: a setup program
+ * that blocks forever on a pipe is worse than one that says which flags it
+ * needs.
+ */
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cloudApiUrl } from './cloud.js';
+import { SynomemError } from './errors.js';
+import { resolveHome } from './config.js';
+import { ask, askSecret, confirm, select, type PromptIo } from './prompt.js';
+
+export type BackendChoice = 'local' | 'remote';
+export type AuthChoice = 'browser' | 'access-key';
+export type CredentialStoreChoice = 'auto' | 'keychain' | 'file' | 'environment';
+
+export interface ConfigInitOptions {
+  backend?: BackendChoice;
+  home?: string;
+  auth?: AuthChoice;
+  workspace?: string;
+  accessToken?: string;
+  credentialStore?: CredentialStoreChoice;
+  yes?: boolean;
+}
+
+export interface ConfigPlan {
+  backend: BackendChoice;
+  home: string;
+  serviceUrl?: string;
+  auth?: AuthChoice;
+  workspaceId?: string;
+  credentialStore?: CredentialStoreChoice;
+}
+
+/**
+ * Where a credential can actually be kept on this platform.
+ *
+ * Reported rather than assumed: offering macOS Keychain on Linux, or a Secret
+ * Service that is not running, produces a setup that appears to succeed and
+ * then cannot read its own credential back.
+ */
+export function credentialStoreChoices(
+  platform: NodeJS.Platform = process.platform,
+): Array<{ value: CredentialStoreChoice; label: string; detail?: string }> {
+  const native =
+    platform === 'darwin'
+      ? { value: 'keychain' as const, label: 'macOS Keychain', detail: 'Recommended.' }
+      : platform === 'win32'
+        ? {
+            value: 'keychain' as const,
+            label: 'Windows Credential Manager',
+            detail: 'Recommended.',
+          }
+        : {
+            value: 'keychain' as const,
+            label: 'Secret Service (libsecret)',
+            detail: 'Recommended where a desktop keyring is running.',
+          };
+  return [
+    native,
+    {
+      value: 'file',
+      label: 'A restricted file in the Synomem home',
+      detail: 'Mode 0600. Use on headless machines with no keyring.',
+    },
+    {
+      value: 'environment',
+      label: 'Print environment-variable instructions',
+      detail: 'Nothing is stored. Synomem never edits your shell profile.',
+    },
+  ];
+}
+
+/** Refuses to guess when there is nobody to ask. */
+export function assertInteractive(io: PromptIo): void {
+  if (io.interactive) return;
+  throw new SynomemError(
+    'INVALID_INPUT',
+    [
+      'synomem config needs an interactive terminal.',
+      '',
+      'For automation, use the deterministic form instead:',
+      '',
+      '  synomem config init --backend local --yes',
+      '',
+      '  synomem config init --backend remote --auth access-key \\',
+      '    --workspace <workspace-id> --access-token-stdin --yes',
+      '',
+      'Pipe the token in rather than passing it as an argument: an argument is',
+      'kept by both the shell history and the process list.',
+    ].join('\n'),
+  );
+}
+
+/**
+ * Stores an access key in a restricted file.
+ *
+ * Separate from `config.json` so a configuration file can be read, copied or
+ * pasted into an issue without carrying a secret with it.
+ */
+export function writeCredentialFile(home: string, token: string): string {
+  const directory = join(home, 'credentials');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  const path = join(directory, 'installation.json');
+  writeFileSync(path, `${JSON.stringify({ accessToken: token }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+/** A key's identifying prefix. Never the key. */
+export function credentialFingerprint(token: string): string {
+  const head = token.slice(0, 12);
+  return `${head}${token.length > 12 ? '\u2026' : ''}`;
+}
+
+export function environmentInstructions(token: string): string {
+  return [
+    'Set this value for the current shell:',
+    '',
+    `  export SYNOMEM_ACCESS_TOKEN='${token}'`,
+    '',
+    'To persist it, add that to a secret-aware shell configuration or to your',
+    'agent runtime environment. Synomem will not edit your shell profile for',
+    'you: silently rewriting a dotfile is not a thing a setup program should do.',
+  ].join('\n');
+}
+
+/** The interactive flow, returning the plan it settled on. */
+export async function runConfigWizard(
+  io: PromptIo,
+  options: { home?: string; env?: NodeJS.ProcessEnv } = {},
+): Promise<ConfigPlan> {
+  assertInteractive(io);
+  const env = options.env ?? process.env;
+
+  io.output.write(
+    [
+      '',
+      'Welcome to Synomem',
+      '',
+      'Synomem gives agents durable notes, messages, tasks, todos, kudos,',
+      'and shared coordination.',
+      '',
+    ].join('\n'),
+  );
+
+  const backend = await select<BackendChoice>(io, 'Where should Synomem store canonical state?', [
+    {
+      value: 'local',
+      label: 'Local \u2014 SQLite on this machine',
+      detail: 'Nothing is uploaded. One implicit workspace.',
+    },
+    {
+      value: 'remote',
+      label: 'Synomem Cloud \u2014 shared across machines and agents',
+      detail: 'Organizations, workspaces, roles and administration.',
+    },
+  ]);
+
+  const home = await ask(io, 'Where should Synomem store its data?', resolveHome(options.home));
+
+  if (backend === 'local') {
+    return { backend, home };
+  }
+
+  const serviceUrl = cloudApiUrl(env);
+  io.output.write(`\nConnecting to Synomem Cloud at ${serviceUrl}\n`);
+
+  const auth = await select<AuthChoice>(io, 'How would you like to sign in?', [
+    {
+      value: 'browser',
+      label: 'Sign in with your browser',
+      detail: 'Opens the authorization server and returns through a loopback callback.',
+    },
+    {
+      value: 'access-key',
+      label: 'Use an installation access key',
+      detail: 'Create one at https://portal.synomem.ai/installations',
+    },
+  ]);
+
+  const workspaceId = await ask(io, 'Workspace ID');
+  if (!workspaceId) {
+    throw new SynomemError('INVALID_INPUT', 'A workspace ID is required for the hosted backend.');
+  }
+
+  const credentialStore =
+    auth === 'access-key'
+      ? await select<CredentialStoreChoice>(
+          io,
+          'Where should Synomem store this credential?',
+          credentialStoreChoices(),
+        )
+      : 'auto';
+
+  return { backend, home, serviceUrl, auth, workspaceId, credentialStore };
+}
+
+/** Reads an access key without ever accepting it as an argument. */
+export async function readAccessToken(io: PromptIo): Promise<string> {
+  const token = await askSecret(io, 'Installation access key');
+  if (!token) throw new SynomemError('INVALID_INPUT', 'No access key was provided.');
+  return token;
+}
+
+export async function confirmPlan(io: PromptIo, plan: ConfigPlan): Promise<boolean> {
+  io.output.write(
+    [
+      '',
+      'Synomem will be configured as:',
+      '',
+      `  Backend:   ${plan.backend === 'local' ? 'Local SQLite' : 'Synomem Cloud'}`,
+      `  Home:      ${plan.home}`,
+      ...(plan.serviceUrl ? [`  Service:   ${plan.serviceUrl}`] : []),
+      ...(plan.workspaceId ? [`  Workspace: ${plan.workspaceId}`] : []),
+      ...(plan.credentialStore && plan.credentialStore !== 'auto'
+        ? [`  Credential: ${plan.credentialStore}`]
+        : []),
+      '',
+    ].join('\n'),
+  );
+  return await confirm(io, 'Apply this?');
+}
+
+export function homeExists(home: string): boolean {
+  return existsSync(home);
+}

package/src/credentials.ts

@@ -6,6 +6,21 @@ import type { ActorIdentity } from './types.js';
 const serviceName = 'ai.synomem.credentials';
 const maximumOutputBytes = 128 * 1024;
 
+/**
+ * An installation access key.
+ *
+ * Not an OAuth credential: it has no refresh, no token endpoint and no client,
+ * and it authorizes a MACHINE rather than a person. Keeping it a distinct shape
+ * stops code treating it as refreshable, which would mean silently failing to
+ * renew something that never expires that way.
+ */
+export interface StoredInstallationKey {
+  kind: 'installation-key';
+  accessToken: string;
+}
+
+export type StoredCredential = StoredOAuthCredential | StoredInstallationKey;
+
 export interface StoredOAuthCredential {
   accessToken: string;
   refreshToken?: string;
@@ -17,8 +32,8 @@ export interface StoredOAuthCredential {
 }
 
 export interface CredentialStore {
-  get(reference: string): Promise<StoredOAuthCredential | undefined>;
-  set(reference: string, credential: StoredOAuthCredential): Promise<void>;
+  get(reference: string): Promise<StoredCredential | undefined>;
+  set(reference: string, credential: StoredCredential): Promise<void>;
   delete(reference: string): Promise<boolean>;
 }
 

package/src/index.ts

@@ -11,7 +11,12 @@ export {
 export { RemoteSynomemService, environmentCredentialProvider } from './remote.js';
 export type { SynomemCredentialProvider, RemoteSynomemOptions } from './remote.js';
 export { credentialReference, OsCredentialStore } from './credentials.js';
-export type { CredentialStore, StoredOAuthCredential } from './credentials.js';
+export type {
+  CredentialStore,
+  StoredCredential,
+  StoredInstallationKey,
+  StoredOAuthCredential,
+} from './credentials.js';
 export { loginWithOAuth, StoredCredentialProvider } from './oauth.js';
 export type { OAuthLoginOptions } from './oauth.js';
 export {
@@ -35,6 +40,7 @@ export type {
   ProjectionRebuildResult,
 } from './service.js';
 export { defaultConfig, resolveHome } from './config.js';
+export { cloudApiUrl, SYNOMEM_CLOUD_API_URL } from './cloud.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
 export {
   dueInstant,

package/src/mcp/index.ts

@@ -6,6 +6,7 @@ import { configuredServiceFactory } from '../backend.js';
 import { SynomemError, asSynomemError } from '../errors.js';
 import {
   actorSchema,
+  agentHandleSchema,
   agentIdSchema,
   changesInputSchema,
   createNoteSchema,
@@ -88,9 +89,18 @@ export async function createSynomemMcpServer(
   options: SynomemMcpOptions,
   serviceFactory: SynomemServiceFactory = configuredServiceFactory,
 ): Promise<SynomemMcpRuntime> {
-  const actor = actorSchema.parse(options.actor);
-  const client = serviceFactory({ ...options, actor });
+  const requested = actorSchema.parse(options.actor);
+  const client = serviceFactory({ ...options, actor: requested });
   await client.init();
+  /*
+   * Every tool reports the CANONICAL actor, not the one that was asked for.
+   *
+   * A harness registers with a handle because that is what a person typed, but
+   * init resolves it against stored state — so the identity echoed back is the
+   * one the events will actually carry. Reporting the requested name would let
+   * a misconfigured runtime appear to be acting as somebody it is not.
+   */
+  const actor = client.actor;
   const server = new McpServer(
     { name: 'synomem', version: packageVersion() },
     {
@@ -282,9 +292,9 @@ export async function createSynomemMcpServer(
       description:
         'Administrative tool for creating a stable agent identity. Disabled by default so runtime agents cannot silently create identities.',
       inputSchema: z.object({
-        id: agentIdSchema,
+        handle: agentHandleSchema,
         displayName: z.string().trim().min(1).max(200),
-        aliases: z.array(agentIdSchema).max(50).optional(),
+        aliases: z.array(agentHandleSchema).max(50).optional(),
         description: z.string().trim().max(2000).optional(),
       }),
       outputSchema,
@@ -300,7 +310,11 @@ export async function createSynomemMcpServer(
           );
         }
         const profile = await client.agents.create(input);
-        return success(actor, `Created agent ${profile.displayName} (${profile.id}).`, { profile });
+        return success(
+          actor,
+          `Created agent ${profile.displayName}: handle ${profile.handle}, ID ${profile.id}.`,
+          { profile },
+        );
       } catch (error) {
         return failure(actor, error);
       }
@@ -326,6 +340,82 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_post_create',
+    {
+      title: 'Publish a post',
+      description:
+        'Publish something the whole workspace can read. Use for an announcement, a decision, or context several agents need. A post has no recipient — if one named actor must act, send a memo or assign a task instead.',
+      inputSchema: z.object({
+        title: z.string().trim().min(1).max(200),
+        body: z.string().trim().min(1).max(32_000),
+        tags: z.array(z.string()).max(20).optional(),
+        replyTo: z.string().length(26).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const result = await client.posts.create(input);
+        return success(actor, `Published post ${result.record.event.id}.`, {
+          post: result.record,
+        });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_acknowledge',
+    {
+      title: 'Acknowledge a post',
+      description:
+        'Record that YOU have seen a post. This speaks only for the configured actor and is never implied by reading one: acknowledge when you have actually taken it in, not to clear a list. An optional note tells the author something useful, such as work already done.',
+      inputSchema: z.object({
+        postId: z.string().length(26),
+        note: z.string().trim().min(1).max(2000).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async (input) => {
+      try {
+        const record = await client.posts.acknowledge(input);
+        return success(actor, `Acknowledged post ${input.postId}.`, { post: record });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_roster',
+    {
+      title: 'See who has acknowledged a post',
+      description:
+        'Who has acknowledged a post and who has not. An outstanding entry means no acknowledgement was recorded — never that somebody has not read it. Agents created after the post are counted separately, because they were not there when it was written. This is read-only and does not acknowledge anything.',
+      inputSchema: z.object({ postId: z.string().length(26) }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ postId }) => {
+      try {
+        const roster = await client.posts.roster(postId);
+        return success(
+          actor,
+          `${roster.acknowledged.length} acknowledged, ${roster.outstanding.length} with no acknowledgement recorded.`,
+          roster,
+        );
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
   server.registerTool(
     'synomem_agent_resolve',
     {

package/src/oauth.ts

@@ -207,7 +207,14 @@ export class StoredCredentialProvider implements SynomemCredentialProvider {
   async getAccessToken(signal?: AbortSignal): Promise<string | undefined> {
     if (this.env.SYNOMEM_ACCESS_TOKEN) return this.env.SYNOMEM_ACCESS_TOKEN;
     if (!this.loaded) {
-      this.credential = await this.store.get(this.reference);
+      const stored = await this.store.get(this.reference);
+      /*
+       * An installation key is not an OAuth credential: it cannot be refreshed
+       * and has no client or token endpoint. Treating one as OAuth would mean
+       * trying to renew something that never renews that way, so this path
+       * ignores it and lets the installation-key path handle it.
+       */
+      this.credential = stored && 'kind' in stored ? undefined : stored;
       this.loaded = true;
     }
     const credential = this.credential;

package/src/ports/repository.ts

@@ -5,6 +5,8 @@ import type {
   ChangePage,
   ItemListInput,
   JsonValue,
+  PostAcknowledgment,
+  PostRoster,
   ItemSummary,
   KudosListInput,
   KudosSummary,
@@ -45,6 +47,9 @@ export interface SynomemRepository {
   listAgents(): Awaitable<AgentProfile[]>;
   /** Resolves a name case-insensitively, reporting ambiguity instead of guessing. */
   resolveAgent(query: string): Awaitable<{ match?: AgentProfile; candidates: AgentProfile[] }>;
+  listPostAcknowledgments(postId: string): Awaitable<PostAcknowledgment[]>;
+  /** Who has acknowledged a post and who has not; see PostRoster. */
+  postRoster(postId: string): Awaitable<PostRoster | undefined>;
   listRuntimeBindings(agentId: string): Awaitable<AgentRuntimeBinding[]>;
   bindRuntime(binding: {
     id: string;

package/src/projections.ts

@@ -16,6 +16,7 @@ import type {
   KudosRecord,
   MemoRecord,
   NoteRecord,
+  PostRecord,
   TaskDue,
   TaskRecord,
   TodoRecord,
@@ -254,6 +255,75 @@ export function memoRecordsFromEvents(events: SynomemEvent[]): MemoRecord[] {
   return [...records.values()].sort((a, b) => b.event.createdAt.localeCompare(a.event.createdAt));
 }
 
+/**
+ * Rebuilds posts from their events, acknowledgements included.
+ *
+ * Edits are kept as a list rather than collapsed into the current text. A reader
+ * has to be able to see that a post changed after somebody acknowledged it —
+ * silently rewriting what was acknowledged is how a record becomes a lie.
+ */
+export function postRecordsFromEvents(events: SynomemEvent[]): PostRecord[] {
+  const records = new Map<string, PostRecord>();
+  for (const event of events) {
+    if (event.type === 'post.created') {
+      records.set(event.id, {
+        event,
+        edits: [],
+        acknowledgments: [],
+        status: 'active',
+        title: event.title,
+        body: event.body,
+        ...(event.tags ? { tags: event.tags } : {}),
+        // The text version, counting only changes to the text.
+        //
+        // Deliberately not the aggregate version, which also counts every
+        // acknowledgement. If they were the same number, somebody
+        // acknowledging a post would invalidate an edit the author was in the
+        // middle of making — a conflict with nothing to reconcile.
+        version: 1,
+      });
+    } else if (event.type === 'post.edited') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.edits.push(event);
+        record.title = event.title;
+        record.body = event.body;
+        if (event.tags) record.tags = event.tags;
+        record.version += 1;
+      }
+    } else if (event.type === 'post.archived') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.archived = event;
+        record.status = 'archived';
+      }
+    } else if (event.type === 'post.acknowledged') {
+      const record = records.get(event.postId);
+      if (record) {
+        // One statement per actor: a repeat replaces rather than accumulates.
+        const existing = record.acknowledgments.findIndex(
+          (entry) => entry.actor.id === event.actor.id && entry.actor.kind === event.actor.kind,
+        );
+        const entry = {
+          actor: event.actor,
+          acknowledgedAt: event.createdAt,
+          ...(event.note ? { note: event.note } : {}),
+        };
+        if (existing >= 0) record.acknowledgments[existing] = entry;
+        else record.acknowledgments.push(entry);
+      }
+    } else if (event.type === 'post.acknowledgment.withdrawn') {
+      const record = records.get(event.postId);
+      if (record) {
+        record.acknowledgments = record.acknowledgments.filter(
+          (entry) => !(entry.actor.id === event.actor.id && entry.actor.kind === event.actor.kind),
+        );
+      }
+    }
+  }
+  return [...records.values()];
+}
+
 export function noteRecordsFromEvents(events: SynomemEvent[]): NoteRecord[] {
   const records = new Map<string, NoteRecord>();
   for (const event of events) {
@@ -480,7 +550,7 @@ export class ProjectionManager implements ProjectionWriter {
     const generated: string[] = [];
 
     for (const profile of profiles) {
-      const agentDirectory = join(this.storage.home, profile.id);
+      const agentDirectory = join(this.storage.home, profile.handle);
       assertNoSymlinkEscape(this.storage.home, agentDirectory);
       ensureDirectory(agentDirectory);
       const profilePath = join(agentDirectory, 'profile.json');
@@ -586,7 +656,7 @@ export class ProjectionManager implements ProjectionWriter {
       (record) => record.event.assigneeAgentId === profile.id,
     );
     const rebuiltAt = events.at(-1)?.createdAt ?? new Date(0).toISOString();
-    const agentDirectory = join(this.storage.home, profile.id);
+    const agentDirectory = join(this.storage.home, profile.handle);
     const inboxDirectory = join(agentDirectory, 'inbox');
     const kudosInboxDirectory = join(inboxDirectory, 'kudos');
     const memoInboxDirectory = join(inboxDirectory, 'memos');
@@ -659,7 +729,7 @@ export class ProjectionManager implements ProjectionWriter {
     }
 
     const keep = new Set(generated);
-    const prefixes = [`${profile.id}/`, `${profile.id}\\`];
+    const prefixes = [`${profile.handle}/`, `${profile.handle}\\`];
     const removed: string[] = [];
     for (const stale of this.storage
       .projectionManifest()
@@ -675,7 +745,7 @@ export class ProjectionManager implements ProjectionWriter {
       unlinkSync(path);
       removed.push(stale);
     }
-    this.storage.replaceAgentProjectionManifest(profile.id, generated, rebuiltAt);
+    this.storage.replaceAgentProjectionManifest(profile.handle, generated, rebuiltAt);
     return { generated: generated.sort(), removed: removed.sort() };
   }
 

package/src/prompt.ts

@@ -0,0 +1,88 @@
+/**
+ * A small prompt boundary, injectable so the wizard is testable.
+ *
+ * Deliberately not a dependency: the wizard needs a select, a line, a masked
+ * line and a confirm, and a library for that would be more surface than
+ * substance. Everything reads from an injected stream, so tests drive the flow
+ * without a terminal.
+ */
+import { createInterface } from 'node:readline/promises';
+import type { Readable, Writable } from 'node:stream';
+
+export interface PromptIo {
+  input: Readable;
+  output: Writable;
+  /**
+   * Whether a person is actually there. A wizard must never wait forever on a
+   * pipe, so a non-interactive stream is refused with instructions instead.
+   */
+  interactive: boolean;
+}
+
+export function defaultPromptIo(): PromptIo {
+  return {
+    input: process.stdin,
+    output: process.stdout,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  };
+}
+
+async function readLine(io: PromptIo, question: string): Promise<string> {
+  const rl = createInterface({ input: io.input, output: io.output, terminal: io.interactive });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function ask(io: PromptIo, question: string, fallback?: string): Promise<string> {
+  const suffix = fallback ? ` [${fallback}]` : '';
+  const answer = await readLine(io, `${question}${suffix}: `);
+  return answer || fallback || '';
+}
+
+export async function confirm(io: PromptIo, question: string): Promise<boolean> {
+  const answer = await readLine(io, `${question} [y/N]: `);
+  return /^y(es)?$/i.test(answer);
+}
+
+/**
+ * Reads a secret from a non-interactive stream, or prompts for one.
+ *
+ * Piping a secret in is the SAFE path and is why this accepts a closed stream
+ * rather than refusing it: a token passed as a command-line argument is kept by
+ * both the shell history and the process list, so `--access-token-stdin` has to
+ * work without a terminal.
+ */
+export async function askSecret(io: PromptIo, question: string): Promise<string> {
+  if (!io.interactive) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of io.input) chunks.push(Buffer.from(chunk as Uint8Array));
+    return Buffer.concat(chunks).toString('utf8').trim();
+  }
+  // Readline echoes, so an interactive secret is read the same way and the
+  // caller is told not to expect masking rather than being silently exposed.
+  io.output.write('The value you type will be visible. Paste it, or pipe it in instead.\n');
+  return await readLine(io, `${question}: `);
+}
+
+export async function select<T extends string>(
+  io: PromptIo,
+  question: string,
+  choices: Array<{ value: T; label: string; detail?: string }>,
+): Promise<T> {
+  io.output.write(`\n${question}\n\n`);
+  choices.forEach((choice, index) => {
+    io.output.write(`  ${index + 1}) ${choice.label}\n`);
+    if (choice.detail) io.output.write(`     ${choice.detail}\n`);
+  });
+  io.output.write('\n');
+  for (;;) {
+    const answer = await readLine(io, `Choose 1-${choices.length} [1]: `);
+    const index = Number(answer || '1');
+    const choice = choices[index - 1];
+    if (choice) return choice.value;
+    io.output.write('Enter one of the listed numbers.\n');
+  }
+}