@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/tests/qa-automation-plan.md

@@ -0,0 +1,101 @@
+# QA automation plan
+
+## Scope
+
+The QA plan covers:
+
+- core resource model and CRDs;
+- aggregated API and Postgres-backed resources;
+- Kubernetes controller and gateway behavior;
+- Gitea-backed repository data plane;
+- web UI and route flows;
+- CI/runners and pipeline/job lifecycle;
+- hooks and webhook delivery;
+- identity, RBAC, secrets, config, and policy;
+- deployments and KubeVela/OAM integration;
+- packaging, Helm chart, Docker image, install, smoke, and upgrade;
+- future agents, Agent Mux integration, company brain memory, `.a5c` run imports, triggers, tools, skills, subagents, and orchestration.
+
+## Test pyramid
+
+| Layer | Goal | Examples | Required speed |
+| --- | --- | --- | --- |
+| Static checks | catch broken contracts before execution | docs coverage, package validation, schema lint, import checks | seconds. |
+| Unit tests | verify pure functions and module contracts | resource schema, route helpers, auth helpers, redaction, ref resolution | seconds. |
+| Integration tests | verify module boundaries with fakes | API controller, Kubernetes gateway, UI model, memory import normalizer | seconds to minutes. |
+| Component/UI tests | verify rendered components and interactions | org switcher, repo tabs, dispatch composer, memory import panel | minutes. |
+| Browser E2E | verify critical user journeys | create repo, run CI, dispatch agent, import memory | minutes. |
+| Package/install tests | verify release artifact shape | Helm template, CRD coverage, minikube dry-run, Docker build | minutes. |
+| Live cluster tests | verify real integrations | Gitea, NATS, ARC, Argo CD, KubeVela, webhooks | longer/nightly. |
+| Chaos/reliability tests | verify failure behavior | watch reconnect, controller retry, Git outage, redaction failure | nightly/staging. |
+
+## Definition of done
+
+A feature is not done until:
+
+- resource/API/schema docs are updated;
+- unit or integration tests cover the core logic;
+- at least one acceptance or E2E path covers the user-visible behavior;
+- cross-org/RBAC/secret negative tests exist where relevant;
+- docs validation and package validation pass;
+- UI changes pass browser or component checks where relevant;
+- release-impacting changes update chart/package tests;
+- future agent/memory changes update the fixture plan and acceptance matrix.
+
+## Rollout phases
+
+### Phase 1: codify current gates
+
+- Keep `npm run check` as the local all-up gate.
+- Make `npm run validate:docs`, `npm test`, `npm run e2e`, `npm run package:check`, `npm run smoke`, `npm run ui:validate`, and `npm run ui:build` visible in CI docs.
+- Add test ownership labels by subsystem.
+
+### Phase 2: add browser automation
+
+- Add Playwright for route-level browser tests.
+- Cover org navigation, repository code/issues/runs/settings, deployments, and advanced plans.
+- Add accessibility checks for primary routes.
+
+### Phase 3: add API/controller contract tests
+
+- Add table-driven tests for org-scoped API routes, resource apply/list/delete, watch, and errors.
+- Add fake Kubernetes/Gitea/NATS/Agent Mux adapters.
+- Add no-secret response tests.
+
+### Phase 4: add agent/company-brain tests
+
+- Add fixtures for org memory, `.a5c` run imports, historical memory refs, and Agent Mux session binding.
+- Add cross-org denial and redaction tests.
+- Add browser E2E for dispatch with memory and import review.
+
+### Phase 5: staging and live integration
+
+- Add nightly cluster tests for Gitea, Argo CD, KubeVela, ARC, NATS, webhooks, and object storage.
+- Add upgrade/rollback tests.
+- Add reliability and failure injection scenarios.
+
+## Ownership model
+
+| Area | Owner role | Required evidence |
+| --- | --- | --- |
+| Resource/API contracts | platform/backend | schema tests, API tests, docs coverage. |
+| Controllers | platform/backend | reconciliation tests, idempotency tests, events/audit. |
+| UI/UX | frontend/product | browser/component tests, accessibility, route guards. |
+| CI/runners | platform/runtime | lifecycle E2E, isolation, ServiceAccount/RBAC tests. |
+| Security | security/platform | auth/RBAC/secret/no-leak tests. |
+| Packaging | release/platform | package/chart/install/smoke tests. |
+| Agents/memory | agents/platform | dispatch, context, memory, Agent Mux, import, trigger tests. |
+
+## Reporting
+
+Every CI run should publish:
+
+- command summary;
+- pass/fail by suite;
+- coverage by subsystem;
+- flaky test list;
+- failed test artifacts;
+- browser traces/screenshots for UI failures;
+- package/chart validation summary;
+- security/secret-scan findings;
+- links to run logs and relevant resources.

