uniweb 1.0.0 → 1.0.2

package/src/utils/pull-written.js

@@ -0,0 +1,132 @@
+/**
+ * The record of what a machine wrote into a site project — pull's own output.
+ *
+ * ⭐ And, since 2026-09-23, what a push delivered: the files of the units the backend
+ * now holds as they were sent (`recordPushedUnits`, site-sync.js). Both are "the last
+ * version this file synced at", which is what `pull --merge` needs as its ancestor —
+ * found again in the repo's history by this hash (`findCommitted`, utils/git.js).
+ *
+ * ## What it is for
+ *
+ * `uniweb pull` refuses to run when there are uncommitted changes under the files
+ * it rewrites, because it reconciles the working tree to the backend and would
+ * overwrite them. That guard needs one distinction to be useful: **a file the
+ * user edited** versus **a file a previous pull wrote and nobody has touched
+ * since**. Without it the guard cries wolf — pull rewrites the tree, so the next
+ * pull sees its own output as uncommitted work and refuses, listing files the
+ * user never touched. A guard that fires on nothing teaches people to reach for
+ * `--force`, which is the destructive option.
+ *
+ * So each write is recorded with a content hash, and a dirty path whose hash
+ * still matches is not user work.
+ *
+ * ## Why it lives here rather than in `pull.js`
+ *
+ * `uniweb clone` has the same claim to make and cannot make it from there.
+ * `pull.js` statically imports `@uniweb/build`, which resolves from the
+ * *project's* `node_modules` — and `clone` runs before a project exists (see
+ * `utils/uwx-read.js` for the same constraint on the `.uwx` reader).
+ *
+ * Clone scaffolds `site.yml` and `theme.yml` and then delegates to `pull`, so
+ * without this the delegated pull sees clone's own scaffolding as uncommitted
+ * user work and refuses — on a project created seconds earlier, where there is no
+ * user work to protect. Clone records what it wrote; the guard then exempts those
+ * files **for the right reason** rather than being overridden.
+ *
+ * Nothing here imports `@uniweb/build`, and nothing here may start to.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, dirname, relative } from 'node:path'
+
+/** Where the record lives — gitignored, beside the other per-site caches. */
+export function writtenCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-written.json')
+}
+
+/**
+ * @param {string} siteDir
+ * @returns {{files: Record<string,string>, deleted: string[]}}
+ */
+export function readWritten(siteDir) {
+  try {
+    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
+    return {
+      files: o && typeof o.files === 'object' ? o.files : {},
+      deleted: Array.isArray(o?.deleted) ? o.deleted : []
+    }
+  } catch {
+    return { files: {}, deleted: [] }
+  }
+}
+
+/**
+ * Record files as machine-written, by absolute path.
+ *
+ * MERGE, don't replace. A conditional pull that 304s writes nothing, and a
+ * partial pull writes only some lanes — in both cases the previous record is
+ * still "the last thing written there". Replacing would forget those paths and
+ * the next pull would see them as the user's work again, which is the false alarm
+ * this cache exists to prevent. A stale entry for a file that no longer exists is
+ * harmless: the hash read fails and it counts as a local change.
+ *
+ * @param {string} siteDir
+ * @param {string[]} absPaths - files just written
+ * @param {string[]} [deletedAbs] - files just pruned
+ */
+export function recordWritten(siteDir, absPaths, deletedAbs = []) {
+  const prior = readWritten(siteDir)
+  const files = prior.files
+  for (const abs of absPaths) {
+    try {
+      files[relative(siteDir, abs)] = createHash('sha256')
+        .update(readFileSync(abs))
+        .digest('hex')
+    } catch {
+      /* deleted or unreadable — nothing to remember */
+    }
+  }
+  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
+  // Without recording them, pull's own pruning reads as the user having deleted
+  // files — the same false alarm as its writes, arriving by the other door.
+  const deleted = [
+    ...new Set([...prior.deleted, ...deletedAbs.map((a) => relative(siteDir, a))])
+  ]
+  try {
+    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
+    writeFileSync(
+      writtenCachePath(siteDir),
+      JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n'
+    )
+  } catch {
+    /* best-effort: losing it only costs a spurious refusal */
+  }
+}
+
+/**
+ * Is this dirty path just machine output nobody has touched?
+ *
+ * The hash comparison is what keeps the guard honest: a scaffolded or pulled file
+ * the user then EDITED no longer matches, so it counts as their work and the
+ * refusal stands.
+ *
+ * @param {string} siteDir
+ * @param {string} relPath
+ * @param {{files: Record<string,string>, deleted: string[]}} written
+ * @returns {boolean}
+ */
+export function isPullOutput(siteDir, relPath, written) {
+  let exists = true
+  let hash = null
+  try {
+    hash = createHash('sha256')
+      .update(readFileSync(join(siteDir, relPath)))
+      .digest('hex')
+  } catch {
+    exists = false
+  }
+  // Absent because pull pruned it — not because the user deleted it.
+  if (!exists) return written.deleted.includes(relPath)
+  return written.files[relPath] === hash
+}

