@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,186 @@
+import { readFile } from 'node:fs/promises';
+import type { Capability, FleetConfig, FleetNode } from './types';
+import { FleetUsageError } from './errors';
+
+export const CAPABILITIES: Capability[] = [
+  'github',
+  'vault',
+  't3',
+  'vscode',
+  'toolchain',
+  'codex',
+  'claude',
+  'services',
+  'workstation',
+  'worker',
+];
+export const DEFAULT_CONFIG = '.fleet.local.json';
+
+export function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fields(value: Record<string, unknown>, allowed: string[]): void {
+  if (Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new FleetUsageError(
+      'Unknown configuration field. Run fleet-nodes --schema.'
+    );
+  }
+}
+
+function absolutePath(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.startsWith('/') &&
+    value.length <= 4096 &&
+    !/[\x00-\x1f\x7f]/.test(value)
+  );
+}
+
+function parseNode(value: unknown): FleetNode {
+  if (!record(value)) throw new FleetUsageError('Each node must be an object.');
+  fields(value, [
+    'id',
+    'ssh',
+    'workspace',
+    'runtime',
+    'required',
+    'tailscaleId',
+    't3EnvironmentId',
+    'bootstrapViaSsh',
+  ]);
+  if (
+    value['t3EnvironmentId'] !== undefined &&
+    (typeof value['t3EnvironmentId'] !== 'string' ||
+      !/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(
+        value['t3EnvironmentId']
+      ))
+  )
+    throw new FleetUsageError('Invalid enrolled T3 environment identity.');
+  const names = nodeNames(value);
+  if (!absolutePath(value['workspace']))
+    throw new FleetUsageError('workspace must be an absolute POSIX path.');
+  if (value['runtime'] !== undefined && !absolutePath(value['runtime'])) {
+    throw new FleetUsageError(
+      'runtime must be an absolute POSIX path to Node or Bun.'
+    );
+  }
+  return {
+    ...names,
+    ...enrollmentOptions(value),
+    ...(typeof value['t3EnvironmentId'] === 'string'
+      ? { t3EnvironmentId: value['t3EnvironmentId'] }
+      : {}),
+    workspace: value['workspace'],
+    ...(typeof value['runtime'] === 'string'
+      ? { runtime: value['runtime'] }
+      : {}),
+    required: requiredCapabilities(value['required']),
+  };
+}
+
+function enrollmentOptions(
+  value: Record<string, unknown>
+): Pick<FleetNode, 'tailscaleId' | 'bootstrapViaSsh'> {
+  if (
+    value['bootstrapViaSsh'] !== undefined &&
+    typeof value['bootstrapViaSsh'] !== 'boolean'
+  )
+    throw new FleetUsageError(
+      'bootstrapViaSsh must explicitly authorize an existing trusted SSH bootstrap route.'
+    );
+  if (
+    value['tailscaleId'] !== undefined &&
+    (typeof value['tailscaleId'] !== 'string' ||
+      !/^[a-zA-Z0-9:_-]{1,128}$/.test(value['tailscaleId']))
+  )
+    throw new FleetUsageError(
+      'tailscaleId must be the explicitly enrolled stable Tailscale device ID.'
+    );
+  return {
+    ...(value['bootstrapViaSsh'] === true ? { bootstrapViaSsh: true } : {}),
+    ...(typeof value['tailscaleId'] === 'string'
+      ? { tailscaleId: value['tailscaleId'] }
+      : {}),
+  };
+}
+
+function nodeNames(
+  value: Record<string, unknown>
+): Pick<FleetNode, 'id' | 'ssh'> {
+  if (
+    typeof value['id'] !== 'string' ||
+    !/^[a-z][a-z0-9-]{0,62}$/.test(value['id'])
+  ) {
+    throw new FleetUsageError(
+      'Node IDs must be lowercase names (1–63 characters).'
+    );
+  }
+  if (
+    typeof value['ssh'] !== 'string' ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$/.test(value['ssh'])
+  ) {
+    throw new FleetUsageError(
+      'ssh must be a plain SSH alias or hostname, not options or user@host.'
+    );
+  }
+  return { id: value['id'], ssh: value['ssh'] };
+}
+
+function requiredCapabilities(value: unknown): Capability[] {
+  const required =
+    value === undefined ? ['github', 'vault', 't3', 'toolchain'] : value;
+  if (
+    !Array.isArray(required) ||
+    required.some((item) => !CAPABILITIES.includes(item as Capability))
+  ) {
+    throw new FleetUsageError(
+      'required must contain only capability names from fleet-nodes --schema.'
+    );
+  }
+  if (new Set(required).size !== required.length)
+    throw new FleetUsageError('required capabilities must be unique.');
+  return required as Capability[];
+}
+
+export function parseConfig(value: unknown): FleetConfig {
+  if (!record(value))
+    throw new FleetUsageError('Fleet configuration must be an object.');
+  fields(value, ['$schema', 'version', 'nodes']);
+  if (value['$schema'] !== undefined && typeof value['$schema'] !== 'string')
+    throw new FleetUsageError('$schema must be a string.');
+  if (value['version'] !== 1 || !Array.isArray(value['nodes'])) {
+    throw new FleetUsageError('Expected version 1 and a nodes array.');
+  }
+  if (value['nodes'].length < 1 || value['nodes'].length > 64) {
+    throw new FleetUsageError('Configure between 1 and 64 developer nodes.');
+  }
+  const nodes = value['nodes'].map(parseNode);
+  if (new Set(nodes.map((node) => node.id)).size !== nodes.length) {
+    throw new FleetUsageError('Node IDs must be unique.');
+  }
+  return { version: 1, nodes };
+}
+
+export async function loadConfig(path: string): Promise<FleetConfig> {
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    throw new FleetUsageError(
+      'Cannot read fleet config. Run devfleet fleet-node-add or use --config PATH.'
+    );
+  }
+  return parseConfig(value);
+}
+
+export function selectNodes(config: FleetConfig, ids: string[]): FleetNode[] {
+  if (ids.some((id) => !config.nodes.some((node) => node.id === id))) {
+    throw new FleetUsageError(
+      'Unknown node selection. Run fleet-nodes --json.'
+    );
+  }
+  return ids.length === 0
+    ? config.nodes
+    : config.nodes.filter((node) => ids.includes(node.id));
+}

