feat!: publish versioned plugin SDKs with compatibility checks

Merged
ZE
1d ago
+14896-944

[!TIP]
PR walkthrough: Open the visual walkthrough

Plugin authors can compile and typecheck against published Go/npm SDKs without a sibling Kandev source checkout. This implements SDK extraction, installed-dependency compatibility checks, and verified Stable publication for #4358. The first public release and external repository migrations remain outstanding.

Implementation

  • Extract github.com/kdlbs/kandev/pluginsdk, including the canonical protocol, and migrate host imports. Update host builds, Docker/preview layouts, and CI selection for the separate module.
  • Publish runtime-free @kdlbs/plugin-sdk types. Go and npm share an independent SDK version starting at 0.1.0, release records, pinned packing tools, and a verified archive inventory.
  • Add kandev-sdk-check. It checks the actual selected Go module and installed npm/pnpm dependency evidence, Stable host minimum, highest consumed SDK floor, and supported API versions. It supports npm hoisting, checkout aliases, and pnpm managed-store links while rejecting local SDK substitutions. Workspace locks have a 32 MiB limit; manifests and release records retain a 1 MiB limit.
  • Add protected signing/retention and separate OIDC publication jobs. Signed source identity, exact archive/receipt verification, immutable retries, bootstrap recovery, and clean public consumers gate Stable completion and contributor notices.
  • Update public author/release guides, requirements/design, SDK READMEs, author inventory, and migration handoffs for both external templates. Backend-owned plugin-pack still requires a separately pinned tooling checkout or equivalent validated packaging.

Compatibility

Old Go imports must migrate; there is no forwarding package. Frontend source consumers must replace the former local @kandev/plugin-sdk name in dependencies, imports, and lockfiles. Already-built plugins retain the same wire protocol and handshake. A real legacy subprocess test verifies handshake and a Host state roundtrip, but does not certify every third-party plugin or frontend bundle. Adopting a newer SDK can raise a plugin's minimum supported host. SDK numbering remains independent of host and plugin versions.

Reliability and validation

Integrated main through 3f3aabc53f23cc8b08f0bf2b1b766b88fbeaf7f2 in
4e965e8393efbefea386f333bd042757ae2804e7. The preceding merge resolves
review-scroll and silent-output fixture conflicts. Review input cancels a
pending restoration before enabling marking, while retaining main's touch
contact support and mouse/pen restrictions. Shared unique gates retain the
silent-output and completion holds. The Go module keeps main's new ACP
replacement plus the standalone SDK requirement/local replacement.

  • Local verification passes 135 focused frontend tests, full typecheck, module tidy/verify, scoped lint and backend rich-output race checks. All 30 freshly rebuilt browser cases pass with retries disabled: 23 locale, three desktop and four phone cases. Documentation coverage passes 36 work orders and 118 linked documents.
  • Main advanced again to d17d84a8084b15ddf1df10ff465a51d27c780e64. The exact synthetic merge f45a92e02e7166c51a4eb2d1919ae37a82619642 is conflict-free and passes 107 focused image/rendering/review tests plus docs/spec validation (414 decisions / 1,802 specifications). It was tested in an owned temporary worktree and was not pushed.
  • SDK source, npm packaging, signing/publication scripts and protected release automation are unchanged by reconciliation. The Windows persistence compilation allowance remains twenty minutes; test deadlines, race flags and required gating remain intact. Recovered E2E retries remain informational; exhausted failures still block.
  • Fresh checks for this head are required in the check rollup. The preceding head's 95 green checks are historical. Normal commit hooks pass without bypass.
  • The operator owns the PR merge. No SDK publication, release dispatch, protected-setting change, external migration or notification was performed. NOTIFICATION_GUIDE.md remains uncommitted.

Implementation plan and receipts · Adversarial review record

Release prerequisites

No release was dispatched or SDK published by this task. Actual Stable preparation must resolve the initial host metadata. Authenticated npm checks confirm zval owns the kdlbs organization. Maintainers must record ownership confirmation in release and release-validation, configure trusted publishing with direct-publish and dist-tag permissions, and handle any first-package bootstrap using the exact retained archive. Public verification must pass before announcing availability. External template/plugin migrations and author notifications remain separate work.

Eleven external migration tasks remain queued, with briefs updated to the selected namespace. Petdex and Augpool are retired.

Related: #4358. This PR is ready for review. Do not close the issue from this delivery.

Checklist

  • If I do not have repository write access and this is a large architectural change, I discussed the direction in a linked issue before opening this PR.
  • This PR contains one logical change; unrelated work is split into separate PRs.
  • I have performed a self-review of my code.
  • I have manually tested my changes and they work as expected.
  • My changes have tests that cover the new functionality and edge cases.
  • If my change touches UI files (apps/web/), I have added or updated Playwright e2e tests in apps/web/e2e/ and verified them with make test-e2e.
  • I checked whether this affects public docs in docs/public/** and updated them or noted why no docs change is needed.