From 25a85b972e42cd38cb0fb5ad9b19ea5a4d0fa314 Mon Sep 17 00:00:00 2001 From: mptyl Date: Mon, 3 Aug 2026 23:06:56 +0200 Subject: [PATCH] docs: plan diagnostic contract extension --- ...026-08-03-diagnostic-contract-extension.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md diff --git a/docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md b/docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md new file mode 100644 index 00000000..56c8b003 --- /dev/null +++ b/docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md @@ -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`.