@crvouga/dev-fleet 0.1.0 → 0.2.0

package/bootstrap/fleet-remote-bootstrap.sh

@@ -1,6 +1,8 @@
 #!/bin/sh
-# Executed over strict SSH from the selected verified Git revision. stdin is a
-# base64 Git bundle. All executable content remains in this tracked source.
+# Executed over strict SSH from the selected verified Git revision. stdin is
+# one line holding the base64 fleet configuration (empty when there is none),
+# then the base64 Git bundle (nothing in cached mode). All executable content
+# remains in this tracked source.
 set -eu
 umask 077
 revision=$1
@@ -16,12 +18,47 @@ case "$node" in *[!a-z0-9-]*|'') exit 2;; esac
 phase=bootstrap
 bundle=''
 code=0
+apt_log=''
 failure_code=REMOTE_BOOTSTRAP_INCOMPLETE
 die() { failure_code=$1; exit 1; }
+# One remedy per failure: what the operator does next. Never raw output.
+remedy() {
+  case "$1" in
+    FLEET_REMOTE_LOCKED) echo 'Another fleet operation holds this machine. Wait for it to finish; rerun fleet-sync afterwards. Never remove the lock while its holder runs.';;
+    ROOT_DEVELOPMENT_USER_REJECTED) echo 'Connect as the non-root developer account the fleet configuration names.';;
+    UBUNTU_BASELINE_MISMATCH|UBUNTU_ARCHITECTURE_UNSUPPORTED|MACOS_BASELINE_MISMATCH|MACOS_ARCHITECTURE_UNSUPPORTED|PLATFORM_UNSUPPORTED) echo 'Workers run Ubuntu 26.04 on x86_64 or aarch64. Reinstall the machine; fleet-sync never upgrades an operating system.';;
+    FLEET_STATE_PATH_UNSAFE) echo 'A fleet state directory under ~/.local/share/personal is a symbolic link. Replace it with a real directory.';;
+    BOOTSTRAP_CAPACITY_UNVERIFIED|BOOTSTRAP_DISK_CAPACITY_REQUIRED) echo 'Free at least 2 GiB and 50000 inodes on the home file system, then rerun fleet-sync.';;
+    SOURCE_DIGEST_MISMATCH) echo 'The bundle changed in transit. Rerun fleet-sync; if it repeats, check the SSH route.';;
+    SUDO_AUTHORIZATION_REQUIRED) echo 'Grant the developer account passwordless sudo, or run fleet-sync interactively once to authorize it.';;
+    APT_LOCK_CONTENDED) echo 'Another package operation held the APT lock past the bounded wait. Let it finish (it is never killed), then rerun fleet-sync.';;
+    APT_DNS_UNAVAILABLE) echo 'The worker cannot resolve the Ubuntu archive. Restore its DNS, then rerun fleet-sync.';;
+    APT_REPOSITORY_UNAVAILABLE) echo 'The Ubuntu archive could not be reached. Check the network or archive status, then rerun fleet-sync.';;
+    APT_DISK_FULL) echo 'Package installation ran out of disk space. Free space under /var and /usr, then rerun fleet-sync.';;
+    DPKG_INTERRUPTED) echo 'An earlier package installation that fleet-sync did not start was interrupted. Run sudo dpkg --configure -a once no package process is running, then rerun fleet-sync.';;
+    APT_UPDATE_FAILED|APT_INSTALL_FAILED) echo 'Run sudo apt-get update and install the bootstrap packages by hand to see the error, then rerun fleet-sync.';;
+    XCODE_COMMAND_LINE_TOOLS_REQUIRED) echo 'Install the Xcode Command Line Tools (xcode-select --install), then rerun fleet-sync.';;
+    BOOTSTRAP_LOCK_TOOL_REQUIRED) echo 'Install python3 so the operation lock can be taken, then rerun fleet-sync.';;
+    SOURCE_CACHE_CHANGED|SOURCE_STATUS_FAILED|SOURCE_CHECKOUT_CONFLICT) echo 'The fleet-owned checkout of this revision holds changes fleet-sync did not make. Inspect and remove that revisions directory, then rerun fleet-sync.';;
+    CONFIGURATION_INSTALL_FAILED) echo 'The fleet configuration could not be written under ~/.config/dev-fleet. Check that directory, then rerun fleet-sync.';;
+    TOOLCHAIN_*) echo 'The pinned toolchain did not converge. Rerun fleet-sync; it resumes where it stopped. If it repeats, run devfleet doctor on the worker.';;
+    *) echo 'Inspect the remote operation lock and rerun the approved revision. No success receipt advanced.';;
+  esac
+}
+# Names an APT failure by the fixed messages of the pinned Ubuntu release.
+apt_failure() {
+  if grep -q 'Could not get lock' "$apt_log" 2>/dev/null; then die APT_LOCK_CONTENDED
+  elif grep -q 'No space left on device' "$apt_log" 2>/dev/null; then die APT_DISK_FULL
+  elif grep -qE 'Temporary failure resolving|Could not resolve' "$apt_log" 2>/dev/null; then die APT_DNS_UNAVAILABLE
+  elif grep -qE 'Failed to fetch|Unable to connect|Connection failed|Unable to locate package' "$apt_log" 2>/dev/null; then die APT_REPOSITORY_UNAVAILABLE
+  elif grep -q 'dpkg was interrupted' "$apt_log" 2>/dev/null; then die DPKG_INTERRUPTED
+  else die "$1"
+  fi
+}
 fail() {
-  printf '{"version":1,"checks":[{"id":"bootstrap:%s","status":"fail","summary":"%s","remedy":{"action":"Inspect prerequisites and the remote operation lock, then retry the approved revision. No success receipt advanced."}}]}\n' "$phase" "$failure_code"
+  printf '{"version":1,"checks":[{"id":"bootstrap:%s","status":"fail","summary":"%s","remedy":{"action":"%s"}}]}\n' "$phase" "$failure_code" "$(remedy "$failure_code")"
 }
