@pellux/goodvibes-daemon 1.28.0

package/src/daemon/pair-command.ts

@@ -0,0 +1,301 @@
+/**
+ * pair-command.ts — `goodvibes-daemon pair`.
+ *
+ * Two forms.
+ *
+ * LOCAL FORM — `pair` with no `--host`, or one naming this machine — reprints
+ * the pairing block a daemon prints once as it starts: the web origin, the
+ * offers a new device can accept, what it will be able to do, and a QR code
+ * encoding the deep link that opens the web app already signed in. It reads
+ * from THIS machine's own token store (the shared companion token in
+ * `<daemon home>/operator-tokens.json` plus the web origin its settings
+ * resolve to) and reprints the EXISTING token rather than minting a new one,
+ * so a link printed here and the one printed at boot are the same link.
+ *
+ * REMOTE FORM — `pair --host <name> [--port] [--token]` — asks THAT daemon to
+ * MINT A NEW per-device pairing token over `pairing.handoff.create` and prints
+ * the pairing block for it. Minting is a different act than reprinting: it is
+ * a fresh token, and every token that daemon already issued (its own shared
+ * token included) is left exactly as it was. Because it changes state on a
+ * daemon that may not be this process's own, it states the plan and asks for
+ * confirmation before acting — `-y`/`--yes` satisfies that non-interactively,
+ * the same convention `migrate-service` uses. An unreachable daemon, a
+ * rejected token, and a daemon too old to serve the verb are each refused by
+ * name (see `callDaemonWsVerb`), never a stack trace.
+ *
+ * The remote form's mint call carries no `--name` flag of its own: the token
+ * is named with the SDK's `defaultPairingTokenName()`, the same date-stamped
+ * default every other pairing producer uses when the operator did not supply
+ * one. The name is user-visible and editable later in device management.
+ */
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import {
+  availablePairingOffers,
+  defaultPairingTokenName,
+  formatPairingOffers,
+  resolvePairingWebOrigin,
+  type PairingHandoffOfferKind,
+} from '@pellux/goodvibes-sdk/platform/pairing';
+import { renderPairingBanner } from '../core/pairing-banner.ts';
+import {
+  extractOperatorToken,
+  resolveRemoteDaemonTarget,
+  type RemoteDaemonTarget,
+} from '@pellux/goodvibes-terminal-shell';
+import { callDaemonWsVerb, type DaemonWebSocketFactory } from '../cluster/daemon-ws-call.ts';
+import type { DaemonCommandResult, RemoteCommandFlags } from './status-command.ts';
+
+export interface PairCommandDeps {
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly daemonHomeDir: string;
+  readonly version: string;
+  /** Injected in tests so nothing reads a real token file. */
+  readonly readToken: (daemonHomeDir: string) => string | undefined;
+  /** Injected in tests so the remote mint path never opens a real socket. */
+  readonly socketFactory?: DaemonWebSocketFactory | undefined;
+}
+
+export interface PairCommandFlags extends RemoteCommandFlags {
+  /** `-y`/`--yes`: consent to minting a new per-device token on a remote daemon. */
+  readonly yes: boolean;
+}
+
+export interface RunPairCommandInput extends PairCommandDeps {
+  readonly flags: PairCommandFlags;
+}
+
+/** The hosts that mean "this machine", matching the remote-target convention. */
+function namesThisMachine(host: string): boolean {
+  const normalized = host.trim().toLowerCase();
+  return normalized === ''
+    || normalized === '127.0.0.1'
+    || normalized === 'localhost'
+    || normalized === '::1'
+    || normalized === '0.0.0.0';
+}
+
+function failure(error: string, fix: string, json: boolean): DaemonCommandResult {
+  return {
+    exitCode: 1,
+    lines: json ? [JSON.stringify({ ok: false, error, fix }, null, 2)] : [error, `  ${fix}`],
+  };
+}
+
+/**
+ * The web origin a remote handoff's deep link opens, recovered from the link
+ * itself. `buildPairingHandoffLink` in the SDK builds the link as exactly
+ * `<webOrigin, trailing slashes stripped>/#<params>` — so slicing at the
+ * first `/#` is the precise inverse, and feeding the result back into
+ * `renderPairingBanner` (which rebuilds the SAME link from origin + token +
+ * offers) reproduces byte-for-byte what the remote daemon already returned.
+ */
+function originFromDeepLink(deepLink: string): string {
+  const cut = deepLink.indexOf('/#');
+  return cut === -1 ? deepLink : deepLink.slice(0, cut);
+}
+
+function isPairingOfferKind(value: string): value is PairingHandoffOfferKind {
+  return value === 'notifications' || value === 'relay' || value === 'passkey';
+}
+
+interface PairingHandoffOfferDetail {
+  readonly kind: string;
+  readonly available?: boolean;
+}
+
+/** The shape `pairing.handoff.create` returns — see routes/pairing-handoff.ts. */
+interface PairingHandoffCreateResult {
+  readonly token: {
+    readonly id: string;
+    readonly name: string;
+    /** The plaintext secret — returned exactly once. */
+    readonly token: string;
+    readonly createdAt: number;
+  };
+  readonly offers: readonly PairingHandoffOfferDetail[];
+  /** `#pair=<token>&offers=...` — present even when no web origin is configured. */
+  readonly fragment: string;
+  /** `<webOrigin>/#pair=...` — present only when that daemon has a web origin configured. */
+  readonly deepLink?: string;
+}
+
+/** `goodvibes-daemon pair` with no `--host`, or one naming this machine. */
+function runLocalReprint(input: RunPairCommandInput): DaemonCommandResult {
+  const { flags } = input;
+
+  const token = extractOperatorToken(input.readToken(input.daemonHomeDir));
+  if (token === undefined) {
+    return failure(
+      'no operator token was found for this machine, so there is no link to print',
+      'start the daemon once — it creates the token as it starts: goodvibes-daemon serve',
+      flags.json,
+    );
+  }
+
+  // The non-writing read: `ensurePublicBaseUrl` (which the boot path uses)
+  // freezes a resolved origin into settings, and a command that only PRINTS a
+  // link has no business writing configuration as a side effect.
+  const origin = resolvePairingWebOrigin(input.configManager);
+  const offers = availablePairingOffers({
+    relayEnabled: input.configManager.get('relay.enabled') === true,
+    stepUpAvailable: true,
+  });
+
+  const banner = renderPairingBanner({
+    version: input.version,
+    origin: origin.origin,
+    token,
+    offers,
+    includeQr: !flags.json,
+  });
+
+  if (flags.json) {
+    return {
+      exitCode: 0,
+      lines: [JSON.stringify({
+        ok: true,
+        data: {
+          origin: origin.origin,
+          deepLink: banner.deepLink,
+          offers,
+          capabilities: banner.capabilities,
+          ...(banner.notice === undefined ? {} : { notice: banner.notice }),
+          originFromPublicBaseUrl: origin.fromPublicBaseUrl,
+        },
+      }, null, 2)],
+    };
+  }
+
+  return { exitCode: 0, lines: banner.lines };
+}
+
+/** The plan `pair --host <target>` prints before it will act, absent `-y`. Nothing is called yet. */
+function mintPlanResult(target: RemoteDaemonTarget, json: boolean): DaemonCommandResult {
+  const plan = [
+    `pair --host: this will MINT A NEW per-device pairing token on the daemon at ${target.baseUrl}`,
+    'and print the pairing link/QR for that new token.',
+    '',
+    "That daemon's existing tokens — its shared token and every other paired device — are",
+    'left exactly as they are: minting is a different act than reprinting, and this is a',
+    'fresh token, not a link to one that already exists.',
+    '',
+    'Nothing has been changed. Re-run with -y (or --yes) to mint it.',
+  ];
+  if (json) {
+    return {
+      exitCode: 0,
+      lines: [JSON.stringify({
+        ok: true,
+        data: { confirmed: false, target: target.baseUrl, plan },
+      }, null, 2)],
+    };
+  }
+  return { exitCode: 0, lines: plan };
+}
+
+/** The remote form, once `-y` has consented: mint and render. */
+async function runRemoteMint(input: RunPairCommandInput, target: RemoteDaemonTarget): Promise<DaemonCommandResult> {
+  const { flags } = input;
+
+  const outcome = await callDaemonWsVerb<PairingHandoffCreateResult>(target, 'pairing.handoff.create', {
+    body: { name: defaultPairingTokenName() },
+    ...(input.socketFactory ? { socketFactory: input.socketFactory } : {}),
+  });
+  if (!outcome.ok) return failure(outcome.error, outcome.fix, flags.json);
+
+  const data = outcome.data;
+  const offerKinds = data.offers.map((offer) => offer.kind).filter(isPairingOfferKind);
+  const mintedLine = `minted a new per-device pairing token ("${data.token.name}") on the daemon at ${target.baseUrl}.`;
+
+  if (data.deepLink === undefined) {
+    // Honest degraded path: the mint itself succeeded — the token is real and
+    // usable — but that daemon has no web origin configured, and this process
+    // has no way to read or fabricate one for it. `resolvePairingWebOrigin` is
+    // what the local form reads instead, and it is exactly the thing this
+    // process cannot ask a REMOTE daemon for outside this verb's own reply.
+    const lines = [
+      mintedLine,
+      '',
+      'that daemon has no web origin configured, so no deep link or QR could be built — only',
+      'the raw token and pairing fragment:',
+      '',
+      `  token:    ${data.token.token}`,
+      `  fragment: ${data.fragment}`,
+      '',
+      ...(offerKinds.length > 0 ? ['Offers (each declinable in the web app):', ...formatPairingOffers(offerKinds), ''] : []),
+      'Configure a web origin on that daemon, then pair again for a scannable link.',
+    ];
+    if (flags.json) {
+      return {
+        exitCode: 0,
+        lines: [JSON.stringify({
+          ok: true,
+          data: {
+            minted: true,
+            target: target.baseUrl,
+            tokenId: data.token.id,
+            tokenName: data.token.name,
+            token: data.token.token,
+            fragment: data.fragment,
+            offers: offerKinds,
+          },
+        }, null, 2)],
+      };
+    }
+    return { exitCode: 0, lines };
+  }
+
+  const origin = originFromDeepLink(data.deepLink);
+  const banner = renderPairingBanner({
+    version: `remote build at ${target.baseUrl}`,
+    origin,
+    token: data.token.token,
+    offers: offerKinds,
+    includeQr: !flags.json,
+  });
+
+  if (flags.json) {
+    return {
+      exitCode: 0,
+      lines: [JSON.stringify({
+        ok: true,
+        data: {
+          minted: true,
+          target: target.baseUrl,
+          tokenId: data.token.id,
+          tokenName: data.token.name,
+          token: data.token.token,
+          origin,
+          deepLink: banner.deepLink,
+          offers: offerKinds,
+          capabilities: banner.capabilities,
+          ...(banner.notice === undefined ? {} : { notice: banner.notice }),
+        },
+      }, null, 2)],
+    };
+  }
+
+  return { exitCode: 0, lines: [mintedLine, '', ...banner.lines] };
+}
+
+export async function runPairCommand(input: RunPairCommandInput): Promise<DaemonCommandResult> {
+  const { flags } = input;
+
+  if (flags.host !== undefined && !namesThisMachine(flags.host)) {
+    const resolved = resolveRemoteDaemonTarget({
+      flags: {
+        host: flags.host,
+        ...(flags.port === undefined ? {} : { port: flags.port }),
+        ...(flags.token === undefined ? {} : { token: flags.token }),
+      },
+      configManager: input.configManager,
+      daemonHomeDir: input.daemonHomeDir,
+      readToken: input.readToken,
+    });
+    if (!resolved.ok) return failure(resolved.error, resolved.fix, flags.json);
+    if (!flags.yes) return mintPlanResult(resolved.target, flags.json);
+    return runRemoteMint(input, resolved.target);
+  }
+
+  return runLocalReprint(input);
+}

