create-kywi-app 0.18.0 → 0.20.0

package/lib/eject.mjs

@@ -0,0 +1,424 @@
+/**
+ * `create-kywi-app eject <artifact>` — the mechanics behind the subcommand.
+ *
+ * WHAT EJECTING IS. Core ships four render-path client components as readable
+ * `.tsx` under `@kywi-software/core/eject/` (built by core's
+ * `scripts/build-eject.mjs`, described by `eject/manifest.json`). This copies
+ * ONE of them into a project's layer — `sites/<site>/themes/<theme>/` by
+ * default — and wires it into that layer's `templates` export, so the layer
+ * chain renders the project's copy instead of core's. From then on the file is
+ * the project's: it stops following core upgrades, which is the whole point and
+ * also the cost, so the report says so out loud.
+ *
+ * WHY THE STAMP IS TWO LINES AND IN THAT ORDER. Line 1 is `'use client'` and
+ * nothing else may precede it: a directive that follows a comment is inert, and
+ * the copied file would silently become a Server Component — `useState` would
+ * throw at render time, far from the CLI that caused it. The provenance comment
+ * therefore goes on line 2, where `upgrade` can still find it.
+ *
+ * WHY THE WIRING IS TEXT SURGERY. `create-kywi-app` is dependency-free (Node
+ * builtins only; it runs through `npx` before the project exists), so there is
+ * no parser available — the same trade `lib/config-scan.mjs` documents. The
+ * answer is the same too: recognise ONLY the shapes this package generates, and
+ * when a file does not match one of them, refuse to touch it and print the two
+ * lines the owner should add. A hand-edited layer index is a file the CLI has no
+ * business rewriting.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { scanKywiConfig } from './config-scan.mjs'
+
+/** The first core release that ships `eject/` (plan E3). Named in the "too old" error. */
+export const MIN_EJECT_CORE_VERSION = '0.20.0'
+
+/** The two layers a project can own an artifact in, nearest-wins last. */
+export const EJECT_LAYERS = ['site', 'theme']
+
+/**
+ * A failure the user caused and can fix. `exitCode` 1 is "bad request / bad
+ * project"; 2 is reserved for "the target already exists", which `--force`
+ * overrides — a distinct code so a script can tell "already ejected" from
+ * "wrong arguments".
+ */
+export class EjectError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message)
+    this.name = 'EjectError'
+    this.exitCode = exitCode
+    this.userFacing = true
+  }
+}
+
+// ── locating core ─────────────────────────────────────────────────────────────
+
+/**
+ * The installed `@kywi-software/core` package DIRECTORY, as the PROJECT resolves
+ * it — not as this CLI does. `npx create-kywi-app` runs from a throwaway npm
+ * cache directory, so resolving from `import.meta.url` would find nothing (or,
+ * worse, some unrelated hoisted copy).
+ *
+ * Two strategies, because module resolution alone cannot answer this question
+ * for core. Core's `exports` map declares no `"./package.json"` subpath, and its
+ * `"."` entry has only an `import` condition, so BOTH
+ * `require.resolve('@kywi-software/core/package.json')` and
+ * `require.resolve('@kywi-software/core')` come back
+ * ERR_PACKAGE_PATH_NOT_EXPORTED — an `exports` map is a public API surface, and
+ * a package directory is not on it. (`import.meta.resolve` cannot stand in: its
+ * second `parent` argument is flag-gated, so it would resolve from the CLI's
+ * location rather than the project's.)
+ *
+ * So: try the manifest subpath first, which works for any package that does
+ * export it, then do what Node's resolver does and walk `node_modules` up from
+ * the project — the directory is what is wanted, and the map has no say over it.
+ * @param {string} projectDir
+ * @returns {string|null} absolute package directory, or null when not installed
+ */
+export function findCoreDir(projectDir) {
+  try {
+    return dirname(createRequire(join(projectDir, 'package.json')).resolve('@kywi-software/core/package.json'))
+  } catch {
+    /* the package's `exports` map does not publish it — walk for the directory */
+  }
+
+  let dir = projectDir
+  while (true) {
+    const candidate = join(dir, 'node_modules', '@kywi-software', 'core')
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** @param {string} coreDir */
+function installedCoreVersion(coreDir) {
+  try {
+    return JSON.parse(readFileSync(join(coreDir, 'package.json'), 'utf8')).version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+/**
+ * Locate the eject source for one artifact in the core the PROJECT has installed.
+ *
+ * The artifact names are read from the manifest rather than hard-coded here: a
+ * core that grows a fifth ejectable artifact must be ejectable with the CLI the
+ * project already has.
+ * @param {string} projectDir
+ * @param {string|undefined} artifact
+ * @returns {{ coreDir: string, coreVersion: string, artifact: string, file: string, exportName: string, sourcePath: string, sourceText: string }}
+ */
+export function resolveEjectSource(projectDir, artifact) {
+  const coreDir = findCoreDir(projectDir)
+  if (!coreDir) {
+    throw new EjectError('Install dependencies first (@kywi-software/core is not resolvable from this project).')
+  }
+
+  const manifestPath = join(coreDir, 'eject', 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    throw new EjectError(
+      `@kywi-software/core ${installedCoreVersion(coreDir)} ships no eject/ sources — ` +
+        `\`create-kywi-app eject\` needs @kywi-software/core >= ${MIN_EJECT_CORE_VERSION}. Upgrade core first.`,
+    )
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (err) {
+    throw new EjectError(`@kywi-software/core's eject/manifest.json could not be read: ${err?.message ?? err}`)
+  }
+
+  const artifacts = manifest?.artifacts ?? {}
+  const names = Object.keys(artifacts)
+  const entry = artifact && Object.prototype.hasOwnProperty.call(artifacts, artifact) ? artifacts[artifact] : null
+  if (!entry) {
+    const lead = artifact ? `Unknown artifact "${artifact}".` : 'Which artifact? Name one.'
+    throw new EjectError(
+      `${lead}\n  Choose one of: ${names.join(', ')}\n  Usage: create-kywi-app eject <artifact> [--site <id>] [--theme <name>] [--layer site|theme] [--force]`,
+    )
+  }
+
+  const sourcePath = join(coreDir, 'eject', entry.file)
+  if (!existsSync(sourcePath)) {
+    throw new EjectError(
+      `@kywi-software/core's manifest names eject/${entry.file} for "${artifact}", but that file is not installed. Reinstall @kywi-software/core.`,
+    )
+  }
+
+  return {
+    coreDir,
+    coreVersion: manifest.coreVersion ?? installedCoreVersion(coreDir),
+    artifact,
+    file: entry.file,
+    exportName: entry.exportName,
+    sourcePath,
+    sourceText: readFileSync(sourcePath, 'utf8'),
+  }
+}
+
+// ── the copied file ───────────────────────────────────────────────────────────
+
+const USE_CLIENT_RE = /^\s*(['"])use client\1\s*;?\s*$/
+
+/**
+ * Core's file, restamped for the project: `'use client'` first (see the header
+ * note — order is load-bearing), then one provenance line naming the artifact
+ * and the core version it was taken from, which is what `upgrade` reads to warn
+ * when core's copy moves on.
+ * @param {string} sourceText
+ * @param {string} artifact
+ * @param {string} coreVersion
+ */
+export function stampEjectedSource(sourceText, artifact, coreVersion) {
+  const lines = sourceText.split('\n')
+  const body = USE_CLIENT_RE.test(lines[0] ?? '') ? lines.slice(1) : lines
+  return ["'use client'", `// kywi-eject ${artifact} (@kywi-software/core ${coreVersion})`, ...body].join('\n')
+}
+
+// ── wiring the layer index ────────────────────────────────────────────────────
+
+const TEMPLATES_ANCHOR = 'export const templates = '
+const TEMPLATES_TYPE_IMPORT = "import type { KywiLayerModule } from '@kywi-software/core/next'"
+/** The generated `sites/<id>/index.ts` landmark — the shape with no templates export yet. */
+const SITE_INDEX_RE = /export\s*\{\s*moduleComponents\s+as\s+modules\s*\}/
+
+/** `site-nav.tsx` → `./site-nav`. Extensionless: the generated tsconfig uses `moduleResolution: Bundler`. */
+function importSpecifier(file) {
+  return `./${file.replace(/\.(tsx|ts|jsx|js)$/, '')}`
+}
+
+/** The two lines an owner must add by hand when the index is not a shape we generate. */
+export function wiringHints({ artifact, exportName, file }) {
+  return [`import { ${exportName} } from '${importSpecifier(file)}'`, `${artifact}: ${exportName},`]
+}
+
+/** Local bindings an import clause introduces (`{ A, B as C }`, `D`, `* as N`). */
+function importBindings(clause) {
+  const names = []
+  const braced = /\{([^}]*)\}/.exec(clause)
+  if (braced) {
+    for (const part of braced[1].split(',')) {
+      const t = part.trim()
+      if (!t) continue
+      const aliased = /^(?:type\s+)?[A-Za-z_$][\w$]*\s+as\s+([A-Za-z_$][\w$]*)$/.exec(t)
+      const plain = /^(?:type\s+)?([A-Za-z_$][\w$]*)$/.exec(t)
+      if (aliased) names.push(aliased[1])
+      else if (plain) names.push(plain[1])
+    }
+  }
+  const outside = clause.replace(/\{[^}]*\}/, '').replace(/,/g, ' ').trim()
+  const namespace = /^\*\s+as\s+([A-Za-z_$][\w$]*)$/.exec(outside)
+  if (namespace) names.push(namespace[1])
+  else if (/^[A-Za-z_$][\w$]*$/.test(outside)) names.push(outside)
+  return names
+}
+
+/** Does this line import `name`? (Single-line imports only — all this package generates.) */
+function importsBinding(line, name) {
+  const m = /^import\s+(.+?)\s+from\s+['"][^'"]+['"];?\s*$/.exec(line)
+  return m ? importBindings(m[1]).includes(name) : false
+}
+
+/** Index of the `}` matching the `{` at `open`, or -1. Braces only; enough for a templates literal. */
+function matchingBrace(text, open) {
+  let depth = 0
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === '{') depth++
+    else if (text[i] === '}' && --depth === 0) return i
+  }
+  return -1
+}
+
+/**
+ * Insert `line` after the file's last single-line `import` statement, or at the
+ * top when it has none.
+ */
+function insertImport(lines, line) {
+  let last = -1
+  for (let i = 0; i < lines.length; i++) if (/^import\s.+\sfrom\s+['"]/.test(lines[i])) last = i
+  const out = lines.slice()
+  out.splice(last + 1, 0, line)
+  return out
+}
+
+/**
+ * Wire `templates.<artifact>` in a layer index to the ejected file. PURE: takes
+ * and returns text.
+ *
+ * Three recognised shapes, and one deliberate refusal:
+ *   - a `templates` object (populated or `{}`): the entry goes in FIRST, and any
+ *     import that bound the entry's previous component is dropped — the scaffold's
+ *     theme index points `nav` at `components/site-nav`, and leaving that import
+ *     behind would declare `SiteNav` twice and fail to compile;
+ *   - the generated site index, which has no `templates` export: one is appended
+ *     in the same `satisfies` form the theme index uses;
+ *   - anything else, including a templates object whose entries are not one
+ *     `key: value,` per line: returned unchanged with `wired: false`.
+ * @param {string} indexText
+ * @param {{ artifact: string, exportName: string, file: string }} target
+ * @returns {{ text: string, wired: boolean }}
+ */
+export function wireLayerIndex(indexText, { artifact, exportName, file }) {
+  const importLine = `import { ${exportName} } from '${importSpecifier(file)}'`
+  const anchor = indexText.indexOf(TEMPLATES_ANCHOR)
+
+  // ── shape 3: the generated site index, no templates export yet ──
+  if (anchor === -1) {
+    if (!SITE_INDEX_RE.test(indexText)) return { text: indexText, wired: false }
+    const body = indexText.endsWith('\n') ? indexText : `${indexText}\n`
+    return {
+      text:
+        `${body}\n${importLine}\n${TEMPLATES_TYPE_IMPORT}\n\n` +
+        `export const templates = {\n  ${artifact}: ${exportName},\n} satisfies NonNullable<KywiLayerModule['templates']>\n`,
+      wired: true,
+    }
+  }
+
+  // ── shapes 1 + 2: an existing templates object ──
+  const open = indexText.indexOf('{', anchor + TEMPLATES_ANCHOR.length)
+  if (open === -1) return { text: indexText, wired: false }
+  const close = matchingBrace(indexText, open)
+  if (close === -1 || !indexText.slice(close).startsWith('} satisfies')) return { text: indexText, wired: false }
+
+  const inner = indexText.slice(open + 1, close)
+  /** @type {string[]} */
+  const kept = []
+  /** @type {string|null} */
+  let replacedBinding = null
+  for (const line of inner.split('\n')) {
+    if (line.trim() === '') continue
+    const m = /^\s*([A-Za-z_$][\w$]*)\s*:\s*([^,]+?),?\s*$/.exec(line)
+    // A comment, a multi-line value, a spread — not a shape we generate, so not
+    // one we rewrite.
+    if (!m) return { text: indexText, wired: false }
+    if (m[1] !== artifact) {
+      kept.push(line.trimEnd())
+      continue
+    }
+    const binding = /^([A-Za-z_$][\w$]*)/.exec(m[2].trim())
+    replacedBinding = binding ? binding[1] : null
+  }
+
+  const newInner = ['', `  ${artifact}: ${exportName},`, ...kept, ''].join('\n')
+  const rewritten = indexText.slice(0, open + 1) + newInner + indexText.slice(close)
+
+  let lines = rewritten.split('\n')
+  // Drop the import the replaced entry pointed at — including our own, on a
+  // re-eject, so `--force` stays idempotent instead of stacking imports.
+  if (replacedBinding) lines = lines.filter((line) => !importsBinding(line, replacedBinding))
+  if (!lines.some((line) => line === importLine)) lines = insertImport(lines, importLine)
+
+  return { text: lines.join('\n'), wired: true }
+}
+
+// ── plan + apply ──────────────────────────────────────────────────────────────
+
+/**
+ * Work out exactly which file this eject would write and which index it would
+ * wire, WITHOUT touching the disk. Everything that can be rejected — no Kywi
+ * project, no core, an unknown artifact, a site or theme the config does not
+ * declare — is rejected here, so `applyEject` only has to deal with the one
+ * question it can answer: does the target already exist.
+ * @param {string} projectDir
+ * @param {{ artifact?: string, site?: string, theme?: string, layer?: string }} options
+ */
+export function planEject(projectDir, { artifact, site, theme, layer } = {}) {
+  const configPath = join(projectDir, 'kywi.config.ts')
+  if (!existsSync(configPath)) {
+    throw new EjectError('No kywi.config.ts here — run `create-kywi-app eject` inside a Kywi project (its root).')
+  }
+
+  const layerName = layer ?? 'theme'
+  if (!EJECT_LAYERS.includes(layerName)) {
+    throw new EjectError(`Unknown --layer "${layer}". Choose one of: ${EJECT_LAYERS.join(', ')}.`)
+  }
+  if (layerName === 'site' && theme) {
+    throw new EjectError('--theme has no meaning with --layer site: a site layer is not per-theme. Drop one of them.')
+  }
+
+  const source = resolveEjectSource(projectDir, artifact)
+
+  const scan = scanKywiConfig(readFileSync(configPath, 'utf8'))
+  if (scan.sites.length === 0) {
+    const why = scan.problems.length ? `\n  - ${scan.problems.join('\n  - ')}` : ''
+    throw new EjectError(`No site could be read out of kywi.config.ts, so there is no layer to eject into.${why}`)
+  }
+
+  const siteId = site ?? scan.sites[0].id
+  const siteEntry = scan.sites.find((s) => s.id === siteId)
+  if (!siteEntry) {
+    throw new EjectError(
+      `Unknown site "${siteId}". kywi.config.ts declares: ${scan.sites.map((s) => s.id).join(', ')}.`,
+    )
+  }
+
+  let themeName = null
+  let dir = `sites/${siteId}`
+  let indexRel = `sites/${siteId}/index.ts`
+  if (layerName === 'theme') {
+    themeName = theme ?? siteEntry.theme
+    if (!themeName) {
+      throw new EjectError(
+        `site "${siteId}" declares no theme in kywi.config.ts — pass --theme <name>, or eject into the site layer with --layer site.`,
+      )
+    }
+    const declared = new Set([
+      ...scan.themes.map((t) => t.name),
+      ...scan.sites.map((s) => s.theme).filter(Boolean),
+    ])
+    if (!declared.has(themeName)) {
+      throw new EjectError(`Unknown theme "${themeName}". kywi.config.ts declares: ${[...declared].join(', ')}.`)
+    }
+    dir = `sites/${siteId}/themes/${themeName}`
+    indexRel = `${dir}/index.tsx`
+  }
+
+  const targetRel = `${dir}/${source.file}`
+  return {
+    projectDir,
+    artifact: source.artifact,
+    exportName: source.exportName,
+    file: source.file,
+    coreVersion: source.coreVersion,
+    layer: layerName,
+    site: siteId,
+    theme: themeName,
+    targetRel,
+    targetPath: join(projectDir, targetRel),
+    indexRel,
+    indexPath: join(projectDir, indexRel),
+    content: stampEjectedSource(source.sourceText, source.artifact, source.coreVersion),
+  }
+}
+
+/**
+ * Execute a plan: write the override, then wire the layer index if it is a shape
+ * this package generated. The index is only rewritten when the wiring succeeded,
+ * so a refusal is genuinely a no-op on that file.
+ * @param {ReturnType<typeof planEject>} plan
+ * @param {{ force?: boolean }} options
+ * @returns {{ overwrote: boolean, wired: boolean }}
+ */
+export function applyEject(plan, { force = false } = {}) {
+  const existed = existsSync(plan.targetPath)
+  if (existed && !force) {
+    throw new EjectError(`${plan.targetRel} already exists. Re-run with --force to overwrite it.`, 2)
+  }
+
+  mkdirSync(dirname(plan.targetPath), { recursive: true })
+  writeFileSync(plan.targetPath, plan.content, 'utf8')
+
+  let wired = false
+  if (existsSync(plan.indexPath)) {
+    const before = readFileSync(plan.indexPath, 'utf8')
+    const result = wireLayerIndex(before, plan)
+    wired = result.wired
+    if (wired && result.text !== before) writeFileSync(plan.indexPath, result.text, 'utf8')
+  }
+
+  return { overwrote: existed, wired }
+}