-trap 'code=$?; [ -z "$bundle" ] || rm -f -- "$bundle"; if [ "$code" != 0 ]; then fail; fi' EXIT
+trap 'code=$?; [ -z "$bundle" ] || rm -f -- "$bundle"; [ -z "$apt_log" ] || rm -f -- "$apt_log"; if [ "$code" != 0 ]; then fail; fi' EXIT
 # Preserve the lock holder if its SSH channel disappears mid-install.
 trap '' HUP
 trap 'exit 1' INT TERM
@@ -61,6 +98,16 @@ else
   python3 -c 'import fcntl; fcntl.flock(9, fcntl.LOCK_EX | fcntl.LOCK_NB)' 9>&9 || die FLEET_REMOTE_LOCKED
 fi
 printf '{"version":1,"pid":%s,"revision":"%s","node":"%s"}\n' "$$" "$revision" "$node" >"$root/remote-operation.json"
+# The fleet configuration is installed under the lock, so two overlapping
+# runs never write it at once. It holds no secret.
+phase='configuration-install'
+IFS= read -r configuration || configuration=''
+if [ -n "$configuration" ]; then
+  config_dir="$HOME/.config/dev-fleet"
+  mkdir -p "$config_dir" || die CONFIGURATION_INSTALL_FAILED
+  printf '%s' "$configuration" | base64 -d >"$config_dir/fleet.json.new" || die CONFIGURATION_INSTALL_FAILED
+  mv "$config_dir/fleet.json.new" "$config_dir/fleet.json" || die CONFIGURATION_INSTALL_FAILED
+fi
 phase=resources
 # A bootstrap floor protects source transfer and minimal prerequisites. The
 # Workstation baseline subsequently enforces its stricter declared capacity.
@@ -87,11 +134,30 @@ for package in git curl ca-certificates unzip xz-utils build-essential python3 a
 done
 if [ -n "$missing" ]; then
   sudo -n true >/dev/null 2>&1 || die SUDO_AUTHORIZATION_REQUIRED