package/src/daemon/provision-wake-model.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// provision-wake-model.ts — `goodvibes-daemon provision-wake-model`.
+//
+// WHAT THIS IS FOR
+//
+// The curl installer needs to put the wake-word model on the machine, and it must
+// not hold the pinned URLs, byte counts or checksums to do it. Those live in ONE
+// place — the SDK's wake-word manifest — and a shell script that copied them
+// would be a second copy of a pin, drifting silently the first time the model is
+// retrained. So the installer runs the binary it just installed and lets the SDK
+// do what the SDK owns.
+//
+// IT EXITS 0 EVEN WHEN THE DOWNLOAD FAILS, ON PURPOSE
+//
+// The caller is an installer. A wake-word model is not a reason to fail installing
+// a coding tool, and an installer that aborts half-way through is worse than one
+// that finishes without a wake word. The outcome is printed either way — one plain
+// line naming what happened and how to retry — and a running daemon retries at
+// every boot. `--strict` is there for a caller that genuinely wants the exit code
+// to carry the result (a test, a provisioning script that is checking); the
+// installer does not pass it.
+//
+// It composes NOTHING. No runtime, no config manager, no gateway: this reads a
+// home directory, derives the managed voice root the same way the running daemon
+// does, and calls one SDK function. Composing a runtime here would start a second
+// set of pollers on a machine whose daemon is probably already running.
+// ---------------------------------------------------------------------------
+
+import {
+  provisionWakeWordModelsAtInstall,
+  resolveManagedVoiceRoot,
+} from '@pellux/goodvibes-sdk/platform/voice';
+
+export interface ProvisionWakeModelResult {
+  readonly exitCode: number;
+  readonly lines: readonly string[];
+}
+
+export interface ProvisionWakeModelDeps {
+  /** The home directory whose `.goodvibes/voice` tree receives the artifacts. */
+  readonly homeDirectory: string;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** Injected in tests: the SDK policy, so nothing downloads. */
+  readonly provisionAtInstall?: typeof provisionWakeWordModelsAtInstall | undefined;
+}
+
+/**
+ * Run the install-time provision and report it.
+ *
+ * `--strict` makes a degraded outcome exit 1. Without it, every outcome exits 0,
+ * because the caller is an installer and the alternative is an aborted install
+ * over an optional model.
+ */
+export async function runProvisionWakeModelCommand(
+  argv: readonly string[],
+  deps: ProvisionWakeModelDeps,
+): Promise<ProvisionWakeModelResult> {
+  const strict = argv.includes('--strict');
+  const provision = deps.provisionAtInstall ?? provisionWakeWordModelsAtInstall;
+  let managedRoot: string;
+  try {
+    managedRoot = resolveManagedVoiceRoot(deps.homeDirectory);
+  } catch (error) {
+    // A home directory this process cannot make sense of is still not a reason to
+    // fail an install, so it is reported on the same terms as a failed download.
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: strict ? 1 : 0,
+      lines: [`wake-word model: skipped — ${message}`],
+    };
+  }
+  const outcome = await provision({
+    managedRoot,
+    recoveryHint: '/voice wake setup',
+    ...(deps.env !== undefined ? { env: deps.env } : {}),
+  });
+  return {
+    exitCode: strict && outcome.state === 'degraded' ? 1 : 0,
+    lines: [`wake-word model: ${outcome.message}`],
+  };
+}

