Skip to content

Commit 34f419f

Browse files
j-zimnowodaj-zimnowoda
committed
chore: agents
1 parent e9550fc commit 34f419f

4 files changed

Lines changed: 79 additions & 20 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# APL Core - AI Coding Agent Instructions
2+
3+
## Project Overview
4+
5+
APL Core (App Platform for Linode) is a Kubernetes platform that integrates 30+ cloud-native applications (Istio, Argo CD, Keycloak, Tekton, Harbor, etc.) into a cohesive, multi-tenant PaaS. The codebase is a hybrid of TypeScript (CLI/operators), Helm charts, Helmfile manifests, and Go templates.
6+
7+
## Knowledge Base
8+
9+
Use AGENTS.md files as your primary reference for understanding the codebase structure, conventions, and critical patterns. Each AGENTS.md file provides a comprehensive overview of its respective directory.
10+
11+
| File | Focus |
12+
| ------------------------------------------------------ | ---------------------------------------------------------- |
13+
| [`AGENTS.md`](AGENTS.md) | Root: architecture, conventions, commands |
14+
| [`src/api/AGENTS.md`](src/api/AGENTS.md) | Versioned route handlers (v1/v2/alpha), handler signatures |
15+
| [`src/middleware/AGENTS.md`](src/middleware/AGENTS.md) | Auth chain: JWT → groups → CASL → session → errors |
16+
| [`src/openapi/AGENTS.md`](src/openapi/AGENTS.md) | OpenAPI YAML specs, ACL definitions, schema conventions |
17+
| [`src/ai/AGENTS.md`](src/ai/AGENTS.md) | AI CRD handlers (models, agents, knowledge bases) |
18+
| [`src/utils/AGENTS.md`](src/utils/AGENTS.md) | Domain utilities: workloads, secrets, repos, YAML |

‎AGENTS.md‎

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,20 @@
22

33
**Generated:** 2026-05-04
44

5+
## TABLE OF CONTENTS
6+
7+
| File | Focus |
8+
|------|-------|
9+
| [`AGENTS.md`](AGENTS.md) | Root: architecture, conventions, commands |
10+
| [`src/api/AGENTS.md`](src/api/AGENTS.md) | Versioned route handlers (v1/v2/alpha), handler signatures |
11+
| [`src/middleware/AGENTS.md`](src/middleware/AGENTS.md) | Auth chain: JWT → groups → CASL → session → errors |
12+
| [`src/openapi/AGENTS.md`](src/openapi/AGENTS.md) | OpenAPI YAML specs, ACL definitions, schema conventions |
13+
| [`src/ai/AGENTS.md`](src/ai/AGENTS.md) | AI CRD handlers (models, agents, knowledge bases) |
14+
| [`src/utils/AGENTS.md`](src/utils/AGENTS.md) | Domain utilities: workloads, secrets, repos, YAML |
15+
516
## OVERVIEW
617

7-
Akamai App Platform API — Express/TypeScript REST API managing Kubernetes teams, workloads, and services. Uses **Git as database** (YAML files in a values repo). OpenAPI-first: specs define endpoints, authorization, and generate types.
18+
App Platform API — Express/TypeScript REST API managing Kubernetes teams, workloads, and services. Uses **Git as database** (YAML files in a values repo). OpenAPI-first: specs define endpoints, authorization, and generate types.
819

920
## STRUCTURE
1021

@@ -42,20 +53,20 @@ apl-api/
4253

4354
## WHERE TO LOOK
4455

45-
| Task | Location | Notes |
46-
|------|----------|-------|
47-
| Add new endpoint | `src/openapi/*.yaml` → `src/api/{version}/` | Define spec FIRST, then handler |
48-
| Add authorization | OpenAPI spec `x-acl` + `x-aclSchema` | ACLs live in YAML, not code |
49-
| Understand CRUD flow | `src/otomi-stack.ts` | All resource operations route here |
50-
| Add middleware | `src/middleware/` → register in `src/app.ts` | Export from `middleware/index.ts` |
51-
| Modify data models | `src/openapi/*.yaml` → `npm run build:models` | Generates `generated-schema.ts` |
52-
| Secret handling | `src/fileStore/` + `ARCHITECTURE.md` | Two-pass loading: YAML first, then secrets merged |
53-
| K8s operations | `src/k8s-operations.ts` | Pod status, logs, builds, sealed secrets |
54-
| Auth flow | `src/middleware/jwt.ts` → `src/middleware/authz.ts` | JWT → group extraction → CASL check |
55-
| AI features | `src/ai/` | Kubernetes CRD CRUD — bypasses OtomiStack |
56-
| Environment config | `src/validators.ts` + `.env.sample` | All env vars validated via envalid |
57-
| Workload/chart utils | `src/utils/workloadUtils.ts` | Git URL validation, Helm chart fetching |
58-
| Sealed secrets | `src/utils/sealedSecretUtils.ts` | Encryption, manifest creation |
56+
| Task | Location | Notes |
57+
| -------------------- | --------------------------------------------------- | ------------------------------------------------- |
58+
| Add new endpoint | `src/openapi/*.yaml` → `src/api/{version}/` | Define spec FIRST, then handler |
59+
| Add authorization | OpenAPI spec `x-acl` + `x-aclSchema` | ACLs live in YAML, not code |
60+
| Understand CRUD flow | `src/otomi-stack.ts` | All resource operations route here |
61+
| Add middleware | `src/middleware/` → register in `src/app.ts` | Export from `middleware/index.ts` |
62+
| Modify data models | `src/openapi/*.yaml` → `npm run build:models` | Generates `generated-schema.ts` |
63+
| Secret handling | `src/fileStore/` + `ARCHITECTURE.md` | Two-pass loading: YAML first, then secrets merged |
64+
| K8s operations | `src/k8s-operations.ts` | Pod status, logs, builds, sealed secrets |
65+
| Auth flow | `src/middleware/jwt.ts` → `src/middleware/authz.ts` | JWT → group extraction → CASL check |
66+
| AI features | `src/ai/` | Kubernetes CRD CRUD — bypasses OtomiStack |
67+
| Environment config | `src/validators.ts` + `.env.sample` | All env vars validated via envalid |
68+
| Workload/chart utils | `src/utils/workloadUtils.ts` | Git URL validation, Helm chart fetching |
69+
| Sealed secrets | `src/utils/sealedSecretUtils.ts` | Encryption, manifest creation |
5970

