npm - create-kywi-app - Versions diffs - 0.19.0 → 0.20.0 - Mend

create-kywi-app 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -83,28 +83,50 @@ CLAUDE.md                          thin pointer that sends a Claude Code session
 .claude/skills/kywi-personalization/SKILL.md  Claude Code project skill: confirm the use case, then
                                    build audiences, page variants, or A/B experiments — loaded
                                    automatically when the owner wants personalization or A/B testing
-lib/kywi.ts                        the ONE wiring point: kywi.config.ts → core's render path
-middleware.ts                      re-exports core's middleware (auth gate, session refresh, cookie→bearer bridge)
-app/api/v1/[...kywi]/route.ts      the versioned API (delegates to core; lifts tokens into httpOnly cookies)
+lib/kywi.ts                        the ONE wiring point: kywi.config.ts → core's render path (stamped)
+kywi.layers.ts                     GENERATED layer registry: imports every site/theme layer so core can
+                                   resolve overrides theme → site → core at build time (never edit; upgrade regenerates) (stamped)
+sites/default/index.ts             this site's layer: re-exports lib/modules.tsx as `modules` (add `templates` to override)
+sites/default/themes/default/index.tsx  the default theme's layer: `templates.nav` → components/site-nav.tsx (coupled only)
+middleware.ts                      re-exports core's middleware (auth gate, session refresh, cookie→bearer bridge) (stamped)
+app/api/v1/[...kywi]/route.ts      the versioned API — a thin delegate to core's `createApiRoute` (cookie lifting lives in core) (stamped)
+app/llms.txt/route.ts etc.        the root AX routes — thin delegates to core's `createAxRoute` (stamped: all 4 of
+                                   llms.txt, llms-full.txt, sitemap.xml, robots.txt)
 app/layout.tsx                     root <html>/<body>
 app/icon.svg                       favicon
-app/admin/[[...admin]]/page.tsx    mounts the FULL core admin (KywiAdminApp, every surface) at /admin
+app/admin/[[...admin]]/page.tsx    mounts the FULL core admin (KywiAdminApp, every surface) at /admin (stamped)
 ```
 **coupled** additionally gets `app/(site)/layout.tsx` + `app/(site)/[[...slug]]/page.tsx`
-(the public site — renders "/" and every published page at its slug), plus
-`app/(site)/site.css` and `components/site-nav.tsx`. **headless** and **decoupled**
-instead get `app/page.tsx` (returns 404 — no public rendering).
-Those two route files, `middleware.ts` and `lib/kywi.ts` are **thin,
-version-stamped delegates** (each opens with a `// kywi-render v…` comment). The
+(the public site — renders "/" and every published page at its slug, both **stamped**),
+plus `app/(site)/site.css` and `components/site-nav.tsx` (project-owned, unstamped).
+**headless** and **decoupled** instead get `app/page.tsx` (returns 404 — no public
+rendering, unstamped).
+All eleven of the files marked **(stamped)** above are **thin, version-stamped
+delegates**: the two `app/(site)` route files, `middleware.ts`, `lib/kywi.ts`,
+`kywi.layers.ts`, the API route, the four AX root routes and the admin catch-all
+page. Each opens with a `// kywi-render v2 (create-kywi-app <version>)
+sha256:<12 hex>` comment — the hash is over the file's own body, so
+`create-kywi-app upgrade` (see below) can tell an untouched generated file
+(safe to replace) from one you've edited (refused) without a diff against
+every historical emission. The
 public render path itself — content and locale resolution, SEO metadata, JSON-LD,
 feed and nav hydration, personalization, A/B assignment and the front-of-site
 editor — is shipped as `@kywi-software/core/next`, so `pnpm up
 @kywi-software/core` upgrades it. Before this, ~1,370 lines of it were copied
 into every project, where no upgrade could ever reach them again. What a project
