@heroiclands/package-build 3.4.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,187 @@
 # @heroiclands/package-build
 
+## 5.0.0
+
+### Major Changes
+
+- 4da0dbc: Every package publishes an authored homepage at `/<contentPackage>/`, and
+  `publish.site` becomes a mode rather than a boolean (#51, #55).
+  
+  **A `type: homepage` note (#51)**
+  
+  A new engine-level content type that compiles into a **page** rather than into a
+  compendium document. Its whole frontmatter envelope is `type` and an optional
+  `title`, defaulting to `packageBuild.manifest.title` so the package's name is not
+  written twice:
+  
+  ```markdown
+  ---
+  type: homepage
+  title: HârnMaster Kethira Basic
+  ---
+  
+  What the module is, which system it needs, how to install it.
+  ```
+  
+  It compiles into no document, appears in no pack and in no link manifest, and is
+  addressed by the **package** — `/<contentPackage>/` — rather than by a slug
+  derived from its name, so `name.full`, `shortcode` and `id` decide nothing on it.
+  It is written at the root of `site.out`, one level above the content mount.
+  
+  The page is _authored, not assembled_. Deriving it from the manifest, the release
+  address and `relationships` was the obvious shortcut and produces a page nobody
+  chose the contents of — it cannot express that Kethira requires buying the book
+  from Keléstia, or which of twenty sections a reader should start with.
+  
+  It is declared in `engine/note-schemas.mjs` rather than in the `sohl` item
+  registry: the `engine/` ÷ `sohl/` line is note-format knowledge against
+  game-system knowledge, and a homepage carries no `system` block and mirrors no
+  item builder. Reachability is the symptom that makes it obvious —
+  `HarnMaster-3-FoundryVTT` declares no `itemBuilders` at all, so a type living in
+  the SoHL registry would be unavailable to HM3 and every HM3 module, which is most
+  of the packages that need a homepage and nothing else.
+  
+  **`publish.site` is a mode (#55) — breaking**
+  
+  | Was           | Write                              |
+  | ------------- | ---------------------------------- |
+  | `site: true`  | `site: content`                    |
+  | `site: false` | `site: homepage`                   |
+  | absent        | absent — the default is `homepage` |
+  
+  `homepage` publishes the authored homepage and **no other page**; `content`
+  publishes it plus every page the content tree compiles to. There is no value
+  meaning "no web presence", because every package publishes its homepage.
+  
+  Both booleans are **refused rather than mapped** onto the nearest mode, naming
+  the mode to write. `false` read as _this package has no web presence_, which
+  describes no package now, and a value silently reinterpreted reads to its author
+  as though it still means what it said.
+  
+  **Homepage-only is a first-class mode, not an accommodation.**
+  `sohl-kethira-basic` (Keléstia Productions' Fan Material Guidelines) and
+  `harn-adventures` (HârnFanon under Lythia's terms) each publish a homepage and
+  nothing beneath it — two packages under two different fan-content licences. The
+  boundary is _published content_: journal text, artwork, item descriptions,
+  compiled notes. Because the failure mode is silent — a `site:` block added later
+  ships licensed content with nobody noticing — the mode **fences the content
+  surfaces off**: in `homepage` mode the tree is never walked for pages, and
+  `sections`, `trees`, `landing` and `backfillSections` emit nothing even when they
+  are declared. Measured against the real `sohl-kethira-basic` tree — 363 notes,
+  and a `site:` block deliberately declaring sections and a landing — the build
+  emits exactly one file.
+  
+  `publish.manifests.publish` is a separate decision and stays `false` for both, for
+  an unrelated reason: a link manifest is the dependency edge that would stop a
+  module being withdrawable, and a homepage is one row in a routing table.
+  
+  **Nothing else moves.** `publish.address`, `publish.manifests` and the whole
+  `site:` block are unchanged, and every address `sohl` already publishes is
+  byte-identical across the upgrade. Verified against the real tree: 1,669 emitted
+  files before, 1,670 after, the one addition being `kb/content/_index.md`; the
+  link manifest's 2,989 entries and all 3,126 compiled pack documents are
+  byte-identical with and without the homepage note.
+
+## 4.0.0
+
+### Major Changes
+
+- 8cfa834: Reject `package:` in a note's frontmatter (#56).
+  
+  A note's package is the repository's configured `contentPackage`, full stop. A
+  note that declares the field fails the build, naming the file — **whatever the
+  value says**. An agreeing declaration is refused exactly as a disagreeing one
+  is: there is no value that makes writing the field correct, and a field accepted
+  while it agrees is a field that grows back one note at a time.
+  
+  ```text
+  assets/content/Gear/Axe.md:12:1: error: `package: sohl` is a retired frontmatter field — delete it. A note's package is this repository's configured `contentPackage` ("sohl", in package-build.config.yaml), and every note in the tree belongs to it.
+  ```
+  
+  `content-build lint` reports every such note in one pass, so a tree can be
+  checked before it is compiled; `package compile` and `manifest` refuse it.
+  
+  **This is the third and last step**, and the two before it are already released
+  and adopted. 3.3.0 made the field optional so an absent one was normal and a
+  disagreeing one was an error; every content tree on the org was then swept on
+  that version — `sohl` (1,639 files), `thalorna` (1,716), `kethira` (363),
+  `harnensemble` (2,517). Nothing this release refuses is authored anywhere today.
+  
+  **Why a major.** Consumers resolve `^3`, so a minor would reach every repository
+  on the next Dependabot run. A major is adopted deliberately, one repository at a
+  time, in a pull request that can also delete the field if any grew back — which
+  is the whole mechanism that made the deprecate → migrate → remove sequence safe.
+  
+  **Migrating** is one line, and nothing else reads the field:
+  
+  ```bash
+  find assets/content -name '*.md' -print0 | xargs -0 sed -i '' '/^package: /d'
+  ```
+  
+  `package compile` then produces byte-identical output, because the value the
+  build derives is the value the notes restated. See `MIGRATING.md`.
+  
+  **`contentPackage` is unaffected, and is not vestigial.** It is the address
+  namespace — the first segment of every canonical key, the name of the emitted
+  link manifest, and the package a cross-package wikilink writes. Retiring the
+  frontmatter field is what leaves it as the single source of that value: every
+  key is now derived from the configuration, where it used to come from two
+  sources that happened to agree.
+  
+  **A generated table's `WHERE … and package = "<pkg>"` clause keeps matching** —
+  45 such clauses across `sohl` and `thalorna` depend on it. The package is
+  _synthesised_ into what the table search sees, from `contentPackage`; it is a
+  search value, never an authored one.
+  
+  **API.** `engine/note-package.mjs` no longer exports `notePackage` — every call
+  site takes `contentPackage` directly, so no key is derived from frontmatter
+  anywhere — and `assertNotePackage` is now `assertNoDeclaredPackage`, which
+  asserts the field's absence rather than answering which package a note belongs
+  to. `expandNoteTables` no longer takes `pkg`: a table searches the whole tree,
+  which is one package's notes and nothing else.
+- ad7691f: Remove `draft:` from a note's frontmatter (#69).
+  
+  The field excluded a note from the compiled packs, from the link manifest and
+  from a consuming site build — and **nothing reported the consequence**.
+  `content-links.mjs`, `site-index.mjs` and `content-lint.mjs` never read it, so a
+  wikilink into a drafted note was indistinguishable from a link to a note that
+  does not exist, and no checker could say which. Its entire effect was to move a
+  note from _published_ to _unresolvable_, in silence. It also suppressed real
+  build failures: a note the compilers never reached could not fail on the defects
+  it carried.
+  
+  Nothing used it. Across every HeroicLands content repository — `sohl`,
+  `sohl-thalorna`, `sohl-kethira-basic`, `harn-ensemble`, `harn-adventures` — not
+  one note declared it.
+  
+  **What changed**
+  
+  - The three readers are gone: the compile loop, the link-manifest walk, and the
+    scenes pass's map collection. So are the `skippedDraft` tally, its `PassStats`
+    field, and the `Skipped N draft(s)` log line.
+  - A note declaring `draft:` now **fails the build**, naming the file and the
+    line, whatever the value says — `draft: false` included, since it reads as
+    "publish this note", which is what happens either way. A field left merely
+    ignored reads to its author as though it still works, which is the same
+    silence in a different place.
+  - `content-build lint` reports it too, so a whole tree is answered at once
+    rather than one note per build.
+  
+  **The `draft` _tag_ is untouched.** It is an authoring marker, read only by the
+  generated-table pass for `FROM #draft` queries, and 268 `sohl-thalorna` notes
+  carry it. An unfinished page is honest about being unfinished; a dropped link is
+  silent.
+  
+  **Adopting**
+  
+  Nothing to sweep — no note in the org declares the field. A consumer that
+  carries one deletes the line.
+  
+  This lands in the same major as the `package:` rejection (#56 step 3), so the
+  two retired fields are one adoption rather than two. They are refused the same
+  way, through the same diagnostic format and the same positioning, and the
+  locator both need is now shared rather than written twice.
+
 ## 3.4.0
 
 ### Minor Changes

package/CONTENT.md

@@ -128,9 +128,11 @@ packageBuild:
     - { from: assets/icons, to: assets/icons }
 
 # Three independent switches — every combination is real — plus the address
-# scheme both `manifest` and `site` derive addresses under.
+# scheme both `manifest` and `site` derive addresses under. `site` is a mode,
+# not a boolean: `homepage` (the default) publishes the authored homepage and
+# no other page; `content` publishes it plus every page the tree compiles to.
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
@@ -147,8 +149,8 @@ site:
 
 The loader validates the document, resolves every path against the directory
 the file sits in, fills the optional halves with their defaults
-(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, every
-publishing switch off),
+(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, both
+manifest switches off and `publish.site` at its `homepage` floor),
 derives `assetRoot`, `packDirectories`, `itemTypes` and `docEntryTypes`, and
 freezes the result. A malformed configuration throws a `TypeError` naming the
 offending field, so it fails at load rather than as an empty pack much later.
@@ -178,27 +180,44 @@ something migrates on it.
 ### A note's package is the repository's, not the note's
 
 `contentPackage` is the **address namespace** every note in the tree is
-published under. It is not a filter, and a note does not restate it.
+published under: the first segment of every canonical key (`sohl-skill-clmb`),
+the name of the link manifest this build emits (`sohl.json`), and the package a
+cross-package wikilink writes to reach one of these notes. It is the
+repository's identity in the address space — not a filter — and a note does not
+restate it.
+
+**`package:` in a note's frontmatter is retired, and declaring it fails the
+build**, naming the file, whatever the value says. An agreeing declaration is
+refused exactly as a disagreeing one is: there is no value that makes writing
+the field correct. The diagnostic says so, and says where the value comes from
+instead:
 
-A note may still carry `package:` — every note written before this did — and it
-is accepted while it **agrees** with `contentPackage`. One that disagrees is an
-error naming the file, in the compile, in the link manifest, and anywhere else
-a note is read. The field is redundant, and it is being retired in three steps:
-optional now, swept out of every content tree on this version, and rejected
-outright in a later major.
+```text
+assets/content/Gear/Axe.md:12:1: error: `package: sohl` is a retired frontmatter field — delete it. A note's package is this repository's configured `contentPackage` ("sohl", in package-build.config.yaml), and every note in the tree belongs to it.
+```
+
+`content-build lint` reports every such note in one pass; `content-build
+package compile` and `content-build manifest` refuse the tree.
 
 A generated table that scopes itself with `WHERE … and package = "<pkg>"` keeps
-working either way: a note's package is supplied to the table search whether or
-not the note declares it, so deleting the field never turns a table into an
-empty one.
+working: the package is **synthesised** into what the table search sees,
+supplied from `contentPackage` rather than read off the note. It is a search
+value, never an authored one.
 
 It used to **select**: a note compiled when its `package:` matched and was
 skipped when it did not. Every content tree is single-package — each is
 single-sourced in the repository that ships it — so the field restated one
 constant thousands of times, while a tree whose notes named a package no
 configuration answered to compiled **zero notes and exited 0**. Deleting the
-field from a note is safe on this version and is the fix; deleting the
-_configured_ value is not, since every address derives from it.
+field from a note is the fix; deleting the _configured_ value is not, since
+every address derives from it.
+
+Sweeping a tree is mechanical — the field is a whole line, and nothing else
+reads it:
+
+```bash
+find assets/content -name '*.md' -print0 | xargs -0 sed -i '' '/^package: /d'
+```
 
 ### A registry of your own
 
@@ -577,10 +596,11 @@ It reads its whole input from configuration and takes nothing else:
 | `publish.address`           | The address scheme those paths are derived under — see below. |
 
 **Both addresses are optional, independently.** A note that compiles into no
-document has no `uuid`, and a package that ships compendiums and publishes no
-site (`publish.site: false`) has no `path` on any entry. Neither is an error, and
-neither is guessed: inventing the missing one asserts a target that does not
-exist, which is the silent dead link the manifest exists to prevent.
+document has no `uuid`, and a package that ships compendiums and publishes only
+a homepage (`publish.site: homepage`) has no `path` on any entry — its notes are
+not pages. Neither is an error, and neither is guessed: inventing the missing one
+asserts a target that does not exist, which is the silent dead link the manifest
+exists to prevent.
 
 **`publish.manifests.publish` is a declaration, not a preference.** The file is
 vendored by other repositories and read as authoritative, so emitting one is a
@@ -598,7 +618,7 @@ time and 404s for the reader.
 
 ```yaml
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
@@ -641,6 +661,64 @@ address derivation, the address index, table expansion, wikilink resolution,
 code-fence protection, the foreign-manifest merge, the page emission and the
 section-landing backfill.
 
+### The homepage, and how much else is published
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and what a reader finds there is a note in the content tree — one markdown file,
+written by a person:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+That is the whole envelope. A homepage **compiles into no compendium
+document**, appears in no pack and in no link manifest, and is addressed by the
+_package_ rather than by its own name — so `name.full`, `shortcode` and `id`
+decide nothing on it. It is dispatched on `type` like every other note, not on a
+filename: `README.md` is already a section landing under `landing: readme`, and
+in `sohl-thalorna` it is a developer explainer about the source tree.
+
+`type: homepage` is declared by the **engine**, not by the `sohl` item registry,
+so a package that configures no `itemBuilders` at all — `HarnMaster-3-FoundryVTT`
+and every HM3 module — can author one. The `engine/` ÷ `sohl/` line is
+note-format knowledge against game-system knowledge, and a homepage carries no
+`system` block.
+
+`publish.site` then says how much _else_ is published:
+
+| Mode       | What is published                                                               |
+| ---------- | ------------------------------------------------------------------------------- |
+| `homepage` | The authored homepage, and no other page. **The default, and the floor.**       |
+| `content`  | The homepage plus every page the content tree compiles to, and its extra trees. |
+
+There is no value meaning "no web presence": every package publishes its
+homepage. It was a boolean until 5.0.0, and both spellings are now refused
+naming the mode to write instead — see [MIGRATING.md](MIGRATING.md).
+
+**Homepage-only is a first-class mode, not an accommodation.**
+`sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's terms)
+must each publish a homepage and nothing beneath it. The boundary is _published
+content_ — journal text, artwork, item descriptions, compiled notes — and a page
+announcing the module discloses none of it. Because the failure mode is silent,
+the mode **fences the content surfaces off** rather than trusting a
+configuration to stay empty: in `homepage` mode the tree is never walked for
+pages, and `sections`, `trees`, `landing` and `backfillSections` emit nothing
+even when they are declared.
+
+That is separate from `publish.manifests.publish`, which stays off for both for
+an unrelated reason: a link manifest is the dependency edge that would stop the
+module being withdrawable, and a homepage is one row in a routing table.
+
+The homepage is written at the root of `site.out` — the package's own address —
+one level above the content mount, which is where `publish.address.prefix` puts
+everything else.
+
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the link manifest reads, so a page and its manifest entry cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
@@ -669,7 +747,7 @@ site:
 
 | Key                | What it decides                                                                                  |
 | ------------------ | ------------------------------------------------------------------------------------------------ |
-| `out`              | The Hugo content root. **Required**, and wiped on every run — see the safety note below.         |
+| `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
 | `sections`         | Landing title and hero per section, so a landing matches the card that links to it.              |

package/MIGRATING.md

@@ -1,3 +1,123 @@
+# Migrating to `@heroiclands/package-build` 5.0.0
+
+**One configuration change: `publish.site` is a mode, not a boolean.** And one
+new authoring capability that needs no migration: a `type: homepage` note.
+
+## 1. Respell `publish.site`
+
+```yaml
+publish:
+  site: content # was `site: true`
+```
+
+```yaml
+publish:
+  site: homepage # was `site: false`, or absent
+```
+
+`homepage` is the default, so a repository that never set the key needs no edit.
+A repository that set it to either boolean gets a `TypeError` at load naming the
+mode to write:
+
+```text
+package-build config: `publish.site` is no longer a boolean — write `site: content`. Every package publishes an authored homepage at /<contentPackage>/, so no value means "no web presence": `homepage` publishes that page and nothing else, and `content` publishes it plus every page the content tree compiles to.
+```
+
+Both spellings are **refused rather than mapped** onto the nearest mode. `false`
+read as _this package has no web presence_, which now describes no package at
+all, and a value silently reinterpreted reads to its author as though it still
+means what it said.
+
+Nothing else about publishing moved: `publish.address`, `publish.manifests` and
+the whole `site:` block are unchanged, and every address `sohl` and `thalorna`
+already publish is byte-identical across the upgrade.
+
+## 2. Author a homepage (optional here, required by #52)
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and the page there is a note in the content tree:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+It compiles into no compendium document, appears in no pack and in no link
+manifest, and is addressed by the package rather than by its own name. It is
+written to the root of `site.out`, one level above the content mount.
+
+A repository with no homepage note publishes none, and the site build says so in
+its count. Requiring exactly one is a separate change (#52).
+
+## 3. What homepage-only means
+
+`homepage` mode does not merely leave the content configuration unused — it
+**fences the content surfaces off**. The tree is never walked for pages, and
+`site.sections`, `site.trees`, `site.landing` and `site.backfillSections` emit
+nothing even when they are declared.
+
+That is deliberate, and it is a licensing requirement rather than a preference.
+`sohl-kethira-basic` (Keléstia Productions' Fan Material Guidelines) and
+`harn-adventures` (HârnFanon under Lythia's terms) publish a homepage and no
+other page; the failure mode is silent — a `site:` block added later ships
+licensed content with nobody noticing — so the property is asserted by the code
+path rather than left to configuration.
+
+`publish.manifests.publish` is a separate decision and stays `false` for both: a
+link manifest is the dependency edge that would stop a module being withdrawable,
+and a homepage is not.
+
+# Migrating to `@heroiclands/package-build` 4.0.0
+
+**One authoring change: delete `package:` from every content note.** A note's
+package is the repository's configured `contentPackage`, and declaring the field
+is now a build error rather than a redundancy the build tolerated.
+
+## 1. Sweep the content tree
+
+The field is a whole line, and nothing else reads it:
+
+```bash
+find assets/content -name '*.md' -print0 | xargs -0 sed -i '' '/^package: /d'
+```
+
+(GNU `sed`: `sed -i '/^package: /d'`.) Then compile — `content-build package
+compile` must produce byte-identical output to the run before the sweep, because
+the value the build derives is the value the notes restated.
+
+A note that still carries the field fails the build where it is:
+
+```text
+assets/content/Gear/Axe.md:12:1: error: `package: sohl` is a retired frontmatter field — delete it. A note's package is this repository's configured `contentPackage` ("sohl", in package-build.config.yaml), and every note in the tree belongs to it.
+```
+
+`content-build lint` reports every one of them in a single pass, so the sweep can
+be checked before it is compiled.
+
+## 2. Nothing else
+
+- **`contentPackage` stays**, and is unchanged. It is the address namespace —
+  the first segment of every canonical key, the name of the emitted link
+  manifest, and the package a cross-package wikilink writes. Every address in
+  every manifest is identical across this upgrade.
+- **A generated table's `WHERE … and package = "<pkg>"` clause keeps matching.**
+  The package is synthesised into what the table search sees, from
+  `contentPackage`; it was never the authored field that answered the clause
+  after 3.3.0.
+- **No configuration key changed**, and no CLI command, flag or exit code.
+
+## What this replaced
+
+A note used to be _selected_ by the field: it compiled when `package:` matched
+`contentPackage` and was skipped, silently and as "belongs to another pass",
+when it did not. A tree whose notes named a package no configuration answered to
+compiled **zero notes and exited 0** (#56). 3.3.0 made the field optional so
+every repository could be swept on a non-breaking version; this major removes it.
+
 # Migrating to `@heroiclands/package-build` 3.0.0
 
 `@heroiclands/content-build` and `@heroiclands/package-build` are one package.

package/bin/content-build.mjs

@@ -76,6 +76,9 @@ import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
 import { NOTE_SCHEMAS } from "../sohl/note-schemas.mjs";
+// The engine's own types, merged under the registry's so the vocabulary stands
+// in a package that configures no `itemBuilders` at all (#51).
+import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
 import {
@@ -346,7 +349,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
                 const frontmatter = lintFrontmatter(index, {
-                    schemas: NOTE_SCHEMAS,
+                    schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
                     references: argv.references,
                 });
 
@@ -823,7 +826,8 @@ function siteCommand() {
 
                 const s = result.stats;
                 log.info(
-                    `wrote ${s.content ?? 0} content page(s) + ` +
+                    `wrote ${s.homepages ?? 0} homepage(s) + ` +
+                        `${s.content ?? 0} content page(s) + ` +
                         `${s.tree ?? 0} tree page(s) + ${s.landings} ` +
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );