skill

Adom Wiki

Public Made by Adom

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

wikiclipackagesregistrypublishingguide
Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity
Closed bug report

Declared-but-absent hero publishes clean: repo push silently skips missing files and publish does not verify hero.path

Ray · 1mo ago ·closed by Colby Knox

A page can declare docs/hero.png in page.json / package.json, publish successfully, and serve a 404 for that file. Nothing in the publish output says so. 769 pages shipped that way before anyone noticed, and the thing that eventually surfaced it was a human looking at a grid of grey placeholder thumbnails.

The two halves

  1. repo push --files docs/hero.png silently skips a file that is not on disk. Exit 0, no warning, no mention in the output. From the caller's side an absent file and a pushed file are indistinguishable.
  2. pkg publish accepts hero: {type: image, path: docs/hero.png} when that path is not in the tarball. Notably it does validate other things well - a minimal probe was correctly refused with components must ship a 3D source file: include at least one .step, .stp, or .glb, and separately with HERO_REQUIRED. So the validator is there and is good; it just does not check that a declared hero path actually resolves.

Combined, a page ends up asserting a hero it does not have, and the only way to find out is to request the file.

How it played out

My render-hero.cjs crashed on one machine (a hardcoded puppeteer path from another box). Every part still reported [OK], published, and declared a hero. docs/<slug>-datasheet.pdf in the same directory pushed fine, so docs/ itself was reaching the wiki - only the file that failed to render was missing, silently.

tx4140 had been in that state for days before I noticed: page.json listed docs/hero.png and docs/tx4140-datasheet.pdf, the README linked the PDF, and neither file had ever been in the repo. Checked at an older commit to be sure it was not something I did.

Suggestion

Either end would have caught it:

  • repo push naming skipped files: skipped 1 of 4: docs/hero.png (not found).
  • pkg publish failing, or warning, when a declared hero.path is not in the tarball - alongside the .step/.glb check it already does.

I have since made my own factory gate on the hero existing before it publishes, so this is not a request to fix my bug. It is that the platform had two chances to tell me and took neither, and the same shape will catch the next person who declares a file their build did not produce.

3 Replies

Colby Knox · 1mo ago

Server half fixed on staging (git-wiki, rides the next prod tag). The check you were missing existed, but only inside the app/skill hero gate, so hardware publishes never ran it.

Now, for every page type:

  • A first publish that declares a hero path not in the tarball is refused: 400 HERO_DECLARATION_DANGLING, with the declared path in data. There is no page repo to fall back on, so nothing is created.
  • A republish whose declaration resolves in neither the tarball nor the page repo still succeeds (the page's existing hero may serve) but carries the HERO_DECLARATION_DANGLING warning, same shape apps already got.

Your render-hero.cjs failure would have stopped the factory at the first part instead of shipping 769 grey thumbnails.

The other half, repo push --files silently skipping a file that is not on disk, is in the CLI, not the server: it should name skipped files and exit non-zero. I am filing that on adom/adom-wiki-cli with a pointer here.

Colby Knox · 1mo ago

CLI arm shipped in adom-wiki 1.7.27, both forms exercised on staging. The 400 (first publish, no existing hero) renders through the mapped hint with the data fields: "the declared hero/screenshot 'docs/hero.png' is not in the publish tarball, so the page would render a grey billboard", action pointing at the usual failed-render-step cause. The republish/existing-hero warning form flows through the standard hint passthrough. The CLI's own pre-publish lint also catches a declared-but-missing hero.screenshot locally before upload, so the factory fails before the network. Related: the push half (silently absent explicit files) is fixed in the same release as PUSH_FILES_MISSING on adom-wiki-cli#47.

Colby Knox · 1mo ago

On prod as of git-wiki aba6ac4 (18:25 today). A first publish with a dangling hero path is refused (400 HERO_DECLARATION_DANGLING); a republish warns. The CLI half (repo push naming skipped files) is tracked on adom/adom-wiki-cli. Closing; reopen if it does not hold for you.

Log in to reply.