feat(assets): the panel that operates the client-file imports (Phase 8)

Admin -> Client Files: one page over the three things that come out of the
operator's UO client -- creature portraits, item and land pictures, and the
cliloc table. One page rather than three because they are one job: same client
install, same bridge, and all of them change at the same moment, when the
operator patches that client. Boot never asks the shard for any of it, so these
buttons are the only thing that imports.

The cliloc pair had had no UI at all since phase 2. On a bridged install, where
boot deliberately stopped calling the shard, that meant `curl` was the only way
to load 67,496 names.

Update and Re-import everything are section 6's two stages as two buttons rather
than one button and a checkbox, because they cost wildly different things. A
vanished key is reviewed in the page and not in a table -- an asset import only
happens because someone pressed a button here, so the review is already in front
of the person who caused it -- and it shows each key's PICTURE, since
`body/820/a23` names nothing a human recognises. `shard_asset_meta` gained a
`last` block (what the import did, who ran it) so the panel can answer "did last
week's import do anything" without scrolling core's whole activity log.

The live walk against a real shard imported 1,095 portraits in 3.5 s, warmed 313
item pictures in 0.6 s and reloaded 67,496 cliloc rows in 1.7 s -- and found two
DELETIONS that predate this phase and that no test could see, because only a
screen showing the numbers together makes them visible:

  * The body import diffed its manifest against every family's rows. Phase 5 put
    item and land art in the same table, and a body manifest never mentions
    them, so all 313 item pictures were staged for deletion with a sentence
    saying the shard had stopped offering them.
  * An approved vanish unlinked the sprite and kept the row. The catalogue went
    on counting a picture that was gone, the atlas could point a creature page at
    a missing file, and the next forced import offered the same key for review
    again -- reporting "nothing was changed" about a file it had deleted.

Both fixed here, with the removals now inside `saveAssets`'s own transaction.
The same whole-table read made the panel announce a 1,408-row creature catalogue
on an install holding 1,095 portraits and 313 item pictures.

Protocol stays 8 and EXTRACTOR_VERSION stays 3: nothing on the wire changed.

Refs: docs/link/v8.md sections 12.2, 14, 16 (phase 8)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

server/test/shardAssets.model.test.js

