@pellux/goodvibes-tui 1.24.2 → 1.26.0

package/src/input/commands/profile-types.ts

@@ -0,0 +1,381 @@
+/**
+ * profile-types.ts
+ *
+ * Response shapes for the owner-profile control-plane verbs (`profile.*`), and
+ * the runtime checks that turn an untyped daemon response into one of them.
+ *
+ * ## The shapes come from the contract, not from a copy of it
+ *
+ * Every type below is derived from `OperatorMethodOutput<'profile.…'>` — the
+ * types generated from the SDK's own output schemas
+ * (`platform/control-plane/method-catalog-owner-profile.ts`). Nothing here
+ * restates a field name, so this file cannot drift from the contract: if a
+ * verb's shape changes, the checkers stop compiling against it.
+ *
+ * ## Why the responses are still checked at runtime
+ *
+ * A generated type is a compile-time claim about what the wire *should* carry,
+ * and nothing enforces it at runtime here. The operator client's
+ * `validateResponses` defaults on, but it only validates method ids with a
+ * matching exported Zod schema and `buildSchemaRegistry` silently skips the
+ * rest. Measured against the installed contracts package: 5 of 452 method ids
+ * have one, and no `profile.*` verb is among them. So response validation is
+ * not a safety net this command can lean on — for these verbs or for most
+ * others.
+ *
+ * So a daemon on a different version — or a 200 from something that is not this
+ * daemon at all — would otherwise reach a renderer and throw on a missing array,
+ * which in a slash command means a stack trace instead of an answer. Each `toX`
+ * function does the cast to `Record<string, unknown>` in ONE place, checks every
+ * property a renderer will read, and returns {@link MALFORMED} when anything is
+ * off. The command then prints an honest "this build does not recognise that
+ * response" line.
+ *
+ * A malformed *member* fails the whole response rather than being filtered out.
+ * Silently dropping a section or a line the checker did not recognise would be
+ * the same failure §4.4 forbids in the parser: content disappearing without
+ * anyone being told.
+ */
+import type { OperatorMethodInput, OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+
+/** Returned by every checker when the response does not match the contract. */
+export const MALFORMED: unique symbol = Symbol('malformed-profile-response');
+export type Checked<T> = T | typeof MALFORMED;
+
+/** The verbs this command calls. Typing the ids is what types the inputs. */
+export type ProfileReadVerb = 'profile.read' | 'profile.provenance' | 'profile.status';
+export type ProfileWriteVerb = 'profile.set' | 'profile.append' | 'profile.forget' | 'profile.undo';
+export type ProfileVerb = ProfileReadVerb | ProfileWriteVerb;
+
+/** The contract's own input shape for a verb, so a wrong field name will not compile. */
+export type ProfileInput<TVerb extends ProfileVerb> = OperatorMethodInput<TVerb>;
+
+/**
+ * Every key of every member of a union. `keyof` on a union yields only the keys
+ * the members SHARE, so a union target would be checked against that
+ * intersection and would wave through a key belonging to a sibling verb.
+ */
+type UnionKeys<T> = T extends unknown ? keyof T : never;
+
+/**
+ * Reject a key the contract does not declare, including on a body that is not a
+ * fresh object literal.
+ *
+ * DO NOT "simplify" this away to plain parameter typing. It is load-bearing,
+ * not a belt-and-braces backstop, and the measurements say which cases it
+ * carries alone. Four ways a stale key can arrive, all compiled against this
+ * repo's TypeScript with a `profile.forget`-shaped input:
+ *
+ *   1. written inline in a fresh literal      — parameter typing already rejects
+ *   2. written inline BESIDE a spread         — parameter typing already rejects
+ *   3. body built as a variable first         — SLIPS PAST parameter typing
+ *   4. carried in by the spread source's type — SLIPS PAST parameter typing
+ *
+ * A spread literal is not uniformly unchecked, which is the easy thing to get
+ * wrong: anything written inline in one is still checked normally, and only what
+ * arrives THROUGH the spread escapes, because it belongs to the source's type
+ * rather than to the literal. Rows 3 and 4 are the two nothing else catches, and
+ * this guard rejects both with TS2345 — measured, not reasoned about.
+ *
+ * That is not hypothetical: `profile.forget` really did retire `lineIndex`, and
+ * a body built one line earlier would have carried it silently past a correctly
+ * typed parameter. Seeding inline literals proves only the cases someone thought
+ * to seed; this closes the shape.
+ *
+ * There is a second reason it earns its place here. The SDK's `invoke` is
+ * OVERLOADED — a typed signature plus a loose
+ * `invoke<T = unknown>(methodId: string, input?: Record<string, unknown>)`. At a
+ * bare call site a body the typed overload rejects does not raise an
+ * excess-property error at all; overload resolution simply falls through to the
+ * loose one and the result degrades to `unknown`. Any error is then incidental,
+ * downstream, and disappears entirely if the caller ignores or casts the result.
+ * `ProfileInvoke` is a single generic signature with no such fallback, so a bad
+ * body fails here, at the call, naming the offending key.
+ *
+ * Intersecting the parameter with this maps every undeclared key to `never`, so
+ * no real value satisfies it however the object was built. Distributed over the
+ * target union via {@link UnionKeys} so each member is checked rather than only
+ * the keys they have in common.
+ */
+export type NoExcessKeys<TBody, TShape> = Record<Exclude<keyof TBody, UnionKeys<TShape>>, never>;
+
+/** A body that conforms to a verb's declared input and carries nothing extra. */
+export type ExactProfileInput<TVerb extends ProfileVerb, TBody> =
+  TBody & NoExcessKeys<TBody, ProfileInput<TVerb>>;
+
+/** What `profile.read` answers: the whole document, by section. */
+export type ProfileDocumentView = OperatorMethodOutput<'profile.read'>;
+
+/**
+ * Load state — what `profile.status` answers, and the `state` half of a read.
+ *
+ * `kind` is `loaded` | `unavailable` | `disabled`. The counts belong to
+ * `loaded` and `reason` to `unavailable`. There is no value property anywhere
+ * in this shape, which is what makes the status output safe to show in a
+ * diagnostic context (§11.3).
+ */
+export type ProfileStateView = OperatorMethodOutput<'profile.status'>;
+
+/** What `profile.provenance` answers for one field. */
+export type ProfileProvenanceReportView = OperatorMethodOutput<'profile.provenance'>;
+
+/** What every write verb answers. `ok: false` always carries a reason. */
+export type ProfileWriteResultView = OperatorMethodOutput<'profile.set'>;
+
+/** One `## ` section, with the tier its content belongs to. */
+export type ProfileSectionView = ProfileDocumentView['sections'][number];
+/** One mechanical field. `valid: false` still carries the value — see §4.3. */
+export type ProfileFieldView = ProfileSectionView['fields'][number];
+/** One prose line, preserved as written. */
+export type ProfileLineView = ProfileSectionView['prose'][number];
+/** Where a line came from: which surface, when, and the owner's exact words. */
+export type ProfileProvenanceView = NonNullable<ProfileFieldView['provenance']>;
+/** A mechanical value that did not validate, and why. Never fails the file. */
+export type ProfileInvalidFieldView = NonNullable<ProfileStateView['invalidFields']>[number];
+/** A retained `<!-- was: … -->` predecessor, so a wrong correction is recoverable. */
+export type ProfileSupersededView = ProfileProvenanceReportView['superseded'][number];
+/** One thing a write did. Names the field; never repeats the value. */
+export type ProfileChangeView = ProfileWriteResultView['changes'][number];
+
+/**
+ * Compile-time proof of two things this file assumes: that all four write verbs
+ * really do answer one shape, and that `profile.status` really is the same
+ * `state` a read carries.
+ *
+ * One write checker serves four verbs and `toProfileState` checks both the
+ * status response and a read's `state`. If the contract ever splits them,
+ * `Exact` collapses to `never` and this assignment stops compiling, rather than
+ * the difference going unnoticed until a response renders wrong.
+ */
+type Exact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
+export const PROFILE_CONTRACT_SHAPES_AGREE: Exact<OperatorMethodOutput<'profile.append'>, ProfileWriteResultView>
+  & Exact<OperatorMethodOutput<'profile.forget'>, ProfileWriteResultView>
+  & Exact<OperatorMethodOutput<'profile.undo'>, ProfileWriteResultView>
+  & Exact<ProfileDocumentView['state'], ProfileStateView> = true;
+
+// ---------------------------------------------------------------------------
+// Primitive checks
+// ---------------------------------------------------------------------------
+
+/** The single place an untyped response is narrowed to an indexable object. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  return value as unknown as Record<string, unknown>;
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/** Absent and null both mean "not supplied"; anything else must be a string. */
+function optionalString(value: unknown): Checked<string | undefined> {
+  if (value === undefined || value === null) return undefined;
+  return isString(value) ? value : MALFORMED;
+}
+
+function optionalBoolean(value: unknown): Checked<boolean | undefined> {
+  if (value === undefined || value === null) return undefined;
+  return isBoolean(value) ? value : MALFORMED;
+}
+
+function optionalNumber(value: unknown): Checked<number | undefined> {
+  if (value === undefined || value === null) return undefined;
+  return isFiniteNumber(value) ? value : MALFORMED;
+}
+
+/** An array whose every member checks out, or MALFORMED. Never a filtered subset. */
+function checkedArray<T>(value: unknown, check: (entry: unknown) => Checked<T>): Checked<T[]> {
+  if (!Array.isArray(value)) return MALFORMED;
+  const out: T[] = [];
+  for (const entry of value) {
+    const parsed = check(entry);
+    if (parsed === MALFORMED) return MALFORMED;
+    out.push(parsed);
+  }
+  return out;
+}
+
+function checkedStringArray(value: unknown): Checked<string[]> {
+  return checkedArray(value, (entry) => (isString(entry) ? entry : MALFORMED));
+}
+
+// ---------------------------------------------------------------------------
+// Response checks
+// ---------------------------------------------------------------------------
+
+function toProvenance(value: unknown): Checked<ProfileProvenanceView | undefined> {
+  if (value === undefined || value === null) return undefined;
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { surface, date, said } = record;
+  if (!isString(surface) || !isString(date) || !isString(said)) return MALFORMED;
+  return { surface, date, said };
+}
+
+function toLine(value: unknown): Checked<ProfileLineView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { lineIndex, section, text } = record;
+  if (!isFiniteNumber(lineIndex) || !isString(section) || !isString(text)) return MALFORMED;
+  const provenance = toProvenance(record.provenance);
+  if (provenance === MALFORMED) return MALFORMED;
+  return { lineIndex, section, text, ...(provenance ? { provenance } : {}) };
+}
+
+function toField(value: unknown): Checked<ProfileFieldView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { fieldId, label, value: fieldValue, valid } = record;
+  if (!isString(fieldId) || !isString(label) || !isString(fieldValue) || !isBoolean(valid)) return MALFORMED;
+  const invalidReason = optionalString(record.invalidReason);
+  if (invalidReason === MALFORMED) return MALFORMED;
+  const provenance = toProvenance(record.provenance);
+  if (provenance === MALFORMED) return MALFORMED;
+  return {
+    fieldId,
+    label,
+    value: fieldValue,
+    valid,
+    ...(invalidReason === undefined ? {} : { invalidReason }),
+    ...(provenance ? { provenance } : {}),
+  };
+}
+
+function toSection(value: unknown): Checked<ProfileSectionView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { heading, tier } = record;
+  if (!isString(heading) || !isString(tier)) return MALFORMED;
+  const fields = checkedArray(record.fields, toField);
+  if (fields === MALFORMED) return MALFORMED;
+  const prose = checkedArray(record.prose, toLine);
+  if (prose === MALFORMED) return MALFORMED;
+  return { heading, tier, fields, prose };
+}
+
+function toInvalidField(value: unknown): Checked<ProfileInvalidFieldView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { fieldId, reason } = record;
+  if (!isString(fieldId) || !isString(reason)) return MALFORMED;
+  return { fieldId, reason };
+}
+
+/** `profile.status`, and the `state` half of `profile.read`. */
+export function toProfileState(value: unknown): Checked<ProfileStateView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { kind, path } = record;
+  if (!isString(kind) || !isString(path)) return MALFORMED;
+  const exists = optionalBoolean(record.exists);
+  if (exists === MALFORMED) return MALFORMED;
+  const lineCount = optionalNumber(record.lineCount);
+  if (lineCount === MALFORMED) return MALFORMED;
+  const fieldCount = optionalNumber(record.fieldCount);
+  if (fieldCount === MALFORMED) return MALFORMED;
+  const proseLineCount = optionalNumber(record.proseLineCount);
+  if (proseLineCount === MALFORMED) return MALFORMED;
+  const reason = optionalString(record.reason);
+  if (reason === MALFORMED) return MALFORMED;
+  const sections = record.sections === undefined || record.sections === null
+    ? undefined
+    : checkedStringArray(record.sections);
+  if (sections === MALFORMED) return MALFORMED;
+  const invalidFields = record.invalidFields === undefined || record.invalidFields === null
+    ? undefined
+    : checkedArray(record.invalidFields, toInvalidField);
+  if (invalidFields === MALFORMED) return MALFORMED;
+  return {
+    kind,
+    path,
+    ...(exists === undefined ? {} : { exists }),
+    ...(lineCount === undefined ? {} : { lineCount }),
+    ...(fieldCount === undefined ? {} : { fieldCount }),
+    ...(proseLineCount === undefined ? {} : { proseLineCount }),
+    ...(sections === undefined ? {} : { sections }),
+    ...(invalidFields === undefined ? {} : { invalidFields }),
+    ...(reason === undefined ? {} : { reason }),
+  };
+}
+
+/** `profile.read`. */
+export function toProfileDocument(value: unknown): Checked<ProfileDocumentView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const state = toProfileState(record.state);
+  if (state === MALFORMED) return MALFORMED;
+  const sections = checkedArray(record.sections, toSection);
+  if (sections === MALFORMED) return MALFORMED;
+  return { state, sections };
+}
+
+function toSuperseded(value: unknown): Checked<ProfileSupersededView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { lineIndex, fieldId, section, text, value: supersededValue, supersededOn, previousLine } = record;
+  if (
+    !isFiniteNumber(lineIndex)
+    || !isString(fieldId)
+    || !isString(section)
+    || !isString(text)
+    || !isString(supersededValue)
+    || !isString(supersededOn)
+    || !isString(previousLine)
+  ) return MALFORMED;
+  const provenance = toProvenance(record.provenance);
+  if (provenance === MALFORMED) return MALFORMED;
+  return {
+    lineIndex,
+    fieldId,
+    section,
+    text,
+    value: supersededValue,
+    supersededOn,
+    previousLine,
+    ...(provenance ? { provenance } : {}),
+  };
+}
+
+/** `profile.provenance`. */
+export function toProfileProvenanceReport(value: unknown): Checked<ProfileProvenanceReportView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { fieldId, present, handEdited } = record;
+  if (!isString(fieldId) || !isBoolean(present) || !isBoolean(handEdited)) return MALFORMED;
+  const provenance = toProvenance(record.provenance);
+  if (provenance === MALFORMED) return MALFORMED;
+  const superseded = checkedArray(record.superseded, toSuperseded);
+  if (superseded === MALFORMED) return MALFORMED;
+  return { fieldId, present, handEdited, ...(provenance ? { provenance } : {}), superseded };
+}
+
+function toChange(value: unknown): Checked<ProfileChangeView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { kind, section, label, superseded } = record;
+  if (!isString(kind) || !isString(section) || !isString(label) || !isBoolean(superseded)) return MALFORMED;
+  const fieldId = optionalString(record.fieldId);
+  if (fieldId === MALFORMED) return MALFORMED;
+  return { kind, section, label, superseded, ...(fieldId === undefined ? {} : { fieldId }) };
+}
+
+/** `profile.set`, `profile.append`, `profile.forget`, `profile.undo`. */
+export function toProfileWriteResult(value: unknown): Checked<ProfileWriteResultView> {
+  const record = asRecord(value);
+  if (!record) return MALFORMED;
+  const { ok, disclosure } = record;
+  if (!isBoolean(ok) || !isString(disclosure)) return MALFORMED;
+  const reason = optionalString(record.reason);
+  if (reason === MALFORMED) return MALFORMED;
+  const changes = checkedArray(record.changes, toChange);
+  if (changes === MALFORMED) return MALFORMED;
+  return { ok, disclosure, changes, ...(reason === undefined ? {} : { reason }) };
+}

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

