@pellux/goodvibes-tui 1.25.0 → 1.27.0

package/src/runtime/device-posture-composition.ts

@@ -0,0 +1,110 @@
+/**
+ * device-posture-composition.ts — the paired-phone feature inside THIS daemon.
+ *
+ * A phone pairs with whichever daemon the person runs, and for this owner that
+ * daemon is hosted by the terminal app. Until this module existed the app had no
+ * device posture at all: `device.nodes.maxPaired` was enforced at the pairing
+ * path (SDK-side) and `device.capabilities.mode` was an onboarding toggle, while
+ * the other eleven `device.*` keys were recorded, read back, and governed
+ * nothing — the capability service they describe was never built here, so there
+ * was nothing for them to govern.
+ *
+ * The feature itself is platform-owned (`platform/devices`): the settings→policy
+ * mapping, the grants ledger, the capture store, the housekeeping sweeps, the
+ * confirmation flow, and the `phone` tool. This module supplies the three seams
+ * that are actually ours and nothing else:
+ *
+ *   - the peer transport — the same DistributedRuntimeManager the remote surface
+ *     pairs devices onto, so a phone paired here is a node here,
+ *   - the approval path — the shared approval broker, so the confirmation
+ *     appears wherever the person is looking (terminal, web app, companion),
+ *   - the storage root and the live config manager.
+ *
+ * Constructing this starts nothing. `startHousekeeping()` is called from the
+ * bootstrap tail: grants and captures both outlive a restart, so a grant whose
+ * phone is gone, or a capture torn by a crash, is reaped BEFORE the first
+ * request of this run is served — and the periodic sweep after it is what keeps
+ * a long-running daemon from going days without one. A failed sweep is logged
+ * and the app still runs: housekeeping failing is a reason to say so, not a
+ * reason to refuse to start.
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import { createDevicePostureRuntime, registerDevicePhoneTool } from '@pellux/goodvibes-sdk/platform/devices';
+import type {
+  DeviceApprovalBridge,
+  DevicePeerTransport,
+  DevicePhoneToolRegistry,
+  DevicePostureRuntime,
+} from '@pellux/goodvibes-sdk/platform/devices';
+import { registerDevicesGatewayMethods } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/** Who this surface records in the device audit trail. */
+export const TUI_DEVICE_ACTOR = 'tui:phone-tool';
+
+export interface DevicePostureCompositionOptions {
+  readonly configManager: ConfigManager;
+  /** The runtime devices pair onto; its listPeers/invokePeer are the transport. */
+  readonly distributedRuntime: DevicePeerTransport;
+  readonly approvals: DeviceApprovalBridge;
+  /** Surface-scoped directory the grants ledger, captures and disclosure live in. */
+  readonly stateDirectory: string;
+  /**
+   * Binding the catalog turns devices.nodes.list / devices.grants.* /
+   * devices.housekeeping.run from cataloged-but-unhandled into real handlers,
+   * which is what makes the grants surface work in the web app and the companion
+   * rather than only through this app's own tool.
+   */
+  readonly gatewayMethods?: GatewayMethodCatalog | undefined;
+  readonly getSessionId?: (() => string | undefined) | undefined;
+}
+
+export interface DevicePostureServices {
+  readonly devicePosture: DevicePostureRuntime;
+}
+
+/** Build the device posture runtime and bind the device verbs to it. */
+export function createDevicePostureServices(options: DevicePostureCompositionOptions): DevicePostureServices {
+  const devicePosture = createDevicePostureRuntime({
+    transport: options.distributedRuntime,
+    approvals: options.approvals,
+    config: options.configManager,
+    stateDirectory: options.stateDirectory,
+    actor: TUI_DEVICE_ACTOR,
+    ...(options.getSessionId ? { getSessionId: options.getSessionId } : {}),
+  });
+  if (options.gatewayMethods) registerDevicesGatewayMethods(options.gatewayMethods, devicePosture);
+  return { devicePosture };
+}
+
+/**
+ * Everything a host with a tool registry has to do once it is up: register the
+ * `phone` tool — the only path that reaches the capability service, so without it
+ * the posture keys govern nothing a session can observe — and start housekeeping.
+ *
+ * One call, because these two belong to the same feature and a host that did the
+ * first and forgot the second would serve requests while never reaping a grant
+ * whose phone is gone.
+ */
+export function installDevicePosture(
+  toolRegistry: DevicePhoneToolRegistry,
+  devicePosture: DevicePostureRuntime,
+): void {
+  registerDevicePhoneTool(toolRegistry, devicePosture);
+  startDeviceHousekeeping(devicePosture);
+}
+
+/**
+ * The recovery sweep plus the periodic timer. Separate from construction so
+ * composing a runtime in a test starts no timer and touches no disk, and
+ * separate from the call above so the standalone daemon — which registers no
+ * tools — still sweeps.
+ */
+export function startDeviceHousekeeping(devicePosture: DevicePostureRuntime): void {
+  void devicePosture.startHousekeeping().catch((error: unknown) => {
+    logger.warn('Device housekeeping sweep failed at startup', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  });
+}

package/src/runtime/disposal-wiring.ts

@@ -38,6 +38,14 @@ export { createDisposalScope };
 export interface SurfaceRuntimePollerOwners extends Omit<RuntimePollerOwners, 'stopConfigWatch'> {
   /** Fork-only: the repeating crash-residue sweep (durability-services.ts). */
   readonly stopDurabilityHousekeeping: () => void;
+  /**
+   * Fork-only: the wake-word recovery sweep and a pending boot provision
+   * (voice-setup-services.ts). Started only when an entrypoint opted into boot
+   * provisioning, and a no-op otherwise — but it is on this list unconditionally,
+   * because "the graph did not start it this time" is not a reason for the
+   * teardown path to have no way to stop it.
+   */
+  readonly stopWakeHousekeeping: () => void;
   /**
    * Fork-only: the daemon handler surfaces (daemon-handler-composition.ts).
    *
@@ -47,6 +55,12 @@ export interface SurfaceRuntimePollerOwners extends Omit<RuntimePollerOwners, 's
    * exists, so if this surface does not stop them nothing does.
    */
   readonly daemonHandlers: { readonly unregister: () => void };
+  /**
+   * Fork-only: the paired-phone feature's housekeeping timer
+   * (device-posture-composition.ts). Started by whichever entry point boots the
+   * host, so the stop belongs on this list rather than in one shutdown path.
+   */
+  readonly devicePosture: { readonly stopHousekeeping: () => void };
 }
 
 /**
@@ -72,6 +86,8 @@ export function registerSurfaceRuntimePollers(
 ): void {
   registerRuntimePollers(registry, { ...services, stopConfigWatch: extras.stopConfigWatch });
   registry.add('durability housekeeping', services.stopDurabilityHousekeeping);
+  registry.add('device housekeeping', () => services.devicePosture.stopHousekeeping());
+  registry.add('wake-word housekeeping', services.stopWakeHousekeeping);
   // Registered LAST so it tears down FIRST (the scope unwinds in reverse), which
   // is the order daemon/cli.ts already used by hand: release the handler surfaces
   // — closing the inbox store and stopping its poll timers — before the pollers

package/src/runtime/install-self-check-startup.ts

@@ -17,6 +17,7 @@
 import { existsSync } from 'node:fs';
 import { getGoodVibesPackageRoot, resolveGoodVibesDaemonExecutable } from '../cli/service-posture.ts';
 import { runInstallSelfCheck } from './install-self-check.ts';
+import { announceReachability } from './path-shadow-startup.ts';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 
 export function announceInstallSelfCheck(router: SystemMessageRouter): void {
@@ -34,3 +35,25 @@ export function announceInstallSelfCheck(router: SystemMessageRouter): void {
     // Best-effort — an install self-check must never block or crash boot.
   }
 }
+
+/**
+ * The one call boot makes about the state of this install: is it complete
+ * (the check above), is it the copy the shell actually reaches, and is it the
+ * current release (path-shadow-startup).
+ *
+ * They are announced together because they are the same question from the
+ * user's side — "am I looking at the build I think I am" — and because the
+ * three answers are useless apart: a complete install nobody can reach, or a
+ * reachable install three versions old, both end with the product appearing
+ * to have lost a capability it never had.
+ *
+ * The reachability half is async (it may look up the latest release) and is
+ * deliberately not awaited: boot continues, the notice arrives through the
+ * same router a moment later.
+ */
+export function announceInstallHealth(router: SystemMessageRouter): void {
+  announceInstallSelfCheck(router);
+  void announceReachability(router).catch(() => {
+    // Best-effort — a reachability check must never block or crash boot.
+  });
+}

package/src/runtime/onboarding/types.ts

@@ -281,7 +281,12 @@ export type OnboardingApplyOperation =
       readonly kind: 'set-secret';
       readonly key: string;
       readonly value: string;
-      readonly scope?: 'project' | 'user';
+      /**
+       * Which secret tier the value is filed in. 'daemon' is the tier the
+       * daemon reads with every surface closed — see
+       * config/secret-config.ts#defaultSecretBackedScope.
+       */
+      readonly scope?: 'project' | 'user' | 'daemon';
       readonly medium: 'secure' | 'plaintext';
     }
   | {

package/src/runtime/path-shadow-startup.ts

@@ -0,0 +1,243 @@
+/**
+ * path-shadow-startup.ts — the boot-time surfacing of "is this the build you
+ * are actually reaching, and is it the current one".
+ *
+ * It wires the real host inputs (this process's executable, the real PATH,
+ * existsSync/realpathSync, and a bounded `<path> --version` spawn) into the
+ * pure scan in path-shadow.ts and the pure wording in reachability-notice.ts,
+ * then prints the result through the same SystemMessageRouter the rest of
+ * startup uses, at high priority, before the session gets going.
+ *
+ * Cost discipline, because this runs on every start:
+ *   - the first scan is existence-only: no process is spawned while there is
+ *     nothing to report, which is the overwhelmingly common case;
+ *   - versions are probed only after a shadow has already been found, and
+ *     only with `--version`, bounded by a short timeout;
+ *   - the latest-release lookup only happens when it can actually change what
+ *     the user should do: a package-managed or source install (which will
+ *     never swap itself), or an install that has just been found unreachable.
+ *     A healthy binary install has already been brought to the latest release
+ *     by the launch auto-updater, so asking again would be a network round
+ *     trip that can only confirm what just happened.
+ *
+ * Every failure is swallowed. A reachability check must never block or crash
+ * boot.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { detectInstallKind, fallbackUpdateCommand, type UpdateFetchLike } from './update-check.ts';
+import { checkForUpdate } from '../input/commands/update-runtime.ts';
+import {
+  scanCommandShadows,
+  splitPathEntries,
+  type ShadowScanResult,
+} from './path-shadow.ts';
+import { buildReachabilityNotices, type ReachabilityNotice } from './reachability-notice.ts';
+import { VERSION } from '../version.ts';
+import type { SystemMessageRouter } from '../core/system-message-router.ts';
+
+/** The commands a goodvibes install places side by side in one directory. */
+export const INSTALLED_COMMANDS = ['goodvibes', 'goodvibes-daemon', 'goodvibes-agent'] as const;
+
+/** How long a `<path> --version` probe may take before it is abandoned. */
+const VERSION_PROBE_TIMEOUT_MS = 3000;
+/** How long the latest-release lookup may take before startup moves on without it. */
+const LATEST_LOOKUP_TIMEOUT_MS = 2500;
+
+function safeRealPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function isExecutableFile(path: string): boolean {
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile()) return false;
+    // Any execute bit is enough: the shell searches for an executable file,
+    // and which bit applies depends on ownership we are not going to compute.
+    return (stats.mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Runs `<path> --version` and returns its first line. Never inherits stdio, so
+ * a binary that tries to draw a terminal cannot disturb this one.
+ */
+export function probeVersionLine(path: string): string | undefined {
+  try {
+    const result = spawnSync(path, ['--version'], {
+      timeout: VERSION_PROBE_TIMEOUT_MS,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    if (result.error || typeof result.stdout !== 'string') return undefined;
+    return result.stdout.split('\n')[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The PATH directory that provides THIS running executable, which is the
+ * position everything else is measured against.
+ *
+ * Preferred answer: the first PATH entry whose `<dir>/<command>` resolves,
+ * through symlinks, to this same file. That is exactly "where the shell would
+ * find me", and it is right for a linked package install as well as a
+ * standalone binary.
+ *
+ * Fallback, for a standalone binary only: the directory the executable sits
+ * in. That directory being absent from PATH is itself worth reporting — an
+ * installed binary nobody can reach by name. For a package-managed install
+ * the executable lives inside node_modules, which is never on PATH and never
+ * meant to be, so there is nothing honest to say and the check stays silent.
+ */
+export function resolveSelfDirectory(input: {
+  readonly execPath: string;
+  readonly command: string;
+  readonly pathEntries: readonly string[];
+  readonly realPath: (path: string) => string;
+  readonly isExecutableFile: (path: string) => boolean;
+}): string | undefined {
+  const self = input.realPath(input.execPath);
+  for (const directory of input.pathEntries) {
+    const candidate = join(directory, input.command);
+    if (!input.isExecutableFile(candidate)) continue;
+    if (input.realPath(candidate) === self) return directory;
+  }
+  if (detectInstallKind(input.execPath) === 'binary') return dirname(self);
+  return undefined;
+}
+
+/** Which of the installed commands actually sit in this directory. */
+function commandsPresentIn(directory: string, exists: (path: string) => boolean): string[] {
+  return INSTALLED_COMMANDS.filter((command) => exists(join(directory, command)));
+}
+
+export interface ReachabilityCheckResult {
+  readonly notices: readonly ReachabilityNotice[];
+  readonly scan?: ShadowScanResult | undefined;
+}
+
+/**
+ * The whole check, with the network lookup injected so tests never reach it.
+ * Returns the notices to print; an empty list is the healthy case.
+ */
+export async function runReachabilityCheck(input: {
+  readonly execPath: string;
+  readonly pathValue: string | undefined;
+  readonly homeDir: string;
+  readonly runningVersion: string;
+  readonly commandName?: string | undefined;
+  /** Resolves the newest released version, or undefined when it cannot be determined. */
+  readonly resolveLatest: () => Promise<string | undefined>;
+  // The host touches, injectable so a test drives a whole scenario with fake
+  // paths and never spawns anything. Production passes none of these.
+  readonly isExecutableFile?: ((path: string) => boolean) | undefined;
+  readonly realPath?: ((path: string) => string) | undefined;
+  readonly probeVersion?: ((path: string) => string | undefined) | undefined;
+}): Promise<ReachabilityCheckResult> {
+  const command = input.commandName ?? basename(input.execPath);
+  const pathEntries = splitPathEntries(input.pathValue);
+  const installKind = detectInstallKind(input.execPath);
+  const fileIsExecutable = input.isExecutableFile ?? isExecutableFile;
+  const resolvePath = input.realPath ?? safeRealPath;
+  const versionProbe = input.probeVersion ?? probeVersionLine;
+
+  // A source checkout is not an install: there is no maintained copy to be
+  // shadowed and no release to be behind.
+  if (installKind === 'source') return { notices: [] };
+
+  const selfDirectory = resolveSelfDirectory({
+    execPath: input.execPath,
+    command,
+    pathEntries,
+    realPath: resolvePath,
+    isExecutableFile: fileIsExecutable,
+  });
+  if (!selfDirectory) return { notices: [] };
+
+  const commands = commandsPresentIn(selfDirectory, fileIsExecutable);
+  const base = {
+    commands: commands.length > 0 ? commands : [command],
+    installDir: selfDirectory,
+    pathEntries,
+    homeDir: input.homeDir,
+    isExecutableFile: fileIsExecutable,
+    realPath: resolvePath,
+  };
+
+  // Existence-only first: nothing is spawned while there is nothing to report.
+  const cheapScan = scanCommandShadows(base);
+  const scan = cheapScan.hasProblem
+    ? scanCommandShadows({ ...base, probeVersion: versionProbe })
+    : cheapScan;
+
+  const latestVersion = scan.hasProblem || installKind !== 'binary'
+    ? await input.resolveLatest()
+    : undefined;
+
+  return {
+    scan,
+    notices: buildReachabilityNotices({
+      scan,
+      runningVersion: input.runningVersion,
+      latestVersion,
+      updateCommand: installKind === 'binary'
+        ? 'curl -fsSL https://goodvibes.sh/install.sh | sh'
+        : fallbackUpdateCommand(installKind),
+    }),
+  };
+}
+
+/** The real latest-release lookup, bounded so a slow network cannot hold up boot. */
+async function resolveLatestReleaseBounded(): Promise<string | undefined> {
+  try {
+    // The same release lookup /update uses — there is deliberately no second
+    // source of truth for what the latest version is.
+    const lookup = checkForUpdate(fetch as UpdateFetchLike, VERSION).then((result) => result.latestTag);
+    const timed = await Promise.race([
+      lookup,
+      new Promise<undefined>((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), LATEST_LOOKUP_TIMEOUT_MS);
+        timer.unref?.();
+      }),
+    ]);
+    return timed ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Boot-time wiring. Prints one high-priority system message per line so the
+ * report reads as prose rather than a single wrapped paragraph, and swallows
+ * everything.
+ */
+export async function announceReachability(router: SystemMessageRouter): Promise<void> {
+  try {
+    const result = await runReachabilityCheck({
+      execPath: process.execPath,
+      pathValue: process.env['PATH'],
+      homeDir: process.env['HOME'] ?? '',
+      runningVersion: VERSION,
+      commandName: 'goodvibes',
+      resolveLatest: resolveLatestReleaseBounded,
+    });
+    for (const notice of result.notices) {
+      for (const line of notice.lines) {
+        router.high(`[Install] ${line}`);
+      }
+    }
+  } catch {
+    // Best-effort — a reachability check must never block or crash boot.
+  }
+}