package/docs/tests/security-compliance-tests.md

@@ -0,0 +1,57 @@
+# Security and compliance tests
+
+## Authentication and authorization
+
+Required tests:
+
+- OIDC/delegated identity config parsing;
+- unauthenticated request rejection;
+- user/group mapping;
+- Kubernetes SubjectAccessReview invocation;
+- org namespace authorization;
+- route guard denies resource with wrong org label;
+- admin-only actions require admin/RBAC.
+
+## RBAC and policy
+
+Required tests:
+
+- runner ServiceAccount scoped to repo/ref/trust tier;
+- agent ServiceAccount cannot mount another org Secret/ConfigMap;
+- untrusted fork has no secrets and no cluster write access;
+- missing `AgentSecretGrant` or `AgentConfigGrant` blocks stack readiness;
+- policy/audit mode surfaces warnings without mutating resources;
+- cross-org refs require `OrgSharingPolicy`.
+
+## Secret and data leakage
+
+No secret-like values may appear in:
+
+- API responses;
+- UI rendered text;
+- context bundles;
+- prompt previews;
+- memory imports;
+- logs and watch events;
+- artifacts;
+- audit records;
+- browser traces.
+
+## Supply chain
+
+Release gates should eventually include:
+
+- dependency vulnerability scan;
+- license policy scan;
+- Docker image scan;
+- SBOM generation;
+- image/chart provenance or signatures;
+- GitHub Actions workflow lint.
+
+## Agent-specific security
+
+- Memory records are untrusted prompt content.
+- Tool calls are admitted by Krate, not Agent Mux alone.
+- Historical memory runs cannot read current memory without refresh/approval.
+- Agent write-back requires artifact digest and approval.
+- `.a5c` imports are redacted and validated before entering company brain.

package/docs/tests/test-framework-tools.md

