Files
Netcatty/docs/plugin-platform/review-2026-10.md
T

5.8 KiB

Plugin platform implementation review

Baseline: main 0256e7471d66bbbca077c361ef379d7b11ce8465 (2026-10-26).

Existing capabilities and gaps

Area Implemented source Remaining boundary
Contract, SDK, package CLI packages/plugin-contract/schema, packages/plugin-sdk, packages/plugin-cli Internal API 0.1.0-internal; no public API stability promise
Runtime electron/plugins/browserPluginRuntime.cjs, utilityPluginRuntime.cjs, hostBootstrap.cjs Entire host remains development opt-in; advanced utility is ambient Node authority, not a fine-grained sandbox
Permissions permissionEngine.cjs, hostRpcRegistry.cjs, secureCapabilities.cjs Broker checks at privileged boundary; unsigned principal bound to package digest; verified publisher/distribution not implemented
UI contributions contributionService.cjs, components/plugins, SettingsPluginsTab.tsx Commands, menus, keybindings, settings and views exist; current Settings page is contributed settings, not a package manager/marketplace
Terminal terminalProviderService.cjs, terminalDataPipelineService.cjs Completion/link/visual providers and lifecycle; interceptors require privileged utility placement; not arbitrary terminal object access
Connection, authentication, importer extensionProviderService.cjs, application/state/pluginExtensionBridge.ts Existing operation-bound provider integration; not general vault/SFTP/clipboard CRUD
Sync pluginSyncSidecarService.cjs, application/pluginSyncSidecarBridge.ts Opt-in non-secret settings and account/CRDT sidecars; ordinary KV is local, package code/permissions/secrets are not cloud authority
Compatibility plugin-cli/src/compatibility.ts, packageStore.cjs, runtimeSupervisor.cjs Install/start checks existed; startup reconciliation and lazy re-enable checks missing
Local package packageStore.cjs, CLI pack, first-party examples/plugins/hello-netcatty Immutable snapshot, hash/integrity validation and safe extraction exist; no ordinary import management UI
Distribution No public catalog implementation Version/hash/pinned README, review workflow, manual update UI still needed

Historical merged steps: #2276 contract/SDK; #2303 runtime; #2315 permission/security; #2324 UI contributions; #2338 terminal providers; #2402 privileged terminal pipeline; #2413 connection/auth/importers; #2713 sync; #2748 and #2752 sync follow-up fixes. The repository AGENTS.md runtime section describes an earlier phase and must not be mistaken for a complete current capability inventory. No repository .agents/skills directory was present at this baseline.

Small implementation slices

  1. Reconcile host/API/features compatibility before contribution enumeration; disable incompatible plugins and retain package/data, record the reason; block lazy re-enable. Do not auto-enable after a host downgrade.
  2. Reuse the existing Settings Plugins tab and management IPC for installed packages, manifest-derived permissions, version/hash and lifecycle actions; local import starts disabled for review. Keep native permission mediation.
  3. Add a lightweight first-party catalog and pinned safe README detail renderer, shared package verification, digest-bound manual update flow and author docs. Do not introduce remote accounts, reviews, payments or a new repository.
  4. Reproduce the actual Electron flow with synthetic data and the first-party sample; transfer source/build instructions if GUI is unavailable here.

Decisions and explicit release gates

User approved public source plus a clear license for catalog entries, and manual confirmation of plugin updates. Private local packages remain separate.

User-approved public v1 eligibility: browser runtime only. Utility Node, native companions and raw terminal interceptors retain the development preview path. This excludes advanced provider implementations requiring Node/native binaries; ordinary browser contributions, broker-backed networking and providers remain possible. No existing local advanced development path is removed.

After product review, normal Settings now admits browser-only packages. The NETCATTY_PLUGIN_DEV=1 flag gates advanced local packages only; their existing permission prompts remain mandatory. Shared host/UI classification preserves browser-first placement for dual-entry packages while excluding them from normal admission. Native acceptance remains pending. Passing tests is not proof of security isolation. Do not describe utility processes as broker-constrained.

A future KV sync feature needs an explicit manifest opt-in schema, size limits, namespace and schema-version migrations, deterministic conflict/deletion rules, account switching semantics and secret exclusion. It is deliberately not silently enabled in this iteration. Reuse existing settings sidecars for small preferences.

Catalog entries should bind ID, repository, license, author, version, commit, artifact SHA-256 and URL, platform/engine ranges, permissions and README revision. A hash mismatch must fail rather than fall back to latest. README must not execute HTML or automatically fetch remote media. Directory PR checks are a bounded review process, not a security certification or a guarantee that maintainers will repair third-party plugins.

Validation at the implementation stage

The full repository TypeScript check has 773 diagnostics on both the frozen main and this implementation. After normalizing worktree paths and line shifts, no new diagnostics were introduced. This existing debt includes plugin integration types and should be addressed in a separate API-drift cleanup rather than being hidden by changing public contracts opportunistically. Canonical contract drift checking and plugin runtime tests pass for this implementation; native Electron UI acceptance is tracked separately in native-acceptance.md.