@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/bootstrap/npm.ts

@@ -0,0 +1,350 @@
+/**
+ * `bun run bootstrap`: the one-time npm setup for publishing this package.
+ *
+ * npm can publish new versions through OIDC but cannot create a package that
+ * does not exist yet. So once, with your own npm login: publish the seed
+ * version, make the Release workflow the package's trusted publisher, and tag
+ * the commit that was published. Every step measures first and skips what is
+ * already done, so it is safe to run again after any interruption.
+ *
+ *   bun run bootstrap              walk through and do it
+ *   bun run bootstrap --yes        do not ask before publishing
+ *   bun run bootstrap --skip-check do not run `bun run check` first
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { confirm } from '@inquirer/prompts';
+
+export const SEED_VERSION = '0.1.0';
+export const WORKFLOW_FILE = 'release.yml';
+const MIN_NPM = [11, 10] as const;
+
+export interface Exec {
+  /** Run quietly and return the output. */
+  capture(command: string[], cwd?: string): Result;
+  /** Run with the terminal attached, for prompts and browser sign-in. */
+  interactive(command: string[], cwd?: string): boolean;
+}
+
+export interface Result {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+export interface Target {
+  /** `@scope/name` from package.json. */
+  name: string;
+  /** `owner/repo` from package.json. */
+  repo: string;
+  root: string;
+}
+
+export interface State {
+  npmVersion: string | null;
+  user: string | null;
+  published: boolean;
+  /** Null until the package exists: there is nothing to look at yet. */
+  trusted: boolean | null;
+  tagLocal: boolean;
+  tagRemote: boolean;
+  /** Commit npm recorded for the seed version, when it was published. */
+  publishedCommit: string | null;
+  clean: boolean;
+  onMain: boolean;
+}
+
+export type StepId = 'login' | 'publish' | 'trust' | 'tag';
+
+export interface Step {
+  id: StepId;
+  title: string;
+  done: boolean;
+  /** Why the step cannot run right now. */
+  blocked: string | null;
+}
+
+export const seedTag = `v${SEED_VERSION}`;
+
+export function readTarget(root: string): Target {
+  const manifest = JSON.parse(
+    readFileSync(join(root, 'package.json'), 'utf8')
+  ) as { name: string; repository: string };
+  return {
+    name: manifest.name,
+    repo: manifest.repository.replace(/^github:/, ''),
+    root,
+  };
+}
+
+export function npmIsRecent(version: string | null): boolean {
+  const [major = 0, minor = 0] = (version ?? '').split('.').map(Number);
+  return major > MIN_NPM[0] || (major === MIN_NPM[0] && minor >= MIN_NPM[1]);
+}
+
+export function measure(exec: Exec, target: Target): State {
+  const { name, repo, root } = target;
+  const npm = exec.capture(['npm', '--version']);
+  const whoami = exec.capture(['npm', 'whoami']);
+  const view = exec.capture([
+    'npm',
+    'view',
+    `${name}@${SEED_VERSION}`,
+    'gitHead',
+  ]);
+  const any = exec.capture(['npm', 'view', name, 'name']);
+  if (!any.ok && !/E404/.test(any.stderr))
+    throw new Error('Could not reach the npm registry. Check the network.');
+  const published = any.ok;
+  const trust = published
+    ? exec.capture(['npm', 'trust', 'list', name, '--json'])
+    : null;
+  exec.capture(['git', 'fetch', '--quiet', 'origin', 'main', '--tags'], root);
+  const head = exec.capture(['git', 'rev-parse', 'HEAD'], root).stdout.trim();
+  const main = exec
+    .capture(['git', 'rev-parse', 'origin/main'], root)
+    .stdout.trim();
+  return {
+    npmVersion: npm.ok ? npm.stdout.trim() : null,
+    user: whoami.ok ? whoami.stdout.trim() : null,
+    published,
+    trusted: trust
+      ? trust.ok &&
+        trust.stdout.includes(repo) &&
+        trust.stdout.includes(WORKFLOW_FILE)
+      : null,
+    tagLocal: exec.capture(
+      ['git', 'rev-parse', '--verify', '--quiet', `refs/tags/${seedTag}`],
+      root
+    ).ok,
+    tagRemote:
+      exec
+        .capture(
+          ['git', 'ls-remote', '--tags', 'origin', `refs/tags/${seedTag}`],
+          root
+        )
+        .stdout.trim() !== '',
+    publishedCommit: view.ok ? view.stdout.trim() || null : null,
+    clean:
+      exec.capture(['git', 'status', '--porcelain'], root).stdout.trim() === '',
+    onMain: head !== '' && head === main,
+  };
+}
+
+export function plan(state: State): Step[] {
+  const needsLogin = state.user === null;
+  const publishBlocked = !state.clean
+    ? 'The working tree has uncommitted changes; the seed is published from a commit.'
+    : !state.onMain
+      ? 'HEAD is not origin/main. Merge the change, then run this on main.'
+      : null;
+  return [
+    {
+      id: 'login',
+      title: 'Sign in to npm',
+      done: !needsLogin,
+      blocked: null,
+    },
+    {
+      id: 'publish',
+      title: `Publish ${SEED_VERSION}, the seed version`,
+      done: state.published,
+      blocked: state.published ? null : publishBlocked,
+    },
+    {
+      id: 'trust',
+      title: `Trust ${WORKFLOW_FILE} to publish every later version`,
+      done: state.trusted === true,
+      blocked: null,
+    },
+    {
+      id: 'tag',
+      title: `Tag ${seedTag} on the commit that was published`,
+      done: state.tagRemote,
+      blocked: null,
+    },
+  ];
+}
+
+export interface Deps {
+  exec: Exec;
+  /** Publish the seed version from a checkout of HEAD. */
+  seed(target: Target): boolean;
+  log(line: string): void;
+  ask(question: string): Promise<boolean>;
+}
+
+interface Options {
+  yes: boolean;
+  skipCheck: boolean;
+}
+
+function show(deps: Deps, state: State, steps: Step[]): void {
+  deps.log(
+    `npm ${state.npmVersion ?? 'missing'} · ${state.user ? `signed in as ${state.user}` : 'not signed in'}`
+  );
+  for (const step of steps)
+    deps.log(
+      `${step.done ? '✓' : step.blocked ? '✗' : '→'} ${step.title}${step.blocked ? ` (${step.blocked})` : ''}`
+    );
+}
+
+/** Publish from a throwaway checkout of HEAD so the working tree is never
+ * edited and npm records the commit it published.
+ */
+function publishSeed(exec: Exec, target: Target): boolean {
+  const dir = mkdtempSync(join(tmpdir(), 'dev-fleet-seed-'));
+  const checkout = join(dir, 'checkout');
+  try {
+    exec.capture(
+      ['git', 'worktree', 'add', '--detach', checkout, 'HEAD'],
+      target.root
+    );
+    const file = join(checkout, 'package.json');
+    const manifest = JSON.parse(readFileSync(file, 'utf8')) as object;
+    writeFileSync(
+      file,
+      `${JSON.stringify({ ...manifest, version: SEED_VERSION }, null, 2)}\n`
+    );
+    return exec.interactive(['npm', 'publish', '--access', 'public'], checkout);
+  } finally {
+    exec.capture(
+      ['git', 'worktree', 'remove', '--force', checkout],
+      target.root
+    );
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function tagPublished(exec: Exec, target: Target, state: State): boolean {
+  const commit =
+    state.publishedCommit ??
+    exec
+      .capture(['npm', 'view', `${target.name}@${SEED_VERSION}`, 'gitHead'])
+      .stdout.trim();
+  if (!commit) return false;
+  if (!state.tagLocal)
+    exec.capture(['git', 'tag', seedTag, commit], target.root);
+  return exec.interactive(
+    ['git', 'push', 'origin', `refs/tags/${seedTag}`],
+    target.root
+  );
+}
+
+export async function bootstrap(
+  deps: Deps,
+  target: Target,
+  options: Options
+): Promise<number> {
+  const { exec, log } = deps;
+  let state = measure(exec, target);
+  const steps = plan(state);
+  show(deps, state, steps);
+  if (!npmIsRecent(state.npmVersion)) {
+    log(
+      `npm ${MIN_NPM.join('.')} or newer is required (for "npm trust"). Run: npm install -g npm@latest`
+    );
+    return 1;
+  }
+  const todo = steps.filter((step) => !step.done);
+  if (todo.length === 0) {
+    log('Nothing to do: publishing is bootstrapped.');
+    return 0;
+  }
+  const blocked = todo.find((step) => step.blocked);
+  if (blocked) return 1;
+  if (
+    !options.yes &&
+    !(await deps.ask(`Run ${todo.length} step(s) as listed?`))
+  )
+    return 130;
+  if (todo.some((s) => s.id === 'publish') && !options.skipCheck) {
+    log('Running bun run check before publishing…');
+    if (!exec.interactive(['bun', 'run', 'check'], target.root)) return 1;
+  }
+  for (const step of todo) {
+    log(`→ ${step.title}`);
+    if (!(await run(step.id, deps, target, state))) {
+      log(`✗ ${step.title} failed; run bun run bootstrap again to continue.`);
+      return 1;
+    }
+    state = measure(exec, target);
+  }
+  show(deps, state, plan(state));
+  return plan(state).every((step) => step.done) ? 0 : 1;
+}
+
+async function run(
+  id: StepId,
+  deps: Deps,
+  target: Target,
+  state: State
+): Promise<boolean> {
+  const { exec } = deps;
+  switch (id) {
+    case 'login':
+      return exec.interactive(['npm', 'login', '--auth-type=web']);
+    case 'publish':
+      return deps.seed(target);
+    case 'trust':
+      return exec.interactive([
+        'npm',
+        'trust',
+        'github',
+        target.name,
+        '--repo',
+        target.repo,
+        '--file',
+        WORKFLOW_FILE,
+        '--allow-publish',
+        '--yes',
+      ]);
+    case 'tag':
+      return tagPublished(exec, target, state);
+  }
+}
+
+const system: Exec = {
+  capture(command, cwd) {
+    const result = spawnSync(command[0]!, command.slice(1), {
+      ...(cwd ? { cwd } : {}),
+      encoding: 'utf8',
+    });
+    return {
+      ok: result.status === 0,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    };
+  },
+  interactive(command, cwd) {
+    const result = spawnSync(command[0]!, command.slice(1), {
+      ...(cwd ? { cwd } : {}),
+      stdio: 'inherit',
+    });
+    return result.status === 0;
+  },
+};
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const options: Options = {
+    yes: args.includes('--yes'),
+    skipCheck: args.includes('--skip-check'),
+  };
+  if (!options.yes && !process.stdin.isTTY) {
+    console.error('Not a terminal: pass --yes to run unattended.');
+    process.exit(2);
+  }
+  process.exitCode = await bootstrap(
+    {
+      exec: system,
+      seed: (target) => publishSeed(system, target),
+      log: (line) => console.log(line),
+      ask: (message) => confirm({ message, default: true }),
+    },
+    readTarget(resolve(import.meta.dir, '..')),
+    options
+  );
+}

package/bootstrap/setup-status.ts

@@ -0,0 +1,51 @@
+/** Nonsecret installer evidence; never contains commands, paths or raw errors. */
+import { lstatSync, writeFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+export type SetupPhase =
+  | 'managed-config'
+  | 'mise'
+  | 'aws'
+  | 't3'
+  | 'global-config'
+  | 'shell'
+  | 'dependencies';
+export function setupFailureCode(error: unknown): string | undefined {
+  const known: Record<string, string> = {
+    'Pinned T3 artifact unavailable.': 'T3_DOWNLOAD_UNAVAILABLE',
+    'T3 artifact checksum mismatch.': 'T3_CHECKSUM_MISMATCH',
+    'T3 cached artifact drift; preserve running service and review maintenance recovery.':
+      'T3_CACHE_DRIFT',
+    'T3 extraction failed.': 'T3_EXTRACTION_FAILED',
+    'Managed T3 files differ from the pinned artifact; maintenance is required.':
+      'T3_INSTALLATION_DRIFT',
+    'Pinned T3 executable verification failed.': 'T3_EXECUTABLE_FAILED',
+  };
+  return error instanceof Error && Object.hasOwn(known, error.message)
+    ? known[error.message]
+    : undefined;
+}
+export function setupStatus(path: string | undefined) {
+  if (path && !isAbsolute(path))
+    throw new Error('Setup status path must be absolute.');
+  return (
+    phase: SetupPhase,
+    status: 'running' | 'failed' | 'passed',
+    code?: string
+  ): void => {
+    if (!path) return;
+    try {
+      if (!lstatSync(path).isFile())
+        throw new Error('Unsafe setup status file.');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    writeFileSync(
+      path,
+      JSON.stringify({ version: 1, phase, status, ...(code ? { code } : {}) }) +
+        '\n',
+      {
+        mode: 0o600,
+      }
+    );
+  };
+}

package/bootstrap/setup.ts

@@ -0,0 +1,88 @@
+import { workerTools } from './worker-tools';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Used by both OS bootstraps, dev-fleet tools sync and dev-fleet update. No workspace dependencies. */
+import { setupStatus, setupFailureCode, type SetupPhase } from './setup-status';
+import { spawnSync } from 'node:child_process';
+import {
+  assertManagedConfig,
+  globalConfigDir,
+  publishGlobalConfig,
+  workspaceRoot,
+} from './global-config';
+import { configureShellPath } from './shell-path';
+import { installNativeAws } from './native-aws';
+import { installNativeT3 } from './native-t3';
+
+function run(args: string[]): void {
+  const result = spawnSync(args[0]!, args.slice(1), {
+    cwd: workspaceRoot,
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0)
+    throw new Error(`${args.join(' ')} failed (${result.status})`);
+}
+
+export async function syncTools(
+  observe: (phase: SetupPhase) => void = () => {},
+  worker = false
+): Promise<void> {
+  observe('managed-config');
+  const dir = globalConfigDir();
+  assertManagedConfig(dir);
+  observe('mise');
+  const config = Bun.TOML.parse(
+    readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
+  ) as { tools: Record<string, unknown>; vars: { worker_tools: unknown } };
+  const selected = worker
+    ? Object.keys(workerTools(config.tools, config.vars.worker_tools))
+    : [];
+  run(['mise', 'install', '--locked', ...selected]);
+  observe('aws');
+  if (!worker) await installNativeAws();
+  observe('t3');
+  await installNativeT3();
+  observe('global-config');
+  publishGlobalConfig(dir);
+  run(['mise', 'reshim']);
+  observe('shell');
+  configureShellPath();
+}
+
+if (import.meta.main) {
+  const flag = process.argv.indexOf('--status-file');
+  const report = setupStatus(flag < 0 ? undefined : process.argv[flag + 1]);
+  let phase: SetupPhase = 'managed-config';
+  try {
+    await syncTools((current) => {
+      phase = current;
+      report(phase, 'running');
+    }, process.argv.includes('--worker'));
+    if (!process.argv.includes('--tools-only')) {
+      phase = 'dependencies';
+      report(phase, 'running');
+      run([
+        'mise',
+        'exec',
+        '--locked',
+        '--',
+        'bun',
+        'install',
+        '--frozen-lockfile',
+      ]);
+    }
+    report(phase, 'passed');
+  } catch (error) {
+    report(phase, 'failed', setupFailureCode(error));
+    throw new Error(
+      `Shared toolchain phase ${phase} failed; inspect the declared installer prerequisites and retry.`
+    );
+  }
+  console.log(
+    'Shared toolchain installed globally. Reopen terminals/editors, or refresh this terminal with: exec "$SHELL" -l (Unix).'
+  );
+  console.log(
+    'Verify: mise exec -- bun bootstrap/doctor.ts (add --docker to require a running Docker engine).'
+  );
+}

package/bootstrap/shell-path.ts

@@ -0,0 +1,105 @@
+/** Persistent shims make the same tool commands work in interactive shells and agents. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function appendOnce(path: string, block: string): void {
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (current.includes(block.trim())) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${current}\n${block}\n`);
+}
+
+export function miseDataDir(
+  platform = process.platform,
+  env = process.env,
+  home = homedir()
+): string {
+  const fallback =
+    platform === 'win32'
+      ? env['LOCALAPPDATA'] || join(home, 'AppData', 'Local')
+      : join(home, '.local', 'share');
+  return env['MISE_DATA_DIR'] || join(env['XDG_DATA_HOME'] || fallback, 'mise');
+}
+
+function persistWindowsPath(bin: string, shims: string): void {
+  const script =
+    "$paths = @($env:WORKSPACE_TOOL_SHIMS, $env:WORKSPACE_TOOL_BIN); $old = [Environment]::GetEnvironmentVariable('Path', 'User'); $new = (($paths + ($old -split ';') | Where-Object { $_ } | Select-Object -Unique) -join ';'); [Environment]::SetEnvironmentVariable('Path', $new, 'User')";
+  const result = spawnSync(
+    'powershell.exe',
+    ['-NoProfile', '-Command', script],
+    {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        WORKSPACE_TOOL_BIN: bin,
+        WORKSPACE_TOOL_SHIMS: shims,
+      },
+    }
+  );
+  if (result.status !== 0)
+    throw new Error(
+      'Could not persist the user PATH. See docs/machine-setup.md.'
+    );
+}
+
+export function configurePosixShellPath(
+  bin: string,
+  shims: string,
+  home = homedir(),
+  zdotdir = process.env['ZDOTDIR'] || home
+): void {
+  const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+  const paths = quote(`${shims}:${bin}`);
+  const legacy = `# dev-fleet toolchain\nexport PATH=${paths}:"$PATH"`;
+  const block = `# dev-fleet toolchain\ncase ":$PATH:" in\n  *${quote(`:${shims}:${bin}:`)}*) ;;\n  *) export PATH=${paths}:"$PATH" ;;\nesac`;
+  const targets = new Set([
+    join(home, '.profile'),
+    ...['.bash_profile', '.bash_login']
+      .map((name) => join(home, name))
+      .filter(existsSync),
+    join(home, '.bashrc'),
+    join(zdotdir, '.zshenv'),
+    join(zdotdir, '.zshrc'),
+  ]);
+  // Version managers and vendor installers (nvm, a native Claude installer's
+  // ~/.local/bin) prepend their own directories later in these files; the
+  // last line puts the pinned shims back in front, so every shell and the
+  // apps that inherit its PATH (T3) run the locked tool versions.
+  // Guarded like the block above so nested shells do not grow PATH.
+  const unguarded = `${TAIL_MARKER}\nexport PATH=${quote(shims)}:"$PATH"\n`;
+  const tail = `${TAIL_MARKER}\ncase "$PATH" in\n  ${quote(shims)}:*) ;;\n  *) export PATH=${quote(shims)}:"$PATH" ;;\nesac\n`;
+  for (const path of targets) {
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const body = current
+      .replace(`${block}\n`, '')
+      .replace(legacy, '')
+      .split(tail)
+      .join('')
+      .split(unguarded)
+      .join('');
+    const next = `${block}\n${body.replace(/\n*$/, '\n')}${tail}`;
+    if (next === current) continue;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+  }
+}
+
+const TAIL_MARKER = '# pinned tool shims first (dev-fleet, keep this last)';
+
+export function configureShellPath(): void {
+  const bin = join(homedir(), '.local', 'bin');
+  const shims = process.env['MISE_SHIMS_DIR'] || join(miseDataDir(), 'shims');
+  if (process.platform === 'win32') {
+    persistWindowsPath(bin, shims);
+    return;
+  }
+  configurePosixShellPath(bin, shims);
+  const fishQuote = (value: string) =>
+    `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+  appendOnce(
+    join(homedir(), '.config/fish/config.fish'),
+    `# dev-fleet toolchain\nfish_add_path --prepend ${fishQuote(shims)} ${fishQuote(bin)}`
+  );
+}

package/bootstrap/verify-t3-archive.py

@@ -0,0 +1,49 @@
+"""Verify the pinned T3 archive against its user-owned installation.
+
+Release-builder numeric identities are not portable. All installed members must
+instead belong to the invoking development user; content, modes and links must
+still match. This reads the archive and installation without modifying either.
+"""
+import os
+from pathlib import Path
+import stat
+import sys
+import tarfile
+
+
+def verify(archive, root):
+    root = Path(root).resolve()
+    with tarfile.open(archive, 'r:gz') as source:
+        for member in source:
+            path = root / member.name
+            if not path.parent.resolve().is_relative_to(root):
+                return False
+            observed = path.lstat()
+            if observed.st_uid != os.getuid():
+                return False
+            if member.issym():
+                if not stat.S_ISLNK(observed.st_mode) or os.readlink(path) != member.linkname:
+                    return False
+            elif member.isdir():
+                if not stat.S_ISDIR(observed.st_mode):
+                    return False
+            elif member.isfile():
+                if not stat.S_ISREG(observed.st_mode) or observed.st_size != member.size:
+                    return False
+                if stat.S_IMODE(observed.st_mode) != member.mode:
+                    return False
+                with source.extractfile(member) as expected, path.open('rb') as actual:
+                    while chunk := expected.read(1024 * 1024):
+                        if actual.read(len(chunk)) != chunk:
+                            return False
+            else:
+                return False
+    return True
+
+
+if __name__ == '__main__':
+    try:
+        valid = verify(sys.argv[1], sys.argv[2])
+    except (OSError, ValueError, tarfile.TarError):
+        valid = False
+    sys.exit(0 if valid else 1)