@ultimat3/cli 29.3.2 → 30.0.0

package/src/upgrade-bun-floor.ts

@@ -0,0 +1,225 @@
+// The Bun floor, as a plain text edit per pin site: `engines.bun`, `.bun-version`, `packageManager`,
+// `setup-bun`, `oven/bun:` tags. Pure over one file's text. Text and not a parse, because the rest of
+// the file is the author's to the byte. A site is only ever raised; one this cannot read is listed.
+
+// why: Bun exposes no basename primitive.
+import { basename } from 'node:path';
+
+export interface BunEdit {
+  readonly path: string;
+  readonly site: string;
+  readonly from: string;
+  readonly to: string;
+}
+
+/** A site only its author can move, with the line to open and why. */
+export interface BunManual {
+  readonly path: string;
+  readonly line: number;
+  readonly text: string;
+  readonly why: string;
+}
+
+export interface BunFileEdit {
+  readonly text: string;
+  readonly edited: readonly BunEdit[];
+  readonly manual: readonly BunManual[];
+}
+
+const DOCKERFILE = /^(?:Dockerfile(?:\..+)?|.+\.[Dd]ockerfile)$/;
+const YAML = /\.ya?ml$/;
+const VERSION_TEXT = /\d+\.\d+(?:\.\d+)?/;
+
+const isPackageManifest = (name: string): boolean => name === 'package.json';
+
+/** Whether a tracked path can hold a pin site at all. */
+export const isBunSite = (path: string): boolean => {
+  const name = basename(path);
+  return (
+    name === '.bun-version' || isPackageManifest(name) || YAML.test(name) || DOCKERFILE.test(name)
+  );
+};
+
+/** The version in an `engines.bun` range, or undefined for one that names none. */
+export const floorOf = (range: string | undefined): string | undefined =>
+  range === undefined ? undefined : VERSION_TEXT.exec(range)?.[0];
+
+const numbers = (version: string): readonly number[] => version.split('.').map(Number);
+
+/** Below the floor, read at the version's own precision: `1.4` floats, so it reaches `1.4.4`. */
+const isBelow = (version: string, floor: string): boolean => {
+  const held = numbers(version);
+  const wanted = numbers(floor);
+  for (let at = 0; at < held.length; at += 1) {
+    const left = held[at] ?? 0;
+    const right = wanted[at] ?? 0;
+    if (left !== right) return left < right;
+  }
+  return false;
+};
+
+/** The floor at the version's precision, so `1.3-alpine` becomes `1.4-alpine` and still floats. */
+const atPrecision = (version: string, floor: string): string =>
+  floor.split('.').slice(0, version.split('.').length).join('.');
+
+/** A range's version is its lower bound, never a floating tag: `>=1.4` admits 1.4.0. */
+const lowerBound = (version: string): string =>
+  [...version.split('.'), '0', '0'].slice(0, 3).join('.');
+
+const lineAt = (text: string, offset: number): number => text.slice(0, offset).split('\n').length;
+
+/** One comparator over one version: the only range a raise cannot turn into a different claim. */
+const PLAIN_RANGE = /^(?:>=|\^|~)?\s*\d+\.\d+(?:\.\d+)?$/;
+const EXACT = /^\d+\.\d+\.\d+$/;
+
+const BY_HAND = (floor: string): string =>
+  `this spelling cannot be raised by a text edit: set it to Bun ${floor} or above`;
+
+const editManifest = (path: string, source: string, floor: string): BunFileEdit => {
+  const edited: BunEdit[] = [];
+  const manual: BunManual[] = [];
+  const listed = (offset: number, text: string): void => {
+    manual.push({ path, line: lineAt(source, offset), text, why: BY_HAND(floor) });
+  };
+  let text = source.replace(
+    /("engines"\s*:\s*\{[^}]*?"bun"\s*:\s*")([^"]*)(")/,
+    (whole, head: string, range: string, tail: string, offset: number) => {
+      const version = floorOf(range);
+      if (version === undefined || !isBelow(lowerBound(version), floor)) return whole;
+      if (!PLAIN_RANGE.test(range)) {
+        listed(offset + head.length, `"bun": "${range}"`);
+        return whole;
+      }
+      const to = range.replace(version, floor);
+      edited.push({ path, site: 'engines.bun', from: range, to });
+      return `${head}${to}${tail}`;
+    },
+  );
+  // Offsets into `source`: the `engines` edit above can only move a later offset by a few bytes, and
+  // never across a line.
+  text = text.replace(
+    /("packageManager"\s*:\s*"bun@)([^"]*)(")/,
+    (whole, head: string, value: string, tail: string, offset: number) => {
+      const version = floorOf(value);
+      if (version === undefined || !isBelow(version, floor)) return whole;
+      if (!EXACT.test(value)) {
+        listed(offset + head.length, `"packageManager": "bun@${value}"`);
+        return whole;
+      }
+      edited.push({ path, site: 'packageManager', from: value, to: floor });
+      return `${head}${floor}${tail}`;
+    },
+  );
+  return { text, edited, manual };
+};
+
+const editVersionFile = (path: string, source: string, floor: string): BunFileEdit => {
+  const value = source.trim();
+  const version = floorOf(value);
+  if (version === undefined || !isBelow(version, floor)) {
+    return { text: source, edited: [], manual: [] };
+  }
+  if (!EXACT.test(value)) {
+    return {
+      text: source,
+      edited: [],
+      manual: [{ path, line: 1, text: value, why: BY_HAND(floor) }],
+    };
+  }
+  return {
+    text: source.replace(value, floor),
+    edited: [{ path, site: '.bun-version', from: value, to: floor }],
+    manual: [],
+  };
+};
+
+const BUN_VERSION_KEY = /^(\s*(?:-\s*)?bun-version:\s*)(['"]?)([^'"\s#][^'"#]*?)\2(\s*(?:#.*)?)$/;
+const IMAGE = /oven\/bun:([^\s'"@]+)(@sha256:[0-9a-f]+)?/;
+/** A suffix is a Docker variant (`-alpine`): `1.3.x` is no version with a suffix. */
+const TAG = /^(\d+\.\d+(?:\.\d+)?)(-.*)?$/;
+
+/** One line of a YAML file or Dockerfile: the edited text, and what it had to report. */
+function editLine(input: {
+  readonly path: string;
+  readonly line: string;
+  readonly number: number;
+  readonly floor: string;
+  readonly edited: BunEdit[];
+  readonly manual: BunManual[];
+}): string {
+  const { path, line, number, floor, edited, manual } = input;
+  // Prose: a Dockerfile's header names the digest it pins, and rewriting that lies about the file.
+  if (line.trimStart().startsWith('#')) return line;
+  const listed = (why: string): string => {
+    manual.push({ path, line: number, text: line.trim(), why });
+    return line;
+  };
+  const belowInSomeSpelling = (value: string): boolean => {
+    const version = floorOf(value);
+    return version !== undefined && isBelow(version, floor);
+  };
+
+  const key = BUN_VERSION_KEY.exec(line);
+  if (key !== null) {
+    const [, head = '', quote = '', value = '', tail = ''] = key;
+    if (value.includes('$')) {
+      return listed('the version is an expression: edit where it is defined');
+    }
+    if (!/^\d+\.\d+(?:\.\d+)?$/.test(value)) {
+      return belowInSomeSpelling(value) ? listed(BY_HAND(floor)) : line;
+    }
+    if (!isBelow(value, floor)) return line;
+    const to = atPrecision(value, floor);
+    edited.push({ path, site: 'setup-bun', from: value, to });
+    return `${head}${quote}${to}${quote}${tail}`;
+  }
+
+  const image = IMAGE.exec(line);
+  if (image === null) return line;
+  const [whole, tag = '', digest] = image;
+  if (tag.includes('$')) return listed('the tag is a variable: edit where it is defined');
+  const parts = TAG.exec(tag);
+  const version = parts?.[1];
+  if (digest !== undefined) {
+    const inspect = `by hand (docker buildx imagetools inspect oven/bun:${floor}-alpine)`;
+    if (version === undefined || isBelow(version, floor)) {
+      return listed(
+        `a digest pins this image: move the tag and digest together to oven/bun:${floor}'s, ${inspect}`,
+      );
+    }
+    // `1.4-alpine@sha256:…` at a 1.4.4 floor: the tag reaches it and the digest may not, and which
+    // patch a digest holds is not on this line. `1.4.4-alpine@…` and `1.5-alpine@…` say enough.
+    return version === atPrecision(version, floor) && version.split('.').length < 3
+      ? listed(
+          `a digest pins a floating tag, so its patch cannot be read here: confirm it is ${floor} or above, ${inspect}`,
+        )
+      : line;
+  }
+  if (version === undefined) return belowInSomeSpelling(tag) ? listed(BY_HAND(floor)) : line;
+  if (!isBelow(version, floor)) return line;
+  const to = atPrecision(version, floor);
+  const suffix = parts?.[2] ?? '';
+  edited.push({ path, site: 'oven/bun', from: tag, to: `${to}${suffix}` });
+  return line.replace(whole, `oven/bun:${to}${suffix}`);
+}
+
+const editLines = (path: string, source: string, floor: string): BunFileEdit => {
+  const edited: BunEdit[] = [];
+  const manual: BunManual[] = [];
+  // Split on `\n` alone, so a CRLF file's `\r` goes through its line untouched — except that a `$`
+  // anchor needs it gone, so it is lifted off and put back.
+  const lines = source.split('\n').map((raw, index) => {
+    const cr = raw.endsWith('\r') ? '\r' : '';
+    const line = cr === '' ? raw : raw.slice(0, -1);
+    return `${editLine({ path, line, number: index + 1, floor, edited, manual })}${cr}`;
+  });
+  return { text: lines.join('\n'), edited, manual };
+};
+
+/** One file's sites raised to `floor`. Run twice, the second run changes nothing. */
+export function editBunSites(path: string, source: string, floor: string): BunFileEdit {
+  const name = basename(path);
+  if (name === '.bun-version') return editVersionFile(path, source, floor);
+  if (isPackageManifest(name)) return editManifest(path, source, floor);
+  return editLines(path, source, floor);
+}

package/src/upgrade-gate.ts

@@ -0,0 +1,228 @@
+// A hop's gate, run by the CLI the hop just installed: `x manifest`, `x doctor --json`, `x verify
+// --json`. Never in this process, because the installed CLI is the one that knows the installed
+// framework (`local-cli.ts`), and it may be many majors older than this one: each answer is read as
+// a foreign document, and one that will not parse is a finding, never a green.
+
+// why: Bun exposes no path-join primitive; the installed bin is assembled from the app root.
+import { join } from 'node:path';
+import { t } from '@ultimat3/schema';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import { LOCAL_CLI_BIN } from './local-cli';
+import { parseJson } from './upgrade-registry';
+
+const FINDING = t.object({
+  code: t.string,
+  cause: t.string,
+  fix: t.string,
+  at: t.optional(t.string),
+});
+const STEP = t.object({ name: t.string, ok: t.boolean, findings: t.optional(t.array(FINDING)) });
+const VERIFY = t.object({
+  ok: t.boolean,
+  summary: t.string,
+  steps: t.optional(t.array(STEP)),
+  findings: t.optional(t.array(FINDING)),
+});
+const MANIFEST = t.object({ ok: t.boolean, findings: t.optional(t.array(FINDING)) });
+const REPO_MANIFEST = t.object({ scripts: t.optional(t.record(t.string)) });
+const GUARD_MISSING = t.object({ name: t.string, add: t.string });
+const GUARD_DIFFERS = t.object({ name: t.string, refresh: t.string });
+const DOCTOR = t.object({
+  data: t.optional(
+    t.object({
+      guards: t.optional(
+        t.object({
+          missing: t.optional(t.array(GUARD_MISSING)),
+          differs: t.optional(t.array(GUARD_DIFFERS)),
+        }),
+      ),
+    }),
+  ),
+});
+
+export interface GateFinding {
+  /** The gate step that raised it; absent for one raised outside any step. */
+  readonly step?: string;
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly at?: string;
+}
+
+interface RawFinding {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly at?: string;
+}
+
+interface VerifyDocument {
+  readonly ok: boolean;
+  readonly summary: string;
+  readonly steps?: readonly {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly findings?: readonly RawFinding[];
+  }[];
+  readonly findings?: readonly RawFinding[];
+}
+
+interface DoctorDocument {
+  readonly data?: {
+    readonly guards?: {
+      readonly missing?: readonly { readonly name: string; readonly add: string }[];
+      readonly differs?: readonly { readonly name: string; readonly refresh: string }[];
+    };
+  };
+}
+
+export interface HopGuards {
+  /** False when the hop's `x doctor` predates the listing: unknown, which is not the same as none. */
+  readonly reported: boolean;
+  readonly missing: readonly { readonly name: string; readonly add: string }[];
+  readonly differs: readonly { readonly name: string; readonly refresh: string }[];
+}
+
+export interface HopGate {
+  readonly manifest: { readonly ok: boolean; readonly findings: readonly GateFinding[] };
+  readonly guards: HopGuards;
+  readonly verify: {
+    readonly ok: boolean;
+    readonly summary: string;
+    /** The steps that went red, whether or not they carried a finding. */
+    readonly failed: readonly string[];
+    readonly findings: readonly GateFinding[];
+  };
+}
+
+/**
+ * The one JSON document on a child's stdout. Whole first; then its last line that parses, because
+ * the CLI that keeps fd 1 to one document under `--json` is a recent one and a hop can install one
+ * that still logs a boot line ahead of it.
+ */
+export function documentIn(stdout: string): unknown {
+  const whole = parseJson(stdout.trim());
+  if (whole !== undefined) return whole;
+  const lines = stdout.split('\n').filter((line) => line.trimStart().startsWith('{'));
+  return lines
+    .reverse()
+    .map(parseJson)
+    .find((parsed) => parsed !== undefined);
+}
+
+const flatten = (document: {
+  readonly steps?: VerifyDocument['steps'];
+  readonly findings?: readonly RawFinding[];
+}): readonly GateFinding[] => [
+  ...(document.steps ?? []).flatMap((step) =>
+    (step.findings ?? []).map((finding) => ({ step: step.name, ...pick(finding) })),
+  ),
+  ...(document.findings ?? []).map(pick),
+];
+
+/** Named fields only: a finding's `meta` carries structures this report promises nothing about. */
+const pick = (finding: RawFinding): RawFinding => ({
+  code: finding.code,
+  cause: finding.cause,
+  fix: finding.fix,
+  ...(finding.at === undefined ? {} : { at: finding.at }),
+});
+
+const INSTALLED_VERIFY = `bun ${LOCAL_CLI_BIN.replaceAll('\\', '/')} verify --json`;
+
+const unreadable = (result: ExecResult): GateFinding => ({
+  code: 'X_UPGRADE_GATE_UNREADABLE',
+  cause: `${result.command.slice(2).join(' ')} exited ${String(result.code)} with no JSON report: ${execOutput(result).slice(-800) || 'no output'}`,
+  fix: INSTALLED_VERIFY,
+});
+
+const readVerify = (result: ExecResult): HopGate['verify'] => {
+  const parsed = VERIFY.safeParse(documentIn(result.stdout));
+  if (parsed.issues !== undefined) {
+    return {
+      ok: false,
+      summary: `x verify exited ${String(result.code)} with no JSON report`,
+      failed: [],
+      findings: [unreadable(result)],
+    };
+  }
+  const document = parsed.value as VerifyDocument;
+  return {
+    // Both have to say so: an exit code of 1 under a document saying `ok` is not a verdict to round up.
+    ok: result.ok && document.ok,
+    summary: document.summary,
+    failed: (document.steps ?? []).filter((step) => !step.ok).map((step) => step.name),
+    findings: flatten(document),
+  };
+};
+
+const readManifest = (result: ExecResult): HopGate['manifest'] => {
+  const parsed = MANIFEST.safeParse(documentIn(result.stdout));
+  if (parsed.issues !== undefined) return { ok: false, findings: [unreadable(result)] };
+  const document = parsed.value as { readonly findings?: readonly RawFinding[] };
+  return { ok: result.ok, findings: flatten(document) };
+};
+
+/** A doctor that exits red is normal (a port, an env key); only its listing is read here. */
+const readGuards = (result: ExecResult): HopGuards => {
+  const parsed = DOCTOR.safeParse(documentIn(result.stdout));
+  const guards =
+    parsed.issues === undefined ? (parsed.value as DoctorDocument).data?.guards : undefined;
+  if (guards === undefined) return { reported: false, missing: [], differs: [] };
+  return { reported: true, missing: guards.missing ?? [], differs: guards.differs ?? [] };
+};
+
+/** The three, in order, each told apart by `onStage` so a long gate is not a long silence. */
+export async function runHopGate(input: {
+  readonly runner: Runner;
+  readonly root: string;
+  readonly onStage: (stage: 'manifest' | 'doctor' | 'verify') => void;
+}): Promise<HopGate> {
+  const { runner, root, onStage } = input;
+  const installed = (args: readonly string[]): Promise<ExecResult> =>
+    runner([process.execPath, join(root, LOCAL_CLI_BIN), ...args], { cwd: root });
+  onStage('manifest');
+  const manifest = readManifest(await installed(['manifest', '--json']));
+  onStage('doctor');
+  const guards = readGuards(await installed(['doctor', '--json']));
+  onStage('verify');
+  const verify = readVerify(await installed(['verify', '--json']));
+  return { manifest, guards, verify };
+}
+
+/** What a repository with no app can still be asked, in the order an author would run them. */
+const REPO_SCRIPTS = ['typecheck', 'test'] as const;
+
+export interface RepoScript {
+  readonly name: string;
+  /** Null when named and not run: a dry run. */
+  readonly ok: boolean | null;
+  readonly code?: number;
+  readonly output?: string;
+}
+
+/** The ones this manifest declares. Read as JSON only after `readManifests` has already parsed it. */
+export function repoScripts(manifestText: string): readonly string[] {
+  const parsed = REPO_MANIFEST.safeParse(parseJson(manifestText));
+  if (parsed.issues !== undefined) return [];
+  const declared = (parsed.value as { readonly scripts?: Readonly<Record<string, string>> })
+    .scripts;
+  return REPO_SCRIPTS.filter((name) => declared !== undefined && Object.hasOwn(declared, name));
+}
+
+/** Each declared script, one after the other, red or not: the report owes every answer. */
+export async function runRepoScripts(input: {
+  readonly runner: Runner;
+  readonly root: string;
+  readonly names: readonly string[];
+  readonly onStage: (stage: string) => void;
+}): Promise<readonly RepoScript[]> {
+  const ran: RepoScript[] = [];
+  for (const name of input.names) {
+    input.onStage(name);
+    const result = await input.runner([process.execPath, 'run', name], { cwd: input.root });
+    ran.push({ name, ok: result.ok, code: result.code, output: execOutput(result).slice(-800) });
+  }
+  return ran;
+}

package/src/upgrade-pins.ts

@@ -0,0 +1,63 @@
+// Where an app's `@ultimat3/*` pins live: the root manifest and every workspace's. Reading and writing
+// go through one pattern, so the set the plan judged is the set the hop moves — `overrides` and
+// `resolutions` included, since an override left behind holds the old version in place.
+
+// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
+import { join } from 'node:path';
+import { UltimateError } from '@ultimat3/core';
+import { pinVersion, type UpgradePin } from './upgrade-plan';
+import { workspaceGlobs, workspaceManifestPaths } from './workspace-graph';
+
+const ROOT_MANIFEST = 'package.json';
+
+export interface WorkspaceManifest {
+  /** Relative to the app root, POSIX. */
+  readonly file: string;
+  readonly text: string;
+}
+
+const PIN_ENTRY = /("(@ultimat3\/[a-z0-9-]+)"\s*:\s*")([^"]*)(")/g;
+
+/** A manifest's JSON, or X_UPGRADE_PIN_UNREADABLE naming the file: never a raw SyntaxError. */
+export const parseManifest = (file: string, text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new UltimateError({
+      code: 'X_UPGRADE_PIN_UNREADABLE',
+      cause: `${file} is not valid JSON, so its @ultimat3/* pins cannot be read`,
+      fix: `bun install   # names the line in ${file} to repair; then: x upgrade --json`,
+    });
+  }
+};
+
+/** The root manifest and every workspace's, read once, as text: the hop edits the text. */
+export async function readManifests(root: string): Promise<readonly WorkspaceManifest[]> {
+  const rootText = await Bun.file(join(root, ROOT_MANIFEST)).text();
+  const files = await workspaceManifestPaths(
+    root,
+    workspaceGlobs(parseManifest(ROOT_MANIFEST, rootText)),
+  );
+  const members = await Promise.all(
+    files
+      .filter((file) => file !== ROOT_MANIFEST)
+      .map(async (file) => ({ file, text: await Bun.file(join(root, file)).text() })),
+  );
+  return [{ file: ROOT_MANIFEST, text: rootText }, ...members];
+}
+
+export function readPins(manifests: readonly WorkspaceManifest[]): readonly UpgradePin[] {
+  return manifests.flatMap(({ file, text }) =>
+    [...text.matchAll(PIN_ENTRY)].map(([, , name = '', spec = '']) => ({ file, name, spec })),
+  );
+}
+
+/**
+ * Every pin at the exact version, the rest of the file byte-identical. Exact whatever it was: a
+ * caret is how `^19.0.0` beside `^19.4.0` came to be mixed, and a range is a silent upgrade.
+ * A spec naming no version never reaches here (`planHop` refused it), and is left as written.
+ */
+export const rewritePins = (text: string, to: string): string =>
+  text.replace(PIN_ENTRY, (whole, head: string, _name: string, spec: string, tail: string) =>
+    pinVersion(spec) === undefined ? whole : `${head}${to}${tail}`,
+  );