@@ -0,0 +1,88 @@
+# Test framework and tools
+
+## Existing baseline
+
+Krate currently uses Node.js with ESM and the built-in `node:test` runner for unit and E2E tests. The package scripts are the source of truth for current gates.
+
+Existing tools:
+
+| Tool | Use |
+| --- | --- |
+| Node `node:test` | unit, integration, and current E2E tests. |
+| `assert/strict` | assertions. |
+| Next.js build | production UI build validation. |
+| custom scripts | docs, package, smoke, UI, minikube dry-run validation. |
+| Helm/minikube dry-run plans | install command validation without a live cluster. |
+
+## Recommended additions
+
+| Tool | Add when | Use |
+| --- | --- | --- |
+| Playwright | first browser suite | browser E2E, traces, screenshots, route assertions, accessibility hooks. |
+| Testing Library / React test utilities | component-level UI tests | component interaction tests without full browser cost. |
+| Istanbul/c8 or Node coverage | coverage reporting | line/branch/function coverage for `src` and critical scripts. |
+| `axe-core` or Playwright accessibility assertions | UI accessibility gate | WCAG smoke checks on primary pages. |
+| Helm unittest or template assertions | chart complexity grows | focused Helm render checks beyond current string tests. |
+| kubeconform/kubeval | CRD/chart validation | Kubernetes schema validation for rendered manifests. |
+| actionlint | workflow validation | GitHub Actions YAML checks. |
+| secret scanner | before memory imports and release | ensure fixtures/logs/artifacts do not leak secrets. |
+| dependency/license scanner | release gate | supply-chain checks. |
+| k6 or autocannon | performance stage | API/web smoke load tests. |
+
+## Tool selection principles
+
+- Prefer fast built-in Node tests for pure logic and contracts.
+- Use browser automation only for routes and interactions that cannot be validated below the browser layer.
+- Use deterministic fakes for Kubernetes, Gitea, Agent Mux, NATS, Argo CD, and object storage in PR gates.
+- Use live integration only in nightly/staging or explicit release gates.
+- Keep tests runnable on Windows and Linux.
+- Store fixtures in repo; avoid network calls in deterministic CI unless the suite is explicitly live.
+
+## Proposed npm scripts
+
+Future scripts should be additive and keep current scripts stable:
+
+```json
+{
+  "test:unit": "node --test tests/unit/**/*.test.js",
+  "test:integration": "node --test tests/integration/**/*.test.js",
+  "test:api": "node --test tests/api/**/*.test.js",
+  "test:e2e": "node --test tests/e2e/**/*.test.js",
+  "test:browser": "playwright test",
+  "test:coverage": "node --test --experimental-test-coverage tests/**/*.test.js",
+  "test:security": "node scripts/security-check.mjs",
+  "test:charts": "node scripts/validate-package.mjs",
+  "test:all": "npm run check && npm run test:browser"
+}
+```
+
+The exact script names can change during implementation, but the suite split should remain recognizable.
+
+## Test doubles
+
+Required fakes/mocks:
+
+| Adapter | Fake behavior |
+| --- | --- |
+| Kubernetes API | list/get/apply/delete/watch resources, SubjectAccessReview, events. |
+| Gitea/Git | repository create, refs, commits, clone URL, protected branches, webhook callbacks. |
+| Postgres | aggregated resources and migrations, preferably in-memory or isolated test DB. |
+| Object storage | artifact put/get by digest. |
+| NATS/webhook queue | enqueue, deliver, retry, replay. |
+| Agent Mux | create run/session, stream events, accept chat continuation, cancel/resume. |
+| Memory Git repo | resolve refs, read files, grep, write branch/PR, merge, diff. |
+| Argo CD/KubeVela | Application status, sync plan, rollout state. |
+
+## Artifacts
+
+Test failures should preserve:
+
+- assertion output;
+- API request/response body with secrets redacted;
+- generated YAML/resource plans;
+- browser trace and screenshot;
+- console/network logs for browser failures;
+- rendered Helm manifests;
+- memory import validation report;
+- `.a5c` fixture redaction report;
+- coverage report.

package/docs/tests/test-suite-layout.md

@@ -0,0 +1,121 @@
+# Test suite layout and naming
+
+## Purpose
+
+This document defines the future test directory layout, naming conventions, fixture locations, and ownership model. The current repository can keep existing tests while migrating incrementally toward this structure.
+
+## Proposed layout
+
+```text
+tests/
+  unit/
+    resource-model.test.js
+    route-helpers.test.js
+    redaction.test.js
+    memory-ref-resolution.test.js
+  integration/
+    api-controller.test.js
+    controller-ui-model.test.js
+    gitea-backend.test.js
+    memory-import-normalizer.test.js
+  api/
+    org-resources.test.js
+    agent-dispatch.test.js
+    memory-query.test.js
+    watch-filters.test.js
+  e2e/
+    lifecycle.test.js
+    org-isolation.test.js
+    repository-pr-ci.test.js
+    deployment-promotion.test.js
+    agent-memory-vertical.test.js
+  browser/
+    org-navigation.spec.ts
+    repository-flow.spec.ts
+    run-detail.spec.ts
+    agent-memory.spec.ts
+  fixtures/
+    orgs/
+    resources/
+    repositories/
+    webhooks/
+    deployments/
+    agents/
+    memory/
+      company-brain/
+      a5c-runs/
+      sessions/
+  helpers/
+    fake-kubernetes.js
+    fake-gitea.js
+    fake-agent-mux.js
+    fake-memory-repo.js
+    assertions.js
+```
+
+## Naming conventions
+
+| Type | Convention |
+| --- | --- |
+| Node tests | `*.test.js` using Node `node:test`. |
+| Playwright tests | `*.spec.ts` or `*.spec.js` under `tests/browser`. |
+| Fixtures | kebab-case directory and file names. |
+| Fake adapters | `fake-<adapter>.js`. |
+| Golden outputs | `<scenario>.expected.json` only when stable and reviewed. |
+| Redaction fixtures | include `redact-me` in synthetic secret values. |
+
+## Test metadata
+
+Each larger scenario test should declare:
+
+```js
+const meta = {
+  area: 'agents-memory',
+  owner: 'platform-agents',
+  gate: 'pr|merge|nightly|release',
+  requires: ['fake-kubernetes', 'fake-memory-repo'],
+  covers: ['ORG-ISOLATION', 'MEMORY-SNAPSHOT']
+};
+```
+
+Metadata can be comments or exported constants at first. Later it can feed reports.
+
+## Fixture policy
+
+- Tests may mutate copies of fixtures, never the fixture source.
+- Fixtures with secret-like values must be synthetic and documented.
+- Fixture IDs and timestamps should be stable.
+- Fixture resource names should include org where useful.
+- Large fixture artifacts should be minimized; prefer digest manifests.
+
+## Migration from current layout
+
+Current tests in `tests/*.test.js` and `tests/e2e/*.test.js` do not need to move immediately. Migration steps:
+
+1. keep existing scripts green;
+2. add new directories when first tests for that layer are created;
+3. move tests only when imports and CI scripts are updated in the same change;
+4. keep `npm test` backwards-compatible or make it run all unit/integration tests;
+5. update docs/tests and package scripts together.
+
+## Ownership labels
+
+Recommended owners:
+
+| Prefix | Area |
+| --- | --- |
+| `core-*` | resource model, API controller, storage. |
+| `ui-*` | web UI, browser, accessibility. |
+| `runtime-*` | runners, pipelines, jobs, Gitea, hooks. |
+| `deploy-*` | Argo CD, KubeVela, chart/install. |
+| `security-*` | auth, RBAC, secrets, policy, audit. |
+| `agents-*` | agent stacks, Agent Mux, memory, triggers, imports. |
+
+## Review checklist
+
+- Does the test run without network unless marked live?
+- Does it clean up temporary files/resources?
+- Does it assert org and namespace where relevant?
+- Does it assert stable error codes for failure paths?
+- Does it avoid real secrets and PII?
+- Does it avoid brittle visual or string-only assertions when semantic assertions are possible?