+  # APT's own messages, in a private file read only for fixed patterns and
+  # removed on exit: they tell a held lock, DNS, an unreachable archive and a
+  # full disk apart. Nothing of them is reported.
+  apt_log=$(mktemp "$root/apt.XXXXXX")
+  pending="$root/prerequisites-pending"
+  # An installation this script started and that was interrupted (the shell
+  # killed, the machine powered off) leaves dpkg half-configured. Finishing
+  # our own transaction is safe; one fleet-sync did not start is reported.
+  # dpkg reads its database lock even to audit, which needs root.
+  if [ -n "$(sudo -n dpkg --audit 2>/dev/null)" ]; then
+    [ -f "$pending" ] || die DPKG_INTERRUPTED
+    # shellcheck disable=SC2024
+    sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive LC_ALL=C dpkg --configure -a >"$apt_log" 2>&1 || apt_failure APT_INSTALL_FAILED
+  fi
+  : >"$pending"
+  # The log belongs to the developer account; sudo only runs the command.
+  # shellcheck disable=SC2024
   # Never remove APT locks or kill package processes. Timeout keeps genuine
   # transactions bounded; Ubuntu archive signatures/TLS remain enabled.
-  sudo -n timeout 300 apt-get -o DPkg::Lock::Timeout=120 update >/dev/null 2>&1 || die APT_UPDATE_FAILED
-  # shellcheck disable=SC2086
-  sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive apt-get -o DPkg::Lock::Timeout=120 --no-install-recommends install -y $missing >/dev/null 2>&1 || die APT_INSTALL_FAILED
+  sudo -n timeout 300 env LC_ALL=C apt-get -o DPkg::Lock::Timeout=120 update >"$apt_log" 2>&1 || apt_failure APT_UPDATE_FAILED
+  # shellcheck disable=SC2086,SC2024
+  sudo -n timeout 600 env DEBIAN_FRONTEND=noninteractive LC_ALL=C apt-get -o DPkg::Lock::Timeout=120 --no-install-recommends install -y $missing >>"$apt_log" 2>&1 || apt_failure APT_INSTALL_FAILED
+  rm -f -- "$pending" "$apt_log"
+  apt_log=''
 fi
 else
   # Apple Command Line Tools provide git and python3; Ansible runs through the
@@ -107,18 +173,25 @@ if [ ! -e "$deployment/.git" ]; then
   [ -z "$(ls -A "$deployment")" ] || exit 1
   git -C "$deployment" init -q >/dev/null 2>&1 || exit 1
 fi
-# An interrupted initial fetch/checkout can leave an empty initialized repository.
-# Resume only that state; an existing commit or untracked work is never reset.
+# An interrupted initial fetch or checkout leaves a repository without a
+# commit, possibly with some of the revision's files written. Resume only
+# that state: every file present must be a file of the revision, so the
+# checkout may write over it. An existing commit or other work is never reset.
 if ! git -C "$deployment" rev-parse --verify HEAD >/dev/null 2>&1; then
   [ "$source_mode" = transfer ] || die SOURCE_CACHE_CHANGED
   [ "$(git -C "$deployment" rev-parse --show-toplevel)" = "$deployment" ] || exit 1
-  clean=$(git -C "$deployment" status --porcelain) || die SOURCE_STATUS_FAILED
-  [ -z "$clean" ] || die SOURCE_CHECKOUT_CONFLICT
   # The bundle holds this commit without its history: declare the checkout
   # shallow at it so Git accepts a commit whose parents are absent.
   printf '%s\n' "$revision" >"$deployment/.git/shallow"
   git -C "$deployment" fetch --no-tags "$bundle" "$revision" >/dev/null 2>&1 || exit 1
