@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/pinning.mjs

@@ -0,0 +1,573 @@
+// Candidate compatibility/pinning contract (design Decision 13).
+//
+// The install record separates two layers:
+//   - declared: compatibility *intent* — supported toolchain ranges (including
+//     the fixed `node-modules` linker), a name-to-range map for every direct
+//     dependency (including the CLI itself), the local CLI version (which must
+//     equal the distributed package version), and the asset BOM.
+//   - resolved: the exact versions those ranges resolve to, the real
+//     `yarn.lock` content hash, and the recorded asset digests, so an M1
+//     artifact is reproducible.
+//
+// Every rule is reported, never short-circuited, and no missing/malformed data
+// is swallowed. Validation rejects an unpinned dependency, an invalid range, a
+// declared/resolved incoherence, a CLI/distributed version mismatch, a missing
+// lockfile, a wrong toolchain/linker, or an asset-digest mismatch. The concrete
+// versions and packed-artifact proof are M1 evidence; this module owns the shape
+// and the rules.
+//
+// Version/range matching uses the well-documented `semver` package (npm) rather
+// than a hand-rolled parser: spec-compliant prerelease semantics, x-ranges,
+// hyphen ranges and comparator sets are all required by the contract and are
+// exactly what a fragile regex drops. This is a deliberate canonical extension
+// of the storefront package's dependencies (justified at this decision site).
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import semver from 'semver'
+
+export const PINNING_VERSION = 2
+
+// Declared toolchain intent. Node >=20.9.0 is the Next.js 16 floor (Node 18 was
+// dropped); the linker is fixed to `node-modules` because PnP breaks the
+// Next.js 16 Turbopack build the candidate targets.
+export const TOOLCHAIN = {
+  node: '>=20.9.0',
+  yarn: '>=4.0.0 <5.0.0',
+  linker: 'node-modules',
+}
+
+// The managed suite is the package-owned surface installed into `.opencode/`.
+// Its BOM is what `doctor` and `update` compare; user-owned storefront files
+// live outside it. Only these directories are ever treated as package-owned.
+// The suite ships skills only — the root `AGENTS.md` is a rendered project file
+// covered by derived drift (reconcile dry-run), not by this BOM.
+export const MANAGED_SUITE_DIRS = ['skills']
+
+// The CLI pins itself as a direct dependency so a generated project can
+// reproduce the exact toolchain that produced it.
+export const CLI_PACKAGE = '@thorprovider/storefront'
+
+function sha256(input) {
+  return createHash('sha256').update(input).digest('hex')
+}
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key)
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** True when `range` is a non-empty, valid semver range. */
+export function isValidRange(range) {
+  return typeof range === 'string' && range.trim() !== '' && semver.validRange(range) !== null
+}
+
+/** True when `version` is a valid semver version. */
+export function isValidVersion(version) {
+  return typeof version === 'string' && semver.valid(version) !== null
+}
+
+/**
+ * Semver range check. Prerelease semantics are the documented semver rules:
+ * a prerelease version only satisfies a range when a comparator with the same
+ * `[major, minor, patch]` tuple also carries a prerelease (so `0.4.0-mvp.0`
+ * does NOT satisfy `^0.4.0`).
+ */
+export function satisfiesRange(version, range) {
+  if (!isValidVersion(version) || !isValidRange(range)) return false
+  return semver.satisfies(version, range)
+}
+
+/**
+ * The package's operative skill set, read from the single declared source: the
+ * package skill layout. Under each managed suite directory, a directory that
+ * directly contains a `SKILL.md` is an operative skill; any other file under a
+ * skill is a scoped reference, never a skill. Returns sorted `<dir>/<name>`
+ * POSIX-relative paths. Installation, migration/refresh, and validation all
+ * read this one source — there is no separate registry or manifest that
+ * restates the set.
+ */
+export function declaredOperativeSkills(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
+  const skills = []
+  for (const dir of dirs) {
+    const base = join(pkgRoot, dir)
+    if (!existsSync(base)) continue
+    for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name)
+    )) {
+      if (!entry.isDirectory()) continue
+      if (existsSync(join(base, entry.name, 'SKILL.md'))) skills.push(`${dir}/${entry.name}`)
+    }
+  }
+  return skills.sort()
+}
+
+/**
+ * The scoped reference files shipped under the operative skills: every managed
+ * suite file that is not a skill's own root `SKILL.md`. References travel with
+ * their owning skill (so the installed skill can load them) but are never
+ * counted or installed as skills.
+ */
+export function declaredSuiteReferences(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
+  const skillRoots = new Set(declaredOperativeSkills(pkgRoot, dirs).map((skill) => `${skill}/SKILL.md`))
+  return managedSuitePaths(pkgRoot, dirs).filter((rel) => !skillRoots.has(rel))
+}
+
+/**
+ * The package-owned suite file set (sorted POSIX-relative paths) under the
+ * managed suite directories of `pkgRoot`. This is the *complete owned asset
+ * set*: only files shipped by the package are ever hashed or compared, so a
+ * user's own skill/command files under `.opencode/` are neither stamped nor
+ * treated as drift. The set is derived from the declared skill layout
+ * (`declaredOperativeSkills`), so a directory without a `SKILL.md` is not part
+ * of the suite.
+ */
+export function managedSuitePaths(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
+  const paths = []
+  for (const skillRel of declaredOperativeSkills(pkgRoot, dirs)) {
+    const base = join(pkgRoot, skillRel)
+    const walk = (current) => {
+      for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) =>
+        a.name.localeCompare(b.name)
+      )) {
+        const abs = join(current, entry.name)
+        if (entry.isDirectory()) walk(abs)
+        else if (entry.isFile()) paths.push(relative(pkgRoot, abs).split(sep).join('/'))
+      }
+    }
+    walk(base)
+  }
+  return paths.sort()
+}
+
+/**
+ * Content digest map (`relpath -> sha256`) for an explicit set of relative
+ * paths under `rootDir`. A path that is absent is recorded as `null` (never
+ * silently dropped), so a missing owned asset is reported by `validatePinning`.
+ */
+export function hashPaths(rootDir, relPaths) {
+  const bom = {}
+  for (const rel of relPaths) {
+    const abs = join(rootDir, rel)
+    bom[rel] = existsSync(abs) ? sha256(readFileSync(abs)) : null
+  }
+  return bom
+}
+
+/**
+ * Content digest map (`relpath -> sha256`) of the managed suite directories
+ * under `rootDir`. Paths are POSIX-normalized so a record written on any
+ * platform compares equal. Only `MANAGED_SUITE_DIRS` are hashed.
+ */
+export async function hashManagedSuite(rootDir, dirs = MANAGED_SUITE_DIRS) {
+  return hashPaths(rootDir, managedSuitePaths(rootDir, dirs))
+}
+
+/**
+ * The owned-file set recorded in an install record, or `null` when the record
+ * predates the BOM (a legacy record) and the set cannot be derived. Callers
+ * MUST treat `null` conservatively: no file is retired from an undetermined
+ * set. Returns the `relpath -> digest` map itself (never a copy silently
+ * dropped), so callers can compare a recorded digest against the live file.
+ */
+export function recordedOwnedSet(record) {
+  if (!isPlainObject(record)) return null
+  if (isPlainObject(record.pinning) && isPlainObject(record.pinning.assets)) {
+    return record.pinning.assets
+  }
+  // An intermediate flattened shape that carried the BOM at the record root.
+  if (isPlainObject(record.assets)) return record.assets
+  return null
+}
+
+/**
+ * Retirement candidates: every path in the previously recorded owned-file set
+ * (the install-record BOM) that the incoming managed set no longer ships. A
+ * `null` or malformed recorded set yields no candidates, so retirement is never
+ * derived from an unknown set (the conservative legacy-record path).
+ */
+export function retirementCandidates(recordedAssets, incomingPaths) {
+  if (!isPlainObject(recordedAssets)) return []
+  const incoming = new Set(incomingPaths)
+  return Object.keys(recordedAssets)
+    .filter((rel) => !incoming.has(rel))
+    .sort()
+}
+
+/**
+ * Read the consumer `package.json`. Returns `{ ok, pkg }` or `{ ok:false,
+ * error }`; a missing or malformed file is an error, never an empty object.
+ */
+export function readProjectPackage(projectDir) {
+  const pkgPath = join(projectDir, 'package.json')
+  if (!existsSync(pkgPath)) return { ok: false, error: 'package.json not found' }
+  let pkg
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch (err) {
+    return { ok: false, error: `package.json is not valid JSON: ${err.message}` }
+  }
+  if (!isPlainObject(pkg)) {
+    return { ok: false, error: 'package.json must contain a JSON object' }
+  }
+  return { ok: true, pkg }
+}
+
+/**
+ * Declared direct dependencies (name -> range) of the consumer project.
+ * Returns `{ ok, dependencies }` or `{ ok:false, error }`.
+ */
+export function readDirectDependencies(projectDir) {
+  const parsed = readProjectPackage(projectDir)
+  if (!parsed.ok) return parsed
+  const deps = parsed.pkg.dependencies
+  if (deps === undefined) return { ok: true, dependencies: {} }
+  if (!isPlainObject(deps)) {
+    return { ok: false, error: 'package.json dependencies must be an object' }
+  }
+  return { ok: true, dependencies: { ...deps } }
+}
+
+/**
+ * Exact resolved versions for the named dependencies, read from the consumer's
+ * `node_modules`. A dependency that cannot be resolved is recorded as `null`
+ * (and is reported by `validatePinning`), never silently dropped.
+ */
+export function readResolvedVersions(projectDir, names) {
+  const versions = {}
+  for (const name of [...names].sort()) {
+    const pkgPath = join(projectDir, 'node_modules', name, 'package.json')
+    if (!existsSync(pkgPath)) {
+      versions[name] = null
+      continue
+    }
+    try {
+      const parsed = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      versions[name] = typeof parsed.version === 'string' ? parsed.version : null
+    } catch {
+      versions[name] = null
+    }
+  }
+  return versions
+}
+
+/** Real `yarn.lock` evidence: existence plus content hash. */
+export function readLockfile(projectDir) {
+  const lockPath = join(projectDir, 'yarn.lock')
+  if (!existsSync(lockPath)) return { ok: false, error: 'yarn.lock not found' }
+  return { ok: true, lockfile: { path: 'yarn.lock', sha256: sha256(readFileSync(lockPath)) } }
+}
+
+/**
+ * Live toolchain evidence: the actual `.yarnrc.yml` linker, the running Node
+ * version, and the pinned Yarn version from `packageManager`. A wrong linker or
+ * a missing package-manager pin is the failure mode `doctor` used to miss, so
+ * both are required.
+ */
+export function readToolchainEvidence(projectDir) {
+  const yarnrcPath = join(projectDir, '.yarnrc.yml')
+  if (!existsSync(yarnrcPath)) return { ok: false, error: '.yarnrc.yml not found' }
+  let linker = null
+  for (const line of readFileSync(yarnrcPath, 'utf8').split('\n')) {
+    const match = /^\s*nodeLinker\s*:\s*(.+?)\s*$/.exec(line)
+    if (match) {
+      linker = match[1].replace(/^['"]|['"]$/g, '')
+      break
+    }
+  }
+  if (!linker) return { ok: false, error: '.yarnrc.yml has no nodeLinker setting' }
+
+  const parsed = readProjectPackage(projectDir)
+  if (!parsed.ok) return parsed
+  const packageManager = parsed.pkg.packageManager
+  if (typeof packageManager !== 'string' || !packageManager.startsWith('yarn@')) {
+    return {
+      ok: false,
+      error: 'package.json must pin the package manager (packageManager: "yarn@<version>")',
+    }
+  }
+  const yarnVersion = packageManager.slice('yarn@'.length)
+  if (!isValidVersion(yarnVersion)) {
+    return { ok: false, error: `packageManager "${packageManager}" does not pin a valid Yarn version` }
+  }
+  return {
+    ok: true,
+    toolchain: { linker, nodeVersion: process.versions.node, yarnVersion },
+  }
+}
+
+/** Compare a live toolchain against the declared intent; collects every error. */
+export function validateToolchainEvidence(declared = TOOLCHAIN, live) {
+  const errors = []
+  if (!isPlainObject(live)) return ['toolchain evidence is missing']
+  if (live.linker !== declared.linker) {
+    errors.push(`toolchain linker "${live.linker ?? 'missing'}" must be "${declared.linker}".`)
+  }
+  if (!isValidVersion(live.nodeVersion)) {
+    errors.push('toolchain nodeVersion is missing or not a valid semver version')
+  } else if (!semver.satisfies(live.nodeVersion, declared.node)) {
+    errors.push(`Node version "${live.nodeVersion}" does not satisfy "${declared.node}".`)
+  }
+  if (live.yarnVersion != null) {
+    if (!isValidVersion(live.yarnVersion)) {
+      errors.push(`toolchain yarnVersion "${live.yarnVersion}" is not a valid semver version.`)
+    } else if (!semver.satisfies(live.yarnVersion, declared.yarn)) {
+      errors.push(`Yarn version "${live.yarnVersion}" does not satisfy "${declared.yarn}".`)
+    }
+  }
+  return errors
+}
+
+/** Assemble the declared/resolved pinning block stored in the install record. */
+export function buildPinningRecord({
+  cliVersion,
+  directDependencies,
+  resolvedVersions,
+  lockfile,
+  assets,
+}) {
+  return {
+    pinningVersion: PINNING_VERSION,
+    declared: {
+      toolchain: { ...TOOLCHAIN },
+      directDependencies: { ...directDependencies },
+      cliVersion,
+    },
+    resolved: {
+      versions: { ...resolvedVersions },
+      lockfile,
+    },
+    assets: { ...assets },
+  }
+}
+
+/**
+ * Validate the declared layer (compatibility intent) of an incoming contract
+ * before any write. Every declared range must be a real semver range; the CLI
+ * must be pinned to a range its version satisfies; `cliVersion` must be a valid
+ * version matching the distributed package; and, when `toolchain` evidence is
+ * supplied, the live linker/Node/Yarn must match the declared intent.
+ */
+export function validateDeclaredContract({
+  directDependencies,
+  cliVersion,
+  distributedVersion,
+  toolchain,
+} = {}) {
+  const errors = []
+  if (!isPlainObject(directDependencies)) {
+    errors.push('declared directDependencies is missing')
+  } else {
+    const entries = Object.entries(directDependencies)
+    if (entries.length === 0) errors.push('declared directDependencies is empty')
+    for (const [name, range] of entries) {
+      if (!isValidRange(range)) {
+        errors.push(`Dependency "${name}" has no valid compatibility range ("${range}").`)
+      }
+    }
+    if (!hasOwn(directDependencies, CLI_PACKAGE)) {
+      errors.push(`declared directDependencies must pin the CLI "${CLI_PACKAGE}".`)
+    } else if (
+      isValidVersion(cliVersion) &&
+      isValidRange(directDependencies[CLI_PACKAGE]) &&
+      !semver.satisfies(cliVersion, directDependencies[CLI_PACKAGE])
+    ) {
+      errors.push(
+        `declared CLI version "${cliVersion}" does not satisfy its range "${directDependencies[CLI_PACKAGE]}".`
+      )
+    }
+  }
+  if (!isValidVersion(cliVersion)) {
+    errors.push('declared cliVersion is missing or not a valid semver version')
+  } else if (distributedVersion && cliVersion !== distributedVersion) {
+    errors.push(
+      `declared cliVersion "${cliVersion}" does not match the distributed package version "${distributedVersion}".`
+    )
+  }
+  if (toolchain) errors.push(...validateToolchainEvidence(TOOLCHAIN, toolchain))
+  return { ok: errors.length === 0, errors }
+}
+
+function compareMaps(recorded, live, label, describe) {
+  const errors = []
+  for (const key of Object.keys(recorded)) {
+    if (!hasOwn(live, key)) errors.push(`${label} "${key}" is recorded but missing from the live project.`)
+    else if (live[key] !== recorded[key]) errors.push(describe(key))
+  }
+  for (const key of Object.keys(live)) {
+    if (!hasOwn(recorded, key)) errors.push(`${label} "${key}" is present in the live project but not recorded.`)
+  }
+  return errors
+}
+
+/**
+ * Validate a pinning block. Structural/declared/resolved/lockfile/toolchain
+ * coherence is always checked; when `live` (the actual project evidence) is
+ * supplied, the record is compared against it instead of only against itself.
+ * `includeAssets:false` skips the asset comparison so a caller can validate
+ * everything precomputable BEFORE structural writes and check assets after the
+ * copy. Returns `{ ok, errors }`.
+ */
+export function validatePinning(pinning, { distributedVersion, live, includeAssets = true } = {}) {
+  const errors = []
+  if (!isPlainObject(pinning)) {
+    return { ok: false, errors: ['install record has no pinning contract'] }
+  }
+  if (pinning.pinningVersion !== PINNING_VERSION) {
+    errors.push(
+      `pinning.pinningVersion must be ${PINNING_VERSION} (got ${JSON.stringify(pinning.pinningVersion)}).`
+    )
+  }
+
+  const declared = pinning.declared
+  let declaredDeps = {}
+  let declaredCliRange = null
+  if (!isPlainObject(declared)) {
+    errors.push('pinning.declared is missing')
+  } else {
+    const toolchain = declared.toolchain
+    if (!isPlainObject(toolchain)) {
+      errors.push('pinning.declared.toolchain is missing')
+    } else {
+      if (!isValidRange(toolchain.node)) errors.push('pinning.declared.toolchain.node is not a valid range')
+      if (!isValidRange(toolchain.yarn)) errors.push('pinning.declared.toolchain.yarn is not a valid range')
+      if (toolchain.linker !== TOOLCHAIN.linker) {
+        errors.push(`pinning.declared.toolchain.linker must be "${TOOLCHAIN.linker}".`)
+      }
+    }
+
+    const deps = declared.directDependencies
+    if (!isPlainObject(deps) || Object.keys(deps).length === 0) {
+      errors.push('pinning.declared.directDependencies is empty')
+    } else {
+      declaredDeps = deps
+      for (const [name, range] of Object.entries(deps)) {
+        if (!isValidRange(range)) {
+          errors.push(`Dependency "${name}" has no valid compatibility range ("${range}").`)
+        }
+      }
+      if (!hasOwn(deps, CLI_PACKAGE)) {
+        errors.push(`pinning.declared.directDependencies must pin the CLI "${CLI_PACKAGE}".`)
+      } else {
+        declaredCliRange = deps[CLI_PACKAGE]
+      }
+    }
+
+    if (!isValidVersion(declared.cliVersion)) {
+      errors.push('pinning.declared.cliVersion is missing or not a valid semver version')
+    } else {
+      if (distributedVersion && declared.cliVersion !== distributedVersion) {
+        errors.push(
+          `pinning.declared.cliVersion "${declared.cliVersion}" does not match the distributed package version "${distributedVersion}".`
+        )
+      }
+      if (
+        isValidRange(declaredCliRange) &&
+        !semver.satisfies(declared.cliVersion, declaredCliRange)
+      ) {
+        errors.push(
+          `declared CLI version "${declared.cliVersion}" does not satisfy its range "${declaredCliRange}".`
+        )
+      }
+    }
+  }
+
+  const resolved = pinning.resolved
+  if (!isPlainObject(resolved)) {
+    errors.push('pinning.resolved is missing')
+  } else {
+    const versions = resolved.versions
+    if (!isPlainObject(versions)) {
+      errors.push('pinning.resolved.versions is missing')
+    } else {
+      for (const [name, range] of Object.entries(declaredDeps)) {
+        if (!hasOwn(versions, name)) {
+          errors.push(`Resolved version for "${name}" is missing.`)
+          continue
+        }
+        const version = versions[name]
+        if (!isValidVersion(version)) {
+          errors.push(`Resolved version for "${name}" is missing or not a valid semver version.`)
+          continue
+        }
+        if (isValidRange(range) && !semver.satisfies(version, range)) {
+          errors.push(`Resolved version "${version}" for "${name}" does not satisfy its range "${range}".`)
+        }
+      }
+      if (isValidVersion(declared?.cliVersion)) {
+        const cliResolved = hasOwn(versions, CLI_PACKAGE) ? versions[CLI_PACKAGE] : null
+        if (cliResolved !== declared.cliVersion) {
+          errors.push(
+            `Resolved version for the CLI "${cliResolved ?? 'null'}" does not match cliVersion "${declared.cliVersion}".`
+          )
+        }
+      }
+    }
+    const lockfile = resolved.lockfile
+    if (!isPlainObject(lockfile)) {
+      errors.push('pinning.resolved.lockfile is missing')
+    } else if (typeof lockfile.sha256 !== 'string' || lockfile.sha256.trim() === '') {
+      errors.push('pinning.resolved.lockfile has no content hash.')
+    }
+  }
+
+  if (includeAssets) {
+    const assets = pinning.assets
+    if (!isPlainObject(assets) || Object.keys(assets).length === 0) {
+      errors.push('pinning.assets is empty')
+    } else {
+      for (const [rel, digest] of Object.entries(assets)) {
+        if (typeof digest !== 'string' || digest.trim() === '') {
+          errors.push(`Asset "${rel}" has no digest.`)
+        }
+      }
+    }
+  }
+
+  if (live) {
+    if (isPlainObject(live.directDependencies)) {
+      errors.push(
+        ...compareMaps(
+          declaredDeps,
+          live.directDependencies,
+          'Declared dependency',
+          (key) =>
+            `Declared dependency "${key}" range changed from "${declaredDeps[key]}" to "${live.directDependencies[key]}".`
+        )
+      )
+    }
+    if (isPlainObject(live.resolvedVersions) && isPlainObject(resolved?.versions)) {
+      errors.push(
+        ...compareMaps(
+          resolved.versions,
+          live.resolvedVersions,
+          'Resolved version',
+          (key) =>
+            `Resolved version for "${key}" changed from "${resolved.versions[key]}" to "${live.resolvedVersions[key]}".`
+        )
+      )
+    }
+    if (isPlainObject(live.lockfile) && resolved?.lockfile?.sha256 !== live.lockfile.sha256) {
+      errors.push('yarn.lock content hash does not match the recorded hash.')
+    }
+    if (isPlainObject(live.toolchain)) {
+      errors.push(...validateToolchainEvidence(TOOLCHAIN, live.toolchain))
+    }
+    if (includeAssets && isPlainObject(live.assets)) {
+      errors.push(
+        ...compareMaps(
+          pinning.assets ?? {},
+          live.assets,
+          'Asset',
+          (key) => `Asset "${key}" digest does not match the recorded set.`
+        )
+      )
+    }
+  }
+
+  return { ok: errors.length === 0, errors }
+}