uniweb 1.0.0 → 1.0.2

package/src/utils/git.js

@@ -0,0 +1,342 @@
+/**
+ * Git awareness for the sync verbs.
+ *
+ * The CLI's file-based workflow is for people who keep their content in git, so
+ * git is the right place to look before doing something destructive to the working
+ * tree — rather than building a merge engine to solve a problem the user's VCS
+ * already solves better.
+ *
+ * DETECTED, NEVER REQUIRED. A project may legitimately have no repo, and — more
+ * commonly — may live *inside* a larger one: `uniweb create` already skips
+ * `git init` when it finds itself inside a work tree ("common for
+ * monorepos/workspaces"), and whole scopes of real projects are versioned by a
+ * parent repo rather than being repo roots themselves. So the question is never
+ * "is this directory a git root" but "is this path tracked by some repo", which is
+ * the question git itself answers. Callers degrade to an explicit confirmation
+ * when the answer is no; sync already requires an account, and a second hard
+ * dependency for a safety net we can provide anyway is a bad trade.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, realpathSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import yaml from 'js-yaml'
+
+/**
+ * The files and directories `uniweb pull` writes into.
+ *
+ * ONE definition, shared by the guard that blocks a pull and the message that
+ * tells someone how to recover from a refused push — a second copy would drift,
+ * and a stale list here means either a guard that misses or advice that is wrong.
+ * `paths:` can relocate the content roots, so the local site.yml is consulted
+ * rather than assuming the defaults.
+ */
+export function siteContentRoots(siteDir) {
+  // ⚠️ `queries.yml` IS AT THE SITE ROOT, and that is why it must be named here.
+  // Its predecessor lived at `collections/collections.yml`, so the `collections`
+  // root added below already covered it and the bare `'collections.yml'` entry
+  // that used to sit in this list resolved to a path no site ever had. A
+  // root-level file has no directory entry standing in for it.
+  //
+  // The records folder's `folder.yml` is the reverse case: it lives in the records
+  // directory, which is a root below, so it needs no entry. (It was `records.yml` at
+  // the site root until 2026-09-21, and was listed here then.)
+  const roots = new Set([
+    'site.yml',
+    'theme.yml',
+    'head.html',
+    'queries.yml',
+    'locales'
+  ])
+  let paths = {}
+  try {
+    paths =
+      yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))?.paths || {}
+  } catch {
+    /* no or unreadable site.yml — the defaults are right */
+  }
+  roots.add(paths.pages || 'pages')
+  roots.add(paths.layout || 'layout')
+  roots.add(paths.records || 'records')
+  return [...roots]
+}
+
+/** Is there uncommitted work where a pull would write? False outside a repo. */
+export function hasUncommittedContent(siteDir) {
+  const dirty = uncommittedUnder(siteDir, siteContentRoots(siteDir))
+  return Array.isArray(dirty) && dirty.length > 0
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore']
+  })
+}
+
+/**
+ * Is `dir` inside a git work tree? False when git is absent, when the path isn't
+ * tracked, or on any error — the caller treats all three the same way.
+ */
+export function isGitRepo(dir) {
+  try {
+    return git(['rev-parse', '--is-inside-work-tree'], dir).trim() === 'true'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Uncommitted work under `relPaths`, relative to `dir`.
+ *
+ * Counts modified, staged, deleted AND untracked files. Untracked matters as much
+ * as modified here: a section file that exists only locally is not on the backend,
+ * so a pruning pull deletes it — losing work that was never committed anywhere.
+ *
+ * ⛔ **Returned relative to `dir`, which is NOT what git prints.** `--porcelain`
+ * paths are always relative to the REPOSITORY ROOT, whatever directory it runs
+ * in, so they only coincide with `dir`-relative when the site *is* the repo root.
+ * Both callers do `join(siteDir, rel)` with the result, so the un-normalized form
+ * was wrong for every nested layout — a site at `myproject/site/` inside a repo.
+ *
+ * What that cost, measured 2026-08-12: pull exempts its own previous output from
+ * the uncommitted-work guard by looking each dirty path up in a record keyed
+ * `dir`-relative (`utils/pull-written.js`). Given `myproject/site/site.yml` the
+ * lookup missed, so **pull refused on files pull itself had written** — the exact
+ * false alarm that record exists to prevent, and the one its own comment warns
+ * teaches people to reach for `--force`. `captureLocalWork` had the same defect
+ * one door along: it reads each path back with `join(siteDir, rel)`.
+ *
+ * The earlier `@returns` said "repo-relative-ish paths as git reports them" while
+ * the summary above said "relative to `dir`" — the ambiguity was noticed and left,
+ * and both callers had picked the other reading.
+ *
+ * @returns {string[]|null} paths relative to `dir`, or `null` when this isn't a
+ *   git work tree (distinct from `[]`, which means "clean").
+ */
+export function uncommittedUnder(dir, relPaths) {
+  if (!isGitRepo(dir)) return null
+  // ⚠️ Both sides must be REAL paths before `relative` can compare them.
+  // `rev-parse --show-toplevel` resolves symlinks; the caller's `dir` usually has
+  // not. On macOS that alone breaks it — `/var` is a symlink to `/private/var`,
+  // so a repo under the temp dir yields a root of `/private/var/…` against a dir
+  // of `/var/…`, and `relative` walks all the way up and back down. The result is
+  // a valid-looking path that matches nothing, i.e. the same silent miss this
+  // normalization exists to fix. Any symlinked checkout does it, not just tmp.
+  let root
+  let base
+  try {
+    root = git(['rev-parse', '--show-toplevel'], dir).trim()
+    base = realpathSync(dir)
+  } catch {
+    return null
+  }
+  try {
+    const out = git(
+      ['status', '--porcelain', '--untracked-files=all', '--', ...relPaths],
+      dir
+    )
+    return (
+      out
+        .split('\n')
+        .filter(Boolean)
+        // porcelain v1: XY<space>path, and a rename is "orig -> new".
+        .map((line) => line.slice(3).trim())
+        .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
+        // Porcelain paths are repo-root-relative; callers want them relative to
+        // `dir`. Quoted paths (git quotes names with spaces or non-ASCII when
+        // `core.quotePath` is on) are left alone rather than half-decoded — a
+        // wrong path is worse than an unmatched one here, since an unmatched
+        // path merely stays "dirty" and the guard errs toward refusing.
+        .map((p) => (p.startsWith('"') ? p : relative(base, join(root, p))))
+        .filter(Boolean)
+    )
+  } catch {
+    // A path git doesn't know (e.g. none of the roots exist yet) is not an error
+    // worth failing a pull over.
+    return []
+  }
+}
+
+/**
+ * A file's committed content — the COMMON ANCESTOR for a three-way merge.
+ *
+ * This is the input a merge needs and the backend cannot supply: it keeps no
+ * per-version item content, and retaining some so it could feed a merge running on
+ * the client would put a permanent second write on its hottest table. It doesn't
+ * have to. `uniweb pull` writes the backend's content into these files, so the
+ * committed version IS the state both sides diverged from — the ancestor was always
+ * on this side, in the tool that already knows how to merge.
+ *
+ * @returns {Buffer|null} null when the path isn't in HEAD (a file added locally and
+ *   never committed has no ancestor, so there is nothing to merge against).
+ */
+export function showAtHead(dir, relPath) {
+  return showAt(dir, 'HEAD', relPath)
+}
+
+/**
+ * A file's content at a revision, by a path relative to `dir`.
+ *
+ * ⛔ THE `./` IS WHAT MAKES THE PATH RELATIVE TO `dir`. In `<rev>:<path>` a bare path
+ * is read from the REPOSITORY ROOT, whatever the cwd. With the repo at the project
+ * root and the site in `site/` — the default layout — `HEAD:pages/home/hero.md`
+ * named nothing, every lookup failed, and `pull --merge` "kept yours" for every file:
+ * the backend's changes never merged in, while the pull recorded them as taken
+ * (2026-09-23). Every merge test ran with the repo AT the site directory, the one
+ * layout where a bare path happens to work.
+ *
+ * @returns {Buffer|null} null when the path isn't in that revision
+ */
+export function showAt(dir, rev, relPath) {
+  try {
+    return execFileSync('git', ['show', `${rev}:./${relPath}`], {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024
+    })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The most recent committed version of a file whose content hashes to `sha256` —
+ * how the version a pull wrote is found again, as the ancestor of a merge.
+ *
+ * HEAD is that version only until the user commits an edit on top of it. After that
+ * HEAD is THEIR edit, and a merge against it reads their change as the starting
+ * point: the backend's version wins whole and the committed edit is reverted in the
+ * working tree. The pull recorded the hash of what it wrote (`pull-written.json`),
+ * so the version is recoverable from history by content, wherever it was committed.
+ *
+ * @param {number} [limit] - how many commits touching the file to search
+ * @returns {Buffer|null} null when no committed version matches
+ */
+export function findCommitted(dir, relPath, sha256, { limit = 50 } = {}) {
+  let revs
+  try {
+    revs = git(['log', `-n${limit}`, '--format=%H', '--', `./${relPath}`], dir)
+      .split('\n')
+      .filter(Boolean)
+  } catch {
+    return null
+  }
+  for (const rev of revs) {
+    const buf = showAt(dir, rev, relPath)
+    if (buf && createHash('sha256').update(buf).digest('hex') === sha256) return buf
+  }
+  return null
+}
+
+/**
+ * Three-way merge, in place: `minePath` is rewritten with the merged result.
+ *
+ * Delegates to `git merge-file`, which is the same machinery git uses for a merge —
+ * text that only one side touched is taken silently, and only genuine overlaps get
+ * conflict markers. Building our own would be a worse version of a solved problem.
+ *
+ * @returns {{ merged: boolean, conflicted: boolean }} `merged:false` means the merge
+ *   could not be attempted at all, which is different from attempting it and finding
+ *   conflicts — the caller must not conflate them.
+ */
+export function mergeFile(dir, minePath, basePath, theirsPath, labels = {}) {
+  try {
+    execFileSync(
+      'git',
+      [
+        'merge-file',
+        '-L',
+        labels.mine || 'yours (local)',
+        '-L',
+        labels.base || 'common ancestor',
+        '-L',
+        labels.theirs || 'theirs (backend)',
+        minePath,
+        basePath,
+        theirsPath
+      ],
+      { cwd: dir, stdio: ['ignore', 'ignore', 'ignore'] }
+    )
+    return { merged: true, conflicted: false }
+  } catch (err) {
+    // A positive status is the CONFLICT COUNT and the file still holds a valid
+    // merge with markers. Anything else (git missing, unreadable input) means no
+    // merge happened and the caller must fall back rather than trust the file.
+    if (typeof err?.status === 'number' && err.status > 0 && err.status < 128) {
+      return { merged: true, conflicted: true }
+    }
+    return { merged: false, conflicted: false }
+  }
+}
+
+/** Does this repo have a remote configured to pull from? */
+export function hasRemote(dir) {
+  try {
+    return git(['remote'], dir).trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `git pull --ff-only` — bring in teammates' commits.
+ *
+ * Fast-forward only, deliberately. A refresh should never silently create a merge
+ * commit or drop the user into a rebase they didn't ask for; if the branches have
+ * genuinely diverged, that is a git problem the user should handle in git, with
+ * git's own vocabulary. We report and step back.
+ *
+ * @returns {{ ok: boolean, changed: boolean, message: string }}
+ */
+export function pullRemote(dir) {
+  const before = (() => {
+    try {
+      return git(['rev-parse', 'HEAD'], dir).trim()
+    } catch {
+      return null
+    }
+  })()
+  try {
+    const out = execFileSync('git', ['pull', '--ff-only'], {
+      cwd: dir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+    const after = (() => {
+      try {
+        return git(['rev-parse', 'HEAD'], dir).trim()
+      } catch {
+        return null
+      }
+    })()
+    return {
+      ok: true,
+      changed: Boolean(before && after && before !== after),
+      message: out.trim()
+    }
+  } catch (err) {
+    const msg = [err?.stderr, err?.stdout]
+      .map((b) => (b ? String(b) : ''))
+      .join('\n')
+      .trim()
+    return { ok: false, changed: false, message: msg || 'git pull failed' }
+  }
+}
+
+/**
+ * Provenance for a deploy record: `{ sha, dirty }`, or null outside a repo.
+ * Answers "what is actually live?" later, which a version number cannot.
+ */
+export function headProvenance(dir) {
+  if (!isGitRepo(dir)) return null
+  try {
+    const sha = git(['rev-parse', 'HEAD'], dir).trim()
+    const dirty = git(['status', '--porcelain'], dir).trim().length > 0
+    return { sha, dirty }
+  } catch {
+    return null // a repo with no commits yet
+  }
+}

package/src/utils/host-prompt.js

@@ -0,0 +1,51 @@
+/**
+ * Interactive host adapter selection
+ *
+ * Prompts the user to pick a host adapter from the registry. Used when
+ * `--host` is passed without a value to `uniweb deploy / build / export`.
+ *
+ * Non-interactive contexts (CI, piped input, --non-interactive) get a
+ * structured error instead of a prompt — never silently default to
+ * something the user didn't pick.
+ */
+
+import { promptSelect } from './workspace.js'
+import { isNonInteractive } from './interactive.js'
+
+/**
+ * Pick a host adapter, optionally with a pre-selection.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.args — Argv, used only to gate non-interactive mode.
+ * @param {string|null} [opts.preselect] — Suggested adapter name; the prompt
+ *   highlights this so Enter accepts it without arrow-key navigation.
+ * @returns {Promise<string>} The chosen adapter name.
+ * @throws {Error} When non-interactive (with the registry list in the message),
+ *   or when the user aborts the prompt.
+ */
+export async function promptForHost({ args, preselect = null } = {}) {
+  // Lazy-load so this module doesn't pull @uniweb/build at import time
+  // for callers that never reach the prompt path.
+  const { listAdapters } = await import('@uniweb/build/hosts')
+  const adapters = listAdapters()
+
+  if (isNonInteractive(args || [])) {
+    const list = adapters.join(', ')
+    throw new Error(
+      `--host requires a value when running non-interactively. Known adapters: ${list}.`
+    )
+  }
+
+  // promptSelect doesn't expose initial-index, so move the preselect to
+  // the top of the list — the menu still highlights index 0 by default.
+  const ordered =
+    preselect && adapters.includes(preselect)
+      ? [preselect, ...adapters.filter((a) => a !== preselect)]
+      : adapters
+
+  const choice = await promptSelect('Pick a host adapter:', ordered)
+  if (!choice) {
+    throw new Error('Host selection cancelled.')
+  }
+  return choice
+}

package/src/utils/install-integrity.js

@@ -0,0 +1,210 @@
+/**
+ * Local development: is the bundler reading the foundation source you are editing?
+ *
+ * SCOPE — this is a check about CLI scaffolding, and only about one modality.
+ * A site's `package.json`, its `file:` dependency on the foundation, and its
+ * `node_modules` are not part of the site as an artifact; they are the project
+ * shape the CLI hangs tooling on (see the three-ingredient model,
+ * the site/foundation/runtime model). Treating
+ * that scaffolding as part of the site is where most of the confusion in this
+ * area comes from, so: nothing here says anything about what a foundation *is*,
+ * how it is distributed, or how it reaches a host.
+ *
+ * The one modality it covers is bundled dev mode against a workspace-local
+ * foundation — `uniweb dev` with `foundation:` naming a sibling package. There,
+ * the site imports `#foundation`, which `build/src/site/config.js` aliases to
+ * the foundation's PACKAGE NAME, so Vite resolves it through node_modules. A
+ * linked site (registry ref or URL) never takes that path, and neither does the
+ * desktop app, unipress, or the edge — they load a built `dist/entry.js`, or
+ * read a content folder directly. The check stays silent for all of them
+ * because there is no node_modules entry to look at.
+ *
+ * What goes wrong in that one modality: a `file:` dependency can be satisfied
+ * by a link to the workspace source or by a materialized copy, and a copy is a
+ * snapshot carrying its own nested node_modules — so it keeps resolving
+ * whatever `@uniweb/*` versions were current when it was taken.
+ *
+ * It hides well. `uniweb build` resolves the foundation by PATH and reads the
+ * workspace source, so the build is green and the tests pass while the dev
+ * server serves code from weeks ago. Cheap enough (a few lstats and JSON reads)
+ * to run on every `uniweb dev` rather than waiting for someone to suspect it.
+ *
+ * Reports; never prints. Callers present findings in their own voice.
+ */
+
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { stripVersionRange } from './dep-survey.js'
+
+/**
+ * The foundation a site declares, or null. Small enough to live beside the one
+ * check that needs it rather than becoming another shared module.
+ *
+ * @param {string} sitePath
+ * @returns {string|null}
+ */
+export function readDeclaredFoundation(sitePath) {
+  for (const name of ['site.yml', 'site.yaml']) {
+    const path = join(sitePath, name)
+    if (!existsSync(path)) continue
+    try {
+      return yaml.load(readFileSync(path, 'utf8'))?.foundation ?? null
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Where a package name resolves from a starting directory, walking up through
+ * node_modules the way Node does. Returns the directory, or null.
+ */
+function resolvePackageDir(fromDir, packageName) {
+  let dir = resolve(fromDir)
+
+  while (true) {
+    const candidate = join(dir, 'node_modules', packageName)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Check one site against the foundation it declares.
+ *
+ * @param {Object} site - { name, path }
+ * @param {Object} foundation - { name, path } — the workspace source
+ * @param {string} workspaceDir - For readable paths in findings
+ * @returns {Array<Object>} findings, each { id, severity, site, message, detail, remedy }
+ */
+export function checkSiteInstall(site, foundation, workspaceDir) {
+  const findings = []
+  const rel = (p) => relative(workspaceDir, p) || '.'
+
+  const linkPath = join(site.path, 'node_modules', foundation.name)
+
+  // Nothing installed at all — not this check's business to complain about,
+  // and every other check will already be shouting.
+  if (!existsSync(linkPath)) {
+    return findings
+  }
+
+  // A symlink points at one source of truth; a real directory is a snapshot.
+  const stat = lstatSync(linkPath)
+  const isLink = stat.isSymbolicLink()
+
+  if (!isLink) {
+    findings.push({
+      id: 'dev-foundation-source-stale',
+      severity: 'error',
+      site: site.name,
+      message: `In dev, this site builds against a copy of "${foundation.name}", not your workspace source.`,
+      detail:
+        `  ${rel(linkPath)} is a directory rather than a link, so it is a snapshot of\n` +
+        `  ${rel(foundation.path)} taken when it was installed. Edits you make will not\n` +
+        `  reach the dev server. \`uniweb build\` resolves the foundation by path and reads\n` +
+        `  your source, so builds stay correct — which is why this is easy to miss.`,
+      remedy:
+        'Reinstall so it links to the workspace source (e.g. pnpm install)'
+    })
+  } else {
+    // Linked, but possibly at the wrong source.
+    const target = realpathSync(linkPath)
+    const expected = realpathSync(foundation.path)
+    if (target !== expected) {
+      findings.push({
+        id: 'dev-foundation-source-elsewhere',
+        severity: 'error',
+        site: site.name,
+        message: `In dev, this site resolves "${foundation.name}" somewhere other than your workspace source.`,
+        detail: `  resolves to: ${rel(target)}\n  workspace source: ${rel(expected)}`,
+        remedy: "Reinstall, and check the site's package.json file: reference"
+      })
+    }
+  }
+
+  // What the site actually reaches, versus what the foundation asks for. These
+  // agree through a link and drift through a copy — the drift is what runs.
+  const foundationPkg = readJson(join(foundation.path, 'package.json'))
+  const declared = {
+    ...foundationPkg?.dependencies,
+    ...foundationPkg?.peerDependencies
+  }
+
+  for (const [name, spec] of Object.entries(declared)) {
+    if (!name.startsWith('@uniweb/')) continue
+    // A range says "anything compatible" — only an exact pin is a promise.
+    if (stripVersionRange(spec) !== spec) continue
+
+    const reachedDir = resolvePackageDir(linkPath, name)
+    if (!reachedDir) continue
+
+    const reached = readJson(join(reachedDir, 'package.json'))?.version
+    if (reached && reached !== spec) {
+      findings.push({
+        id: 'dev-foundation-dep-skew',
+        severity: 'error',
+        site: site.name,
+        message: `In dev, "${foundation.name}" compiles against ${name} ${reached}, but declares ${spec}.`,
+        detail:
+          `  declared in ${rel(join(foundation.path, 'package.json'))}: ${spec}\n` +
+          `  resolved from ${rel(linkPath)}: ${reached}\n` +
+          `  ${name} is bundled into the foundation, so the dev server runs the version it\n` +
+          `  reaches here. A build reads the workspace tree and may compile a different one.`,
+        remedy: 'Reinstall so the resolved tree matches what is declared'
+      })
+    }
+  }
+
+  return findings
+}
+
+/**
+ * Check every site in the workspace.
+ *
+ * @param {Array<Object>} sites - [{ name, path, foundation }]
+ * @param {Array<Object>} foundations - [{ name, path }]
+ * @param {string} workspaceDir
+ * @returns {Array<Object>} findings
+ */
+export function checkWorkspaceInstall(sites, foundations, workspaceDir) {
+  const findings = []
+
+  for (const site of sites) {
+    const foundation = foundations.find((f) => f.name === site.foundation)
+    // An unresolvable foundation name is a different check's finding.
+    if (!foundation) continue
+    findings.push(...checkSiteInstall(site, foundation, workspaceDir))
+  }
+
+  return findings
+}
+
+/**
+ * One-line summary for callers that only want to know whether to speak up.
+ * @param {Array<Object>} findings
+ * @returns {string|null}
+ */
+export function summarizeInstallFindings(findings) {
+  if (!findings.length) return null
+
+  const sites = [...new Set(findings.map((f) => f.site))]
+  const what = findings.some((f) => f.id === 'foundation-dep-skew')
+    ? 'the installed packages do not match what is declared'
+    : 'the foundation is not linked to its workspace source'
+
+  return `Install is out of date in ${sites.join(', ')} — ${what}. Run your package manager's install, or \`uniweb doctor\` for detail.`
+}