@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/platform/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Platform abstraction for the `personal` CLI.
+ *
+ * Every OS-specific behavior lives behind this interface so the commands stay
+ * platform-agnostic. Concrete adapters (darwin / linux / windows) implement
+ * the same contract via polymorphism; `getPlatform()` is the factory.
+ */
+
+export type PlatformName = 'darwin' | 'linux' | 'windows' | 'unknown';
+
+export type NotificationKind =
+  'finished' | 'interrupted' | 'question' | 'permission' | 'error';
+
+export type NotifierCapability = {
+  /** Native rich notifications (click actions where supported). */
+  readonly native: boolean;
+  /** Per-kind sounds. */
+  readonly sounds: boolean;
+  /** Click-to-focus a project window/tab. */
+  readonly clickToFocus: boolean;
+  /** Human reason when a capability is unavailable. */
+  readonly reason?: string;
+};
+
+export type NotifierTestResult = {
+  readonly ok: boolean;
+  readonly detail: string;
+};
+
+export type GlobalInstallResult = {
+  readonly binDir: string;
+  readonly launcherPath: string;
+  readonly created: boolean;
+  readonly alreadyOnPath: boolean;
+};
+
+/** One row of the OS process table (see `listProcesses`). */
+export type ProcessInfo = {
+  readonly pid: number;
+  readonly ppid: number;
+  /** Process group (a shell pipeline / job shares one). */
+  readonly pgid: number;
+  readonly uid: number;
+  /** Resident memory in KiB. */
+  readonly rssKb: number;
+  /** Recent CPU percent (may exceed 100 on multi-core). */
+  readonly cpu: number;
+  /** `ps` state flags; a leading `Z` marks a zombie. */
+  readonly state: string;
+  /** Full command line (executable + args). */
+  readonly command: string;
+};
+
+/** A periodic background job (launchd agent, systemd user timer, …). */
+export type ScheduledJob = {
+  readonly label: string;
+  /** Absolute executable + args. */
+  readonly command: readonly string[];
+  readonly intervalSeconds: number;
+  /** Directory for the job's stdout/stderr logs. */
+  readonly logDir: string;
+  /** Extra environment (e.g. PATH so `bun` resolves outside a login shell). */
+  readonly env: Readonly<Record<string, string>>;
+};
+
+export type ScheduledJobStatus = {
+  readonly supported: boolean;
+  readonly installed: boolean;
+  readonly detail: string;
+};
+
+export type Platform = {
+  /** Optional source-owned native Docker installer. */
+  readonly dockerSetupScript?: string;
+  readonly name: PlatformName;
+  readonly label: string;
+
+  /** `~/.config/opencode` (or the OS equivalent). */
+  opencodeDir(): string;
+  /** `~/.cache` (or the OS equivalent) — daemon sockets live here. */
+  cacheDir(): string;
+  /** Preferred global bin dir (`~/.local/bin` or Windows equivalent). */
+  globalBinDir(): string;
+
+  /** Whether `swiftc` builds / shell shims apply on this platform. */
+  canBuildSwiftNotifier(): boolean;
+  /** Shell RC files to inspect when ensuring `~/.local/bin` is on PATH. */
+  shellRcFiles(): readonly string[];
+
+  notifierCapabilities(): NotifierCapability;
+  /** Best-effort desktop notification. Never throws — returns a result. */
+  postNotification(input: {
+    title: string;
+    message: string;
+    kind: NotificationKind;
+  }): Promise<NotifierTestResult>;
+
+  /** Daemon process running? (best-effort, always safe when unknown). */
+  isNotifierDaemonRunning(): boolean;
+  /** Best-effort daemon restart (kill so the next `--post` relaunches). */
+  restartNotifierDaemon(): void;
+
+  /** System sound names available for per-kind configuration (sorted, unique). */
+  availableSystemSounds(): string[];
+  /** Preview a system sound by name. Never throws — returns a result. */
+  playSystemSound(name: string): Promise<NotifierTestResult>;
+
+  /** Snapshot of every process, or `null` when unsupported on this OS. */
+  listProcesses(): ProcessInfo[] | null;
+
+  /** App-bundled Tailscale CLI binaries that exist (used when `tailscale` is not on PATH). */
+  tailscaleAppBinaries(): readonly string[];
+  /** VS Code user `settings.json`, or `null` when unknown on this OS. */
+  vscodeSettingsPath(): string | null;
+  /** VS Code `code` CLI binaries shipped inside the installed app. */
+  vscodeCliBinaries(): readonly string[];
+
+  /** Install (or replace) a periodic job. Never throws — returns a result. */
+  installScheduledJob(job: ScheduledJob): NotifierTestResult;
+  /** Remove a periodic job. Never throws — returns a result. */
+  removeScheduledJob(label: string): NotifierTestResult;
+  scheduledJobStatus(label: string): ScheduledJobStatus;
+};

