uniweb 1.0.0 → 1.0.2

package/src/commands/export.js

@@ -0,0 +1,116 @@
+/**
+ * Export Command
+ *
+ * Produces a self-contained, vite-built site artifact in `dist/` for
+ * hosting on a third-party CDN (Netlify, Vercel, GitHub Pages, S3 +
+ * CloudFront, etc.). Does NOT upload anywhere — `uniweb deploy --host`
+ * uploads to a third-party host; `uniweb publish` ships to Uniweb hosting.
+ *
+ * The `dist/` output bundles the runtime + foundation + content into
+ * concatenated packaging, with a vite-built `index.html` + `entry.js` +
+ * `assets/`. The user copies it to whatever host they like.
+ *
+ * Internally this is `uniweb build --bundle` plus user guidance for the
+ * upload step. The `--link` / `--bundle` flag pair is internal-only
+ * vocabulary now (Phase 2 of the CLI ergonomics overhaul); users see
+ * `uniweb publish` (Uniweb hosting), `uniweb deploy --host` (third-party),
+ * and `uniweb export` (self-contained artifact).
+ *
+ * Usage:
+ *   uniweb export                          Produce dist/ for static hosting
+ *   uniweb export --no-prerender           Skip per-page prerendered HTML
+ *   uniweb export --host <name>            Pick a host adapter for postBuild
+ *                                          (e.g. cloudflare-pages, s3-cloudfront,
+ *                                          github-pages, generic-static).
+ *                                          Default: cloudflare-pages.
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveSiteDir } from './deploy.js'
+
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m'
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
+}
+
+export async function exportSite(args = []) {
+  const siteDir = await resolveSiteDir(args, 'export')
+
+  // Pass through --no-prerender and --host. Everything else is ignored.
+  // `uniweb export` stays low-flag: the user picks the destination host
+  // themselves outside the CLI, so there's nothing to configure beyond
+  // what `uniweb build --bundle` already exposes.
+  const noPrerender = args.includes('--no-prerender')
+  const buildArgs = ['build', '--bundle']
+  if (noPrerender) buildArgs.push('--no-prerender')
+
+  const { readFlagValue } = await import('../utils/args.js')
+  const hostFlag = readFlagValue(args, '--host')
+  if (hostFlag === null) {
+    // --host with no value → prompt here so the build subprocess gets
+    // a concrete value (and doesn't re-prompt against its own argv).
+    const { promptForHost } = await import('../utils/host-prompt.js')
+    try {
+      const chosen = await promptForHost({ args })
+      buildArgs.push('--host', chosen)
+    } catch (err) {
+      say.err(err.message)
+      process.exit(1)
+    }
+  } else if (typeof hostFlag === 'string') {
+    buildArgs.push('--host', hostFlag)
+  }
+
+  say.info('Exporting site (vite build → dist/)…')
+  console.log('')
+
+  // Spawn the SAME CLI binary (process.argv[1]) — same reason as deploy.js:
+  // npx walks node_modules and could resolve to a different version.
+  try {
+    execSync(`node ${JSON.stringify(process.argv[1])} ${buildArgs.join(' ')}`, {
+      cwd: siteDir,
+      stdio: 'inherit'
+    })
+  } catch {
+    say.err('Build failed. See output above.')
+    process.exit(1)
+  }
+
+  const distDir = join(siteDir, 'dist')
+  if (!existsSync(distDir)) {
+    say.err('Build did not produce dist/.')
+    process.exit(1)
+  }
+
+  console.log('')
+  say.ok('Export complete.')
+  console.log('')
+  console.log(`  ${c.dim}Artifact:${c.reset} ${c.cyan}${distDir}${c.reset}`)
+  console.log('')
+  console.log(
+    `  ${c.dim}Upload the contents of ${c.reset}${c.cyan}dist/${c.reset}${c.dim} to your static host. Examples:${c.reset}`
+  )
+  console.log(
+    `    ${c.dim}Netlify:${c.reset} ${c.cyan}netlify deploy --prod --dir=dist${c.reset}`
+  )
+  console.log(`    ${c.dim}Vercel:${c.reset}  ${c.cyan}vercel --prod${c.reset}`)
+  console.log(
+    `    ${c.dim}S3:${c.reset}      ${c.cyan}aws s3 sync dist/ s3://your-bucket/${c.reset}`
+  )
+  console.log('')
+  console.log(
+    `  ${c.dim}For Uniweb hosting instead, use ${c.reset}${c.cyan}uniweb publish${c.reset}${c.dim}.${c.reset}`
+  )
+}

package/src/commands/families.js

@@ -0,0 +1,82 @@
+/**
+ * `uniweb families` — the standard section families this CLI knows.
+ *
+ * ⭐ NAMED AFTER THE FIELD, not after the things it lists. A developer's question
+ * is "what can I put in `family:`?", and they will type the word they just read
+ * in a `meta.js` or a doctor warning.
+ *
+ * ⚠️ IT REPORTS THE ROSTER THIS CLI SHIPS WITH, not a live fetch — the list comes
+ * from the `@uniweb/schemas` version this CLI resolved. That is the right answer,
+ * because it is also the list `uniweb doctor` matched against. A newer family
+ * than your CLI will not appear, and declaring one is not fatal either way: an
+ * unrecognized value falls back to a generic illustration.
+ */
+
+import { FAMILIES, GROUPS } from '@uniweb/schemas/families'
+import { getCliVersion } from '../versions.js'
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m'
+}
+
+export async function families(args = []) {
+  if (args.includes('--json')) {
+    // ⛔ stdout carries JSON and nothing else, so it pipes. Every human-facing
+    // line in this command goes to stdout only in the non-JSON branch.
+    process.stdout.write(
+      JSON.stringify(
+        { cliVersion: getCliVersion(), count: FAMILIES.length, groups: GROUPS, families: FAMILIES },
+        null,
+        2
+      ) + '\n'
+    )
+    return
+  }
+
+  const filter = args.find((a) => !a.startsWith('-'))
+  const shown = filter
+    ? FAMILIES.filter(
+        (f) =>
+          f.id.includes(filter.toLowerCase()) ||
+          f.label.toLowerCase().includes(filter.toLowerCase()) ||
+          f.group === filter.toLowerCase()
+      )
+    : FAMILIES
+
+  console.log('')
+  console.log(
+    `${colors.bright}Section families${colors.reset} ${colors.dim}(uniweb ${getCliVersion()})${colors.reset}`
+  )
+
+  if (shown.length === 0) {
+    console.log('')
+    console.log(`  ${colors.dim}Nothing matches "${filter}".${colors.reset}`)
+    console.log(
+      `  ${colors.dim}A name of your own is fine — it falls back to a generic illustration.${colors.reset}`
+    )
+    console.log('')
+    return
+  }
+
+  const width = Math.max(...shown.map((f) => f.id.length))
+  for (const group of GROUPS) {
+    const rows = shown.filter((f) => f.group === group.id)
+    if (rows.length === 0) continue
+    console.log('')
+    console.log(`  ${colors.bright}${group.label}${colors.reset} ${colors.dim}— ${group.description}${colors.reset}`)
+    for (const f of rows) {
+      console.log(`    ${colors.cyan}${f.id.padEnd(width)}${colors.reset}  ${colors.dim}${f.label}${colors.reset}`)
+    }
+  }
+
+  console.log('')
+  console.log(`  ${colors.dim}Declare one in a section's meta.js:  family: 'hero'${colors.reset}`)
+  console.log(
+    `  ${colors.dim}A component already named for its family needs no declaration.${colors.reset}`
+  )
+  console.log(`  ${colors.dim}--json for scripts. uniweb doctor reports what your sections resolved to.${colors.reset}`)
+  console.log('')
+}

