@nonext/husk 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,148 @@
+# @nonext/husk
+
+Release notes for the `@nonext/husk` package. Assembled from the changesets in
+`.changeset/` by `pnpm changeset version`; the GitHub release body is generated from this
+file. Never from `AGENTS.md`, which describes how this repository is worked on rather than
+what shipped.
+
+While the package is on `0.x` the minor version is where breaking changes go. A note that
+describes a breaking change says so in its first line.
+
+## 0.2.3
+
+### Patch Changes
+
+- Fixed a test in `packaging.test.ts` that still asserted `publishConfig.provenance` was
+  `true`, left over from before provenance was disabled in 0.2.2. This is what CI's
+  `pnpm verify` step for the v0.2.2 tag caught and failed on.
+
+## 0.2.2
+
+### Patch Changes
+
+- Publishing with provenance requires a public source repository; this one is private, so
+  provenance is off for now (`publishConfig.provenance: false`, and the release workflow no
+  longer sets `NPM_CONFIG_PROVENANCE`). No functional change to the package itself. Filed as
+  a patch for the same reason as 0.2.1: nothing published under the prior version.
+
+## 0.2.1
+
+### Patch Changes
+
+- Renamed the package from `@nonext/cms` to `@nonext/husk`, and the CLI command from
+  `nonext-cms` to `nonext-husk`. Filed as a patch rather than the minor version breaking
+  changes otherwise use on `0.x`, because nothing ever successfully published under the old
+  name: there is no real installed base to break.
+
+## 0.2.0
+
+### Minor Changes
+
+- 2d76d63: `@nonext/husk/firebase` no longer exports the Firestore layout.
+  
+  Removed: `bootstrapPath`, `BOOTSTRAP_KEY`, `contentPath`, `entriesPath`, `entryPath`,
+  `mediaPath`, `schemaPath`, `settingsPath`, `storageObjectPath`, `userPath`,
+  `RESERVED_COLLECTIONS`, `entryFromStored`, `metaFromStored`, `valuesFromStored`,
+  `valuesToStored`, `toIso`, `toTimestamp`, `userFromStored`, and the duplicate
+  `slugFieldKey` which is still exported from `.` and `/core`.
+  
+  Read and write through `CmsAdapter`. Publishing the collection paths would have made every
+  future change to the Firestore layout a breaking change for every customer project, which is
+  the property the adapter boundary exists to provide. If something cannot be expressed
+  through `CmsAdapter`, the adapter is missing a method, which is the smaller problem.
+  
+  Kept: `createFirestoreAdapter`, `createHuskAuth`, the claim-sync factories, the media
+  uploader, and the user directory. Those are the wiring a host cannot avoid, because Husk
+  ships no credentials and opens no connection of its own.
+- 2d76d63: Breaking: `CmsAdapter` now requires a `migrations` member.
+  
+  A hand-written adapter that compiled before this stops compiling. `migrations` holds the
+  three storage methods the migration runner drives (`select`, `read`, `write`), and they are
+  required rather than optional on purpose: an optional member lets an adapter silently have
+  no migration path, and the failure then arrives on the day somebody needs to move data
+  between schema versions. Projects using `createFirestoreAdapter` need no change.
+  
+  Filed as `minor` because the package is on `0.x`, where the minor version is where breaking
+  changes go.
+- 0042a29: `npx nonext-husk init` and `npx nonext-husk doctor`.
+  
+  The package now ships a binary. `init` scaffolds Husk into an existing Next.js App Router
+  project: the admin routes and their host halves, `cms.config.ts` with a starter collection
+  and singleton, `firestore.rules`, `storage.rules`, `firestore.indexes.json` generated from
+  those content types, `firebase.json`, and the `.env.local` that carries
+  `FIREBASE_AUTH_EMULATOR_HOST`, without which the server verifier trusts nothing and every
+  admin route redirects to sign-in. It prompts for the Firebase project, the admin route, the
+  media library, authentication and the emulators, and `--yes` takes the defaults.
+  
+  It refuses rather than overwriting. A generated file that exists and differs stops the whole
+  run, with a bounded diff per file and nothing written; `--force` is the way out and
+  `--dry-run` shows the plan. A project whose root layout cannot be moved into a route group
+  without orphaning a route is refused with the three steps that fix it, because Husk's admin
+  needs its own root layout.
+  
+  `doctor` checks the config, the rules against the templates the installed package ships,
+  composite index coverage against the content types in `cms.config.ts`, version skew between
+  the installed package and the one the app was scaffolded with, the Firebase wiring and the
+  emulator environment. It reports what it cannot check without a real Firebase project as
+  `unchecked` with a reason rather than passing it.
+  
+  New public type: `HuskConfig`, exported from `@nonext/husk` and `@nonext/husk/types`. It is
+  what `cms.config.ts` records about the scaffold, and it is read by `doctor` and by nothing
+  at runtime.
+- 2d76d63: Breaking: `can()` no longer widens a permission when a content type's matrix lists a role.
+  
+  Ticking `author` under `delete` used to make `can(author, "delete", { type })` answer
+  `true`, while `firestore.rules` answered permission-denied. A matrix narrows and never
+  widens; the resolver was reconciled to the rules rather than the other way round, because a
+  rule that reads a privilege out of a document is letting a document grant a privilege.
+  
+  Nothing that previously worked stops working: the write was already being refused. What
+  changes for a consuming project is a UI affordance that used to be enabled and is now
+  correctly disabled.
+- Add a `brand` icon (`sprout`) to the icon vocabulary for the sidebar brand row, and a `side?: "top" | "bottom"` prop to `Menu` so a trigger pinned to the bottom of a scrollable region (the sidebar's account menu) can open upward instead of pushing the region into a scrolled state. Both are additive: existing icon names and every existing `Menu` call site keep their current behavior unchanged.
+
+## 0.1.0 (unreleased)
+
+First packaged version. Nothing has been published yet, so no consuming project exists to
+break. The two changes below are classified as if one did, because a changelog is where that
+judgement is preserved and a judgement made after the fact is worth less.
+
+### Breaking
+
+- **`CmsAdapter` requires a `migrations` member.** A hand-written adapter that compiled
+  before this stops compiling. The three methods (`select`, `read`, `write`) are what the
+  migration runner drives, and they are required rather than optional deliberately: an
+  optional member would let an adapter silently have no migration path, and the failure
+  would arrive on the day somebody needed to move data between schema versions, which is the
+  worst possible day to discover it. Migration is checked against `manage-schema`, the same
+  permission that allows changing a shape. Consuming projects that use
+  `createFirestoreAdapter` need no change; the shipped adapter already implements it.
+
+- **`can()` no longer widens a permission when a content type's matrix lists a role.**
+  Ticking `author` under `delete` used to make `can(author, "delete", { type })` answer
+  `true`, while `firestore.rules` answered permission-denied, because the rule resolves the
+  role default from the token and a matrix cannot grant an action the role does not have.
+  The resolver was reconciled to the rules rather than the other way round: a rule that
+  reads a privilege out of a document is letting a document grant a privilege. A matrix
+  narrows and never widens. The visible effect for a consuming project is a UI affordance
+  that used to be enabled and is now correctly disabled; nothing that previously worked
+  stops working, because the write was already refused.
+
+### Added
+
+- The `@nonext/husk` package itself: twelve entry points (`.`, `/admin`, `/admin/ui`,
+  `/auth`, `/client`, `/server`, `/core`, `/firebase`, `/permissions`, `/richtext`,
+  `/schema`, `/types`) plus `./admin.css`, built to ESM with type declarations.
+- `packages/cms/api/public-api.md`: the reviewed public API report, shipped in the tarball.
+
+### Changed
+
+- **`@nonext/husk/firebase` no longer exports the Firestore layout.** Removed:
+  `bootstrapPath`, `BOOTSTRAP_KEY`, `contentPath`, `entriesPath`, `entryPath`, `mediaPath`,
+  `schemaPath`, `settingsPath`, `storageObjectPath`, `userPath`, `RESERVED_COLLECTIONS`,
+  `entryFromStored`, `metaFromStored`, `valuesFromStored`, `valuesToStored`, `toIso`,
+  `toTimestamp`, `userFromStored`, and the duplicate `slugFieldKey` (still exported from
+  `.` and `/core`). Read and write through `CmsAdapter`. Publishing the collection paths
+  would have made every future change to the Firestore layout a breaking change for every
+  customer project, which is the property the adapter exists to prevent. See
+  `.docs/decisions/2026-09-19-package-public-surface.md`.

package/LICENSE

@@ -0,0 +1,166 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright Nonext (https://github.com/nonext-at/nonext-husk)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,140 @@
+# @nonext/husk
+
+Nonext CMS, spoken name **Husk**. A schema-driven CMS for Next.js and Firebase, mounted at
+`/admin` inside the customer's own Next app.
+
+The site stays a normal modern frontend. Husk adds an admin UI plus a typed read SDK, so an
+editor changes content without touching Firebase, code, or a deployment.
+
+- Content types generate the sidebar, the list views, the forms, the validation and the CRUD.
+- Code-defined types (TypeScript, in git, lockable) coexist with types created in the admin
+  Schema Builder without a deploy.
+- Firebase stays behind an adapter. Nothing in the SDK names a collection or a document id.
+- One Firebase project per customer. No shared multi-tenant project.
+
+## Install
+
+The package is not on npm yet. Until the public surface stops moving, customer projects
+consume the git dependency.
+
+```json
+{
+  "dependencies": {
+    "@nonext/husk": "github:nonext-at/nonext-husk#semver:^0.1.0"
+  }
+}
+```
+
+That resolves a git tag rather than a branch, so an install is reproducible and a push to
+`main` does not change what a customer already has. Pinning one exact tag works too, and is
+what a project that is not watching this repository should do:
+
+```json
+{ "dependencies": { "@nonext/husk": "github:nonext-at/nonext-husk#v0.1.0" } }
+```
+
+The repository is a pnpm workspace and the package lives in `packages/cms`, so a plain git
+dependency on the repository root does not resolve the package by itself. Two working
+options:
+
+1. **A packed tarball**, which is what the release workflow attaches to every GitHub release:
+
+   ```json
+   { "dependencies": { "@nonext/husk": "https://github.com/nonext-at/nonext-husk/releases/download/v0.1.0/nonext-husk-0.1.0.tgz" } }
+   ```
+
+   No build step at install time, identical bytes to what npm would serve, and it works with
+   npm, pnpm and yarn without further configuration. This is the recommended path.
+
+2. **A git dependency plus `prepare`**, if a project must track a branch. The consuming
+   project needs pnpm, because the workspace has to install before the package can build.
+
+Once the surface is stable the package is published and the install line becomes
+`pnpm add @nonext/husk`. Nothing else about the wiring changes.
+
+### Peer dependencies
+
+Supplied by the customer app, never bundled by this package:
+
+| Peer | Range |
+|---|---|
+| `next` | `^16.0.0` |
+| `react` | `^19.0.0` |
+| `react-dom` | `^19.0.0` |
+| `firebase` | `^12.0.0` |
+
+Two copies of React or of the Firebase SDK is two contexts, two app instances, and hooks
+that throw, so this is enforced by a test rather than left to convention.
+
+## Setting up a project
+
+The package ships a binary. Inside an existing Next.js App Router project:
+
+```bash
+npx nonext-husk init      # scaffold the admin, the config, the rules and the indexes
+npx nonext-husk doctor    # check an existing installation
+```
+
+`init` asks for the Firebase project, the admin route, the media library, authentication
+and the emulators; `--yes` takes the defaults. It refuses to overwrite a file that exists
+and differs, and prints the difference rather than replacing your work. `doctor` exits
+non-zero when it finds a problem and reports what it cannot check without a real Firebase
+project as `unchecked`, with the reason.
+
+The full six-step setup, including the parts Husk deliberately leaves to you outside an
+emulator, is in `docs/getting-started.md` in the repository.
+
+## Entry points
+
+| Import | What it is |
+|---|---|
+| `@nonext/husk` | Schema, registry, validation, permissions, types. No React, no Next, no Firebase. |
+| `@nonext/husk/core` | The same surface under a narrower name. |
+| `@nonext/husk/types` | Types only. |
+| `@nonext/husk/schema` | Validation and the field-type registry. |
+| `@nonext/husk/permissions` | `can()`, the one permission truth table. |
+| `@nonext/husk/server` | The read SDK for server code. Preview lives here. |
+| `@nonext/husk/client` | The read SDK for browser code. No preview, by construction. |
+| `@nonext/husk/richtext` | Rendering stored rich text. Separate so a project without a rich text field does not carry Tiptap. |
+| `@nonext/husk/admin` | The server half of the admin: session, guard, route handlers, navigation as data. |
+| `@nonext/husk/admin/ui` | The client half: every React component the admin renders. |
+| `@nonext/husk/auth` | Sign-in, sign-up, roles, claims. |
+| `@nonext/husk/firebase` | The wiring: adapter, auth and upload factories. Not the Firestore layout. |
+| `@nonext/husk/admin.css` | The admin stylesheet. Import once. |
+
+`@nonext/husk/admin` and `@nonext/husk/admin/ui` are separate on purpose, and merging them
+back would break every admin route. A Next server component imports the first and gets no
+React hook in its module graph.
+
+`packages/cms/api/public-api.md`, shipped in this package as `api/public-api.md`, is the
+reviewed list of every exported name with its type.
+
+## Reading content
+
+```ts
+import { createServerCMS } from "@nonext/husk/server"
+import { createFirestoreAdapter } from "@nonext/husk/firebase"
+
+const cms = createServerCMS({
+  adapter: createFirestoreAdapter({ db }),
+  contentTypes: { projects, team },
+})
+
+const page = await cms.collection("projects").findMany({ limit: 12 })
+const project = await cms.collection("projects").findBySlug(slug) // project.title is string
+const home = await cms.single("home").get()
+const cover = await cms.media().getById(project.cover.id)
+```
+
+The reader is published-only. `CmsQuery` has no `status`, so a draft cannot leak through a
+forwarded query object or a URL parameter. Preview is a second instance
+(`cms.preview()`) and exists on the server entry only.
+
+## Versioning
+
+`0.x`: the minor version is where breaking changes go, and a release note that describes one
+says so in its first line. See `CHANGELOG.md`.
+
+## License
+
+UNLICENSED. Internal to Nonext customer projects.