@a5c-ai/krate 5.0.1-staging.d8bdfcceaf4a → 5.0.1-staging.daf8e165bc4a
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +187 -183
- package/bin/krate-demo.mjs +1 -1
- package/bin/krate-server.mjs +1 -1
- package/dist/krate-controller-ui.json +163 -5
- package/dist/krate-lifecycle.json +1 -1
- package/dist/krate-runtime-snapshot.json +48 -48
- package/dist/krate-summary.json +3 -3
- package/docs/README.md +61 -61
- package/docs/agents/README.md +83 -83
- package/docs/agents/acceptance-test-matrix.md +193 -193
- package/docs/agents/agent-mux-source-map.md +310 -310
- package/docs/agents/agent-run-memory-import-spec.md +256 -256
- package/docs/agents/agent-stack-management-spec.md +1 -1
- package/docs/agents/api-contract-spec.md +309 -309
- package/docs/agents/artifacts-writeback-spec.md +144 -144
- package/docs/agents/ci-orchestration-spec.md +140 -140
- package/docs/agents/context-assembly-spec.md +219 -219
- package/docs/agents/controller-reconciliation-spec.md +255 -255
- package/docs/agents/crd-schema-spec.md +315 -315
- package/docs/agents/decision-log-open-questions.md +168 -168
- package/docs/agents/developer-implementation-checklist.md +329 -329
- package/docs/agents/dispatching-design.md +262 -262
- package/docs/agents/glossary.md +66 -66
- package/docs/agents/implementation-blueprint.md +324 -324
- package/docs/agents/implementation-rollout-slices.md +251 -251
- package/docs/agents/memory-context-integration-spec.md +194 -194
- package/docs/agents/memory-ontology-schema-spec.md +253 -253
- package/docs/agents/memory-operations-runbook.md +1 -1
- package/docs/agents/mvp-vertical-slice-spec.md +146 -146
- package/docs/agents/observability-audit-spec.md +265 -265
- package/docs/agents/operator-runbook.md +174 -174
- package/docs/agents/org-memory-api-payload-examples.md +333 -333
- package/docs/agents/org-memory-controller-sequence-spec.md +1 -1
- package/docs/agents/org-memory-e2e-fixture-plan.md +161 -161
- package/docs/agents/org-memory-ui-implementation-map.md +114 -114
- package/docs/agents/org-memory-vertical-slice-spec.md +168 -168
- package/docs/agents/org-resource-model-delta-spec.md +111 -111
- package/docs/agents/org-route-resource-model-spec.md +183 -183
- package/docs/agents/org-scoping-namespace-spec.md +114 -114
- package/docs/agents/rbac-secrets-management-spec.md +406 -406
- package/docs/agents/repository-page-integration-spec.md +255 -255
- package/docs/agents/resource-contract-examples.md +808 -808
- package/docs/agents/resource-relationship-map.md +190 -190
- package/docs/agents/security-threat-model.md +188 -188
- package/docs/agents/shared-memory-company-brain-spec.md +358 -358
- package/docs/agents/storage-migration-spec.md +168 -168
- package/docs/agents/system-overview.md +88 -88
- package/docs/agents/tools-mcp-skills-spec.md +189 -189
- package/docs/agents/traceability-matrix.md +79 -79
- package/docs/agents/ui-flow-spec.md +211 -211
- package/docs/agents/ui-ux-system-spec.md +426 -426
- package/docs/components/control-plane.md +1 -1
- package/docs/components/identity-rbac-policy.md +70 -70
- package/docs/components/kubevela-oam.md +1 -1
- package/docs/components/operations-publishing.md +81 -81
- package/docs/components/runners-ci.md +1 -1
- package/docs/components/web-ui.md +94 -94
- package/docs/external/README.md +47 -47
- package/docs/external/bidirectional-sync-design.md +1 -1
- package/docs/external/cicd-interface.md +1 -1
- package/docs/external/external-backend-controllers.md +170 -170
- package/docs/external/external-backend-crds.md +234 -234
- package/docs/external/external-backend-ui-spec.md +1 -1
- package/docs/external/external-backend-ux-flows.md +1 -1
- package/docs/external/external-object-mapping.md +1 -1
- package/docs/external/git-forge-interface.md +1 -1
- package/docs/external/github-integration-design.md +1 -1
- package/docs/external/issue-tracking-interface.md +1 -1
- package/docs/external/provider-capability-manifests.md +1 -1
- package/docs/external/provider-catalog.md +1 -1
- package/docs/external/provider-rollout-testing.md +1 -1
- package/docs/external/research-results.md +1 -1
- package/docs/external/security-auth-permissions.md +1 -1
- package/docs/external/sync-state-machines.md +1 -1
- package/docs/external/unified-external-backend-model.md +1 -1
- package/docs/external/user-facing-changes.md +1 -1
- package/docs/gaps.md +161 -161
- package/docs/install.md +84 -84
- package/docs/krate-design.md +334 -334
- package/docs/local-minikube.md +55 -55
- package/docs/ontology/oam-kubevela.md +1 -1
- package/docs/ontology/resource-contracts.md +40 -40
- package/docs/ontology/resource-taxonomy.md +42 -42
- package/docs/ontology/web-ui-excellent-flows.md +1 -1
- package/docs/openapi.yaml +18 -2
- package/docs/product-requirements.md +62 -62
- package/docs/system-requirements.md +90 -90
- package/docs/tests/README.md +53 -53
- package/docs/tests/agent-qa-plan.md +1 -1
- package/docs/tests/browser-ui-tests.md +1 -1
- package/docs/tests/ci-quality-gates.md +1 -1
- package/docs/tests/coverage-model.md +1 -1
- package/docs/tests/e2e-scenario-tests.md +1 -1
- package/docs/tests/fixtures-test-data.md +1 -1
- package/docs/tests/observability-reliability-tests.md +1 -1
- package/docs/tests/product-test-matrix.md +145 -145
- package/docs/tests/qa-adoption-roadmap.md +1 -1
- package/docs/tests/qa-automation-plan.md +1 -1
- package/docs/tests/security-compliance-tests.md +1 -1
- package/docs/tests/test-framework-tools.md +1 -1
- package/docs/tests/test-suite-layout.md +1 -1
- package/docs/tests/unit-integration-tests.md +1 -1
- package/docs/todos.md +3 -3
- package/docs/user-stories.md +1 -1
- package/examples/minikube-demo.yaml +190 -190
- package/examples/policy-kyverno-pr-title.yaml +18 -18
- package/package.json +6 -3
- package/scripts/setup-minikube.mjs +65 -65
- package/scripts/smoke.mjs +37 -37
- package/scripts/validate-doc-coverage.mjs +152 -152
- package/scripts/validate-package.mjs +95 -93
- package/src/agent-dispatch-controller.js +80 -9
- package/src/agent-identity-migration.js +115 -0
- package/src/agent-mux-client.js +102 -14
- package/src/agent-persona-controller.js +135 -0
- package/src/agent-prompt-composition.js +55 -0
- package/src/agent-stack-controller.js +47 -0
- package/src/agent-trigger-controller.js +6 -0
- package/src/api-controller.js +621 -566
- package/src/argocd-gitops.js +1 -1
- package/src/assistant-runtime.js +60 -6
- package/src/auth.js +310 -307
- package/src/control-plane.js +2 -2
- package/src/controller-client.js +1 -1
- package/src/controller-ui.js +541 -539
- package/src/data-plane.js +176 -176
- package/src/event-bus.js +371 -35
- package/src/external/provider-resource-factory.js +64 -4
- package/src/gitea-backend.js +95 -95
- package/src/handoff.js +98 -98
- package/src/health-probes.js +134 -0
- package/src/hooks-events.js +63 -63
- package/src/http-server.js +409 -379
- package/src/identity-policy.js +86 -86
- package/src/index.js +71 -62
- package/src/jitsi-agent-bridge.js +141 -0
- package/src/jitsi-meeting-controller.js +291 -0
- package/src/jitsi-sync-controller.js +198 -0
- package/src/kubernetes-controller.js +904 -894
- package/src/kubernetes-resource-gateway.js +48 -48
- package/src/operations.js +112 -112
- package/src/resource-model.js +282 -230
- package/src/runners-ci.js +48 -48
- package/src/runtime.js +196 -196
- package/src/virtual-model-controller.js +538 -0
- package/src/virtual-model-hook-bridge.js +200 -0
- package/src/web-ui.js +40 -40
- package/tests/agent-dispatch-controller.test.js +185 -0
- package/tests/agent-identity-migration.test.js +87 -0
- package/tests/agent-memory-controller.test.js +153 -0
- package/tests/agent-mux-client.test.js +59 -0
- package/tests/agent-persona-controller.test.js +127 -0
- package/tests/agent-prompt-composition.test.js +76 -0
- package/tests/agent-resources.test.js +83 -8
- package/tests/agent-stack-controller.test.js +62 -0
- package/tests/agent-trigger-controller.test.js +61 -1
- package/tests/assistant-runtime.test.js +6 -6
- package/tests/deployment.test.js +521 -403
- package/tests/e2e/lifecycle.test.js +119 -119
- package/tests/event-bus-integration.test.js +166 -1
- package/tests/external-persistence.test.js +77 -2
- package/tests/external-resource-model.test.js +23 -15
- package/tests/health-probes.test.js +90 -0
- package/tests/jitsi-agent-bridge.test.js +119 -0
- package/tests/jitsi-helm-integration.test.js +77 -0
- package/tests/jitsi-meeting-controller.test.js +170 -0
- package/tests/jitsi-resource-model.test.js +73 -0
- package/tests/jitsi-sync-controller.test.js +112 -0
- package/tests/krate.test.js +779 -779
- package/tests/model-route-controller.test.js +60 -0
- package/tests/virtual-model-controller.test.js +877 -0
- package/tests/virtual-model-hook-bridge.test.js +384 -0
package/README.md
CHANGED
|
@@ -1,183 +1,187 @@
|
|
|
1
|
-
# Krate
|
|
2
|
-
|
|
3
|
-
Krate is a Kubernetes-native Git forge runtime. Repositories, pull requests, CI, webhooks, policy, and UI flows execute through Kubernetes-style resources, Argo CD GitOps reconciliation, and a Gitea-backed Git hosting backend with explicit storage boundaries.
|
|
4
|
-
|
|
5
|
-
This repository is the executable MVP runtime and handoff package for the specs in `docs/`. It includes a stateful Node.js runtime, HTTP API server, production-shaped Kubernetes package surface, deterministic e2e/package validation, a minikube setup script, a production-built controller container, and safe GitHub publishing lanes for package, chart, image, and generated artifacts.
|
|
6
|
-
|
|
7
|
-
## What is implemented
|
|
8
|
-
|
|
9
|
-
- Kubernetes-style resource taxonomy for `Repository`, `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, `RunnerPool`, `WebhookSubscription`, `WebhookDelivery`, `RefPolicy`, `BranchProtection`, `View`, and `Selector`.
|
|
10
|
-
- Control-plane behavior for validation, storage routing, watches, RBAC checks, admission policy, and audit warnings.
|
|
11
|
-
- Data-plane behavior backed by Gitea for repository hosting, SSH deploy keys, collaborators/teams, protected branches, webhooks, object storage records, and search indexing queueing.
|
|
12
|
-
- Runner/CI behavior for trusted and forked jobs, projected service-account identity, isolation policy, checks completion, and rerun-from-step behavior.
|
|
13
|
-
- Webhook/event behavior for subscriptions, signed deliveries, inspection, replay, and PR lifecycle notifications.
|
|
14
|
-
- Runnable local runtime and HTTP API for repository creation, PR creation, checks, review approval, merge, resource listing, and snapshot export/import restore.
|
|
15
|
-
- UI and operations handoff models for excellent flows, YAML transparency, Argo CD Application manifests, Gitea-backed install manifests, observability, backup/restore, and release gates.
|
|
16
|
-
- Integrated component catalog and lifecycle snapshot for all implementation areas.
|
|
17
|
-
- Next.js console under `apps/web` backed by the executable Krate runtime model.
|
|
18
|
-
- Production-shaped controller container using `bin/krate-server.mjs`, `/healthz`, and the same runtime API covered by tests.
|
|
19
|
-
- GitHub Actions publishing for validated package artifacts, dist/chart/example bundles, GHCR controller images, tagged Helm chart OCI pushes, and AKS Helm deployments for develop/staging/main.
|
|
20
|
-
|
|
21
|
-
## Quick start
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
npm run check
|
|
25
|
-
npm run demo
|
|
26
|
-
npm run demo -- --json
|
|
27
|
-
npm run serve
|
|
28
|
-
npm run e2e
|
|
29
|
-
npm run package:check
|
|
30
|
-
npm run setup:minikube -- --dry-run
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
`npm run check` runs the full local gate: build, docs/ontology coverage, unit tests, e2e package validation, package checks, smoke assertions, UI validation, and the Next.js production build. `npm run serve` starts the local runtime API used by the lifecycle tests.
|
|
34
|
-
|
|
35
|
-
## Entrypoints
|
|
36
|
-
|
|
37
|
-
- Library API: `src/index.js`
|
|
38
|
-
- CLI demo: `bin/krate-demo.mjs` or package bin `krate-demo`
|
|
39
|
-
- Runtime server: `bin/krate-server.mjs` or package bin `krate-server` (`npm run serve`)
|
|
40
|
-
- Public preview: `public/index.html`
|
|
41
|
-
- Next.js UI: `apps/web` (`npm run dev`, `npm run ui:build`)
|
|
42
|
-
- Product home: `https://a5c.ai/krate`
|
|
43
|
-
- Helm-style package: `charts/krate`
|
|
44
|
-
- Controller image: `Dockerfile` builds `ghcr.io/${{ github.repository }}/krate-controller`
|
|
45
|
-
- Publishing workflow: `.github/workflows/publish.yml` (develop -> `krate-develop.a5c.ai`, staging -> `krate-staging.a5c.ai`, main -> `krate.a5c.ai`)
|
|
46
|
-
- Minikube setup: `scripts/setup-minikube.mjs`
|
|
47
|
-
- Demo resources: `examples/minikube-demo.yaml`
|
|
48
|
-
- Generated handoff summary: `dist/krate-summary.json`
|
|
49
|
-
- Generated lifecycle snapshot: `dist/krate-lifecycle.json`
|
|
50
|
-
- Documentation index: `docs/README.md`
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
## Sign-in and user management
|
|
54
|
-
|
|
55
|
-
Krate installs with GitHub login enabled by default and optional SSO disabled until an operator supplies provider settings. SSO is installation configuration only: admins manage users, teams, invites, repository access, and identity mappings in Krate after the provider is configured through Helm values.
|
|
56
|
-
|
|
57
|
-
### Create a GitHub OAuth client
|
|
58
|
-
|
|
59
|
-
1. In GitHub, open **Settings -> Developer settings -> OAuth Apps -> New OAuth App**.
|
|
60
|
-
2. Set the homepage URL to the public Krate URL, for example `https://krate.example.com`.
|
|
61
|
-
3. Set the callback URL to `https://krate.example.com/api/auth/callback/github`.
|
|
62
|
-
4. Copy the generated client ID and client secret into a private values file or an existing Kubernetes Secret.
|
|
63
|
-
|
|
64
|
-
```yaml
|
|
65
|
-
auth:
|
|
66
|
-
github:
|
|
67
|
-
enabled: true
|
|
68
|
-
clientId: "<github-client-id>"
|
|
69
|
-
clientSecret: "<github-client-secret>"
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
Install or upgrade with:
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
helm upgrade --install krate charts/krate -n krate-system --create-namespace -f auth-values.yaml
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
To disable GitHub login:
|
|
79
|
-
|
|
80
|
-
```yaml
|
|
81
|
-
auth:
|
|
82
|
-
github:
|
|
83
|
-
enabled: false
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
### Configure SSO
|
|
87
|
-
|
|
88
|
-
Create an OAuth/OIDC client in your identity provider with callback URL `https://krate.example.com/api/auth/callback/sso`, then pass the provider endpoints through Helm values. This configuration is intentionally not exposed in the UI.
|
|
89
|
-
|
|
90
|
-
```yaml
|
|
91
|
-
auth:
|
|
92
|
-
sso:
|
|
93
|
-
enabled: true
|
|
94
|
-
providerName: "Company SSO"
|
|
95
|
-
issuerUrl: "https://idp.example.com"
|
|
96
|
-
authorizationUrl: "https://idp.example.com/oauth2/v1/authorize"
|
|
97
|
-
tokenUrl: "https://idp.example.com/oauth2/v1/token"
|
|
98
|
-
userInfoUrl: "https://idp.example.com/oauth2/v1/userinfo"
|
|
99
|
-
clientId: "<sso-client-id>"
|
|
100
|
-
clientSecret: "<sso-client-secret>"
|
|
101
|
-
scopes: "openid profile email groups"
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
For existing secrets, create keys named `github-client-id`, `github-client-secret`, `sso-client-id`, and `sso-client-secret`, then reference them:
|
|
105
|
-
|
|
106
|
-
When every enabled provider uses `existingSecret`, the chart does not render an additional Krate-managed auth Secret. If only one provider uses an existing Secret, the chart renders only the inline-managed provider keys.
|
|
107
|
-
|
|
108
|
-
```yaml
|
|
109
|
-
auth:
|
|
110
|
-
github:
|
|
111
|
-
existingSecret: krate-auth-secrets
|
|
112
|
-
sso:
|
|
113
|
-
existingSecret: krate-auth-secrets
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
When a cluster ingress or identity proxy delegates authentication, set the forwarded identity headers at install time:
|
|
117
|
-
|
|
118
|
-
```yaml
|
|
119
|
-
auth:
|
|
120
|
-
delegatedIdentity:
|
|
121
|
-
enabled: true
|
|
122
|
-
userHeader: x-forwarded-user
|
|
123
|
-
groupsHeader: x-forwarded-groups
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
For local Next.js development, `http://localhost:3000/api/auth/delegated` can sign in without a proxy header when delegated identity is enabled. It defaults to `local-developer` in `krate:repo-admins`, and can be overridden with `?user=alice&email=alice@example.test&groups=krate:developers` or disabled with `KRATE_AUTH_DELEGATED_LOCAL_DEVELOPMENT=false`.
|
|
127
|
-
|
|
128
|
-
All web UI pages and authenticated API routes require the `krate_session` login cookie. `/login` and `/api/auth/*` stay public so users can start OAuth, delegated sign-in, or logout flows.
|
|
129
|
-
|
|
130
|
-
Krate stores `User`, `Team`, `Invite`, `IdentityMapping`, `RepositoryPermission`, and `SSHKey` resources. OAuth callbacks and delegated identity headers auto-register the Krate user plus identity mapping, and controllers reconcile those resources into workspace access, repository account mappings, team membership, SSH keys, and repository permissions while the UI exposes only Krate people and access flows.
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
- `
|
|
141
|
-
- `
|
|
142
|
-
- `
|
|
143
|
-
- `POST /api/
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
- `
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
- `npm run
|
|
152
|
-
- `npm run
|
|
153
|
-
- `npm
|
|
154
|
-
- `npm run
|
|
155
|
-
- `npm run
|
|
156
|
-
- `npm run
|
|
157
|
-
- `npm run
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
- `docs/
|
|
168
|
-
- `docs/
|
|
169
|
-
- `docs/
|
|
170
|
-
- `
|
|
171
|
-
- `docs/
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
##
|
|
178
|
-
|
|
179
|
-
The
|
|
180
|
-
|
|
181
|
-
##
|
|
182
|
-
|
|
183
|
-
|
|
1
|
+
# Krate
|
|
2
|
+
|
|
3
|
+
Krate is a Kubernetes-native Git forge runtime. Repositories, pull requests, CI, webhooks, policy, and UI flows execute through Kubernetes-style resources, Argo CD GitOps reconciliation, and a Gitea-backed Git hosting backend with explicit storage boundaries.
|
|
4
|
+
|
|
5
|
+
This repository is the executable MVP runtime and handoff package for the specs in `docs/`. It includes a stateful Node.js runtime, HTTP API server, production-shaped Kubernetes package surface, deterministic e2e/package validation, a minikube setup script, a production-built controller container, and safe GitHub publishing lanes for package, chart, image, and generated artifacts.
|
|
6
|
+
|
|
7
|
+
## What is implemented
|
|
8
|
+
|
|
9
|
+
- Kubernetes-style resource taxonomy for `Repository`, `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, `RunnerPool`, `WebhookSubscription`, `WebhookDelivery`, `RefPolicy`, `BranchProtection`, `View`, and `Selector`.
|
|
10
|
+
- Control-plane behavior for validation, storage routing, watches, RBAC checks, admission policy, and audit warnings.
|
|
11
|
+
- Data-plane behavior backed by Gitea for repository hosting, SSH deploy keys, collaborators/teams, protected branches, webhooks, object storage records, and search indexing queueing.
|
|
12
|
+
- Runner/CI behavior for trusted and forked jobs, projected service-account identity, isolation policy, checks completion, and rerun-from-step behavior.
|
|
13
|
+
- Webhook/event behavior for subscriptions, signed deliveries, inspection, replay, and PR lifecycle notifications.
|
|
14
|
+
- Runnable local runtime and HTTP API for repository creation, PR creation, checks, review approval, merge, resource listing, and snapshot export/import restore.
|
|
15
|
+
- UI and operations handoff models for excellent flows, YAML transparency, Argo CD Application manifests, Gitea-backed install manifests, observability, backup/restore, and release gates.
|
|
16
|
+
- Integrated component catalog and lifecycle snapshot for all implementation areas.
|
|
17
|
+
- Next.js console under `apps/web` backed by the executable Krate runtime model.
|
|
18
|
+
- Production-shaped controller container using `bin/krate-server.mjs`, `/healthz`, and the same runtime API covered by tests.
|
|
19
|
+
- GitHub Actions publishing for validated package artifacts, dist/chart/example bundles, GHCR controller images, tagged Helm chart OCI pushes, and AKS Helm deployments for develop/staging/main.
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm run check
|
|
25
|
+
npm run demo
|
|
26
|
+
npm run demo -- --json
|
|
27
|
+
npm run serve
|
|
28
|
+
npm run e2e
|
|
29
|
+
npm run package:check
|
|
30
|
+
npm run setup:minikube -- --dry-run
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`npm run check` runs the full local gate: build, docs/ontology coverage, unit tests, e2e package validation, package checks, smoke assertions, UI validation, and the Next.js production build. `npm run serve` starts the local runtime API used by the lifecycle tests.
|
|
34
|
+
|
|
35
|
+
## Entrypoints
|
|
36
|
+
|
|
37
|
+
- Library API: `src/index.js`
|
|
38
|
+
- CLI demo: `bin/krate-demo.mjs` or package bin `krate-demo`
|
|
39
|
+
- Runtime server: `bin/krate-server.mjs` or package bin `krate-server` (`npm run serve`)
|
|
40
|
+
- Public preview: `public/index.html`
|
|
41
|
+
- Next.js UI: `apps/web` (`npm run dev`, `npm run ui:build`)
|
|
42
|
+
- Product home: `https://a5c.ai/krate`
|
|
43
|
+
- Helm-style package: `charts/krate`
|
|
44
|
+
- Controller image: `Dockerfile` builds `ghcr.io/${{ github.repository }}/krate-controller`
|
|
45
|
+
- Publishing workflow: `.github/workflows/publish.yml` (develop -> `krate-develop.a5c.ai`, staging -> `krate-staging.a5c.ai`, main -> `krate.a5c.ai`)
|
|
46
|
+
- Minikube setup: `scripts/setup-minikube.mjs`
|
|
47
|
+
- Demo resources: `examples/minikube-demo.yaml`
|
|
48
|
+
- Generated handoff summary: `dist/krate-summary.json`
|
|
49
|
+
- Generated lifecycle snapshot: `dist/krate-lifecycle.json`
|
|
50
|
+
- Documentation index: `docs/README.md`
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
## Sign-in and user management
|
|
54
|
+
|
|
55
|
+
Krate installs with GitHub login enabled by default and optional SSO disabled until an operator supplies provider settings. SSO is installation configuration only: admins manage users, teams, invites, repository access, and identity mappings in Krate after the provider is configured through Helm values.
|
|
56
|
+
|
|
57
|
+
### Create a GitHub OAuth client
|
|
58
|
+
|
|
59
|
+
1. In GitHub, open **Settings -> Developer settings -> OAuth Apps -> New OAuth App**.
|
|
60
|
+
2. Set the homepage URL to the public Krate URL, for example `https://krate.example.com`.
|
|
61
|
+
3. Set the callback URL to `https://krate.example.com/api/auth/callback/github`.
|
|
62
|
+
4. Copy the generated client ID and client secret into a private values file or an existing Kubernetes Secret.
|
|
63
|
+
|
|
64
|
+
```yaml
|
|
65
|
+
auth:
|
|
66
|
+
github:
|
|
67
|
+
enabled: true
|
|
68
|
+
clientId: "<github-client-id>"
|
|
69
|
+
clientSecret: "<github-client-secret>"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Install or upgrade with:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
helm upgrade --install krate charts/krate -n krate-system --create-namespace -f auth-values.yaml
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
To disable GitHub login:
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
auth:
|
|
82
|
+
github:
|
|
83
|
+
enabled: false
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Configure SSO
|
|
87
|
+
|
|
88
|
+
Create an OAuth/OIDC client in your identity provider with callback URL `https://krate.example.com/api/auth/callback/sso`, then pass the provider endpoints through Helm values. This configuration is intentionally not exposed in the UI.
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
auth:
|
|
92
|
+
sso:
|
|
93
|
+
enabled: true
|
|
94
|
+
providerName: "Company SSO"
|
|
95
|
+
issuerUrl: "https://idp.example.com"
|
|
96
|
+
authorizationUrl: "https://idp.example.com/oauth2/v1/authorize"
|
|
97
|
+
tokenUrl: "https://idp.example.com/oauth2/v1/token"
|
|
98
|
+
userInfoUrl: "https://idp.example.com/oauth2/v1/userinfo"
|
|
99
|
+
clientId: "<sso-client-id>"
|
|
100
|
+
clientSecret: "<sso-client-secret>"
|
|
101
|
+
scopes: "openid profile email groups"
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
For existing secrets, create keys named `github-client-id`, `github-client-secret`, `sso-client-id`, and `sso-client-secret`, then reference them:
|
|
105
|
+
|
|
106
|
+
When every enabled provider uses `existingSecret`, the chart does not render an additional Krate-managed auth Secret. If only one provider uses an existing Secret, the chart renders only the inline-managed provider keys.
|
|
107
|
+
|
|
108
|
+
```yaml
|
|
109
|
+
auth:
|
|
110
|
+
github:
|
|
111
|
+
existingSecret: krate-auth-secrets
|
|
112
|
+
sso:
|
|
113
|
+
existingSecret: krate-auth-secrets
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
When a cluster ingress or identity proxy delegates authentication, set the forwarded identity headers at install time:
|
|
117
|
+
|
|
118
|
+
```yaml
|
|
119
|
+
auth:
|
|
120
|
+
delegatedIdentity:
|
|
121
|
+
enabled: true
|
|
122
|
+
userHeader: x-forwarded-user
|
|
123
|
+
groupsHeader: x-forwarded-groups
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For local Next.js development, `http://localhost:3000/api/auth/delegated` can sign in without a proxy header when delegated identity is enabled. It defaults to `local-developer` in `krate:repo-admins`, and can be overridden with `?user=alice&email=alice@example.test&groups=krate:developers` or disabled with `KRATE_AUTH_DELEGATED_LOCAL_DEVELOPMENT=false`.
|
|
127
|
+
|
|
128
|
+
All web UI pages and authenticated API routes require the `krate_session` login cookie. `/login` and `/api/auth/*` stay public so users can start OAuth, delegated sign-in, or logout flows.
|
|
129
|
+
|
|
130
|
+
Krate stores `User`, `Team`, `Invite`, `IdentityMapping`, `RepositoryPermission`, and `SSHKey` resources. OAuth callbacks and delegated identity headers auto-register the Krate user plus identity mapping, and controllers reconcile those resources into workspace access, repository account mappings, team membership, SSH keys, and repository permissions while the UI exposes only Krate people and access flows.
|
|
131
|
+
|
|
132
|
+
### Staging service bindings
|
|
133
|
+
|
|
134
|
+
The Helm chart can wire assistant, Gitea, Agent Mux, and NATS event transport configuration into the deployed workloads without committing secret values. Use `assistant.*.existingSecret` for `ANTHROPIC_API_KEY` or `KRATE_ASSISTANT_API_KEY`, `gitea.token.existingSecret` for `KRATE_GITEA_TOKEN`, `agentMux.url` or `agentMux.gatewayUrl` for the Agent Mux service endpoints, and `externalDependencies.nats.eventTransport.enabled` plus either `externalDependencies.nats.url` or `externalDependencies.nats.existingSecret` for broker-backed event fanout/replay. Secret-backed NATS URLs default to key `url` and can be overridden with `externalDependencies.nats.key`. `externalDependencies.nats.eventTransport.subject` and `stream` select the NATS subject and JetStream stream. Empty values remain omitted so local/default renders keep their degraded-service behavior until real backing services are configured.
|
|
135
|
+
|
|
136
|
+
## Runtime API
|
|
137
|
+
|
|
138
|
+
Start the local server with `npm run serve`, then use:
|
|
139
|
+
|
|
140
|
+
- `GET /healthz` — health check.
|
|
141
|
+
- `GET /api/snapshot` — complete runtime resource/event/audit snapshot.
|
|
142
|
+
- `GET /api/resources/:kind` — Kubernetes-style list for a resource kind.
|
|
143
|
+
- `POST /api/repositories` — create a repository resource backed by the Gitea Git hosting integration plan.
|
|
144
|
+
- `POST /api/pullrequests` — create a PR, enqueue CI jobs, and deliver a webhook.
|
|
145
|
+
- `POST /api/pullrequests/:name/checks/complete` — complete the PR pipeline.
|
|
146
|
+
- `POST /api/pullrequests/:name/reviews` — add an approval or change-request review.
|
|
147
|
+
- `POST /api/pullrequests/:name/merge` — enforce checks/reviews, execute the Gitea-backed receive-pack path, and emit merge webhook delivery.
|
|
148
|
+
|
|
149
|
+
## Development commands
|
|
150
|
+
|
|
151
|
+
- `npm run build` — generate `dist/krate-summary.json` and `dist/krate-lifecycle.json` from the executable model.
|
|
152
|
+
- `npm run validate:docs` — verify required docs, ontology files, and source terms.
|
|
153
|
+
- `npm test` — run Node test coverage for the model, runtime, API, and handoff surfaces.
|
|
154
|
+
- `npm run smoke` — execute MVP smoke assertions and print flow/storage status.
|
|
155
|
+
- `npm run demo` — print the human-readable handoff summary.
|
|
156
|
+
- `npm run serve` — start the local Krate HTTP API.
|
|
157
|
+
- `npm run ui:dev` / `npm run dev` — start the Next.js implementation console.
|
|
158
|
+
- `npm run ui:validate` — verify the UI files and model-data contract.
|
|
159
|
+
- `npm run ui:build` — build the Next.js console for production using the webpack builder for deterministic standalone tracing of the Node-backed Kubernetes controller routes.
|
|
160
|
+
- `npm run dev:check` — quick developer loop for UI contract and unit tests.
|
|
161
|
+
- `npm run check` — run the complete quality gate.
|
|
162
|
+
|
|
163
|
+
## Documentation map
|
|
164
|
+
|
|
165
|
+
Start with `docs/README.md`, then read:
|
|
166
|
+
|
|
167
|
+
- `docs/product-requirements.md`
|
|
168
|
+
- `docs/system-requirements.md`
|
|
169
|
+
- `docs/architecture-spec.md`
|
|
170
|
+
- `docs/user-stories.md`
|
|
171
|
+
- `docs/roadmap-mvp.md`
|
|
172
|
+
- `docs/install.md`
|
|
173
|
+
- `docs/local-minikube.md`
|
|
174
|
+
- `charts/krate/README.md`
|
|
175
|
+
- `docs/ontology/README.md`
|
|
176
|
+
|
|
177
|
+
## Release boundary
|
|
178
|
+
|
|
179
|
+
The current package is ready as a verified Kubernetes-native runtime contract, chart package, local minikube handoff, controller image build, and implementation artifact. The chart validates the Kubernetes install contract locally through e2e/package gates, the Dockerfile packages the runnable controller API and Next.js web app, and the publishing workflow safely pushes images/charts from non-PR contexts while deploying branch commits to the existing AKS cluster at `krate-develop.a5c.ai`, `krate-staging.a5c.ai`, and `krate.a5c.ai`.
|
|
180
|
+
|
|
181
|
+
## QA automation
|
|
182
|
+
|
|
183
|
+
The product-wide QA strategy lives in `docs/tests/README.md`. Current executable gates are `npm run check`, `npm test`, `npm run e2e`, `npm run validate:docs`, `npm run package:check`, `npm run smoke`, `npm run ui:validate`, and `npm run ui:build`. Future planned gates cover browser automation, coverage, security, live integrations, and agent/company-brain workflows.
|
|
184
|
+
|
|
185
|
+
## External backend integrations
|
|
186
|
+
|
|
187
|
+
Design docs for GitHub and future externally managed backends live in `docs/external/README.md`. The model splits providers into three optional interfaces: issue tracking, CI/CD, and git forge, with GitHub expected to support all three through GitHub Apps, APIs, webhooks, and bidirectional sync.
|
package/bin/krate-demo.mjs
CHANGED
package/bin/krate-server.mjs
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"platformNamespace": "krate-org-default"
|
|
20
20
|
}
|
|
21
21
|
],
|
|
22
|
-
"generatedAt": "2026-
|
|
22
|
+
"generatedAt": "2026-06-02T07:00:21.510Z",
|
|
23
23
|
"correlationId": null,
|
|
24
24
|
"controller": {
|
|
25
25
|
"mode": "krate-workspace",
|
|
@@ -583,7 +583,7 @@
|
|
|
583
583
|
"maintainers"
|
|
584
584
|
],
|
|
585
585
|
"invitedBy": "admin",
|
|
586
|
-
"expiresAt": "2026-06-
|
|
586
|
+
"expiresAt": "2026-06-09T07:00:21.507Z"
|
|
587
587
|
},
|
|
588
588
|
"status": {
|
|
589
589
|
"phase": "Pending",
|
|
@@ -595,7 +595,7 @@
|
|
|
595
595
|
"Pending": 1
|
|
596
596
|
},
|
|
597
597
|
"storage": "etcd",
|
|
598
|
-
"yaml": "apiVersion: krate.a5c.ai/v1alpha1\nkind: Invite\nmetadata:\n namespace: krate-org-default\n labels:\n role: member\n annotations:\n name: new-user-example-com\n resourceVersion: 1\nspec:\n organizationRef: default\n email: new-user@example.com\n role: member\n teams:\n - maintainers\n invitedBy: admin\n expiresAt: 2026-06-
|
|
598
|
+
"yaml": "apiVersion: krate.a5c.ai/v1alpha1\nkind: Invite\nmetadata:\n namespace: krate-org-default\n labels:\n role: member\n annotations:\n name: new-user-example-com\n resourceVersion: 1\nspec:\n organizationRef: default\n email: new-user@example.com\n role: member\n teams:\n - maintainers\n invitedBy: admin\n expiresAt: 2026-06-09T07:00:21.507Z\nstatus:\n phase: Pending\n storage: etcd\n",
|
|
599
599
|
"action": {
|
|
600
600
|
"list": "Open Invite records in krate-org-default",
|
|
601
601
|
"watch": "Watch Invite updates in krate-org-default",
|
|
@@ -1622,6 +1622,91 @@
|
|
|
1622
1622
|
"delete": "Delete Selector in krate-org-default"
|
|
1623
1623
|
}
|
|
1624
1624
|
},
|
|
1625
|
+
{
|
|
1626
|
+
"kind": "AgentPersona",
|
|
1627
|
+
"plural": "agentpersonas",
|
|
1628
|
+
"apiResource": "agentpersonas.krate.a5c.ai",
|
|
1629
|
+
"count": 0,
|
|
1630
|
+
"names": [],
|
|
1631
|
+
"items": [],
|
|
1632
|
+
"phases": {},
|
|
1633
|
+
"storage": "etcd",
|
|
1634
|
+
"yaml": null,
|
|
1635
|
+
"action": {
|
|
1636
|
+
"list": "Open AgentPersona records in krate-org-default",
|
|
1637
|
+
"watch": "Watch AgentPersona updates in krate-org-default",
|
|
1638
|
+
"apply": "Save resource changes",
|
|
1639
|
+
"delete": "Delete AgentPersona in krate-org-default"
|
|
1640
|
+
}
|
|
1641
|
+
},
|
|
1642
|
+
{
|
|
1643
|
+
"kind": "AgentSoul",
|
|
1644
|
+
"plural": "agentsouls",
|
|
1645
|
+
"apiResource": "agentsouls.krate.a5c.ai",
|
|
1646
|
+
"count": 0,
|
|
1647
|
+
"names": [],
|
|
1648
|
+
"items": [],
|
|
1649
|
+
"phases": {},
|
|
1650
|
+
"storage": "etcd",
|
|
1651
|
+
"yaml": null,
|
|
1652
|
+
"action": {
|
|
1653
|
+
"list": "Open AgentSoul records in krate-org-default",
|
|
1654
|
+
"watch": "Watch AgentSoul updates in krate-org-default",
|
|
1655
|
+
"apply": "Save resource changes",
|
|
1656
|
+
"delete": "Delete AgentSoul in krate-org-default"
|
|
1657
|
+
}
|
|
1658
|
+
},
|
|
1659
|
+
{
|
|
1660
|
+
"kind": "AgentAppearance",
|
|
1661
|
+
"plural": "agentappearances",
|
|
1662
|
+
"apiResource": "agentappearances.krate.a5c.ai",
|
|
1663
|
+
"count": 0,
|
|
1664
|
+
"names": [],
|
|
1665
|
+
"items": [],
|
|
1666
|
+
"phases": {},
|
|
1667
|
+
"storage": "etcd",
|
|
1668
|
+
"yaml": null,
|
|
1669
|
+
"action": {
|
|
1670
|
+
"list": "Open AgentAppearance records in krate-org-default",
|
|
1671
|
+
"watch": "Watch AgentAppearance updates in krate-org-default",
|
|
1672
|
+
"apply": "Save resource changes",
|
|
1673
|
+
"delete": "Delete AgentAppearance in krate-org-default"
|
|
1674
|
+
}
|
|
1675
|
+
},
|
|
1676
|
+
{
|
|
1677
|
+
"kind": "AgentVoiceProfile",
|
|
1678
|
+
"plural": "agentvoiceprofiles",
|
|
1679
|
+
"apiResource": "agentvoiceprofiles.krate.a5c.ai",
|
|
1680
|
+
"count": 0,
|
|
1681
|
+
"names": [],
|
|
1682
|
+
"items": [],
|
|
1683
|
+
"phases": {},
|
|
1684
|
+
"storage": "etcd",
|
|
1685
|
+
"yaml": null,
|
|
1686
|
+
"action": {
|
|
1687
|
+
"list": "Open AgentVoiceProfile records in krate-org-default",
|
|
1688
|
+
"watch": "Watch AgentVoiceProfile updates in krate-org-default",
|
|
1689
|
+
"apply": "Save resource changes",
|
|
1690
|
+
"delete": "Delete AgentVoiceProfile in krate-org-default"
|
|
1691
|
+
}
|
|
1692
|
+
},
|
|
1693
|
+
{
|
|
1694
|
+
"kind": "AgentDefinition",
|
|
1695
|
+
"plural": "agentdefinitions",
|
|
1696
|
+
"apiResource": "agentdefinitions.krate.a5c.ai",
|
|
1697
|
+
"count": 0,
|
|
1698
|
+
"names": [],
|
|
1699
|
+
"items": [],
|
|
1700
|
+
"phases": {},
|
|
1701
|
+
"storage": "etcd",
|
|
1702
|
+
"yaml": null,
|
|
1703
|
+
"action": {
|
|
1704
|
+
"list": "Open AgentDefinition records in krate-org-default",
|
|
1705
|
+
"watch": "Watch AgentDefinition updates in krate-org-default",
|
|
1706
|
+
"apply": "Save resource changes",
|
|
1707
|
+
"delete": "Delete AgentDefinition in krate-org-default"
|
|
1708
|
+
}
|
|
1709
|
+
},
|
|
1625
1710
|
{
|
|
1626
1711
|
"kind": "AgentStack",
|
|
1627
1712
|
"plural": "agentstacks",
|
|
@@ -2319,6 +2404,74 @@
|
|
|
2319
2404
|
"delete": "Delete KrateServingRuntime in krate-org-default"
|
|
2320
2405
|
}
|
|
2321
2406
|
},
|
|
2407
|
+
{
|
|
2408
|
+
"kind": "JitsiMeetProvider",
|
|
2409
|
+
"plural": "jitsimeetproviders",
|
|
2410
|
+
"apiResource": "jitsimeetproviders.krate.a5c.ai",
|
|
2411
|
+
"count": 0,
|
|
2412
|
+
"names": [],
|
|
2413
|
+
"items": [],
|
|
2414
|
+
"phases": {},
|
|
2415
|
+
"storage": "etcd",
|
|
2416
|
+
"yaml": null,
|
|
2417
|
+
"action": {
|
|
2418
|
+
"list": "Open JitsiMeetProvider records in krate-org-default",
|
|
2419
|
+
"watch": "Watch JitsiMeetProvider updates in krate-org-default",
|
|
2420
|
+
"apply": "Save resource changes",
|
|
2421
|
+
"delete": "Delete JitsiMeetProvider in krate-org-default"
|
|
2422
|
+
}
|
|
2423
|
+
},
|
|
2424
|
+
{
|
|
2425
|
+
"kind": "JitsiMeetingTemplate",
|
|
2426
|
+
"plural": "jitsimeetingtemplates",
|
|
2427
|
+
"apiResource": "jitsimeetingtemplates.krate.a5c.ai",
|
|
2428
|
+
"count": 0,
|
|
2429
|
+
"names": [],
|
|
2430
|
+
"items": [],
|
|
2431
|
+
"phases": {},
|
|
2432
|
+
"storage": "etcd",
|
|
2433
|
+
"yaml": null,
|
|
2434
|
+
"action": {
|
|
2435
|
+
"list": "Open JitsiMeetingTemplate records in krate-org-default",
|
|
2436
|
+
"watch": "Watch JitsiMeetingTemplate updates in krate-org-default",
|
|
2437
|
+
"apply": "Save resource changes",
|
|
2438
|
+
"delete": "Delete JitsiMeetingTemplate in krate-org-default"
|
|
2439
|
+
}
|
|
2440
|
+
},
|
|
2441
|
+
{
|
|
2442
|
+
"kind": "JitsiMeeting",
|
|
2443
|
+
"plural": "jitsimeetings",
|
|
2444
|
+
"apiResource": "jitsimeetings.krate.a5c.ai",
|
|
2445
|
+
"count": 0,
|
|
2446
|
+
"names": [],
|
|
2447
|
+
"items": [],
|
|
2448
|
+
"phases": {},
|
|
2449
|
+
"storage": "postgres",
|
|
2450
|
+
"yaml": null,
|
|
2451
|
+
"action": {
|
|
2452
|
+
"list": "Open JitsiMeeting records in krate-org-default",
|
|
2453
|
+
"watch": "Watch JitsiMeeting updates in krate-org-default",
|
|
2454
|
+
"apply": "Save resource changes",
|
|
2455
|
+
"delete": "Delete JitsiMeeting in krate-org-default"
|
|
2456
|
+
}
|
|
2457
|
+
},
|
|
2458
|
+
{
|
|
2459
|
+
"kind": "JitsiRecording",
|
|
2460
|
+
"plural": "jitsirecordings",
|
|
2461
|
+
"apiResource": "jitsirecordings.krate.a5c.ai",
|
|
2462
|
+
"count": 0,
|
|
2463
|
+
"names": [],
|
|
2464
|
+
"items": [],
|
|
2465
|
+
"phases": {},
|
|
2466
|
+
"storage": "postgres",
|
|
2467
|
+
"yaml": null,
|
|
2468
|
+
"action": {
|
|
2469
|
+
"list": "Open JitsiRecording records in krate-org-default",
|
|
2470
|
+
"watch": "Watch JitsiRecording updates in krate-org-default",
|
|
2471
|
+
"apply": "Save resource changes",
|
|
2472
|
+
"delete": "Delete JitsiRecording in krate-org-default"
|
|
2473
|
+
}
|
|
2474
|
+
},
|
|
2322
2475
|
{
|
|
2323
2476
|
"kind": "Secret",
|
|
2324
2477
|
"plural": "secrets",
|
|
@@ -2516,6 +2669,11 @@
|
|
|
2516
2669
|
"count": 0,
|
|
2517
2670
|
"items": []
|
|
2518
2671
|
},
|
|
2672
|
+
"meetings": {
|
|
2673
|
+
"count": 0,
|
|
2674
|
+
"items": [],
|
|
2675
|
+
"active": []
|
|
2676
|
+
},
|
|
2519
2677
|
"memoryRepositories": {
|
|
2520
2678
|
"count": 0,
|
|
2521
2679
|
"items": []
|
|
@@ -2595,7 +2753,7 @@
|
|
|
2595
2753
|
"maintainers"
|
|
2596
2754
|
],
|
|
2597
2755
|
"phase": "Pending",
|
|
2598
|
-
"expiresAt": "2026-06-
|
|
2756
|
+
"expiresAt": "2026-06-09T07:00:21.507Z"
|
|
2599
2757
|
}
|
|
2600
2758
|
],
|
|
2601
2759
|
"mappings": [
|
|
@@ -3201,7 +3359,7 @@
|
|
|
3201
3359
|
"maintainers"
|
|
3202
3360
|
],
|
|
3203
3361
|
"phase": "Pending",
|
|
3204
|
-
"expiresAt": "2026-06-
|
|
3362
|
+
"expiresAt": "2026-06-09T07:00:21.507Z"
|
|
3205
3363
|
}
|
|
3206
3364
|
],
|
|
3207
3365
|
"mappings": [
|