@erclx/aitk 0.109.0 → 0.111.0

package/src/commands/upgrade.ts

@@ -0,0 +1,231 @@
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { PROJECT_ROOT } from '@/project-root'
+import {
+  frameError,
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+import { detectManager, installCommand, type Manager } from '@/version/manager'
+import {
+  describeSkew,
+  latestOf,
+  readSkew,
+  type SkewReport,
+} from '@/version/skew'
+
+interface UpgradeOptions {
+  readonly json?: boolean
+}
+
+interface UpgradeRecord {
+  readonly root: string
+  readonly manager?: string
+  readonly command?: string
+  readonly before: string
+  readonly after?: string
+  readonly latest?: string
+  readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
+  readonly reason?: string
+}
+
+export function register(program: Command): void {
+  program
+    .command('upgrade')
+    .description(
+      'Reinstall the CLI globally with whichever package manager installed it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the binary is current, the reinstall completed, or it was cancelled',
+        '  1  refused or the reinstall failed, with the reason on stderr',
+        '',
+        'The package manager is read off the install path rather than guessed',
+        'from PATH, and named before anything runs. A source checkout matches no',
+        'install tree and is refused rather than reinstalled over.',
+        '',
+        'Examples:',
+        '  aitk upgrade',
+        '  aitk upgrade --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: UpgradeOptions) => {
+      process.exitCode = await runUpgrade(opts)
+    })
+}
+
+/**
+ * Detection runs before the registry lookup so the one case that cannot upgrade
+ * at all, a source checkout, refuses without waiting on a network call whose
+ * answer it would then discard.
+ */
+async function runUpgrade(opts: UpgradeOptions): Promise<number> {
+  const installed = readInstalled()
+  const before = installed.version ?? UNKNOWN_LABEL
+
+  intro('aitk upgrade')
+  logStep('Installed')
+  logInfo(`${installed.name ?? UNKNOWN_LABEL} ${before}`)
+  logInfo(PROJECT_ROOT)
+
+  const manager = detectManager(PROJECT_ROOT)
+  if (manager === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package manager owns ${PROJECT_ROOT}. A source checkout is upgraded by pulling, not by reinstalling over it.`,
+    )
+  }
+
+  // A manifest that did not parse, or carried no `name`, would otherwise reach
+  // `installCommand` and produce a global install of whatever sits under that
+  // placeholder on the registry. The prompt below defaults to yes headlessly,
+  // so nothing downstream would stop it.
+  if (installed.name === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package name in ${PROJECT_ROOT}/package.json, so there is nothing safe to reinstall. Repair the manifest, or reinstall by name yourself.`,
+      manager,
+    )
+  }
+
+  const command = installCommand(manager.id, installed.name)
+  logStep('Detected')
+  logInfo(`${manager.id}, from the \`${manager.evidence}\` path segment`)
+  logInfo(command.join(' '))
+
+  const skew = await readSkew({ installed })
+  logStep('Published')
+  logInfo(describeSkew(skew))
+
+  if (skew.state === 'current') {
+    outro()
+    emit(opts, {
+      ...base(before, manager, command, skew),
+      after: before,
+      state: 'current',
+    })
+    return 0
+  }
+
+  return await applyUpgrade(opts, before, skew, manager, command)
+}
+
+/**
+ * Runs the reinstall and reads the version back off disk rather than trusting
+ * the manager's own report, since each spells success differently and one of
+ * them exits zero on a no-op. The read is the same `package.json` the CLI names
+ * on `--version`, which the install has overwritten by this point.
+ *
+ * An `unknown` skew reaches here rather than stopping. The operator asked for
+ * the reinstall, and the manager reports its own network failure in terms the
+ * dist-tag endpoint cannot.
+ */
+async function applyUpgrade(
+  opts: UpgradeOptions,
+  before: string,
+  skew: SkewReport,
+  manager: Manager,
+  command: readonly string[],
+): Promise<number> {
+  const proceed = await select({
+    message: `Run \`${command.join(' ')}\`?`,
+    options: [
+      { value: true, label: 'Upgrade' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!proceed) {
+    logWarn('Cancelled')
+    outro()
+    emit(opts, { ...base(before, manager, command, skew), state: 'cancelled' })
+    return 0
+  }
+
+  logStep('Upgrading')
+  const [bin, ...args] = command
+  // The manager's own progress goes to stderr with the rest of the UI, leaving
+  // stdout carrying nothing but the record. Inheriting all three streams would
+  // put npm's output ahead of the JSON and break every wrapper parsing it.
+  const result = await execa(bin, args, {
+    reject: false,
+    stdin: 'inherit',
+    stdout: process.stderr,
+    stderr: 'inherit',
+  })
+
+  if (result.exitCode !== 0) {
+    return refuse(
+      opts,
+      before,
+      `\`${command.join(' ')}\` exited ${result.exitCode}. Run it yourself to read what it reported.`,
+      manager,
+    )
+  }
+
+  const after = readInstalled().version ?? UNKNOWN_LABEL
+  logStep('Installed')
+  logInfo(after === before ? `${after}, unchanged` : `${before} to ${after}`)
+  outro()
+
+  emit(opts, {
+    ...base(before, manager, command, skew),
+    after,
+    state: 'upgraded',
+  })
+  return 0
+}
+
+function base(
+  before: string,
+  manager: Manager,
+  command: readonly string[],
+  skew: SkewReport,
+): Omit<UpgradeRecord, 'state'> {
+  const latest = latestOf(skew)
+
+  return {
+    root: PROJECT_ROOT,
+    manager: manager.id,
+    command: command.join(' '),
+    before,
+    ...(latest === undefined ? {} : { latest }),
+  }
+}
+
+function refuse(
+  opts: UpgradeOptions,
+  before: string,
+  reason: string,
+  manager?: Manager,
+): number {
+  outro()
+  frameError(reason)
+  emit(opts, {
+    root: PROJECT_ROOT,
+    ...(manager === undefined ? {} : { manager: manager.id }),
+    before,
+    state: 'refused',
+    reason,
+  })
+  return 1
+}
+
+function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
+  if (opts.json !== true) return
+  process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/sync/check.ts

@@ -27,6 +27,7 @@ import { createStandardsAdapter } from '@/standards/adapter'
 import { isDirectory } from '@/target'
 import { loadManifest } from '@/tooling/manifest'
 import { scan } from '@/tooling/scan'
+import { readSkew, type SkewReport } from '@/version/skew'
 
 /**
  * Domains the sync engine walks file by file. Tooling is a stamp domain without
@@ -163,6 +164,17 @@ export interface CheckReport {
    * the same question correctly. See `@/sync/reverse`.
    */
   readonly reverse: ReverseReport
+  /**
+   * The binary running the check, not the target. It reports on an unmanaged
+   * target too, since a reader told to run `aitk init` is better off knowing
+   * first whether the binary about to install is the current one.
+   *
+   * `hasDrift` deliberately ignores it. A registry lookup inside a check that
+   * gates would fail CI on an offline machine for a condition the check never
+   * measured, and the state reaching the reader is the point rather than the
+   * exit code.
+   */
+  readonly skew: SkewReport
 }
 
 export function installedStampDomains(target: string): ScannedDomain[] {
@@ -300,6 +312,10 @@ export async function buildCheckReport(
 ): Promise<CheckReport> {
   const stamp = readStamp(target)
 
+  // Started before the local scan and awaited after it, so the network wait
+  // overlaps work the report needs anyway rather than adding to it.
+  const skewRead = readSkew()
+
   const domains = await Promise.all(
     installedStampDomains(target).map((domain) =>
       buildDomainReport(toolkitRoot, target, stamp, domain),
@@ -324,6 +340,7 @@ export async function buildCheckReport(
       unmigrated: [],
       newSkills: [],
       reverse: emptyReverseReport(),
+      skew: await skewRead,
     }
   }
 
@@ -337,6 +354,7 @@ export async function buildCheckReport(
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
     reverse: buildReverseReport(toolkitRoot, target),
+    skew: await skewRead,
   }
 }
 

package/src/version/compare.ts

@@ -0,0 +1,53 @@
+/**
+ * A `major.minor.patch` core with an optional prerelease tail. The registry
+ * publishes both shapes under the same dist tag, so a comparison that only
+ * understood the core would read `1.0.0-rc.1` as unparseable and report the
+ * whole lookup as unknown.
+ */
+const VERSION =
+  /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+export interface ParsedVersion {
+  readonly major: number
+  readonly minor: number
+  readonly patch: number
+  /** Absent on a release, which sorts above every prerelease of the same core. */
+  readonly prerelease?: string
+}
+
+export function parseVersion(raw: string): ParsedVersion | undefined {
+  const match = VERSION.exec(raw.trim())
+  if (match === null) return undefined
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    ...(match[4] === undefined ? {} : { prerelease: match[4] }),
+  }
+}
+
+/**
+ * Negative when `left` is older, positive when it is newer, zero when the two
+ * name the same version.
+ *
+ * Prerelease identifiers compare as whole strings rather than dot segment by
+ * dot segment, which is narrower than semver states. Every version this repo
+ * publishes is a plain core, so the ordering inside a prerelease series decides
+ * nothing here, and the one comparison that matters is that any prerelease
+ * sorts below the release sharing its core.
+ */
+export function compareVersions(
+  left: ParsedVersion,
+  right: ParsedVersion,
+): number {
+  if (left.major !== right.major) return left.major - right.major
+  if (left.minor !== right.minor) return left.minor - right.minor
+  if (left.patch !== right.patch) return left.patch - right.patch
+
+  if (left.prerelease === right.prerelease) return 0
+  if (left.prerelease === undefined) return 1
+  if (right.prerelease === undefined) return -1
+
+  return left.prerelease < right.prerelease ? -1 : 1
+}

package/src/version/installed.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+
+/** What a reader prints in place of a field the manifest did not carry. */
+export const UNKNOWN_LABEL = 'unknown'
+
+/**
+ * Either field is absent when the manifest could not be read or did not carry
+ * it. They are optional rather than sentinel strings so a caller has to narrow
+ * before using one, which is what makes a name the manifest never supplied
+ * impossible to interpolate into a shell command. A sentinel typed `string`
+ * reads as an ordinary value at every call site and hides that case.
+ */
+export interface InstalledPackage {
+  readonly name?: string
+  readonly version?: string
+}
+
+/**
+ * Read at runtime rather than inlined, because a literal is a second place the
+ * version lives and it stopped tracking `package.json` at `0.1.0`. The release
+ * tool writes one file and this follows it. `package.json` ships in every npm
+ * tarball regardless of the `files` list, so the read resolves from a registry
+ * install as well as from a clone.
+ *
+ * This sits apart from the skew read so `src/cli.ts` can name the version on
+ * every invocation without pulling the registry lookup into the startup import
+ * graph of a CLI that compiles nothing ahead of time.
+ */
+export function readInstalled(root: string = PROJECT_ROOT): InstalledPackage {
+  try {
+    const raw = readFileSync(join(root, 'package.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { name?: string; version?: string }
+
+    return { name: parsed.name, version: parsed.version }
+  } catch {
+    return {}
+  }
+}

package/src/version/manager.ts

@@ -0,0 +1,67 @@
+export type ManagerId = 'bun' | 'pnpm' | 'yarn' | 'npm'
+
+export interface Manager {
+  readonly id: ManagerId
+  /** The path segment the detection matched, so a wrong read is correctable. */
+  readonly evidence: string
+}
+
+/**
+ * Segments that only appear in one manager's global install tree, checked
+ * before the `node_modules` fallback because every one of these trees contains
+ * a `node_modules` too.
+ */
+const SIGNATURES: readonly (readonly [ManagerId, string])[] = [
+  ['bun', '.bun'],
+  ['pnpm', 'pnpm'],
+  ['pnpm', '.pnpm'],
+  ['yarn', 'yarn'],
+  ['yarn', '.yarn'],
+]
+
+/**
+ * Which package manager installed the package rooted at `root`, read off the
+ * install path rather than guessed from what is on `PATH`.
+ *
+ * Removing the guess is the whole case for the upgrade verb, so a detection
+ * that cannot be read back is worth no more than the guess it replaced. The
+ * evidence travels with the answer and the verb prints it before running
+ * anything, which lets an operator correct a wrong read without the detection
+ * having to be right every time.
+ *
+ * Returns `undefined` for a path outside any install tree, which is a source
+ * checkout. That is not a case to guess at either: reinstalling over a clone
+ * would replace what the operator is working in.
+ */
+export function detectManager(root: string): Manager | undefined {
+  const segments = root.split(/[/\\]/).filter((segment) => segment !== '')
+
+  for (const [id, signature] of SIGNATURES) {
+    if (segments.includes(signature)) return { id, evidence: signature }
+  }
+
+  if (segments.includes('node_modules')) {
+    return { id: 'npm', evidence: 'node_modules' }
+  }
+
+  return undefined
+}
+
+/** The global reinstall each manager spells, pinned to the newest published. */
+export function installCommand(
+  manager: ManagerId,
+  name: string,
+): readonly string[] {
+  const spec = `${name}@latest`
+
+  switch (manager) {
+    case 'bun':
+      return ['bun', 'add', '--global', spec]
+    case 'pnpm':
+      return ['pnpm', 'add', '--global', spec]
+    case 'yarn':
+      return ['yarn', 'global', 'add', spec]
+    case 'npm':
+      return ['npm', 'install', '--global', spec]
+  }
+}

package/src/version/skew.ts

@@ -0,0 +1,192 @@
+import { PROJECT_ROOT } from '@/project-root'
+import { compareVersions, parseVersion } from '@/version/compare'
+import {
+  type InstalledPackage,
+  readInstalled,
+  UNKNOWN_LABEL,
+} from '@/version/installed'
+import { detectManager } from '@/version/manager'
+
+const REGISTRY = 'https://registry.npmjs.org'
+
+/**
+ * Short enough that a check waiting on a dead network still returns inside the
+ * time an operator would give the command anyway. The skew line is one section
+ * of a report the rest of which needs no network at all, so the budget is set
+ * against how long the report may be held up rather than against how long the
+ * registry usually takes.
+ */
+const LOOKUP_TIMEOUT_MS = 3_000
+
+/**
+ * Three states and no fourth. `unknown` covers every way the question could not
+ * be answered and carries the reason, which is what a caller reports instead of
+ * a version.
+ *
+ * An installed version ahead of the published one reports `current`. That is a
+ * source checkout between a release commit and the publish job, or a local
+ * build, and neither is skew. Giving it a state of its own would fire a warning
+ * on every maintainer run for a condition with no remedy.
+ */
+export type SkewState = 'current' | 'behind' | 'unknown'
+
+interface SkewBase {
+  readonly name: string
+  readonly installed: string
+}
+
+/**
+ * A union rather than one shape with two optional fields, so a `behind` report
+ * cannot exist without the version it is behind and an `unknown` one cannot
+ * exist without its reason. Both are what `describeSkew` renders into a line an
+ * operator reads, and an optional field renders the word `undefined` there.
+ */
+export type SkewReport =
+  | (SkewBase & {
+      readonly state: 'current' | 'behind'
+      readonly latest: string
+    })
+  | (SkewBase & { readonly state: 'unknown'; readonly reason: string })
+
+/** Resolves the newest published version, or throws for `readSkew` to absorb. */
+export type LatestLookup = (name: string) => Promise<string>
+
+export interface SkewOptions {
+  readonly installed?: InstalledPackage
+  readonly lookup?: LatestLookup
+}
+
+/**
+ * The installed version against the newest published one.
+ *
+ * Never rejects and never reports through an exit code. `aitk sync --check
+ * --exit-code` gates CI on drift it measured locally, so a lookup that failed
+ * the caller would turn an offline machine into a failing check and the check
+ * would be routed around. Every failure lands in `unknown` with its reason.
+ */
+export async function readSkew(options: SkewOptions = {}): Promise<SkewReport> {
+  const installed = options.installed ?? readInstalled()
+  const lookup = options.lookup ?? fetchLatest
+  const { name, version } = installed
+
+  if (version === undefined) {
+    return unknown(
+      installed,
+      'No version in the package manifest, so there is nothing to compare.',
+    )
+  }
+
+  if (name === undefined) {
+    return unknown(
+      installed,
+      'No name in the package manifest, so the registry has nothing to look up.',
+    )
+  }
+
+  const local = parseVersion(version)
+  if (local === undefined) {
+    return unknown(
+      installed,
+      `Installed version ${version} is not a version this can parse.`,
+    )
+  }
+
+  let raw: string
+  try {
+    raw = await lookup(name)
+  } catch (error) {
+    return unknown(installed, `Registry lookup failed: ${describe(error)}`)
+  }
+
+  const published = parseVersion(raw)
+  if (published === undefined) {
+    return unknown(
+      installed,
+      `Registry reported ${raw} as the newest version, which is not a version this can parse.`,
+    )
+  }
+
+  return {
+    state: compareVersions(local, published) < 0 ? 'behind' : 'current',
+    name,
+    installed: version,
+    latest: raw,
+  }
+}
+
+function unknown(installed: InstalledPackage, reason: string): SkewReport {
+  return {
+    state: 'unknown',
+    name: installed.name ?? UNKNOWN_LABEL,
+    installed: installed.version ?? UNKNOWN_LABEL,
+    reason,
+  }
+}
+
+/** The newest published version, or `undefined` when it could not be read. */
+export function latestOf(report: SkewReport): string | undefined {
+  return report.state === 'unknown' ? undefined : report.latest
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * The dist-tag endpoint rather than the full packument, which for this package
+ * carries every published manifest and is the larger part of a megabyte. The
+ * question is one string and this is the endpoint that answers only it.
+ */
+async function fetchLatest(name: string): Promise<string> {
+  const response = await fetch(
+    `${REGISTRY}/-/package/${encodeURIComponent(name)}/dist-tags`,
+    {
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`registry returned ${response.status}`)
+  }
+
+  const tags = (await response.json()) as Record<string, unknown>
+  const latest = tags.latest
+
+  if (typeof latest !== 'string') {
+    throw new Error('registry reported no latest dist-tag')
+  }
+
+  return latest
+}
+
+/**
+ * One line naming the state, for a caller that renders the skew beside sections
+ * it does not own. Held here so `aitk sync --check` and `aitk claude skills
+ * drift` cannot word the same three states differently.
+ *
+ * The remedy is chosen by the same detection `aitk upgrade` runs, because both
+ * callers run from a source checkout routinely and that is where the verb
+ * refuses. Naming it unconditionally sends a contributor whose clone sits a
+ * release behind to a command that declines. The read is a match against the
+ * root string rather than a filesystem call, so the line stays cheap.
+ */
+export function describeSkew(
+  report: SkewReport,
+  root: string = PROJECT_ROOT,
+): string {
+  if (report.state === 'unknown') {
+    return `Installed ${report.installed}, published unknown. ${report.reason}`
+  }
+
+  if (report.state === 'current') {
+    return `Installed ${report.installed}, which is the newest published.`
+  }
+
+  const remedy =
+    detectManager(root) === undefined
+      ? 'This is a source checkout, so pull rather than reinstalling.'
+      : 'Run `aitk upgrade`.'
+
+  return `Installed ${report.installed}, published ${report.latest}. ${remedy}`
+}