package/docs/tests/unit-integration-tests.md

@@ -0,0 +1,48 @@
+# Unit and integration tests
+
+## Unit test targets
+
+| Area | Examples |
+| --- | --- |
+| Resource model | kind definitions, required spec fields, schema generation, plural names. |
+| Org routing helpers | `orgHref`, route ambiguity, slug handling, breadcrumb construction. |
+| API validation | required fields, stable errors, org mismatch, no-secret responses. |
+| Context assembly | source manifests, digest calculation, redaction ordering, truncation. |
+| Memory utilities | ref resolution, graph/frontmatter parsing, grep result bounding, import normalization. |
+| Auth/RBAC helpers | delegated identity, SubjectAccessReview requests, permission summaries. |
+| Chart/package scripts | required files, CRD coverage, values coverage. |
+| Setup/smoke scripts | deterministic dry-run output and command plans. |
+
+## Integration test targets
+
+| Boundary | Required tests |
+| --- | --- |
+| API controller + fake Kubernetes | list/get/apply/delete resources, org filters, watch setup. |
+| UI model + fake controller | dashboard summaries, org pages, repository pages, run pages. |
+| Controller + fake Gitea | repository create, branch protection, permissions, webhook sync. |
+| Runner + fake Kubernetes | ServiceAccount selection, untrusted fork policy, job lifecycle. |
+| Hook queue + fake delivery | signing, retry, replay, failure status. |
+| Memory import + fake Git repo | read `.a5c`, redact, normalize, validate, open PR. |
+| Agent dispatch + fake Agent Mux | launch, session binding, events, cancel/resume. |
+
+## Required negative tests
+
+- missing `organizationRef`;
+- namespace does not match org binding;
+- cross-org repository, memory, secret, config, runner, or session ref;
+- denied SubjectAccessReview;
+- missing Secret/ConfigMap grant;
+- untrusted fork tries to access secrets;
+- memory import contains secret-like content;
+- webhook signature mismatch;
+- duplicate repository slug through legacy route;
+- stale memory ref cannot resolve.
+
+## Test style
+
+- Use table-driven cases for resource and API validation.
+- Keep fixtures small and explicit.
+- Prefer fake adapters over network calls.
+- Assert stable error codes, not only messages.
+- Assert status conditions and audit fields.
+- Assert no secret values appear in responses, logs, snapshots, or artifacts.