npm - create-kywi-app - Versions diffs - 0.1.0 - Mend

create-kywi-app 0.1.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 (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,146 @@
+# create-kywi-app
+Scaffold a new Kywi CMS project.
+```bash
+npx create-kywi-app my-site
+```
+Dependency-free by design (`bin/create-kywi-app.mjs` uses only Node built-ins),
+so `npx create-kywi-app` runs with nothing pre-installed. The file contents it
+writes live in `lib/templates.mjs` (`buildFileSet(answers)`), unit-tested
+independently of the CLI's prompting/arg-parsing.
+## Usage
+```bash
+npx create-kywi-app [project-name] [options]
+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)
+  --help, -h            Show this help
+```
+With no flags and a TTY, it prompts interactively (project name, DB provider,
+auth providers, deployment mode). Pass `--yes` (or run non-interactively, e.g.
+in CI) to skip straight to defaults + flags.
+```bash
+npx create-kywi-app my-site --yes
+npx create-kywi-app blog --mode headless --auth credentials,google
+```
+## Deployment modes
+Set via `--mode` (and written into the generated `kywi.config.ts`'s
+`mode` field):
+- **`coupled`** — the app renders the public site AND serves the API + admin.
+  `GET /` renders content from the DB-backed scope.
+- **`headless`** — API + admin only. `GET /` returns 404.
+- **`decoupled`** — API + admin serve here; a separate frontend consumes
+  `@kywi-software/sdk` against this app's `/api/v1`. `GET /` returns 404.
+## What gets generated
+A generated project **boots and works with zero manual edits**:
+`pnpm install && pnpm migrate && pnpm seed && pnpm dev` gives you a working admin
+at `/admin` (sign in, create + publish a page) and — in `coupled` mode — a public
+site that renders published pages at their slug.
+`buildFileSet()` writes (`lib/templates.mjs`):
+```
+package.json                       scripts (dev/build/start/migrate/seed) + deps incl. drizzle-kit + tsx
+kywi.config.ts                     defineKywiConfig/Site/Theme + a default "Page" content type
+tsconfig.json
+next.config.mjs                    the FULL config to consume core (extensionAlias, serverExternalPackages,
+                                   isomorphic-dompurify stub) — every line is load-bearing
+.env.example                       DATABASE_URL + AUTH_SECRET
+.gitignore
+README.md                          project-specific quick start (createdb, migrate, seed, dev, /admin)
+lib/dompurify-stub.js              webpack stub referenced by next.config
+lib/kywi.ts                        server runtime: DB, API handler, content scope (memoised)
+lib/config.ts                      re-export of kywi.config
+lib/admin-auth.ts                  client admin helpers, re-exported from @kywi-software/core/host-client
+lib/content-types.ts               config + built-in (page/folder/link) content-type resolver
+middleware.ts                      auth gate + session refresh + cookie→bearer bridge (over core/host)
+app/api/v1/[...kywi]/route.ts      the versioned API (delegates to core; lifts tokens into httpOnly cookies)
+app/layout.tsx                     root <html>/<body>
+components/admin-shell.tsx         minimal admin chrome (your app's own layer)
+app/admin/layout.tsx               pass-through admin segment layout
+app/admin/page.tsx                 redirect → /admin/content
+app/admin/login/page.tsx           sign-in form
+app/admin/content/page.tsx         content-type picker
+app/admin/content/[type]/…         list / new / edit + publish (core's ContentEditForm)
+```
+**coupled** additionally gets `app/(site)/layout.tsx` + `app/(site)/[[...slug]]/page.tsx`
+(the public site — renders "/" and every published page at its slug). **headless**
+and **decoupled** instead get `app/page.tsx` (returns 404 — no public rendering).
+The security-critical session plumbing (JWT verify, the httpOnly cookie contract,
+the cookie→bearer bridge) is NOT copied into every project. It lives once in
+`@kywi-software/core/host` (+ `/host-client`); the generated `middleware.ts` and
+API route are thin framework wiring over those primitives, so a `kywi` upgrade
+ships session fixes without the app hand-maintaining crypto. See
+[`docs/hosting.md`](../../docs/hosting.md) for the full host-app contract.
+The generated project's own `README.md` walks through `createdb`, copying
+`.env.example` → `.env`, `pnpm migrate`, `pnpm seed`, and `pnpm dev`. For a
+`decoupled` deployment it also shows the `@kywi-software/sdk` usage snippet (see
+`packages/sdk/README.md` in this monorepo for the current, verified SDK API).
+## Using an unpublished checkout (local packages)
+The `@kywi-software/*` packages are not published to npm yet, so the generated
+`package.json` refs (`"@kywi-software/core": "^0.1.0"`, etc.) will not install
+as-is. To scaffold against a **local checkout of this monorepo**, point those two
+deps at your built local packages before `pnpm install`.
+The most reliable way (mirrors a real npm install — dist-only, deduped React) is
+to pack the packages and reference the tarballs:
+```bash
+# 1. From the monorepo, build + pack core and cli
+pnpm --filter @kywi-software/core --filter @kywi-software/cli build
+( cd packages/core && pnpm pack --pack-destination /tmp/kywi-pkgs )
+( cd packages/cli  && pnpm pack --pack-destination /tmp/kywi-pkgs )
+# 2. Scaffold your app
+node packages/create-kywi-app/bin/create-kywi-app.mjs my-site --yes
+# 3. Repoint the two @kywi-software deps at the tarballs in my-site/package.json,
+#    AND add a pnpm override so cli's own core dependency resolves to the tarball:
+#    "dependencies": {
+#      "@kywi-software/core": "file:/tmp/kywi-pkgs/kywi-software-core-0.1.0.tgz",
+#      "@kywi-software/cli":  "file:/tmp/kywi-pkgs/kywi-software-cli-0.1.0.tgz"
+#    },
+#    "pnpm": {
+#      "overrides": {
+#        "@kywi-software/core": "file:/tmp/kywi-pkgs/kywi-software-core-0.1.0.tgz",
+#        "@kywi-software/cli":  "file:/tmp/kywi-pkgs/kywi-software-cli-0.1.0.tgz"
+#      }
+#    }
+# 4. Then the normal flow works unchanged
+cd my-site && pnpm install && createdb my_site && cp .env.example .env
+#   (set DATABASE_URL + AUTH_SECRET in .env)
+pnpm migrate && pnpm seed && pnpm dev
+```
+`file:` to a directory (`file:../kywi/packages/core`) also works but risks a
+duplicate React copy through the symlink; tarballs avoid that. Re-pack after any
+change to core/cli and re-run `pnpm install`.
+## Testing
+```bash
+pnpm --filter create-kywi-app test
+```
+`__tests__/templates.test.mjs` asserts on `buildFileSet()`'s output directly —
+no filesystem or network access required.

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

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * create-kywi-app — scaffold a new Kywi CMS project.
+ *
+ *   npx create-kywi-app my-site
+ *   npx create-kywi-app my-site --yes            # non-interactive defaults
+ *   npx create-kywi-app my-site --mode headless --db postgresql --auth credentials,google
+ *
+ * Dependency-free by design: uses only Node built-ins so `npx create-kywi-app`
+ * runs with nothing pre-installed. The actual file contents live in
+ * ../lib/templates.mjs (buildFileSet), which is unit-tested independently.
+ */
+import { mkdir, writeFile, readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { stdin, stdout, argv, exit } from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { readFileSync } from 'node:fs'
+import { buildFileSet } from '../lib/templates.mjs'
+const MODES = ['coupled', 'headless', 'decoupled']
+const DB_PROVIDERS = ['postgresql', 'mysql']
+const AUTH_CHOICES = ['credentials', 'google', 'github']
+const KYWI_VERSION = readKywiVersion()
+function readKywiVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'))
+    return pkg.version ?? '0.1.0'
+  } catch {
+    return '0.1.0'
+  }
+}
+// ── Arg parsing ───────────────────────────────────────────────────────────────
+function parseArgs(args) {
+  const opts = { name: undefined, yes: false, mode: undefined, db: undefined, auth: undefined, help: false }
+  const 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 === '--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.startsWith('-')) positional.push(arg)
+  }
+  if (positional.length > 0) opts.name = positional[0]
+  return opts
+}
+function printHelp() {
+  stdout.write(`
+create-kywi-app — scaffold a new Kywi CMS project
+Usage:
+  create-kywi-app [project-name] [options]
+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)
+  --help, -h           Show this help
+Examples:
+  npx create-kywi-app my-site
+  npx create-kywi-app my-site --yes
+  npx create-kywi-app blog --mode headless --auth credentials,google
+`)
+}
+// ── Prompting ─────────────────────────────────────────────────────────────────
+async function prompt(rl, question, def, choices) {
+  const hint = choices ? ` (${choices.join('/')})` : def ? ` (${def})` : ''
+  const answer = (await rl.question(`${question}${hint}: `)).trim()
+  return answer || def
+}
+async function resolveAnswers(opts) {
+  // Non-interactive path: flags + defaults, no TTY needed.
+  if (opts.yes || !stdin.isTTY) {
+    return normalize({
+      projectName: opts.name || 'my-kywi-app',
+      mode: opts.mode || 'coupled',
+      dbProvider: opts.db || 'postgresql',
+      auth: opts.auth || 'credentials',
+    })
+  }
+  const rl = createInterface({ input: stdin, output: stdout })
+  try {
+    const projectName = opts.name || (await prompt(rl, 'Project name', 'my-kywi-app'))
+    const dbProvider = opts.db || (await prompt(rl, 'Database provider', 'postgresql', DB_PROVIDERS))
+    const auth = opts.auth || (await prompt(rl, 'Auth providers (comma-separated)', 'credentials'))
+    const mode = opts.mode || (await prompt(rl, 'Deployment mode', 'coupled', MODES))
+    return normalize({ projectName, mode, dbProvider, auth })
+  } finally {
+    rl.close()
+  }
+}
+function normalize({ projectName, mode, dbProvider, auth }) {
+  const errors = []
+  if (!projectName || !/^[A-Za-z0-9._-]+$/.test(projectName)) {
+    errors.push(`Invalid project name "${projectName}". Use letters, numbers, dots, dashes, underscores.`)
+  }
+  if (!MODES.includes(mode)) errors.push(`Invalid mode "${mode}". Choose one of: ${MODES.join(', ')}.`)
+  if (!DB_PROVIDERS.includes(dbProvider)) errors.push(`Invalid db provider "${dbProvider}". Choose one of: ${DB_PROVIDERS.join(', ')}.`)
+  const authProviders = String(auth).split(',').map((s) => s.trim()).filter(Boolean)
+  for (const p of authProviders) {
+    if (!AUTH_CHOICES.includes(p)) errors.push(`Invalid auth provider "${p}". Choose from: ${AUTH_CHOICES.join(', ')}.`)
+  }
+  if (authProviders.length === 0) authProviders.push('credentials')
+  if (errors.length) {
+    const err = new Error(errors.join('\n'))
+    err.userFacing = true
+    throw err
+  }
+  return { projectName, mode, dbProvider, authProviders, kywiVersion: KYWI_VERSION }
+}
+// ── Generation ────────────────────────────────────────────────────────────────
+async function generate(answers, targetDir) {
+  const files = buildFileSet(answers)
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(targetDir, rel)
+    await mkdir(dirname(abs), { recursive: true })
+    await writeFile(abs, content, 'utf8')
+  }
+  return Object.keys(files)
+}
+async function isNonEmptyDir(dir) {
+  if (!existsSync(dir)) return false
+  const entries = await readdir(dir)
+  return entries.length > 0
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+  const opts = parseArgs(argv.slice(2))
+  if (opts.help) {
+    printHelp()
+    return 0
+  }
+  let answers
+  try {
+    answers = await resolveAnswers(opts)
+  } catch (err) {
+    stdout.write(`\n✖ ${err.message}\n`)
+    return 1
+  }
+  const targetDir = resolve(process.cwd(), answers.projectName)
+  // Edge case (TC-01.001): existing non-empty directory — clear error, no overwrite.
+  if (await isNonEmptyDir(targetDir)) {
+    stdout.write(`\n✖ Directory "${answers.projectName}" already exists and is not empty. Choose a different name or remove it.\n`)
+    return 1
+  }
+  stdout.write(`\nScaffolding ${answers.projectName} (${answers.mode} mode, ${answers.dbProvider})…\n`)
+  const written = await generate(answers, targetDir)
+  for (const f of written) stdout.write(`  + ${f}\n`)
+  const dbName = answers.projectName.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'kywi_app'
+  stdout.write(`
+✔ Created ${answers.projectName}/
+Next steps:
+  cd ${answers.projectName}
+  pnpm install
+  createdb ${dbName}
+  cp .env.example .env      # set DATABASE_URL + AUTH_SECRET
+  pnpm migrate
+  pnpm seed                 # prints the superadmin credentials
+  pnpm dev                  # http://localhost:3000
+Docs: https://kywi.dev/docs
+`)
+  return 0
+}
+main()
+  .then((code) => exit(code))
+  .catch((err) => {
+    stdout.write(`\n✖ Unexpected error: ${err?.stack || err}\n`)
+    exit(1)
+  })