@viglet/create-shio-app 2026.3.2 → 2026.3.3

package/LICENSE

@@ -1,201 +1,201 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,10 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/@viglet/create-shio-app?logo=npm)](https://www.npmjs.com/package/@viglet/create-shio-app)
 [![License](https://img.shields.io/npm/l/@viglet/create-shio-app)](https://github.com/openviglet/shio/blob/HEAD/LICENSE)
-[![Website](https://img.shields.io/badge/shio.viglet.org-0ea5e9?logo=googlechrome&logoColor=white)](https://shio.viglet.org/)
+[![Website](https://img.shields.io/badge/website-0ea5e9?logo=googlechrome&logoColor=white)](https://openviglet.github.io/shio/)
 
 Scaffold a **Next.js (App Router)** site wired to the Content Delivery API of
-**[Viglet Shio](https://shio.viglet.org/)**, the open source **headless CMS built
+**[Viglet Shio](https://openviglet.github.io/shio/)**, the open source, **agent-ready CMS
 for coding agents**.
 
 The flagship "JS dev, zero Java" starter — a JavaScript/TypeScript developer
@@ -92,7 +92,7 @@ npm test   # node:test — scaffolds into a temp dir and asserts the output
 
 ## License
 
-Apache-2.0 — [Viglet Shio](https://shio.viglet.org/) ·
+Apache-2.0 — [Viglet Shio](https://openviglet.github.io/shio/) ·
 [github.com/openviglet/shio](https://github.com/openviglet/shio) ·
 [docs.viglet.org/shio](https://docs.viglet.org/shio/) ·
 part of the [Viglet](https://www.viglet.org) open source family.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@viglet/create-shio-app",
-  "version": "2026.3.2",
-  "description": "Scaffold a Next.js (App Router) site wired to the Shio CMS Content Delivery API. The flagship 'JS dev, zero Java' starter.",
-  "homepage": "https://shio.viglet.org/",
+  "version": "2026.3.3",
+  "description": "Scaffold a Next.js (App Router) site wired to the Viglet Shio Content Delivery API. The flagship 'JS dev, zero Java' starter.",
+  "homepage": "https://openviglet.github.io/shio/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openviglet/shio.git",
@@ -53,7 +53,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "emit": "node src/emit.mjs",
-    "test": "node --test \"test/*.test.mjs\"",
+    "test": "node --import ../scripts/test-watchdog.mjs --test \"test/*.test.mjs\"",
     "emit:check": "node scripts/emit-guard.mjs"
   }
 }

package/src/emit.mjs

@@ -1,292 +1,292 @@
-/*
- * Copyright (C) 2016-2026 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0.
- *
- * SH119 — generate the `nextjs-starter` blueprint package from this package's
- * `template/` tree, so there is one starter with two ways to get it: offline
- * (`npm create shio-app`, which copies the tree) and from an instance
- * (`shio init --blueprint nextjs-starter`, which downloads the package's `files`).
- *
- * SH156 — and generate the section-vocabulary packages' front-end half the same way, as
- * **the same tree plus an overlay**. That is the answer to "how do packages share a tree
- * instead of each carrying a copy": they each carry a copy and *nobody writes one*. A
- * hand-maintained second starter would drift within a release; a generated one cannot,
- * because `test/emit.test.mjs` fails the build the moment it disagrees with its sources.
- *
- * Why generate rather than share. A running Shio reads blueprints off the classpath
- * and cannot run a JS build, so the bytes have to exist under
- * `shio-app/src/main/resources/blueprints/`. That is a second copy by necessity, which
- * is precisely why the drift test exists — the same discipline `shio-sections`' `emit`
- * uses for post-type defs.
- *
- * Run: `pnpm -C create-shio-app run emit`
- */
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-import { rangeFor, unpublished } from "./published.mjs";
-import { readTemplateFiles } from "./scaffold.mjs";
-
-/** Where the blueprint packages live, relative to this file. */
-const BLUEPRINTS = fileURLToPath(
-  new URL("../../shio-app/src/main/resources/blueprints/", import.meta.url)
-);
-
-/**
- * The section vocabulary's front-end half, authored once (SH156).
- *
- * <p>It lives in `shio-sections` rather than here because the vocabulary owns how it
- * renders — the same argument that puts its post-type defs in `src/post-types.ts`. This
- * package owns the *starter*, that one owns the *sections*, and `emit` is where they
- * meet.</p>
- */
-const SECTIONS_OVERLAY = fileURLToPath(new URL("../../shio-sections/front-end/", import.meta.url));
-
-/**
- * A package's own index page, one directory per package (SH216).
- *
- * <h2>Why these live here and the section overlay does not</h2>
- *
- * <p>The section overlay lives in `shio-sections` because <b>the vocabulary owns how it
- * renders</b> — the same argument that puts its post-type defs in `src/post-types.ts`. These have
- * no vocabulary. `blog`, `docs` and `product-catalog` are ordinary posts with an HTML field, and
- * what each is missing is one page the starter cannot provide because it is about the *model*
- * rather than about any page: the posts newest first, the documentation tree, the catalogue grid.
- * That belongs to whoever owns the starter, which is this package.</p>
- *
- * <p><b>Not beside the blueprint</b>, which was the tempting answer: `blueprints/<name>/files/` is
- * the tree `emit` <em>writes</em>, so a source overlay in the same directory would put input and
- * output in one place and make the drift test compare a thing with itself.</p>
- */
-const packageOverlay = (name) =>
-  fileURLToPath(new URL(`../overlays/${name}/`, import.meta.url));
-
-/** `@viglet/shio-sections`' own package.json — the version the overlay depends on. */
-const SECTIONS_MANIFEST = fileURLToPath(
-  new URL("../../shio-sections/package.json", import.meta.url)
-);
-
-/**
- * Every package generated from the starter tree.
- *
- * <p>Named explicitly rather than globbed, for the same reason `shio-sections`' target
- * list is: a package that stops carrying a front end is a decision, and it should look
- * like one here.</p>
- *
- * <p><b>`blog`, `docs` and `product-catalog` carry an index page instead of the section
- * overlay (SH216).</b> They do not compose sections — their models are ordinary posts with an
- * HTML field, which the starter's catch-all already renders — so the section tree would ship a
- * dependency they never import and let three packages claim a front end that renders their pages
- * no better than the plain starter does. What each was actually missing is one page the starter
- * cannot provide because it is about the <em>model</em>: a post list at `/blog`, a navigation tree
- * at `/docs`, a grid at `/products`. Three shapes, which is exactly why it is three overlays and
- * not one.</p>
- */
-export const PACKAGES = [
-  { name: "nextjs-starter", overlay: null },
-  { name: "marketing-site", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
-  { name: "landing", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
-  // No `needs`: an index page uses the SDK the starter already depends on. That is the whole
-  // distinction from the section overlay, which brings a vocabulary with it.
-  { name: "blog", overlay: packageOverlay("blog") },
-  { name: "docs", overlay: packageOverlay("docs") },
-  { name: "product-catalog", overlay: packageOverlay("product-catalog") },
-];
-
-/** Where the carried tree lives inside a package. */
-const FILES_SUBDIR = "files";
-
-/** The starter's package directory — kept as a named export for SH119's callers. */
-export const PACKAGE_DIR = join(BLUEPRINTS, "nextjs-starter/");
-
-/**
- * The manifest's `files` refs for a carried tree.
- *
- * <p>`path` is where the file goes in the caller's project; `from` is where its bytes
- * live in the package. Both are always stated: the tree lives under `files/` so the
- * package root stays readable (manifest, model, content, tree), and the two names differ
- * for dotfiles anyway — a leading dot is stripped inside the package, which is the same
- * dodge the npm template uses for `gitignore` and which the `path` now undoes *in the
- * format* rather than in each consumer's code.</p>
- *
- * @param {Array<{path: string, text: string}>} files
- */
-export function fileRefs(files) {
-  return files.map((file) => ({ path: file.path, from: sourcePath(file) }));
-}
-
-/** Where a row's bytes are written inside the package. */
-export function sourcePath(file) {
-  return `${FILES_SUBDIR}/${file.path.replace(/^\./, "")}`;
-}
-
-/** Read an overlay directory as the same `{path, text}` rows the template produces. */
-export async function readOverlay(dir) {
-  if (!dir || !existsSync(dir)) return [];
-  const rows = [];
-  for (const rel of await listFiles(dir)) {
-    rows.push({ path: rel, text: await readFile(join(dir, rel), "utf8") });
-  }
-  return rows.sort((a, b) => a.path.localeCompare(b.path));
-}
-
-async function listFiles(dir, prefix = "") {
-  const out = [];
-  for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isDirectory()) {
-      out.push(...(await listFiles(join(dir, entry.name), rel)));
-    } else {
-      out.push(rel);
-    }
-  }
-  return out;
-}
-
-/**
- * The tree one package carries: the starter, with the overlay's files replacing or
- * joining it, and the dependencies the overlay needs added to `package.json`.
- *
- * <p>Replace-by-path is what keeps the overlay small. The section-aware catch-all route
- * is the starter's route plus one branch, so it <em>is</em> `app/[...slug]/page.tsx`
- * rather than a second route the project would have to be told about.</p>
- *
- * @param {Array<{path: string, text: string}>} base    the starter tree
- * @param {Array<{path: string, text: string}>} overlay files that replace or join it
- * @param {Record<string, string>} dependencies         added to the project's package.json
- */
-export function compose(base, overlay, dependencies = {}) {
-  const byPath = new Map(base.map((file) => [file.path, file]));
-  for (const file of overlay) {
-    byPath.set(file.path, file);
-  }
-  if (Object.keys(dependencies).length > 0) {
-    const manifest = byPath.get("package.json");
-    if (!manifest) {
-      throw new Error("emit: the starter tree has no package.json to add dependencies to");
-    }
-    const parsed = JSON.parse(manifest.text);
-    // Sorted, so adding one dependency does not reorder the ones already there and the
-    // generated diff is the change and nothing else (P5).
-    parsed.dependencies = Object.fromEntries(
-      Object.entries({ ...parsed.dependencies, ...dependencies }).sort(([a], [b]) =>
-        a.localeCompare(b)
-      )
-    );
-    byPath.set("package.json", {
-      path: "package.json",
-      text: `${JSON.stringify(parsed, null, 2)}\n`,
-    });
-  }
-  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
-}
-
-/**
- * The dependency ranges an overlay's `needs` resolve to.
- *
- * <h3>The comment that used to be here was exactly backwards (SH446)</h3>
- *
- * <p>It read: "read from the workspace rather than written down here, so a release that bumps
- * `@viglet/shio-sections` cannot leave the generated packages pointing at a version nobody
- * published." Reading it from the workspace is what <em>guarantees</em> pointing at a version nobody
- * published — the workspace is the version being <em>built</em>, and it is installable only in the
- * instant after a release. Measured on `@viglet/shio-client`, whose template range was derived the
- * same way: `^2026.3.1` against a registry that had `2026.2.1`, so `npm install` in a fresh scaffold
- * failed `ETARGET` and nothing in the repository noticed, because nothing installs from the
- * registry.</p>
- *
- * <p>So the published range wins when there is one ({@link rangeFor}), and the workspace's is the
- * fallback for a package that has never been published at all — where no range is correct and
- * writing *something* at least leaves a project that is right the day the release runs.
- * {@link unpublishedNeeds} is what reports that state, and `emit` prints it.</p>
- */
-export async function resolveNeeds(needs) {
-  if (!needs || needs.length === 0) return {};
-  const { version } = JSON.parse(await readFile(SECTIONS_MANIFEST, "utf8"));
-  return Object.fromEntries(needs.map((name) => [name, rangeFor(name) ?? `^${version}`]));
-}
-
-/** The `needs` across every package that name something the registry does not have (SH446). */
-export function unpublishedNeeds() {
-  return unpublished([...new Set(PACKAGES.flatMap((pkg) => pkg.needs ?? []))]);
-}
-
-/** The whole tree one entry of {@link PACKAGES} should carry. */
-export async function filesFor(pkg, base) {
-  const template = base ?? (await readTemplateFiles());
-  if (!pkg.overlay) return template;
-  return compose(template, await readOverlay(pkg.overlay), await resolveNeeds(pkg.needs));
-}
-
-/**
- * Read a package's manifest with its `files` list replaced by what its tree currently
- * holds — the shape `emit` would write. Pure, so the drift test can compare it against
- * what is on disk without touching the filesystem twice.
- */
-export async function expectedManifest(files, name = "nextjs-starter") {
-  const manifest = JSON.parse(await readFile(join(BLUEPRINTS, name, "blueprint.json"), "utf8"));
-  return { ...manifest, files: fileRefs(files) };
-}
-
-/** The bytes a package should carry, keyed by package-relative path. */
-export function expectedSources(files) {
-  return new Map(files.map((file) => [sourcePath(file), file.text]));
-}
-
-export async function emit({ log = console.log } = {}) {
-  const base = await readTemplateFiles();
-  const emitted = {};
-
-  for (const pkg of PACKAGES) {
-    const dir = join(BLUEPRINTS, pkg.name);
-    if (!existsSync(dir)) {
-      throw new Error(
-        `emit: the ${pkg.name} blueprint package is missing at ${dir}. ` +
-          "The manifest is hand-authored (it declares the params and the promise); only " +
-          "`files` and the carried tree are generated."
-      );
-    }
-    const files = await filesFor(pkg, base);
-
-    // Rewritten wholesale so a file deleted from the template disappears here too — a
-    // stale leftover would be shipped to every project that applies the package.
-    await rm(join(dir, FILES_SUBDIR), { recursive: true, force: true });
-    for (const file of files) {
-      const target = join(dir, sourcePath(file));
-      await mkdir(dirname(target), { recursive: true });
-      await writeFile(target, file.text, "utf8");
-    }
-
-    const manifest = await expectedManifest(files, pkg.name);
-    await writeFile(join(dir, "blueprint.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-
-    log(`✓ emitted ${files.length} file(s) into blueprints/${pkg.name}`);
-    emitted[pkg.name] = files.map((file) => file.path);
-  }
-
-  // SH446 — said at the moment the file is written, because the alternative is a stranger's
-  // `npm install` saying it, and by then the scaffold is on their disk and this repository is not.
-  const missing = unpublishedNeeds();
-  if (missing.length) {
-    log(
-      `\n! ${missing.join(" ")} ${missing.length === 1 ? "is" : "are"} NOT on the registry, so the `
-        + `starter${missing.length === 1 ? "" : "s"} carrying the section overlay cannot `
-        + `npm install outside this monorepo.\n`
-        + `  No range fixes it — publish them, then record the range in src/published.mjs.\n`
-        + `  \`shio init\` (no --blueprint) is unaffected: it carries only published packages.\n`,
-    );
-  }
-
-  return { files: emitted["nextjs-starter"], packages: emitted, unpublished: missing };
-}
-
-// `pathToFileURL`, not a hand-built `file://` string: on Windows `process.argv[1]` is
-// `D:\...` while `import.meta.url` is `file:///D:/...`, so the concatenated form never
-// matched and running the script did nothing at all — silently, which is the worst way for
-// a generator to fail.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  await emit();
-}
+/*
+ * Copyright (C) 2016-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0.
+ *
+ * SH119 — generate the `nextjs-starter` blueprint package from this package's
+ * `template/` tree, so there is one starter with two ways to get it: offline
+ * (`npm create shio-app`, which copies the tree) and from an instance
+ * (`shio init --blueprint nextjs-starter`, which downloads the package's `files`).
+ *
+ * SH156 — and generate the section-vocabulary packages' front-end half the same way, as
+ * **the same tree plus an overlay**. That is the answer to "how do packages share a tree
+ * instead of each carrying a copy": they each carry a copy and *nobody writes one*. A
+ * hand-maintained second starter would drift within a release; a generated one cannot,
+ * because `test/emit.test.mjs` fails the build the moment it disagrees with its sources.
+ *
+ * Why generate rather than share. A running Shio reads blueprints off the classpath
+ * and cannot run a JS build, so the bytes have to exist under
+ * `shio-app/src/main/resources/blueprints/`. That is a second copy by necessity, which
+ * is precisely why the drift test exists — the same discipline `shio-sections`' `emit`
+ * uses for post-type defs.
+ *
+ * Run: `pnpm -C create-shio-app run emit`
+ */
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { rangeFor, unpublished } from "./published.mjs";
+import { readTemplateFiles } from "./scaffold.mjs";
+
+/** Where the blueprint packages live, relative to this file. */
+const BLUEPRINTS = fileURLToPath(
+  new URL("../../shio-app/src/main/resources/blueprints/", import.meta.url)
+);
+
+/**
+ * The section vocabulary's front-end half, authored once (SH156).
+ *
+ * <p>It lives in `shio-sections` rather than here because the vocabulary owns how it
+ * renders — the same argument that puts its post-type defs in `src/post-types.ts`. This
+ * package owns the *starter*, that one owns the *sections*, and `emit` is where they
+ * meet.</p>
+ */
+const SECTIONS_OVERLAY = fileURLToPath(new URL("../../shio-sections/front-end/", import.meta.url));
+
+/**
+ * A package's own index page, one directory per package (SH216).
+ *
+ * <h2>Why these live here and the section overlay does not</h2>
+ *
+ * <p>The section overlay lives in `shio-sections` because <b>the vocabulary owns how it
+ * renders</b> — the same argument that puts its post-type defs in `src/post-types.ts`. These have
+ * no vocabulary. `blog`, `docs` and `product-catalog` are ordinary posts with an HTML field, and
+ * what each is missing is one page the starter cannot provide because it is about the *model*
+ * rather than about any page: the posts newest first, the documentation tree, the catalogue grid.
+ * That belongs to whoever owns the starter, which is this package.</p>
+ *
+ * <p><b>Not beside the blueprint</b>, which was the tempting answer: `blueprints/<name>/files/` is
+ * the tree `emit` <em>writes</em>, so a source overlay in the same directory would put input and
+ * output in one place and make the drift test compare a thing with itself.</p>
+ */
+const packageOverlay = (name) =>
+  fileURLToPath(new URL(`../overlays/${name}/`, import.meta.url));
+
+/** `@viglet/shio-sections`' own package.json — the version the overlay depends on. */
+const SECTIONS_MANIFEST = fileURLToPath(
+  new URL("../../shio-sections/package.json", import.meta.url)
+);
+
+/**
+ * Every package generated from the starter tree.
+ *
+ * <p>Named explicitly rather than globbed, for the same reason `shio-sections`' target
+ * list is: a package that stops carrying a front end is a decision, and it should look
+ * like one here.</p>
+ *
+ * <p><b>`blog`, `docs` and `product-catalog` carry an index page instead of the section
+ * overlay (SH216).</b> They do not compose sections — their models are ordinary posts with an
+ * HTML field, which the starter's catch-all already renders — so the section tree would ship a
+ * dependency they never import and let three packages claim a front end that renders their pages
+ * no better than the plain starter does. What each was actually missing is one page the starter
+ * cannot provide because it is about the <em>model</em>: a post list at `/blog`, a navigation tree
+ * at `/docs`, a grid at `/products`. Three shapes, which is exactly why it is three overlays and
+ * not one.</p>
+ */
+export const PACKAGES = [
+  { name: "nextjs-starter", overlay: null },
+  { name: "marketing-site", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
+  { name: "landing", overlay: SECTIONS_OVERLAY, needs: ["@viglet/shio-sections"] },
+  // No `needs`: an index page uses the SDK the starter already depends on. That is the whole
+  // distinction from the section overlay, which brings a vocabulary with it.
+  { name: "blog", overlay: packageOverlay("blog") },
+  { name: "docs", overlay: packageOverlay("docs") },
+  { name: "product-catalog", overlay: packageOverlay("product-catalog") },
+];
+
+/** Where the carried tree lives inside a package. */
+const FILES_SUBDIR = "files";
+
+/** The starter's package directory — kept as a named export for SH119's callers. */
+export const PACKAGE_DIR = join(BLUEPRINTS, "nextjs-starter/");
+
+/**
+ * The manifest's `files` refs for a carried tree.
+ *
+ * <p>`path` is where the file goes in the caller's project; `from` is where its bytes
+ * live in the package. Both are always stated: the tree lives under `files/` so the
+ * package root stays readable (manifest, model, content, tree), and the two names differ
+ * for dotfiles anyway — a leading dot is stripped inside the package, which is the same
+ * dodge the npm template uses for `gitignore` and which the `path` now undoes *in the
+ * format* rather than in each consumer's code.</p>
+ *
+ * @param {Array<{path: string, text: string}>} files
+ */
+export function fileRefs(files) {
+  return files.map((file) => ({ path: file.path, from: sourcePath(file) }));
+}
+
+/** Where a row's bytes are written inside the package. */
+export function sourcePath(file) {
+  return `${FILES_SUBDIR}/${file.path.replace(/^\./, "")}`;
+}
+
+/** Read an overlay directory as the same `{path, text}` rows the template produces. */
+export async function readOverlay(dir) {
+  if (!dir || !existsSync(dir)) return [];
+  const rows = [];
+  for (const rel of await listFiles(dir)) {
+    rows.push({ path: rel, text: await readFile(join(dir, rel), "utf8") });
+  }
+  return rows.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+async function listFiles(dir, prefix = "") {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listFiles(join(dir, entry.name), rel)));
+    } else {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * The tree one package carries: the starter, with the overlay's files replacing or
+ * joining it, and the dependencies the overlay needs added to `package.json`.
+ *
+ * <p>Replace-by-path is what keeps the overlay small. The section-aware catch-all route
+ * is the starter's route plus one branch, so it <em>is</em> `app/[...slug]/page.tsx`
+ * rather than a second route the project would have to be told about.</p>
+ *
+ * @param {Array<{path: string, text: string}>} base    the starter tree
+ * @param {Array<{path: string, text: string}>} overlay files that replace or join it
+ * @param {Record<string, string>} dependencies         added to the project's package.json
+ */
+export function compose(base, overlay, dependencies = {}) {
+  const byPath = new Map(base.map((file) => [file.path, file]));
+  for (const file of overlay) {
+    byPath.set(file.path, file);
+  }
+  if (Object.keys(dependencies).length > 0) {
+    const manifest = byPath.get("package.json");
+    if (!manifest) {
+      throw new Error("emit: the starter tree has no package.json to add dependencies to");
+    }
+    const parsed = JSON.parse(manifest.text);
+    // Sorted, so adding one dependency does not reorder the ones already there and the
+    // generated diff is the change and nothing else (P5).
+    parsed.dependencies = Object.fromEntries(
+      Object.entries({ ...parsed.dependencies, ...dependencies }).sort(([a], [b]) =>
+        a.localeCompare(b)
+      )
+    );
+    byPath.set("package.json", {
+      path: "package.json",
+      text: `${JSON.stringify(parsed, null, 2)}\n`,
+    });
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * The dependency ranges an overlay's `needs` resolve to.
+ *
+ * <h3>The comment that used to be here was exactly backwards (SH446)</h3>
+ *
+ * <p>It read: "read from the workspace rather than written down here, so a release that bumps
+ * `@viglet/shio-sections` cannot leave the generated packages pointing at a version nobody
+ * published." Reading it from the workspace is what <em>guarantees</em> pointing at a version nobody
+ * published — the workspace is the version being <em>built</em>, and it is installable only in the
+ * instant after a release. Measured on `@viglet/shio-client`, whose template range was derived the
+ * same way: `^2026.3.1` against a registry that had `2026.2.1`, so `npm install` in a fresh scaffold
+ * failed `ETARGET` and nothing in the repository noticed, because nothing installs from the
+ * registry.</p>
+ *
+ * <p>So the published range wins when there is one ({@link rangeFor}), and the workspace's is the
+ * fallback for a package that has never been published at all — where no range is correct and
+ * writing *something* at least leaves a project that is right the day the release runs.
+ * {@link unpublishedNeeds} is what reports that state, and `emit` prints it.</p>
+ */
+export async function resolveNeeds(needs) {
+  if (!needs || needs.length === 0) return {};
+  const { version } = JSON.parse(await readFile(SECTIONS_MANIFEST, "utf8"));
+  return Object.fromEntries(needs.map((name) => [name, rangeFor(name) ?? `^${version}`]));
+}
+
+/** The `needs` across every package that name something the registry does not have (SH446). */
+export function unpublishedNeeds() {
+  return unpublished([...new Set(PACKAGES.flatMap((pkg) => pkg.needs ?? []))]);
+}
+
+/** The whole tree one entry of {@link PACKAGES} should carry. */
+export async function filesFor(pkg, base) {
+  const template = base ?? (await readTemplateFiles());
+  if (!pkg.overlay) return template;
+  return compose(template, await readOverlay(pkg.overlay), await resolveNeeds(pkg.needs));
+}
+
+/**
+ * Read a package's manifest with its `files` list replaced by what its tree currently
+ * holds — the shape `emit` would write. Pure, so the drift test can compare it against
+ * what is on disk without touching the filesystem twice.
+ */
+export async function expectedManifest(files, name = "nextjs-starter") {
+  const manifest = JSON.parse(await readFile(join(BLUEPRINTS, name, "blueprint.json"), "utf8"));
+  return { ...manifest, files: fileRefs(files) };
+}
+
+/** The bytes a package should carry, keyed by package-relative path. */
+export function expectedSources(files) {
+  return new Map(files.map((file) => [sourcePath(file), file.text]));
+}
+
+export async function emit({ log = console.log } = {}) {
+  const base = await readTemplateFiles();
+  const emitted = {};
+
+  for (const pkg of PACKAGES) {
+    const dir = join(BLUEPRINTS, pkg.name);
+    if (!existsSync(dir)) {
+      throw new Error(
+        `emit: the ${pkg.name} blueprint package is missing at ${dir}. ` +
+          "The manifest is hand-authored (it declares the params and the promise); only " +
+          "`files` and the carried tree are generated."
+      );
+    }
+    const files = await filesFor(pkg, base);
+
+    // Rewritten wholesale so a file deleted from the template disappears here too — a
+    // stale leftover would be shipped to every project that applies the package.
+    await rm(join(dir, FILES_SUBDIR), { recursive: true, force: true });
+    for (const file of files) {
+      const target = join(dir, sourcePath(file));
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.text, "utf8");
+    }
+
+    const manifest = await expectedManifest(files, pkg.name);
+    await writeFile(join(dir, "blueprint.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+    log(`✓ emitted ${files.length} file(s) into blueprints/${pkg.name}`);
+    emitted[pkg.name] = files.map((file) => file.path);
+  }
+
+  // SH446 — said at the moment the file is written, because the alternative is a stranger's
+  // `npm install` saying it, and by then the scaffold is on their disk and this repository is not.
+  const missing = unpublishedNeeds();
+  if (missing.length) {
+    log(
+      `\n! ${missing.join(" ")} ${missing.length === 1 ? "is" : "are"} NOT on the registry, so the `
+        + `starter${missing.length === 1 ? "" : "s"} carrying the section overlay cannot `
+        + `npm install outside this monorepo.\n`
+        + `  No range fixes it — publish them, then record the range in src/published.mjs.\n`
+        + `  \`shio init\` (no --blueprint) is unaffected: it carries only published packages.\n`,
+    );
+  }
+
+  return { files: emitted["nextjs-starter"], packages: emitted, unpublished: missing };
+}
+
+// `pathToFileURL`, not a hand-built `file://` string: on Windows `process.argv[1]` is
+// `D:\...` while `import.meta.url` is `file:///D:/...`, so the concatenated form never
+// matched and running the script did nothing at all — silently, which is the worst way for
+// a generator to fail.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await emit();
+}

package/src/published.mjs

@@ -40,15 +40,24 @@
  * A `null` is not a placeholder to fill in with a guess: it means the package has no version on the
  * registry at all, so **no range is correct** and any scaffold carrying it cannot install. It is
  * recorded rather than hidden so the failure has a name, and `unpublished()` is what reports it.
+ *
+ * The `null` form is kept now that nothing uses it (SH502). It is the shape the next unpublished
+ * package needs, and the two readers that branch on it — `init`'s warning and the SH448 conformance
+ * — are written against `unpublished()` rather than against a fixed list, so they already work in
+ * both worlds. Deleting it would mean rediscovering the answer the next time a package is added
+ * ahead of its release, which is the situation these two rows spent two blocks in.
  */
 export const PUBLISHED = {
   "@viglet/shio-client": "^2026.2.1",
-  // SH156 made these publishable and no release has run, so both answer E404. The section-carrying
-  // starters (`marketing-site`, `landing`) import the vocabulary, so they cannot be made installable
-  // by choosing a different range — only by publishing. Left declared so the gap is a row rather
-  // than an absence.
-  "@viglet/shio-model": null,
-  "@viglet/shio-sections": null,
+  // SH502 — these were `null` for two blocks: SH156 made them publishable and no release had run, so
+  // both answered E404 and the section-carrying starters (`marketing-site`, `landing`), which import
+  // the vocabulary, could not be made installable by choosing a different range. Only by publishing.
+  //
+  // The release landed on 2026-08-12 at `2026.3.2` and both now resolve. Caret on the published
+  // version, the same rule `@viglet/shio-client` follows one line up and for the same reason: it
+  // resolves today and picks up the next release without this file being edited again.
+  "@viglet/shio-model": "^2026.3.2",
+  "@viglet/shio-sections": "^2026.3.2",
 };
 
 /** The packages a scaffold would need and the registry does not have. */

package/template/README.md

@@ -1,6 +1,6 @@
 # {{projectName}}
 
-A [Next.js](https://nextjs.org) (App Router) site powered by **Shio CMS** via the
+A [Next.js](https://nextjs.org) (App Router) site powered by **Viglet Shio** via the
 Content Delivery API — headless, TypeScript-first, **zero Java**.
 
 ## Getting started
@@ -26,6 +26,7 @@ Content Delivery API — headless, TypeScript-first, **zero Java**.
 - [`lib/shio.ts`](lib/shio.ts) creates a shared [`@viglet/shio-client`](https://www.npmjs.com/package/@viglet/shio-client) instance from the environment.
 - [`app/page.tsx`](app/page.tsx) lists the site's published posts (`shio.query`).
 - [`app/[...slug]/page.tsx`](app/[...slug]/page.tsx) resolves any path to a post via `shio.getPostByUrl(siteId, "/the/path")` — friendly-URL routing straight from the CDA, with `generateStaticParams` (SSG) + `revalidate` (ISR).
+- [`middleware.ts`](middleware.ts) answers a path that moved. Redirects written in Shio (a `Redirect` post, or keeping an old address working when a page is renamed) come from the CDA's `/site/{siteId}/redirects` table, held for 60 seconds, and a moved path gets its `301` or `302` before any page is looked up. The logic is in [`lib/redirects.ts`](lib/redirects.ts).
 
 All content comes from the Shio CDA (`/api/v2/cda/**`). You never touch the Java backend — just edit React/TypeScript.
 
@@ -104,5 +105,5 @@ by hand.
 
 ## Learn more
 
-- [Shio CMS](https://github.com/openviglet/shio)
+- [Viglet Shio](https://github.com/openviglet/shio)
 - [Next.js Docs](https://nextjs.org/docs)

package/template/app/layout.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 
 export const metadata = {
   title: "Shio site",
-  description: "Powered by Shio CMS — headless, JavaScript-first.",
+  description: "Powered by Viglet Shio — headless, JavaScript-first.",
 };
 
 export default function RootLayout({ children }: { children: ReactNode }) {

package/template/gitignore

@@ -24,3 +24,9 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# shio: the CLI's derived state — a clone's progress and inventory, a conversion
+# proposal, and SH1117's conditional-read cache. None of it is content, all of it
+# is reproducible, and the read cache holds response bodies that belong to nobody's
+# history.
+/shio/.shio/

package/template/lib/redirects.ts

@@ -0,0 +1,106 @@
+/**
+ * The site's redirect table, consulted before a page is looked up (Shio roadmap SH1133).
+ *
+ * A redirect written in Shio — a `Redirect` post, or the "keep the old address working" offer when
+ * a page is renamed — is honoured by Shio's own `/sites/**` delivery. This front end serves the
+ * site's URLs itself, so it has to do the redirecting: `middleware.ts` asks here first.
+ *
+ * Plain TypeScript with no `next` import, so it can be tested with `node --test` directly.
+ */
+
+/** One row of `GET /api/v2/cda/site/{siteId}/redirects`. */
+export interface Redirect {
+  from: string;
+  to: string;
+  permanent: boolean;
+}
+
+/** Where a moved path goes, and with which status. */
+export interface Moved {
+  destination: string;
+  status: 301 | 302;
+}
+
+/**
+ * The spelling Shio matches paths in: repeated slashes collapsed, one leading slash, no trailing
+ * one (the root stays `/`). Case is kept, as it is on the server.
+ */
+export function canonicalPath(path: string): string {
+  const collapsed = ("/" + (path ?? "")).replace(/\/{2,}/g, "/");
+  // Repeated slashes are already collapsed, so there is at most one to take off the end.
+  return collapsed.length > 1 ? collapsed.replace(/\/$/, "") : collapsed;
+}
+
+/** The row for this path, or `null` when it did not move. */
+export function findRedirect(
+  table: readonly Redirect[] | null | undefined,
+  path: string
+): Moved | null {
+  const wanted = canonicalPath(path);
+  for (const row of table ?? []) {
+    if (row.to && canonicalPath(row.from) === wanted) {
+      return { destination: row.to, status: row.permanent ? 301 : 302 };
+    }
+  }
+  return null;
+}
+
+/**
+ * A cached lookup over a table loaded by `load`.
+ *
+ * The table is small and changes rarely, so it is held for `ttlMs` (the same 60 seconds the pages'
+ * ISR window uses) rather than fetched per request. A load that fails keeps the last table it had —
+ * an unreachable CMS must never turn every request into an error — and is retried after the same
+ * interval rather than on the next request.
+ */
+export function redirectLookup(
+  load: () => Promise<readonly Redirect[] | null>,
+  ttlMs = 60_000,
+  now: () => number = Date.now
+): (path: string) => Promise<Moved | null> {
+  let table: readonly Redirect[] = [];
+  let loadedAt = Number.NEGATIVE_INFINITY;
+  // Requests arriving while a load is in flight wait for that load rather than starting their own.
+  let pending: Promise<void> | null = null;
+  return async (path: string) => {
+    if (!pending && now() - loadedAt >= ttlMs) {
+      loadedAt = now();
+      pending = load()
+        .then((loaded) => {
+          table = loaded ?? [];
+        })
+        .catch(() => {
+          // Keep the last table: see the note above.
+        })
+        .finally(() => {
+          pending = null;
+        });
+    }
+    if (pending) await pending;
+    return findRedirect(table, path);
+  };
+}
+
+/**
+ * The loader `middleware.ts` uses: the CDA's redirect table for one site.
+ *
+ * It calls the endpoint with `fetch` rather than through `@viglet/shio-client`, because the SDK's
+ * `getRedirects` is newer than the release this template installs. A Shio instance that predates the
+ * endpoint answers 404, which is an empty table here rather than an error.
+ */
+export function cdaRedirects(
+  baseUrl: string,
+  siteId: string,
+  token?: string
+): () => Promise<Redirect[] | null> {
+  return async () => {
+    if (!siteId) return null;
+    const url = `${baseUrl.replace(/\/+$/, "")}/api/v2/cda/site/${encodeURIComponent(siteId)}/redirects`;
+    const response = await fetch(url, {
+      headers: { Accept: "application/json", ...(token ? { Key: token } : {}) },
+    });
+    if (response.status === 404) return [];
+    if (!response.ok) throw new Error(`redirect table: HTTP ${response.status}`);
+    return (await response.json()) as Redirect[];
+  };
+}

package/template/middleware.ts

@@ -0,0 +1,31 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { cdaRedirects, redirectLookup } from "./lib/redirects";
+
+/**
+ * Answers a path that moved with the redirect written for it in Shio (roadmap SH1133).
+ *
+ * Shio's own delivery honours its redirects; this site does not go through that delivery, so the
+ * table is consulted here, before any page is looked up. A redirect's source is its own address in
+ * Shio, so it never shadows a page: the CMS refuses a redirect over a page that exists.
+ */
+const moved = redirectLookup(
+  cdaRedirects(
+    process.env.SHIO_URL ?? "http://localhost:2710",
+    process.env.SHIO_SITE_ID ?? "",
+    process.env.SHIO_CDA_TOKEN
+  )
+);
+
+export async function middleware(request: NextRequest) {
+  const found = await moved(request.nextUrl.pathname);
+  if (!found) return NextResponse.next();
+  // A relative destination is on this site; an absolute one is passed through as written.
+  const destination = new URL(found.destination, request.url);
+  if (!destination.search) destination.search = request.nextUrl.search;
+  return NextResponse.redirect(destination, found.status);
+}
+
+export const config = {
+  // Everything but Next's own assets and this app's route handlers; a moved path may end in `.html`.
+  matcher: ["/((?!_next/|api/).*)"],
+};