package/src/configure.ts

@@ -0,0 +1,255 @@
+import { join } from 'node:path';
+import { mkdir, writeFile, rename, readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { record } from './config';
+import type { Check, Runner } from './types';
+
+export type ConfigurationRequest = {
+  revision: string;
+  tool: string;
+  profile: string;
+  node: string;
+};
+
+export function validConfiguration(
+  value: unknown
+): value is ConfigurationRequest {
+  return (
+    record(value) &&
+    typeof value['revision'] === 'string' &&
+    /^[a-f0-9]{40}$/.test(value['revision']) &&
+    ['codex', 'claude', 'opencode', 'gemini', 'grok', 'antigravity'].includes(
+      String(value['tool'])
+    ) &&
+    ['direct', 'proxy'].includes(String(value['profile'])) &&
+    typeof value['node'] === 'string' &&
+    /^[a-z0-9][a-z0-9-]{0,62}$/.test(value['node'])
+  );
+}
+
+/** A pinned deployment worktree leaves the developer's branch and dirty files intact. */
+export async function configureWorkspace(
+  root: string,
+  request: ConfigurationRequest,
+  run: Runner,
+  options: { additionalTools: string[]; bootstrappedDeployment: boolean } = {
+    additionalTools: [],
+    bootstrappedDeployment: false,
+  }
+): Promise<Check[]> {
+  if (
+    options.additionalTools.some(
+      (tool) => !validConfiguration({ ...request, tool })
+    )
+  )
+    return failure('Invalid additional profile.');
+  if (!validConfiguration(request))
+    return failure('Invalid reviewed revision or configuration selection.');
+  const directory = deploymentDirectory(
+    root,
+    request.revision,
+    options.bootstrappedDeployment
+  );
+  const head = await run(
+    ['git', 'rev-parse', '--verify', `${request.revision}^{commit}`],
+    { cwd: root }
+  );
+  if (!head.ok || head.stdout.trim() !== request.revision)
+    return failure(
+      'Reviewed commit is unavailable locally. Fetch it explicitly and retry.'
+    );
+  const prepared = await prepareRevision(
+    root,
+    directory,
+    request.revision,
+    run
+  );
+  if (prepared.length) return prepared;
+  if (!options.bootstrappedDeployment) {
+    const setup = await setupRevision(directory, run);
+    if (setup.length) return setup;
+  }
+  const checks: Check[] = [];
+  for (const tool of [request.tool, ...options.additionalTools]) {
+    checks.push(
+      ...(await applyProfile(root, directory, { ...request, tool }, run))
+    );
+  }
+  return checks;
+}
+async function setupRevision(directory: string, run: Runner): Promise<Check[]> {
+  const setup = await run(
+    [
+      'mise',
+      'exec',
+      '--locked',
+      'bun',
+      '--',
+      'bun',
+      'bootstrap/setup.ts',
+      '--non-interactive',
+    ],
+    { cwd: directory, timeoutMs: 1_200_000 }
+  );
+  if (!setup.ok)
+    return failure(
+      'Existing setup owner failed. Partial tool/dependency installation is possible; no configuration receipt was advanced.'
+    );
+  return [];
+}
+
+async function applyProfile(
+  root: string,
+  directory: string,
+  request: ConfigurationRequest,
+  run: Runner
+): Promise<Check[]> {
+  const applied = await applyOwner(directory, request, run);
+  if (!applied.ok)
+    return failure(
+      'Agent profile configuration failed. Inspect preview on this node; no rollout receipt was advanced.'
+    );
+  const receipt = decodeReceipt(applied.stdout, request.revision);
+  if (!receipt)
+    return failure(
+      'The agent profile owner returned an invalid receipt; rollout remains unverified.'
+    );
+  await recordConfiguration(root, request, receipt);
+  return [
+    {
+      id: 'configuration:apply',
+      status: 'pass',
+      summary: `agent profile applied at revision ${request.revision}; configuration fingerprint ${receipt}. Authentication and T3 end-to-end remain separate gates.`,
+    },
+  ];
+}
+
+export function decodeReceipt(output: string, revision: string): string | null {
+  try {
+    const data: unknown = JSON.parse(output);
+    return record(data) &&
+      data['ok'] === true &&
+      data['revision'] === revision &&
+      typeof data['fingerprint'] === 'string' &&
+      /^[a-f0-9]{64}$/.test(data['fingerprint'])
+      ? data['fingerprint']
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(summary: string): Check[] {
+  return [{ id: 'configuration:apply', status: 'fail', summary }];
+}
+
+async function prepareRevision(
+  root: string,
+  directory: string,
+  revision: string,
+  run: Runner
+): Promise<Check[]> {
+  if (root === directory) return verifyRevision(directory, revision, run);
+  await mkdir(join(root, 'node_modules', '.fleet-revisions'), {
+    recursive: true,
+  });
+  let deployed = await run(['git', 'rev-parse', 'HEAD'], { cwd: directory });
+  if (!deployed.ok) {
+    const created = await run(
+      ['git', 'worktree', 'add', '--detach', directory, revision],
+      { cwd: root, timeoutMs: 30_000 }
+    );
+    if (!created.ok)
+      return failure(
+        'Cannot create pinned deployment worktree. Existing data was preserved.'
+      );
+    deployed = await run(['git', 'rev-parse', 'HEAD'], { cwd: directory });
+  }
+  return verifyRevision(directory, revision, run);
+}
+async function verifyRevision(
+  directory: string,
+  revision: string,
+  run: Runner
+): Promise<Check[]> {
+  const deployed = await run(['git', 'rev-parse', 'HEAD'], { cwd: directory });
+  const clean = await run(['git', 'status', '--porcelain'], { cwd: directory });
+  if (
+    !deployed.ok ||
+    deployed.stdout.trim() !== revision ||
+    !clean.ok ||
+    clean.stdout.trim()
+  )
+    return failure(
+      'Pinned deployment checkout differs or is dirty. Inspect it; fleet never resets it.'
+    );
+  const top = await run(['git', 'rev-parse', '--show-toplevel'], {
+    cwd: directory,
+  });
+  if (!top.ok || top.stdout.trim() !== directory)
+    return failure('Deployment path is not its own Git worktree.');
+  return [];
+}
+
+async function recordConfiguration(
+  root: string,
+  request: ConfigurationRequest,
+  receipt: string
+): Promise<void> {
+  const receipts = join(root, 'node_modules', '.fleet-configuration');
+  await mkdir(receipts, { recursive: true, mode: 0o700 });
+  const path = join(
+    receipts,
+    `${request.node}-${request.tool}-${request.profile}.json`
+  );
+  const contents =
+    JSON.stringify({ version: 1, ...request, fingerprint: receipt }) + '\n';
+  try {
+    if ((await readFile(path, 'utf8')) === contents) return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temp, contents, { flag: 'wx', mode: 0o600 });
+  await rename(temp, path);
+}
+
+async function applyOwner(
+  directory: string,
+  request: ConfigurationRequest,
+  run: Runner
+) {
+  return run(
+    [
+      'mise',
+      'exec',
+      '--locked',
+      'bun',
+      '--',
+      'bun',
+      'src/agents/cli.ts',
+      '--json',
+      '--yes',
+      '--non-interactive',
+      'agents',
+      'apply',
+      '--node',
+      request.node,
+      '--tool',
+      request.tool,
+      '--profile',
+      request.profile,
+    ],
+    { cwd: directory, timeoutMs: 120_000 }
+  );
+}
+
+function deploymentDirectory(
+  root: string,
+  revision: string,
+  bootstrapped: boolean
+): string {
+  return bootstrapped
+    ? root
+    : join(root, 'node_modules', '.fleet-revisions', revision);
+}

package/src/definition.ts

@@ -0,0 +1,260 @@
+import { parseWorkerPolicy, type WorkerPolicy } from './worker-policy';
+import { readFileSync } from 'node:fs';
+import { FleetUsageError } from './errors';
+import { parseConfig, record } from './config';
+import type { FleetConfig } from './types';
+import { parseSecretsConfig, type SecretsConfig } from './secrets';
+
+export interface MachineDefinition {
+  id: string;
+  ssh: string;
+  os: 'linux' | 'macOS' | 'windows';
+  network?: {
+    tailscaleName: string;
+    user: string;
+    sshPort: number;
+    t3Port: number;
+  };
+}
+/** The singleton manager: the human's machine. It runs fleet-sync and hosts
+ * every singleton service; it is never converged over SSH. */
+export interface ManagerDefinition {
+  id: string;
+  os: 'macOS';
+  network: { tailscaleName: string; user: string };
+  neverSleepOnPower: true;
+}
+export interface FleetDefinition {
+  version: 3;
+  /** The Git repository that holds this fleet's configuration and pins. */
+  source: { repository: string };
+  /** Where this fleet keeps its secrets. */
+  secrets: SecretsConfig;
+  manager: ManagerDefinition;
+  /** Stateless, replaceable Linux boxes; clients of the manager's services. */
+  workers: MachineDefinition[];
+  services: {
+    /** Public HTTPS origin of the CLI proxy every node uses. */
+    proxy: { endpoint: string };
+    monitoring: {
+      hubPort: 8443;
+      /** Public dashboard origin. */
+      publicUrl: string;
+      /** Beszel account the manager enrolls nodes with. */
+      managerAccount: string;
+      /** Read-only Beszel account visitors are signed in as. */
+      viewerAccount: string;
+    };
+  };
+  worker?: WorkerPolicy;
+  ubuntu: { release: '26.04'; architectures: ['amd64', 'arm64'] };
+}
+const ID = /^[a-z][a-z0-9-]{0,62}$/;
+const HOST = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$/;
+function fail(): never {
+  throw new FleetUsageError(
+    'Invalid Fleet definition. Check version 3, one macOS manager, unique Linux worker IDs, singleton services and network metadata in fleet.json.'
+  );
+}
+function keys(value: Record<string, unknown>, allowed: string[]): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+function network(value: unknown): NonNullable<MachineDefinition['network']> {
+  if (
+    !record(value) ||
+    !keys(value, ['tailscaleName', 'user', 'sshPort', 't3Port'])
+  )
+    return fail();
+  if (
+    typeof value['tailscaleName'] !== 'string' ||
+    !HOST.test(value['tailscaleName'])
+  )
+    return fail();
+  if (
+    typeof value['user'] !== 'string' ||
+    !/^[a-z_][a-z0-9_-]{0,31}$/.test(value['user'])
+  )
+    return fail();
+  for (const port of ['sshPort', 't3Port'])
+    if (!validPort(value[port])) return fail();
+  return value as NonNullable<MachineDefinition['network']>;
+}
+function validPort(value: unknown): boolean {
+  return (
+    Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 65535
+  );
+}
+function worker(value: unknown): MachineDefinition {
+  if (!record(value) || !keys(value, ['id', 'ssh', 'os', 'network']))
+    return fail();
+  if (typeof value['id'] !== 'string' || !ID.test(value['id'])) return fail();
+  if (typeof value['ssh'] !== 'string' || !HOST.test(value['ssh']))
+    return fail();
+  // Workers are the Linux boxes; any other platform is not a worker.
+  if (value['os'] !== 'linux') return fail();
+  return {
+    id: value['id'],
+    ssh: value['ssh'],
+    os: 'linux',
+    ...(value['network'] ? { network: network(value['network']) } : {}),
+  };
+}
+function manager(value: unknown): ManagerDefinition {
+  if (
+    !record(value) ||
+    !keys(value, ['id', 'os', 'network', 'neverSleepOnPower']) ||
+    typeof value['id'] !== 'string' ||
+    !ID.test(value['id']) ||
+    value['os'] !== 'macOS' ||
+    value['neverSleepOnPower'] !== true
+  )
+    return fail();
+  return {
+    id: value['id'],
+    os: 'macOS',
+    network: managerNetwork(value['network']),
+    neverSleepOnPower: true,
+  };
+}
+function managerNetwork(value: unknown): ManagerDefinition['network'] {
+  if (
+    !record(value) ||
+    !keys(value, ['tailscaleName', 'user']) ||
+    typeof value['tailscaleName'] !== 'string' ||
+    !HOST.test(value['tailscaleName']) ||
+    typeof value['user'] !== 'string' ||
+    !/^[a-z_][a-z0-9_.-]{0,31}$/.test(value['user'])
+  )
+    return fail();
+  return { tailscaleName: value['tailscaleName'], user: value['user'] };
+}
+export function parseDefinition(value: unknown): FleetDefinition {
+  if (
+    !record(value) ||
+    value['version'] !== 3 ||
+    !keys(value, [
+      '$schema',
+      'version',
+      'source',
+      'secrets',
+      'manager',
+      'workers',
+      'services',
+      'ubuntu',
+      'worker',
+    ])
+  )
+    return fail();
+  if (!Array.isArray(value['workers']) || value['workers'].length > 64)
+    return fail();
+  const lead = manager(value['manager']);
+  const workers = value['workers'].map(worker);
+  const ids = [lead.id, ...workers.map((entry) => entry.id)];
+  if (new Set(ids).size !== ids.length) return fail();
+  return {
+    version: 3,
+    source: source(value['source']),
+    secrets: secrets(value['secrets']),
+    manager: lead,
+    workers,
+    services: services(value['services']),
+    ubuntu: baseline(value['ubuntu']),
+    ...(value['worker'] === undefined
+      ? {}
+      : { worker: parseWorkerPolicy(value['worker']) }),
+  };
+}
+/** Singleton services name no host: they always run on the manager. */
+function services(value: unknown): FleetDefinition['services'] {
+  if (!record(value) || !keys(value, ['proxy', 'monitoring'])) return fail();
+  const { proxy, monitoring } = value;
+  if (
+    !record(proxy) ||
+    !keys(proxy, ['endpoint']) ||
+    !origin(proxy['endpoint'])
+  )
+    return fail();
+  return {
+    proxy: { endpoint: proxy['endpoint'] },
+    monitoring: monitoringService(monitoring),
+  };
+}
+function monitoringService(
+  value: unknown
+): FleetDefinition['services']['monitoring'] {
+  const fields = ['hubPort', 'publicUrl', 'managerAccount', 'viewerAccount'];
+  if (!record(value) || !keys(value, fields) || value['hubPort'] !== 8443)
+    return fail();
+  const { publicUrl, managerAccount, viewerAccount } = value;
+  if (!origin(publicUrl) || !account(managerAccount) || !account(viewerAccount))
+    return fail();
+  return { hubPort: 8443, publicUrl, managerAccount, viewerAccount };
+}
+const origin = (value: unknown): value is string =>
+  typeof value === 'string' && /^https:\/\/[A-Za-z0-9.-]{1,253}$/.test(value);
+const account = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  /^[^\s@]{1,64}@[A-Za-z0-9.-]{1,253}$/.test(value);
+function secrets(value: unknown): SecretsConfig {
+  return parseSecretsConfig(value) ?? fail();
+}
+function source(value: unknown): FleetDefinition['source'] {
+  if (
+    !record(value) ||
+    !keys(value, ['repository']) ||
+    typeof value['repository'] !== 'string' ||
+    !/^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._/-]+\.git$/.test(
+      value['repository']
+    )
+  )
+    return fail();
+  return { repository: value['repository'] };
+}
+function baseline(ubuntu: unknown): FleetDefinition['ubuntu'] {
+  if (
+    !record(ubuntu) ||
+    !keys(ubuntu, ['release', 'architectures']) ||
+    ubuntu['release'] !== '26.04' ||
+    JSON.stringify(ubuntu['architectures']) !== '["amd64","arm64"]'
+  )
+    return fail();
+  return ubuntu as FleetDefinition['ubuntu'];
+}
+
+export function loadDefinition(path: string): FleetDefinition {
+  try {
+    return parseDefinition(JSON.parse(readFileSync(path, 'utf8')));
+  } catch {
+    return fail();
+  }
+}
+/** Local v1 roster supplies paths/requirements only for explicitly enrolled workers. */
+export function enrolledRoster(
+  definition: FleetDefinition,
+  overrides: unknown
+): FleetConfig {
+  const roster = parseConfig(overrides);
+  for (const node of roster.nodes) {
+    const declared = definition.workers.find((entry) => entry.id === node.id);
+    if (!declared)
+      throw new FleetUsageError(
+        'Roster contains a node that is not a declared worker. Add the worker to fleet.json in Git before rollout; the manager is never a roster node.'
+      );
+    if (declared.ssh !== node.ssh)
+      throw new FleetUsageError(
+        'Fleet SSH assignment conflicts with the local roster. Review the migration; discovery cannot overwrite explicit assignments.'
+      );
+  }
+  return {
+    ...roster,
+    nodes: roster.nodes.map((node) => ({
+      ...node,
+      required: [
+        ...new Set([
+          ...node.required,
+          ...(definition.worker?.requiredCapabilities ?? []),
+        ]),
+      ],
+    })),
+  };
+}