package/src/commands/forget.js

@@ -0,0 +1,197 @@
+/**
+ * `uniweb forget` — remove what this project recorded about where it has synced and
+ * deployed. Local files only; nothing on any backend changes.
+ *
+ *   uniweb forget --server <url>   one backend
+ *   uniweb forget --all             everything — for a COPY that is to become a new project
+ *
+ * ## `--server <url>`
+ *
+ *   - that backend's section of `sync.json` — the site uuid, the record map, asset
+ *     ids, provisioned services and the rest of what it minted;
+ *   - that backend's section of `.uniweb/backend-cache.json`;
+ *   - the `deploys:` records in `deploy.yml` that name it. ⭐ Its TARGETS stay: a
+ *     target is where you chose to ship, not something the backend told us, and the
+ *     next publish there simply creates a new site.
+ *
+ * Every other backend is untouched, which is only possible because all three are
+ * keyed by backend.
+ *
+ * ## `--all`
+ *
+ * A copied project carries the original's `sync.json`, so its first push updates the
+ * ORIGINAL's site — the copy sends uuids that are the original's. `--all` deletes
+ * `sync.json`, `.uniweb/backend-cache.json` and `deploy.yml`, after which the copy's
+ * next push creates a new site.
+ *
+ * ⭐ **`deploy.yml` goes whole, targets included** *[Diego, 2026-09-21]*. Its targets
+ * name the original's destinations — its Pages project, its bucket, its domain — so a
+ * deploy from the copy would overwrite the original there. The copy's first deploy
+ * writes a fresh one.
+ *
+ * ## What neither form touches
+ *
+ * ⛔ **Record files.** A record's `$uuid` is its OWN id, not any backend's. It is
+ * written once, on the record's first push anywhere, and never changes after;
+ * removing it would delete the record's identity, which is not what forgetting a
+ * backend means. A copy keeps them too: they never reach a backend again once the
+ * map that pointed them at the original's entities is gone. *[Diego, 2026-09-20.]*
+ *
+ * ⛔ **Any backend.** Every site still exists where it was. Deleting one is a
+ * different operation, on the backend's side.
+ *
+ * ## Why it exists
+ *
+ * Two jobs. A script pushes a template site to a short-lived dev server and then
+ * removes the traces of it without discarding the rest of the project (`--server`)
+ * — which is also why traceless publish was dropped: push and pull leave traces too.
+ * And someone duplicates a project to start a new site from it (`--all`).
+ *
+ * ⚠️ **No default target.** Forgetting a backend you still use means its next push
+ * creates a second site there, so the verb makes you name it — `--server` is
+ * required even when the project has synced with only one.
+ */
+
+import { readFlagValue } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
+import { resolveSiteDir } from './deploy.js'
+import { forgetBackendCache, forgetAllBackendCaches } from '../backend/site-sync.js'
+import { clearBackend, forgetSyncStore, readBackendState } from '@uniweb/build/uwx'
+import { forgetDeploys, forgetDeployYml } from '@uniweb/build/site'
+import { syncedBackends, normalizeOrigin } from '../utils/site-identity.js'
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
+}
+
+/** "a", "a and b", "a, b and c" */
+function listed(items) {
+  return items.length < 2
+    ? items.join('')
+    : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<{ exitCode: number, forgot?: string[], removed?: string[] }>}
+ */
+export async function forget(args = []) {
+  const badFlag = checkFlags('forget', args)
+  if (badFlag) {
+    say.err(badFlag.message)
+    return { exitCode: 2 }
+  }
+
+  const all = args.includes('--all')
+  const flag = readFlagValue(args, '--server')
+  if (all && flag) {
+    say.err('Use --server <url> or --all, not both.')
+    return { exitCode: 2 }
+  }
+
+  const siteDir = await resolveSiteDir(args, 'forget')
+  const known = syncedBackends(siteDir)
+
+  if (all) return forgetAll(siteDir)
+
+  if (!flag) {
+    say.err('Name what to forget: uniweb forget --server <url>')
+    if (known.length) {
+      say.dim(`This project has synced with: ${known.join(', ')}`)
+    } else {
+      say.dim('This project has not synced with any backend.')
+    }
+    say.dim('For a copied project that should become a new one: uniweb forget --all')
+    return { exitCode: 2 }
+  }
+
+  const origin = normalizeOrigin(flag)
+  if (!origin) {
+    say.err(`Not a URL: ${flag}`)
+    return { exitCode: 2 }
+  }
+
+  // Read before removing, so the report can say what the section held.
+  const state = readBackendState(siteDir, origin)
+  const removed = []
+  if (clearBackend(siteDir, origin)) removed.push('sync.json')
+  if (forgetBackendCache(siteDir, origin)) removed.push('.uniweb/backend-cache.json')
+  let deploys = []
+  try {
+    deploys = await forgetDeploys(siteDir, origin)
+    if (deploys.length) removed.push('deploy.yml')
+  } catch (err) {
+    // Not a stop: the identity above is already forgotten, and a deploy.yml that does
+    // not parse fails every deploy on its own. Rewriting a file we could not read
+    // would be the one thing worse than leaving it.
+    say.warn(`${err.message} — its deploy records were left as they are.`)
+  }
+
+  // Idempotent on purpose: a script calls this after every run, and a second call
+  // (or a call for a backend the push never reached) is not an error.
+  if (!removed.length) {
+    say.info(`Nothing recorded for ${origin} — nothing to forget.`)
+    if (known.length) say.dim(`This project has synced with: ${known.join(', ')}`)
+    return { exitCode: 0, forgot: [origin], removed }
+  }
+
+  say.ok(`Forgot ${c.bold}${origin}${c.reset}`)
+  if (state.site?.uuid) say.dim(`site ${state.site.uuid}`)
+  const counts = [
+    ['records', state.records],
+    ['assets', state.assets]
+  ]
+    .map(([name, map]) => [name, map ? Object.keys(map).length : 0])
+    .filter(([, n]) => n > 0)
+    .map(([name, n]) => `${n} ${name}`)
+  if (counts.length) say.dim(counts.join(' · '))
+  if (deploys.length) {
+    say.dim(`deploy records: ${deploys.join(', ')} (the targets stay)`)
+  }
+  say.dim(`removed from ${listed(removed)}`)
+  say.dim('The site still exists on that backend; this removed only what this project recorded.')
+
+  return { exitCode: 0, forgot: [origin], removed }
+}
+
+/** `--all`: the three files, whole. */
+async function forgetAll(siteDir) {
+  const origins = forgetSyncStore(siteDir)
+  const cache = forgetAllBackendCaches(siteDir)
+  const targets = await forgetDeployYml(siteDir)
+
+  const removed = []
+  if (origins) removed.push('sync.json')
+  if (targets) removed.push('deploy.yml')
+  if (cache) removed.push('.uniweb/backend-cache.json')
+
+  if (!removed.length) {
+    say.info('Nothing recorded — this project has not synced or deployed anywhere.')
+    return { exitCode: 0, forgot: [], removed }
+  }
+
+  say.ok('Forgot every backend and deploy target')
+  if (origins?.length) say.dim(`backends: ${origins.join(', ')}`)
+  if (targets?.length) say.dim(`deploy targets: ${targets.join(', ')}`)
+  say.dim(`removed ${listed(removed)}`)
+  say.dim('Its next push creates a new site. Every existing site is untouched.')
+  // ⛔ The mistake this cannot prevent: running it in the ORIGINAL. That project's
+  // next push would then mint a second site on every backend. Both files are
+  // committed, so the way back is one command — say it now, while it is cheap.
+  say.dim('If this was the original rather than a copy, restore sync.json and deploy.yml from git.')
+
+  return { exitCode: 0, forgot: origins || [], removed }
+}

package/src/commands/handoff.js

@@ -0,0 +1,21 @@
+/**
+ * handoff — RESERVED (not available on the new backend yet).
+ *
+ * The "create a site and hand it off to a client" flow ran against the legacy
+ * platform (the PHP backend + Cloudflare Worker) the CLI no longer talks to. A
+ * new-backend CLI equivalent isn't built; the command name is kept reserved so a
+ * future rebuild can claim it without a breaking change.
+ */
+
+export async function handoff() {
+  console.error(
+    "\x1b[31m✗\x1b[0m `uniweb handoff` isn't available on the new backend yet."
+  )
+  console.error(
+    '  The legacy site-handoff flow was retired with the PHP backend.'
+  )
+  console.error('  Manage client sites from the Uniweb app for now.')
+  process.exit(1)
+}
+
+export default handoff