@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/src/package-info.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Where this code's own files live: the published package, or a checkout. */
+export const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+export interface PackageInfo {
+  name: string;
+  version: string;
+  /** The commit this package was published from; null in a checkout. */
+  revision: string | null;
+  /** Where a defect or a feature request is raised (`bugs` in the manifest). */
+  issues: string | null;
+}
+
+function issueTracker(bugs: unknown): string | null {
+  const url =
+    typeof bugs === 'object' && bugs !== null
+      ? (bugs as { url?: unknown }).url
+      : bugs;
+  return typeof url === 'string' && /^https:\/\/\S+$/.test(url) ? url : null;
+}
+
+/** What the running package says about itself. The release workflow stamps
+ * the version and the commit (`gitHead`) into the package it publishes, so an
+ * installed dev-fleet knows which revision every machine has to run. A
+ * checkout carries neither: its revision is its own HEAD. The issue tracker
+ * comes from the manifest too, so a fork sends its users to its own.
+ */
+export function packageInfo(root = PACKAGE_ROOT): PackageInfo {
+  const manifest = JSON.parse(
+    readFileSync(join(root, 'package.json'), 'utf8')
+  ) as { name?: unknown; version?: unknown; gitHead?: unknown; bugs?: unknown };
+  const { gitHead } = manifest;
+  return {
+    name: String(manifest.name),
+    version: String(manifest.version),
+    revision:
+      typeof gitHead === 'string' && /^[a-f0-9]{40}$/.test(gitHead)
+        ? gitHead
+        : null,
+    issues: issueTracker(manifest.bugs),
+  };
+}