package/src/platform/ubuntu-audit.ts

@@ -0,0 +1,66 @@
+import policy from '../../ansible/ubuntu/policy.json';
+import type { Runner } from '../types';
+
+export interface UbuntuAudit {
+  supported: boolean;
+  release: string | null;
+  architecture: string | null;
+  packages: Record<string, string>;
+  desktop: boolean;
+  services: Record<string, boolean>;
+  passwordlessSudo: boolean;
+  rebootPending: boolean;
+}
+const PACKAGES = [...Object.keys(policy.packages), 'tailscale'];
+
+/** Read-only audit: never emit package sources, environment, accounts or raw errors. */
+export async function auditUbuntu(run: Runner): Promise<UbuntuAudit> {
+  const release = await run(['cat', '/etc/os-release']);
+  const arch = await run(['dpkg', '--print-architecture']);
+  const packages = await run([
+    'dpkg-query',
+    '-W',
+    '-f=${Package}\t${Version}\n',
+    ...PACKAGES,
+  ]);
+  const services: Record<string, boolean> = {};
+  for (const name of ['ssh', 'tailscaled', 'beszel-agent', 'docker']) {
+    services[name] = (
+      await run(['systemctl', 'is-active', `${name}.service`])
+    ).ok;
+  }
+  const version =
+    /^VERSION_ID="?([0-9]+\.[0-9]+)"?$/m.exec(release.stdout)?.[1] ?? null;
+  const reported = arch.stdout.trim();
+  const architecture = policy.architectures.includes(reported)
+    ? reported
+    : null;
+  return {
+    supported:
+      release.ok &&
+      /^ID=ubuntu$/m.test(release.stdout) &&
+      version === policy.release &&
+      architecture !== null,
+    release: version,
+    architecture,
+    packages: packageVersions(packages.stdout),
+    desktop: (await run(['test', '-d', '/usr/share/xsessions'])).ok,
+    services,
+    passwordlessSudo: (await run(['sudo', '-n', 'true'])).ok,
+    rebootPending: (await run(['test', '-f', '/var/run/reboot-required'])).ok,
+  };
+}
+function packageVersions(output: string): Record<string, string> {
+  const versions: Record<string, string> = {};
+  for (const line of output.split('\n')) {
+    const [name, version] = line.split('\t');
+    if (
+      name &&
+      PACKAGES.includes(name) &&
+      version &&
+      /^[a-zA-Z0-9.+:~_-]{1,100}$/.test(version)
+    )
+      versions[name] = version;
+  }
+  return versions;
+}

package/src/platform/ubuntu-verify.ts