6071
## CONVENTIONS
6172

‎src/api/AGENTS.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ api/
1414
│ ├── apps/ # Platform app configs
1515
│ ├── settings/ # Cluster settings
1616
│ └── *.ts # Top-level resource handlers
17-
├── v2/ # Current handlers — return AplResponseObject, call req.otomi.*Apl*
17+
├── v2/ # Current handlers — (req, res) signature, call req.otomi.*Apl*
1818
│ └── teams/{teamId}/ # Team-scoped with sub-resource dirs
1919
├── alpha/ # Experimental (AI features, team extensions)
2020
│ ├── ai/ # AI model/agent/knowledgebase endpoints
@@ -27,14 +27,15 @@ api/
2727
| Task | Location | Notes |
2828
|------|----------|-------|
2929
| Add v1 endpoint | `v1/` + matching OpenAPI spec | Legacy: `(req, res) => void` |
30-
| Add v2 endpoint | `v2/` + matching OpenAPI spec | Current: `(req) => Promise<AplResponseObject>` |
30+
| Add v2 endpoint | `v2/` + matching OpenAPI spec | Current: `(req, res) => void` |
3131
| Add AI endpoint | `alpha/ai/` | Uses `src/ai/` handlers, not OtomiStack |
3232
| Team-scoped resource | `{version}/teams/{teamId}/` | Dir name literally `{teamId}` |
3333

3434
## CONVENTIONS
3535

36-
- **v1 handlers**: `export const opId = (req: OpenApiRequestExt, res: Response): void` — send response via `res.json()`
37-
- **v2 handlers**: `export async function opId(req: OpenApiRequestExt): Promise<AplResponseObject>` — return value
36+
- **v1 handlers**: `export const opId = (req: OpenApiRequestExt, res: Response): void` — call `req.otomi.get*()`, send via `res.json()`
37+
- **v2 handlers**: `export const opId = (req: OpenApiRequestExt, res: Response): void` — call `req.otomi.*Apl*()`, send via `res.json()`
38+
- **v1 vs v2 difference**: Method names on `req.otomi` — v1 uses `get*()`, v2 uses `getApl*()`/`createApl*()` etc.
3839
- **File naming**: Matches resource name (e.g., `services.ts`, `coderepos.ts`)
3940
- **Sub-resource pattern**: Directory for collection, file for item (e.g., `services.ts` = list, `services/{name}.ts` = single)
4041
- **All business logic** lives in `OtomiStack` via `req.otomi.*` — handlers are thin wrappers
@@ -44,4 +45,3 @@ api/
4445

4546
- **DO NOT** put business logic in handlers — delegate to `req.otomi` (OtomiStack)
4647
- **DO NOT** create handler files without corresponding OpenAPI spec entry
47-
- **DO NOT** mix v1/v2 patterns — v1 uses `res.json()`, v2 returns objects

‎src/utils/AGENTS.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Utilities
2+
3+
## OVERVIEW
4+
5+
Domain-specific utility modules. No barrel file — import each directly.
6+
7+
## WHERE TO LOOK
8+
9+
| Task | Location | Notes |
10+
|------|----------|-------|
11+
| Workload/Helm operations | `workloadUtils.ts` | Git URL validation, chart fetching, sparse clone, provider detection |
12+
| Code repository setup | `codeRepoUtils.ts` | Gitea URL management, SSH key normalization, connectivity testing |
13+
| Sealed secret encryption | `sealedSecretUtils.ts` | Encrypt values, create manifests, extract secret paths |
14+
| User/Keycloak integration | `userUtils.ts` | User data handling, username validation |
15+
| YAML safety | `yamlUtils.ts` | `quoteIfDangerous`, `deepQuote` — prevents YAML injection |
16+
| V1↔APL object conversion | `manifests.ts` | Bidirectional transforms, merge utilities |
17+
| Policy retrieval | `policiesUtils.ts` | Reads policies from generated schema |
18+
| K8s version checks | `k8sUtils.ts` | Cluster version, Knative support detection |
19+
| Object storage/cluster ID | `wizardUtils.ts` | `ObjectStorageClient` class, cluster ID definition |
20+
21+
## CONVENTIONS
22+
23+
- **No barrel export** — import individual files: `import { ... } from 'src/utils/workloadUtils'`
24+
- **Debug namespace**: `otomi:utils:*`
25+
- **Tests colocated**: `*.test.ts` alongside source files
26+
27+
## ANTI-PATTERNS
28+
29+
- **DO NOT** add generic helpers here — each file is domain-scoped
30+
- **DO NOT** import from `src/utils` (no index.ts) — always import specific file

0 commit comments

Comments
 (0)