@pellux/goodvibes-tui 1.27.1 → 2.0.2

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

@@ -1,93 +0,0 @@
-/**
- * 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

@@ -1,225 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * 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/daemon/service-commands.ts

@@ -1,329 +0,0 @@
-/**
- * TUI wiring — `goodvibes-daemon install-service | uninstall-service
- * | service-status`.
- *
- * The daemon is a SYSTEM SERVICE. These subcommands install it as a durable host
- * service (systemd user unit on Linux, launchd agent on macOS, a Scheduled Task
- * on Windows) so N surfaces share ONE daemon that survives reboots, instead of
- * every surface spawning a session-scoped daemon.
- *
- * Drift note: the SDK's older `systemd-user-service.ts` (a Linux-only,
- * bespoke systemd shim) was dead code and got deleted from the SDK. The SDK's
- * REAL wired service machinery — reached in production by the daemon's own HTTP
- * `/api/service/*` routes via facade-composition.ts — is
- * `PlatformServiceManager` (`@pellux/goodvibes-sdk/platform/daemon`): a single
- * systemd/launchd/windows-aware manager with install/uninstall/status/start/
- * stop/restart and a `suggestedCommands` hint list. This module now rewires the
- * three CLI subcommands onto that manager instead of the deleted shim.
- *
- * Two real behavioral differences from the old shim, called out honestly:
- *   - `install()` only WRITES the unit/plist/task; it does not enable/start it.
- *     So `install-service` here calls `install()` then `start()` to preserve the
- *     old "install implies enabled + running" behavior.
- *   - `uninstall()` only REMOVES the unit file; there is no manager-level
- *     `disable` verb (only start/stop/restart exist). So `uninstall-service`
- *     calls `stop()` then `uninstall()`, and honestly tells the caller that a
- *     stray "enabled" symlink may remain until `systemctl --user daemon-reload`
- *     (offered back as a suggested follow-up) or the next login cleans it up.
- *
- * A fourth subcommand, `migrate-service`, closes the earlier "detect and
- * disclose only" inheritance (W3 Finding 4, below) with a GUIDED, CONSENTED
- * takeover of the legacy `goodvibes-daemon.service` unit. Design constraints,
- * all load-bearing:
- *   - NEVER auto-migrate. Without explicit consent (`confirmMigration`, wired
- *     from the CLI's existing `-y`/`--yes` flag) this prints the exact plan
- *     and touches nothing.
- *   - NEW-UP-THEN-OLD-DOWN. The new `goodvibes.service` unit is installed,
- *     started, and verified healthy (a fresh `status().running` read, which
- *     honestly queries systemd via the injected actionRunner) BEFORE the
- *     legacy unit is stopped, disabled, or removed. A failed or unhealthy new
- *     unit rolls itself back (uninstalled) and never touches the legacy one
- *     — a botched takeover must never cost the user their working daemon.
- *   - ADOPT-OR-WARN, NEVER KILL. If the legacy unit file is simply absent but
- *     something is already listening on the configured host:port (Mike's real
- *     dev-host case: a manual `nohup`'d daemon with no unit at all), this is
- *     an unidentified process, not a managed unit — there is nothing to stop
- *     or disable, and this module will not attempt to kill it. It warns and
- *     leaves the decision to the operator.
- *   - Every action (legacy stop/disable, unit-file removal, daemon-reload)
- *     goes through the SAME injectable `actionRunner`/`legacyUnitFileRemove`
- *     seams tests already use — this module never has a code path that bypasses
- *     them, so the migration is exercised deterministically via fakes and never
- *     touches a real running service in tests.
- */
-
-import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
-import { PlatformServiceManager, type ManagedServiceStatus } from '@pellux/goodvibes-sdk/platform/daemon';
-import {
-  buildManagedDaemonServiceManager,
-  detectLegacyUnit,
-  legacyUnitNote,
-  resolveManagedUnitName,
-  runLegacyDaemonMigration,
-  LEGACY_SERVICE_UNIT_NAME,
-  MANAGED_SERVICE_NAME as SERVICE_NAME,
-  MANAGED_SERVICE_DESCRIPTION as SERVICE_DESCRIPTION,
-  type LegacyUnitInfo,
-  type ManagedServiceActionRunner,
-} from '../runtime/legacy-daemon-migration.ts';
-
-// `resolveInstalledDaemonBinary` lives in the runtime module (shared with the
-// onboarding guided UX) — re-exported here so this module stays the CLI's
-// stable public surface (and so existing test imports keep working).
-export {
-  resolveInstalledDaemonBinary,
-  type ResolveDaemonBinaryOptions,
-} from '../runtime/legacy-daemon-migration.ts';
-export type { ManagedServiceActionRunner } from '../runtime/legacy-daemon-migration.ts';
-
-// ---------------------------------------------------------------------------
-// Legacy-unit detection, plus guided migration.
-//
-// The prior command installed the daemon's systemd unit under the
-// literal name `goodvibes-daemon.service`. This module (rewired onto
-// PlatformServiceManager, see the file banner above) manages a DIFFERENT
-// unit name (`goodvibes`, SERVICE_NAME). A host that still has the legacy
-// unit installed — this dev machine included — would otherwise see
-// service-status honestly report installed:false/running:false for the
-// tracked name while the legacy unit keeps running untouched underneath it,
-// uninstall-service would silently leave the legacy unit orphaned with no
-// mention, and install-service could start a SECOND daemon competing for the
-// same port.
-//
-// The detection (`detectLegacyUnit`/`legacyUnitNote`) and the guided
-// migration engine (`runLegacyDaemonMigration`) both live in
-// `../runtime/legacy-daemon-migration.ts` rather than here, so the TUI's
-// onboarding UX (`src/input/handler-onboarding-daemon-adopt.ts`) can reuse
-// them directly — the architecture gate forbids `src/input/**` from
-// importing `src/daemon/**` (input must stay entrypoint-agnostic), so the
-// shared engine lives in the entrypoint-agnostic `runtime` layer instead and
-// this CLI module is just one of its two consumers.
-//
-// This detection is entirely independent of PlatformServiceManager's own
-// status() — it does not rely on (or get invalidated by) the parallel SDK
-// fix that makes status().running itself query systemd honestly for the
-// TRACKED unit name.
-// ---------------------------------------------------------------------------
-
-export type DaemonServiceSubcommand = 'install-service' | 'uninstall-service' | 'service-status' | 'migrate-service';
-
-export function isDaemonServiceSubcommand(value: string | undefined): value is DaemonServiceSubcommand {
-  return value === 'install-service' || value === 'uninstall-service' || value === 'service-status' || value === 'migrate-service';
-}
-
-export interface DaemonServiceCliInput {
-  readonly subcommand: DaemonServiceSubcommand;
-  readonly binaryPath: string;
-  readonly homeDir: string;
-  readonly host: string;
-  readonly port: number;
-  /** Defaults to `homeDir` — overridable so tests can scope both to one tempdir. */
-  readonly workingDirectory?: string | undefined;
-  /** Injected in tests; a real `ConfigManager` rooted at `homeDir` otherwise. */
-  readonly configManager?: ConfigManager | undefined;
-  /** Injectable systemctl/launchctl/schtasks runner so tests never touch the host. */
-  readonly actionRunner?: ManagedServiceActionRunner | undefined;
-  /** Injectable existsSync for the legacy-unit file check (W3 Finding 4) so tests never touch the host filesystem. */
-  readonly legacyUnitFileExists?: ((path: string) => boolean) | undefined;
-  /**
-   * `migrate-service` only: explicit consent to actually execute the
-   * migration (wired from the CLI's `-y`/`--yes` flag). Without it, the
-   * subcommand prints the exact plan and changes nothing — never auto-migrate.
-   */
-  readonly confirmMigration?: boolean | undefined;
-  /**
-   * `migrate-service` only: injectable port-liveness check for the
-   * legacy-absent branch (never a raw network call in tests). Defaults to a
-   * real, read-only TCP connect attempt.
-   */
-  readonly portProbe?: ((host: string, port: number) => boolean | Promise<boolean>) | undefined;
-  /**
-   * `migrate-service` only: injectable removal of the legacy unit file, so
-   * tests never call a raw fs op against a real path. Defaults to a real
-   * `rmSync`.
-   */
-  readonly legacyUnitFileRemove?: ((path: string) => void) | undefined;
-}
-
-export interface DaemonServiceCliResult {
-  readonly ok: boolean;
-  readonly exitCode: number;
-  /** Honest, human-readable stdout lines describing exactly what happened. */
-  readonly lines: readonly string[];
-  readonly status: ManagedServiceStatus;
-}
-
-/**
- * The manager's definition (`ExecStart` command/args, name, description) is
- * built once, in `../runtime/legacy-daemon-migration.ts`, and shared with the
- * onboarding guided UX — see that module's doc comment for why.
- */
-function buildManager(input: DaemonServiceCliInput): PlatformServiceManager {
-  return buildManagedDaemonServiceManager({
-    binaryPath: input.binaryPath,
-    homeDir: input.homeDir,
-    host: input.host,
-    port: input.port,
-    workingDirectory: input.workingDirectory,
-    configManager: input.configManager,
-    actionRunner: input.actionRunner,
-  });
-}
-
-function statusLines(status: ManagedServiceStatus): string[] {
-  const lines = [
-    `platform: ${status.platform}`,
-    `installed: ${status.installed}`,
-    `running: ${status.running}`,
-    `unit path: ${status.path}`,
-  ];
-  if (status.pid !== undefined) lines.push(`pid: ${status.pid}`);
-  if (status.platform !== 'manual' && status.installed && !status.running) {
-    // W3 Finding 4: this used to assert "'running' here only reflects
-    // processes this tool started directly" — true for the pid-file-only
-    // check the (currently linked) SDK still uses, but the parallel SDK
-    // batch is making status().running query systemd honestly via
-    // `is-active`, which would make that specific claim stale. Drop the
-    // claim about HOW running was computed and just offer the escape
-    // hatch — true and useful under either SDK version.
-    lines.push(
-      `note: if this looks wrong, verify directly: ${status.suggestedCommands[status.suggestedCommands.length - 1] ?? 'the platform service-status command'}`,
-    );
-  }
-  return lines;
-}
-
-/**
- * Build the install-branch's result lines. Exported for direct unit
- * coverage: the "suggested follow-ups" block is gated on the actual
- * not-started case (W3 Finding 4 friction fix) rather than printed
- * unconditionally, and driving that through the full
- * PlatformServiceManager/systemd integration can't reliably produce
- * `running: true` under the (currently linked) SDK build, whose systemd
- * status check is still pid-file-only (see the honesty note above).
- */
-export function buildInstallResultLines(status: ManagedServiceStatus): string[] {
-  const lines = [`installed the ${status.platform} service at ${status.path}`];
-  if (status.running) {
-    lines.push('service is enabled and running');
-  } else {
-    lines.push('suggested follow-ups if it did not start automatically:');
-    for (const cmd of status.suggestedCommands) lines.push(`  ${cmd}`);
-  }
-  return lines;
-}
-
-function ok(action: 'install' | 'uninstall' | 'status', status: ManagedServiceStatus, extra: string[] = []): DaemonServiceCliResult {
-  const lines: string[] = [];
-  if (action === 'install') {
-    lines.push(...buildInstallResultLines(status));
-  } else if (action === 'uninstall') {
-    lines.push(`removed the ${status.platform} service at ${status.path}`);
-    if (status.platform === 'systemd') {
-      lines.push(
-        "note: this removes the unit file but does not run `disable` — run " +
-          "`systemctl --user daemon-reload` to clear any stale enablement symlink.",
-      );
-    }
-  } else {
-    lines.push(...statusLines(status));
-  }
-  lines.push(...extra);
-  return { ok: true, exitCode: 0, lines, status };
-}
-
-function failed(action: 'install' | 'uninstall' | 'status', status: ManagedServiceStatus): DaemonServiceCliResult {
-  return {
-    ok: false,
-    exitCode: 1,
-    lines: [`service ${action} failed: ${status.actionError ?? 'unknown error'}`],
-    status,
-  };
-}
-
-/**
- * `migrate-service`: the guided, consented takeover of the legacy
- * `goodvibes-daemon.service` unit. Thin wrapper over
- * `runLegacyDaemonMigration` (`../runtime/legacy-daemon-migration.ts`) — see
- * that module for the design constraints (never auto-migrate,
- * new-up-then-old-down, adopt-or-warn/never kill an unrecognized process,
- * every action through an injectable seam) and the onboarding UX consumer.
- */
-function runMigrateService(
-  input: DaemonServiceCliInput,
-  manager: PlatformServiceManager,
-  legacy: LegacyUnitInfo,
-): Promise<DaemonServiceCliResult> {
-  return runLegacyDaemonMigration(
-    {
-      host: input.host,
-      port: input.port,
-      trackedServiceName: SERVICE_NAME,
-      confirmMigration: input.confirmMigration,
-      portProbe: input.portProbe,
-      legacyUnitFileRemove: input.legacyUnitFileRemove,
-      actionRunner: input.actionRunner,
-    },
-    manager,
-    legacy,
-  );
-}
-
-/** Dispatch a daemon service subcommand to the SDK's `PlatformServiceManager`. */
-export async function runDaemonServiceCli(input: DaemonServiceCliInput): Promise<DaemonServiceCliResult> {
-  const manager = buildManager(input);
-  const legacy = detectLegacyUnit(input);
-  switch (input.subcommand) {
-    case 'migrate-service':
-      return runMigrateService(input, manager, legacy);
-    case 'install-service': {
-      // W3 Finding 4: refuse rather than risk starting a second daemon
-      // alongside an already-installed legacy unit. Refuses whenever the
-      // legacy unit is present at all (not just when currently active) —
-      // an installed-but-inactive legacy unit can still be enabled and
-      // start competing for the same port later, and "never silently
-      // start a second daemon" is the bar here, not "never right now."
-      if (legacy.present) {
-        const status = manager.status();
-        const resolvedName = resolveManagedUnitName(status);
-        return {
-          ok: false,
-          exitCode: 1,
-          lines: [
-            `service install refused: a service is already installed as ${LEGACY_SERVICE_UNIT_NAME}.service (the unit name the goodvibes install script manages).`,
-            legacyUnitNote(legacy, resolvedName),
-            `Installing this tool's ${resolvedName}.service alongside it risks two daemons competing for the same port.`,
-          ],
-          status,
-        };
-      }
-      const installed = manager.install();
-      if (installed.actionError) return failed('install', installed);
-      const started = manager.start();
-      // start()'s actionError (e.g. a platform this manager can't dispatch
-      // actions for) doesn't undo the write — report install as ok, but surface
-      // the follow-up problem honestly instead of claiming it is running.
-      return started.actionError
-        ? ok('install', { ...started, running: false }, [`could not start it automatically: ${started.actionError}`])
-        : ok('install', started);
-    }
-    case 'uninstall-service': {
-      const stopped = manager.stop();
-      const uninstalled = manager.uninstall();
-      if (uninstalled.actionError) return failed('uninstall', uninstalled);
-      const extra: string[] = [];
-      if (stopped.actionError) extra.push(`(it may not have been running: ${stopped.actionError})`);
-      // This command only ever touches the TRACKED unit (whatever name/path
-      // actually resolved — not necessarily the SERVICE_NAME constant) above —
-      // say so explicitly when an install-script unit also exists, so its
-      // continued presence is never a silent surprise.
-      if (legacy.present) extra.push(legacyUnitNote(legacy, resolveManagedUnitName(uninstalled)));
-      return ok('uninstall', uninstalled, extra);
-    }
-    case 'service-status': {
-      const status = manager.status();
-      if (status.actionError) return failed('status', status);
-      return ok('status', status, legacy.present ? [legacyUnitNote(legacy, resolveManagedUnitName(status))] : []);
-    }
-  }
-}