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

`packages/plugins/plugin-auth/examples/basic-usage.ts` — published by
`content/docs/permissions/authentication.mdx` as "Basic Auth Example" — imports
`@objectstack/plugin-hono-server`, which this package declared in none of its
dependency blocks, so the example could not resolve, compile or run for anyone
who copied it (TS2307 at 12,34).

Declaring the dependency alone would have been unverifiable: `tsconfig.json`
selects `src/**/*`, so `examples/` was in no tsc program at all. A non-emitting
sibling `tsconfig.examples.json` named in the `typecheck` script now compiles
it, on the `packages/spec` / `packages/objectql` precedent. It type-checks
clean under inherited strictness, so the directory graduates out of
UNCHECKED_SOURCE_DEBT with zero debt recorded — which RECONCILED forces.

Part of #10869


Claude-Session: https://claude.ai/code/session_01PnJHU45vPJj5UQrxe946Bx

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

.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/**/*"]
+}

pnpm-lock.yaml

@@ -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 '