-  git -C "$deployment" checkout --detach "$revision" >/dev/null 2>&1 || exit 1
+  present=$(mktemp "$root/present.XXXXXX")
+  expected=$(mktemp "$root/expected.XXXXXX")
+  git -C "$deployment" -c core.quotePath=false ls-files --others | LC_ALL=C sort >"$present" || { rm -f -- "$present" "$expected"; die SOURCE_STATUS_FAILED; }
+  git -C "$deployment" -c core.quotePath=false ls-tree -r --name-only "$revision" | LC_ALL=C sort >"$expected" || { rm -f -- "$present" "$expected"; die SOURCE_STATUS_FAILED; }
+  foreign=$(LC_ALL=C comm -23 "$present" "$expected")
+  rm -f -- "$present" "$expected"
+  [ -z "$foreign" ] || die SOURCE_CHECKOUT_CONFLICT
+  git -C "$deployment" checkout --force --detach "$revision" >/dev/null 2>&1 || exit 1
 fi
 [ -z "$bundle" ] || rm -f "$bundle"
 bundle=''

package/bootstrap/global-config.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
@@ -48,17 +49,23 @@ export function assertManagedConfig(dir: string): void {
   }
 }
 
+/** What `publishGlobalConfig` writes to config.toml, given what is there. */
+function publishedConfig(root: string, previous: string | undefined): string {
+  return (
+    MARKER +
+    withTrustedPaths(
+      readFileSync(join(root, 'mise.toml'), 'utf8'),
+      trustedPaths(previous)
+    )
+  );
+}
+
 export function publishGlobalConfig(dir: string, root = workspaceRoot): void {
   assertManagedConfig(dir);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'config.toml');
   const previous = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
-  const config =
-    MARKER +
-    withTrustedPaths(
-      readFileSync(join(root, 'mise.toml'), 'utf8'),
-      trustedPaths(previous)
-    );
+  const config = publishedConfig(root, previous);
   if (previous !== config) writeFileSync(path, config);
   cpSync(join(root, 'mise.lock'), join(dir, 'mise.lock'), {
     filter: changedFile,
@@ -71,6 +78,57 @@ export function publishGlobalConfig(dir: string, root = workspaceRoot): void {
     });
 }
 