@@ -40,6 +40,7 @@ function stubEverything({ manifest, fetched, held = new Map(), meta = null, sour
   saved.resolveBodies = bridge.resolveBodies
   saved.allAssets = db.allAssets
   saved.saveAssets = db.saveAssets
+  saved.recordLastImport = db.recordLastImport
   saved.getMeta = db.getMeta
   saved.countAssets = db.countAssets
   saved.countBodies = db.countBodies
@@ -50,7 +51,7 @@ function stubEverything({ manifest, fetched, held = new Map(), meta = null, sour
   saved.loadArtMap = atlasModel.loadArtMap
   saved.getSafe = uoLinkConfig.getSafe
 
-  const seen = { saved: null, fetchedKeys: null, art: null }
+  const seen = { saved: null, fetchedKeys: null, art: null, last: null }
 
   uoLinkConfig.getSafe = async () => ({ enabled: true, baseUrl: 'http://127.0.0.1:8080' })
 
@@ -78,6 +79,9 @@ function stubEverything({ manifest, fetched, held = new Map(), meta = null, sour
     seen.saved = rows
     return rows.length
   }
+  db.recordLastImport = async (last) => {
+    seen.last = last
+  }
   db.replaceBodies = async () => 0
   db.artBySlug = async () => ({})
 
@@ -363,3 +367,193 @@ test('a sprite filename carries its hash so a changed picture is a changed URL',
   assert.notEqual(before, after)
   assert.match(before, /^uo-body-34-a0-[0-9a-f]{8}\.png$/)
 })
+
+// ── what the panel reads (phase 8) ────────────────────────────────────────
+//
+// The admin surface is the only thing that imports — boot never calls the shard
+// — so everything an operator can learn about an import, they learn from what
+// these two return. Each of these is a way the panel would render a confident
+// sentence that is not true.
+
+test('the vanished keys come back with the pictures they currently have', async (t) => {
+  useTempUploads(t)
+
+  const held = new Map([
+    ['body/820/a23', { key: 'body/820/a23', sha256: 'a', file: 'uo-body-820-a23-aabbccdd.png' }],
+  ])
+
+  stubEverything({ held, manifest: manifestOf([row(12, 'a')]) })
+  t.after(restore)
+
+  const result = await model.importAssets({ force: true })
+
+  // The decision being asked for is "is it right that these disappear?", and a
+  // key names nothing a human recognises. Without the filename the panel has
+  // nothing to show but `body/820/a23`, which is a horse.
+  assert.equal(result.status, 'needsReview')
+  assert.deepEqual(result.vanished, [
+    { key: 'body/820/a23', file: 'uo-body-820-a23-aabbccdd.png' },
+  ])
+})
+
+test('an import records what it did, including the body tally and who ran it', async (t) => {
+  useTempUploads(t)
+
+  const seen = stubEverything({
+    manifest: manifestOf([row(12, 'new')]),
+    fetched: {
+      assets: new Map([['body/12/a0', sprite('new')]]),
+      missing: { absent: 3, unsupported: 0 },
+    },
+  })
+  t.after(restore)
+
+  atlasDb.allCreatureTypes = async () => [{ slug: 'wolf', name: 'Wolf' }]
+  bridge.resolveBodies = async () => [
+    { slug: 'wolf', typeName: 'Wolf', body: 34, status: 'ok' },
+    { slug: 'ghost-of-something', typeName: 'GhostOfSomething', body: null, status: 'unknown' },
+  ]
+
+  await model.importAssets({ force: true, by: 'colby' })
+
+  assert.equal(seen.last.by, 'colby')
+  assert.equal(seen.last.force, true)
+  assert.equal(seen.last.written, 1)
+  assert.equal(seen.last.absent, 3)
+  // The body pass is kept as a TALLY rather than a single "resolved" number:
+  // `unknown` means the spawn files name a type this shard's scripts do not
+  // define, which is real drift, and it reads identically to a failure if both
+  // are summed into "not resolved".
+  assert.deepEqual(seen.last.bodies, { ok: 1, unknown: 1, notCreature: 0, failed: 0 })
+})
+
+test('a summary that cannot be written does not fail an import that applied', async (t) => {
+  useTempUploads(t)
+
+  stubEverything({
+    manifest: manifestOf([row(12, 'new')]),
+    fetched: {
+      assets: new Map([['body/12/a0', sprite('new')]]),
+      missing: { absent: 0, unsupported: 0 },
+    },
+  })
+  t.after(restore)
+
+  db.recordLastImport = async () => {
+    throw new Error('the meta row is locked')
+  }
+
+  // The pictures are already on disk and the rows are already committed. Failing
+  // here would report a failure for an import that succeeded, and the operator's
+  // next move — press it again — would re-fetch the whole catalogue for nothing.
+  const result = await model.importAssets({ force: true })
+
+  assert.equal(result.status, 'imported')
+  assert.equal(result.written, 1)
+})
+
+test('status says whether a shard is linked rather than leaving it to be inferred', async (t) => {
+  stubEverything({ manifest: manifestOf([]) })
+  t.after(restore)
+
+  db.getMeta = async () => ({ catalog: 'cat1', last: { by: 'colby', written: 4 } })
+
+  const linked = await model.getStatus()
+
+  assert.equal(linked.linked, true)
+  assert.deepEqual(linked.loaded.last, { by: 'colby', written: 4 })
+
+  // A shard that is linked but DOWN also reports `shard: null`, which is why the
+  // panel cannot read this off that: one wants its buttons disabled and the
+  // other wants them available so the operator can retry.
+  uoLinkConfig.getSafe = async () => ({ enabled: false, baseUrl: '' })
+
+  const unlinked = await model.getStatus()
+
+  assert.equal(unlinked.linked, false)
+  assert.equal(unlinked.reason, 'uo-link is not configured')
+})
+
+test('the catalogue count is the body family, not every asset in the table', async (t) => {
+  stubEverything({ manifest: manifestOf([]) })
+  t.after(restore)
+
+  let askedFor = 'never called'
+
+  // Item and land art live in the same table as the body catalogue (phase 5) and
+  // are counted separately on purpose: one is a set with a size, the other is
+  // however much of an unbounded space the site has happened to ask for. A
+  // whole-table count reported 1,095 portraits plus 313 item pictures as a
+  // "1,408-row catalogue" on the one screen that answers "did the import work".
+  db.countAssets = async (family) => {
+    askedFor = family
+    return { total: 1095, stored: 1095 }
+  }
+
+  const status = await model.getStatus()
+
+  assert.equal(askedFor, 'body')
+  assert.equal(status.loaded.assets, 1095)
+})
+
+test('item pictures are not "vanished" just because the body manifest never listed them', async (t) => {
+  useTempUploads(t)
+
+  // The state every install reaches within a day of its first import: a body
+  // catalogue, plus whatever item art the warm pass has fetched because a
+  // marketplace page asked for it. Both live in `shard_assets`.
+  const held = new Map([
+    ['body/12/a0', { key: 'body/12/a0', family: 'body', sha256: 'a', file: 'wolf.png' }],
+    ['static/3934/h1801', { key: 'static/3934/h1801', family: 'static', sha256: 'b', file: 'robe.png' }],
+  ])
+
+  const seen = stubEverything({ held, manifest: manifestOf([row(12, 'a')]) })
+  t.after(restore)
+
+  // The family filter is the fix, so the stub has to honour it or the test
+  // passes against a whole-table read.
+  db.allAssets = async (family) =>
+    new Map([...held].filter(([, r]) => !family || r.family === family))
+
+  const result = await model.importAssets({ force: true })
+
+  // Before the filter this was `needsReview` naming the item picture, and
+  // approving it would have deleted every picture the warm pass had fetched —
+  // with a sentence saying the shard had stopped offering them, which it had
+  // not: a body manifest never mentions item art at all.
+  assert.equal(result.status, 'imported')
+  assert.equal(result.removed, 0)
+  assert.ok(seen.saved)
+})
+
+test('an approved vanish deletes the row, not just the picture', async (t) => {
+  const dir = useTempUploads(t)
+  fs.mkdirSync(path.join(dir, model.ART_SUBDIR), { recursive: true })
+  fs.writeFileSync(path.join(dir, model.ART_SUBDIR, 'gone.png'), 'x')
+
+  const held = new Map([
+    ['body/99/a0', { key: 'body/99/a0', family: 'body', sha256: 'a', file: 'gone.png' }],
+  ])
+
+  let removedKeys = null
+
+  const seen = stubEverything({ held, manifest: manifestOf([row(12, 'a')]) })
+  t.after(restore)
+
+  db.saveAssets = async (rows, meta, remove) => {
+    seen.saved = rows
+    removedKeys = remove
+    return rows.length
+  }
+
+  const result = await model.importAssets({ force: true, approve: true })
+
+  assert.equal(result.removed, 1)
+  // The file was already unlinked before this fix; the ROW was not. A row whose
+  // picture is gone keeps being counted, keeps being offered for review on every
+  // forced import, and can still point a creature page at a file that is not
+  // there — with the import reporting "nothing was changed" about a deletion it
+  // had already performed.
+  assert.deepEqual(removedKeys, ['body/99/a0'])
+  assert.equal(fs.existsSync(path.join(dir, model.ART_SUBDIR, 'gone.png')), false)
+})