@crvouga/dev-fleet 0.4.0 → 0.6.0

package/src/cli/fleet-sync-remote.ts

@@ -203,7 +203,7 @@ function deployWithMonitoring(
     );
     // Workers are Linux by definition.
     ui.progress.step(node.id, 'Verifying SSH, OS and T3');
-    result.checks.push(...(await inspectBootstrap(node, run, 'linux')));
+    result.checks.push(...(await inspectBootstrap(node, run)));
     result.checks.push(
       ...(await workerChecks(enabled(idesOf(canonical), IDES), node, {
         run,

package/src/cli/github-verify.ts

@@ -0,0 +1,57 @@
+import type { Command } from 'commander';
+import { hostname } from 'node:os';
+import { FleetUsageError } from '../errors';
+import { fleet } from '../fleet-config';
+import { githubPolicy } from '../github/policy';
+import { verifyGithubWorkflow } from '../github/workflow';
+import { runCommand } from '../runner';
+import { hostId } from '../topology';
+import type { Runner } from '../types';
+import type { CommandOutcome } from './contracts';
+
+/** Runs the GitHub workflow an agent depends on from this machine against
+ * the declared sandbox repository, and cleans up after itself.
+ */
+export async function githubVerify(
+  run: Runner = runCommand,
+  node = hostId(hostname())
+): Promise<CommandOutcome> {
+  const sandbox = githubPolicy(fleet).sandbox;
+  if (!sandbox)
+    throw new FleetUsageError(
+      'No sandbox repository. Declare github.sandbox ("owner/name") in fleet.json: a repository the fleet login may branch, push to and open pull requests on.'
+    );
+  const result = await verifyGithubWorkflow({ run, sandbox, node });
+  const ok = result.check.status === 'pass';
+  return {
+    exitCode: ok ? 0 : 1,
+    data: {
+      version: 1,
+      command: 'github-verify',
+      ok,
+      node,
+      checks: [result.check],
+      ...(result.failed ? { failedStep: result.failed } : {}),
+      leftBehind: result.leftBehind,
+    },
+    text: `${result.check.id} ${result.check.status}: ${result.check.summary}`,
+  };
+}
+
+export function registerGithubVerify(
+  program: Command,
+  complete: (outcome: CommandOutcome) => void
+): void {
+  program
+    .command('fleet-github-verify')
+    .description(
+      'Prove this machine can clone, push, open a pull request, read checks and comment on GitHub'
+    )
+    .addHelpText(
+      'after',
+      '\nWorks on the sandbox repository named by github.sandbox in fleet.json: a uniquely named branch and a draft pull request, both closed and deleted again by the same run, whatever failed.'
+    )
+    .action(async () => {
+      complete(await githubVerify());
+    });
+}

package/src/cli/register-fleet.ts

@@ -11,6 +11,7 @@ import { fleetAccounts, type FleetAccountsOptions } from './fleet-accounts';
 import { fleetReport, type FleetReportOptions } from './fleet-report';
 import { fleetWatch, watchServices } from './fleet-watch';
 import type { NodeReport } from '../types';
+import { registerGithubVerify } from './github-verify';
 
 type Complete = (outcome: CommandOutcome) => void;
 
@@ -350,6 +351,7 @@ export function registerFleet(
   registerRepair(registration);
   registerNodes(registration);
   registerAccounts(registration);
+  registerGithubVerify(program, complete);
 }
 
 function registerAccounts({ program, defaults, complete }: Registration) {

package/src/cli/registry.ts

@@ -161,6 +161,13 @@ export const COMMANDS: CommandSpec[] = [
       ['accounts', 'login', 'relogin', 'remove', 'add', 'sign in'],
       true,
     ],
+    [
+      'fleet-github-verify',
+      'Verify the GitHub workflow from this machine',
+      'Against the sandbox repository fleet.json declares (github.sandbox): clone, push a uniquely named branch, open a draft pull request, read its checks and comment, then close it and delete the branch whatever failed. Fails at the named step.',
+      ['github', 'verify', 'pull request', 'push', 'permissions', 'workflow'],
+      true,
+    ],
   ]),
   ...group('T3', [
     [

package/src/definition.ts

@@ -17,11 +17,13 @@ import {
   type T3Definition,
 } from './ide/definition';
 import { parseNotify, type NotifyConfig } from './notify';
+import { ubuntuRelease } from './platform/ubuntu-release';
+import { parseGithubPolicy, type GithubPolicy } from './github/policy';
 
 export interface MachineDefinition {
   id: string;
   ssh: string;
-  os: 'linux' | 'macOS' | 'windows';
+  os: 'linux';
   /** Tool profiles this worker adds to the fleet-wide ones. */
   toolProfiles?: ToolProfile[];
   network?: {
@@ -78,7 +80,11 @@ export interface FleetDefinition {
   git?: GitIdentity;
   /** Where fleet-watch sends notifications; absent, nobody is notified. */
   notify?: NotifyConfig;
-  ubuntu: { release: '26.04'; architectures: ['amd64', 'arm64'] };
+  /** An Ubuntu release ansible/ubuntu/policy.json accepts, with exactly the
+   * architectures the policy names for it. */
+  ubuntu: { release: string; architectures: string[] };
+  /** How every node signs in to GitHub; defaults when absent. */
+  github?: GithubPolicy;
 }
 /** How provider accounts are watched and chosen (src/accounts/). */
 export interface AccountPolicy {
@@ -223,6 +229,7 @@ export function parseDefinition(value: unknown): FleetDefinition {
       't3',
       'git',
       'notify',
+      'github',
     ])
   )
     return fail();
@@ -249,7 +256,10 @@ export function parseDefinition(value: unknown): FleetDefinition {
  */
 function optionalSections(
   value: Record<string, unknown>
-): Pick<FleetDefinition, 'worker' | 'ides' | 't3' | 'git' | 'notify'> {
+): Pick<
+  FleetDefinition,
+  'worker' | 'ides' | 't3' | 'git' | 'notify' | 'github'
+> {
   return {
     ...(value['worker'] === undefined
       ? {}
@@ -260,6 +270,9 @@ function optionalSections(
     ...(value['notify'] === undefined
       ? {}
       : { notify: parseNotify(value['notify']) ?? fail() }),
+    ...(value['github'] === undefined
+      ? {}
+      : { github: parseGithubPolicy(value['github']) }),
   };
 }
 /** Singleton services name no host: they always run on the manager. */
@@ -449,14 +462,22 @@ function source(value: unknown): FleetDefinition['source'] {
   return { repository: value['repository'] };
 }
 function baseline(ubuntu: unknown): FleetDefinition['ubuntu'] {
+  if (!record(ubuntu) || !keys(ubuntu, ['release', 'architectures']))
+    return fail();
+  const accepted =
+    typeof ubuntu['release'] === 'string'
+      ? ubuntuRelease(ubuntu['release'])
+      : undefined;
   if (
-    !record(ubuntu) ||
-    !keys(ubuntu, ['release', 'architectures']) ||
-    ubuntu['release'] !== '26.04' ||
-    JSON.stringify(ubuntu['architectures']) !== '["amd64","arm64"]'
+    !accepted ||
+    JSON.stringify(ubuntu['architectures']) !==
+      JSON.stringify(accepted.architectures)
   )
     return fail();
-  return ubuntu as FleetDefinition['ubuntu'];
+  return {
+    release: accepted.release,
+    architectures: [...accepted.architectures],
+  };
 }
 
 /** The configuration as every machine keeps it at

package/src/github/checks.ts

@@ -0,0 +1,412 @@
+import type { FleetDefinition } from '../definition';
+import type { SecretsProvider } from '../secrets';
+import type { Check, Runner } from '../types';
+import { githubCredential } from './credential';
+import { githubNode, githubPolicy, type GithubNode } from './policy';
+import { activeToken, GITHUB_STEP_TIMEOUT_MS } from './sync';
+
+export interface GithubCheckInput {
+  definition: FleetDefinition;
+  /** The node measured; the manager when it is not a declared worker. */
+  node?: string;
+  secret: SecretsProvider;
+  now?: () => Date;
+}
+
+const DAY = 86_400_000;
+const EXPIRY_WARN_DAYS = 14;
+const EXPIRY_FAIL_DAYS = 3;
+const RATE_WARN_FRACTION = 0.2;
+
+/** GitHub sign-in on any node, manager or worker: what the token is, what it
+ * can do and for how long. One request to GitHub answers the scopes, the
+ * expiry and the rate limit together; nothing it prints is kept.
+ */
+export async function githubChecks(
+  run: Runner,
+  input: GithubCheckInput
+): Promise<Check[]> {
+  const target = githubNode(input.definition, input.node);
+  const policy = githubPolicy(input.definition);
+  const status = await run(['gh', 'auth', 'status', '--active'], {
+    timeoutMs: 15_000,
+  });
+  const checks: Check[] = [
+    {
+      id: 'auth:github',
+      status: status.ok ? 'pass' : 'fail',
+      summary: status.ok
+        ? 'github check succeeded in this process context.'
+        : `github check failed (${status.reason}); no credential output retained.`,
+      ...(status.ok
+        ? {}
+        : {
+            remedy: {
+              action: target.managed
+                ? 'Put the fleet GitHub token in the secrets provider under github-token, then run fleet-sync: it signs this node in. No interactive login is needed.'
+                : 'Authenticate on this node with gh auth login, then gh auth setup-git.',
+            },
+          }),
+    },
+  ];
+  const user = await run(['gh', 'api', '--include', 'user'], {
+    timeoutMs: GITHUB_STEP_TIMEOUT_MS,
+  });
+  const response = parseResponse(user.stdout);
+  const login =
+    user.ok && typeof response.body?.['login'] === 'string'
+      ? response.body['login']
+      : null;
+  checks.push(principal(target, login));
+  if (target.managed) checks.push(await tokenCurrent(run, target, input));
+  if (login === null) return checks;
+  const now = (input.now ?? (() => new Date()))();
+  checks.push(
+    await permissions(run, policy.scopes, policy.repositories, response),
+    expiry(response.headers, now),
+    rateLimit(response.headers),
+    ...(await organizationAccess(run, policy.organizations, login)),
+    await gitCredential(run)
+  );
+  return checks;
+}
+
+interface Response {
+  headers: Record<string, string>;
+  body: Record<string, unknown> | null;
+}
+
+/** `gh api --include`: a status line, headers, a blank line, then the body. */
+export function parseResponse(text: string): Response {
+  const [head = '', ...rest] = text.split(/\r?\n\r?\n/);
+  const headers: Record<string, string> = {};
+  for (const line of head.split(/\r?\n/).slice(1)) {
+    const at = line.indexOf(':');
+    if (at > 0)
+      headers[line.slice(0, at).trim().toLowerCase()] = line
+        .slice(at + 1)
+        .trim();
+  }
+  let body: Record<string, unknown> | null = null;
+  try {
+    const parsed: unknown = JSON.parse(rest.join('\n\n'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+      body = parsed as Record<string, unknown>;
+  } catch {}
+  return { headers, body };
+}
+
+function principal(target: GithubNode, login: string | null): Check {
+  if (target.login === null)
+    return {
+      id: 'github:principal',
+      status: 'skip',
+      required: false,
+      summary:
+        'The fleet declares no GitHub login (worker.githubLogin); the account is not compared.',
+    };
+  const ok = login === target.login;
+  return {
+    id: 'github:principal',
+    status: ok ? 'pass' : 'fail',
+    summary: ok
+      ? `This ${target.role} is signed in to GitHub as the declared ${target.managed ? 'fleet' : 'personal'} login.`
+      : login === null
+        ? 'GITHUB_NOT_SIGNED_IN'
+        : 'GITHUB_LOGIN_MISMATCH: this node is signed in to GitHub as an account the fleet configuration does not declare for it.',
+    ...(ok
+      ? {}
+      : {
+          remedy: {
+            action: target.managed
+              ? 'Run fleet-sync: it signs this node in with the token in the secrets provider (github-token). If the stored token belongs to another account, replace it or change worker.githubLogin.'
+              : 'Sign in on this manager as the login named in github.manager of the fleet configuration (gh auth login), or change that declaration. dev-fleet never replaces a personal login.',
+          },
+        }),
+  };
+}
+
+/** The node uses the token the store holds now: after a rotation, every node
+ * passes before the old token is revoked.
+ */
+async function tokenCurrent(
+  run: Runner,
+  target: GithubNode,
+  input: GithubCheckInput
+): Promise<Check> {
+  const stored = (
+    (await githubCredential(input.definition, target.node, input.secret)()) ??
+    ''
+  ).trim();
+  if (!stored)
+    return {
+      id: 'github:token-current',
+      status: 'skip',
+      required: false,
+      summary:
+        'The secrets provider holds no github-token for this node; there is no stored token to compare with.',
+    };
+  const ok = (await activeToken(run)) === stored;
+  return {
+    id: 'github:token-current',
+    status: ok ? 'pass' : 'fail',
+    summary: ok
+      ? 'This node signs GitHub requests with the token the store holds now.'
+      : 'GITHUB_TOKEN_STALE: this node still uses a token the store no longer holds.',
+    ...(ok
+      ? {}
+      : {
+          remedy: {
+            action:
+              'Run fleet-sync, or wait for the next run of the GitHub sign-in job: either adopts the stored token while the old one still works. Revoke the old token only when every node passes this check.',
+          },
+        }),
+  };
+}
+
+/** A scope a token has implies the scopes beneath it. */
+const IMPLIED: Record<string, string[]> = {
+  repo: [
+    'repo:status',
+    'repo_deployment',
+    'public_repo',
+    'repo:invite',
+    'security_events',
+  ],
+  'write:packages': ['read:packages'],
+  'admin:org': ['write:org', 'read:org', 'manage_runners:org'],
+  'write:org': ['read:org'],
+  'admin:repo_hook': ['write:repo_hook', 'read:repo_hook'],
+  'write:repo_hook': ['read:repo_hook'],
+  'admin:public_key': ['write:public_key', 'read:public_key'],
+  'write:public_key': ['read:public_key'],
+  user: ['read:user', 'user:email', 'user:follow'],
+};
+
+async function permissions(
+  run: Runner,
+  scopes: string[],
+  repositories: string[],
+  response: Response
+): Promise<Check> {
+  const base = { id: 'github:permissions' };
+  if (!scopes.length && !repositories.length)
+    return {
+      ...base,
+      status: 'skip',
+      required: false,
+      summary:
+        'The fleet declares no GitHub scopes or repositories (github.scopes, github.repositories).',
+    };
+  const granted = response.headers['x-oauth-scopes'];
+  const missing: string[] = [];
+  if (scopes.length && granted !== undefined) {
+    const held = new Set(
+      granted
+        .split(',')
+        .map((scope) => scope.trim())
+        .filter(Boolean)
+        .flatMap((scope) => [scope, ...(IMPLIED[scope] ?? [])])
+    );
+    missing.push(...scopes.filter((scope) => !held.has(scope)));
+  }
+  for (const repository of repositories) {
+    const result = await run(
+      ['gh', 'api', `repos/${repository}`, '--jq', '.permissions.push'],
+      { timeoutMs: GITHUB_STEP_TIMEOUT_MS }
+    );
+    if (!result.ok || result.stdout.trim() !== 'true')
+      missing.push(`push to ${repository}`);
+  }
+  if (missing.length)
+    return {
+      ...base,
+      status: 'fail',
+      summary: `GITHUB_PERMISSION_MISSING: ${missing.join(', ')}`,
+      remedy: {
+        action:
+          'Issue a token with the permissions named, store it as github-token and run fleet-sync. A token without them fails agents mid-task with a 403.',
+      },
+    };
+  // A fine-grained token reports no scopes: only the repositories are proof.
+  if (scopes.length && granted === undefined)
+    return {
+      ...base,
+      status: 'warn',
+      summary:
+        'GITHUB_SCOPES_NOT_OBSERVABLE: the token reports no scopes (a fine-grained token); the declared repositories were checked.',
+    };
+  return {
+    ...base,
+    status: 'pass',
+    summary:
+      'The token holds every declared scope and can push to every declared repository.',
+  };
+}
+
+/** `2026-11-20 12:00:00 UTC` or `2026-11-20 12:00:00 -0800`. */
+export function parseExpiry(value: string): Date | null {
+  const match =
+    /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) (UTC|[+-]\d{4})$/.exec(value);
+  if (!match) return null;
+  const zone =
+    match[3] === 'UTC' ? 'Z' : `${match[3]!.slice(0, 3)}:${match[3]!.slice(3)}`;
+  const date = new Date(`${match[1]}T${match[2]}${zone}`);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function expiry(headers: Record<string, string>, now: Date): Check {
+  const value = headers['github-authentication-token-expiration'];
+  const base = { id: 'github:expiry' };
+  if (value === undefined)
+    return {
+      ...base,
+      status: 'pass',
+      summary: 'GitHub reports no expiry date for this token.',
+    };
+  const date = parseExpiry(value);
+  if (!date)
+    return {
+      ...base,
+      status: 'warn',
+      summary:
+        'GitHub reported an expiry date in a form this check does not read.',
+    };
+  const days = (date.getTime() - now.getTime()) / DAY;
+  const at = date.toISOString();
+  const remedy = {
+    action:
+      'Issue a new token, store it as github-token and run fleet-sync before this one expires; every node adopts it while the old one still works.',
+  };
+  if (days <= EXPIRY_FAIL_DAYS)
+    return {
+      ...base,
+      status: 'fail',
+      summary: `GITHUB_TOKEN_EXPIRING: the token expires at ${at}.`,
+      remedy,
+    };
+  if (days <= EXPIRY_WARN_DAYS)
+    return {
+      ...base,
+      status: 'warn',
+      summary: `GITHUB_TOKEN_EXPIRING_SOON: the token expires at ${at}.`,
+      remedy,
+    };
+  return { ...base, status: 'pass', summary: `The token expires at ${at}.` };
+}
+
+function rateLimit(headers: Record<string, string>): Check {
+  const limit = Number(headers['x-ratelimit-limit']);
+  const remaining = Number(headers['x-ratelimit-remaining']);
+  const reset = Number(headers['x-ratelimit-reset']);
+  const base = { id: 'github:rate-limit' };
+  if (!(limit > 0) || !Number.isFinite(remaining))
+    return {
+      ...base,
+      status: 'skip',
+      required: false,
+      summary: 'GitHub reported no rate limit for this request.',
+    };
+  const percent = Math.round((remaining / limit) * 100);
+  const resetAt = Number.isFinite(reset)
+    ? new Date(reset * 1000).toISOString()
+    : 'an unknown time';
+  if (remaining / limit < RATE_WARN_FRACTION)
+    return {
+      ...base,
+      status: 'warn',
+      summary: `GITHUB_RATE_LIMIT_LOW: ${remaining} of ${limit} requests (${percent} %) remain until ${resetAt}.`,
+      remedy: {
+        action:
+          'Every node shares the rate limit of one login. Spread the load with per-node credentials (github.credential "per-node") or wait for the reset.',
+      },
+    };
+  return {
+    ...base,
+    status: 'pass',
+    summary: `${remaining} of ${limit} requests (${percent} %) remain until ${resetAt}.`,
+  };
+}
+
+async function organizationAccess(
+  run: Runner,
+  organizations: string[],
+  login: string
+): Promise<Check[]> {
+  if (!organizations.length) return [];
+  const missing: string[] = [];
+  const unauthorized: string[] = [];
+  for (const organization of organizations) {
+    const result = await run(
+      ['gh', 'api', '--include', `user/memberships/orgs/${organization}`],
+      { timeoutMs: GITHUB_STEP_TIMEOUT_MS }
+    );
+    const response = parseResponse(result.stdout);
+    if (response.headers['x-github-sso']?.startsWith('required'))
+      unauthorized.push(organization);
+    else if (!result.ok || response.body?.['state'] !== 'active')
+      missing.push(organization);
+  }
+  if (!missing.length && !unauthorized.length)
+    return [
+      {
+        id: 'github:org-access',
+        status: 'pass',
+        summary: `${login} is an active member of every declared organisation, and single sign-on has authorised the token.`,
+      },
+    ];
+  const reasons: string[] = [];
+  if (unauthorized.length)
+    reasons.push(
+      `GITHUB_SSO_AUTHORIZATION_REQUIRED: ${unauthorized.join(', ')}`
+    );
+  if (missing.length)
+    reasons.push(`GITHUB_ORG_MEMBERSHIP_MISSING: ${missing.join(', ')}`);
+  return [
+    {
+      id: 'github:org-access',
+      status: 'fail',
+      summary: reasons.join('; '),
+      remedy: {
+        action:
+          'Authorise the token for single sign-on in each organisation named (GitHub settings, Configure SSO), or add the fleet login to it. This needs a person who administers the organisation.',
+      },
+    },
+  ];
+}
+
+/** git asks gh for the token at every use, so a replaced token needs no
+ * change in git; no second copy of it is written.
+ */
+async function gitCredential(run: Runner): Promise<Check> {
+  const helpers = await run(
+    [
+      'git',
+      'config',
+      '--global',
+      '--get-all',
+      'credential.https://github.com.helper',
+    ],
+    { timeoutMs: 5_000 }
+  );
+  const ok =
+    helpers.ok &&
+    helpers.stdout
+      .split('\n')
+      .some((line) => /(^|[/!\s])gh'? auth git-credential$/.test(line.trim()));
+  return {
+    id: 'github:git-credential',
+    status: ok ? 'pass' : 'fail',
+    summary: ok
+      ? 'git asks gh for the GitHub token at every use.'
+      : 'GITHUB_GIT_CREDENTIAL_MISSING: git does not take its GitHub credential from gh.',
+    ...(ok
+      ? {}
+      : {
+          remedy: {
+            action:
+              'Declare the git block in fleet.json and run fleet-sync: ansible/github/git.yml sets gh as the credential helper. On a manager with a personal login, run gh auth setup-git.',
+          },
+        }),
+  };
+}

package/src/github/converge.ts

@@ -0,0 +1,62 @@
+import type { Check, Runner } from '../types';
+import type { GithubCode } from './sync';
+
+const CODES: GithubCode[] = [
+  'GITHUB_OK',
+  'GITHUB_TOKEN_MISSING',
+  'GITHUB_TOKEN_REJECTED',
+  'GITHUB_LOGIN_MISMATCH',
+  'GITHUB_UNREACHABLE',
+  'GITHUB_SIGN_IN_FAILED',
+];
+
+const REMEDIES: Record<Exclude<GithubCode, 'GITHUB_OK'>, string> = {
+  GITHUB_TOKEN_MISSING:
+    'Store the fleet GitHub token in the secrets provider under github-token (github-token-<node> with github.credential "per-node"), then run fleet-sync again.',
+  GITHUB_TOKEN_REJECTED:
+    'GitHub refuses the stored token: it was revoked or has expired. Store a new one under github-token and run fleet-sync again.',
+  GITHUB_LOGIN_MISMATCH:
+    'The stored token belongs to another account than the fleet configuration declares (worker.githubLogin, or github.manager for the manager). Store the right token or correct the declaration.',
+  GITHUB_UNREACHABLE:
+    'GitHub did not answer from this node. Check its network and DNS; the node keeps the sign-in it has.',
+  GITHUB_SIGN_IN_FAILED:
+    'gh refused to store the validated token. Inspect gh on this node (gh auth status); nothing was copied from another machine.',
+};
+
+/** Runs this node's GitHub sign-in job once and reports what it came to. A
+ * failure fails the sync: a node that cannot reach GitHub as the fleet login
+ * is not ready for an agent.
+ */
+export async function convergeGithub(
+  root: string,
+  run: Runner,
+  node?: string
+): Promise<Check> {
+  const result = await run(
+    ['bun', 'bootstrap/worker-github.ts', ...(node ? ['--node', node] : [])],
+    { cwd: root, timeoutMs: 240_000 }
+  );
+  let code: GithubCode | undefined;
+  try {
+    const line: unknown = JSON.parse(result.stdout.trim().split('\n').pop()!);
+    const found = (line as { code?: unknown }).code;
+    if (CODES.includes(found as GithubCode)) code = found as GithubCode;
+  } catch {}
+  if (code === 'GITHUB_OK')
+    return {
+      id: 'github:sync',
+      status: 'pass',
+      summary:
+        'This node is signed in to GitHub as its declared login with the stored credential.',
+    };
+  return {
+    id: 'github:sync',
+    status: 'fail',
+    summary: code ?? 'GITHUB_SYNC_UNREPORTED',
+    remedy: {
+      action: code
+        ? REMEDIES[code]
+        : 'The GitHub sign-in job reported no result. Run bun bootstrap/worker-github.ts on this node to see its result line.',
+    },
+  };
+}