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

[os-warren]

Fixes#10869

packages/plugins/plugin-auth/examples/basic-usage.ts line 12 imports
HonoServerPlugin from @objectstack/plugin-hono-server, and
packages/plugins/plugin-auth/package.json declared that package 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.

Reproduced first, on this tree

The card measured the failure at main @ 5886ee6d22 and the tree has moved, so
it was re-measured at merge base 163a16241 with the dependency closure built,
through the program this PR adds:

$ cd packages/plugins/plugin-auth
$ pnpm exec tsc --noEmit -p tsconfig.examples.json
examples/basic-usage.ts(12,34): error TS2307: Cannot find module '@objectstack/plugin-hono-server' or its corresponding type declarations.
TSC_EXIT=2

Same file, same line, same column as the card. The identical invocation after
the fix:

$ cd packages/plugins/plugin-auth
$ pnpm exec tsc --noEmit -p tsconfig.examples.json
TSC_EXIT=0 (0 bytes of output)

⚠️ One detail worth recording, because it is the instrument and not the defect: on
a first run the same command also reported basic-usage.ts(13,28): error TS2307
for @objectstack/plugin-auth itself. That is the unbuilt-closure artifact, not a
finding — the example self-references its own package, which resolves through
dist/index.d.ts, and that package had not been built. Building it removed the
second error and left exactly the one above. typecheck-workspace in lint.yml
builds @objectstack/plugin-auth before running typecheck (confirmed by
turbo run build --filter='./packages/*' --filter='./examples/*^...' --dry=json,
which lists @objectstack/plugin-auth#build), so the self-reference resolves in
CI. It is left resolving through dist rather than repointed with a paths
block: that would be a partial, unledgered paydown of a different shrink-only
registry (check:type-source-resolution, where this package is one of 51
registered entries), and half-paying a ratchet is worse than not touching it.

Which repair, and the measurement that chose it

The card names two and declines to pick. Measured, they separate cleanly:

1. The example is published, not orphaned.
   content/docs/permissions/authentication.mdx:1284 links it under "Complete
   working examples are available in the repository" as "Basic Auth Example".
   Deleting it breaks a live docs link and removes a reference readers are being
   sent to.
2. The hono pairing is a documented, supported pattern, stated in the
   plugin's own class docblock (src/auth-plugin.ts): "Server mode
   (HonoServerPlugin active): Registers HTTP routes at basePath". The two
   packages are at the same version (17.1.0), and plugin-hono-server exports
   HonoServerPlugin with HonoPluginOptions.port?: number — exactly what the
   example passes.
3. The API it demonstrates still exists as written. This is what the clean
   compile above measures, under inherited strict: ObjectKernel, use(),
   bootstrap(), getService(), shutdown(), HonoServerPlugin({ port }), and
   every AuthPluginOptions key it passes (secret, baseUrl, databaseUrl,
   providers[], plugins{organization,twoFactor,passkeys,magicLink},
   session{expiresIn,updateAge}, registerRoutes, basePath).

Nothing here reads as stale. Repair 1 — declare the dependency — and the example
stays a working reference.

The other half: repair 1 alone would have been unverifiable

tsconfig.json selects include: ["src/**/*"], and a manifest edit does not
change an include. After a bare manifest edit the example would still compile
in no program, pnpm typecheck would still ignore it, and the only evidence
for the fix would be that the right package name was typed.

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. That is the
in-tree precedent, not a new shape — packages/spec/tsconfig.scripts.json (#5475)
and packages/objectql/tsconfig.scripts.json (#10756) are the same file for the
same reason, and check-type-check-coverage.mjs names the sibling as the remedy
in its own header. A sibling rather than widening tsconfig.json because that
config emits (rootDir: "src", outDir: "dist"): widening it would put
examples/ in front of the emit, rootDir would reject it, and tsup would
start shipping the example. Strictness is inherited and not relaxed.

$ pnpm --filter @objectstack/plugin-auth run typecheck
> @objectstack/plugin-auth@17.1.0 typecheck
> tsc --noEmit && tsc --noEmit -p tsconfig.examples.json
TYPECHECK_EXIT=0

The UNCHECKED_SOURCE_DEBT entry — deleted because the directory is read now

This PR is the widen-the-program case, so the entry must go, and the gate
said so before it was touched rather than after:

$ pnpm check:type-check-coverage # BEFORE the ledger edit
GATE_EXIT=1
• UNCHECKED_SOURCE_DEBT entry for "packages/plugins/plugin-auth/examples" is no longer
unread source (a tsc program reads it now, or the directory is gone) -- delete it from
scripts/check-type-check-coverage.mjs. That is the ratchet: this list only shrinks.

The entry is gone, and the header records the graduation so SEEDED AT 10 cannot
be read as "still 10". The directory graduates with zero debt recorded
anywhere — it type-checks clean, so there was nothing to write down. The ratchet
shrank because the thing was repaired, which is the only reason it is allowed to:

$ pnpm check:type-check-coverage # AFTER
GATE_EXIT=0
check-type-check-coverage: OK — 65/78 workspace packages type-checked (plus the root) …
source layer: 9 directory(ies) of non-test source in 9 ledgered entr(y/ies) sit outside
every tsc program their package's own `typecheck` runs (9 files as counted by this run).

10 directories → 9.

Ablation — prediction written before mutating

Predicted, in writing before the mutation: removing the devDependency line and
re-installing turns the program RED, exit 2, with exactly one error —
examples/basic-usage.ts(12,34): error TS2307: Cannot find module '@objectstack/plugin-hono-server' ….
Direction predicted as a straight red, not a count change and not a reversal,
because the widened program compiles the file unconditionally and only the
resolution is being removed.

Observed: exit 2, exactly that one error, exactly that line.

Both legs ran pnpm install, because the thing being ablated is the pnpm
workspace symlink rather than a dist/ artifact — a manifest edit alone leaves
the symlink in place and the mutated leg would have stayed green, which is the
manifest-layer form of an unrebuilt ablation. Each leg proved the symlink's state
before reading tsc: LINK ABSENT on the mutation leg, LINK PRESENT on the
restore leg.

Restore proved byte-identical:

pre-ablation package.json : c2f5f3bdd79a2b2c4abb086b38717def53d811e4
post-restore package.json : c2f5f3bdd79a2b2c4abb086b38717def53d811e4
pre-ablation pnpm-lock : 8491e01df7bc5f9468ddaad40f1adac461090c37
post-restore pnpm-lock : 8491e01df7bc5f9468ddaad40f1adac461090c37

Why devDependencies and not dependencies

Counter-check, with the positive control run first so the instrument is proven
on the corpus before its silence is read as evidence: the exact pattern that finds
the import in examples/ finds nothing in src/.

control grep -rn "from '@objectstack/core'" src/ → 3 hits (instrument reaches corpus)
claim grep -rn "from '@objectstack/plugin-hono-server'" src/ → exit 1, zero hits
control grep -rn "from '@objectstack/plugin-hono-server'" examples/ → basic-usage.ts:12 (pattern itself works)

A first attempt at this used a regex whose own positive control came back empty —
the bracket expression [^\n]* excludes the literal n, so it matched nothing.
That run was not measured and is not quoted here; the control is what caught
it. Three plugin-hono-server strings do exist in src/, and all three are
comment prose, inspected line by line rather than counted.

files ships only dist, README.md and CHANGELOG.md, so nothing new reaches
a published tarball. No cycle: plugin-hono-server names plugin-auth in none of
its dependency blocks.

Gates

Union derived on the final commit a144502c, clean tree,
node scripts/pm/dispatch-gates.mjs with no path arguments (5 paths vs merge
base 163a16241; exit 0). Every exit code captured before any pipe. All 20 derived
families plus check:published-files and check:nul-bytes, added by judgment
because a package.json and a new tsconfig were edited — class #10309 is live and
the derivation is known short. The derivation did not name either of those two.

All green (EXIT=0): check:changeset-gate-self-tests,
check:cross-package-test-inputs, check:entry-guard, check:objectui-changeset,
check:override-consistency, check:parse-guard, check:slot-lookup,
check:test-source-alias, check:type-check-coverage, check:type-check-debt,
check:type-source-resolution, check-adr-0087-registration,
check-changeset-fixed, check-changeset-no-major, check-ci-filter-parity,
check-empty-changeset, check-osv-exemptions, check-plugin-teardown-shape,
check-affected-docs, check:published-files, check:nul-bytes.

Their own verdict lines, quoted rather than inferred from $?:

• check-type-check-coverage: OK — 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger …
• check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 381.0s, 1908 raw tsc error(s) total, none above its recorded number.
• check-type-source-resolution OK — 77 packages with a tsconfig.json scanned; 51 registered as still resolving a workspace dep's types through 'dist/'.
• check-nul-bytes: OK (scanned 6357 text file(s) … no raw ASCII control bytes).

⚠️check:type-check-debt first exited 1 with --re-measure cannot run: 30 workspace dependenc(ies) … have no built type entry point on disk. That is a refusal, not a
measurement — nothing was checked. The closure was built exactly as lint.yml
does (turbo run build --filter='./packages/*' --filter='./packages/*/*', 70/70
successful) and the gate re-run to the green verdict quoted above.

Package suite, script name echoed so a zero-match cannot read as a pass:

$ pnpm --filter @objectstack/plugin-auth run test
declared script: vitest run
Test Files 67 passed (67)
Tests 1400 passed (1400)
TEST_EXIT=0

Left alone deliberately

check:type-check-debt reports @objectstack/plugin-auth: TEST_DEBT records 109, tsc now reports 97 (-12) -- the entry can be lowered. That surplus is the standing
one tracked in #10615, it pre-dates this branch, and this PR touches no test and no
src file. --lower was not run: that ledger is not this card's to move.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/plugins/plugin-auth/tsconfig.examples.json) — pages documenting those are invisible to this run

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 490879ad0fe22c57d74799828a49feac6860757a → packageMentionDocs.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 32560319985 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Console Pin Gate — 失败步骤: Build the Console SPA at the pinned objectui SHA

  ✗ Build failed in 5.94s
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 87 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)