@@ -26,7 +26,19 @@ interface RevertHunkResult {
   readonly refusal: { readonly reason: string } | null;
 }
 
-const INVOKE_CONTEXT = { context: { clientKind: 'tui' as const } };
+/**
+ * The review UI's invoke context.
+ *
+ * `explicitUserRequest: true` is honest here and only here-shaped: this path
+ * runs because a person is looking at a hunk and pressed a key. Scheduled
+ * work, triggers and channel-driven work must never set it — the distinction
+ * is exactly "did the owner ask for this right now", and it is what lets a
+ * confirmation-gated verb tell an authorized action apart from one initiated
+ * by content.
+ */
+const INVOKE_CONTEXT = {
+  context: { clientKind: 'tui' as const, metadata: { explicitUserRequest: true } },
+};
 
 /** True for the honest 409 the revert verb throws when the hunk drifted since it was captured. */
 function isConflict(err: unknown): boolean {

package/src/input/commands.ts

@@ -11,6 +11,7 @@ import { registerConfigCommand } from './commands/config.ts';
 import { registerDiscoveryRuntimeCommands } from './commands/discovery-runtime.ts';
 import { registerPlanningRuntimeCommands } from './commands/planning-runtime.ts';
 import { registerSecretRuntimeCommands } from './commands/secret-runtime.ts';
+import { registerPaymentCardCommands } from './commands/payment-card-intake.ts';
 import { registerScheduleRuntimeCommands } from './commands/schedule-runtime.ts';
 import { registerBranchRuntimeCommands } from './commands/branch-runtime.ts';
 import { registerOperatorRuntimeCommands } from './commands/operator-runtime.ts';
@@ -79,7 +80,10 @@ import { registerReviewRuntimeCommands } from './commands/review-runtime.ts';
 import { registerPaletteRuntimeCommands } from './commands/palette-runtime.ts';
 import { registerCiRuntimeCommands } from './commands/ci-runtime.ts';
 import { registerCheckinRuntimeCommands } from './commands/checkin-runtime.ts';
+import { registerMailRuntimeCommands } from './commands/mail-runtime.ts';
+import { registerCalendarRuntimeCommands } from './commands/calendar-runtime.ts';
 import { registerPrincipalsRuntimeCommands } from './commands/principals-runtime.ts';
+import { registerProfileRuntimeCommands } from './commands/profile-runtime.ts';
 
 /**
  * A named group of built-in commands. The `category` label is the single
@@ -160,6 +164,7 @@ export const BUILTIN_COMMAND_GROUPS: readonly BuiltinCommandGroup[] = [
   { category: 'Discovery', register: registerDiscoveryRuntimeCommands },
   { category: 'Planning', register: registerPlanningRuntimeCommands },
   { category: 'Secrets', register: registerSecretRuntimeCommands },
+  { category: 'Payments', register: registerPaymentCardCommands },
   { category: 'Scheduling', register: registerScheduleRuntimeCommands },
   { category: 'Branches', register: registerBranchRuntimeCommands },
   { category: 'Session Content', register: registerSessionContentCommands },
@@ -173,7 +178,13 @@ export const BUILTIN_COMMAND_GROUPS: readonly BuiltinCommandGroup[] = [
   { category: 'Diff & Review', register: registerReviewRuntimeCommands },
   { category: 'CI', register: registerCiRuntimeCommands },
   { category: 'Check-in', register: registerCheckinRuntimeCommands },
+  { category: 'Mail & Calendar', register: registerMailRuntimeCommands },
+  { category: 'Mail & Calendar', register: registerCalendarRuntimeCommands },
   { category: 'Principals', register: registerPrincipalsRuntimeCommands },
+  // "Owner Profile", not "Profiles": the Profiles category above is
+  // /profile-sync's named-config-preset bundles, which have nothing to do with
+  // what the platform knows about the person who owns it.
+  { category: 'Owner Profile', register: registerProfileRuntimeCommands },
   { category: 'Policy', register: (registry) => registry.register(policyCommand) },
   { category: 'Providers', register: (registry) => registry.register(providerCommand) },
   { category: 'Eval', register: (registry) => registry.register(evalCommand) },

package/src/input/composer-editor.ts

@@ -66,6 +66,10 @@ export function openComposerInEditor(deps: ComposerEditorDeps): void {
     return;
   }
   const draft = deps.readDraft();
+  // Real production scratch (runs on the end user's machine, not test
+  // infrastructure), so this stays rooted at the real OS temp dir rather
+  // than the test-only makeProjectTempDir helper. Cleaned up in the
+  // `finally` below on every exit path.
   const dir = mkdtempSync(join(tmpdir(), 'goodvibes-composer-'));
   const file = join(dir, 'COMPOSER.md');
   const spawn = deps.spawn ?? defaultSpawn;

package/src/input/onboarding/onboarding-wizard-apply.ts

@@ -52,6 +52,18 @@ export function buildOnboardingApplyRequest(controller: OnboardingWizardControll
         acknowledged: controller.getBooleanFieldValue(fieldId, false),
       });
     };
+    // Every credential the first-run wizard captures is one the DAEMON executes
+    // with: model provider API keys (the daemon runs the model), the Cloudflare
+    // API token, and the masked fields of the external surfaces — all of which
+    // live under daemon-owned `surfaces.*` config paths. So they all go to the
+    // daemon tier, which is the one tier every surface AND the daemon read.
+    //
+    // 'project' — what this used to pass — filed them under whatever directory
+    // the wizard happened to be run from. Run the wizard in ~/code/foo and the
+    // daemon, which has no idea that directory exists, found nothing; run it
+    // again elsewhere and the first setup silently stopped applying. First-run
+    // setup is exactly the moment where "configure once, works everywhere" has
+    // to hold.
     const setSecret = (key: string, value: string): void => {
       if (value.length === 0) return;
       const medium = controller.getSelectedSecretMedium();
@@ -59,7 +71,7 @@ export function buildOnboardingApplyRequest(controller: OnboardingWizardControll
         kind: 'set-secret',
         key,
         value,
-        scope: 'project',
+        scope: 'daemon',
         medium,
       });
     };

package/src/input/payments-config.ts

@@ -0,0 +1,167 @@
+/**
+ * payments-config.ts — TUI-local synthetic settings for the payment card
+ * capability's card MATERIAL fields.
+ *
+ * The SDK's CONFIG_SCHEMA now has a full real `payments` section (28 keys:
+ * enabled, defaultCardId, currency, cvvHandling, the six budget keys,
+ * shipping.preferredTier, the fourteen billing/shipping address sub-fields
+ * (name, line1, line2, city, region, postalCode, country — each repeated for
+ * billingAddress and shippingAddress), the two window keys, and
+ * notifyChannels — see `@pellux/goodvibes-sdk/platform/config`). Every one of
+ * those keys reads and writes through the ordinary CONFIG_SCHEMA-driven path
+ * in settings-modal-data.ts's buildSettingGroups, exactly like `relay.*` or
+ * any other real SDK domain — no synthetic entry or dedicated store is needed
+ * for them, and this module builds none. (An earlier round of this module
+ * modeled billing/shipping address as two flat TUI-local strings; the SDK's
+ * own structured per-field keys superseded that the moment they shipped, so
+ * those two synthetic entries are gone from this file entirely.)
+ *
+ * What this module still builds synthetic entries for is the four card
+ * MATERIAL fields: number, expiry, CVV, cardholder name. Per the SDK's own
+ * design (see its schema-domain-payments.ts header and `platform/payments`'s
+ * method catalog), card material is deliberately never a config path at all:
+ * it lives write-only in the daemon secret store, named by keys the daemon's
+ * own `payments.cards.create` control-plane method derives internally. The
+ * SDK does not yet expose an equivalent config-level path for a single
+ * implicit card the way this app's `/payments card` flow models it, so these
+ * four fields are synthetic sub-keys under the SDK's real `payments`
+ * section — the same established pattern this codebase already uses for
+ * `tts.speed`, `behavior.notifyAfterSeconds`, etc.: a key one level under an
+ * EXISTING section that CONFIG_SCHEMA hasn't grown a scalar entry for yet.
+ *
+ * That one-level-under-an-existing-section shape matters mechanically: the
+ * real ConfigManager's dotted-path resolver only throws "Invalid config path"
+ * when an INTERMEDIATE segment is missing (e.g. `payments.card.number`, where
+ * `card` is not itself a section) — it does not throw for a final leaf that
+ * the schema hasn't declared (`payments.cardNumber`), the same tolerance
+ * `tts.speed` already relies on under `tts`. So these four keys are named
+ * FLAT (`payments.cardNumber`, not `payments.card.number`) specifically so
+ * `ConfigManager.get/setDynamic` accepts them — verified against the real
+ * ConfigManager (not the fake store this module used before this round): a
+ * flat sub-key persists to the real daemon-owned settings file precisely
+ * because `payments.` is a `DAEMON_OWNED_CONFIG_PREFIXES` entry, which is
+ * exactly what makes the daemon (and every other surface) able to see it
+ * after this TUI closes — the thing the local JSON store this module used to
+ * use never gave them.
+ *
+ * All four keys are secret-tier (see config/secret-config.ts's
+ * SECRET_CONFIG_KEYS). Primary entry for those is the concealed-input flow in
+ * commands/payment-card-intake.ts, itself gated on the SDK's
+ * `mayOfferCardEntryFlow` (card details may only be typed at a local
+ * terminal or the webui, never over a remote messaging surface — see that
+ * file's header); they are also reachable as ordinary secret-backed settings
+ * rows here, which is what makes them masked mid-edit — see
+ * renderer/settings-modal.ts's currentSettingValue().
+ *
+ * cvvHandling — real now, not built here — selects whether the CVV is stored
+ * (the default, per the 2026-07-27 payment-capability ruling) or requested at
+ * purchase time; see `CVV_PROMPT_TRADEOFF_WARNING`, imported directly from
+ * `@pellux/goodvibes-sdk/platform/payments` by every caller that needs it
+ * (renderer/settings-modal.ts, settings-modal.ts) — no local copy lives here
+ * or anywhere else in this app.
+ */
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigKey } from '../config/index.ts';
+import type { SettingEntry } from './settings-modal-types.ts';
+
+/** Real ConfigManager's read surface — these four keys are defensive reads (see header comment). */
+export type PaymentsConfigReader = Pick<ConfigManager, 'get'>;
+
+export const PAYMENTS_CARD_NUMBER_CONFIG_KEY = 'payments.cardNumber' as ConfigKey;
+export const PAYMENTS_CARD_EXPIRY_CONFIG_KEY = 'payments.cardExpiry' as ConfigKey;
+export const PAYMENTS_CARD_CVV_CONFIG_KEY = 'payments.cardCvv' as ConfigKey;
+export const PAYMENTS_CARD_CARDHOLDER_NAME_CONFIG_KEY = 'payments.cardholderName' as ConfigKey;
+
+/** The real SDK schema key for the CVV-handling selector — no longer synthetic. */
+export const PAYMENTS_CVV_HANDLING_CONFIG_KEY = 'payments.cvvHandling' as ConfigKey;
+
+function readStringField(configManager: PaymentsConfigReader, key: ConfigKey): string {
+  // Defensive try/catch, same rationale as worktree-setup-config.ts's
+  // readWorktreeSetupList and this codebase's other one-level-under-a-real-
+  // section synthetic reads (tts.speed, behavior.notifyAfterSeconds): the real
+  // ConfigManager never throws for these particular keys (verified — see
+  // header comment), but degrading to empty rather than crashing the whole
+  // settings modal is the same posture every synthetic setting here takes
+  // toward an unexpected value.
+  try {
+    const raw = configManager.get(key);
+    return typeof raw === 'string' ? raw : '';
+  } catch {
+    return '';
+  }
+}
+
+function buildStringFieldEntry(
+  configManager: PaymentsConfigReader,
+  key: ConfigKey,
+  description: string,
+): SettingEntry {
+  const currentValue = readStringField(configManager, key);
+  return {
+    setting: { key, type: 'string', default: '', description },
+    currentValue,
+    isDefault: currentValue === '',
+  };
+}
+
+export function buildPaymentsCardNumberEntry(configManager: PaymentsConfigReader): SettingEntry {
+  return buildStringFieldEntry(
+    configManager,
+    PAYMENTS_CARD_NUMBER_CONFIG_KEY,
+    'Payment card number. Stored through the secret manager at daemon scope; entering it here or via /payments card never shows the typed characters in plaintext.',
+  );
+}
+
+export function buildPaymentsCardExpiryEntry(configManager: PaymentsConfigReader): SettingEntry {
+  return buildStringFieldEntry(
+    configManager,
+    PAYMENTS_CARD_EXPIRY_CONFIG_KEY,
+    'Payment card expiry (MM/YY). Stored through the secret manager at daemon scope, same handling as the card number.',
+  );
+}
+
+export function buildPaymentsCardCvvEntry(configManager: PaymentsConfigReader): SettingEntry {
+  return buildStringFieldEntry(
+    configManager,
+    PAYMENTS_CARD_CVV_CONFIG_KEY,
+    'Payment card CVV. Stored through the secret manager at daemon scope: never logged, never rendered, never shown mid-edit, excluded from every export and diagnostic dump.',
+  );
+}
+
+export function buildPaymentsCardCardholderNameEntry(configManager: PaymentsConfigReader): SettingEntry {
+  return buildStringFieldEntry(
+    configManager,
+    PAYMENTS_CARD_CARDHOLDER_NAME_CONFIG_KEY,
+    'Name on the payment card. Stored through the secret manager at daemon scope, same handling as the card number.',
+  );
+}
+
+/** All payments synthetic entries (the four card-material fields), in the order they should render. */
+export function buildPaymentsSyntheticEntries(configManager: PaymentsConfigReader): SettingEntry[] {
+  return [
+    buildPaymentsCardNumberEntry(configManager),
+    buildPaymentsCardExpiryEntry(configManager),
+    buildPaymentsCardCvvEntry(configManager),
+    buildPaymentsCardCardholderNameEntry(configManager),
+  ];
+}
+
+/** Every payments synthetic config key this module owns, for refresh-loop membership checks. */
+export const PAYMENTS_SYNTHETIC_CONFIG_KEYS: readonly ConfigKey[] = [
+  PAYMENTS_CARD_NUMBER_CONFIG_KEY,
+  PAYMENTS_CARD_EXPIRY_CONFIG_KEY,
+  PAYMENTS_CARD_CVV_CONFIG_KEY,
+  PAYMENTS_CARD_CARDHOLDER_NAME_CONFIG_KEY,
+];
+
+export function isPaymentsSyntheticConfigKey(key: string): key is ConfigKey {
+  return (PAYMENTS_SYNTHETIC_CONFIG_KEYS as readonly string[]).includes(key);
+}
+
+/** Refresh one payments synthetic entry's currentValue/isDefault in place. */
+export function refreshPaymentsSyntheticEntry(entry: SettingEntry, configManager: PaymentsConfigReader): void {
+  const currentValue = readStringField(configManager, entry.setting.key as ConfigKey);
+  entry.currentValue = currentValue;
+  entry.isDefault = currentValue === '';
+}