Skip to content

Commit 886f442

Browse files
maryam-saeidimaryam-saeidi
authored
Merge branch 'main' into 238777-enable-list-layout
2 parents 64f961a + 8235b0e commit 886f442

9,809 files changed

Lines changed: 376242 additions & 325859 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/api-authz/SKILL.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: api-authz
3+
description: Kibana API route authorization patterns. Use when configuring route security, working with requiredPrivileges, using authzResult for privilege-based branching, opting out of authorization, or naming custom privileges.
4+
---
5+
6+
# API Authorization
7+
8+
> All API routes in Kibana must have authorization checks. Authorization is not optional, even for `internal` routes.
9+
10+
## Route Security Configuration
11+
12+
Routes declare authorization via the `security` option in `KibanaRouteOptions`:
13+
14+
```ts
15+
router.get({
16+
path: '/api/path',
17+
security: {
18+
authz: {
19+
requiredPrivileges: ['<privilege_1>', '<privilege_2>'],
20+
},
21+
},
22+
...
23+
}, handler);
24+
```
25+
26+
## Privilege Naming
27+
28+
Privilege names follow the `<operation>_<subject>` convention using underscores only.
29+
30+
| Incorrect | Why | Correct |
31+
|-----------|-----|---------|
32+
| `read-entity-a` | Uses `-` instead of `_` | `read_entity_a` |
33+
| `delete_entity-a` | Mixes `_` and `-` | `delete_entity_a` |
34+
| `entity_manage` | Subject before operation | `manage_entity` |
35+
36+
## Privilege-Based Branching with `authzResult`
37+
38+
When a route handler branches logic based on user privileges (returns different data, enables different features), it **must** use `request.authzResult`. Do not use `capabilities.resolveCapabilities()` or other authorization checks for branching — `authzResult` is the single source of truth.
39+
40+
**Look for:** routes with `anyRequired` (OR logic), handlers that conditionally expose data based on permissions, or functions that check capabilities and return booleans for branching.
41+
42+
**Correct — use `authzResult`:**
43+
```ts
44+
router.get({
45+
path: '/api/path',
46+
security: {
47+
authz: {
48+
requiredPrivileges: ['privilege_3', { anyRequired: ['privilege_1', 'privilege_2'] }],
49+
},
50+
},
51+
...
52+
}, (context, request, response) => {
53+
const authzResult = request.authzResult;
54+
// { "privilege_3": true, "privilege_1": true, "privilege_2": false }
55+
56+
if (authzResult.privilege_1) {
57+
return response.ok({ body: ... });
58+
} else if (authzResult.privilege_2) {
59+
return response.ok({ body: ... });
60+
}
61+
62+
return response.ok({ body: { data: ... } });
63+
});
64+
```
65+
66+
**Wrong — using capabilities for authorization branching:**
67+
```ts
68+
const canReadDecryptedParams = async (routeContext: RouteContext) => {
69+
const { request, server } = routeContext;
70+
const capabilities = await server.coreStart.capabilities.resolveCapabilities(request, {
71+
capabilityPath: 'my_capability.*',
72+
});
73+
return capabilities.my_capability?.canReadParams ?? false;
74+
};
75+
76+
if (await canReadDecryptedParams(routeContext)) {
77+
return getDecryptedParams(routeContext, paramId);
78+
} else {
79+
return getBasicParams(routeContext, paramId);
80+
}
81+
```
82+
83+
**Fix:** declare both privileges in the route config with `anyRequired` and branch on `request.authzResult`:
84+
```ts
85+
router.get({
86+
path: '/api/params',
87+
security: {
88+
authz: {
89+
requiredPrivileges: [{ anyRequired: ['read_params_decrypted', 'read_params'] }],
90+
},
91+
},
92+
}, (context, request, response) => {
93+
if (request.authzResult.read_params_decrypted) {
94+
return getDecryptedParams(routeContext, paramId);
95+
} else {
96+
return getBasicParams(routeContext, paramId);
97+
}
98+
});
99+
```
100+
101+
## Opting Out of Authorization
102+
103+
When a route must opt out, use the predefined `AuthzOptOutReason` enum or `AuthzDisabled` helpers from `@kbn/core-security-server`:
104+
105+
```ts
106+
import { AuthzDisabled, AuthzOptOutReason } from '@kbn/core-security-server';
107+
108+
// Predefined helper
109+
router.get({
110+
path: '/api/path',
111+
security: { authz: AuthzDisabled.delegateToSOClient },
112+
...
113+
}, handler);
114+
115+
// Predefined enum
116+
router.get({
117+
path: '/api/path',
118+
security: {
119+
authz: { enabled: false, reason: AuthzOptOutReason.DelegateToSOClient },
120+
},
121+
...
122+
}, handler);
123+
124+
// Custom reason — only when no predefined reason applies
125+
router.get({
126+
path: '/api/health',
127+
security: {
128+
authz: {
129+
enabled: false,
130+
reason: 'This route is a health check endpoint that returns no sensitive information',
131+
},
132+
},
133+
...
134+
}, handler);
135+
```
136+
137+
**Invalid opt-out reasons — flag these:**
138+
- `"Opt out from authorization"` — too generic, no context
139+
- `"This route does not need authorization"` — no explanation why
140+
- `"Authorization not required"` — no context provided
141+
- `"Authorization is delegated to SO Client"` — use `AuthzOptOutReason.DelegateToSOClient` instead
142+
143+
## References
144+
145+
- [Kibana API Authorization Documentation](dev_docs/key_concepts/api_authorization.mdx)
146+
- [Kibana HTTP API Design Guidelines](dev_docs/contributing/kibana_http_api_design_guidelines.mdx)

