uniweb 1.0.0 → 1.0.2

package/src/utils/flag-guard.js

@@ -0,0 +1,246 @@
+/**
+ * Reject unrecognized flags on the backend verbs.
+ *
+ * Every one of these commands can send data to, or authenticate against, a remote
+ * host — and the CLI resolves flags by scanning argv for a literal, so a flag it
+ * does not recognize does not fail: it *disappears*, and the thing it was meant to
+ * change silently keeps its default.
+ *
+ * Tolerable for a cosmetic flag; dangerous for any flag that aims the command or picks
+ * its identity. This turns that class into one sentence.
+ *
+ * ⛔ **A backend flag and `--token` are NOT flags of these verbs** *(2026-09-21)*. Every
+ * backend verb goes to the backend you are logged in to, with that login's session:
+ * switching and signing in are `uniweb login` (`--server`, `--token`), and a script
+ * aims one process with UNIWEB_SERVER + UNIWEB_TOKEN. Passed to a verb, each is an
+ * unknown flag — and this guard is what makes that a loud error, with a pointer to the
+ * login, instead of a command that quietly runs against wherever and as whoever you
+ * happen to be. `--server` stays on `forget`, where it SELECTS which backend's records
+ * to remove. ⛔ *The flag was `--backend` until 2026-10-07, renamed so it is not read as
+ * a site's `backend` service; `--backend` is refused everywhere, naming `--server`.*
+ *
+ * ⚠️ A wrong rejection is worse than a missed one — it breaks an invocation that
+ * works — so the per-command lists must be complete, INCLUDING flags read by
+ * helpers rather than by the command file itself. Two live examples: `--no-validate`
+ * is consumed inside `utils/conformance.js`, and `--yes` inside
+ * `backend/foundation-bring-along.js`. Grepping only the command's own source
+ * misses both. When you add a flag anywhere on one of these paths, add it here.
+ */
+
+import { findUnknownFlags, didYouMean } from './args.js'
+
+/** Accepted by every command, wherever they are actually consumed. */
+const GLOBAL = ['--non-interactive', '--help', '-h']
+
+/**
+ * Login-method flags. Any verb that can hit an unauthenticated backend may fall
+ * into `ensureRegistryAuth`, which hands `args` to the login picker — so these are
+ * genuinely reachable from all of them, not just from `uniweb login`.
+ */
+const AUTH = ['--browser', '--password', '--token-paste']
+
+/**
+ * Flags a verb inherits by importing `commands/deploy.js` for `resolveSiteDir`.
+ * Inert on these verbs, and listed rather than filtered:
+ * accepting a flag that does nothing is exactly the pre-guard behaviour, while
+ * rejecting one that works is a broken command. The guard's job is catching
+ * `--backed`, not policing inert-but-valid spellings.
+ */
+const VIA_DEPLOY = ['--target', '--host', '--no-save']
+
+/**
+ * Per-verb flag sets. Derived by scanning each command for dash-literals AND the
+ * helpers it calls — not from the help text, which has drifted from the parser in
+ * both directions (`--yes` is documented on `publish` and consumed two files away).
+ */
+const VERBS = {
+  push: [
+    '--all', '--org', '--dry-run', '--force',
+    '--foundation', '--output', '-o', '--personal',
+    // read in utils/conformance.js and backend/site-sync.js respectively —
+    // neither appears in push.js
+    '--no-validate', '--yes',
+    // via backend/foundation-bring-along.js, which push runs since 2026-08-19 —
+    // one of the three flags that skip its prompts. Found by
+    // flag-guard-coverage.test.js the moment push gained the import, which is
+    // exactly the hand-enumeration failure that test exists to catch.
+    '--no-verify',
+    // ship content against the already-released code, releasing nothing — or
+    // release above a newer registered version instead of stopping (both bring-along)
+    '--no-release', '--bump', ...VIA_DEPLOY
+  ],
+  publish: [
+    '--org', '--dry-run', '--force', '--foundation',
+    '--personal',
+    // read in utils/conformance.js, backend/site-sync.js, and
+    // backend/foundation-bring-along.js — none appear in publish.js
+    '--no-validate', '--yes', '--no-verify', '--no-release', '--bump', ...VIA_DEPLOY
+  ],
+  pull: [
+    '--content-only', '--dry-run', '--force', '--merge',
+    '--no-assets',
+    '--no-records', '--no-delete', '--no-prune',
+    // via backend/site-sync.js (the owner resolver) and utils/conformance.js
+    '--yes', '--org', '--personal', '--no-validate', ...VIA_DEPLOY
+  ],
+  clone: [
+    '--content-only', '--no-assets', '--no-records', '--path',
+    '--project', '--org', '--personal'
+  ],
+  register: [
+    '--dry-run', '--json', '--output', '-o',
+    '--schema-only', '--scope', '--org',
+    // reach the login a register may trigger, which chooses the workspace it works in
+    '--personal'
+  ],
+  /**
+   * `forget` = remove one backend's records (`--server <url>`), or everything a
+   * copied project inherited (`--all`). One of the two is required — the verb refuses
+   * without it — and they exclude each other. `--non-interactive` reaches it through
+   * resolveSiteDir in a workspace of several sites.
+   */
+  forget: ['--server', '--all'],
+  /**
+   * `site list | unpublish | delete` — a workspace's sites. `--yes` confirms a write;
+   * `--json` is `list`'s porcelain; the workspace is `--org` / `--personal`.
+   */
+  site: ['--json', '--yes', '--org', '--personal'],
+  status: [
+    '--json', '--remote', '--dry-run',
+    '--force', '--no-verify', '--no-validate', '--yes', '--org', '--personal',
+    // inert here, reachable through the bring-along module status imports for
+    // `resolveLocalFoundation` — listed per the over-approximation note above
+    '--no-release', '--bump', ...VIA_DEPLOY
+  ],
+  /**
+   * `refresh` = `git pull`, then a DELEGATED `pull --merge`.
+   *
+   * It forwards nothing of its own argv to that pull — it builds `['--merge']`
+   * itself. So pull's own flags (`--merge`, `--force`, `--no-delete`, `--no-prune`,
+   * `--content-only`, …) are NOT reachable from a `refresh` argv and
+   * are deliberately absent here. ⚠️ `--force` especially: `refresh` is read-only by
+   * design, and forwarding it would ask pull to DISCARD local work.
+   *
+   * The trailing group is inert on this verb but reachable through the
+   * `resolveSiteDir` / `probeUnpushed` imports — listed rather than filtered, per
+   * the VIA_DEPLOY note above, and required by `flag-guard-coverage.test.js`.
+   */
+  refresh: [
+    '--no-backend', '--no-git',
+    '--org', '--personal', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
+  ]
+}
+
+/**
+ * `sync` is `refresh` + `push`, forwarding RAW argv to both halves — so its
+ * accepted set is exactly the UNION of theirs. Derived, never hand-written.
+ *
+ * Hand-writing it would rot the moment either half gained a flag, and it would rot
+ * in the expensive direction: `uniweb sync --no-git` and `uniweb sync --force` are
+ * both documented in `sync.js`, and a union that forgot either would reject a
+ * working command.
+ *
+ * ⭐ The union is also WHY `sync` checks and the two halves skip (`skipFlagCheck`,
+ * see `sync.js`). Each half's set is a strict subset of this one, so letting them
+ * re-check would have `push` reject `--no-git` and `refresh` reject `--force` —
+ * both legal on `sync`. Validating once, against the union, at the only layer that
+ * knows both halves are in play, is what makes the composite safe.
+ */
+VERBS.sync = [...new Set([...VERBS.refresh, ...VERBS.push])]
+
+/**
+ * The accepted set per verb: its own flags, plus the login-method flags every
+ * backend verb can reach, plus the globals.
+ *
+ * Derived from each verb's IMPORT GRAPH, not from its own source and not from the
+ * help text — `test/flag-guard-coverage.test.js` walks that graph and fails if a
+ * verb can honour a flag this list omits. Deliberately an over-approximation: a
+ * flag accepted here but inert costs nothing (it was ignored before the guard
+ * existed), while one rejected here breaks a working command.
+ */
+/**
+ * Read in the verbs' import graphs, and deliberately NOT accepted by them.
+ *
+ * `--token` is read by `runRegistryLogin` (utils/registry-auth.js) for
+ * `uniweb login --token <bearer>`, which seeds and STORES a session. The verbs reach
+ * that function through `ensureRegistryAuth`, which strips `--token` from their argv
+ * first — so a static walk sees the read, and no verb can honour it.
+ * `flag-guard-coverage.test.js` subtracts this list; add to it only with the same
+ * proof: a read no verb's argv can reach.
+ */
+export const LOGIN_ONLY = ['--token']
+
+export const VERB_FLAGS = Object.fromEntries(
+  Object.entries(VERBS).map(([verb, flags]) => [
+    verb,
+    [...new Set([...flags, ...AUTH])]
+  ])
+)
+
+/**
+ * Check `args` against the verb's accepted set. Returns null when everything is
+ * recognized, or a ready-to-print message naming the first offender (plus a
+ * suggestion when one is close).
+ *
+ * Reports ONE flag rather than all of them: the first is usually the cause, and a
+ * list invites skimming past the suggestion, which is the actionable half.
+ *
+ * @param {string} verb - a key of VERB_FLAGS
+ * @param {string[]} args - the argv slice for this command
+ * @returns {{ flag: string, message: string, suggestion: string|null }|null}
+ */
+export function checkFlags(verb, args = []) {
+  const known = VERB_FLAGS[verb]
+  if (!known) return null
+  const all = [...known, ...GLOBAL]
+  const unknown = findUnknownFlags(args, all)
+  if (!unknown.length) return null
+
+  const flag = unknown[0]
+  // ⭐ `--backend`, `--server` and `--token` are not typos on these verbs — they aim a
+  // command or pick its identity, which only the login does (2026-09-21), and `--backend`
+  // is `--server` since 2026-10-07. The useful answer is where each went, not "run --help".
+  if (flag === '--backend' && verb === 'forget') {
+    return {
+      flag,
+      suggestion: '--server',
+      message: '`--backend` is now `--server`: uniweb forget --server <url>'
+    }
+  }
+  if (flag === '--backend' || flag === '--server') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        `\`uniweb ${verb}\` has no \`${flag}\`: it goes to the backend you are logged in to.`,
+        '  Switch with: uniweb login --server <url>',
+        '  (A script can aim one process with UNIWEB_SERVER instead.)'
+      ].join('\n')
+    }
+  }
+  if (flag === '--token') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        `\`uniweb ${verb}\` has no \`--token\`: it uses the session of the backend you are logged in to.`,
+        '  Sign in with a token: uniweb login --server <url> --token <bearer>',
+        '  (A script can authenticate one process with UNIWEB_TOKEN instead.)'
+      ].join('\n')
+    }
+  }
+  // ⭐ `--as-org` is RETIRED (2026-09-23) with the `?as_org=` it mirrored — the request
+  // names its workspace in a header now, and `--org` is the one spelling.
+  if (flag === '--as-org' && all.includes('--org')) {
+    return {
+      flag,
+      suggestion: '--org',
+      message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
+    }
+  }
+  const suggestion = didYouMean(flag, all)
+  const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
+  if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)
+  lines.push(`  Run \`uniweb ${verb} --help\` for the accepted flags.`)
+  return { flag, suggestion, message: lines.join('\n') }
+}