+/**
+ * How the global mise configuration stands against what this revision
+ * publishes. On a fleet machine it belongs to dev-fleet: a project pins its
+ * tools in its own mise.toml and never publishes a global one.
+ *
+ * - `published`: dev-fleet's marker, this revision's pins and lock
+ * - `missing`: there is no global config.toml
+ * - `replaced`: another owner (or nobody's marker) wrote it
+ * - `changed`: dev-fleet's marker, but not this revision's content
+ */
+export type GlobalConfigStanding =
+  'published' | 'missing' | 'replaced' | 'changed';
+
+export function globalConfigStanding(
+  dir: string,
+  root = workspaceRoot
+): GlobalConfigStanding {
+  const path = join(dir, 'config.toml');
+  if (!existsSync(path)) return 'missing';
+  const current = readFileSync(path, 'utf8');
+  if (!current.startsWith(MARKER)) return 'replaced';
+  const same = (source: string, target: string): boolean =>
+    existsSync(target) && readFileSync(source).equals(readFileSync(target));
+  const sidecars = join(root, '.mise/locks');
+  const locks = existsSync(sidecars)
+    ? (readdirSync(sidecars, { recursive: true }) as string[])
+        .map((name) => join('.mise/locks', name))
+        .filter((name) => statSync(join(root, name)).isFile())
+    : [];
+  // Paths trusted on the machine are kept by every publish, in any order;
+  // the agent worktree roots must be among them.
+  const TRUSTED = /^trusted_config_paths\s*=.*\n/m;
+  const trusted = trustedPaths(current);
+  let listed: unknown;
+  try {
+    listed = (Bun.TOML.parse(current) as { settings?: Record<string, unknown> })
+      .settings?.['trusted_config_paths'];
+  } catch {
+    listed = undefined;
+  }
+  const unchanged =
+    Array.isArray(listed) &&
+    trusted.every((path) => listed.includes(path)) &&
+    current.replace(TRUSTED, '') ===
+      publishedConfig(root, current).replace(TRUSTED, '') &&
+    ['mise.lock', ...locks].every((name) =>
+      same(join(root, name), join(dir, name))
+    );
+  return unchanged ? 'published' : 'changed';
+}
+
 /**
  * The managed roots plus any entries already in the published config, so a
  * local `mise settings add trusted_config_paths ...` survives the next publish.

package/bootstrap/install-launcher.sh

@@ -3,5 +3,8 @@
 set -eu
 root=${1:-$(cd "$(dirname "$0")/.." && pwd)}
 [ -x "$root/bootstrap/devfleet" ] || exit 1
+# Only ever a checkout: an installed package sits wherever a package manager
+# put it and may be gone tomorrow.
+[ -e "$root/.git" ] || { echo 'The devfleet launcher links to a checkout of dev-fleet; fleet-sync installs it.' >&2; exit 1; }
 mkdir -p "$HOME/.local/bin"
 ln -sfn "$root/bootstrap/devfleet" "$HOME/.local/bin/devfleet"

package/bootstrap/npm.ts

@@ -162,7 +162,11 @@ export function plan(state: State): Step[] {
     {
       id: 'tag',
       title: `Tag ${seedTag} on the commit that was published`,
-      done: state.tagRemote,
+      // npm recorded no commit for a seed published without one, so there is
+      // nothing to tag: the Release workflow then counts from the newest
+      // version on npm (bootstrap/release-version.ts).
+      done:
+        state.tagRemote || (state.published && state.publishedCommit === null),
       blocked: null,
     },
   ];
@@ -204,9 +208,13 @@ function publishSeed(exec: Exec, target: Target): boolean {
     );
     const file = join(checkout, 'package.json');
     const manifest = JSON.parse(readFileSync(file, 'utf8')) as object;
+    // As the Release workflow does: the package names the commit it is.
+    const gitHead = exec
+      .capture(['git', 'rev-parse', 'HEAD'], checkout)
+      .stdout.trim();
     writeFileSync(
       file,
-      `${JSON.stringify({ ...manifest, version: SEED_VERSION }, null, 2)}\n`
+      `${JSON.stringify({ ...manifest, version: SEED_VERSION, gitHead }, null, 2)}\n`
     );
     return exec.interactive(['npm', 'publish', '--access', 'public'], checkout);
   } finally {

package/bootstrap/release-version.ts

@@ -0,0 +1,157 @@
+/**
+ * Prints the version the Release workflow should publish for `HEAD`, or
+ * nothing when there is nothing to release (the reason goes to stderr).
+ *
+ * The newest `vX.Y.Z` tag is the last release. Without one, the newest
+ * version on npm is: it was published by hand before the workflow tagged
+ * anything, and npm may not have recorded its commit, so every commit up to
+ * `HEAD` counts. Commits since the last release pick the bump, Conventional
+ * Commits style:
+ *
+ *   `feat!:` / `BREAKING CHANGE:`  major (minor while the major is 0)
+ *   `feat:`                         minor
+ *   anything else                   patch
+ *
+ * Exits 1 when nothing can be released because publishing was never set up
+ * (no tag and nothing on npm), so the Release workflow does not report a
+ * skipped release as a success.
+ *
+ *   bun bootstrap/release-version.ts
+ */
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Git {
+  /** Run git and return stdout, or null when it exits non-zero. */
+  (args: string[]): string | null;
+}
+
+export type Decision =
+  | { release: true; version: string; previous: string }
+  | { release: false; reason: string; setup?: true };
+
+const TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+const BREAKING_SUBJECT = /^\w+(\([^)]*\))?!:/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+const FEATURE = /^feat(\([^)]*\))?:/;
+
+export type Bump = 'major' | 'minor' | 'patch';
+
+export function bumpFor(messages: string[]): Bump {
+  let bump: Bump = 'patch';
+  for (const message of messages) {
+    const subject = message.split('\n', 1)[0]!.trim();
+    if (BREAKING_SUBJECT.test(subject) || BREAKING_FOOTER.test(message))
+      return 'major';
+    if (FEATURE.test(subject)) bump = 'minor';
+  }
+  return bump;
+}
+
+export function bumpVersion(tag: string, bump: Bump): string {
+  const match = TAG.exec(tag);
+  if (!match) throw new Error(`Not a release tag: ${tag}`);
+  const [major, minor, patch] = match.slice(1).map(Number) as [
+    number,
+    number,
+    number,
+  ];
+  if (bump === 'major' && major > 0) return `${major + 1}.0.0`;
+  if (bump === 'patch') return `${major}.${minor}.${patch + 1}`;
+  return `${major}.${minor + 1}.0`;
+}
+
+export function latestTag(git: Git): string | null {
+  const tags = git(['tag', '--list', 'v*', '--sort=-v:refname']) ?? '';
+  return (
+    tags
+      .split('\n')
+      .map((tag) => tag.trim())
+      .find((tag) => TAG.test(tag)) ?? null
+  );
+}
+
+/** The newest stable `X.Y.Z` of these npm versions, or null. */
+export function newestPublished(versions: string[]): string | null {
+  const stable = versions
+    .filter((version) => TAG.test(`v${version}`))
+    .map((version) => version.split('.').map(Number) as number[]);
+  stable.sort((a, b) => b[0]! - a[0]! || b[1]! - a[1]! || b[2]! - a[2]!);
+  return stable[0]?.join('.') ?? null;
+}
+
+/**
+ * `published` is the newest stable version on npm, or null when the package
+ * is not there.
+ */
+export function decide(git: Git, published: string | null = null): Decision {
+  const tag = latestTag(git);
+  if (!tag && !published)
+    return {
+      release: false,
+      setup: true,
+      reason:
+        'No vX.Y.Z tag and nothing on npm yet: run `bun run bootstrap` once first.',
+    };
+  const previous = tag ?? `v${published}`;
+  if (tag && git(['merge-base', '--is-ancestor', 'HEAD', tag]) !== null)
+    return { release: false, reason: `HEAD is already in ${tag}.` };
+  const log =
+    git(['log', '--format=%B%x00', tag ? `${tag}..HEAD` : 'HEAD']) ?? '';
+  const messages = log
+    .split('\0')
+    .map((message) => message.trim())
+    .filter(Boolean);
+  if (messages.length === 0)
+    return { release: false, reason: `No commits since ${previous}.` };
+  return {
+    release: true,
+    version: bumpVersion(previous, bumpFor(messages)),
+    previous,
+  };
+}
+
+const system: Git = (args) => {
+  const result = spawnSync('git', args, { encoding: 'utf8' });
+  return result.status === 0 ? (result.stdout ?? '') : null;
+};
+
+/** The versions of the package on npm; empty when it is not there. */
+function npmVersions(): string[] {
+  const name = (
+    JSON.parse(
+      readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf8')
+    ) as { name: string }
+  ).name;
+  const result = spawnSync('npm', ['view', name, 'versions', '--json'], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return [];
+  const versions: unknown = JSON.parse(result.stdout || '[]');
+  return Array.isArray(versions)
+    ? versions.filter((v): v is string => typeof v === 'string')
+    : typeof versions === 'string'
+      ? [versions]
+      : [];
+}
+
+if (import.meta.main) {
+  const decision = decide(system, newestPublished(npmVersions()));
+  const summary = process.env['GITHUB_STEP_SUMMARY'];
+  const note = (line: string) => {
+    if (summary) appendFileSync(summary, `${line}\n`);
+  };
+  if (decision.release) {
+    console.error(`${decision.previous} -> v${decision.version}`);
+    note(`Releasing v${decision.version} (after ${decision.previous}).`);
+    console.log(decision.version);
+  } else if (decision.setup) {
+    console.error(`::error::${decision.reason}`);
+    note(`**Nothing was released.** ${decision.reason}`);
+    process.exitCode = 1;
+  } else {
+    console.error(decision.reason);
+    note(`Nothing to release: ${decision.reason}`);
+  }
+}