@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/bootstrap/npm.ts

@@ -0,0 +1,358 @@
+/**
+ * `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`,
+      // 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,
+    },
+  ];
+}
+
+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;
+    // 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, gitHead }, 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/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}`);
+  }
+}

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).'
+  );
+}