package/src/platform/ansible-receipt.ts

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, relative } from 'node:path';
+import { runAnsible } from './ansible';
+import type { CommandOptions, CommandResult, Runner } from '../types';
+
+/** Full re-apply at least this often, so drift a cheap check misses still heals. */
+export const RECEIPT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface Receipt {
+  /** Stable receipt name, e.g. `ubuntu-baseline`. */
+  name: string;
+  /** Files or directories whose content the playbook result depends on. */
+  sources: string[];
+  /** Cheap postcondition probe; a skip happens only while it passes. */
+  verify: () => Promise<boolean>;
+  /** Ignore any receipt and apply in full. */
+  force?: boolean;
+  /** Receipt directory; defaults to the user's fleet state. */
+  directory?: string;
+  now?: number;
+}
+
+export interface ReceiptResult extends CommandResult {
+  /** True when the playbook was skipped on an unchanged, verified receipt. */
+  cached: boolean;
+}
+
+export function receiptDirectory(home = homedir()): string {
+  return join(home, '.local/state/personal/fleet/receipts');
+}
+
+/** Ansible is idempotent but slow (fact gathering, package and service
+ * inspection). A successful apply records a digest of its exact inputs
+ * (playbook sources and variables, never the variables themselves). A later
+ * run with the same digest skips the playbook while the cheap postcondition
+ * still holds; any input change, failed probe, failed apply or a receipt
+ * older than a day applies in full again.
+ */
+export async function runAnsibleWithReceipt(
+  run: Runner,
+  playbook: string,
+  options: CommandOptions & { input: string },
+  receipt: Receipt
+): Promise<ReceiptResult> {
+  const directory = receipt.directory ?? receiptDirectory();
+  const path = join(directory, `${receipt.name}.json`);
+  const now = receipt.now ?? Date.now();
+  const key = await inputKey(playbook, options.input, receipt.sources);
+  if (
+    !receipt.force &&
+    key !== null &&
+    (await fresh(path, key, now)) &&
+    (await receipt.verify().catch(() => false))
+  )
+    return { ok: true, reason: 'exit', stdout: '', stderr: '', cached: true };
+  await rm(path, { force: true }).catch(() => undefined);
+  const result = await runAnsible(run, playbook, options);
+  if (result.ok && key !== null)
+    await record(directory, path, { version: 1, key, appliedAt: now });
+  return { ...result, cached: false };
+}
+
+/** Best effort: a missing receipt only means the next run applies in full. */
+async function record(directory: string, path: string, value: object) {
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(path, JSON.stringify(value) + '\n', { mode: 0o600 });
+  } catch {
+    /* Never fail a successful apply over its receipt. */
+  }
+}
+
+async function fresh(path: string, key: string, now: number) {
+  try {
+    const value = JSON.parse(await readFile(path, 'utf8')) as {
+      version?: unknown;
+      key?: unknown;
+      appliedAt?: unknown;
+    };
+    return (
+      value.version === 1 &&
+      value.key === key &&
+      typeof value.appliedAt === 'number' &&
+      now - value.appliedAt >= 0 &&
+      now - value.appliedAt < RECEIPT_MAX_AGE_MS
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Null when any source is unreadable: then the playbook always runs. */
+export async function inputKey(
+  playbook: string,
+  input: string,
+  sources: string[]
+): Promise<string | null> {
+  const hash = createHash('sha256');
+  hash.update(`playbook\0${playbook}\0input\0${input}\0`);
+  try {
+    for (const source of [...sources].sort())
+      for (const file of await files(source)) {
+        hash.update(`${relative(source, file)}\0`);
+        hash.update(await readFile(file));
+        hash.update('\0');
+      }
+  } catch {
+    return null;
+  }
+  return hash.digest('hex');
+}
+
+async function files(source: string): Promise<string[]> {
+  const entries = await readdir(source, {
+    recursive: true,
+    withFileTypes: true,
+  }).catch((error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOTDIR') return null;
+    throw error;
+  });
+  if (entries === null) return [source];
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => join(entry.parentPath, entry.name))
+    .sort();
+}

package/src/platform/ansible.ts

@@ -0,0 +1,66 @@
+import { mkdir, mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { PACKAGE_ROOT } from '../package-info';
+import type { Runner, CommandOptions, CommandResult } from '../types';
+
+/** The Ansible each machine runs playbooks with, pinned either way. A worker
+ * has the exact `ansible-core` package the Ubuntu policy names. The manager
+ * runs the project in `ansible/` (`pyproject.toml`, `uv.lock`): one release on
+ * one Python, every dependency checked against its locked hash, in a
+ * throwaway environment. No global Python environment is modified, nothing is
+ * written into the checkout, and an `ansible-playbook` that happens to be on
+ * PATH is never used.
+ */
+export function ansibleCommand(
+  platform: NodeJS.Platform = process.platform,
+  root = PACKAGE_ROOT
+): string[] {
+  return platform === 'linux'
+    ? ['ansible-playbook']
+    : [
+        'uv',
+        'run',
+        '--project',
+        join(root, 'ansible'),
+        '--locked',
+        '--isolated',
+        '--quiet',
+        'ansible-playbook',
+      ];
+}
+
+/** Private fleet state on disk, never /tmp: a worker's /tmp is RAM-backed with a
+ * per-user quota that agent caches can exhaust, and the baseline that bounds it
+ * must still be able to run then.
+ */
+export function variablesDirectory(home = homedir()): string {
+  return join(home, '.local/state/personal/fleet/run');
+}
+
+/** Ansible resolves @file paths before opening them; @/dev/stdin is not portable
+ * across versions when stdin is a pipe. Keep runtime variables in a private,
+ * short-lived directory instead. Never put their values in argv or logs.
+ */
+export async function runAnsible(
+  run: Runner,
+  playbook: string,
+  options: CommandOptions & { input: string },
+  scratch = variablesDirectory()
+): Promise<CommandResult> {
+  if (Buffer.byteLength(options.input) > 256 * 1024)
+    throw new Error('ANSIBLE_VARIABLE_LIMIT');
+  await mkdir(scratch, { recursive: true, mode: 0o700 });
+  const directory = await mkdtemp(join(scratch, 'personal-ansible-'));
+  const path = join(directory, 'variables.json');
+  try {
+    await writeFile(path, options.input, { mode: 0o600, flag: 'wx' });
+    const { input: _input, ...commandOptions } = options;
+    return await run(
+      [...ansibleCommand(), playbook, '--extra-vars', '@' + path],
+      commandOptions
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}

package/src/platform/darwin.ts

@@ -0,0 +1,203 @@
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  NotificationKind,
+  NotifierCapability,
+  NotifierTestResult,
+  Platform,
+  ProcessInfo,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+import {
+  installLaunchdJob,
+  launchdJobStatus,
+  removeLaunchdJob,
+} from './launchd';
+import { psProcesses } from './ps';
+
+function appleScriptString(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`;
+}
+
+export class DarwinPlatform implements Platform {
+  readonly dockerSetupScript = 'bootstrap/docker-desktop.sh';
+  readonly name = 'darwin' as const;
+  readonly label = 'macOS';
+
+  opencodeDir(): string {
+    return join(homedir(), '.config/opencode');
+  }
+
+  cacheDir(): string {
+    return join(homedir(), '.cache');
+  }
+
+  globalBinDir(): string {
+    return join(homedir(), '.local/bin');
+  }
+
+  canBuildSwiftNotifier(): boolean {
+    return (
+      spawnSync('/usr/bin/which', ['swiftc'], { stdio: 'ignore' }).status === 0
+    );
+  }
+
+  shellRcFiles(): readonly string[] {
+    const home = homedir();
+    return [
+      join(home, '.zshrc'),
+      join(home, '.bashrc'),
+      join(home, '.bash_profile'),
+      join(home, '.config/fish/config.fish'),
+    ];
+  }
+
+  notifierCapabilities(): NotifierCapability {
+    return { native: true, sounds: true, clickToFocus: true };
+  }
+
+  async postNotification(input: {
+    title: string;
+    message: string;
+    kind: NotificationKind;
+  }): Promise<NotifierTestResult> {
+    const cli = join(this.opencodeDir(), 'bin/opencode-notifier');
+    try {
+      const { existsSync } = await import('node:fs');
+      if (existsSync(cli)) {
+        const body = JSON.stringify({
+          kind: input.kind,
+          title: input.title,
+          message: input.message,
+          subtitle: 'dev-fleet test',
+          sessionID: 'ses_ws_test',
+          directory: process.cwd(),
+          sessionTitle: 'dev-fleet test',
+          token: '',
+        });
+        const r = spawnSync(cli, ['--post', body], { encoding: 'utf8' });
+        if (r.status === 0) {
+          return { ok: true, detail: 'posted via OpenCodeNotifier daemon' };
+        }
+      }
+    } catch {
+      // Fall through to osascript.
+    }
+    try {
+      const script = `display notification ${appleScriptString(input.message)} with title ${appleScriptString(input.title)}`;
+      execSync(`osascript -e ${JSON.stringify(script)}`, { stdio: 'ignore' });
+      return { ok: true, detail: 'posted via osascript fallback' };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, detail: `osascript failed: ${msg}` };
+    }
+  }
+
+  isNotifierDaemonRunning(): boolean {
+    try {
+      const out = execSync('pgrep -fl "OpenCodeNotifier.*daemon"', {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      return out.trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  restartNotifierDaemon(): void {
+    spawnSync('pkill', ['-f', 'OpenCodeNotifier.*--daemon'], {
+      stdio: 'ignore',
+    });
+  }
+
+  availableSystemSounds(): string[] {
+    const dirs = [
+      '/System/Library/Sounds',
+      '/Library/Sounds',
+      join(homedir(), 'Library/Sounds'),
+    ];
+    const names = new Set<string>();
+    for (const dir of dirs) {
+      let entries: string[] = [];
+      try {
+        entries = readdirSync(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const m = entry.match(/^(.*)\.(aiff?|wav|mp3|m4a|caf)$/i);
+        if (m?.[1]) names.add(m[1]);
+      }
+    }
+    return [...names].sort((a, b) => a.localeCompare(b));
+  }
+
+  async playSystemSound(name: string): Promise<NotifierTestResult> {
+    const trimmed = name.trim();
+    if (trimmed.length === 0) {
+      return { ok: false, detail: 'empty sound name' };
+    }
+    const dirs = [
+      '/System/Library/Sounds',
+      '/Library/Sounds',
+      join(homedir(), 'Library/Sounds'),
+    ];
+    const exts = ['aiff', 'aif', 'wav', 'mp3', 'm4a', 'caf'];
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        const candidate = join(dir, `${trimmed}.${ext}`);
+        if (existsSync(candidate)) {
+          const r = spawnSync('afplay', [candidate], { stdio: 'ignore' });
+          if (r.status === 0) {
+            return { ok: true, detail: `played ${trimmed} via afplay` };
+          }
+          return { ok: false, detail: `afplay failed for ${trimmed}` };
+        }
+      }
+    }
+    return {
+      ok: false,
+      detail: `unknown sound "${trimmed}" (see \`devfleet workstation opencode notifications sounds list\`)`,
+    };
+  }
+
+  listProcesses(): ProcessInfo[] | null {
+    return psProcesses();
+  }
+
+  tailscaleAppBinaries(): readonly string[] {
+    return ['/Applications/Tailscale.app/Contents/MacOS/Tailscale'].filter(
+      (p) => existsSync(p)
+    );
+  }
+
+  vscodeSettingsPath(): string | null {
+    return join(
+      homedir(),
+      'Library/Application Support/Code/User/settings.json'
+    );
+  }
+
+  vscodeCliBinaries(): readonly string[] {
+    return [
+      '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+    ].filter((p) => existsSync(p));
+  }
+
+  installScheduledJob(job: ScheduledJob): NotifierTestResult {
+    return installLaunchdJob(job);
+  }
+
+  removeScheduledJob(label: string): NotifierTestResult {
+    return removeLaunchdJob(label);
+  }
+
+  scheduledJobStatus(label: string): ScheduledJobStatus {
+    return launchdJobStatus(label);
+  }
+}

package/src/platform/detect.ts

@@ -0,0 +1,11 @@
+import type { PlatformName } from './types';
+
+/** Map `process.platform` onto the dev-fleet platform names. Pure — unit-tested. */
+export function detectPlatformName(
+  platform: NodeJS.Platform = process.platform
+): PlatformName {
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'linux') return 'linux';
+  if (platform === 'win32') return 'windows';
+  return 'unknown';
+}

package/src/platform/fallback.ts

@@ -0,0 +1,110 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  NotificationKind,
+  NotifierCapability,
+  NotifierTestResult,
+  Platform,
+  ProcessInfo,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+
+/** Safe default for unrecognized platforms — filesystem converges, notify degrades. */
+export class FallbackPlatform implements Platform {
+  readonly name = 'unknown' as const;
+  readonly label = 'Unknown';
+
+  opencodeDir(): string {
+    return join(homedir(), '.config/opencode');
+  }
+
+  cacheDir(): string {
+    return join(homedir(), '.cache');
+  }
+
+  globalBinDir(): string {
+    return join(homedir(), '.local/bin');
+  }
+
+  canBuildSwiftNotifier(): boolean {
+    return false;
+  }
+
+  shellRcFiles(): readonly string[] {
+    return [join(homedir(), '.profile')];
+  }
+
+  notifierCapabilities(): NotifierCapability {
+    return {
+      native: false,
+      sounds: false,
+      clickToFocus: false,
+      reason: 'unrecognized platform — notifications disabled',
+    };
+  }
+
+  async postNotification(_input: {
+    title: string;
+    message: string;
+    kind: NotificationKind;
+  }): Promise<NotifierTestResult> {
+    return { ok: false, detail: 'notifications unsupported on this platform' };
+  }
+
+  isNotifierDaemonRunning(): boolean {
+    return false;
+  }
+
+  restartNotifierDaemon(): void {
+    // No-op.
+  }
+
+  availableSystemSounds(): string[] {
+    return [];
+  }
+
+  async playSystemSound(name: string): Promise<NotifierTestResult> {
+    void name;
+    return { ok: false, detail: 'sounds unsupported on this platform' };
+  }
+
+  listProcesses(): ProcessInfo[] | null {
+    return null;
+  }
+
+  tailscaleAppBinaries(): readonly string[] {
+    return [];
+  }
+
+  vscodeSettingsPath(): string | null {
+    return null;
+  }
+
+  vscodeCliBinaries(): readonly string[] {
+    return [];
+  }
+
+  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/platform/index.ts

@@ -0,0 +1,38 @@
+import { DarwinPlatform } from './darwin';
+import { detectPlatformName } from './detect';
+import { FallbackPlatform } from './fallback';
+import { LinuxPlatform } from './linux';
+import { WindowsPlatform } from './windows';
+import type { Platform, PlatformName } from './types';
+
+export type { Platform, PlatformName } from './types';
+export type {
+  NotificationKind,
+  NotifierCapability,
+  NotifierTestResult,
+  GlobalInstallResult,
+} from './types';
+export { detectPlatformName } from './detect';
+
+/** Polymorphic factory — callers never branch on `process.platform` directly. */
+export function getPlatform(name?: PlatformName): Platform {
+  const resolved = name ?? detectPlatformName();
+  switch (resolved) {
+    case 'darwin':
+      return new DarwinPlatform();
+    case 'linux':
+      return new LinuxPlatform();
+    case 'windows':
+      return new WindowsPlatform();
+    case 'unknown':
+      return new FallbackPlatform();
+  }
+}
+
+let cached: Platform | null = null;
+
+/** Memoized current-platform adapter. */
+export function currentPlatform(): Platform {
+  if (cached === null) cached = getPlatform();
+  return cached;
+}

package/src/platform/launchd.ts

@@ -0,0 +1,98 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+
+import type {
+  NotifierTestResult,
+  ScheduledJob,
+  ScheduledJobStatus,
+} from './types';
+
+function xml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function launchAgentPath(label: string, home = homedir()): string {
+  return join(home, 'Library/LaunchAgents', `${label}.plist`);
+}
+
+/** launchd agent plist for a periodic job. Pure — unit-tested. */
+export function launchdPlist(job: ScheduledJob): string {
+  const args = job.command.map((a) => `    <string>${xml(a)}</string>`);
+  const env = Object.entries(job.env).map(
+    ([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`
+  );
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0"><dict>',
+    `  <key>Label</key><string>${xml(job.label)}</string>`,
+    '  <key>ProgramArguments</key><array>',
+    ...args,
+    '  </array>',
+    '  <key>EnvironmentVariables</key><dict>',
+    ...env,
+    '  </dict>',
+    `  <key>StartInterval</key><integer>${job.intervalSeconds}</integer>`,
+    '  <key>RunAtLoad</key><true/>',
+    '  <key>LowPriorityIO</key><true/>',
+    '  <key>Nice</key><integer>10</integer>',
+    `  <key>StandardOutPath</key><string>${xml(join(job.logDir, `${job.label}.out.log`))}</string>`,
+    `  <key>StandardErrorPath</key><string>${xml(join(job.logDir, `${job.label}.err.log`))}</string>`,
+    '</dict></plist>',
+    '',
+  ].join('\n');
+}
+
+function domain(): string {
+  return `gui/${userInfo().uid}`;
+}
+
+export function installLaunchdJob(job: ScheduledJob): NotifierTestResult {
+  const plist = launchAgentPath(job.label);
+  mkdirSync(join(homedir(), 'Library/LaunchAgents'), { recursive: true });
+  mkdirSync(job.logDir, { recursive: true });
+  writeFileSync(plist, launchdPlist(job));
+  spawnSync('launchctl', ['bootout', `${domain()}/${job.label}`], {
+    stdio: 'ignore',
+  });
+  const r = spawnSync('launchctl', ['bootstrap', domain(), plist], {
+    encoding: 'utf8',
+  });
+  return r.status === 0
+    ? { ok: true, detail: `launchd agent ${plist}` }
+    : { ok: false, detail: `launchctl bootstrap failed: ${r.stderr.trim()}` };
+}
+
+export function removeLaunchdJob(label: string): NotifierTestResult {
+  spawnSync('launchctl', ['bootout', `${domain()}/${label}`], {
+    stdio: 'ignore',
+  });
+  rmSync(launchAgentPath(label), { force: true });
+  return { ok: true, detail: `removed launchd agent ${label}` };
+}
+
+export function launchdJobStatus(label: string): ScheduledJobStatus {
+  const r = spawnSync('launchctl', ['print', `${domain()}/${label}`], {
+    encoding: 'utf8',
+  });
+  if (r.status !== 0) {
+    const present = existsSync(launchAgentPath(label));
+    return {
+      supported: true,
+      installed: false,
+      detail: present ? 'plist present but not loaded' : 'not installed',
+    };
+  }
+  const lastExit =
+    /last exit code = (.+)/.exec(r.stdout)?.[1]?.trim() ?? 'unknown';
+  return {
+    supported: true,
+    installed: true,
+    detail: `loaded; last exit code ${lastExit}`,
+  };
+}