@pellux/goodvibes-tui 1.25.0 → 1.26.0

package/src/daemon/send/failure-text.ts

@@ -0,0 +1,93 @@
+/**
+ * failure-text.ts — what the operator is told when a send does not happen.
+ *
+ * ## Why this is not `summarizeError`
+ *
+ * The SDK's `summarizeError` is the right tool nearly everywhere: it classifies
+ * an error, adds a hint, and deliberately drops detail so a transcript stays
+ * readable. That is the wrong trade here, and measurably so. Given the real
+ * Telegram failure
+ *
+ *     Telegram delivery failed HTTP 401: {"ok":false,"description":"Unauthorized"}
+ *
+ * it returns `Telegram delivery failed HTTP 401` — its `stripJson` pass removes
+ * the `{...}`, which is exactly the part naming what went wrong. Given
+ * `connect ECONNREFUSED 149.154.167.220:443` it returns "Cannot connect to the
+ * provider. Check whether the service is reachable." — advice in place of the
+ * address that was refused.
+ *
+ * A person debugging a message that did not arrive needs the provider's own
+ * words: "Unauthorized", "chat not found", and "Bad Request: message is too
+ * long" have three different fixes, and all three flatten to the same summary.
+ *
+ * ## What is removed, and why that is not the same thing
+ *
+ * Detail is kept; CREDENTIALS are not. This matters more here than in most
+ * places because Telegram puts the bot token in the URL PATH
+ * (`api.telegram.org/bot<token>/sendMessage`), so a transport error that echoes
+ * the request URL would print the owner's bot token to a terminal and into
+ * whatever log or pasted report that terminal output ends up in.
+ *
+ * `redactSensitiveData` from the SDK covers the shapes it knows (bearer tokens,
+ * `sk-`/`xoxb-`/`ghp_` keys, home directories). It has NO pattern for a
+ * URL-embedded credential, so the two passes below add them. They run BEFORE
+ * the SDK pass, because a redacted string must not then be re-scanned in a way
+ * that could reveal structure.
+ */
+
+import { redactSensitiveData } from '@pellux/goodvibes-sdk/platform/utils';
+
+/**
+ * A generous cap. The point of this text is diagnosis, so it is far larger than
+ * the 240 characters `summarizeError` allows — but an HTML error page or a
+ * multi-megabyte body still must not flood the terminal.
+ */
+const MAX_FAILURE_TEXT = 2_000;
+
+const URL_CREDENTIAL_PATTERNS: ReadonlyArray<{ readonly pattern: RegExp; readonly replacement: string }> = [
+  // Telegram: the bot token IS the path segment.
+  { pattern: /\/bot\d{5,}:[A-Za-z0-9_-]{10,}/g, replacement: '/bot[REDACTED_BOT_TOKEN]' },
+  // Any URL carrying `user:password@host` — BlueBubbles, Mattermost and Matrix
+  // base URLs are all operator-supplied and can be written this way.
+  { pattern: /(\b[a-z][a-z0-9+.-]*:\/\/)[^/\s:@]+:[^/\s@]+@/gi, replacement: '$1[REDACTED_CREDENTIALS]@' },
+  // A credential passed as a query parameter — BlueBubbles sends `?password=`.
+  {
+    pattern: /([?&](?:password|token|secret|access_token|api_?key|auth)=)[^&\s"']+/gi,
+    replacement: '$1[REDACTED]',
+  },
+];
+
+/** Strip credentials this command can put on the wire but the SDK pass does not know. */
+export function redactUrlCredentials(text: string): string {
+  let result = text;
+  for (const { pattern, replacement } of URL_CREDENTIAL_PATTERNS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+/**
+ * The provider's own failure text, with credentials removed and nothing else
+ * rewritten.
+ *
+ * Never returns an empty string: an error whose message is blank still has to
+ * produce something an operator can act on, because the alternative is an exit
+ * code with no explanation beside it.
+ */
+export function describeSendFailure(error: unknown): string {
+  const raw = error instanceof Error
+    ? (error.message.trim().length > 0 ? error.message : error.name)
+    : typeof error === 'string'
+      ? error
+      : (() => { try { return JSON.stringify(error); } catch { return String(error); } })();
+  const message = typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : 'the provider failed without saying why';
+  // `cause` is where Node and Bun put the real reason for `fetch failed`, and
+  // dropping it is how a genuinely diagnosable DNS or TLS failure becomes two
+  // useless words.
+  const cause = error instanceof Error && error.cause instanceof Error && error.cause.message.trim().length > 0
+    ? ` (${error.cause.message.trim()})`
+    : '';
+  const full = `${message}${cause}`;
+  const redacted = redactSensitiveData(redactUrlCredentials(full));
+  return redacted.length <= MAX_FAILURE_TEXT ? redacted : `${redacted.slice(0, MAX_FAILURE_TEXT)}…`;
+}

package/src/daemon/send/inert-text.ts

@@ -0,0 +1,225 @@
+/**
+ * inert-text.ts — make a message arrive as LITERAL TEXT on whichever channel
+ * `goodvibes-daemon send` delivers it to.
+ *
+ * ## What "inert" means here, and why it is per (surface × transport), not
+ * per surface
+ *
+ * The transform a surface needs depends on what the delivery strategy in
+ * `platform/channels/delivery/strategies-core.ts` actually does with the body,
+ * not on what the surface is capable of parsing. Two examples that pull in
+ * opposite directions:
+ *
+ *  - Telegram's `sendMessage` CAN parse MarkdownV2, but the strategy sends with
+ *    NO `parse_mode`, which is Telegram's plain-text mode. Running a MarkdownV2
+ *    escaper over the body on this path would not protect anything — it would
+ *    put visible backslashes in front of every `.` `-` `!` `(` in the owner's
+ *    message. The correct transform is identity, and the property that makes it
+ *    correct is asserted by a test against the real wire payload rather than
+ *    asserted here in prose (see src/test/daemon/send-command-wire.test.ts).
+ *
+ *  - Discord's `postMessage` renders markdown unconditionally, INCLUDING masked
+ *    links, so the same body needs real escaping.
+ *
+ * A single "escape for channel X" table that ignored the transport would get
+ * Telegram wrong in the direction that mangles the owner's text, and would get
+ * Discord wrong in the direction that renders a link. Hence the split below.
+ *
+ * ## Provenance of the escaper bodies
+ *
+ * `escapeDiscordMarkdown` and `escapeSlackMrkdwn` are the escapers written for
+ * the inbound-mail structured notices, in the SDK at
+ * `packages/sdk/src/platform/email/inbound-notice.ts` — same character classes,
+ * same zero-width-space mention break, same rationale. They are reproduced here
+ * rather than imported for one reason: that module lives on the unmerged
+ * `inbound-email-*` branches and is absent from the published
+ * `@pellux/goodvibes-sdk@1.18.1` this product consumes, so there is nothing to
+ * import yet.
+ *
+ * This is a second copy and that is a defect, not a design. When the
+ * inbound-mail round merges and an SDK release publishes `platform/email`'s
+ * notice escapers, THIS FILE'S `escapeDiscordMarkdown` and `escapeSlackMrkdwn`
+ * are to be deleted and the SDK's imported in their place; the surface-kind
+ * table below is the only part that should survive that change. The behaviour
+ * is pinned by tests either way, so the swap is verifiable rather than hopeful.
+ */
+
+import type { ChannelDeliverySurfaceKind } from '@pellux/goodvibes-sdk/platform/channels';
+
+/**
+ * Zero-width space. Used to break a token that a surface would otherwise read
+ * as syntax, on surfaces that offer no backslash escape (Slack) or where
+ * backslash-escaping demonstrably does not defeat the token (Discord mentions).
+ */
+const ZERO_WIDTH_SPACE = '​';
+
+/**
+ * `@everyone`, `@here`, and raw role/channel/user mentions. Backslash-escaping
+ * the `@` does NOT reliably suppress these in every Discord client, so the
+ * zero-width break is used instead.
+ */
+function breakMentionForms(text: string): string {
+  return text
+    .replace(/@(everyone|here)/g, (_match, word: string) => `@${ZERO_WIDTH_SPACE}${word}`)
+    .replace(/<@[!&]?(\d+)>/g, (_match, id: string) => `<@${ZERO_WIDTH_SPACE}${id}>`)
+    .replace(/<#(\d+)>/g, (_match, id: string) => `<#${ZERO_WIDTH_SPACE}${id}>`);
+}
+
+/**
+ * Discord markdown. Backslash-escaping `* _ ~ \` |` and `>` renders each as its
+ * literal character rather than triggering bold/italic/strikethrough/code/
+ * spoiler/quote.
+ *
+ * `[` `]` `(` `)` are escaped too, and this is REQUIRED rather than
+ * precautionary: masked links (`[text](url)`) DO render as clickable in
+ * bot-sent and webhook messages — which is exactly how this product delivers to
+ * Discord — even though they do not render for text a human typed into the
+ * client.
+ *   https://github.com/discord/discord-api-docs/issues/6096
+ *   https://gist.github.com/matthewzring/9f7bbfd102003963f9be7dbcf7d40e51
+ *
+ * Without this, a message body assembled from anything the owner did not type
+ * arrives in his Discord as a clickable link reading whatever the body said.
+ * An escaper that looks optional gets tidied away by the next reader: it is not
+ * optional, and it stays.
+ *
+ * `\` is inside the character class, so a backslash in the input is escaped
+ * first and cannot un-escape what follows it.
+ */
+function escapeDiscordMarkdown(text: string): string {
+  return breakMentionForms(text.replace(/[*_~`|>[\]()\\]/g, (ch) => `\\${ch}`));
+}
+
+/**
+ * Slack mrkdwn. `&`, `<`, `>` MUST be HTML-entity-escaped per Slack's own
+ * formatting reference. That is also what defeats `<url|text>` link syntax and
+ * `<!channel>` / `<@id>` mention syntax outright, since both require a literal
+ * unescaped `<`.
+ *
+ * Slack has no backslash escape for `* _ ~ \``, so the zero-width break is
+ * applied to those as the best available mitigation — stated as a mitigation,
+ * not a guarantee, because Slack's whitespace-adjacency rule for what breaks a
+ * delimiter pair is not publicly specified to that precision. The residual risk
+ * is cosmetic (accidental bold/italic); the injection class this exists to
+ * close — a clickable link or a real mention — is closed by the entity escaping
+ * above.
+ */
+function escapeSlackMrkdwn(text: string): string {
+  const entityEscaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return entityEscaped.replace(/[*_~`]/g, (ch) => `${ch}${ZERO_WIDTH_SPACE}`);
+}
+
+/**
+ * Google Chat's `text` field renders `*bold*`, `_italic_`, `~strike~`,
+ * `` `code` `` and `<url|text>` links. The `<` entity escape is what defeats
+ * the link and `<users/all>` mention forms; the delimiters get the zero-width
+ * break, as Google Chat documents no backslash escape either.
+ */
+function escapeGoogleChatMarkup(text: string): string {
+  const entityEscaped = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return entityEscaped.replace(/[*_~`]/g, (ch) => `${ch}${ZERO_WIDTH_SPACE}`);
+}
+
+/**
+ * WhatsApp Cloud API text messages render `*bold*`, `_italic_`, `~strike~` and
+ * ```` ```mono``` ````. There is no masked-link syntax — a URL in the body is
+ * auto-linked showing its real address — so the injection class Discord has
+ * does not exist here and only the delimiters need neutralizing. WhatsApp
+ * documents no backslash escape, so the zero-width break is used.
+ */
+function escapeWhatsAppMarkup(text: string): string {
+  return text.replace(/[*_~`]/g, (ch) => `${ch}${ZERO_WIDTH_SPACE}`);
+}
+
+/**
+ * The surfaces whose delivery strategy hands the body to a renderer that parses
+ * markup. Every other routable surface is absent DELIBERATELY, and each absence
+ * is a checked claim about the strategy, not an oversight:
+ *
+ *  - `telegram`  — `sendMessage` without `parse_mode`; Telegram's plain-text
+ *                  mode. Escaping here would corrupt, not protect.
+ *  - `ntfy`      — `publish` sends the body as `text/plain` and never sets the
+ *                  `Markdown` header, so ntfy renders it literally. The title
+ *                  is derived by `titleFromBody` (first non-empty LINE) and
+ *                  passed through `toHeaderSafeTitle`, so no line break or
+ *                  non-ASCII byte from the body can reach an HTTP header.
+ *  - `webhook`   — the body is a JSON string field; the receiver decides what
+ *                  to do with it and there is no markup layer to neutralize.
+ *
+ *  - `signal`    — the strategy posts `text` to a signal bridge. Signal renders
+ *                  no markup in a plain message body; styling travels as
+ *                  explicit range metadata the strategy never sends.
+ *  - `imessage`,
+ *    `bluebubbles` — both end at iMessage, which renders no markup at all.
+ *  - `msteams`   — the strategy sends `textFormat: 'plain'` alongside the text,
+ *                  which is Teams' own instruction not to parse it.
+ *  - `matrix`    — `msgtype: 'm.text'` with no `format`/`formatted_body`. A
+ *                  Matrix event without the HTML format field is rendered
+ *                  literally by clients, per the spec.
+ *
+ * `web` is absent for a different reason: its strategy needs a live
+ * `ControlPlaneGateway` in the same process, which a short-lived CLI does not
+ * have, so the command does not offer it as a channel at all. `telephony` is
+ * absent because a CLI `send` to it would place a phone call or an SMS through
+ * a paid carrier — a different act from messaging a channel — and because the
+ * strategy already XML-escapes the voice path itself via `escapeTwiml`.
+ */
+const INERT_TRANSFORMS: Partial<Record<ChannelDeliverySurfaceKind, (text: string) => string>> = {
+  // Renders markup, including a masked link: full escaping.
+  discord: escapeDiscordMarkdown,
+  mattermost: escapeDiscordMarkdown,
+  // Renders markup, but has no masked-link syntax: delimiters only.
+  slack: escapeSlackMrkdwn,
+  'google-chat': escapeGoogleChatMarkup,
+  whatsapp: escapeWhatsAppMarkup,
+  // Delivered as plain text by the strategy: transforming would corrupt, not
+  // protect. Each of these is a checked claim about the strategy, not a guess —
+  // see the list above.
+  telegram: (text) => text,
+  ntfy: (text) => text,
+  webhook: (text) => text,
+  signal: (text) => text,
+  imessage: (text) => text,
+  bluebubbles: (text) => text,
+  msteams: (text) => text,
+  matrix: (text) => text,
+};
+
+/** Surfaces `goodvibes-daemon send` will deliver to, in a stable display order. */
+export const INERT_RENDERABLE_SURFACE_KINDS: readonly ChannelDeliverySurfaceKind[] = [
+  'telegram', 'ntfy', 'discord', 'slack', 'google-chat', 'webhook',
+  'signal', 'whatsapp', 'imessage', 'msteams', 'bluebubbles', 'mattermost', 'matrix',
+];
+
+/**
+ * Whether this surface has a verified inert transform.
+ *
+ * A surface with no entry gets a refusal from the send command, never an
+ * untransformed body. Returning the body unchanged for an unknown surface is
+ * precisely how a markup-rendering channel acquires a live link: the default
+ * has to be "refuse", and it has to be checkable from the caller.
+ */
+export function canRenderInert(surfaceKind: ChannelDeliverySurfaceKind): boolean {
+  return Object.prototype.hasOwnProperty.call(INERT_TRANSFORMS, surfaceKind);
+}
+
+/**
+ * Render `text` so it arrives on `surfaceKind` as the literal characters the
+ * caller supplied.
+ *
+ * Throws for a surface with no verified transform. This function has no
+ * "pass it through" branch and must never grow one: every caller of the send
+ * command reaches the world through here, so a permissive fallback would make
+ * the command a way to put live markup on the owner's phone.
+ */
+export function inertBodyFor(surfaceKind: ChannelDeliverySurfaceKind, text: string): string {
+  const transform = INERT_TRANSFORMS[surfaceKind];
+  if (!transform) {
+    throw new Error(
+      `No verified inert-text transform for surface '${surfaceKind}'. `
+      + 'Sending would risk the message being rendered as markup rather than as text, '
+      + `so nothing was sent. Supported: ${INERT_RENDERABLE_SURFACE_KINDS.join(', ')}.`,
+    );
+  }
+  return transform(text);
+}

package/src/daemon/send/stdin.ts

@@ -0,0 +1,24 @@
+/**
+ * stdin.ts — read the whole of stdin as the message body.
+ *
+ * Kept out of command.ts so the command stays a pure function of its arguments
+ * and its injected dependencies: every test drives it with a stub rather than
+ * having to arrange a real pipe on the process running the suite.
+ */
+
+/**
+ * Read stdin to end, as UTF-8.
+ *
+ * There is deliberately no timeout. `send` reads stdin only when the operator
+ * gave no message argument AND stdin is not a terminal — meaning something is
+ * piping into it — so waiting for that producer to finish is the correct
+ * behaviour, and cutting it off at an arbitrary deadline would silently
+ * truncate a long message.
+ */
+export async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}

package/src/input/commands/config.ts

@@ -1,6 +1,13 @@
-import type { CommandRegistry } from '../command-registry.ts';
+import type { CommandContext, CommandRegistry } from '../command-registry.ts';
 import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
 import { setActiveThemeMode, type ThemeMode } from '../../renderer/theme.ts';
+import {
+  buildGoodVibesSecretKey,
+  defaultSecretBackedScope,
+  isSecretConfigKey,
+  persistSecretBackedConfigValue,
+} from '../../config/secret-config.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 export function registerConfigCommand(registry: CommandRegistry): void {
   registry.register({
@@ -9,7 +16,7 @@ export function registerConfigCommand(registry: CommandRegistry): void {
     description: 'Open the fullscreen configuration workspace, or set a key directly',
     usage: '[category|key] | set <key> <value>',
     argsHint: '[category|key] | set <key> <value>',
-    handler(args, ctx) {
+    async handler(args, ctx) {
       // An earlier replay fix: `/config set <key> <value>` used to fall through to
       // the workspace with the assignment silently ignored — the dishonest-
       // fallthrough class. `set` is now a real verb.
@@ -20,6 +27,17 @@ export function registerConfigCommand(registry: CommandRegistry): void {
           ctx.print('Usage: /config set <key> <value> — e.g. /config set display.themeMode light');
           return;
         }
+        // A credential key must never take the generic path below: setDynamic
+        // writes the value it is handed straight into a settings JSON file, so
+        // `/config set surfaces.email.password hunter2` used to put the mailbox
+        // password in cleartext on disk. The settings modal already routes these
+        // keys through the secret manager (settings-modal-secrets.ts); this
+        // command has to route them the same way, or the two ways of setting the
+        // same key disagree about where the value lands.
+        if (isSecretConfigKey(key)) {
+          await handleSecretConfigSet(ctx, key as ConfigKey, value);
+          return;
+        }
         try {
           const before = ctx.platform.configManager.get(key as ConfigKey);
           ctx.platform.configManager.setDynamic(key as ConfigKey, coerceConfigValue(value));
@@ -49,6 +67,54 @@ export function registerConfigCommand(registry: CommandRegistry): void {
   });
 }
 
+/**
+ * Store a credential-bearing config key through the secret manager instead of
+ * writing it into a config file: the value goes to the secret store and the
+ * config key keeps only a `goodvibes://secrets/...` reference to it.
+ *
+ * The entered value is never echoed. The transcript is a diagnostic surface —
+ * it is scrolled back through, copied into support threads and captured in
+ * screen recordings — so it gets the reference and the store key, never the
+ * secret.
+ *
+ * With no secret manager in this runtime there is nowhere safe to put it, and
+ * the command REFUSES rather than falling back to a plaintext config write.
+ */
+async function handleSecretConfigSet(
+  ctx: CommandContext,
+  key: ConfigKey,
+  value: string,
+): Promise<void> {
+  const secretKey = buildGoodVibesSecretKey(key);
+  const secretsManager = ctx.platform?.secretsManager;
+  if (!secretsManager) {
+    ctx.print(
+      `${key} holds a credential, and this runtime has no secret store to put it in — `
+      + `refusing rather than writing it in cleartext into a config file.\n`
+      + `  Store it with: /secrets set ${secretKey} <value>`,
+    );
+    return;
+  }
+  try {
+    const configValue = await persistSecretBackedConfigValue(
+      ctx.platform.configManager,
+      secretsManager,
+      key,
+      value,
+    );
+    const scope = defaultSecretBackedScope(key);
+    ctx.print(
+      `Set ${key}: stored in the ${scope} secret tier as ${secretKey} (value hidden).\n`
+      + `  ${key} now holds the reference ${configValue} — the value itself is never written to a config file.`
+      + (scope === 'daemon'
+        ? '\n  The daemon reads that tier, so this keeps working with this client closed.'
+        : ''),
+    );
+  } catch (e) {
+    ctx.print(`Could not set ${key}: ${summarizeError(e)}`);
+  }
+}
+
 /** Coerce CLI text to the JSON-ish scalar the config schema expects. */
 function coerceConfigValue(raw: string): unknown {
   if (raw === 'true') return true;

package/src/input/commands/local-provider-runtime.ts

@@ -130,7 +130,15 @@ export function registerLocalProviderRuntimeCommands(registry: CommandRegistry):
               }
               void (async () => {
                 try {
-                  await secretsManager.set(keyName, value, { scope: 'user', medium: 'secure' });
+                  // Daemon scope, stated explicitly here rather than left to the
+                  // platform's daemon-owned credential registry: that registry
+                  // recognises credentials by NAME, and this name is derived
+                  // from an operator-chosen provider name
+                  // (customProviderKeyName above), so no shipped list can
+                  // contain it. The daemon is what runs the model, so the key
+                  // has to reach the daemon tier or a locally-hosted endpoint
+                  // is usable only while this TUI is open.
+                  await secretsManager.set(keyName, value, { scope: 'daemon', medium: 'secure' });
                   ctx.print(`Stored the API key for '${name}' (value hidden). It resolves live for this provider — no restart needed.`);
                 } catch (error) {
                   ctx.print(`Could not store the key for '${name}': ${summarizeError(error)}`);

package/src/input/commands/operator-runtime.ts

@@ -65,7 +65,12 @@ export function registerOperatorRuntimeCommands(registry: CommandRegistry): void
 
   registry.register({
     name: 'profiles',
-    aliases: ['profile'],
+    // The singular `profile` alias was given up to /profile, the owner profile
+    // (docs/owner-profile.md). These are two unrelated things — this command
+    // loads saved display/provider settings presets, and the other one is what
+    // the platform knows about the person who owns it — and the singular word
+    // now belongs to the second. `/profiles` is unchanged; only the abbreviation
+    // moved. See the naming note in docs/owner-profile.md §3.
     description: 'Browse and load config profiles',
     handler(_args, ctx) {
       if (ctx.openProfilePicker) {

package/src/input/commands/payment-card-intake.ts

@@ -0,0 +1,200 @@
+/**
+ * /payments card — capture a payment card through the composer's concealed
+ * input mode, following the same guided-chain pattern as /channel pair
+ * (channel-pairing.ts) and the SAME concealed-input mechanism as
+ * provider-key-intake.ts (see concealed-input.ts).
+ *
+ * Card number, expiry, CVV, and cardholder name are secret-tier (see
+ * config/secret-config.ts's SECRET_CONFIG_KEYS): each is entered through one
+ * masked concealed-input prompt in turn and stored via
+ * persistSecretBackedConfigValue, the same secret-manager + config-reference
+ * path every other secret-backed setting in this app uses. The plaintext
+ * never reaches the transcript, input history, or a log line — only a
+ * redacted confirmation is printed after each field.
+ *
+ * Billing and shipping address are ordinary (non-secret) config fields, now
+ * real structured CONFIG_SCHEMA entries (payments.billingAddress.{name,
+ * line1, line2, city, region, postalCode, country} and the shippingAddress
+ * equivalents) — this command points the user at the Payments settings
+ * category (or /config payments) to set them, the same way /channel pair
+ * directs non-secret credential fields, rather than routing plain text
+ * through the concealed (masked) input path where it does not belong.
+ *
+ * Stored with `scope: 'daemon'`: the daemon — not just this interactive
+ * client — is what completes an autonomous purchase, so the credential must
+ * land in the daemon-scoped secret tier the daemon actually reads.
+ *
+ * The config-reference half (the `goodvibes://secrets/...` marker
+ * persistSecretBackedConfigValue writes alongside the secret) goes through
+ * `ctx.platform.configManager` directly — the same real ConfigManager every
+ * other command in this app uses, not a TUI-local store. See
+ * payments-config.ts's header comment for why these particular keys
+ * (`payments.cardNumber`, etc., flat sub-keys under the SDK's real
+ * `payments` section) are ConfigManager-safe even though the SDK's
+ * CONFIG_SCHEMA has no scalar entry for them yet: `payments.` is a
+ * daemon-owned config prefix, so the reference lands in the daemon's own
+ * settings file and is visible to the daemon, the webui and the agent —
+ * not just this TUI session.
+ *
+ * ── Card details are entered only at a local terminal or the webui ────────
+ *
+ * Owner ruling (see the SDK's platform/payments/entry-surface.ts): card
+ * material may be TYPED only on `tui`, `agent-terminal`, or `webui` — never
+ * over Telegram, ntfy, Discord, Slack, WhatsApp, Signal, a webhook, or any
+ * other remote messaging surface. A card number typed into a hosted chat is
+ * stored on that provider's own servers, in history this app cannot erase,
+ * and it already passed through their infrastructure before reaching us —
+ * our own encryption at rest does nothing for a value copied elsewhere on
+ * its way in. This is a SEPARATE question from which surfaces may APPROVE or
+ * VETO a purchase (every command-authority channel still can); the two are
+ * never merged into one check.
+ *
+ * This command always runs inside the TUI's own composer (CARD_ENTRY_SURFACE
+ * below), which the SDK's allowlist accepts — so this gate changes nothing
+ * about today's behavior. What it buys is that the refusal already exists
+ * the moment this app (or a shared command registry) ever grows a path that
+ * lets `/payments card` be reached from somewhere else: the check is real
+ * and SDK-driven, not an implicit "this is the TUI so it's fine" assumption.
+ */
+
+import type { CommandRegistry, CommandContext } from '../command-registry.ts';
+import { persistSecretBackedConfigValue } from '../../config/secret-config.ts';
+import type { ConfigKey } from '../../config/index.ts';
+import { describeCardEntryRefusal, mayOfferCardEntryFlow } from '@pellux/goodvibes-sdk/platform/payments';
+import {
+  PAYMENTS_CARD_NUMBER_CONFIG_KEY,
+  PAYMENTS_CARD_EXPIRY_CONFIG_KEY,
+  PAYMENTS_CARD_CVV_CONFIG_KEY,
+  PAYMENTS_CARD_CARDHOLDER_NAME_CONFIG_KEY,
+} from '../payments-config.ts';
+
+/**
+ * This command is wired only into the TUI's own composer command registry —
+ * it is never reachable from a channel bridge (Telegram, Discord, ...), each
+ * of which has its own separate command surface in the daemon. The constant
+ * still names the surface explicitly and is checked through the SDK's own
+ * allowlist below, rather than skipping the check because "this is the TUI".
+ */
+export const CARD_ENTRY_SURFACE = 'tui';
+
+interface CardField {
+  readonly key: ConfigKey;
+  readonly label: string;
+  readonly placeholder: string;
+}
+
+/** Order matters only for the guided prompt sequence, not for storage. */
+const CARD_SECRET_FIELDS: readonly CardField[] = [
+  { key: PAYMENTS_CARD_NUMBER_CONFIG_KEY, label: 'Card number', placeholder: '4242424242424242' },
+  { key: PAYMENTS_CARD_EXPIRY_CONFIG_KEY, label: 'Expiry (MM/YY)', placeholder: '12/34' },
+  { key: PAYMENTS_CARD_CVV_CONFIG_KEY, label: 'CVV', placeholder: '123' },
+  { key: PAYMENTS_CARD_CARDHOLDER_NAME_CONFIG_KEY, label: 'Cardholder name', placeholder: 'as printed on the card' },
+];
+
+function fieldConfigured(ctx: CommandContext, field: CardField): boolean {
+  const raw: unknown = ctx.platform.configManager.get(field.key);
+  return typeof raw === 'string' && raw.trim().length > 0;
+}
+
+function renderCardStatus(ctx: CommandContext): string[] {
+  const lines = ['Payment card on file:'];
+  for (const field of CARD_SECRET_FIELDS) {
+    lines.push(`  ${field.label.padEnd(20)} ${fieldConfigured(ctx, field) ? 'set' : 'not set'}`);
+  }
+  lines.push('');
+  lines.push('Run /payments card to enter or replace the card (masked input, chained prompts).');
+  lines.push('Billing/shipping address, budgets, windows and the rest of the payment capability are ordinary config values: set them via /config payments or the Settings > Payments category.');
+  return lines;
+}
+
+/** Chain a masked prompt for each card secret field, storing each through the daemon-scoped secret tier. */
+function promptCardFields(ctx: CommandContext, fields: readonly CardField[], index: number): void {
+  if (index >= fields.length) {
+    ctx.print('\nCard stored. Billing/shipping address and the rest of the payment capability are ordinary config values — set them via /config payments or the Settings > Payments category.');
+    ctx.renderRequest();
+    return;
+  }
+  const field = fields[index]!;
+  if (!ctx.beginConcealedInput) {
+    ctx.print('[payments] Concealed input is unavailable on this surface; card entry requires it and cannot fall back to plaintext.');
+    return;
+  }
+  ctx.print(`[payments] Enter ${field.label} (e.g. ${field.placeholder}) — masked; Enter to store, Esc to stop.`);
+  ctx.beginConcealedInput({
+    label: field.label,
+    onSubmit: (value) => {
+      if (value.length === 0) {
+        ctx.print(`[payments] ${field.label} left unset.`);
+        promptCardFields(ctx, fields, index + 1);
+        return;
+      }
+      void persistSecretBackedConfigValue(
+        ctx.platform.configManager,
+        ctx.platform.secretsManager,
+        field.key,
+        value,
+        { scope: 'daemon' },
+      )
+        .then(() => {
+          ctx.print(`[payments] ${field.label} stored securely (hidden).`);
+          promptCardFields(ctx, fields, index + 1);
+        })
+        .catch((error: unknown) => {
+          ctx.print(`[payments] Failed to store ${field.label}: ${error instanceof Error ? error.message : String(error)}`);
+          promptCardFields(ctx, fields, index + 1);
+        });
+    },
+    onCancel: () => {
+      ctx.print(`[payments] Stopped. Re-run /payments card to finish the remaining fields.`);
+    },
+  });
+}
+
+/**
+ * Start the card-entry flow, gated on the SDK's own entry-surface allowlist
+ * rather than an assumption baked into this command. `surface` defaults to
+ * this command's real, fixed identity (CARD_ENTRY_SURFACE) — exposed as a
+ * parameter only so tests can drive the refusal path without needing this
+ * app to actually be reachable from a remote channel.
+ */
+export function startCardEntryFlow(ctx: CommandContext, surface: string = CARD_ENTRY_SURFACE): void {
+  if (!mayOfferCardEntryFlow(surface)) {
+    ctx.print(describeCardEntryRefusal(surface));
+    return;
+  }
+  if (!ctx.beginConcealedInput) {
+    ctx.print('[payments] Concealed input is unavailable on this surface.');
+    return;
+  }
+  ctx.print(`Entering ${CARD_SECRET_FIELDS.length} card field(s) — masked; Esc to stop at any point.`);
+  promptCardFields(ctx, CARD_SECRET_FIELDS, 0);
+}
+
+/** Entry point for `/payments [card|status]` — exported directly so tests can drive it without the registry. */
+export function runPaymentsCommand(args: readonly string[], ctx: CommandContext): void {
+  const sub = (args[0] ?? '').toLowerCase();
+  if (sub === '' || sub === 'status') {
+    ctx.print(renderCardStatus(ctx).join('\n'));
+    return;
+  }
+  if (sub === 'card') {
+    startCardEntryFlow(ctx);
+    return;
+  }
+  ctx.print('Usage: /payments [card|status]');
+}
+
+/** Card secret fields in prompt order — exported for tests that need to drive the chain field-by-field. */
+export { CARD_SECRET_FIELDS };
+
+export function registerPaymentCardCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'payments',
+    description: 'Payment card on file for daemon-initiated purchases (card entry is masked input)',
+    usage: '/payments [card]',
+    argsHint: '[card]',
+    handler(args, ctx) {
+      runPaymentsCommand(args, ctx);
+    },
+  });
+}