‎.agents/skills/branch-readiness-checks/SKILL.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: branch-readiness-checks
3+
description: "Validate branch readiness before push or PR using base-diff and local-change checks."
4+
disable-model-invocation: true
5+
---
6+
7+
# Branch Readiness
8+
9+
Run focused checks before push/PR.
10+
11+
## Command Timing
12+
13+
Use bounded polling rather than agent-specific timeout fields.
14+
For each command, set a `max_wait_ms`, poll every `poll_interval_ms`, and stop when the command completes or the max wait is reached.
15+
If `max_wait_ms` is exceeded, report a timeout and continue to the next workflow step.
16+
17+
| Command type | `max_wait_ms` | `poll_interval_ms` |
18+
|---|---:|---:|
19+
| `git diff`, `git merge-base` | 15000 | 1000 |
20+
| `node scripts/check_changes.ts --ref "$BASE"` | 180000 | 2000 |
21+
| `node scripts/lint_ts_projects.js`, `yarn test:type_check --project` | 120000 | 2000 |
22+
| `node scripts/generate codeowners`, `node scripts/regenerate_moon_projects.js` | 60000 | 2000 |
23+
| `yarn test:jest` (per package) | 300000 | 5000 |
24+
25+
## Workflow
26+
27+
Run these steps **sequentially**. Continue through all steps even if one fails.
28+
At the end, summarize issues that are likely to fail CI.
29+
30+
### Step 0: Identify affected packages
31+
32+
Collect changes relative to branch base, including untracked files. Detect the base branch rather than assuming `main`:
33+
34+
```bash
35+
BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD origin/main)
36+
# Files changed since the branch base (committed + working tree changes).
37+
git diff --name-only "$BASE"
38+
# Untracked files.
39+
git ls-files --others --exclude-standard
40+
```
41+
42+
Combine and deduplicate results. From the changed file paths, identify:
43+
- The affected packages — walk up from each changed file to the nearest `kibana.jsonc` and read its `id` field for the package ID.
44+
- The `tsconfig.json` files for those packages (sibling to `kibana.jsonc`).
45+
46+
**Prerequisite check**: verify the TS project map exists by running a quick type check on one package. If it fails with `TS Project map missing`, **stop** and ask the user if they'd like you to run `yarn kbn bootstrap`. Once bootstrap completes (or if the user declines), proceed with the remaining steps.
47+
48+
### Step 1: Run `check_changes` against branch base
49+
50+
Run `check_changes` using the `BASE` computed in Step 0:
51+
52+
```bash
53+
node scripts/check_changes.ts --ref "$BASE"
54+
```
55+
56+
Record failures in the final summary, then continue with the remaining steps.
57+
58+
### Step 2: Lint TS projects
59+
60+
Validate and auto-fix `tsconfig.json` files across affected packages.
61+
62+
```bash
63+
node scripts/lint_ts_projects.js --fix
64+
```
65+
66+
This runs repo-wide but is fast. Note files modified by `--fix` and report any remaining errors.
67+
68+
### Step 3: Type check
69+
70+
Run type checking scoped to each affected package's `tsconfig.json`.
71+
Only one `--project` flag per invocation — run separate commands for each package.
72+
73+
```bash
74+
yarn test:type_check --project path/to/tsconfig.json
75+
```
76+
77+
**Also check downstream dependents** — find packages whose `kbn_references` include any affected
78+
package ID and type-check those too. This catches cross-package breakage that CI's full
79+
`tsc -b tsconfig.refs.json` would find.
80+
81+
Use `rg` if available, otherwise fall back to `grep`:
82+
83+
```bash
84+
# Preferred (rg).
85+
rg -l '"@kbn/affected-package-id"' --glob 'tsconfig.json' .
86+
# Fallback (grep).
87+
grep -rl '"@kbn/affected-package-id"' --include='tsconfig.json' .
88+
```
89+
90+
Deduplicate against already-checked packages. If a package has more than **20** downstream
91+
tsconfigs, skip the downstream check and warn the user that a full `tsc -b` may be needed.
92+
93+
### Step 4: Unit tests
94+
95+
Run unit tests **per affected package** with coverage enabled.
96+
97+
```bash
98+
yarn test:jest --coverage path/to/package/src/
99+
```
100+
101+
If your environment provides a package-scoped unit-test tool, use the equivalent command.
102+
103+
After the run, read the coverage summary output and report overall line/branch/function coverage percentages per package. Flag any package whose line coverage is **below 80%** and provide recommendations to bring it above that threshold. Use specific uncovered files or line ranges when the coverage output provides them.
104+
105+
### Step 5: CODEOWNERS generation
106+
107+
Regenerate the CODEOWNERS file from `kibana.jsonc` owner fields.
108+
109+
```bash
110+
node scripts/generate codeowners
111+
```
112+
113+
Check `git diff .github/CODEOWNERS` afterward — if the file changed, note it in the summary.
114+
115+
### Step 6: Moon project regeneration
116+
117+
Regenerate moon project configs.
118+
119+
```bash
120+
node scripts/regenerate_moon_projects.js --update
121+
```
122+
123+
Check for unstaged changes afterward — if any moon configs changed, note them in the summary.
124+
125+
## Re-runs within the same session
126+
127+
If the user asks to re-run branch-readiness checks after fixes, or if you make changes due to failures, run all steps again.
128+
129+
## After all checks have run
130+
131+
Report a summary including:
132+
- Check changes pass/fail and key failures (if any).
133+
- TS project lint pass/fail.
134+
- Type check pass/fail per package (or "skipped" if unchanged).
135+
- Test results and coverage per package (or "skipped" if unchanged); flag packages below 80% line coverage.
136+
- Whether CODEOWNERS or moon configs need to be committed.
137+
138+
### Offering to Fix Issues
139+
140+
After reporting the summary, offer fixes by risk level:
141+
142+
- **Check changes failures, type errors, and TS project lint errors not resolved by `--fix`** — offer to fix automatically when mechanical and low risk.
143+
- **Test failures** — ask before touching test code. Test fixes can change intent, so the user should confirm before proceeding.
144+
- **Coverage gaps (below 80%)** — offer to add tests for uncovered code, but ask first. Coverage improvements are optional and the user may choose to defer them.
145+
146+
Do **not** commit or stage automatically — let the user decide.

‎.agents/skills/branch-readiness-checks/agents/openai.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
interface:
2+
display_name: "Branch Readiness Checks"
3+
short_description: "Run branch-focused validation checks"
4+
policy:
5+
allow_implicit_invocation: false

0 commit comments

Comments
 (0)