package/src/utils/foundation-name.js

@@ -0,0 +1,179 @@
+/**
+ * Giving a foundation its name — `name` in `main.js`'s default export.
+ *
+ * The rule itself (main.js `name`, else package.json `name`; `src` and `foundation`
+ * refused) is `@uniweb/build`'s `foundation-name.js`, shared by the build, `register`
+ * and `push`. This module only WRITES the name: the scaffold at `create` / `add`, and
+ * `register` when it asks for one.
+ *
+ * ⛔ NO `@uniweb/build` IMPORT, AND NO IMPORT OF main.js. `uniweb create` runs before
+ * any project exists: `@uniweb/build` is an optional peer that may not be installed,
+ * and main.js's own imports may not be either. Hence text scans rather than a load,
+ * and the one duplicated fact below, pinned to the build's list by
+ * `test/foundation-name.test.js`. What a foundation IS named is always read by the
+ * build (`readFoundationName`); these only decide where to write.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+
+// The folders a foundation's code lives in — never a foundation's name
+// (`@uniweb/build`'s FORBIDDEN_FOUNDATION_NAMES; the test keeps them equal).
+export const SCAFFOLD_FOLDER_NAMES = new Set(['src', 'foundation'])
+
+// Written above the name wherever the CLI adds one — the scaffold's main.js
+// template says the same.
+const NAME_COMMENT = '// What this foundation registers as — @<org>/<name> — and what sites pin.'
+
+/**
+ * A name made from free text — a project's name, a folder's — in the form a
+ * foundation name takes: lowercase letters, digits and inner hyphens.
+ * `My Site` → `my-site`. Null when nothing usable is left, or when what is left
+ * names a folder rather than a foundation.
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function normalizeFoundationName(raw) {
+  const name = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@[^/]*\//, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return name && !SCAFFOLD_FOLDER_NAMES.has(name) ? name : null
+}
+
+/**
+ * A name to offer a foundation that has none of its own: its folder's — or, for
+ * the `src/` and `foundation/` a scaffold makes, its project's folder. Null when
+ * neither makes one.
+ *
+ * @param {string} foundationDir
+ * @returns {string|null}
+ */
+export function suggestFoundationName(foundationDir) {
+  const dir = resolve(foundationDir)
+  return (
+    normalizeFoundationName(basename(dir)) ||
+    normalizeFoundationName(basename(dirname(dir)))
+  )
+}
+
+/**
+ * Whether `main.js`'s default export names the foundation — a `name` key at the
+ * export's own level, not one nested in `props` or `vars`.
+ *
+ * A scan, not a parse (see the module note): it skips strings and comments and
+ * counts brackets, which is all an object literal of declarations needs. A name
+ * that arrives by a spread is invisible to it — the build's read is the truth.
+ *
+ * @param {string} text - main.js source
+ * @returns {boolean}
+ */
+export function mainNamesFoundation(text) {
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) return false
+  let depth = 1
+  let atKey = true // just after the opening brace, or a comma at the top level
+  for (let i = opening.index + opening[0].length; i < text.length && depth > 0; i++) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      i = text.indexOf('\n', i)
+      if (i < 0) break
+    } else if (c === '/' && text[i + 1] === '*') {
+      i = text.indexOf('*/', i + 2) + 1
+      if (i <= 0) break
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1
+      while (j < text.length && text[j] !== c) j += text[j] === '\\' ? 2 : 1
+      if (depth === 1 && atKey && text.slice(i + 1, j) === 'name' && /^\s*:/.test(text.slice(j + 1))) {
+        return true
+      }
+      i = j
+      atKey = false
+    } else if ('{[('.includes(c)) {
+      depth++
+      atKey = false
+    } else if ('}])'.includes(c)) {
+      depth--
+    } else if (depth === 1 && c === ',') {
+      atKey = true
+    } else if (depth === 1 && atKey && /[A-Za-z_$]/.test(c)) {
+      const word = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))[0]
+      // `name: 'x'`, or the shorthand `{ name }`
+      if (word === 'name' && /^\s*[:,}]/.test(text.slice(i + word.length))) return true
+      i += word.length - 1
+      atKey = false
+    } else if (!/\s/.test(c)) {
+      atKey = false
+    }
+  }
+  return false
+}
+
+/**
+ * Write `name` into a foundation's `main.js`.
+ *
+ * With `replace`, the one `name: '<replace>'` literal is rewritten — the case where
+ * main.js already names the foundation, with a name that cannot register. Without
+ * it, `name` becomes the default export's first key. A missing main.js is created.
+ *
+ * ⚠️ A text edit, not a parse: it handles `export default { … }` — every scaffold
+ * and every template — and says so otherwise rather than guessing.
+ *
+ * @param {string} mainFile
+ * @param {string} name - already a valid foundation name
+ * @param {{ replace?: string|null }} [opts]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function writeFoundationName(mainFile, name, { replace = null } = {}) {
+  const line = `${NAME_COMMENT}\n  name: '${name}',`
+  if (!existsSync(mainFile)) {
+    writeFileSync(mainFile, `export default {\n  ${line}\n}\n`)
+    return { ok: true }
+  }
+  const text = readFileSync(mainFile, 'utf8')
+
+  if (replace !== null) {
+    const literal = new RegExp(
+      `(\\bname\\s*:\\s*)(['"\`])${replace.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\2`,
+      'g'
+    )
+    const hits = text.match(literal) || []
+    if (hits.length !== 1) {
+      return {
+        ok: false,
+        reason: `main.js does not name the foundation "${replace}" in exactly one place`
+      }
+    }
+    writeFileSync(mainFile, text.replace(literal, `$1'${name}'`))
+    return { ok: true }
+  }
+
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) {
+    return { ok: false, reason: 'main.js has no `export default { … }` to add a name to' }
+  }
+  // The name leads the export — on lines of its own, so a multi-line export keeps
+  // its first line and gains a blank one between.
+  const at = opening.index + opening[0].length
+  writeFileSync(mainFile, `${text.slice(0, at)}\n  ${line}\n${text.slice(at)}`)
+  return { ok: true }
+}
+
+/**
+ * Give a freshly scaffolded foundation its name, unless its main.js already has one.
+ *
+ * Called after template content is applied, because a template's own main.js
+ * replaces the scaffolded one — and with it the name the scaffold wrote.
+ *
+ * @param {string} foundationDir - the scaffolded package (flat layout: main.js at its root)
+ * @param {string|null} name
+ */
+export function ensureFoundationName(foundationDir, name) {
+  if (!name) return
+  const mainFile = join(foundationDir, 'main.js')
+  if (existsSync(mainFile) && mainNamesFoundation(readFileSync(mainFile, 'utf8'))) return
+  writeFoundationName(mainFile, name)
+}