[naerymdan]

Brings the layered ports-and-adapters design and the static analysis gates of kandev-plugin-forgejo#35 to this plugin. Behaviour is unchanged by the refactor itself; the fixes that review turned up are listed under Fixes found in review.

Design

docs/architecture.md has the layer table, what enforces each rule, and the practices a linter can't check. An import may only point to a lower layer:

Layer	Packages
foundation	internal/remote (quoting, command output, the admin login, SSH error kinds), internal/kandev (the late-bound Host, state documents, action responses)
model	egress, profile, hosts, secrets, pki, msbctl (the protocol, run through its Runner port): pure
features	hostcheck (Test's diagnosis, certificate care), sandbox (the provider's decisions), readiness, hostsetup (machine setup, plus the setup and upgrade jobs). No SDK
adapters	sshx (keyring, pool, admin login), store (every Host state and secret key)
transport	internal/plugin: one handler per surface; wire.go is the only file that names an adapter
entry	server

What changed to get there:

• Runtime is no longer a god object. Every action and provider RPC was a method on it, with access to every adapter. Each surface now has its own handler holding only the ports it uses: hosts, CA, secrets, egress, host jobs, readiness and the executor provider. Actions route through a table instead of a switch.
• One store package. Host-state load and save was written out six times, for the registry, egress, secrets, status, CA and API URL. All of it is now in internal/store over one codec (kandev.LoadDocument/SaveDocument).
• Decisions moved out of the transport:
  • the diagnosis and certificate care went to hostcheck;
  • placement, recovery, the bootstrap, the provision request and Kandev's states went to sandbox, which is SDK-free;
  • secret validation went to secrets;
  • the readiness items went to readiness;
  • the job table and the setup and upgrade flows went to hostsetup.
• Features no longer import the SSH adapter. Host setup and the diagnosis matched on sshx error sentinels and used its Output type. Those now live in internal/remote.
• Large files are split by concern. hostsetup.go (750 lines) is now one file per step. In the UI, the hosts page row (complexity 38), hostDetail (38), toActionError (17) and the egress page are split into hooks and render helpers. The UI's job view is no longer a module-level variable.

Measured

	before	after
Go average cyclomatic complexity	4.77	3.80
Go worst cyclomatic / cognitive	21 / 20	15 / 15
Go functions over cyclomatic 15	6	0
UI functions over complexity 12 / over 100 lines	3 / 2	0 / 0
golangci-lint issues (gate config)	16	0

Enforced

• internal/archtest fails go test on an import that crosses a layer, or on a package missing from the table.
• golangci-lint (.golangci.yml, same as the forgejo plugin) runs staticcheck, errorlint, unparam, gocyclo 15, gocognit 20, nestif 5, funlen 50 statements and dupl.
• ESLint with typescript-eslint caps UI complexity, function length and file length.
• dependency-cruiser forbids cycles, the model importing components, and imports of bundle.ts.
• make lint runs all of them. CI installs golangci-lint from its checksummed release binary.
• make metrics and make deadcode report without failing. deadcode currently finds nothing.
• go.mod ignores node_modules, where flatted ships Go sources.

Verification

• make lint, make test-race, make test-ui and make verify-package-host pass locally.
• No test expectation changed. Test plumbing that named moved internals was updated:
  • the in-memory host moved to kandevtest;
  • the bootstrap and lease-header unit tests moved to internal/sandbox;
  • one placement assertion goes through sandbox.PlaceOrReuse.
• New UI tests render the host row and the egress page against a stub host.
• An independent review compared every old handler with its new home. These fixes from it are in the last commit:
  • a reworded base_url error string is restored;
  • Jobs.Stop takes the table lock again, so a job cannot start during Close;
  • two decisions still in the transport moved into hostcheck and sandbox.

Also bumps vitest to 4.1.12 for two moderate @vitest/mocker advisories, GHSA-qxg6-89mg-rqv8 and GHSA-xp26-3454-mjgp. The lockfile was made with npm 11, because npm 10 crashes resolving the linked SDK package. docs/development.md now says so. npm audit reports 0 vulnerabilities.

Fixes found in review

Every finding below was reproduced with a failing test first; each test is kept.

• Regression from the refactor: a host write before the CA existed loaded, and on a fresh install generated, the plugin's SSH key. HealNow now connects only once a root exists (TestAddWithoutARootLeavesTheKeyAlone).

• A root that exists but cannot be used (its key is gone from the secret store, unreadable, or does not match) was treated as "no root yet": hosts.add/update reported nothing and logged nothing, setup.status failed as a whole, and ca.create refused to replace it even with replace: true, which left no way out. pki.ErrRootUnusable now marks exactly these cases, which are now handled like this:

  • Test reports root_unusable (it used to blame the host with tls_install_failed).
  • hosts.add/update answer tls root_unusable.
  • The root readiness item is failing, with the replace step.
  • ca.create answers 409 naming replace: true, and replaces the root when that is set.

  A failure to read the store is kept separate: it stays a retryable 500 and never replaces the root (TestAnUnusableRootIsReportedAndReplaceable, TestAStoreOutageIsNotAnUnusableRoot).

• The add-existing-host form let Add pin a host key that was scanned for one destination after the destination was edited. It now requires the scan to match, as the setup form already did (UI test in pages.test.ts).

• Misnamed failures: an unreadable SSH key, or unreadable last-check results, were reported as the host registry's (TestAnUnreadableKeyIsNamed, TestUnreadableCheckResultsAreNamed), and a refused admin login was logged as "host refused the plugin's ssh key".

• The maintainer connected, and so created the key, with no hosts registered (TestMaintainingNoHostsLeavesTheKeyAlone).

All but the first were already on main. CHANGELOG.md and docs/configuration.md are updated.

Checked and ruled out, so not changed:

• the setup job's closure does not keep the admin login after the dial (heap-dump probe, with positive and negative controls);
• JobView's stale onFinished is harmless;
• the //nolint:errcheck directives on <-done are needed.