infra-kit 0.1.128 → 0.1.129

package/src/lib/version-utils/next-version.ts

@@ -1,283 +0,0 @@
-import { parseReleaseRef, validateName } from 'src/lib/release-id'
-import type { ReleaseId } from 'src/lib/release-id'
-import type { ReleaseType } from 'src/lib/release-utils'
-
-import { parseVersion, sortVersions } from './version-utils'
-
-export const NEXT_TOKEN = 'next'
-
-export type SemVer = readonly [number, number, number]
-
-export interface ExistingVersionsSources {
-  remoteBranches?: string[]
-  jiraVersions?: string[]
-}
-
-const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)$/
-
-const stripBranchPrefix = (raw: string): string => {
-  return raw.replace(/^.*release\//, '')
-}
-
-const tryParse = (raw: string): SemVer | null => {
-  const cleaned = stripBranchPrefix(raw.trim())
-  const match = VERSION_RE.exec(cleaned)
-
-  if (!match) return null
-
-  return [Number(match[1]), Number(match[2]), Number(match[3])]
-}
-
-const semverKey = (v: SemVer): string => {
-  return `${v[0]}.${v[1]}.${v[2]}`
-}
-
-export const collectKnownVersions = (sources: ExistingVersionsSources): SemVer[] => {
-  const all = [...(sources.remoteBranches ?? []), ...(sources.jiraVersions ?? [])]
-  const parsed: SemVer[] = []
-  const seen = new Set<string>()
-
-  for (const raw of all) {
-    const v = tryParse(raw)
-
-    if (!v) continue
-
-    const key = semverKey(v)
-
-    if (seen.has(key)) continue
-
-    seen.add(key)
-    parsed.push(v)
-  }
-
-  return sortVersions(
-    parsed.map((v) => {
-      return semverKey(v)
-    }),
-  ).map((s) => {
-    return parseVersion(`v${s}`)
-  })
-}
-
-export class NoPriorVersionsError extends Error {
-  constructor() {
-    super('No prior release versions found from git or Jira. Specify the version explicitly.')
-    this.name = 'NoPriorVersionsError'
-  }
-}
-
-/**
- * Compute the next semantic version based on release type.
- * - regular: bump minor, reset patch to 0
- * - hotfix: bump patch on the highest minor (any patch)
- *
- * Returns the version without the leading "v" (e.g. "1.64.0").
- */
-export const computeNextVersion = (known: SemVer[], type: ReleaseType): string => {
-  if (known.length === 0) throw new NoPriorVersionsError()
-
-  const max = known[known.length - 1] as SemVer
-
-  if (type === 'hotfix') {
-    const [major, minor] = max
-
-    const highestPatchOnMinor = known.reduce((acc, v) => {
-      if (v[0] === major && v[1] === minor) return Math.max(acc, v[2])
-
-      return acc
-    }, 0)
-
-    return `${major}.${minor}.${highestPatchOnMinor + 1}`
-  }
-
-  const [major, minor] = max
-
-  return `${major}.${minor + 1}.0`
-}
-
-const isNextToken = (token: string): boolean => {
-  return token.trim().toLowerCase() === NEXT_TOKEN
-}
-
-/**
- * A release spec is the parsed form of a versioned release request: a raw
- * version token (`"1.2.5"` or `"next"`) plus its type and optional
- * description. This is the unchanged output of {@link parseReleaseSpec} and the
- * versioned-input shape consumed by {@link resolveReleaseEntries}.
- */
-export interface ReleaseSpec {
-  version: string
-  type: ReleaseType
-  description?: string
-}
-
-/**
- * A named release request: a bare kebab-case name plus its type and optional
- * description. Named releases never auto-bump; `"next"` is version-only.
- */
-export interface NamedReleaseInput {
-  name: string
-  type: ReleaseType
-  description?: string
-}
-
-/** Either a versioned spec or a named release request. */
-export type ReleaseInput = ReleaseSpec | NamedReleaseInput
-
-/**
- * A fully resolved release entry. The {@link ReleaseId} carries the concrete
- * identity (version or name) and is the single source for branch/PR/Jira
- * formatting via the `release-id` module.
- */
-export interface ReleaseEntry {
-  id: ReleaseId
-  type: ReleaseType
-  description?: string
-}
-
-const isReleaseType = (value: string): value is ReleaseType => {
-  return value === 'regular' || value === 'hotfix'
-}
-
-const isNamedReleaseInput = (input: ReleaseInput): input is NamedReleaseInput => {
-  return 'name' in input
-}
-
-/**
- * Parse a CLI release spec of the form `<token>[:type[:description]]` into a
- * {@link ReleaseInput}. The token determines the kind: a semver (`"1.2.5"`) or
- * the literal `"next"` yields a versioned {@link ReleaseSpec}; anything else is
- * treated as a named release ({@link NamedReleaseInput}) — the name is not
- * validated here, {@link resolveReleaseEntries} runs `validateName` later. Type
- * defaults to "regular". Description is everything after the second colon, so
- * colons inside descriptions are preserved.
- */
-export const parseReleaseSpec = (raw: string): ReleaseInput => {
-  const spec = raw.trim()
-
-  if (spec === '') throw new Error('Release spec is empty')
-
-  const firstColon = spec.indexOf(':')
-  let token = spec
-  let type: ReleaseType = 'regular'
-  let description = ''
-
-  if (firstColon !== -1) {
-    token = spec.slice(0, firstColon).trim()
-    const rest = spec.slice(firstColon + 1)
-    const secondColon = rest.indexOf(':')
-    const typeRaw = secondColon === -1 ? rest.trim() : rest.slice(0, secondColon).trim()
-
-    description = secondColon === -1 ? '' : rest.slice(secondColon + 1).trim()
-    const typeLower = typeRaw.toLowerCase()
-
-    if (!isReleaseType(typeLower)) {
-      throw new Error(`Invalid release type "${typeRaw}". Expected "regular" or "hotfix".`)
-    }
-
-    type = typeLower
-  }
-
-  // A semver token or the "next" token is a versioned release; everything else
-  // is a named release. parseReleaseRef applies the same precedence downstream.
-  // Note: tryParse strips a leading "release/" prefix, so "release/1.2.3" reads
-  // as the version 1.2.3 (a real name can never contain a slash anyway).
-  if (isNextToken(token) || tryParse(token) !== null) {
-    const entry: ReleaseSpec = { version: token, type }
-
-    if (description !== '') entry.description = description
-
-    return entry
-  }
-
-  const entry: NamedReleaseInput = { name: token, type }
-
-  if (description !== '') entry.description = description
-
-  return entry
-}
-
-/**
- * Render a resolved {@link ReleaseEntry} as the canonical `--release` spec that
- * reproduces it — the inverse of {@link parseReleaseSpec} composed with
- * {@link resolveReleaseEntries}. The form is minimal: the bare token when the
- * release is `regular` with no description, `token:hotfix` for a hotfix with no
- * description, and `token:type:description` whenever a description is present
- * (the type segment is required to reach the description segment). The token is
- * the resolved {@link ReleaseId.raw} — a concrete semver for versions (so a
- * resolved `"next"` pins its computed version) or the name for named releases.
- */
-export const formatReleaseSpec = (entry: ReleaseEntry): string => {
-  const token = entry.id.raw
-
-  if (entry.description !== undefined && entry.description !== '') {
-    return `${token}:${entry.type}:${entry.description}`
-  }
-
-  if (entry.type === 'hotfix') return `${token}:hotfix`
-
-  return token
-}
-
-const withDescription = (base: { id: ReleaseId; type: ReleaseType }, description?: string): ReleaseEntry => {
-  return description !== undefined && description !== '' ? { ...base, description } : base
-}
-
-const resolveNamedInput = (input: NamedReleaseInput): ReleaseEntry => {
-  const name = input.name.trim()
-
-  // validateName throws InvalidReleaseNameError with a specific message.
-  validateName(name)
-
-  return withDescription({ id: { kind: 'name', name, raw: name }, type: input.type }, input.description)
-}
-
-/**
- * Resolve a list of release inputs into entries carrying a concrete
- * {@link ReleaseId}. Versioned inputs use the existing spec format: the
- * `"next"` token advances based on the running max so successive `"next"`
- * tokens produce sequential versions (even across mixed types), then the
- * concrete version is wrapped in a {@link ReleaseId}. Named inputs are
- * validated via `validateName` and never auto-bump.
- */
-export const resolveReleaseEntries = (entries: ReleaseInput[], known: SemVer[]): ReleaseEntry[] => {
-  const running: SemVer[] = [...known]
-
-  return entries.map((entry) => {
-    if (isNamedReleaseInput(entry)) {
-      return resolveNamedInput(entry)
-    }
-
-    const trimmed = entry.version.trim()
-
-    if (trimmed === '') {
-      throw new Error('Release entry has an empty version')
-    }
-
-    if (isNextToken(trimmed)) {
-      const next = computeNextVersion(running, entry.type)
-
-      running.push(parseVersion(`v${next}`))
-
-      return withDescription({ id: parseReleaseRef(next), type: entry.type }, entry.description)
-    }
-
-    const parsed = tryParse(trimmed)
-
-    if (!parsed) {
-      throw new Error(`Invalid version "${trimmed}". Expected semver like "1.2.5" or the token "next".`)
-    }
-
-    const explicit = `${parsed[0]}.${parsed[1]}.${parsed[2]}`
-
-    running.push(parsed)
-
-    return withDescription({ id: parseReleaseRef(explicit), type: entry.type }, entry.description)
-  })
-}
-
-export const hasNextToken = (entries: ReleaseInput[]): boolean => {
-  return entries.some((e) => {
-    return !isNamedReleaseInput(e) && isNextToken(e.version)
-  })
-}

package/src/lib/version-utils/version-utils.ts

@@ -1,31 +0,0 @@
-/**
- * Parse a `v<semver>` token into major, minor, patch numbers.
- *
- * SemVer-ONLY: this assumes a `v<semver>` token and will produce `NaN`s for
- * anything else. Callers that may see branch names or named releases
- * (`release/<name>`) MUST use the `release-id` module (`parseBranchName` /
- * `parseReleaseRef` + `compareReleaseIds`) instead. Only provably names-free
- * callers (the `collectKnownVersions` / `next`-bump math path) may use this.
- */
-export const parseVersion = (versionStr: string): [number, number, number] => {
-  return versionStr.slice(1).split('.').map(Number) as [number, number, number]
-}
-
-/**
- * Sort version strings in ascending order.
- * Note: Returns a new sorted array without mutating the original.
- *
- * SemVer-ONLY: relies on {@link parseVersion} and will NaN-sort named releases.
- * Name-aware callers MUST use `compareReleaseIds` from the `release-id` module.
- */
-export const sortVersions = (versions: string[]): string[] => {
-  return [...versions].sort((a, b) => {
-    const [majA, minA, patchA] = parseVersion(a)
-    const [majB, minB, patchB] = parseVersion(b)
-
-    if (majA !== majB) return (majA ?? 0) - (majB ?? 0)
-    if (minA !== minB) return (minA ?? 0) - (minB ?? 0)
-
-    return (patchA ?? 0) - (patchB ?? 0)
-  })
-}

package/src/lib/warm-cache/__tests__/warm-cache.test.ts

@@ -1,164 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import crypto from 'node:crypto'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-
-import {
-  ENV_CLEAR_FILE,
-  ENV_LOAD_FILE,
-  getProjectWarmCacheDir,
-  getWarmCacheRoot,
-  warmCacheKey,
-} from 'src/lib/constants'
-
-import {
-  canonicalizeProjectRoot,
-  evictStaleWarmCaches,
-  invalidateProjectWarmCache,
-  shouldWriteWarm,
-  writeWarmCache,
-} from '../warm-cache'
-
-let tmp: string
-const origXdg = process.env.XDG_CACHE_HOME
-
-beforeEach(() => {
-  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'warm-cache-test-'))
-  process.env.XDG_CACHE_HOME = path.join(tmp, 'cache')
-})
-
-afterEach(() => {
-  if (origXdg === undefined) delete process.env.XDG_CACHE_HOME
-  else process.env.XDG_CACHE_HOME = origXdg
-  fs.rmSync(tmp, { recursive: true, force: true })
-})
-
-describe('warmCacheKey — byte-identical to the zsh shasum contract', () => {
-  it('is the plain hex sha256 of the verbatim dir string', () => {
-    const dir = '/Users/x/projects/demo'
-
-    expect(warmCacheKey(dir)).toBe(crypto.createHash('sha256').update(dir, 'utf8').digest('hex'))
-  })
-
-  it('matches `printf %s "$dir" | shasum -a 256 | cut -c1-64` (the shell side)', () => {
-    const dir = '/Users/x/some/project path/with spaces'
-    const shell = execFileSync('/bin/zsh', ['-c', `printf %s ${JSON.stringify(dir)} | shasum -a 256 | cut -c1-64`])
-      .toString()
-      .trim()
-
-    expect(warmCacheKey(dir)).toBe(shell)
-  })
-})
-
-describe('shouldWriteWarm — pure gate matrix', () => {
-  const base = { autoLoaded: true, projectDir: '/p', canonicalProjectRoot: '/p' }
-
-  it('writes when auto-loaded, dir passed, and realpath root === dir', () => {
-    expect(shouldWriteWarm(base)).toBe(true)
-  })
-
-  it('skips a manual load', () => {
-    expect(shouldWriteWarm({ ...base, autoLoaded: false })).toBe(false)
-  })
-
-  it('skips when no projectDir (cli-invocation trigger)', () => {
-    expect(shouldWriteWarm({ ...base, projectDir: undefined })).toBe(false)
-  })
-
-  it('skips when non-git (empty canonical root — no sha256("") collapse)', () => {
-    expect(shouldWriteWarm({ ...base, canonicalProjectRoot: '' })).toBe(false)
-  })
-
-  it('skips when the realpath root diverges from the shell dir (symlink/nested)', () => {
-    expect(shouldWriteWarm({ ...base, canonicalProjectRoot: '/other' })).toBe(false)
-  })
-})
-
-describe('canonicalizeProjectRoot', () => {
-  it('returns "" for empty input', () => {
-    expect(canonicalizeProjectRoot('')).toBe('')
-  })
-
-  it('returns "" for an unresolvable path', () => {
-    expect(canonicalizeProjectRoot(path.join(tmp, 'does-not-exist'))).toBe('')
-  })
-
-  it('resolves symlinks to the physical path', () => {
-    const real = path.join(tmp, 'real')
-    const link = path.join(tmp, 'link')
-
-    fs.mkdirSync(real)
-    fs.symlinkSync(real, link)
-    expect(canonicalizeProjectRoot(link)).toBe(fs.realpathSync(real))
-  })
-})
-
-describe('writeWarmCache + evictStaleWarmCaches', () => {
-  it('writes the warm file 0o600 and reads back the contents', () => {
-    const dir = '/canon/project-a'
-
-    writeWarmCache(dir, 'export A=1\n')
-    const file = path.join(getProjectWarmCacheDir(dir), ENV_LOAD_FILE)
-
-    expect(fs.readFileSync(file, 'utf8')).toBe('export A=1\n')
-    expect(fs.statSync(file).mode & 0o777).toBe(0o600)
-  })
-
-  it('dELETES a past-TTL other-project warm dir on the next write (criterion #12)', () => {
-    const stale = '/canon/abandoned'
-
-    writeWarmCache(stale, 'export OLD=1\n')
-    const staleDir = getProjectWarmCacheDir(stale)
-    // Backdate the stale file well past the TTL.
-    const old = new Date(Date.now() - 5 * 60 * 60 * 1000)
-
-    fs.utimesSync(path.join(staleDir, ENV_LOAD_FILE), old, old)
-
-    // A fresh write for a DIFFERENT project triggers the sweep.
-    writeWarmCache('/canon/active', 'export NEW=1\n')
-    evictStaleWarmCaches()
-
-    expect(fs.existsSync(staleDir)).toBe(false)
-    expect(fs.existsSync(getProjectWarmCacheDir('/canon/active'))).toBe(true)
-  })
-
-  it('keeps a fresh warm dir', () => {
-    writeWarmCache('/canon/fresh', 'export F=1\n')
-    evictStaleWarmCaches()
-    expect(fs.existsSync(getProjectWarmCacheDir('/canon/fresh'))).toBe(true)
-  })
-
-  it('is a no-op when the warm root does not exist', () => {
-    expect(() => {
-      return evictStaleWarmCaches()
-    }).not.toThrow()
-    expect(fs.existsSync(getWarmCacheRoot())).toBe(false)
-  })
-})
-
-describe('invalidateProjectWarmCache', () => {
-  it('writes a clear-marker when a warm file exists (transient disable)', () => {
-    const dir = '/canon/to-clear'
-
-    writeWarmCache(dir, 'export A=1\n')
-    invalidateProjectWarmCache(dir, false)
-    expect(fs.existsSync(path.join(getProjectWarmCacheDir(dir), ENV_CLEAR_FILE))).toBe(true)
-    // warm file itself remains (startup gate compares mtimes)
-    expect(fs.existsSync(path.join(getProjectWarmCacheDir(dir), ENV_LOAD_FILE))).toBe(true)
-  })
-
-  it('does NOT create a dir/marker when there is no warm file', () => {
-    invalidateProjectWarmCache('/canon/never-warmed', false)
-    expect(fs.existsSync(getProjectWarmCacheDir('/canon/never-warmed'))).toBe(false)
-  })
-
-  it('purge deletes the whole warm dir', () => {
-    const dir = '/canon/to-purge'
-
-    writeWarmCache(dir, 'export A=1\n')
-    invalidateProjectWarmCache(dir, true)
-    expect(fs.existsSync(getProjectWarmCacheDir(dir))).toBe(false)
-  })
-})

