docs: plan diagnostic contract extension

2026-08-03 23:06:56 +02:00
parent 319d1add2e
commit 25a85b972e
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Workspace Diagnostic Contract Extension Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` to implement this plan task-by-task.
+
+**Goal:** Make workspace connector diagnostics executable without weakening least privilege or storing secrets in Git.
+
+**Architecture:** Extend the canonical descriptor with vector database/schema identity, optional writer-only bindings, and declared REST/embedding diagnostic contracts. The backend resolves only local `*_FILE` values, uses bounded transport adapters, and runs a vector write probe only when a reversible writer RPC and a distinct local writer binding both exist.
+
+**Tech Stack:** TypeScript, Zod, YAML, Fastify, native fetch, OpenSSH, Vitest.
+
+## Global Constraints
+
+- Descriptor Git files never contain secrets; all secrets are deterministic local variables ending `_FILE`.
+- Writer credentials are optional and distinct from reader credentials; never substitute a reader key.
+- A write probe requires a declared reversible RPC, bounded cleanup in `finally`, and must never call an upsert-only endpoint.
+- REST diagnostics use only descriptor-declared method, path, auth mode and response fields.
+- SSH uses `StrictHostKeyChecking=yes`, a short-lived local forward, and cleanup in `finally`.
+- Every diagnostic uses `workspaceDiagnosticTimeoutMs`, emits only stable redacted errors, and is tested with fakes or loopback only.
+
+## File Structure
+
+| Path | Responsibility |
+| --- | --- |
+| `backend/src/workspaces/schema.ts` | Canonical vector identity and diagnostics contracts. |
+| `backend/src/workspaces/contracts.ts` | Reader/writer variable names and `.env.example` documentation. |
+| `backend/src/workspaces/runtime-renderer.ts` | Renders vector `database` and `schema`, not DWH identity. |
+| `backend/src/workspaces/diagnostics.ts` | Bounded direct/REST/SSH/vector/embedding adapters. |
+| `backend/test/workspaces-{schema,contracts,diagnostics}.test.ts` | TDD coverage for validation, protocol and cleanup. |
+| `docs/workspace-diagnostic-protocol.md` | Service-operator protocol and local variable contract. |
+
+### Task 1: Define canonical diagnostic contracts
+
+**Files:** modify `backend/src/workspaces/schema.ts`, `backend/src/workspaces/contracts.ts`, `backend/src/workspaces/runtime-renderer.ts`; test `backend/test/workspaces-schema.test.ts`, `backend/test/workspaces-contracts.test.ts`.
+
+- [ ] Write failing tests that reject blank `vector_store.database`/`schema`, render their distinct values, and generate `VECTOR_WRITER_*_FILE` only for an optional `vector_writer` role.
+- [ ] Run `npx vitest run test/workspaces-schema.test.ts test/workspaces-contracts.test.ts` and observe failure.
+- [ ] Implement `vector_store.database`, `vector_store.schema`, optional `vector_writer`, `diagnostics.dwh_rest`, `diagnostics.vector_rest` (metadata plus optional reversible probe), and `diagnostics.embedding`, all strictly validated. Keep reader-only workspace valid.
+- [ ] Re-run focused tests and `npx tsc --noEmit -p .`.
+- [ ] Commit `feat: define workspace diagnostic contracts`.
+
+### Task 2: Implement declared bounded diagnostics
+
+**Files:** modify `backend/src/workspaces/diagnostics.ts`; test `backend/test/workspaces-diagnostics.test.ts`.
+
+- [ ] Write failing faked-transport tests for `POST /rpc/ping`, vector metadata dimensions/metric/collection, reader-only non-write activation, writer probe cleanup after timeout, direct/SSH declared vector database/schema, strict SSH known-host arguments, and redacted malformed response/timeout errors.
+- [ ] Run `npx vitest run test/workspaces-diagnostics.test.ts` and observe failure.
+- [ ] Implement production adapters using descriptor-declared contracts only, `AbortController` timeouts, injected direct-protocol and SSH process factories, local secret files, and bounded `finally` cleanup after a successful writer probe.
+- [ ] Run focused diagnostics, `npx vitest run`, and `npx tsc --noEmit -p .`.
+- [ ] Commit `feat: run bounded workspace connector diagnostics`.
+
+### Task 3: Specify installation and server protocols
+
+**Files:** create `docs/workspace-diagnostic-protocol.md`; modify `docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md`; test `backend/test/workspaces-contracts.test.ts`.
+
+- [ ] Write a failing documentation-contract test that writer workspaces render the writer `_FILE` variables.
+- [ ] Run `npx vitest run test/workspaces-contracts.test.ts` and observe failure.
+- [ ] Document request/response requirements for DWH ping, vector metadata, reversible writer probe, embedding dimensions, SSH known-hosts, reader-only fallback, and every local variable name.
+- [ ] Run `npx vitest run && npx tsc --noEmit -p . && git diff --check`.
+- [ ] Commit `docs: specify workspace diagnostic protocols`.