-owns: `kywi.config.ts`, `app/(site)/site.css`, `lib/modules.tsx` and
-`components/site-nav.tsx`.
+owns: `kywi.config.ts`, `app/(site)/site.css`, `lib/modules.tsx`,
+`components/site-nav.tsx` and the layer files under `sites/**`.
+**The layer chain.** Every named artifact core renders — a module renderer, the nav,
+the front-edit overlay, the personalization runtime, the `/kywi.js` loader — is resolved
+per request as **theme → site → core**, first hit wins, from the registry `kywi.layers.ts`
+imports. To override one, export it by name from `sites/<site>/index.ts` (`modules` or
+`templates`) or from `sites/<site>/themes/<theme>/index.tsx`; never edit core or the
+generated files. Core validates the registry at startup and fails loudly when a configured
+site or theme is missing from it, when two themes of one site disagree on region names, or
+when a layer overrides a module name neither core nor `kywi.config.ts` defines.
 Note what's *not* in this list: there is no `components/admin-shell.tsx`, no
 per-route `app/admin/content/**`, no `lib/admin-auth.ts`. Since 0.2.0 the whole
@@ -159,6 +181,128 @@ It writes the same five files (`AGENTS.md`, `CLAUDE.md`, and the three
 Use `@latest` so an existing project picks up the newest guidance regardless of
 which `create-kywi-app` version originally scaffolded it.
+## Upgrading a project
+Every generated render-path file is version-stamped (see the eleven **(stamped)**
+files above), so `create-kywi-app upgrade` can prove which ones are still exactly
+what it emitted and safe to replace, versus which ones carry your own edits and
+must not be touched. Run it **from the project's root**:
+```bash
+npx create-kywi-app@latest upgrade --dry-run   # see the full report, write nothing
+npx create-kywi-app@latest upgrade             # apply it
+```
+What it does, one line per file in this order — landmarks, then layer files,
+then retired pre-0.19 glue:
+- **`created`** — a landmark file the project is missing, or a layer file
+  (`sites/<id>/index.ts`, `sites/<id>/themes/<theme>/index.tsx`) a site declared
+  in `kywi.config.ts` has none of yet.
+- **`replaced`** — a stamped landmark whose hash proves it is still untouched;
+  swapped for the current emission.
+- **`current`** — a stamped landmark that already matches the current emission
+  byte for byte.
+- **`kept`** — a layer file under `sites/**` that already exists. Layer files are
+  created once and never compared or overwritten again — from the moment they
+  exist they are the project's.
+- **`REFUSED (edited)`** / **`REFUSED (unstamped)`** — a landmark whose hash
+  doesn't match (someone's work is in it) or that carries no stamp at all
+  (predates the layered render path, or was hand-written). The exception: a
+  project scaffolded by 0.19.0 has six landmarks (the API route, the four AX
+  root routes, the admin catch-all page) that 0.19.0 emitted with no stamp at
+  all — `upgrade` recognises those six by their exact 0.19.0 bytes and
+  `replace`s them like any other untouched file, so a 0.19.0 project upgrades
+  with a plain `upgrade`, no `--force` needed.
+- **`REFUSED (legacy)`** — one of the six retired pre-0.19 files
+  (`lib/site.ts`, `lib/config.ts`, `lib/kywi-js-loader.ts`,
+  `components/kywi-js-loader.tsx`, `components/personalization-runtime.tsx`,
+  `app/(site)/kywi-front-edit.tsx`) is still present; their contents now live
+  in `@kywi-software/core/next`, and leaving a stale copy shadows the real
+  thing. `--force` turns this into **`removed`** instead.
+- **`backed up: <path> → .kywi-upgrade/<timestamp>/<path>`** — printed above any
+  `replaced`/`removed` line that `--force` produced from a refusal: the original
+  is copied there before it's touched.
+- **`warn: <path> was ejected from @kywi-software/core <v>; installed is <v>`** —
+  advisory only, for a file `create-kywi-app eject` (below) put under `sites/**`
+  whose stamped core version no longer matches the installed one.
+- **`note: …`** — advisory hints: stale `AGENTS.md` guidance (`create-kywi-app
+  agents --force` refreshes it), or an installed `@kywi-software/core` older
+  than the generated files target.
+Without `--force`, an edited or unstamped file (and the six retired files) is
+**refused, not touched** — the command reports it and leaves it exactly as it
+is. Re-run with `--force` to replace/remove refused files too; each one is
+backed up under `.kywi-upgrade/<timestamp>/` first, so nothing is discarded.
+`--dry-run` runs the identical plan and prints the identical report, but writes
+nothing.
+**Exit codes:** `0` — nothing was refused (with `--force`, every refusable file
+was replaced/removed instead). `2` — one or more files are still refused
+because `--force` wasn't passed — a CI job should treat this as "the project
+isn't caught up yet." `1` — no `kywi.config.ts` here, or it couldn't be scanned
+(the layer registry is generated from it, so the command would rather refuse to
+write anything than emit one that fails `assertLayerContracts` at boot).
+**What it never touches:** `kywi.config.ts`, `package.json`, `lib/modules.tsx`,
+`components/site-nav.tsx`, `app/(site)/site.css`, `app/layout.tsx`, and any
+`sites/**` file that already exists.
+**Where your edits belong now**, once a file is refused or you're migrating off
+a pre-0.19 project:
+- module renderers → `sites/<site>/index.ts`
+- nav / front-edit / personalization runtime / JS loader → `create-kywi-app
+  eject <artifact>` (below)
+- styles → `app/(site)/site.css`
+## Ejecting a core artifact
+Four of core's render-path client components ship as readable `.tsx` sources
+inside `@kywi-software/core`'s `eject/` folder, one per name:
+| artifact                  | source file                    |
+| -------------------------- | ------------------------------- |
+| `nav`                      | `site-nav.tsx`                  |
+| `frontEdit`                 | `front-edit.tsx`                |
+| `personalizationRuntime`    | `personalization-runtime.tsx`   |
+| `jsLoader`                  | `kywi-js-loader.tsx`            |
+```bash
+npx create-kywi-app@latest eject <artifact> [--site <id>] [--theme <name>] [--layer site|theme] [--force]
+```
+It copies the named artifact into the project as a layer override you own —
+`sites/<site>/themes/<theme>/<file>.tsx` by default (`--layer theme`; `--site`
+defaults to the first site `kywi.config.ts` declares, `--theme` to that site's
+own configured theme), or `sites/<site>/<file>.tsx` with `--layer site`
+(`--theme` is meaningless there — a site layer isn't per-theme). The copy opens with two stamp
+lines: `'use client'` first (a directive after any other line is inert, so this
+has to stay first), then `// kywi-eject <artifact> (@kywi-software/core
+<version>)` — the provenance `create-kywi-app upgrade` reads to warn when
+core's copy has since moved on.
+When the target layer's index file still has the shape `create-kywi-app`
+generates, `eject` also **wires** the copy into that layer's `templates`
+export automatically (dropping any import that pointed the same entry at its
+previous component, so a re-eject with `--force` doesn't stack imports). When
+the index has been hand-edited into some other shape, it refuses to touch that
+file and prints the two lines to add by hand instead — an import line and a
+`<artifact>: <ExportName>,` entry for inside `templates`.
+`--force` here means something different than in `upgrade`: it overwrites an
+**existing ejected file** at the target path (without it, `eject` refuses to
+clobber one). Needs `node_modules` installed, and an installed
+`@kywi-software/core >= 0.20.0` (the first release that ships `eject/`).
+Ejecting is a deliberate, one-artifact opt-out of core upgrades: from that
+moment the file is the project's own, `pnpm up @kywi-software/core` can no
+longer reach it, and `create-kywi-app upgrade` only warns — via the `warn:`
+line above — when the installed core has moved past the version it was copied
+from. Reach for it when you need to change the behaviour of one of these four
+components; everything else (module renderers, styles) has a lighter-weight
+home — see "Where your edits belong now" above.
 ## Installing the generated packages
 All `@kywi-software/*` packages (`core`, `cli`, `sdk`, `mcp`, `js`) are

package/bin/create-kywi-app.mjs CHANGED Viewed

@@ -18,6 +18,8 @@ import { stdin, stdout, argv, exit } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { buildFileSet, guidanceFileSet, detectAgentsLandmarks } from '../lib/templates.mjs'
+import { planUpgrade, applyUpgrade, formatReport, exitCodeFor } from '../lib/upgrade.mjs'
+import { planEject, applyEject, wiringHints } from '../lib/eject.mjs'
 const MODES = ['coupled', 'headless', 'decoupled']
 const DB_PROVIDERS = ['postgresql', 'mysql']
@@ -38,19 +40,41 @@ function readKywiVersion() {
 // ── Arg parsing ───────────────────────────────────────────────────────────────
 function parseArgs(args) {
-  const opts = { name: undefined, yes: false, mode: undefined, db: undefined, auth: undefined, help: false, force: false, positional: [] }
+  const opts = {
+    name: undefined,
+    yes: false,
+    mode: undefined,
+    db: undefined,
+    auth: undefined,
+    help: false,
+    force: false,
+    // Parsed for the subcommands that offer a preview of the edits they would
+    // make; `eject` always writes, so it ignores this one.
+    dryRun: false,
+    site: undefined,
+    theme: undefined,
+    layer: undefined,
+    positional: [],
+  }
   const positional = opts.positional
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
     if (arg === '--yes' || arg === '-y') opts.yes = true
     else if (arg === '--help' || arg === '-h') opts.help = true
     else if (arg === '--force' || arg === '-f') opts.force = true
+    else if (arg === '--dry-run') opts.dryRun = true
     else if (arg === '--mode') opts.mode = args[++i]
     else if (arg.startsWith('--mode=')) opts.mode = arg.slice(7)
     else if (arg === '--db') opts.db = args[++i]
     else if (arg.startsWith('--db=')) opts.db = arg.slice(5)
     else if (arg === '--auth') opts.auth = args[++i]
     else if (arg.startsWith('--auth=')) opts.auth = arg.slice(7)
+    else if (arg === '--site') opts.site = args[++i]
+    else if (arg.startsWith('--site=')) opts.site = arg.slice(7)
+    else if (arg === '--theme') opts.theme = args[++i]
+    else if (arg.startsWith('--theme=')) opts.theme = arg.slice(8)
+    else if (arg === '--layer') opts.layer = args[++i]
+    else if (arg.startsWith('--layer=')) opts.layer = arg.slice(8)
     else if (!arg.startsWith('-')) positional.push(arg)
   }
   if (positional.length > 0) opts.name = positional[0]
@@ -68,13 +92,30 @@ Usage:
                                                .claude/skills/) in the CURRENT
                                                Kywi project — run it from the
                                                project root
+  create-kywi-app upgrade [--dry-run] [--force]
+                                               Bring the CURRENT project's
+                                               generated render path up to this
+                                               create-kywi-app: replace stamped,
+                                               unedited files, create what is
+                                               missing, and report anything it
+                                               refuses to touch
+  create-kywi-app eject <artifact>             Copy one of core's render
+                                               artifacts into this project as a
+                                               layer override you own
 Options:
   --yes, -y            Use defaults, skip prompts
   --mode <mode>        coupled | headless | decoupled   (default: coupled)
   --db <provider>      postgresql | mysql               (default: postgresql)
   --auth <list>        comma-separated: credentials,google,github  (default: credentials)
+  --site <id>          eject: which site's layer      (default: the first site in kywi.config.ts)
+  --theme <name>       eject: which theme's layer     (default: that site's theme)
+  --layer <layer>      eject: site | theme            (default: theme)
   --force, -f          agents: overwrite existing guidance files (default: skip them)
+                       upgrade: replace edited/unstamped/legacy files too — each
+                       original is copied to .kywi-upgrade/<timestamp>/ first
+  --dry-run            upgrade: print the full report, write nothing
+                       eject: overwrite an existing override
   --help, -h           Show this help
 Examples:
@@ -83,6 +124,13 @@ Examples:
   npx create-kywi-app blog --mode headless --auth credentials,google
   npx create-kywi-app@latest agents          # add guidance to an existing project
   npx create-kywi-app@latest agents --force  # refresh it to the latest version
+  npx create-kywi-app@latest upgrade --dry-run  # see what an upgrade would change
+  npx create-kywi-app@latest upgrade            # apply it
+Exit codes (upgrade): 0 nothing refused · 2 something was refused · 1 the project
+or its kywi.config.ts could not be read.
+  npx create-kywi-app@latest eject nav       # own the site nav in this theme
+  npx create-kywi-app@latest eject frontEdit --layer site
 `)
 }
@@ -256,8 +304,83 @@ async function runAgentsCommand(opts) {
   return 0
 }
+// ── `upgrade` subcommand ──────────────────────────────────────────────────────
+/**
+ * `create-kywi-app upgrade [--dry-run] [--force]` — bring an existing project's
+ * generated render path up to this create-kywi-app's emission. The whole
+ * decision lives in ../lib/upgrade.mjs (planned, applied, formatted and scored
+ * separately so it is unit-testable and so `--dry-run` cannot drift from a real
+ * run); this wrapper is just cwd + stdout + exit code.
+ */
+async function runUpgradeCommand(opts) {
+  const plan = planUpgrade(process.cwd(), { force: opts.force, dryRun: opts.dryRun })
+  const applied = applyUpgrade(plan, { dryRun: opts.dryRun })
+  stdout.write(formatReport(plan, applied))
+  return exitCodeFor(plan)
+}
+// ── `eject` subcommand ────────────────────────────────────────────────────────
+/**
+ * `create-kywi-app eject <artifact> [--site <id>] [--theme <name>] [--layer site|theme] [--force]`
+ *
+ * Copies one of core's render artifacts (`nav`, `frontEdit`,
+ * `personalizationRuntime`, `jsLoader`) into this project's layer chain as an
+ * override the project owns, and wires it into that layer's `templates` export.
+ * The mechanics live in ../lib/eject.mjs; this is argument handling and the
+ * report — including the cost, stated plainly: the copy stops following core.
+ */
+async function runEjectCommand(opts) {
+  const cwd = process.cwd()
+  // positional[0] is the subcommand name itself.
+  const artifact = opts.positional[1]
+  let plan
+  let result
+  try {
+    plan = planEject(cwd, { artifact, site: opts.site, theme: opts.theme, layer: opts.layer })
+    result = applyEject(plan, { force: opts.force })
+  } catch (err) {
+    if (!err?.userFacing) throw err
+    stdout.write(`\n✖ ${err.message}\n`)
+    return err.exitCode ?? 1
+  }
+  stdout.write(`\n${result.overwrote ? 'overwrote' : 'ejected'}: ${plan.targetRel}\n`)
+  if (result.wired) {
+    stdout.write(`wired: ${plan.indexRel}\n`)
+  } else {
+    const [importLine, entryLine] = wiringHints(plan)
+    stdout.write(`not wired (edit by hand): ${plan.indexRel}\n`)
+    stdout.write(`  ${importLine}\n`)
+    stdout.write(`  ${entryLine}   ← inside its \`templates\` object\n`)
+  }
+  const where = plan.theme ? `site "${plan.site}", theme "${plan.theme}"` : `site "${plan.site}"`
+  stdout.write(
+    `\n✔ ${plan.artifact} is now a ${plan.layer}-layer override for ${where}. ` +
+      `It no longer follows core upgrades; \`create-kywi-app upgrade\` will warn when core ${plan.coreVersion} moves.\n`,
+  )
+  return 0
+}
 // ── Main ──────────────────────────────────────────────────────────────────────
+/**
+ * Subcommands that operate on the CURRENT project rather than scaffolding a new
+ * one. A bare first positional that is not a key here is a project name, which
+ * is why the table is consulted before anything else runs. Null-prototyped so a
+ * project literally named `constructor` or `toString` scaffolds instead of
+ * dispatching to something off Object.prototype.
+ */
+const COMMANDS = {
+  __proto__: null,
+  agents: runAgentsCommand,
+  upgrade: runUpgradeCommand,
+  eject: runEjectCommand,
+}
 async function main() {
   const opts = parseArgs(argv.slice(2))
   if (opts.help) {
@@ -265,11 +388,10 @@ async function main() {
     return 0
   }
-  // Subcommand: `create-kywi-app agents [--force]` refreshes the agent-guidance
-  // files in an existing project instead of scaffolding a new one.
-  if (opts.positional[0] === 'agents') {
-    return runAgentsCommand(opts)
-  }
+  // A subcommand (`agents`, `upgrade`, `eject`) acts on the CURRENT project instead of
+  // scaffolding a new one.
+  const cmd = COMMANDS[opts.positional[0]]
+  if (cmd) return cmd(opts)
   let answers
   try {