@shazhou/proman-core 0.9.0

package/src/config/types.ts

@@ -0,0 +1,19 @@
+export type PackageType = 'lib' | 'cli' | 'webui' | 'api'
+
+export type PackageEntry = {
+  name: string
+  path: string
+  type: PackageType
+  private?: boolean
+}
+
+export type ReleaseConfig = {
+  registry?: string
+  access?: 'public' | 'restricted'
+  gitTagPrefix?: string
+}
+
+export type PromanConfig = {
+  packages: PackageEntry[]
+  release?: ReleaseConfig
+}

package/src/config/validate-config.ts

@@ -0,0 +1,81 @@
+import type { PackageEntry, PackageType, PromanConfig } from './types.js'
+
+const ERR_PREFIX = 'Invalid proman config:'
+const VALID_TYPES: readonly PackageType[] = ['lib', 'cli', 'webui', 'api']
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function validatePackageEntry(entry: unknown, index: number): PackageEntry {
+  if (!isPlainObject(entry)) {
+    throw new Error(`${ERR_PREFIX} packages[${index}] must be an object`)
+  }
+  const { name, path, type, private: isPrivate } = entry
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`${ERR_PREFIX} packages[${index}].name must be a non-empty string`)
+  }
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error(`${ERR_PREFIX} packages[${index}].path must be a non-empty string`)
+  }
+  let resolvedType: PackageType = 'lib'
+  if (type !== undefined) {
+    if (typeof type !== 'string' || !VALID_TYPES.includes(type as PackageType)) {
+      throw new Error(
+        `${ERR_PREFIX} packages[${index}].type must be one of 'lib' | 'cli' | 'webui' | 'api'`,
+      )
+    }
+    resolvedType = type as PackageType
+  }
+  if (isPrivate !== undefined && typeof isPrivate !== 'boolean') {
+    throw new Error(`${ERR_PREFIX} packages[${index}].private must be a boolean`)
+  }
+  const result: PackageEntry = { name, path, type: resolvedType }
+  if (isPrivate === true) result.private = true
+  return result
+}
+
+/**
+ * Pure validator. Throws Error with descriptive message on failure.
+ * Returns a typed PromanConfig (does not mutate input, does not apply defaults).
+ */
+export function validateConfig(value: unknown): PromanConfig {
+  if (!isPlainObject(value)) {
+    throw new Error(`${ERR_PREFIX} config must be an object`)
+  }
+
+  const { packages, release } = value
+
+  if (!Array.isArray(packages) || packages.length === 0) {
+    throw new Error(`${ERR_PREFIX} packages must be a non-empty array`)
+  }
+  const validatedPackages = packages.map((p, i) => validatePackageEntry(p, i))
+
+  let validatedRelease: PromanConfig['release']
+  if (release !== undefined) {
+    if (!isPlainObject(release)) {
+      throw new Error(`${ERR_PREFIX} release must be an object`)
+    }
+    const { registry, access, gitTagPrefix } = release
+    if (registry !== undefined && (typeof registry !== 'string' || registry.length === 0)) {
+      throw new Error(`${ERR_PREFIX} release.registry must be a non-empty string`)
+    }
+    if (access !== undefined && access !== 'public' && access !== 'restricted') {
+      throw new Error(`${ERR_PREFIX} release.access must be 'public' or 'restricted'`)
+    }
+    if (gitTagPrefix !== undefined && typeof gitTagPrefix !== 'string') {
+      throw new Error(`${ERR_PREFIX} release.gitTagPrefix must be a string`)
+    }
+    validatedRelease = {
+      registry: registry as string | undefined,
+      access: access as 'public' | 'restricted' | undefined,
+      gitTagPrefix: gitTagPrefix as string | undefined,
+    }
+  }
+
+  const result: PromanConfig = {
+    packages: validatedPackages,
+  }
+  if (validatedRelease !== undefined) result.release = validatedRelease
+  return result
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Re-export config utilities
+
+export type {
+  BumpOptions,
+  DeployCommandOptions,
+  DevCommandOptions,
+  InitOptions,
+  LinkCommandOptions,
+  PublishOptions,
+} from './commands/index.js'
+// Re-export all command functions
+export {
+  build,
+  bump,
+  check,
+  deploy,
+  format,
+  init,
+  link,
+  linkStatus,
+  publish,
+  runTests,
+  unlink,
+} from './commands/index.js'
+export type { PackageEntry, PackageType, PromanConfig, ReleaseConfig } from './config/index.js'
+export { loadConfig, validateConfig } from './config/index.js'
+
+// Re-export utility functions
+export * from './utils/index.js'

package/src/utils/changeset.ts

@@ -0,0 +1,98 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export type Bump = 'major' | 'minor' | 'patch'
+
+export type Changeset = {
+  file: string
+  packages: Record<string, Bump>
+  body: string
+}
+
+const VALID_BUMPS: ReadonlySet<string> = new Set(['major', 'minor', 'patch'])
+
+function stripQuotes(s: string): string {
+  const t = s.trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1)
+  }
+  return t
+}
+
+export function parseChangeset(raw: string, file: string): Changeset {
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!fmMatch) {
+    throw new Error(`missing frontmatter in changeset: ${file}`)
+  }
+  const fmBlock = fmMatch[1] as string
+  const body = (fmMatch[2] as string).replace(/^\s+|\s+$/g, '')
+  const packages: Record<string, Bump> = {}
+  const lines = fmBlock.split(/\r?\n/)
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    const colonIdx = trimmed.indexOf(':')
+    if (colonIdx < 0) {
+      throw new Error(`invalid frontmatter line in ${file}: ${line}`)
+    }
+    const key = stripQuotes(trimmed.slice(0, colonIdx))
+    const value = stripQuotes(trimmed.slice(colonIdx + 1))
+    if (!VALID_BUMPS.has(value)) {
+      throw new Error(`invalid bump '${value}' for package '${key}' in ${file}`)
+    }
+    packages[key] = value as Bump
+  }
+  return { file, packages, body }
+}
+
+export async function readChangesets(rootDir: string): Promise<Changeset[]> {
+  const dir = join(rootDir, '.changeset')
+  let entries: string[]
+  try {
+    entries = await readdir(dir)
+  } catch {
+    return []
+  }
+  const mdFiles = entries.filter((n) => n.endsWith('.md') && n.toLowerCase() !== 'readme.md').sort()
+  const out: Changeset[] = []
+  for (const name of mdFiles) {
+    const file = join(dir, name)
+    const raw = await readFile(file, 'utf8')
+    out.push(parseChangeset(raw, file))
+  }
+  return out
+}
+
+export type ChangelogEntryInput = {
+  version: string
+  date: string
+  bodies: string[]
+}
+
+export function buildChangelogEntry(input: ChangelogEntryInput): string {
+  const { version, date, bodies } = input
+  const lines: string[] = [`## ${version} — ${date}`, '']
+  for (const body of bodies) {
+    const parts = body.split(/\r?\n/)
+    const first = parts[0] ?? ''
+    lines.push(`- ${first}`)
+    for (let i = 1; i < parts.length; i++) {
+      lines.push(`  ${parts[i]}`)
+    }
+  }
+  lines.push('')
+  return `${lines.join('\n')}\n`
+}
+
+export function prependChangelog(existing: string | null, entry: string): string {
+  if (!existing || existing.trim() === '') {
+    return `# Changelog\n\n${entry}`
+  }
+  const headingMatch = existing.match(/^(#\s+[^\n]*\n)(\n*)([\s\S]*)$/)
+  if (headingMatch) {
+    const heading = headingMatch[1] as string
+    const rest = headingMatch[3] as string
+    return `${heading}\n${entry}${rest}`
+  }
+  return `${entry}\n${existing}`
+}

package/src/utils/fingerprint.ts

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import type { PackageEntry } from '../config/types.js'
+
+/**
+ * Recursively collect files matching glob-like patterns.
+ * Supports `**\/*.ext`, `dir/**\/*.ext`, and literal filenames.
+ */
+function collectFiles(baseDir: string, patterns: string[]): string[] {
+  const results: string[] = []
+
+  function walk(dir: string): void {
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of entries) {
+      if (name === 'node_modules' || name === '.git' || name === 'dist') continue
+      if (name === '.proman') continue
+      const full = join(dir, name)
+      let st: ReturnType<typeof statSync>
+      try {
+        st = statSync(full)
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) {
+        walk(full)
+      } else if (st.isFile()) {
+        const rel = relative(baseDir, full)
+        if (matchesAny(rel, patterns)) {
+          results.push(rel)
+        }
+      }
+    }
+  }
+
+  walk(baseDir)
+  return results.sort()
+}
+
+function matchesAny(relPath: string, patterns: string[]): boolean {
+  for (const p of patterns) {
+    // Handle patterns with **/ anywhere (e.g. "**/*.ts", "src/**/*.ts")
+    const dstarIdx = p.indexOf('**/')
+    if (dstarIdx >= 0) {
+      const prefix = p.slice(0, dstarIdx) // e.g. "" or "src/"
+      const suffix = p.slice(dstarIdx + 3) // e.g. "*.ts"
+
+      // Check prefix: relPath must start with the prefix (if any)
+      if (prefix && !relPath.startsWith(prefix)) continue
+
+      // Check suffix: get the part after the prefix match
+      const rest = prefix ? relPath.slice(prefix.length) : relPath
+      if (suffix.startsWith('*')) {
+        // *.ext pattern
+        const ext = suffix.slice(1) // e.g. ".ts"
+        if (rest.endsWith(ext)) return true
+      } else if (rest.endsWith(suffix)) {
+        return true
+      }
+    } else {
+      // Exact filename match (e.g. "package.json", "biome.json")
+      const base = relPath.split('/').pop() ?? relPath
+      if (base === p || relPath === p) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Hash file contents for a set of glob patterns under a directory.
+ * Returns a hex sha256 hash string.
+ */
+export function hashFiles(dir: string, patterns: string[]): string {
+  const files = collectFiles(dir, patterns)
+  const hash = createHash('sha256')
+  for (const rel of files) {
+    hash.update(rel)
+    hash.update('\0')
+    const content = readFileSync(join(dir, rel))
+    hash.update(content)
+    hash.update('\0')
+  }
+  return hash.digest('hex')
+}
+
+/** Read a stored fingerprint. Returns null if file does not exist. */
+export function readFingerprint(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf-8').trim()
+  } catch {
+    return null
+  }
+}
+
+/** Write a fingerprint, creating parent dirs as needed. */
+export function writeFingerprint(path: string, hash: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, hash)
+}
+
+/**
+ * Compute per-package build fingerprints with dependency propagation.
+ * Processes packages in order (assumed topo-sorted in proman.yaml).
+ * Each package's fingerprint = hash(own src/** + package.json + tsconfig.json + dep fingerprints).
+ */
+export function computeBuildFingerprints(
+  cwd: string,
+  packages: readonly Pick<PackageEntry, 'name' | 'path'>[],
+): Map<string, string> {
+  // Build dependency map from package.json files
+  const depMap = new Map<string, string[]>()
+  const pkgNames = new Set(packages.map((p) => p.name))
+
+  for (const pkg of packages) {
+    const pkgJsonPath = join(resolve(cwd, pkg.path), 'package.json')
+    let deps: string[] = []
+    try {
+      const json = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as {
+        dependencies?: Record<string, string>
+      }
+      if (json.dependencies) {
+        deps = Object.keys(json.dependencies).filter((d) => pkgNames.has(d))
+      }
+    } catch {
+      // no package.json or parse error — no deps
+    }
+    depMap.set(pkg.name, deps)
+  }
+
+  const fingerprints = new Map<string, string>()
+
+  for (const pkg of packages) {
+    const pkgDir = resolve(cwd, pkg.path)
+    // Own file hash
+    const ownHash = hashFiles(pkgDir, ['src/**/*.ts', 'package.json', 'tsconfig.json'])
+
+    // Combine with dependency fingerprints
+    const hash = createHash('sha256')
+    hash.update(ownHash)
+
+    const deps = depMap.get(pkg.name) ?? []
+    for (const dep of deps.sort()) {
+      const depFp = fingerprints.get(dep) ?? ''
+      hash.update(dep)
+      hash.update('\0')
+      hash.update(depFp)
+      hash.update('\0')
+    }
+
+    fingerprints.set(pkg.name, hash.digest('hex'))
+  }
+
+  return fingerprints
+}
+
+/**
+ * Compute a root-level fingerprint for test or check commands.
+ * - test: all .ts files + package.json (covers src, tests, vitest.config.ts)
+ * - check: all .ts files + package.json + biome.json
+ */
+export function computeRootFingerprint(cwd: string, command: 'test' | 'check'): string {
+  const patterns: string[] =
+    command === 'test' ? ['**/*.ts', 'package.json'] : ['**/*.ts', 'package.json', 'biome.json']
+
+  return hashFiles(cwd, patterns)
+}
+
+/** Convert a package name to a safe filename: @scope/name → @scope-name */
+export function pkgNameToFilename(name: string): string {
+  return name.replace(/\//g, '-')
+}
+
+/**
+ * Get the path where a fingerprint file should be stored.
+ *
+ * Storage strategy differs by command type:
+ * - **build**: stores fingerprint at `<pkg>/dist/.build-fingerprint` so that
+ *   deleting `dist/` (clean build) automatically invalidates the cache.
+ * - **test / check**: stores in `.proman/<command>/` directory, which is
+ *   independent of build artifacts and survives `dist/` cleanup.
+ *
+ * This separation ensures `rm -rf dist` forces a rebuild without
+ * accidentally invalidating test/check caches (and vice-versa).
+ */
+export function fingerprintPath(cwd: string, command: string, pkgName?: string): string {
+  if (command === 'build' && pkgName) {
+    // For build command, store fingerprint inside package's dist folder
+    return join(cwd, 'dist/.build-fingerprint')
+  }
+
+  // For test/check commands or when no package name, use .proman directory
+  const filename = pkgName ? `${pkgNameToFilename(pkgName)}.fingerprint` : 'root.fingerprint'
+  return join(cwd, '.proman', command, filename)
+}

package/src/utils/git.ts

@@ -0,0 +1,119 @@
+export type GitOps = {
+  getCurrentBranch: () => Promise<string>
+  isCleanTree: () => Promise<boolean>
+  branchExists: (name: string) => Promise<boolean>
+  checkoutNewBranch: (name: string) => Promise<void>
+  checkoutNewBranchFrom: (name: string, ref: string) => Promise<void>
+  tagExists: (tag: string) => Promise<boolean>
+  addAll: () => Promise<void>
+  commit: (msg: string, author?: string) => Promise<void>
+  push: (branch: string) => Promise<void>
+  log: (range?: string) => Promise<string>
+  tag: (name: string, message?: string) => Promise<void>
+  pushTags: () => Promise<void>
+  checkout: (branch: string) => Promise<void>
+  merge: (branch: string, opts?: { noFf?: boolean; message?: string }) => Promise<void>
+  deleteBranchLocal: (name: string) => Promise<void>
+  deleteBranchRemote: (name: string) => Promise<void>
+}
+
+async function run(args: string[], cwd: string = process.cwd()): Promise<string> {
+  const { execFileSync } = await import('node:child_process')
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 10 * 1024 * 1024,
+    })
+  } catch (err: unknown) {
+    const e = err as { stderr?: string; stdout?: string }
+    throw new Error(`git ${args.join(' ')} failed: ${(e.stderr ?? e.stdout ?? '').trim()}`)
+  }
+}
+
+function parseAuthor(author: string): { name: string; email: string } {
+  const m = author.match(/^(.+?)\s*<(.+)>\s*$/)
+  if (!m) throw new Error(`invalid author string: ${author}`)
+  return { name: (m[1] as string).trim(), email: (m[2] as string).trim() }
+}
+
+export function createGitOps(cwd: string = process.cwd()): GitOps {
+  return {
+    getCurrentBranch: async () => (await run(['branch', '--show-current'], cwd)).trim(),
+    isCleanTree: async () => (await run(['status', '--porcelain'], cwd)).trim() === '',
+    branchExists: async (name) => {
+      const { execFileSync } = await import('node:child_process')
+      try {
+        execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${name}`], {
+          cwd,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        return true
+      } catch {
+        return false
+      }
+    },
+    checkoutNewBranch: async (name) => {
+      await run(['checkout', '-b', name], cwd)
+    },
+    checkoutNewBranchFrom: async (name, ref) => {
+      await run(['checkout', '-b', name, ref], cwd)
+    },
+    tagExists: async (tag) => {
+      const { execFileSync } = await import('node:child_process')
+      try {
+        execFileSync('git', ['rev-parse', '--verify', '-q', `refs/tags/${tag}`], {
+          cwd,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        return true
+      } catch {
+        return false
+      }
+    },
+    addAll: async () => {
+      await run(['add', '-A'], cwd)
+    },
+    commit: async (msg, author) => {
+      const args = ['commit', '-m', msg]
+      if (author) {
+        const { name, email } = parseAuthor(author)
+        args.unshift('-c', `user.name=${name}`, '-c', `user.email=${email}`)
+        args.push(`--author=${author}`)
+      }
+      await run(args, cwd)
+    },
+    push: async (branch) => {
+      await run(['push', '-u', 'origin', branch], cwd)
+    },
+    log: async (range) => {
+      const args = ['log', '--pretty=%s']
+      if (range) args.push(range)
+      return await run(args, cwd)
+    },
+    tag: async (name, message) => {
+      const args = message ? ['tag', '-a', name, '-m', message] : ['tag', name]
+      await run(args, cwd)
+    },
+    pushTags: async () => {
+      await run(['push', '--tags'], cwd)
+    },
+    checkout: async (branch) => {
+      await run(['checkout', branch], cwd)
+    },
+    merge: async (branch, opts) => {
+      const args = ['merge']
+      if (opts?.noFf) args.push('--no-ff')
+      if (opts?.message) args.push('-m', opts.message)
+      args.push(branch)
+      await run(args, cwd)
+    },
+    deleteBranchLocal: async (name) => {
+      await run(['branch', '-d', name], cwd)
+    },
+    deleteBranchRemote: async (name) => {
+      await run(['push', 'origin', '--delete', name], cwd)
+    },
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+// Export all utility functions
+export * from './changeset.js'
+export * from './fingerprint.js'
+export * from './git.js'
+export * from './npm.js'
+export * from './smoke-test.js'
+export * from './version.js'
+export * from './workspace.js'

package/src/utils/npm.ts

@@ -0,0 +1,110 @@
+export type NpmRegistryFetch = (pkg: string) => Promise<string[]>
+
+export type PublishOptions = {
+  tag: string
+  access?: 'public' | 'restricted'
+}
+
+export type NpmRunner = {
+  install: () => Promise<void>
+  build: () => Promise<void>
+  test: () => Promise<void>
+  check: () => Promise<void>
+  format: () => Promise<void>
+  publish: (pkgDir: string, opts: PublishOptions) => Promise<void>
+}
+
+export type NextRcOptions = {
+  baseVersion: string
+  existing: string[]
+}
+
+const RELEASE_BRANCH_RE = /^release\/(.+)$/
+
+export function parseReleaseBranch(branch: string): string {
+  const m = branch.match(RELEASE_BRANCH_RE)
+  if (!m) throw new Error(`not a release branch: '${branch}'`)
+  const v = (m[1] as string).trim()
+  if (!v) throw new Error(`malformed release branch: '${branch}'`)
+  return v
+}
+
+export function nextRcNumber(opts: NextRcOptions): number {
+  const { baseVersion, existing } = opts
+  const prefix = `${baseVersion}-rc.`
+  let max = 0
+  for (const v of existing) {
+    if (!v.startsWith(prefix)) continue
+    const tail = v.slice(prefix.length)
+    const n = Number.parseInt(tail, 10)
+    if (Number.isFinite(n) && n > max) max = n
+  }
+  return max + 1
+}
+
+export function formatRcVersion(baseVersion: string, n: number): string {
+  return `${baseVersion}-rc.${n}`
+}
+
+export const defaultRegistryFetch: NpmRegistryFetch = async (pkg) => {
+  const res = await fetch(`https://registry.npmjs.org/${pkg}`)
+  if (!res.ok) {
+    if (res.status === 404) return []
+    throw new Error(`registry fetch failed for ${pkg}: ${res.status} ${res.statusText}`)
+  }
+  const json = (await res.json()) as { versions?: Record<string, unknown> }
+  return Object.keys(json.versions ?? {})
+}
+
+export type SpawnFn = (
+  argv: string[],
+  cwd: string,
+) => Promise<{ code: number; stdout: string; stderr: string }>
+
+export const defaultSpawn: SpawnFn = async (argv, cwd) => {
+  const { spawnSync } = await import('node:child_process')
+  const result = spawnSync(argv[0] as string, argv.slice(1), {
+    cwd,
+    stdio: 'pipe',
+  })
+  const stdout = result.stdout?.toString() ?? ''
+  const stderr = result.stderr?.toString() ?? ''
+  // Forward captured output to terminal so users still see progress
+  if (stdout) process.stdout.write(stdout)
+  if (stderr) process.stderr.write(stderr)
+  return {
+    code: result.status ?? 1,
+    stdout,
+    stderr,
+  }
+}
+
+export async function runOrThrow(spawn: SpawnFn, argv: string[], cwd: string): Promise<void> {
+  const { code, stdout, stderr } = await spawn(argv, cwd)
+  if (code !== 0) {
+    const detail = stderr.trim() || stdout.trim()
+    throw new Error(detail ? `${argv.join(' ')} failed: ${detail}` : `${argv.join(' ')} failed`)
+  }
+}
+
+export function createNpmRunner(cwd: string, spawn: SpawnFn = defaultSpawn): NpmRunner {
+  const runScript = (script: string) => async () => {
+    await runOrThrow(spawn, ['pnpm', 'run', script], cwd)
+  }
+  return {
+    install: async () => {
+      await runOrThrow(spawn, ['pnpm', 'install'], cwd)
+    },
+    build: runScript('build'),
+    test: async () => {
+      await runOrThrow(spawn, ['pnpm', 'exec', 'vitest', 'run'], cwd)
+    },
+    check: runScript('check'),
+    format: runScript('format'),
+    publish: async (pkgDir, opts) => {
+      const args = ['pnpm', 'publish', '--tag', opts.tag, '--no-git-checks']
+      if (opts.access) args.push('--access', opts.access)
+      await runOrThrow(spawn, args, pkgDir)
+    },
+  }
+}