package/src/lib/warm-cache/index.ts

@@ -1,7 +0,0 @@
-export {
-  canonicalizeProjectRoot,
-  evictStaleWarmCaches,
-  invalidateProjectWarmCache,
-  shouldWriteWarm,
-  writeWarmCache,
-} from './warm-cache'

package/src/lib/warm-cache/warm-cache.ts

@@ -1,136 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-
-import {
-  DEFAULT_WARM_TTL_SECONDS,
-  ENV_CLEAR_FILE,
-  ENV_LOAD_FILE,
-  atomicWriteFileSync,
-  getProjectWarmCacheDir,
-  getWarmCacheRoot,
-} from 'src/lib/constants'
-import { logger } from 'src/lib/logger'
-
-/** Inputs for {@link shouldWriteWarm}. All derivable without I/O so the gate is pure. */
-export interface ShouldWriteWarmInput {
-  /** Was this an automatic load? Manual loads must never become the project default. */
-  autoLoaded: boolean
-  /** The canonical project dir the SHELL passed via `--project-dir` (undefined for cli-invocation / non-startup callers). */
-  projectDir: string | undefined
-  /** `realpath(git top-level)` for this load, or '' when non-git / unresolvable (see {@link canonicalizeProjectRoot}). */
-  canonicalProjectRoot: string
-}
-
-/**
- * Decide whether an auto-load should ALSO write a project-scoped warm copy. Pure
- * (no I/O) so the full gate matrix is unit-testable. Warm requires ALL of:
- *  - the load was automatic (a manual `env-load prod` must not warm the project);
- *  - the shell passed a canonical `--project-dir` (warm is a shell-startup-only
- *    optimization; the cli-invocation trigger passes none and gets no warm file);
- *  - a non-empty git root (else every non-git project would collapse to one key
- *    and cross-leak secrets);
- *  - the realpath'd git root EQUALS the shell's canonical dir — the byte-identical
- *    key contract. On any mismatch (symlink/nested-config monorepo) we skip warm
- *    and degrade to the already-correct poll rather than write under a key the
- *    shell will never look up.
- */
-export const shouldWriteWarm = ({ autoLoaded, projectDir, canonicalProjectRoot }: ShouldWriteWarmInput): boolean => {
-  if (!autoLoaded) return false
-  if (!projectDir) return false
-  if (!canonicalProjectRoot) return false
-
-  return canonicalProjectRoot === projectDir
-}
-
-/** `realpath(projectRoot)`, or '' when projectRoot is empty or unresolvable. Never throws. */
-export const canonicalizeProjectRoot = (projectRoot: string): string => {
-  if (!projectRoot) return ''
-
-  try {
-    return fs.realpathSync(projectRoot)
-  } catch {
-    return ''
-  }
-}
-
-/**
- * Write the warm copy of env-load.sh for a project (0o600). Best-effort: a warm
- * write must never break the real (session) load, so failures are swallowed to
- * debug. `contents` is the SAME bytes as the session file so a warm-source is
- * indistinguishable from a fresh one.
- */
-export const writeWarmCache = (canonicalProjectDir: string, contents: string): void => {
-  try {
-    const dir = getProjectWarmCacheDir(canonicalProjectDir)
-
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
-    atomicWriteFileSync(path.join(dir, ENV_LOAD_FILE), contents, 0o600)
-  } catch (error) {
-    logger.debug(`warm-cache write skipped: ${(error as Error).message}`)
-  }
-}
-
-/**
- * Delete every project's warm dir whose env-load.sh is older than the TTL. The
- * codebase has no cache reaper, so warm files (plaintext secrets) would otherwise
- * accumulate indefinitely at a stable path; each successful warm write sweeps the
- * whole `projects/` tree. The just-written project is fresh (mtime≈now) so it is
- * never swept. Best-effort, concurrency-tolerant (force), never throws.
- */
-export const evictStaleWarmCaches = (
-  nowMs: number = Date.now(),
-  ttlSeconds: number = DEFAULT_WARM_TTL_SECONDS,
-): void => {
-  const root = getWarmCacheRoot()
-
-  let entries: fs.Dirent[]
-
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true })
-  } catch {
-    return // no warm root yet — nothing to sweep
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue
-
-    const projectDir = path.join(root, entry.name)
-
-    try {
-      const { mtimeMs } = fs.statSync(path.join(projectDir, ENV_LOAD_FILE))
-
-      if (nowMs - mtimeMs >= ttlSeconds * 1000) {
-        fs.rmSync(projectDir, { recursive: true, force: true })
-      }
-    } catch {
-      // missing/unreadable warm file — leave the dir (a lone clear marker is harmless)
-    }
-  }
-}
-
-/**
- * Invalidate a project's warm cache on `env-clear`. `purge` removes the project's
- * warm dir outright (durable disable). Otherwise, when a warm file exists, write a
- * clear-marker (`env-clear.sh`) so the NEXT shell's startup gate skips warm-source
- * (it compares marker mtime vs warm mtime, clear wins). The marker is TRANSIENT: a
- * later successful auto-load writes a newer warm file and warm resumes — durable
- * disable requires `purge`. Best-effort, never throws.
- */
-export const invalidateProjectWarmCache = (canonicalProjectDir: string, purge: boolean): void => {
-  try {
-    const dir = getProjectWarmCacheDir(canonicalProjectDir)
-
-    if (purge) {
-      fs.rmSync(dir, { recursive: true, force: true })
-
-      return
-    }
-
-    // No warm file ⇒ nothing to suppress; don't create a dir just to hold a marker.
-    if (!fs.existsSync(path.join(dir, ENV_LOAD_FILE))) return
-
-    atomicWriteFileSync(path.join(dir, ENV_CLEAR_FILE), '# infra-kit warm cache cleared\n', 0o600)
-  } catch (error) {
-    logger.debug(`warm-cache invalidate skipped: ${(error as Error).message}`)
-  }
-}