create-kywi-app 0.18.0 → 0.20.0

package/lib/upgrade.mjs

@@ -0,0 +1,490 @@
+/**
+ * `create-kywi-app upgrade` — bring an EXISTING project's generated render path
+ * up to the current create-kywi-app emission (plan E3 Task 6).
+ *
+ * WHAT MAKES THIS SAFE. Every render-path file the scaffold writes opens with a
+ * {@link renderStamp}: a version, the CLI that wrote it, and a hash of the body
+ * that follows. So this command never has to guess whether a file is still
+ * create-kywi-app's own output — `detectRenderLandmarks` tells it. A file whose
+ * hash still matches is untouched generated code and is replaced without
+ * ceremony; a file whose hash does NOT match carries someone's work and is
+ * REFUSED; a file with no stamp at all predates the layered shape (or was
+ * hand-written) and is refused for the same reason — UNLESS its whole-content
+ * hash matches a known historical unstamped emission ({@link
+ * KNOWN_UNSTAMPED_EMISSIONS}, e.g. the six render files create-kywi-app 0.19.0
+ * wrote with no stamp at all), in which case it is replaced exactly as an
+ * intact stamped file would be. `--force` overrides a real refusal, but only
+ * after copying the original into `.kywi-upgrade/<timestamp>/`.
+ *
+ * WHAT IT NEVER TOUCHES. The project-owned files: `kywi.config.ts`,
+ * `lib/modules.tsx`, `components/site-nav.tsx`, `app/(site)/site.css` and
+ * everything under `sites/`. The layer files under `sites/` are CREATED when a
+ * configured site has none (otherwise the project would not boot — core's
+ * `assertLayerContracts` throws), and then left alone forever.
+ *
+ * THE REGISTRY COMES FROM THE PROJECT, NOT THE SCAFFOLD. `kywi.layers.ts` must
+ * enumerate the sites *this* config declares, so it is regenerated from
+ * `scanKywiConfig(kywi.config.ts)` — and when that scan reports a problem, the
+ * command REFUSES to generate anything at all rather than emitting a registry
+ * that would fail `assertLayerContracts` at boot.
+ *
+ * Structure: {@link planUpgrade} is pure (reads the project, writes nothing),
+ * {@link applyUpgrade} performs the writes, {@link formatReport} renders, and
+ * {@link exitCodeFor} decides the process exit code. `--dry-run` runs all four
+ * with the writes suppressed, which is why the dry run's report and exit code
+ * are the real ones by construction rather than by a parallel code path.
+ */
+
+import {
+  copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync,
+} from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+import {
+  RENDER_LANDMARK_PATHS,
+  LEGACY_RENDER_FILES,
+  KNOWN_UNSTAMPED_EMISSIONS,
+  GUIDANCE_VERSION,
+  buildFileSet,
+  detectRenderLandmarks,
+  hashRenderBody,
+  kywiLayers,
+  layerFilesFor,
+  packageVersion,
+  registryLayout,
+  renderLandmarks,
+} from './templates.mjs'
+import { scanKywiConfig } from './config-scan.mjs'
+
+/**
+ * The stamp `create-kywi-app eject` writes at the top of an artifact it copies
+ * out of core, recording WHICH artifact and which core version it came from.
+ * This command only READS it: an ejected file is project-owned from the moment
+ * it lands, so the most `upgrade` can do is point out that core has moved on
+ * underneath it. Matched against the first TWO lines, because an ejected React
+ * component may legitimately open with its `import`/`'use client'` line.
+ */
+const EJECT_STAMP_RE = /^\/\/ kywi-eject (\S+) \(@kywi-software\/core ([^)]+)\)$/m
+
+/** The one guidance stamp `agents` writes as AGENTS.md's first line. */
+const GUIDANCE_STAMP_RE = /^<!-- kywi-agent-guidance v(\d+) \(create-kywi-app ([^)]+)\) -->$/
+
+/**
+ * @typedef {'create'|'replace'|'current'|'kept'|'refused'|'removed'} UpgradeAction
+ * @typedef {{
+ *   kind: 'landmark'|'layer'|'legacy',
+ *   path: string,
+ *   action: UpgradeAction,
+ *   reason: 'edited'|'unstamped'|'legacy'|null,
+ *   content: string|null,
+ *   backup: string|null,
+ * }} UpgradeEntry
+ */
+
+// ── planning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Decide everything the run will do, WITHOUT writing a byte. `force` is an input
+ * rather than a post-hoc filter because it changes an entry's outcome (a refused
+ * landmark becomes a backed-up replacement), and the report, the writes and the
+ * exit code must all agree about that single decision.
+ *
+ * @param {string} projectDir  absolute path to the project root
+ * @param {{ force?: boolean, dryRun?: boolean }} [options]
+ * @returns {{
+ *   projectDir: string, projectName: string, force: boolean, dryRun: boolean,
+ *   ok: boolean, gate: { kind: 'no-project'|'scan', problems: string[] }|null,
+ *   mode: string|null, modeDetected: boolean,
+ *   entries: UpgradeEntry[], warns: string[], notes: string[], backupDir: string|null,
+ * }}
+ */
+export function planUpgrade(projectDir, { force = false, dryRun = false } = {}) {
+  /** @type {ReturnType<typeof planUpgrade>} */
+  const plan = {
+    projectDir,
+    projectName: basename(projectDir) || 'kywi-app',
+    force: Boolean(force),
+    dryRun: Boolean(dryRun),
+    ok: false,
+    gate: null,
+    mode: null,
+    modeDetected: false,
+    entries: [],
+    warns: [],
+    notes: [],
+    backupDir: null,
+  }
+
+  const configPath = join(projectDir, 'kywi.config.ts')
+  if (!existsSync(configPath)) {
+    plan.gate = { kind: 'no-project', problems: [] }
+    return plan
+  }
+
+  const scan = scanKywiConfig(readFileSync(configPath, 'utf8'))
+  plan.mode = scan.mode ?? 'coupled'
+  plan.modeDetected = scan.mode !== null
+
+  // The refusal that matters most. `registryLayout` deliberately keeps a site
+  // whose theme could not be read (`theme: null`) rather than dropping it, so a
+  // partial scan would produce a registry that core's `assertLayerContracts`
+  // rejects at boot — a broken deploy instead of a message. Refuse here.
+  if (scan.problems.length > 0 || scan.sites.length === 0) {
+    plan.gate = {
+      kind: 'scan',
+      problems: scan.problems.length > 0
+        ? scan.problems.slice()
+        : ['no sites found — every Kywi project declares at least one site, and the layer registry is built from that list.'],
+    }
+    return plan
+  }
+
+  plan.ok = true
+
+  const layout = registryLayout(scan)
+  const backupDir = `.kywi-upgrade/${new Date().toISOString().replace(/:/g, '-')}`
+
+  // The current emission for this project's MODE. Every landmark but the
+  // registry has fixed content; the registry is built from the project's own
+  // config, which is the whole point of scanning it.
+  const emitted = buildFileSet({
+    projectName: sanitizeProjectName(plan.projectName),
+    mode: plan.mode,
+    dbProvider: 'postgresql',
+    authProviders: ['credentials'],
+    kywiVersion: packageVersion(),
+  })
+  const expectedFor = (key, rel) => (key === 'layers' ? kywiLayers(layout) : emitted[rel])
+
+  // 1. Landmarks, in RENDER_LANDMARK_PATHS order.
+  const wanted = renderLandmarks(plan.mode)
+  const detected = detectRenderLandmarks(projectDir)
+  for (const [key, rel] of Object.entries(RENDER_LANDMARK_PATHS)) {
+    // A landmark this mode does not have is not this project's file. A headless
+    // project is not missing `app/(site)/layout.tsx`; it correctly has none.
+    if (!wanted[key]) continue
+    const expected = expectedFor(key, rel)
+    const d = detected[key]
+
+    if (!d.present) {
+      plan.entries.push(entry('landmark', rel, 'create', null, expected))
+      continue
+    }
+
+    const actual = readFileSync(join(projectDir, rel), 'utf8')
+    if (actual === expected) {
+      plan.entries.push(entry('landmark', rel, 'current', null, null))
+      continue
+    }
+
+    const stamped = d.version !== null
+    // `intact === null` on a stamped file means the stamp carries no hash, which
+    // is only legitimate for the pre-E3 v1 stamp. A v2 stamp without a hash was
+    // hand-assembled, so its integrity is unknowable and it is treated as
+    // unstamped rather than trusted.
+    const replaceable = stamped && (d.intact === true || (d.intact === null && d.version === 1))
+    // An UNSTAMPED file may still be a KNOWN historical create-kywi-app
+    // emission — e.g. the six render files 0.19.0 wrote with no stamp at all
+    // (see KNOWN_UNSTAMPED_EMISSIONS's doc comment in templates.mjs). Its
+    // whole-content hash (there is no stamp line to split off) proves that
+    // just as reliably as a stamp's hash proves an intact stamped file.
+    const knownUnstamped = !stamped && KNOWN_UNSTAMPED_EMISSIONS[rel]?.[hashRenderBody(actual)] !== undefined
+    if (replaceable || knownUnstamped) {
+      plan.entries.push(entry('landmark', rel, 'replace', null, expected))
+    } else {
+      const reason = stamped && d.intact === false ? 'edited' : 'unstamped'
+      plan.entries.push(refusal('landmark', rel, reason, expected, plan.force, backupDir))
+    }
+  }
+
+  // 2. Layer files: created when a configured site has none, never compared and
+  //    never overwritten — from the moment they exist they are the project's.
+  for (const [rel, content] of Object.entries(layerFilesFor(layout, plan.mode))) {
+    plan.entries.push(
+      existsSync(join(projectDir, rel))
+        ? entry('layer', rel, 'kept', null, null)
+        : entry('layer', rel, 'create', null, content),
+    )
+  }
+
+  // 3. Retired pre-E1 glue: its contents live in @kywi-software/core/next now,
+  //    and leaving a stale copy in the project shadows the real thing.
+  for (const rel of LEGACY_RENDER_FILES) {
+    if (!existsSync(join(projectDir, rel))) continue
+    plan.entries.push(refusal('legacy', rel, 'legacy', null, plan.force, backupDir))
+  }
+
+  if (plan.entries.some((e) => e.backup)) plan.backupDir = backupDir
+
+  // 4. Advisory only, in report order: ejected artifacts, then the two version
+  //    hints. None of these ever cause a write or change the exit code.
+  const installedCore = installedCoreVersion(projectDir)
+  for (const { path, artifact, version } of scanEjectedArtifacts(projectDir)) {
+    if (installedCore === null || version === installedCore) continue
+    plan.warns.push(`${path} was ejected from @kywi-software/core ${version}; installed is ${installedCore}`)
+  }
+  if (installedCore !== null && isOlderMinor(installedCore, packageVersion())) {
+    plan.notes.push(
+      `this project depends on @kywi-software/core ${installedCore}; the generated files target ${packageVersion()}. Bump @kywi-software/* to match.`,
+    )
+  }
+  const guidance = staleGuidance(projectDir)
+  if (guidance !== null) {
+    plan.notes.push(
+      `AGENTS.md guidance is from create-kywi-app ${guidance}; run \`create-kywi-app agents --force\` to refresh.`,
+    )
+  }
+
+  return plan
+}
+
+/** @returns {UpgradeEntry} */
+function entry(kind, path, action, reason, content) {
+  return { kind, path, action, reason, content, backup: null }
+}
+
+/**
+ * A file this command will not silently overwrite. Without `--force` it stays a
+ * refusal; with it, the original is backed up first and then replaced (a
+ * landmark) or removed (retired glue).
+ * @returns {UpgradeEntry}
+ */
+function refusal(kind, path, reason, content, force, backupDir) {
+  if (!force) return { kind, path, action: 'refused', reason, content, backup: null }
+  return {
+    kind,
+    path,
+    action: kind === 'legacy' ? 'removed' : 'replace',
+    reason,
+    content,
+    backup: `${backupDir}/${path}`,
+  }
+}
+
+/** buildFileSet writes the name into package.json/README; keep it legal there. */
+function sanitizeProjectName(name) {
+  return name.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'kywi-app'
+}
+
+// ── the advisory scanners ─────────────────────────────────────────────────────
+
+/**
+ * The `@kywi-software/core` version this project actually runs: the installed
+ * package if there is one (the truth), else the declared dependency range with
+ * its `^`/`~` stripped (the intent). No semver parsing — a range like
+ * `>=0.19 <1` comes back as-is and simply never equals a concrete version, which
+ * costs a warn line and never a wrong write.
+ * @returns {string|null}
+ */
+function installedCoreVersion(projectDir) {
+  const installed = join(projectDir, 'node_modules/@kywi-software/core/package.json')
+  if (existsSync(installed)) {
+    try {
+      const version = JSON.parse(readFileSync(installed, 'utf8')).version
+      if (typeof version === 'string' && version) return version
+    } catch {
+      /* an unreadable installed package.json — fall through to the declared range */
+    }
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'))
+    const range = pkg?.dependencies?.['@kywi-software/core']
+    if (typeof range === 'string' && range) return range.replace(/^[\^~]/, '')
+  } catch {
+    /* no/invalid package.json — nothing to compare against */
+  }
+  return null
+}
+
+/** `0.9.0` is older than `0.19.0`; a string compare would say otherwise. */
+function isOlderMinor(installed, target) {
+  const parse = (v) => String(v).split('.').slice(0, 2).map((p) => Number.parseInt(p, 10))
+  const [im, in_] = parse(installed)
+  const [tm, tn] = parse(target)
+  if (![im, in_, tm, tn].every(Number.isFinite)) return false
+  return im !== tm ? im < tm : in_ < tn
+}
+
+/**
+ * Every `.ts`/`.tsx` under `sites/**` that opens with an eject stamp.
+ * @returns {Array<{ path: string, artifact: string, version: string }>}
+ */
+function scanEjectedArtifacts(projectDir) {
+  const out = []
+  const root = join(projectDir, 'sites')
+  if (!existsSync(root)) return out
+  const stack = [root]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    let dirents
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const dirent of dirents) {
+      const abs = join(dir, dirent.name)
+      if (dirent.isDirectory()) {
+        stack.push(abs)
+        continue
+      }
+      if (!/\.tsx?$/.test(dirent.name)) continue
+      let head
+      try {
+        head = readFileSync(abs, 'utf8').split('\n').slice(0, 2).join('\n')
+      } catch {
+        continue
+      }
+      const match = EJECT_STAMP_RE.exec(head)
+      if (match) {
+        out.push({ path: relative(projectDir, abs), artifact: match[1], version: match[2] })
+      }
+    }
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
+/**
+ * The create-kywi-app version AGENTS.md's guidance stamp names, when that
+ * guidance is stale (older surface version, or a different CLI). `null` when
+ * there is no AGENTS.md or it is already current. An AGENTS.md with no stamp at
+ * all is stale by definition — it predates the stamp.
+ * @returns {string|null}
+ */
+function staleGuidance(projectDir) {
+  const abs = join(projectDir, 'AGENTS.md')
+  if (!existsSync(abs)) return null
+  let firstLine
+  try {
+    firstLine = readFileSync(abs, 'utf8').split('\n')[0].trim()
+  } catch {
+    return null
+  }
+  const match = GUIDANCE_STAMP_RE.exec(firstLine)
+  if (match === null) return 'an unknown version'
+  const [, version, cliVersion] = match
+  if (Number(version) < GUIDANCE_VERSION || cliVersion !== packageVersion()) return cliVersion
+  return null
+}
+
+// ── applying ──────────────────────────────────────────────────────────────────
+
+/**
+ * Perform the plan's writes. Under `dryRun` it walks the identical branches and
+ * skips only the syscalls, so what it REPORTS having done is what a real run
+ * would do — the dry run cannot drift from the real one.
+ *
+ * @param {ReturnType<typeof planUpgrade>} plan
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ backedUp: Array<{ path: string, to: string }>, written: string[], removed: string[] }}
+ */
+export function applyUpgrade(plan, { dryRun = plan.dryRun } = {}) {
+  const applied = { backedUp: [], written: [], removed: [] }
+  if (!plan.ok) return applied
+
+  for (const e of plan.entries) {
+    // The backup comes FIRST and unconditionally: a --force that replaced a file
+    // before copying it would destroy the work on any failure in between.
+    if (e.backup) {
+      if (!dryRun) writeCopy(join(plan.projectDir, e.path), join(plan.projectDir, e.backup))
+      applied.backedUp.push({ path: e.path, to: e.backup })
+    }
+    if (e.action === 'create' || e.action === 'replace') {
+      if (!dryRun) {
+        const abs = join(plan.projectDir, e.path)
+        mkdirSync(dirname(abs), { recursive: true })
+        writeFileSync(abs, e.content, 'utf8')
+      }
+      applied.written.push(e.path)
+    } else if (e.action === 'removed') {
+      if (!dryRun) rmSync(join(plan.projectDir, e.path), { force: true })
+      applied.removed.push(e.path)
+    }
+  }
+  return applied
+}
+
+function writeCopy(from, to) {
+  mkdirSync(dirname(to), { recursive: true })
+  copyFileSync(from, to)
+}
+
+// ── reporting ─────────────────────────────────────────────────────────────────
+
+const ACTION_LABEL = {
+  create: 'created',
+  replace: 'replaced',
+  current: 'current',
+  kept: 'kept',
+  removed: 'removed',
+}
+
+/**
+ * The whole run as text: one line per path in plan order (landmarks, then layer
+ * files, then retired glue), then the ejected-artifact warns, the version notes
+ * and the summary.
+ *
+ * @param {ReturnType<typeof planUpgrade>} plan
+ * @param {ReturnType<typeof applyUpgrade>} applied
+ * @returns {string}
+ */
+export function formatReport(plan, applied) {
+  if (plan.gate?.kind === 'no-project') {
+    return '\n✖ No kywi.config.ts here — run `create-kywi-app upgrade` inside a Kywi project (its root).\n'
+  }
+  if (plan.gate?.kind === 'scan') {
+    const lines = plan.gate.problems.map((p) => `✖ kywi.config.ts: ${p}\n`)
+    return `\n${lines.join('')}\nNothing was written: the layer registry is generated from this file, and a registry built from a half-read config fails at boot rather than here.\n`
+  }
+
+  const backedUp = new Map((applied?.backedUp ?? []).map(({ path, to }) => [path, to]))
+  const out = []
+  out.push(`\nUpgrading ${plan.projectName} (${plan.mode} mode)…\n`)
+  if (!plan.modeDetected) {
+    out.push('  note: no deployment mode found in kywi.config.ts — assuming `coupled`.\n')
+  }
+  if (plan.dryRun) out.push('  (dry run — nothing will be written)\n')
+
+  for (const e of plan.entries) {
+    const to = backedUp.get(e.path)
+    if (to) out.push(`  backed up: ${e.path} → ${to}\n`)
+    if (e.action === 'refused') out.push(`  REFUSED (${e.reason}): ${e.path}\n`)
+    else out.push(`  ${ACTION_LABEL[e.action]}: ${e.path}\n`)
+  }
+  for (const warn of plan.warns) out.push(`  warn: ${warn}\n`)
+  for (const note of plan.notes) out.push(`  note: ${note}\n`)
+
+  const n = countActions(plan)
+  out.push(`\n✔ ${n.create} created, ${n.replace} replaced, ${n.current} current, ${n.kept} kept, ${n.refused} refused.\n`)
+  if (n.refused > 0) {
+    out.push(
+      '  Re-run with --force to replace the refused file(s) (each is backed up under .kywi-upgrade/ first). ' +
+        'Where your edits belong now: module renderers → sites/<site>/index.ts; ' +
+        'nav / front-edit / personalization / js-loader → `create-kywi-app eject <artifact>`; ' +
+        'styles → app/(site)/site.css.\n',
+    )
+  } else if (plan.backupDir !== null) {
+    out.push(`  Originals are under ${plan.backupDir}/.\n`)
+  }
+  return out.join('')
+}
+
+function countActions(plan) {
+  const n = { create: 0, replace: 0, current: 0, kept: 0, refused: 0 }
+  for (const e of plan.entries) {
+    if (e.action === 'refused') n.refused++
+    else if (e.action in n) n[e.action]++
+  }
+  return n
+}
+
+/**
+ * 1 when the project could not be read at all, 2 while a refusal still stands
+ * (the run did NOT finish the job, and CI must notice), 0 otherwise. Independent
+ * of `dryRun` by construction: the plan already knows what `--force` resolves.
+ * @param {ReturnType<typeof planUpgrade>} plan
+ * @returns {0|1|2}
+ */
+export function exitCodeFor(plan) {
+  if (plan.gate !== null) return 1
+  return plan.entries.some((e) => e.action === 'refused') ? 2 : 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Scaffold a new Kywi CMS project — npx create-kywi-app my-site",
   "type": "module",
   "homepage": "https://github.com/Kywi-Software/kywi-cms#readme",