@@ -0,0 +1,105 @@
+import type { Check, Runner } from '../types';
+
+const LOGIND = {
+  HandleLidSwitch: 's "ignore"',
+  HandleLidSwitchDocked: 's "ignore"',
+  HandleLidSwitchExternalPower: 's "ignore"',
+  IdleAction: 's "ignore"',
+  KillUserProcesses: 'b false',
+  StopIdleSessionUSec: 't 18446744073709551615',
+};
+const POWER_FILES = [
+  '/etc/systemd/logind.conf.d/60-personal-fleet.conf',
+  '/etc/systemd/sleep.conf.d/60-personal-fleet.conf',
+];
+/** Inspect the running manager, not an installer receipt. Reboot acceptance
+ * additionally requires the managed files to predate this kernel boot.
+ */
+export async function verifyUbuntuBoot(
+  user: string,
+  run: Runner
+): Promise<Check[]> {
+  for (const [property, expected] of Object.entries(LOGIND)) {
+    const observed = await run([
+      'busctl',
+      'get-property',
+      'org.freedesktop.login1',
+      '/org/freedesktop/login1',
+      'org.freedesktop.login1.Manager',
+      property,
+    ]);
+    if (!observed.ok || observed.stdout.trim() !== expected)
+      return pending(
+        'UBUNTU_SESSION_POLICY_PENDING',
+        'The running login manager does not expose the declared ' +
+          property +
+          '. Keep active work intact and schedule an explicit maintenance reboot; do not restart logind during sessions.'
+      );
+  }
+  for (const name of [
+    'sleep',
+    'suspend',
+    'hibernate',
+    'hybrid-sleep',
+    'suspend-then-hibernate',
+  ]) {
+    const observed = await run(['systemctl', 'is-enabled', name + '.target']);
+    if (observed.stdout.trim() !== 'masked')
+      return pending(
+        'UBUNTU_SLEEP_POLICY_DRIFT',
+        'A declared sleep transition is not masked. Reapply the approved Ubuntu baseline; preserve user sessions.'
+      );
+  }
+  const linger = await run([
+    'loginctl',
+    'show-user',
+    user,
+    '--property=Linger',
+    '--value',
+  ]);
+  if (!linger.ok || linger.stdout.trim() !== 'yes')
+    return pending(
+      'UBUNTU_LINGER_REQUIRED',
+      'The designated user is not observed as lingering. Reapply the approved user policy before claiming logout survival.'
+    );
+  if (!(await filesPredateBoot(run)))
+    return pending(
+      'UBUNTU_MAINTENANCE_REBOOT_PENDING',
+      'Effective session policy matches, but the managed power files were not observed before this boot. Perform an explicit maintenance reboot and rerun the manager command.'
+    );
+  return [
+    {
+      id: 'ubuntu:boot-policy',
+      status: 'pass',
+      summary:
+        'Managed power files predate this boot; the running login manager exposes the declared no-sleep/session policy, sleep transitions are masked, and designated-user lingering is active.',
+    },
+  ];
+}
+async function filesPredateBoot(run: Runner): Promise<boolean> {
+  const boot = await run(['cat', '/proc/stat']);
+  const seconds = Number(/^btime (\d+)$/m.exec(boot.stdout)?.[1]);
+  if (!boot.ok || !Number.isSafeInteger(seconds) || seconds <= 0) return false;
+  for (const path of POWER_FILES) {
+    const observed = await run(['stat', '--format=%Y', path]);
+    const modified = Number(observed.stdout.trim());
+    if (
+      !observed.ok ||
+      !Number.isSafeInteger(modified) ||
+      modified <= 0 ||
+      modified >= seconds
+    )
+      return false;
+  }
+  return true;
+}
+function pending(code: string, action: string): Check[] {
+  return [
+    {
+      id: 'ubuntu:boot-policy',
+      status: 'fail',
+      summary: code,
+      remedy: { action },
+    },
+  ];
+}

package/src/platform/windows.ts

