fix(plugin-auth): declare plugin-hono-server and put the published example in a tsc program

.changeset/plugin-auth-example-hono-server-dependency.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+Declare `@objectstack/plugin-hono-server` and put the published auth example in a
+tsc program (#10869).
+
+`packages/plugins/plugin-auth/examples/basic-usage.ts` — the file
+`content/docs/permissions/authentication.mdx` publishes as "Basic Auth Example" —
+imports `HonoServerPlugin` from `@objectstack/plugin-hono-server` on line 12, and
+this package declared that dependency in **none** of `dependencies`,
+`devDependencies` or `peerDependencies`. (It declares `hono`, which is a different
+package.) So the example could not resolve, compile or run for anyone who copied
+it out of the docs:
+
+```
+examples/basic-usage.ts(12,34): error TS2307: Cannot find module
+'@objectstack/plugin-hono-server' or its corresponding type declarations.
+```
+
+The declaration is now there (`devDependencies`, `workspace:*` — the example is
+development material, and `files` ships only `dist`, so nothing new reaches a
+published tarball).
+
+**The dependency alone would have been unverifiable, which is the other half of
+this change.** `tsconfig.json` selects `include: ["src/**/*"]`, so `examples/` sat
+in no tsc program at all — the type-check-coverage census's only instance of that
+— and a manifest edit does not change an `include`. The fix would have had no
+compile behind it and the defect could return unseen. So the directory now has a
+program: `packages/plugins/plugin-auth/tsconfig.examples.json`, a non-emitting
+sibling named in the package's `typecheck` script, following the precedent
+`packages/spec/tsconfig.scripts.json` and `packages/objectql/tsconfig.scripts.json`
+set. Strictness is inherited, not relaxed, and the directory enters with zero
+recorded debt — the example type-checks clean under `strict`, which also measures
+that every API it demonstrates (`ObjectKernel.use`/`bootstrap`/`getService`,
+`HonoServerPlugin({ port })`, and every `AuthPluginOptions` key it passes) still
+exists as written, so it is a working reference rather than a stale one.
+
+Because the directory is now read, `packages/plugins/plugin-auth/examples` leaves
+`UNCHECKED_SOURCE_DEBT` in `scripts/check-type-check-coverage.mjs` — the ratchet
+shrinks because the thing was repaired, and `RECONCILED` required the deletion in
+the same change.

packages/plugins/plugin-auth/package.json

@@ -21,7 +21,7 @@
  "scripts": {
  "build": "tsup",
  "test": "vitest run",
- "typecheck": "tsc --noEmit"
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.examples.json"
  },
  "dependencies": {
  "@better-auth/core": "^1.7.1",
@@ -40,6 +40,7 @@
  "devDependencies": {
  "@objectstack/driver-sql": "workspace:*",
  "@objectstack/objectql": "workspace:*",
+ "@objectstack/plugin-hono-server": "workspace:*",
  "@types/node": "^26.2.0",
  "hono": "^4.13.2",
  "typescript": "^6.0.3",

packages/plugins/plugin-auth/tsconfig.examples.json

@@ -0,0 +1,36 @@
+// The EXAMPLES-layer type-check program for @objectstack/plugin-auth (#10869).
+//
+// `packages/plugins/plugin-auth/examples/` held `basic-usage.ts` -- the file
+// `content/docs/permissions/authentication.mdx` publishes as "Basic Auth
+// Example" -- and no tsc program had ever read a line of it. `tsconfig.json`
+// selects `src/**/*`, tsup builds only `src`, and nothing imports it, so it was
+// the source census's single instance of a file in NO tsc program at all. What
+// that hid: line 12 imports `@objectstack/plugin-hono-server`, which this
+// package declared in none of its dependency blocks, so the published example
+// could not resolve, compile or run for anyone who copied it.
+//
+// A SIBLING rather than a wider `include` on `tsconfig.json`, the distinction
+// #5475 drew for `packages/spec` and #10756 for `packages/objectql/scripts`,
+// and it holds here for the same reason: that config EMITS (`rootDir: "src"`,
+// `outDir: "dist"`), so widening it to reach `examples/` would put the
+// directory in front of the emit and `rootDir` would reject it -- and `tsup`
+// would start shipping the example. This program emits nothing, so it can
+// neutralise `rootDir` without touching what ships.
+//
+// STRICTNESS IS INHERITED and deliberately not relaxed: `strict`,
+// `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns` and the rest come
+// from the root config through `tsconfig.json`. The directory type-checks clean
+// under them -- it enters with ZERO recorded debt, and there is no ledger here
+// to record any in. A published example that does not compile is the finding,
+// not a line to write down.
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "noEmit": true,
+ // `.` rather than the inherited `src`, because the file this program checks
+ // is the one outside `src`. Safe precisely because nothing is emitted from
+ // here -- see the header.
+ "rootDir": "."
+ },
+ "include": ["examples/**/*"]
+}

scripts/check-type-check-coverage.mjs

@@ -1058,17 +1058,28 @@ const PHANTOM_PIN_DEBT = {};
 // `rootDir` neutralised (it emits nothing) against a built dependency closure on
 // main @ 5886ee6d22. Those counts are prose, deliberately: nothing here compares
 // them, and a number this gate does not read must not look like one it does.
+//
+// GRADUATED SINCE, so the seed count above is a starting line and not a census
+// of what is left: `packages/plugins/plugin-auth/examples` (#10869). Its entry
+// recorded 1 x TS2307 for `@objectstack/plugin-hono-server`, a package
+// plugin-auth declared in none of its dependency blocks -- and the file was the
+// census's only instance of source in NO tsc program at all, which is precisely
+// why the missing dependency could sit in a PUBLISHED example
+// (`content/docs/permissions/authentication.mdx` links it as "Basic Auth
+// Example") without any gate reading it. Repaired on the terms this header
+// names rather than by rewriting the entry: the dependency is declared
+// (`devDependencies`, `workspace:*`) AND `packages/plugins/plugin-auth/
+// tsconfig.examples.json` puts the directory in a program named in that
+// package's `typecheck` script, so the compile that reproduced the TS2307 now
+// runs on every typecheck. It type-checks clean, so it graduated with zero debt
+// recorded anywhere -- and RECONCILED forced the entry out, as this header said
+// it would.
 const UNCHECKED_SOURCE_DEBT = {
  'packages/cli/test': 'One non-test module, `test/helpers/serve-process.ts`, the spawn harness the '
  + '`os serve` e2e tests share. It measures 0 errors on its own, and it is not separate debt: it '
  + 'sits inside the hidden test tree already measured by TEST_DEBT[\'@objectstack/cli\'] (56 of '
  + 'that package\'s 110 test files are outside `include`). Repairing it means repairing that '
  + 'layer, so this entry graduates with the TEST_DEBT one rather than before it.',
- 'packages/plugins/plugin-auth/examples': 'One file, `basic-usage.ts`, and it does not compile: '
- + '1 x TS2307 for `@objectstack/plugin-hono-server`, which this package declares in NO dependency '
- + 'block. The census\'s only instance of source in no tsc program AT ALL rather than merely '
- + 'outside its own package\'s -- nothing imports it, tsup builds only `src`. Repair is a manifest '
- + 'change or a rewrite, tracked in #10869.',
  'packages/platform-objects/scripts': '`i18n-extract.config.ts`, 1 x TS2883: the inferred type of '
  + 'its `default` export names a hash-suffixed internal chunk of `@objectstack/spec`\'s dist '
  + '(`state-machine.zod-<hash>`), so it is non-portable by construction. One of 8 identical '