package/src/daemon/send/channels.ts

@@ -0,0 +1,200 @@
+/**
+ * channels.ts — which channels `goodvibes-daemon send` can reach, and which one
+ * it uses when the operator names none.
+ *
+ * The surface list, labels and required-setup keys are IMPORTED from
+ * `src/cli/surface-catalog.ts` rather than restated, so `goodvibes surfaces
+ * list` and `goodvibes-daemon send --list` can never disagree about what a
+ * channel is called or what it needs. What this module adds on top is the two
+ * facts that command needs and `SURFACE_CONFIGS` does not carry: the routable
+ * `ChannelDeliverySurfaceKind` for each surface id (they differ in case —
+ * `googleChat` vs `google-chat`), and the settings key holding each surface's
+ * default destination.
+ */
+
+import type { ConfigKey, ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ChannelDeliverySurfaceKind } from '@pellux/goodvibes-sdk/platform/channels';
+import { SURFACE_CONFIGS } from '../../cli/surface-catalog.ts';
+import { canRenderInert } from './inert-text.ts';
+
+/**
+ * The settings key holding each supported surface's default destination — the
+ * chat, channel, topic or URL a message goes to when `--to` is not given.
+ *
+ * These are the SAME keys the delivery strategies in the SDK's
+ * `strategies-core.ts` fall back to (`surfaces.telegram.defaultChatId`,
+ * `surfaces.discord.defaultChannelId`, …). Only surfaces with a verified inert
+ * transform appear; see inert-text.ts for why the rest are refused rather than
+ * sent to.
+ */
+const DESTINATION_KEY_BY_SURFACE_ID = {
+  telegram: 'surfaces.telegram.defaultChatId',
+  ntfy: 'surfaces.ntfy.topic',
+  discord: 'surfaces.discord.defaultChannelId',
+  slack: 'surfaces.slack.defaultChannel',
+  googleChat: 'surfaces.googleChat.webhookUrl',
+  webhook: 'surfaces.webhook.defaultTarget',
+  signal: 'surfaces.signal.defaultRecipient',
+  whatsapp: 'surfaces.whatsapp.defaultRecipient',
+  imessage: 'surfaces.imessage.defaultChatId',
+  msteams: 'surfaces.msteams.defaultConversationId',
+  bluebubbles: 'surfaces.bluebubbles.defaultChatGuid',
+  mattermost: 'surfaces.mattermost.defaultChannelId',
+  matrix: 'surfaces.matrix.defaultRoomId',
+  // Not cast: every value is checked against the real ConfigKey union, so a
+  // key that is renamed or misspelled in the schema fails the build here
+  // instead of reading `undefined` at send time and reporting the channel as
+  // unconfigured.
+} as const satisfies Readonly<Record<string, ConfigKey>>;
+
+/** Surface ids whose routable kind is not simply the id itself. */
+const SURFACE_KIND_BY_ID: Readonly<Record<string, ChannelDeliverySurfaceKind>> = {
+  googleChat: 'google-chat',
+};
+
+/**
+ * What `--to` addresses on each channel, in that channel's own vocabulary.
+ *
+ * This is naming, not a scheme: `--to` becomes `ChannelDeliveryTarget.address`,
+ * which is the first thing every strategy in `strategies-core.ts`,
+ * `strategies-bridge.ts` and `strategies-enterprise.ts` already checks before
+ * falling back to its configured default. Nothing new is invented — the label
+ * exists so `--list` and the help can say "topic" where the channel says topic
+ * and "chat id" where it says chat id, rather than making the operator work out
+ * what an "address" is for ntfy.
+ */
+const ADDRESS_LABEL_BY_SURFACE_ID: Readonly<Record<string, string>> = {
+  telegram: 'chat id',
+  ntfy: 'topic',
+  discord: 'channel id',
+  slack: 'channel id',
+  googleChat: 'webhook URL',
+  webhook: 'URL',
+  signal: 'recipient',
+  whatsapp: 'recipient',
+  imessage: 'chat id',
+  msteams: 'conversation id',
+  bluebubbles: 'chat GUID',
+  mattermost: 'channel id',
+  matrix: 'room id',
+};
+
+export interface SendChannel {
+  /** The id an operator types after `--channel`, e.g. `telegram`. */
+  readonly id: string;
+  /** Human label, shared with `goodvibes surfaces list`. */
+  readonly label: string;
+  /** The kind the channel delivery router routes on. */
+  readonly surfaceKind: ChannelDeliverySurfaceKind;
+  /** `surfaces.<id>.enabled`. */
+  readonly enabledKey: ConfigKey;
+  /** The settings key holding this channel's default destination. */
+  readonly destinationKey: ConfigKey;
+  /** What `--to` names on this channel, in the channel's own words ("topic"). */
+  readonly addressLabel: string;
+}
+
+/**
+ * Every channel this command can deliver to. Derived, not restated: a surface
+ * that gains a delivery strategy and an inert transform appears here by adding
+ * its destination key above, and a surface that loses its entry in
+ * `SURFACE_CONFIGS` disappears from both commands at once.
+ */
+const destinationKeys: Readonly<Record<string, ConfigKey>> = DESTINATION_KEY_BY_SURFACE_ID;
+
+export const SEND_CHANNELS: readonly SendChannel[] = SURFACE_CONFIGS
+  .flatMap(([id, label]): SendChannel[] => {
+    const destinationKey = destinationKeys[id];
+    if (!destinationKey) return [];
+    const surfaceKind = SURFACE_KIND_BY_ID[id] ?? (id as ChannelDeliverySurfaceKind);
+    if (!canRenderInert(surfaceKind)) return [];
+    return [{
+      id,
+      label,
+      surfaceKind,
+      enabledKey: `surfaces.${id}.enabled` as ConfigKey,
+      destinationKey,
+      addressLabel: ADDRESS_LABEL_BY_SURFACE_ID[id] ?? 'address',
+    }];
+  });
+
+/**
+ * Look a channel up by the id an operator typed, accepting either the settings
+ * id (`googleChat`) or the routable kind (`google-chat`) — the two spellings
+ * are both visible in this product's own output, and making the operator
+ * remember which one this command wants would be a trap.
+ */
+export function findSendChannel(name: string): SendChannel | undefined {
+  const wanted = name.trim().toLowerCase();
+  return SEND_CHANNELS.find((channel) =>
+    channel.id.toLowerCase() === wanted || channel.surfaceKind.toLowerCase() === wanted);
+}
+
+export interface ChannelReadiness {
+  readonly channel: SendChannel;
+  /** `surfaces.<id>.enabled` is true. */
+  readonly enabled: boolean;
+  /** The configured default destination, or null when the key is blank. */
+  readonly destination: string | null;
+}
+
+function readSetting(config: Pick<ConfigManager, 'get'>, key: ConfigKey): string {
+  const value = config.get(key);
+  return typeof value === 'string' ? value.trim() : value === undefined || value === null ? '' : String(value).trim();
+}
+
+/**
+ * Read every channel's live state from config.
+ *
+ * The `ConfigManager` handed in must be one built with a `homeDir`, because
+ * every `surfaces.*` key is daemon-owned: the manager overlays
+ * `<home>/.goodvibes/daemon/settings.json` LAST, which is the only reason a
+ * client process can see a bot token the daemon owns. A manager built without
+ * that overlay reads a surface silo holding nothing but `setupVersion` and
+ * reports every channel as unconfigured.
+ */
+export function readChannelReadiness(config: Pick<ConfigManager, 'get'>): readonly ChannelReadiness[] {
+  return SEND_CHANNELS.map((channel) => {
+    const destination = readSetting(config, channel.destinationKey);
+    return {
+      channel,
+      enabled: config.get(channel.enabledKey) === true,
+      destination: destination.length > 0 ? destination : null,
+    };
+  });
+}
+
+export type DefaultChannelResolution =
+  | { readonly kind: 'resolved'; readonly channel: SendChannel; readonly destination: string; readonly reason: string }
+  | { readonly kind: 'none'; readonly candidates: readonly ChannelReadiness[] }
+  | { readonly kind: 'ambiguous'; readonly candidates: readonly ChannelReadiness[] };
+
+/**
+ * Which channel a `send` with no `--channel` goes to.
+ *
+ * A channel qualifies when it is switched on AND has a destination configured —
+ * "enabled" alone is not enough, because an enabled surface with a blank
+ * destination is a channel that would throw at the provider rather than deliver.
+ *
+ * **Ambiguity refuses; it never picks.** With two qualifying channels there is
+ * no non-arbitrary winner, and this command has an outward effect: sending the
+ * owner's message to the wrong one of his channels is worse than printing the
+ * list and exiting non-zero. There is deliberately no priority order here to
+ * silently break that tie — a preference ordering baked into this file would be
+ * an invisible decision about where his messages go.
+ */
+export function resolveDefaultChannel(config: Pick<ConfigManager, 'get'>): DefaultChannelResolution {
+  const readiness = readChannelReadiness(config);
+  const qualifying = readiness.filter((entry) => entry.enabled && entry.destination !== null);
+  if (qualifying.length === 1) {
+    const only = qualifying[0]!;
+    return {
+      kind: 'resolved',
+      channel: only.channel,
+      destination: only.destination!,
+      reason: 'the only channel that is switched on and has a destination configured',
+    };
+  }
+  if (qualifying.length === 0) return { kind: 'none', candidates: readiness };
+  return { kind: 'ambiguous', candidates: qualifying };
+}