package/src/utils/records-guard.js

@@ -0,0 +1,88 @@
+// ⛔ THE ONE PLACE AN ORDINARY ACT IS DESTRUCTIVE.
+//
+// A push sends the site's records folder whole, and it REPLACES the backend's. A site
+// with no records directory sends none and leaves the backend's alone; a records
+// directory that holds no records sends an EMPTY folder, and the backend removes what
+// is there. The asymmetry is well-shaped — the safe state is the ABSENCE of the
+// directory, so a site whose records live only on the backend is never emptied by a
+// push of its pages — and it leaves exactly one sharp edge: a directory emptied by
+// accident, or kept with only a placeholder (`records/.gitkeep`), and pushed.
+//
+// ⭐ THE CLI DOES THE ASKING. Never make "empty" mean "missing" to dodge this: that
+// would delete a capability to avoid writing a prompt.
+//
+// ⛔ Until 2026-09-21 both states were `records.yml`'s — missing and empty — because
+// that file listed the records. The directory holds them now (`@uniweb/build`'s
+// `sendsFolder` decides what a push sends, and this asks about exactly its empty case).
+//
+// The count comes from the placement identity a previous push banked — what WE
+// last saw the folder hold. It needs no network call, and it is the right source:
+// a site that has never pushed has nothing to lose and is never asked.
+
+import { readEntityPool } from '@uniweb/build/uwx'
+import { readFolderItemUuids } from '../backend/site-sync.js'
+import { confirm, isNonInteractive, getCliPrefix } from './interactive.js'
+
+/**
+ * Record placements in a banked placement map.
+ *
+ * ⭐ A placement banked since 2026-09-21 is keyed by the record it references —
+ * `@<record uuid>`, one per record — so where those exist they ARE the count. A map
+ * banked before holds `name` chains only: a branch's path is a prefix of every path
+ * beneath it, so anything that is a prefix of another key is a folder rather than a
+ * record. Counting raw keys would report a two-record site inside one folder as
+ * three things to lose — or, with both kinds of key, each record twice.
+ */
+export function countPlacedRecords(pathToUuid) {
+  const keys = Object.keys(pathToUuid || {})
+  const byRecord = keys.filter((k) => k.startsWith('@'))
+  if (byRecord.length) return byRecord.length
+  return keys.filter((p) => !keys.some((q) => q !== p && q.startsWith(`${p}/`))).length
+}
+
+/**
+ * Stop an empty records directory from silently emptying the backend's folder.
+ *
+ * @param {object} params
+ * @param {string} params.siteDir
+ * @param {string} params.backend - whose placements to count; they are minted per backend
+ * @param {string[]} params.args - the verb's argv, for --yes / non-interactive
+ * @param {(m: string) => void} params.warn - the CALLER's reporter. Each verb owns
+ *        its own output style; a second copy here would drift from all of them.
+ * @param {(m: string) => void} params.note
+ * @returns {Promise<{ ok: boolean, count: number }>} `ok: false` means abort
+ */
+export async function guardEmptyRecords({ siteDir, backend, args = [], warn, note }) {
+  const pool = await readEntityPool(siteDir)
+  // Only a directory that is there and holds nothing at all — no records, and no
+  // files that fail to be records — sends the empty folder.
+  if (!pool.exists || pool.entities.length > 0 || pool.errors.length > 0) return { ok: true, count: 0 }
+
+  const count = countPlacedRecords(readFolderItemUuids(siteDir, backend))
+  // Nothing banked ⇒ nothing this push can remove. A first push of an empty
+  // folder is a legitimate (if odd) thing to do, and asking about it would train
+  // people to type y.
+  if (count === 0) return { ok: true, count: 0 }
+
+  warn(
+    `${pool.dir}/ holds no records, and this push would REMOVE ${count} record${count === 1 ? '' : 's'} ` +
+      `from the site's folder on the backend.`
+  )
+  note(
+    `An empty ${pool.dir}/ means "the folder holds nothing" — it is not the same as having no ` +
+      `${pool.dir}/ at all, which leaves the backend's folder alone. If you did not mean to remove ` +
+      `them, put the files back (or pull) before pushing.`
+  )
+
+  // ⚠️ `--yes` ONLY. `-y` is not a flag this CLI has anywhere, and adding one here
+  // would have been caught by `flag-guard-coverage.test.js` — which it was.
+  if (args.includes('--yes')) return { ok: true, count }
+  if (isNonInteractive(args)) {
+    warn(`Refusing to remove ${count} record${count === 1 ? '' : 's'} without confirmation.`)
+    note(`Re-run with --yes if that is what you want: ${getCliPrefix()} push --yes`)
+    return { ok: false, count }
+  }
+
+  const yes = await confirm(`Remove ${count} record${count === 1 ? '' : 's'} from the site's folder?`, false)
+  return { ok: yes, count }
+}