@pellux/goodvibes-daemon 1.28.0

package/src/daemon/send/command.ts

@@ -0,0 +1,333 @@
+/**
+ * command.ts — `goodvibes-daemon send`, the shell's way to put a message on one
+ * of the owner's channels.
+ *
+ * ## Why this exists
+ *
+ * Nothing on this machine could send the owner a message from a script. The
+ * three binaries exposed no send verb, the daemon's HTTP API answers
+ * `401 AUTH_REQUIRED` to the operator token as stored, and driving the agent to
+ * do it failed with `Missing Telegram bot token` — because the credential lives
+ * in the DAEMON tier (`~/.goodvibes/daemon/settings.json`) and the agent was
+ * reading its own surface silo. So the one process that could always send was
+ * the daemon, and only while it was running.
+ *
+ * ## Three properties this command is built around
+ *
+ * 1. **It uses the delivery path, it is not a second sender.** Everything below
+ *    ends in `ChannelDeliveryRouter.deliver()` — the same call
+ *    `AutomationDeliveryManager.sendTarget` makes, reaching the same
+ *    per-surface strategies in `strategies-core.ts`. Nothing here talks to a
+ *    provider API directly.
+ *
+ * 2. **It never exits 0 on a send that did not happen.** The router throws with
+ *    the provider's own error text and that error is printed and exits non-zero.
+ *    `AutomationDeliveryManager.deliverText` was the alternative entry point and
+ *    was NOT used, deliberately: it returns an empty array when a feature gate
+ *    is off and returns failed attempts rather than throwing, so a caller that
+ *    did not inspect its result would report success for a message that never
+ *    left the machine — the exact false-green this command exists to avoid. The
+ *    gate check it would have done is done here instead, explicitly, and a gate
+ *    that is off produces a refusal naming the settings key rather than silence.
+ *
+ * 3. **Every message it sends arrives as literal text.** The body is passed
+ *    through `inertBodyFor` for the target surface before it reaches the router,
+ *    and there is no flag, env var or code path that skips that. The message
+ *    normally comes from the operator's own shell, but the command must not
+ *    become the way something else's text — a log line, a captured error, a
+ *    remote agent's output piped in — arrives on the owner's phone rendered as
+ *    live markup with a clickable link in it. See inert-text.ts.
+ */
+
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ChannelDeliveryRequest } from '@pellux/goodvibes-sdk/platform/channels';
+import { operations } from '@pellux/goodvibes-sdk/platform/runtime';
+const { getMissingSurfaceFeatureFlags, surfaceFeatureGateSettingsKeys } = operations;
+import { findSendChannel, readChannelReadiness, resolveDefaultChannel, SEND_CHANNELS, type SendChannel } from './channels.ts';
+import { describeSendFailure } from './failure-text.ts';
+import { inertBodyFor } from './inert-text.ts';
+
+/** What the router needs to actually send; injected so tests never reach the network. */
+export type SendDeliver = (request: ChannelDeliveryRequest) => Promise<string | undefined>;
+
+export interface SendCommandDeps {
+  /** Built with a `homeDir` so the daemon tier overlays — see channels.ts. */
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly deliver: SendDeliver;
+  /** Reads the whole of stdin; only called when no message argument was given. */
+  readonly readStdin: () => Promise<string>;
+  /** Whether stdin is a terminal. A TTY means there is no piped message to wait for. */
+  readonly stdinIsTty: boolean;
+  /** Injected so the run id in the delivery request is deterministic under test. */
+  readonly newRunId?: (() => string) | undefined;
+}
+
+export interface SendCommandResult {
+  readonly lines: readonly string[];
+  readonly exitCode: number;
+}
+
+interface ParsedSendArgs {
+  readonly channel: string | null;
+  readonly to: string | null;
+  readonly title: string | null;
+  readonly list: boolean;
+  readonly help: boolean;
+  readonly words: readonly string[];
+  readonly errors: readonly string[];
+}
+
+const USAGE = [
+  'Usage: goodvibes-daemon send [OPTIONS] [MESSAGE...]',
+  '',
+  'Send a message to one of your configured channels. With no MESSAGE, the',
+  'message is read from stdin, so this composes with other tooling.',
+  '',
+  'Options:',
+  '      --channel <id>   Channel to send to. With none named, your configured',
+  '                       channel is used and the output says which one.',
+  '      --to <address>   Where within that channel: an ntfy topic, a Telegram chat',
+  '                       id, a Slack or Mattermost channel id, a Matrix room id.',
+  '                       Without it the channel\'s configured destination is used.',
+  '      --title <text>   Title for channels that show one (ntfy).',
+  '      --list           Show every channel, whether it is on, and where it sends.',
+  '  -h, --help           Print this help',
+  '',
+  'A channel that is switched off is refused by name and NOTHING is sent — the',
+  'command never quietly falls back to the default, so a message meant for a',
+  'quiet channel cannot end up on a noisy one.',
+  '',
+  'The message is always delivered as literal text: markup a channel would',
+  'otherwise render — a Discord masked link, a Slack mention — arrives inert.',
+].join('\n');
+
+function parseSendArgs(argv: readonly string[]): ParsedSendArgs {
+  let channel: string | null = null;
+  let to: string | null = null;
+  let title: string | null = null;
+  let list = false;
+  let help = false;
+  const words: string[] = [];
+  const errors: string[] = [];
+  let optionsEnded = false;
+
+  const takeValue = (flag: string, value: string | undefined): string | null => {
+    if (value === undefined || value.length === 0) {
+      errors.push(`${flag} needs a value.`);
+      return null;
+    }
+    return value;
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (optionsEnded) { words.push(arg); continue; }
+    // Everything after `--` is message text, so a message that starts with a
+    // dash is still sendable.
+    if (arg === '--') { optionsEnded = true; continue; }
+    if (arg === '-h' || arg === '--help') { help = true; continue; }
+    if (arg === '--list') { list = true; continue; }
+    if (arg === '--channel' || arg === '-c') { channel = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--channel=')) { channel = takeValue('--channel', arg.slice('--channel='.length)); continue; }
+    if (arg === '--to') { to = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--to=')) { to = takeValue('--to', arg.slice('--to='.length)); continue; }
+    if (arg === '--title') { title = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--title=')) { title = takeValue('--title', arg.slice('--title='.length)); continue; }
+    if (arg.startsWith('-') && arg.length > 1) {
+      errors.push(`Unknown option: ${arg}`);
+      continue;
+    }
+    words.push(arg);
+  }
+  return { channel, to, title, list, help, words, errors };
+}
+
+/**
+ * The channels that are actually usable right now, named. Every refusal ends
+ * with this: telling someone their channel is not configured without telling
+ * them which ones are just moves the guessing to them.
+ */
+function describeConfiguredChannels(config: Pick<ConfigManager, 'get'>): string {
+  const usable = readChannelReadiness(config)
+    .filter((entry) => entry.enabled && entry.destination !== null)
+    .map((entry) => entry.channel.id);
+  return usable.length > 0
+    ? `Configured and ready: ${usable.join(', ')}.`
+    : 'No channel is currently both switched on and given a destination — run: goodvibes-daemon send --list';
+}
+
+function renderChannelList(config: Pick<ConfigManager, 'get'>): string[] {
+  const readiness = readChannelReadiness(config);
+  const idWidth = Math.max(...SEND_CHANNELS.map((channel) => channel.id.length), 7);
+  const lines = ['Channels goodvibes-daemon send can reach:', ''];
+  for (const entry of readiness) {
+    const state = entry.enabled ? 'on ' : 'off';
+    const destination = entry.destination ?? `not set (${entry.channel.destinationKey})`;
+    lines.push(`  ${entry.channel.id.padEnd(idWidth)}  ${state}  ${entry.channel.addressLabel}: ${destination}`);
+  }
+  lines.push('');
+  lines.push('Override any channel\'s destination for one message with --to <address>.');
+  lines.push('');
+  const resolution = resolveDefaultChannel(config);
+  if (resolution.kind === 'resolved') {
+    lines.push(`Default with no --channel: ${resolution.channel.id} (${resolution.reason}).`);
+  } else if (resolution.kind === 'none') {
+    lines.push('There is no default: no channel is both switched on and given a destination.');
+  } else {
+    const names = resolution.candidates.map((entry) => entry.channel.id).join(', ');
+    lines.push(`There is no default: ${names} all qualify, so --channel is required.`);
+  }
+  return lines;
+}
+
+/** Refusals that must happen before anything is sent, in the order they matter. */
+function checkChannelUsable(
+  config: Pick<ConfigManager, 'get'>,
+  channel: SendChannel,
+): readonly string[] {
+  if (config.get(channel.enabledKey) !== true) {
+    // No fallback to the default channel, deliberately. Falling back is how a
+    // message meant for a quiet channel lands on a noisy one, and how a caller
+    // that named a channel because it mattered never finds out it was ignored.
+    return [
+      `${channel.label} is switched off, so nothing was sent.`,
+      `Switch it on with: goodvibes surfaces enable ${channel.id}   (settings key ${channel.enabledKey})`,
+      describeConfiguredChannels(config),
+    ];
+  }
+  // The same capability gates the daemon's own delivery honours. Checked here
+  // rather than left to AutomationDeliveryManager, which answers a disabled
+  // gate with an empty result and no reason.
+  const missing = getMissingSurfaceFeatureFlags(config, channel.id);
+  if (missing.length > 0) {
+    return [
+      `${channel.label} is switched on but the capabilities delivery needs are off, so nothing was sent.`,
+      `Turn these settings on: ${surfaceFeatureGateSettingsKeys(missing).join(', ')}`,
+      describeConfiguredChannels(config),
+    ];
+  }
+  return [];
+}
+
+export async function runSendCommand(
+  argv: readonly string[],
+  deps: SendCommandDeps,
+): Promise<SendCommandResult> {
+  const parsed = parseSendArgs(argv);
+  if (parsed.errors.length > 0) {
+    return { lines: [...parsed.errors, '', USAGE], exitCode: 2 };
+  }
+  if (parsed.help) return { lines: [USAGE], exitCode: 0 };
+  if (parsed.list) return { lines: renderChannelList(deps.configManager), exitCode: 0 };
+
+  // --- which channel -------------------------------------------------------
+  let channel: SendChannel;
+  let usedDefault = false;
+  let defaultReason = '';
+  if (parsed.channel !== null) {
+    const named = findSendChannel(parsed.channel);
+    if (!named) {
+      return {
+        lines: [
+          `Unknown channel: ${parsed.channel}`,
+          `Known channels: ${SEND_CHANNELS.map((entry) => entry.id).join(', ')}`,
+          describeConfiguredChannels(deps.configManager),
+        ],
+        exitCode: 2,
+      };
+    }
+    channel = named;
+  } else {
+    const resolution = resolveDefaultChannel(deps.configManager);
+    if (resolution.kind === 'none') {
+      return {
+        lines: [
+          'No channel was named and none is configured to be the default, so nothing was sent.',
+          'A channel qualifies when it is switched on AND has a destination set.',
+          '',
+          ...renderChannelList(deps.configManager),
+        ],
+        exitCode: 2,
+      };
+    }
+    if (resolution.kind === 'ambiguous') {
+      return {
+        lines: [
+          `No channel was named and more than one qualifies (${resolution.candidates.map((entry) => entry.channel.id).join(', ')}), so nothing was sent.`,
+          'Name one with --channel <id> rather than have this command guess which of your channels to message.',
+        ],
+        exitCode: 2,
+      };
+    }
+    channel = resolution.channel;
+    usedDefault = true;
+    defaultReason = resolution.reason;
+  }
+
+  // --- what to send --------------------------------------------------------
+  let message = parsed.words.join(' ');
+  if (message.trim().length === 0) {
+    if (deps.stdinIsTty) {
+      return {
+        lines: ['No message given. Pass it as an argument or pipe it on stdin.', '', USAGE],
+        exitCode: 2,
+      };
+    }
+    message = (await deps.readStdin()).replace(/\n+$/, '');
+  }
+  if (message.trim().length === 0) {
+    return { lines: ['The message was empty, so nothing was sent.'], exitCode: 2 };
+  }
+
+  const refusal = checkChannelUsable(deps.configManager, channel);
+  if (refusal.length > 0) return { lines: refusal, exitCode: 1 };
+
+  // --- send ----------------------------------------------------------------
+  const runId = deps.newRunId?.() ?? `cli-send-${Date.now().toString(36)}`;
+  const title = parsed.title ?? 'GoodVibes';
+  const body = inertBodyFor(channel.surfaceKind, message);
+  const request: ChannelDeliveryRequest = {
+    target: {
+      kind: 'surface',
+      surfaceKind: channel.surfaceKind,
+      ...(parsed.to === null ? {} : { address: parsed.to }),
+      label: title,
+    },
+    body,
+    title,
+    jobId: 'goodvibes-daemon-send',
+    runId,
+    // A message typed at a shell has no artifacts and no control-plane session
+    // to link back to; a link appended here would point at a page the reader
+    // did not ask for.
+    includeLinks: false,
+  };
+
+  const preamble = usedDefault
+    ? [`No channel named — using ${channel.id}: ${defaultReason}.`]
+    : [];
+  try {
+    const responseId = await deps.deliver(request);
+    return {
+      lines: [
+        ...preamble,
+        `Sent to ${channel.label}${responseId ? ` (${responseId})` : ''}.`,
+      ],
+      exitCode: 0,
+    };
+  } catch (error) {
+    // The provider's own words, not a paraphrase: "Missing Telegram chat id"
+    // and "HTTP 401: Unauthorized" are different problems with different fixes,
+    // and flattening them into "delivery failed" is what makes a failed send
+    // take an hour to diagnose. See failure-text.ts for what is stripped
+    // (credentials) and what is deliberately kept (everything else).
+    return {
+      lines: [
+        ...preamble,
+        `Sending to ${channel.label} failed, so the message did NOT go out.`,
+        describeSendFailure(error),
+      ],
+      exitCode: 1,
+    };
+  }
+}

package/src/daemon/send/composition.ts

@@ -0,0 +1,100 @@
+/**
+ * composition.ts — the smallest set of services that can put a message on a
+ * channel, built from the daemon's own tier.
+ *
+ * ## Why not `createRuntimeServices`
+ *
+ * The daemon's full runtime graph starts a LAN scan, a cluster coordinator, an
+ * inbox poller, a fleet tick, a memory governor and a config watch. Composing
+ * it to send one message would build a second, competing set of that state on a
+ * machine that is already running a daemon — the same reason `cluster …` is
+ * intercepted before any runtime is constructed (see src/daemon/cli.ts). This
+ * builds only the five objects `ChannelDeliveryRouter` needs and starts no
+ * timers, binds no sockets and joins no election, so it is safe to run beside a
+ * live daemon.
+ *
+ * ## Why it does not talk to the running daemon over HTTP either
+ *
+ * That was tried before this command existed: the control-plane API answers
+ * `401 AUTH_REQUIRED` to the operator token as stored on disk. More importantly
+ * an HTTP-backed send would only work while a daemon is up, and the case this
+ * command is for — telling the owner that something has stopped — is exactly
+ * when it may not be.
+ *
+ * ## Where the credentials come from
+ *
+ * `surfaces.*` is a daemon-owned config prefix, so `ConfigManager` overlays
+ * `<home>/.goodvibes/daemon/settings.json` LAST and a bot token stored there is
+ * visible here. `SecretsManager` gets the same `daemonHome` the daemon itself
+ * resolves, so a `goodvibes://secrets/...` reference in one of those keys
+ * resolves against the daemon's store rather than a client silo. Getting that
+ * second half wrong is what produced `Missing Telegram bot token` from a
+ * machine whose token was present and correct.
+ */
+
+import { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
+import { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
+import { ConfigManager, ServiceRegistry, SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
+import { createShellPathService } from '@/runtime/index.ts';
+import { SecretsManager } from '../../config/secrets.ts';
+import type { SendDeliver } from './command.ts';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from '../../config/surface.ts';
+
+export interface SendStackRoots {
+  readonly workingDirectory: string;
+  /** The GoodVibes tree root — the directory `.goodvibes/` sits under. */
+  readonly homeDirectory: string;
+  /** The daemon's own state root, holding the daemon-scoped secret stores. */
+  readonly daemonHomeDirectory: string;
+}
+
+export interface SendStack {
+  readonly configManager: ConfigManager;
+  readonly deliver: SendDeliver;
+}
+
+/**
+ * Build the delivery stack for one CLI send.
+ *
+ * `secretsManager` is passed to `ChannelDeliveryRouter` because the router
+ * REQUIRES it and refuses to construct without it. That requirement is the fix
+ * for a real defect: while the parameter was optional, two shipped composition
+ * roots (goodvibes-tui and goodvibes-agent) omitted it, still type-checked,
+ * still delivered on every surface whose credential happens to sit in config or
+ * the environment, and failed only on the surfaces that use a secret reference
+ * — at send time, as `Missing Telegram bot token`. This composition root does
+ * not repeat that.
+ */
+export function createSendStack(roots: SendStackRoots): SendStack {
+  const configManager = new ConfigManager({
+    workingDir: roots.workingDirectory,
+    homeDir: roots.homeDirectory,
+    surfaceRoot: GOODVIBES_DAEMON_SURFACE_ROOT,
+  });
+  const shellPaths = createShellPathService({
+    workingDirectory: roots.workingDirectory,
+    homeDirectory: roots.homeDirectory,
+  });
+  const secretsManager = new SecretsManager({
+    projectRoot: roots.workingDirectory,
+    globalHome: roots.homeDirectory,
+    // Threaded, never defaulted: a daemon told to run out of an isolated tree
+    // must not read the real home's credential store, and neither must this.
+    daemonHome: roots.daemonHomeDirectory,
+    configManager,
+  });
+  const serviceRegistry = new ServiceRegistry(shellPaths.resolveProjectPath(GOODVIBES_DAEMON_SURFACE_ROOT, 'services.json'), {
+    secretsManager,
+    subscriptionManager: new SubscriptionManager(shellPaths.resolveUserPath(GOODVIBES_DAEMON_SURFACE_ROOT, 'subscriptions.json')),
+  });
+  const router = new ChannelDeliveryRouter({
+    configManager,
+    secretsManager,
+    serviceRegistry,
+    artifactStore: new ArtifactStore({ configManager }),
+  });
+  return {
+    configManager,
+    deliver: (request) => router.deliver(request),
+  };
+}

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)}…`;
+}