Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

A publish may never delete another app's artifacts (#204)

nyblnet54b20af35328
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 47d79063..961d32d2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -131,6 +131,14 @@ jobs:
# throw when storage does.
run: node scripts/test-storage.ts
+ - name: Publish deletion-gate rig
+ # A publish assembles site/ for ONE app and mirrors it authoritatively.
+ # Measured: a spaces-shaped site/ deleted 47 live files — the signed
+ # shell, the manifest, all 22 packs — with every other gate green,
+ # because those gates are `if (existsSync(...))` and skip when the
+ # artifact is missing. Shipped files cannot recover from that.
+ run: node scripts/test-publish-gate.mjs
+
- name: Model key tables match the format
# slides/src/modelkeys.generated.ts is derived from model.ts and drives
# validate()'s unknown-key check. A stale copy would report real
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 06d5d192..498a2671 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -761,3 +761,49 @@ motion, so `fx.enter` and `fx.countUp` are both skipped. With no partner it is
new to the slide, has no tween to fight, and both run. Do not "simplify" this
back into a blanket morph-vs-entrance branch; that blanket rule is what made
count-ups silently dead and `slide-left` silently mean "rise 14px".
+
+## 2026-08-02 — Publishing one app may never delete another's artifacts
+
+`site/` is assembled for ONE app and mirrored into `bento-site` with
+`rsync -a --delete`, so anything that build did not write is removed from
+bento.page. Measured, not theorised: a cloned `release.mjs --app spaces`
+staged a spaces site, and a publish against a copy of the real published tree
+removed **47 live files** — `releases/slides/Bento_Slides.bento.html`,
+`releases/slides/manifest.json`, `packs.json`, all 22 signed language packs,
+`slides/index.html`, all four gallery decks, `guestbook/index.html` — with
+every existing gate reporting green.
+
+Shipped slides files check `releases/slides/manifest.json` at launch
+(`slides/src/main.ts`) and their pack channel at `releases/slides/packs.json`
+(`slides/src/packs.ts`). Both are frozen URLs in files already on disks, so a
+deletion takes those channels offline permanently, for every copy in the
+world, with no client-side repair. It is the one publish mistake with no way
+back.
+
+**Why nothing caught it: the existing gates are fail-OPEN.** The
+shell-consistency gate and the pack-index gate are both
+`if (existsSync(<path in site/>))` — an artifact that is *missing* skips the
+check instead of tripping it, and missing is exactly the dangerous case.
+PR #192's `--exclude guestbook.bento.html` is one hardcoded filename, not a
+mechanism; it must not be read as evidence that protection exists.
+
+**The gate is a deletion inventory of the DESTINATION, and it is fail-closed.**
+Before mirroring, walk the published tree and refuse if any path would
+disappear. If the destination cannot be inventoried at all, refuse — that is
+the case where we know least about what we are about to overwrite.
+Deliberate removal is `--allow-deletions`, which lists what it would drop.
+
+Deletions are singled out from changes on purpose. A changed file is a release
+doing its job; the one byte-change nobody can repair, a manifest going
+backwards, already has its own monotonicity gate.
+
+Gate on the published INVENTORY, not on `releases/*/manifest.json`. The
+deletion set included `slides/index.html`, the gallery, `agents.md`,
+`skills/`, `LICENSE`, `404.html`, `help/`, `q/`, `og.png`, `robots.txt` and
+`sitemap.xml` — none of which a manifest-shaped gate would have seen.
+
+Rig: `scripts/test-publish-gate.mjs`; shared logic `scripts/site-inventory.mjs`.
+This is the first half of the multi-app release work
+(`working/spaces-design.md` §6.1); per-app assembly — build one app, restore
+the others byte-identically from the published tree — is the second, and
+spaces cannot be released until both exist.
diff --git a/scripts/publish-site.mjs b/scripts/publish-site.mjs
index 9f66881d..19f6cf42 100755
--- a/scripts/publish-site.mjs
+++ b/scripts/publish-site.mjs
@@ -26,6 +26,7 @@ import { dirname, join, resolve } from 'node:path'
import { tmpdir } from 'node:os'
import { fileURLToPath } from 'node:url'
import { gatePackIndex } from './sign-packs.mjs'
+import { walk, plannedDeletions, groupDeletions } from './site-inventory.mjs'
const root = dirname(dirname(fileURLToPath(import.meta.url)))
const site = join(root, 'site')
@@ -183,10 +184,74 @@ const cmpVersion = (a, b) => {
// The landing page is now written unconditionally (release.mjs), so only the
// deck needs protecting, and only when this build has none to offer.
const rsyncFlags = ['-a', '--delete', '--exclude', '.git']
+const excluded = ['.git']
if (!existsSync(join(site, 'guestbook.bento.html'))) {
rsyncFlags.push('--exclude', 'guestbook.bento.html')
+ excluded.push('guestbook.bento.html')
console.log('• no guestbook deck in this build (no local epoch) — leaving the published one untouched')
}
+
+// ---- gate: a publish may not DELETE what is already published --------------
+//
+// The exclusion above is one hardcoded filename. It is not a mechanism, and
+// the failure it patches is general: `site/` is assembled by a process that
+// knows about ONE app, and the mirror is authoritative, so anything the
+// assembler did not write is removed from the live site.
+//
+// Measured, not theorised. A cloned `release.mjs --app spaces` staged a spaces
+// site and this script mirrored it against a copy of the real bento-site:
+// 52 deletions, every existing gate green, nothing refused — including
+// `releases/slides/manifest.json`, all 22 signed language packs, the shell,
+// `slides/index.html`, all four gallery decks and `guestbook/index.html`.
+// Shipped slides files would then 404 on both their launch update check and
+// their pack channel, permanently, with no way to repair it from their side.
+//
+// The existing gates could not catch it because they are FAIL-OPEN: the
+// shell-consistency gate and the pack-index gate are both `if (existsSync(…))`
+// over a path in `site/`, so an artifact that is *missing* — exactly the
+// dangerous case — skips the check rather than tripping it. This gate is
+// fail-CLOSED: it inventories the destination, and anything it cannot account
+// for stops the publish.
+//
+// Deletions are singled out from changes deliberately. A changed file is a
+// release doing its job, and the manifest downgrade above already guards the
+// one change nobody can repair. A deletion is unrecoverable from the client
+// side and is never what a publish means to do.
+{
+ let published
+ try {
+ published = walk(dest)
+ } catch (e) {
+ // Fail CLOSED. An unreadable destination is the case where we know least
+ // about what we are about to overwrite, so it is the last place to guess.
+ die(`cannot inventory the published site at ${dest} — refusing to mirror over it.\n ${e.message}`)
+ }
+ const deletions = plannedDeletions(published, walk(site), excluded)
+
+ if (deletions.length) {
+ if (!args.includes('--allow-deletions')) {
+ die(
+ `this publish would DELETE ${deletions.length} file(s) that are live on bento.page:\n` +
+ groupDeletions(deletions).map(([g, n]) => ` · ${g}${n > 1 ? ` (${n} files)` : ''}`).join('\n') +
+ '\n\n' +
+ ` Full list: ${deletions.slice(0, 40).join(', ')}${deletions.length > 40 ? ', …' : ''}\n\n` +
+ ` A publish assembles site/ for ONE app and mirrors it authoritatively,\n` +
+ ` so every artifact another app or an earlier build produced is missing\n` +
+ ` from site/ and would be removed from the live site. Files already in\n` +
+ ` the world check their manifest and pack channel at those paths; a\n` +
+ ` deletion takes them offline permanently and cannot be repaired from\n` +
+ ` the client side.\n\n` +
+ ` If site/ is simply incomplete, rebuild it (release.mjs) or restore the\n` +
+ ` missing artifacts from the published tree before publishing.\n` +
+ ` Deliberate removal: --allow-deletions.`,
+ )
+ }
+ console.log(`⚠ deleting ${deletions.length} published file(s) — allowed explicitly`)
+ } else {
+ console.log(`• deletion gate: ${published.length} published file(s), none would be removed ✓`)
+ }
+}
+
if (dry) rsyncFlags.push('-n', '-v', '--itemize-changes')
console.log(`• ${dry ? 'DRY-RUN ' : ''}mirroring ${site}/ → ${dest}/`)
run('rsync', [...rsyncFlags, `${site}/`, `${dest}/`])
diff --git a/scripts/site-inventory.mjs b/scripts/site-inventory.mjs
new file mode 100644
index 00000000..c32c8fd6
--- /dev/null
+++ b/scripts/site-inventory.mjs
@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+//
+// What is published, and what a publish would remove.
+//
+// Its own module so the rule is testable without running a publish:
+// publish-site.mjs dies during preflight when imported, and the failure this
+// guards is the one class of mistake nobody can repair afterwards — a deleted
+// artifact takes shipped files' update and pack channels offline permanently.
+
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Every file under `dirPath`, as paths relative to it. `.git` is never walked. */
+export function walk(dirPath, base = dirPath) {
+ const out = []
+ for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+ if (entry.name === '.git') continue
+ const full = join(dirPath, entry.name)
+ if (entry.isDirectory()) out.push(...walk(full, base))
+ else out.push(full.slice(base.length + 1))
+ }
+ return out
+}
+
+/**
+ * Published files an authoritative mirror of `staged` would remove.
+ *
+ * `excluded` holds the mirror's own --exclude patterns: a path the mirror does
+ * not touch is not a deletion, and counting it as one would block every
+ * ordinary publish that legitimately carries no guestbook deck.
+ *
+ * Matching is exact-or-directory-prefix, deliberately not glob: an exclusion
+ * that quietly matched more than it looks like it does would re-open the hole.
+ */
+export function plannedDeletions(published, staged, excluded = []) {
+ const have = new Set(staged)
+ return published
+ .filter((p) => !have.has(p))
+ .filter((p) => !excluded.some((ex) => p === ex || p.startsWith(`${ex}/`)))
+}
+
+/** Deletions grouped by top-level path, so 22 packs read as one line. */
+export function groupDeletions(deletions) {
+ const groups = new Map()
+ for (const p of deletions) {
+ const top = p.includes('/') ? p.slice(0, p.indexOf('/')) : p
+ groups.set(top, (groups.get(top) ?? 0) + 1)
+ }
+ return [...groups]
+}
diff --git a/scripts/test-publish-gate.mjs b/scripts/test-publish-gate.mjs
new file mode 100644
index 00000000..5142b0ae
--- /dev/null
+++ b/scripts/test-publish-gate.mjs
@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Publish deletion-gate rig.
+//
+// node scripts/test-publish-gate.mjs
+//
+// WHAT THIS PROVES. `site/` is assembled for ONE app and mirrored
+// authoritatively with `rsync --delete`, so every artifact that build did not
+// write is removed from bento.page. Measured against a copy of the real
+// published tree, a spaces-shaped `site/` deleted 47 live files — the signed
+// shell, `releases/slides/manifest.json`, all 22 language packs, the gallery,
+// the guestbook landing page — with every pre-existing gate green.
+//
+// Shipped files check their manifest and pack channel at those exact paths.
+// A deletion takes them offline permanently and cannot be repaired from the
+// client side, which makes this the one publish mistake with no way back.
+//
+// The pre-existing gates could not catch it because they are FAIL-OPEN:
+// `if (existsSync(<path in site/>))` skips the check when the artifact is
+// MISSING, which is exactly the dangerous case. So the properties that matter
+// here are (1) a missing artifact TRIPS the gate rather than skipping it, and
+// (2) an excluded path is still not a deletion, or every ordinary publish
+// without a guestbook deck would be blocked.
+
+import { plannedDeletions, groupDeletions, walk } from './site-inventory.mjs'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let failures = 0
+let checks = 0
+function ok(cond, msg) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+// A published tree shaped like the real one: the artifacts shipped files depend on.
+const PUBLISHED = [
+ 'index.html', 'CNAME', '.nojekyll', 'agents.md', 'LICENSE',
+ 'releases/slides/Bento_Slides.bento.html',
+ 'releases/slides/manifest.json',
+ 'releases/slides/packs.json',
+ 'releases/slides/packs/bento-slides-1.0.13-ko.pack.json',
+ 'releases/slides/packs/bento-slides-1.0.13-ru.pack.json',
+ 'slides/index.html',
+ 'gallery/orbital-dark-immersive.bento.html',
+ 'guestbook/index.html',
+ 'guestbook.bento.html',
+ 'skills/bento-slides/SKILL.md',
+]
+
+// ---- the failure this exists to stop -------------------------------------
+// A spaces release: index.html is rewritten, spaces artifacts appear, and
+// every slides artifact is simply absent from the staging tree.
+const SPACES_STAGED = [
+ 'index.html', 'CNAME', '.nojekyll',
+ 'releases/spaces/Bento_Spaces.bento.html',
+ 'releases/spaces/manifest.json',
+ 'spaces/index.html',
+]
+const spacesDeletions = plannedDeletions(PUBLISHED, SPACES_STAGED, ['.git'])
+ok(spacesDeletions.length === 12,
+ `a spaces-shaped publish is reported as deleting 12 live files (got ${spacesDeletions.length})`)
+for (const critical of [
+ 'releases/slides/manifest.json',
+ 'releases/slides/packs.json',
+ 'releases/slides/Bento_Slides.bento.html',
+ 'releases/slides/packs/bento-slides-1.0.13-ko.pack.json',
+]) {
+ ok(spacesDeletions.includes(critical),
+ `the update/pack channel artifact ${critical} is caught`)
+}
+
+// ---- an ordinary publish must not be blocked ------------------------------
+ok(plannedDeletions(PUBLISHED, PUBLISHED, ['.git']).length === 0,
+ 'republishing exactly what is live deletes nothing')
+
+// Note the gate is deliberately PATH-based: a release is supposed to change
+// bytes, and the one byte-change nobody can repair — a manifest going
+// backwards — already has its own monotonicity gate in publish-site.mjs.
+
+// ---- exclusions ------------------------------------------------------------
+// The mirror does not touch an excluded path, so it cannot delete it. Without
+// this, every release built from a clean tag checkout — which never has the
+// gitignored guestbook epoch — would be blocked outright.
+const noGuestbookDeck = PUBLISHED.filter((p) => p !== 'guestbook.bento.html')
+ok(plannedDeletions(PUBLISHED, noGuestbookDeck, ['.git', 'guestbook.bento.html']).length === 0,
+ 'a path excluded from the mirror is not counted as a deletion')
+ok(plannedDeletions(PUBLISHED, noGuestbookDeck, ['.git']).includes('guestbook.bento.html'),
+ 'the same path IS a deletion when it is not excluded — the exclusion is doing the work')
+
+// Directory-prefix exclusions must cover their contents, and nothing else.
+ok(plannedDeletions(PUBLISHED, [], ['.git', 'releases']).every((p) => !p.startsWith('releases/')),
+ 'excluding a directory covers everything under it')
+ok(plannedDeletions(PUBLISHED, [], ['.git', 'guestbook']).includes('guestbook.bento.html'),
+ 'excluding "guestbook" does NOT swallow the sibling file "guestbook.bento.html"')
+
+// ---- grouping --------------------------------------------------------------
+const groups = new Map(groupDeletions(spacesDeletions))
+ok(groups.get('releases') === 5, `the shell, manifest, index and 2 packs collapse into one "releases" line (got ${groups.get('releases')})`)
+ok(groups.get('agents.md') === 1, 'a top-level file is its own group')
+
+// ---- walk() ----------------------------------------------------------------
+const tmp = join(tmpdir(), `bento-gate-${process.pid}`)
+try {
+ for (const rel of ['a.txt', 'sub/b.txt', '.git/HEAD', 'sub/deep/c.txt']) {
+ mkdirSync(dirname(join(tmp, rel)), { recursive: true })
+ writeFileSync(join(tmp, rel), 'x')
+ }
+ const found = walk(tmp).sort()
+ ok(JSON.stringify(found) === JSON.stringify(['a.txt', 'sub/b.txt', 'sub/deep/c.txt']),
+ `walk() returns relative paths and never enters .git (got ${JSON.stringify(found)})`)
+} finally {
+ rmSync(tmp, { recursive: true, force: true })
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)