@@ -0,0 +1,148 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+import type {
+  NotificationKind,
+  NotifierCapability,
+  NotifierTestResult,
+  Platform,
+  ProcessInfo,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+import { existsSync } from 'node:fs';
+
+export class WindowsPlatform implements Platform {
+  readonly name = 'windows' as const;
+  readonly label = 'Windows';
+
+  opencodeDir(): string {
+    const base =
+      process.env['APPDATA']?.trim() || join(homedir(), 'AppData/Roaming');
+    return join(base, 'opencode');
+  }
+
+  cacheDir(): string {
+    const base =
+      process.env['LOCALAPPDATA']?.trim() || join(homedir(), 'AppData/Local');
+    return join(base, 'opencode-cache');
+  }
+
+  globalBinDir(): string {
+    return join(homedir(), '.local/bin');
+  }
+
+  canBuildSwiftNotifier(): boolean {
+    return false;
+  }
+
+  shellRcFiles(): readonly string[] {
+    return [];
+  }
+
+  notifierCapabilities(): NotifierCapability {
+    return {
+      native: true,
+      sounds: false,
+      clickToFocus: false,
+      reason:
+        'Windows uses a PowerShell toast fallback (no sounds, no click-to-focus); the macOS OpenCodeNotifier app is macOS-only.',
+    };
+  }
+
+  async postNotification(input: {
+    title: string;
+    message: string;
+    kind: NotificationKind;
+  }): Promise<NotifierTestResult> {
+    void input.kind;
+    try {
+      const ps = [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `New-BurntToastNotification -Text ${JSON.stringify(input.title)}, ${JSON.stringify(input.message)}`,
+      ];
+      execFileSync('powershell', ps, { stdio: 'ignore' });
+      return { ok: true, detail: 'posted via BurntToast' };
+    } catch {
+      // Fall through to msg.exe.
+    }
+    const r = spawnSync('msg', ['*', `${input.title}: ${input.message}`], {
+      stdio: 'ignore',
+    });
+    if (r.status === 0) return { ok: true, detail: 'posted via msg' };
+    return {
+      ok: false,
+      detail:
+        'no notifier found (install BurntToast: Install-Module BurntToast)',
+    };
+  }
+
+  isNotifierDaemonRunning(): boolean {
+    return false;
+  }
+
+  restartNotifierDaemon(): void {
+    // No daemon on Windows — no-op.
+  }
+
+  availableSystemSounds(): string[] {
+    return [];
+  }
+
+  async playSystemSound(name: string): Promise<NotifierTestResult> {
+    void name;
+    return {
+      ok: false,
+      detail: 'sounds unsupported on Windows (toast fallback has no sound API)',
+    };
+  }
+
+  listProcesses(): ProcessInfo[] | null {
+    return null;
+  }
+
+  tailscaleAppBinaries(): readonly string[] {
+    return ['C:\\Program Files\\Tailscale\\tailscale.exe'].filter((p) =>
+      existsSync(p)
+    );
+  }
+
+  vscodeSettingsPath(): string | null {
+    const base =
+      process.env['APPDATA']?.trim() || join(homedir(), 'AppData/Roaming');
+    return join(base, 'Code/User/settings.json');
+  }
+
+  vscodeCliBinaries(): readonly string[] {
+    const base =
+      process.env['LOCALAPPDATA']?.trim() || join(homedir(), 'AppData/Local');
+    return [join(base, 'Programs/Microsoft VS Code/bin/code.cmd')].filter((p) =>
+      existsSync(p)
+    );
+  }
+
+  installScheduledJob(job: ScheduledJob): NotifierTestResult {
+    return {
+      ok: false,
+      detail: `scheduled jobs are not supported on ${this.label} (${job.label})`,
+    };
+  }
+
+  removeScheduledJob(label: string): NotifierTestResult {
+    return {
+      ok: true,
+      detail: `nothing to remove for ${label} on ${this.label}`,
+    };
+  }
+
+  scheduledJobStatus(label: string): ScheduledJobStatus {
+    return {
+      supported: false,
+      installed: false,
+      detail: `not supported on ${this.label} (${label})`,
+    };
+  }
+}

package/src/power-recovery.ts

@@ -0,0 +1,55 @@
+import { record } from './config';
+import type { Check, Runner } from './types';
+
+/** Only recognize named firmware settings; an enabled OS service is not proof of AC recovery. */
+export async function powerRecoveryCheck(run: Runner): Promise<Check> {
+  const result = await run(
+    ['sudo', '-n', 'fwupdmgr', 'get-bios-settings', '--json'],
+    { timeoutMs: 15_000 }
+  );
+  try {
+    const data: unknown = JSON.parse(result.stdout);
+    const settings =
+      record(data) && Array.isArray(data['BiosSettings'])
+        ? data['BiosSettings']
+        : [];
+    const observed = settings.find(
+      (item) =>
+        record(item) &&
+        [
+          'RestoreACPowerLoss',
+          'AfterPowerLoss',
+          'PowerOnAfterPowerFail',
+          'ACPowerRecovery',
+        ].includes(String(item['Name']))
+    );
+    if (result.ok && record(observed)) {
+      const enabled = ['Power On', 'Always On', 'PowerOn', 'On'].includes(
+        String(observed['CurrentValue'])
+      );
+      return {
+        id: 'worker:power-loss-recovery',
+        status: enabled ? 'pass' : 'fail',
+        summary: enabled
+          ? 'Firmware reports an enabled restore-after-AC-loss setting; a real power-loss test remains distinct from configuration evidence.'
+          : 'Firmware restore-after-AC-loss is disabled.',
+        remedy: {
+          action:
+            'Enable the machine firmware restore-after-AC-loss setting or configure its VM host power recovery.',
+        },
+      };
+    }
+  } catch {
+    /* Firmware output may contain hardware identifiers; never expose it. */
+  }
+  return {
+    id: 'worker:power-loss-recovery',
+    status: 'skip',
+    summary:
+      'Automatic power-on after AC loss is not observable through a supported firmware adapter on this machine.',
+    remedy: {
+      action:
+        'Enable and test restore-on-AC-power in the firmware or VM host during initial enrollment. An OS unit cannot power on a switched-off machine.',
+    },
+  };
+}

package/src/probe.ts

@@ -0,0 +1,51 @@
+import { dependencyCheck, fingerprint } from './fingerprint';
+import { CAPABILITIES } from './config';
+import { authCheck } from './auth-checks';
+import type { Capability, Check, Runner, Snapshot } from './types';
+
+export async function probe(
+  root: string,
+  required: Capability[],
+  run: Runner,
+  nodeId?: string
+): Promise<Snapshot> {
+  const current = await fingerprint(root, run);
+  const checks: Check[] = [
+    {
+      id: 'workspace',
+      status:
+        Object.values(current.files).every(Boolean) && current.head
+          ? 'pass'
+          : 'fail',
+      summary:
+        'Checkout revision and shared dependency/toolchain input availability.',
+    },
+  ];
+  const dirty = await run(['git', 'status', '--porcelain'], { cwd: root });
+  checks.push({
+    id: 'git:clean',
+    status: dirty.ok ? (dirty.stdout.trim() ? 'warn' : 'pass') : 'fail',
+    summary:
+      dirty.ok && !dirty.stdout.trim()
+        ? 'Working tree is clean.'
+        : 'Working tree is dirty or unreadable; sync --pull will refuse.',
+  });
+  checks.push(await dependencyCheck(root, current));
+  for (const capability of CAPABILITIES) {
+    if (required.includes(capability))
+      checks.push(...(await authCheck(capability, run, root, nodeId)));
+    else
+      checks.push({
+        id: `auth:${capability}`,
+        status: 'skip',
+        required: false,
+        summary: 'Not required by this node configuration.',
+      });
+  }
+  return {
+    version: 1,
+    platform: process.platform,
+    fingerprint: current,
+    checks,
+  };
+}

package/src/protocol.ts

@@ -0,0 +1,119 @@
+import { record } from './config';
+import { FINGERPRINT_FILES } from './input-hashes';
+import type { Check, Snapshot } from './types';
+
+const STATUSES = ['pass', 'warn', 'fail', 'skip'];
+
+export function validCheck(value: unknown): value is Check {
+  if (
+    !record(value) ||
+    typeof value['id'] !== 'string' ||
+    !/^[a-z0-9:._-]{1,100}$/.test(value['id']) ||
+    !STATUSES.includes(String(value['status'])) ||
+    typeof value['summary'] !== 'string' ||
+    value['summary'].length > 2000
+  )
+    return false;
+  if (!validDuration(value['phaseDurationMs'])) return false;
+  if (!validRequired(value['required'])) return false;
+  const remedy = value['remedy'];
+  return remedy === undefined || validRemedy(remedy);
+}
+
+function validRemedy(value: unknown): boolean {
+  return (
+    record(value) &&
+    typeof value['action'] === 'string' &&
+    value['action'].length < 2000 &&
+    (value['command'] === undefined || typeof value['command'] === 'string')
+  );
+}
+
+export function validSnapshot(value: unknown): value is Snapshot {
+  if (
+    !record(value) ||
+    value['version'] !== 1 ||
+    typeof value['platform'] !== 'string' ||
+    !Array.isArray(value['checks']) ||
+    value['checks'].length > 200 ||
+    !value['checks'].every(validCheck)
+  )
+    return false;
+  return validFingerprint(value['fingerprint']);
+}
+
+function validFingerprint(value: unknown): boolean {
+  if (!record(value) || !record(value['files'])) return false;
+  if (
+    !Object.keys(value['files']).every((key) => FINGERPRINT_FILES.includes(key))
+  )
+    return false;
+  const head = value['head'];
+  return (
+    (head === null ||
+      (typeof head === 'string' && /^[a-f0-9]{40,64}$/.test(head))) &&
+    Object.values(value['files']).every(validHash)
+  );
+}
+
+function validHash(value: unknown): boolean {
+  return (
+    value === null ||
+    (typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))
+  );
+}
+
+export function decodeSnapshot(output: string): Snapshot | null {
+  try {
+    const data: unknown = JSON.parse(output);
+    return validSnapshot(data) ? cleanSnapshot(data) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function cleanCheck(check: Check): Check {
+  return {
+    id: check.id,
+    status: check.status,
+    summary: check.summary,
+    ...(check.required !== undefined ? { required: check.required } : {}),
+    ...(check.phaseDurationMs !== undefined
+      ? { phaseDurationMs: check.phaseDurationMs }
+      : {}),
+    ...(check.remedy
+      ? {
+          remedy: {
+            action: check.remedy.action,
+            ...(check.remedy.command ? { command: check.remedy.command } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+function cleanSnapshot(snapshot: Snapshot): Snapshot {
+  return {
+    version: 1,
+    platform: snapshot.platform,
+    fingerprint: {
+      head: snapshot.fingerprint.head,
+      files: snapshot.fingerprint.files,
+    },
+    checks: snapshot.checks.map(cleanCheck),
+  };
+}
+
+function validDuration(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (typeof value === 'number' &&
+      Number.isSafeInteger(value) &&
+      value >= 0 &&
+      value <= 86_400_000)
+  );
+}
+
+function validRequired(value: unknown): boolean {
+  return value === undefined || typeof value === 'boolean';
+}