agent-steward 0.0.4 → 0.0.6
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/CHANGELOG.md +309 -2
- package/CROSS_PLATFORM.md +19 -0
- package/README.md +55 -8
- package/ROADMAP-STRATEGY.md +22 -19
- package/ROADMAP.md +230 -159
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +356 -0
- package/dist/core/analytics.d.ts +6 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +20 -3
- package/dist/core/audit.d.ts +6 -0
- package/dist/core/audit.d.ts.map +1 -1
- package/dist/core/audit.js +24 -0
- package/dist/core/budget.d.ts +118 -0
- package/dist/core/budget.d.ts.map +1 -0
- package/dist/core/budget.js +206 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -1
- package/dist/core/cron-to-schtasks.js +38 -0
- package/dist/core/dry-run.d.ts +26 -1
- package/dist/core/dry-run.d.ts.map +1 -1
- package/dist/core/dry-run.js +199 -8
- package/dist/core/execution.d.ts +203 -0
- package/dist/core/execution.d.ts.map +1 -0
- package/dist/core/execution.js +309 -0
- package/dist/core/feedback.d.ts +192 -0
- package/dist/core/feedback.d.ts.map +1 -0
- package/dist/core/feedback.js +426 -0
- package/dist/core/gate-integrity.d.ts +71 -0
- package/dist/core/gate-integrity.d.ts.map +1 -0
- package/dist/core/gate-integrity.js +275 -0
- package/dist/core/git-trigger.d.ts.map +1 -1
- package/dist/core/git-trigger.js +14 -2
- package/dist/core/guard-run.d.ts +4 -0
- package/dist/core/guard-run.d.ts.map +1 -0
- package/dist/core/guard-run.js +101 -0
- package/dist/core/guard.d.ts +52 -0
- package/dist/core/guard.d.ts.map +1 -0
- package/dist/core/guard.js +362 -0
- package/dist/core/local-ai.d.ts.map +1 -1
- package/dist/core/local-ai.js +7 -3
- package/dist/core/lock.d.ts +41 -0
- package/dist/core/lock.d.ts.map +1 -1
- package/dist/core/lock.js +141 -29
- package/dist/core/matrix.d.ts +8 -0
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +132 -17
- package/dist/core/mission.d.ts +103 -0
- package/dist/core/mission.d.ts.map +1 -0
- package/dist/core/mission.js +374 -0
- package/dist/core/opencode-models.d.ts +2 -2
- package/dist/core/opencode-models.d.ts.map +1 -1
- package/dist/core/opencode-models.js +28 -21
- package/dist/core/opencode-usage.d.ts +35 -0
- package/dist/core/opencode-usage.d.ts.map +1 -0
- package/dist/core/opencode-usage.js +132 -0
- package/dist/core/pipeline-apply.d.ts +38 -0
- package/dist/core/pipeline-apply.d.ts.map +1 -0
- package/dist/core/pipeline-apply.js +117 -0
- package/dist/core/pipeline-io.d.ts +13 -0
- package/dist/core/pipeline-io.d.ts.map +1 -0
- package/dist/core/pipeline-io.js +78 -0
- package/dist/core/pipeline-map.d.ts +52 -0
- package/dist/core/pipeline-map.d.ts.map +1 -0
- package/dist/core/pipeline-map.js +208 -0
- package/dist/core/pipeline-spec.d.ts +109 -0
- package/dist/core/pipeline-spec.d.ts.map +1 -0
- package/dist/core/pipeline-spec.js +554 -0
- package/dist/core/ps-wrapper.d.ts +27 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +424 -65
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +206 -33
- package/dist/core/router/rules.d.ts.map +1 -1
- package/dist/core/router/rules.js +6 -0
- package/dist/core/run-mode.d.ts +12 -0
- package/dist/core/run-mode.d.ts.map +1 -0
- package/dist/core/run-mode.js +17 -0
- package/dist/core/scheduler/linux.d.ts +8 -1
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +34 -9
- package/dist/core/scheduler/logs.d.ts +4 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -1
- package/dist/core/scheduler/logs.js +25 -1
- package/dist/core/scheduler/mac.d.ts +44 -2
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +126 -15
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +15 -12
- package/dist/core/secrets.d.ts.map +1 -1
- package/dist/core/secrets.js +18 -8
- package/dist/core/self-analysis.d.ts +32 -2
- package/dist/core/self-analysis.d.ts.map +1 -1
- package/dist/core/self-analysis.js +38 -27
- package/dist/core/shutdown.d.ts +33 -2
- package/dist/core/shutdown.d.ts.map +1 -1
- package/dist/core/shutdown.js +58 -2
- package/dist/core/structured-log.d.ts +37 -1
- package/dist/core/structured-log.d.ts.map +1 -1
- package/dist/core/structured-log.js +37 -0
- package/dist/core/usage-surface.d.ts +25 -0
- package/dist/core/usage-surface.d.ts.map +1 -0
- package/dist/core/usage-surface.js +41 -0
- package/dist/core/worktree-run.d.ts +4 -0
- package/dist/core/worktree-run.d.ts.map +1 -0
- package/dist/core/worktree-run.js +164 -0
- package/dist/core/worktree.d.ts +115 -0
- package/dist/core/worktree.d.ts.map +1 -0
- package/dist/core/worktree.js +462 -0
- package/dist/core/wrappers/bash.d.ts +19 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +230 -27
- package/dist/db/capability-repo.d.ts +43 -2
- package/dist/db/capability-repo.d.ts.map +1 -1
- package/dist/db/capability-repo.js +96 -11
- package/dist/db/history-repo.d.ts +70 -5
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +170 -29
- package/dist/db/metrics-repo.d.ts +20 -2
- package/dist/db/metrics-repo.d.ts.map +1 -1
- package/dist/db/metrics-repo.js +35 -13
- package/dist/db/migrate.d.ts.map +1 -1
- package/dist/db/migrate.js +37 -17
- package/dist/db/recovery.d.ts +3 -1
- package/dist/db/recovery.d.ts.map +1 -1
- package/dist/db/recovery.js +11 -5
- package/dist/db/run-journal.d.ts +33 -5
- package/dist/db/run-journal.d.ts.map +1 -1
- package/dist/db/run-journal.js +78 -14
- package/dist/db/run-resume.d.ts +5 -0
- package/dist/db/run-resume.d.ts.map +1 -1
- package/dist/db/run-resume.js +9 -2
- package/dist/db/runs-repo.d.ts +19 -2
- package/dist/db/runs-repo.d.ts.map +1 -1
- package/dist/db/runs-repo.js +91 -60
- package/dist/db/schema.d.ts +2 -2
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +132 -2
- package/dist/db/templates-repo.d.ts +2 -2
- package/dist/db/templates-repo.d.ts.map +1 -1
- package/dist/db/templates-repo.js +5 -3
- package/dist/history.d.ts +7 -2
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +4 -2
- package/dist/hook-output.d.ts +2 -0
- package/dist/hook-output.d.ts.map +1 -0
- package/dist/hook-output.js +31 -0
- package/dist/i18n.d.ts +5 -0
- package/dist/i18n.d.ts.map +1 -1
- package/dist/i18n.js +11 -4
- package/dist/index.d.ts +375 -47
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1344 -192
- package/dist/notifications.d.ts +53 -2
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +168 -21
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +82 -10
- package/dist/rpc.d.ts +354 -0
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +145 -0
- package/dist/server.d.ts +32 -2
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +154 -30
- package/dist/settings.d.ts +44 -2
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +85 -3
- package/dist/shared/jobs-view.d.ts +1 -1
- package/dist/shared/jobs-view.d.ts.map +1 -1
- package/dist/shared/jobs-view.js +2 -0
- package/dist/task-transfer.d.ts +21 -0
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +64 -3
- package/dist/templates.d.ts +2 -2
- package/dist/templates.d.ts.map +1 -1
- package/dist/templates.js +3 -3
- package/dist/types.d.ts +22 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +34 -11
- package/docs/ARCHITECTURE.md +319 -66
- package/docs/COMPATIBILITY.md +2 -2
- package/docs/CONCEPT.md +18 -4
- package/docs/CROSS_PLATFORM.ru.md +20 -0
- package/docs/CROSS_PLATFORM.zh.md +18 -0
- package/docs/EXECUTION-LOOP.md +28 -10
- package/docs/FEATURES.md +129 -7
- package/docs/FEATURES.zh.md +97 -6
- package/docs/MIGRATION.md +2 -2
- package/docs/PIPELINE.md +293 -0
- package/docs/QA-A2-GUI-TUI.md +205 -0
- package/docs/README.ru.md +43 -4
- package/docs/README.zh.md +44 -4
- package/docs/SAFETY.md +23 -3
- package/gui-experimental.cjs +9 -8
- package/locales/en.json +58 -3
- package/locales/ru.json +58 -3
- package/locales/zh.json +58 -3
- package/opencode.pipeline.yaml +35 -0
- package/package.json +36 -4
- package/scripts/check-eslint-baseline.mjs +139 -0
- package/scripts/gen-test-plan-counters.mjs +117 -0
- package/scripts/github-ci-fetch.ps1 +37 -0
- package/scripts/pl-commit.ps1 +112 -0
- package/scripts/qa-a2-commit.ps1 +104 -0
- package/scripts/test-home.mjs +107 -0
- package/skills/scheduled-job-best-practices/SKILL.md +95 -1
- package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
- package/src/cli.ts +417 -0
- package/src/core/analytics.ts +27 -4
- package/src/core/audit.ts +25 -0
- package/src/core/budget.ts +340 -0
- package/src/core/cron-to-schtasks.ts +42 -0
- package/src/core/dry-run.ts +235 -12
- package/src/core/execution.ts +538 -0
- package/src/core/feedback.ts +582 -0
- package/src/core/file-watcher.ts +2 -2
- package/src/core/gate-integrity.ts +330 -0
- package/src/core/git-trigger.ts +18 -5
- package/src/core/guard-run.ts +119 -0
- package/src/core/guard.ts +431 -0
- package/src/core/local-ai.ts +7 -3
- package/src/core/lock.ts +178 -37
- package/src/core/matrix.ts +158 -52
- package/src/core/mission.ts +531 -0
- package/src/core/native-notify.ts +1 -1
- package/src/core/opencode-models.ts +30 -21
- package/src/core/opencode-usage.ts +182 -0
- package/src/core/pipeline-apply.ts +158 -0
- package/src/core/pipeline-io.ts +96 -0
- package/src/core/pipeline-map.ts +283 -0
- package/src/core/pipeline-spec.ts +775 -0
- package/src/core/ps-wrapper.ts +435 -66
- package/src/core/record-history.ts +258 -81
- package/src/core/router/rules.ts +6 -0
- package/src/core/run-mode.ts +19 -0
- package/src/core/schedule-gate.ts +1 -1
- package/src/core/scheduler/at-fallback.ts +1 -1
- package/src/core/scheduler/linux.ts +40 -11
- package/src/core/scheduler/logs.ts +34 -3
- package/src/core/scheduler/mac.ts +174 -14
- package/src/core/scheduler/registry.ts +2 -2
- package/src/core/scheduler/windows.ts +19 -15
- package/src/core/secrets.ts +26 -19
- package/src/core/self-analysis.ts +75 -29
- package/src/core/shutdown.ts +90 -4
- package/src/core/structured-log.ts +89 -5
- package/src/core/telegram.ts +2 -2
- package/src/core/triage-worker.ts +7 -7
- package/src/core/triage.ts +2 -2
- package/src/core/usage-surface.ts +70 -0
- package/src/core/worktree-run.ts +199 -0
- package/src/core/worktree.ts +600 -0
- package/src/core/wrappers/bash.ts +248 -26
- package/src/db/capability-repo.ts +127 -10
- package/src/db/history-repo.ts +281 -40
- package/src/db/metrics-repo.ts +40 -13
- package/src/db/migrate.ts +57 -32
- package/src/db/recovery.ts +12 -5
- package/src/db/run-journal.ts +100 -13
- package/src/db/run-resume.ts +17 -1
- package/src/db/runs-repo.ts +147 -65
- package/src/db/schema.ts +134 -2
- package/src/db/templates-repo.ts +5 -3
- package/src/gui.tsx +438 -18
- package/src/history.ts +11 -4
- package/src/hook-output.ts +39 -0
- package/src/i18n.ts +12 -4
- package/src/index.ts +1902 -320
- package/src/notifications.ts +227 -47
- package/src/profiles.ts +88 -10
- package/src/rpc.ts +158 -0
- package/src/server.ts +201 -41
- package/src/settings.ts +125 -5
- package/src/shared/jobs-view.ts +3 -1
- package/src/task-transfer.ts +90 -6
- package/src/templates.ts +3 -3
- package/src/types.ts +23 -2
- package/src/workspaces.ts +37 -14
package/docs/PIPELINE.md
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
# Pipeline as code
|
|
2
|
+
|
|
3
|
+
`opencode.pipeline.yaml` describes a whole workflow — triggers, DAG dependencies,
|
|
4
|
+
defaults and matrix fan-out — as one reviewable file. The scheduler validates it,
|
|
5
|
+
turns every step into a task, and applies it idempotently.
|
|
6
|
+
|
|
7
|
+
- [File format](#file-format)
|
|
8
|
+
- [Steps and dependencies](#steps-and-dependencies)
|
|
9
|
+
- [Triggers](#triggers)
|
|
10
|
+
- [Defaults](#defaults)
|
|
11
|
+
- [Matrix fan-out](#matrix-fan-out)
|
|
12
|
+
- [Validate, apply, export](#validate-apply-export)
|
|
13
|
+
- [Apply semantics](#apply-semantics)
|
|
14
|
+
- [Agent tools](#agent-tools)
|
|
15
|
+
- [Validation rules](#validation-rules)
|
|
16
|
+
- [Limitations](#limitations)
|
|
17
|
+
|
|
18
|
+
A ready-to-run example lives in [`opencode.pipeline.yaml`](../opencode.pipeline.yaml).
|
|
19
|
+
|
|
20
|
+
## File format
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
version: 1
|
|
24
|
+
name: nightly-release
|
|
25
|
+
description: Lint, test and build the repository every night.
|
|
26
|
+
|
|
27
|
+
defaults:
|
|
28
|
+
timeoutSeconds: 1800
|
|
29
|
+
retryCount: 1
|
|
30
|
+
retryDelay: 120
|
|
31
|
+
|
|
32
|
+
steps:
|
|
33
|
+
- id: lint
|
|
34
|
+
schedule: "0 2 * * *"
|
|
35
|
+
prompt: Run the linter and fix what it reports.
|
|
36
|
+
qualityGate: npm run lint
|
|
37
|
+
|
|
38
|
+
- id: test
|
|
39
|
+
needs: [lint]
|
|
40
|
+
trigger: dag
|
|
41
|
+
prompt: Run the tests and fix failures.
|
|
42
|
+
qualityGate: npm test
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| Field | Required | Meaning |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| `version` | yes | Format version. Must be `1`. |
|
|
48
|
+
| `name` | yes | Pipeline name, 1–120 characters: letters, digits, space, `.`, `_`, `-`. |
|
|
49
|
+
| `description` | no | Free-form text for humans. |
|
|
50
|
+
| `defaults` | no | Values inherited by every step (see [Defaults](#defaults)). |
|
|
51
|
+
| `steps` | yes | 1–200 steps. |
|
|
52
|
+
|
|
53
|
+
Every step becomes a scheduler task. Unless the step sets `name`, the task is named
|
|
54
|
+
`<pipeline> <step id>` — for example `nightly-release test`. The name must pass the
|
|
55
|
+
normal task-name rules (letters, digits, space, `.`, `_`, `-`), so keep pipeline names
|
|
56
|
+
and step ids reasonably short.
|
|
57
|
+
|
|
58
|
+
## Steps and dependencies
|
|
59
|
+
|
|
60
|
+
| Field | Type | Meaning |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `id` | string | Stable step identifier, 1–64 characters. Unique within the pipeline, case-insensitive. |
|
|
63
|
+
| `name` | string | Task name override. Default: `<pipeline> <id>`. |
|
|
64
|
+
| `prompt` | string | Agent prompt. Required and non-empty. |
|
|
65
|
+
| `needs` | string[] | Step ids that must finish successfully first. Becomes `dependsOn`. |
|
|
66
|
+
| `schedule` | string | Cron expression for `trigger: cron`. |
|
|
67
|
+
| `trigger` | enum | `cron` (default), `once`, `dag`, `file`, `git`, `mcp-event`. |
|
|
68
|
+
| `runAt` | string | ISO-8601 start time for `trigger: once`. |
|
|
69
|
+
| `qualityGate` | string | Command that decides whether the run is successful. |
|
|
70
|
+
| `beforeScript` / `afterScript` | string | Hooks around the agent run. |
|
|
71
|
+
| `model` | string | `provider/model` (optionally `provider/model#variant`). |
|
|
72
|
+
| `priority` | integer | 0–10, higher runs first. |
|
|
73
|
+
| `timeoutSeconds` | integer | Hard timeout, at least 1. |
|
|
74
|
+
| `retryCount` / `retryDelay` | integer | Retries (≥ 0) and delay between them. |
|
|
75
|
+
| `workingDirectory` | string | Run directory for the step. |
|
|
76
|
+
| `workspaceId` | string | Run inside a workspace. Cannot be combined with `matrix`. |
|
|
77
|
+
| `allowedTools` / `deniedTools` | string[] | Per-step tool policy. A non-empty `allowedTools` is an allowlist. |
|
|
78
|
+
| `matrix` | object | Fan the step out over workspaces (see [Matrix fan-out](#matrix-fan-out)). |
|
|
79
|
+
| `timezone` | string | IANA timezone, e.g. `Europe/Moscow`. |
|
|
80
|
+
| `notBefore` / `notAfter` | string | Launch window as `HH:MM`; `notAfter` may be earlier (crosses midnight). |
|
|
81
|
+
| `activeDays` | integer[] | Allowed weekdays, `0` = Sunday. |
|
|
82
|
+
| `windowPolicy` | enum | `skip`, `postpone` (default) or `run` outside the window. |
|
|
83
|
+
|
|
84
|
+
Dependencies are declarative: a step listed in `needs` starts only after every
|
|
85
|
+
dependency's latest run succeeded. Cycles, unknown ids and self-references are rejected
|
|
86
|
+
before anything is created.
|
|
87
|
+
|
|
88
|
+
A step that has no trigger of its own uses `trigger: dag`:
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
steps:
|
|
92
|
+
- id: lint
|
|
93
|
+
schedule: "0 2 * * *"
|
|
94
|
+
prompt: Lint the repository.
|
|
95
|
+
|
|
96
|
+
- id: test
|
|
97
|
+
needs: [lint]
|
|
98
|
+
trigger: dag
|
|
99
|
+
prompt: Run the tests.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`dag` steps are stored as dependency-only tasks (`triggerType: "file"` with an empty
|
|
103
|
+
schedule), just like matrix parents: the DAG engine starts them, not the OS scheduler.
|
|
104
|
+
They must have a non-empty `needs`; otherwise they would never run.
|
|
105
|
+
|
|
106
|
+
## Triggers
|
|
107
|
+
|
|
108
|
+
| `trigger` | Requires | Behaviour |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| `cron` (default) | `schedule` in the step or defaults | Registered with the native OS scheduler. |
|
|
111
|
+
| `once` | `runAt` (ISO-8601) | Runs once at the given moment; `schedule` is ignored. |
|
|
112
|
+
| `dag` | non-empty `needs` | Started by the DAG engine after dependencies succeed; `schedule` is ignored. |
|
|
113
|
+
| `file`, `git`, `mcp-event` | — | Accepted by the validator, but see [Limitations](#limitations). |
|
|
114
|
+
|
|
115
|
+
Cron expressions use the same parser as regular tasks: five fields, lists, ranges,
|
|
116
|
+
steps, month and weekday names, `@every 15m`, `L` and `FRI#3`. The validator calls that
|
|
117
|
+
parser, so an invalid expression is reported before apply.
|
|
118
|
+
|
|
119
|
+
A one-shot pipeline step:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
steps:
|
|
123
|
+
- id: deploy
|
|
124
|
+
trigger: once
|
|
125
|
+
runAt: "2026-11-20T22:40:00+03:00"
|
|
126
|
+
prompt: Deploy the current main branch.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Defaults
|
|
130
|
+
|
|
131
|
+
`defaults` is inherited by every step that does not set the field itself. Supported
|
|
132
|
+
keys: `schedule`, `trigger`, `model`, `priority`, `timeoutSeconds`, `workingDirectory`,
|
|
133
|
+
`retryCount`, `retryDelay`, `allowedTools`, `deniedTools`, `timezone`.
|
|
134
|
+
|
|
135
|
+
Defaults do not include `matrix`, quality gates, hooks, launch windows or
|
|
136
|
+
`workspaceId` — set those per step. Unknown keys under `defaults` produce warnings so
|
|
137
|
+
typos are visible.
|
|
138
|
+
|
|
139
|
+
## Matrix fan-out
|
|
140
|
+
|
|
141
|
+
A step with `matrix` becomes a matrix parent: one clone per workspace, with the same
|
|
142
|
+
strategy, failure mode, concurrency and aggregation as a regular matrix task.
|
|
143
|
+
|
|
144
|
+
```yaml
|
|
145
|
+
steps:
|
|
146
|
+
- id: deploy
|
|
147
|
+
schedule: "0 3 * * *"
|
|
148
|
+
prompt: Build, test and deploy this repository.
|
|
149
|
+
matrix:
|
|
150
|
+
workspaces: [frontend, backend]
|
|
151
|
+
strategy: parallel
|
|
152
|
+
failureMode: continue
|
|
153
|
+
concurrency: 2
|
|
154
|
+
aggregation: summary
|
|
155
|
+
createAggregator: true
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
| `matrix` field | Default | Meaning |
|
|
159
|
+
| --- | --- | --- |
|
|
160
|
+
| `workspaces` | required | Workspace names or ids; non-empty and unique. |
|
|
161
|
+
| `strategy` | `parallel` | `sequential` starts the next clone after the previous one. |
|
|
162
|
+
| `failureMode` | `continue` | `stop` cancels the remaining clones after the first failure. |
|
|
163
|
+
| `concurrency` | unlimited | Maximum clones running at once. |
|
|
164
|
+
| `aggregation` | `summary` | `summary` writes one aggregate record for the parent. |
|
|
165
|
+
| `createAggregator` | `false` | Also create `<parent>-matrix-complete`. |
|
|
166
|
+
|
|
167
|
+
Workspace names are resolved when the file is applied. An unknown name produces a
|
|
168
|
+
warning and the step is rejected at apply time, so create workspaces first (or use
|
|
169
|
+
their ids). `matrix` cannot be combined with `workspaceId` on the same step.
|
|
170
|
+
|
|
171
|
+
## Validate, apply, export
|
|
172
|
+
|
|
173
|
+
The CLI ships with the package (`agent-steward` binary):
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
agent-steward pipeline validate opencode.pipeline.yaml
|
|
177
|
+
agent-steward pipeline apply opencode.pipeline.yaml --dry-run
|
|
178
|
+
agent-steward pipeline apply opencode.pipeline.yaml
|
|
179
|
+
agent-steward pipeline export --pipeline nightly-release
|
|
180
|
+
agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
| Command | Flags | Result |
|
|
184
|
+
| --- | --- | --- |
|
|
185
|
+
| `pipeline validate <file>` | `--json` | Parses and validates; never changes tasks. |
|
|
186
|
+
| `pipeline apply <file>` | `--dry-run`, `--json` | Creates and updates tasks; `--dry-run` only prints the plan. |
|
|
187
|
+
| `pipeline export` | `--pipeline <name>`, `--out <file>` | Rebuilds YAML from tasks; stdout unless `--out` is given. |
|
|
188
|
+
|
|
189
|
+
Exit codes: `0` success, `1` validation/apply errors (or an unknown pipeline on export),
|
|
190
|
+
`2` bad arguments. Human-readable output is in Russian; add `--json` for stable machine
|
|
191
|
+
output.
|
|
192
|
+
|
|
193
|
+
`validate --json` returns:
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{ "ok": true, "errors": [], "warnings": [], "steps": 3 }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`apply --json` returns the plan summary:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"pipeline": "nightly-release",
|
|
204
|
+
"dryRun": false,
|
|
205
|
+
"creates": ["nightly-release build"],
|
|
206
|
+
"updates": ["nightly-release test"],
|
|
207
|
+
"unchanged": ["nightly-release lint"],
|
|
208
|
+
"stale": []
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Apply semantics
|
|
213
|
+
|
|
214
|
+
Apply is a three-way diff, not a blind rewrite:
|
|
215
|
+
|
|
216
|
+
1. Tasks of this pipeline are matched by the `pipelineName` + `pipelineStepId` markers
|
|
217
|
+
stored in their definition. Matching is case-insensitive.
|
|
218
|
+
2. A step with no matching task is **created**.
|
|
219
|
+
3. A step whose significant fields changed is **updated**; the comparison covers the
|
|
220
|
+
schedule, prompt, trigger, DAG dependencies, model, matrix, gates, hooks, tool
|
|
221
|
+
policy, launch window and pipeline markers.
|
|
222
|
+
4. A step with an identical definition is **unchanged** and untouched.
|
|
223
|
+
5. A task of the same pipeline that is no longer in the file is reported as **stale**.
|
|
224
|
+
It is never deleted automatically — delete it manually or return the step to the
|
|
225
|
+
file.
|
|
226
|
+
|
|
227
|
+
Tasks that do not carry pipeline markers are never read, updated or deleted by apply.
|
|
228
|
+
Running `apply` twice in a row is safe: the second run reports `unchanged` for every
|
|
229
|
+
step.
|
|
230
|
+
|
|
231
|
+
Renaming `name` starts a new pipeline identity. The old tasks keep their old marker, so
|
|
232
|
+
they are not matched, not reported as stale and must be removed by hand.
|
|
233
|
+
|
|
234
|
+
`export` reverses the mapping: it restores `needs` from `dependsOn`,
|
|
235
|
+
`matrix.workspaces` from `matrix.workspaceIds`, and the trigger from `triggerType`.
|
|
236
|
+
A `file` task with no schedule, no watch path and non-empty `dependsOn` is exported as
|
|
237
|
+
`trigger: dag`. Dependencies that point outside the pipeline are dropped with a
|
|
238
|
+
warning, and the default `<pipeline> <step>` name is omitted.
|
|
239
|
+
|
|
240
|
+
## Agent tools
|
|
241
|
+
|
|
242
|
+
| Tool | Arguments | What it does |
|
|
243
|
+
| --- | --- | --- |
|
|
244
|
+
| `pipeline_validate` | `path?`, `source?` | Validates a file or inline YAML. Returns pipeline name, step count, errors and warnings. |
|
|
245
|
+
| `pipeline_apply` | `path?`, `source?`, `dryRun?` | Idempotent create/update. `dryRun: true` only reports the diff. |
|
|
246
|
+
| `pipeline_export` | `pipeline` | Returns the pipeline as YAML plus warnings. |
|
|
247
|
+
|
|
248
|
+
`pipeline_apply` writes an audit record with action `pipeline.apply`. Pass either
|
|
249
|
+
`path` or `source`; with neither, the tool returns an explicit error.
|
|
250
|
+
|
|
251
|
+
## Validation rules
|
|
252
|
+
|
|
253
|
+
Validation never throws: it returns `{ ok, errors, warnings }`, where every issue has a
|
|
254
|
+
`path` such as `steps[2].schedule` and a human-readable message. Errors block apply;
|
|
255
|
+
warnings do not.
|
|
256
|
+
|
|
257
|
+
| Area | Rule |
|
|
258
|
+
| --- | --- |
|
|
259
|
+
| Format | YAML up to 1 MiB, duplicate keys rejected, aliases limited to 100. |
|
|
260
|
+
| `version` | Exactly `1`. |
|
|
261
|
+
| `name` | Non-empty, ≤ 120 characters, no control characters, limited alphabet. |
|
|
262
|
+
| `steps` | 1–200 entries. |
|
|
263
|
+
| Step `id` | Non-empty, ≤ 64 characters, must start with a letter or digit, then letters, digits, `.`, `_`, `-`; unique case-insensitively. |
|
|
264
|
+
| `prompt` | Non-empty. |
|
|
265
|
+
| Task name | Explicit `name` must pass task-name validation; generated names must not collide case-insensitively. |
|
|
266
|
+
| `needs` | No duplicates, no self-reference, every id must exist, no cycles. |
|
|
267
|
+
| Cron | A cron step needs `schedule`; the expression must parse with the shared cron parser. |
|
|
268
|
+
| `once` | `runAt` must be valid ISO-8601. |
|
|
269
|
+
| `dag` | `needs` must be non-empty; `schedule` is ignored with a warning. |
|
|
270
|
+
| Other triggers | `schedule` on `file`, `git` or `mcp-event` is ignored with a warning. |
|
|
271
|
+
| Numbers | `priority` 0–10; `timeoutSeconds` ≥ 1; `retryCount` and `retryDelay` are non-negative integers; `concurrency` ≥ 1. |
|
|
272
|
+
| Tools | `allowedTools` must be a non-empty array of non-empty strings; `deniedTools` must be an array of strings. |
|
|
273
|
+
| Matrix | `workspaces` non-empty and unique; valid enum values; no `workspaceId` on the same step. |
|
|
274
|
+
| Timezone | Valid IANA zone name. |
|
|
275
|
+
| Window | `notBefore`/`notAfter` valid `HH:MM`; `activeDays` integers 0–6; `windowPolicy` one of the enum values. |
|
|
276
|
+
| Unknown keys | Reported as warnings at the root, in `defaults`, in a step and in `matrix`. |
|
|
277
|
+
|
|
278
|
+
## Limitations
|
|
279
|
+
|
|
280
|
+
- **File, git and MCP-event triggers are not fully expressible yet.** The validator
|
|
281
|
+
accepts the trigger names, but the format has no fields for `watchPath`, globs, git
|
|
282
|
+
filters or an MCP event name. Use `schedule_task` / `update_task` for those tasks in
|
|
283
|
+
v1.
|
|
284
|
+
- **No automatic deletion.** Removed steps stay as stale tasks on purpose, so a bad
|
|
285
|
+
edit cannot destroy a working schedule. Clean them up by hand.
|
|
286
|
+
- **Not in the format yet:** session continuity (`session` / `sessionMaxRuns`), `env`
|
|
287
|
+
and secrets, chains (`nextTaskOnSuccess` / `nextTaskOnError`), incoming webhooks,
|
|
288
|
+
`runWhenLoggedOff`, `paused`, and per-workspace matrix `overrides`. Use
|
|
289
|
+
`schedule_task` for those, or manage them after apply.
|
|
290
|
+
- **One profile at a time.** Apply and export work against the active profile's
|
|
291
|
+
database.
|
|
292
|
+
- **A pipeline is identified by `name`.** Treat the name as an immutable key; renaming
|
|
293
|
+
it leaves the old task family behind.
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# QA-A2.6 — Исключение GUI/TUI из контура типизации (явная фиксация)
|
|
2
|
+
|
|
3
|
+
Статус: **исключение зафиксировано явно** (вместо молчаливого). Ветка: `dev`.
|
|
4
|
+
Эпик: QA-A2 «Полная типизация плагина». Ссылка: `ROADMAP.md`, строка QA-A2.6.
|
|
5
|
+
|
|
6
|
+
Цель подзадачи — не «типизировать GUI/TUI прямо сейчас», а прервать статус
|
|
7
|
+
*silent-исключения*: записать, **почему** три `.tsx`-файла не попадают ни в `tsc`,
|
|
8
|
+
ни в ESLint, и дать воспроизводимый план их подключения с JSX-парсером. Настоящая
|
|
9
|
+
правка — **только документация**; `tsconfig.json`, `eslint.config.mjs` и код не
|
|
10
|
+
изменяются.
|
|
11
|
+
|
|
12
|
+
## 1. Фактическое состояние (что и где настроено)
|
|
13
|
+
|
|
14
|
+
### 1.1 `tsconfig.json`
|
|
15
|
+
|
|
16
|
+
- `include: ["src/**/*"]` — формально покрывает весь `src/`.
|
|
17
|
+
- `exclude: ["node_modules", "dist", "src/tui.tsx", "src/tui-v1.tsx", "src/gui.tsx"]`
|
|
18
|
+
— три JSX-файла исключены **явно, но без объяснения причины** (это и есть
|
|
19
|
+
«молчаливое исключение»).
|
|
20
|
+
- При этом компилятор *уже* настроен на JSX: `jsx: "preserve"`,
|
|
21
|
+
`jsxImportSource: "@opentui/solid"`, `resolveJsonModule: true`,
|
|
22
|
+
`declaration: true`, `module: "Node16"`, `outDir: "./dist"`.
|
|
23
|
+
То есть конфиг выглядит «готовым к JSX», из-за чего исключение выглядит
|
|
24
|
+
случайным — отсюда и возникла задача QA-A2.6.
|
|
25
|
+
|
|
26
|
+
### 1.2 `eslint.config.mjs`
|
|
27
|
+
|
|
28
|
+
- Глобальный `ignores`: `dist/`, `node_modules/`, `*.cjs`, `*.mjs`, `*.js`, `scripts/`.
|
|
29
|
+
- Рабочий блок: `files: ["src/**/*.ts"]` — glob матчит **только `.ts`**, но не
|
|
30
|
+
`.tsx`. Следовательно `src/gui.tsx`, `src/tui.tsx`, `src/tui-v1.tsx` не
|
|
31
|
+
попадают под линтер даже при том, что `parserOptions.project: "./tsconfig.json"`
|
|
32
|
+
и подключены `recommendedTypeChecked` + `stylisticTypeChecked`.
|
|
33
|
+
- Второй блок `files: ["src/core/**/*.ts"]` c локальным правилом
|
|
34
|
+
`no-any-in-catch` тоже `.tsx` не затрагивает.
|
|
35
|
+
|
|
36
|
+
Итог: файлы выпадают из обоих контуров **дважды** — через `exclude` в `tsconfig`
|
|
37
|
+
и через `files`-паттерн в ESLint.
|
|
38
|
+
|
|
39
|
+
### 1.3 Сборка и точки входа (dual-entry)
|
|
40
|
+
|
|
41
|
+
`package.json` задаёт три независимых пути сборки/загрузки:
|
|
42
|
+
|
|
43
|
+
| Экспорт |Цель | Инструмент |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| `.` | `dist/index.js` (основной плагин) | `tsc` (`npm run build`) |
|
|
46
|
+
| `./rpc` | `dist/rpc.js` | `tsc` |
|
|
47
|
+
| `./tui` | `src/tui.tsx` (сырой TSX, грузится OpenCode TUI-рантаймом) | OpenCode TUI loader |
|
|
48
|
+
| `./gui-experimental` | `gui-experimental.cjs` (один CJS-бандл в корне) | Vite, `npm run build:gui` |
|
|
49
|
+
|
|
50
|
+
`vite.config.ts` подключает официальный `gui()` из `@opencode/plugin/gui/vite`,
|
|
51
|
+
который сам подключает `vite-plugin-solid`, компилирует Solid JSX и пишет
|
|
52
|
+
`gui-experimental.cjs`. GUI-бандл, таким образом, **собирается не `tsc`**, а
|
|
53
|
+
отдельным Vite-проходом с `prepublishOnly: npm run build && npm run build:gui`.
|
|
54
|
+
|
|
55
|
+
## 2. Почему исключение существует и чем опасно «просто убрать exclude»
|
|
56
|
+
|
|
57
|
+
1. **Два разных JSX-рантайма в одном проекте.**
|
|
58
|
+
- `src/gui.tsx` использует Solid JSX: `solid-js`, `@opencode/plugin/gui`,
|
|
59
|
+
каталоги подключаются как JSON-импорты (`../locales/*.json`).
|
|
60
|
+
- `src/tui.tsx` использует OpenTUI/Solid: первая строка — директива
|
|
61
|
+
`/** @jsxImportSource @opentui/solid */`, JSX-примитивы `<box>`, `<text>`.
|
|
62
|
+
- `src/tui-v1.tsx` — V1-ветка TUI, тоже JSX.
|
|
63
|
+
Глобальный `jsxImportSource: "@opentui/solid"` в `tsconfig.json` корректен
|
|
64
|
+
для TUI, но **не для GUI**. Один `tsconfig` не может одновременно и корректно
|
|
65
|
+
типизировать оба рантайма без per-file `@jsxImportSource`-директив.
|
|
66
|
+
|
|
67
|
+
2. **`tsc` производит артефакты для Node16 ESM, а не для JSX-рантаймов.**
|
|
68
|
+
При `jsx: "preserve"` компиляция `.tsx` оставит JSX в `.jsx`-файлах в `dist/` —
|
|
69
|
+
такой файл не 실행ится загрузчиком Node16 ESM. Плюс `declaration: true`
|
|
70
|
+
сгенерирует `.d.ts` для GUI/TUI, которые в пакете не используются (GUI
|
|
71
|
+
потребляется как готовый CJS-бандл, TUI — как исходный TSX). Прямое удаление
|
|
72
|
+
из `exclude` меняет состав `dist/` и ломает `npm run build` / целостность
|
|
73
|
+
`exports` (`test-package-exports.mjs`).
|
|
74
|
+
|
|
75
|
+
3. **Отдельный Vite-бандл.** GUI собирается в `gui-experimental.cjs` через
|
|
76
|
+
`gui()`-плагин с внешними `solid-js`/`@opencode/plugin/gui`. Это отдельный
|
|
77
|
+
контур: типы GUI проверять можно, но *эмит* `tsc` для GUI не нужен и вреден.
|
|
78
|
+
|
|
79
|
+
4. **Dual-entry / загрузка сырого TSX.** `./tui` указывает прямо на
|
|
80
|
+
`src/tui.tsx`; OpenCode V2 подхватывает его как TUI-точку входа. Это
|
|
81
|
+
«рантайм-исходник», а не вход для `tsc`. Попытка перевести его в `dist/`
|
|
82
|
+
потребует менять `exports` и синхронизировать V1/V2-совместимость
|
|
83
|
+
(`docs/COMPATIBILITY.md`, `test-docs.mjs`).
|
|
84
|
+
|
|
85
|
+
5. **Typed ESLint требует присутствия файла в TS-программе.** Даже если просто
|
|
86
|
+
добавить `.tsx` в `files` ESLint, `recommendedTypeChecked` с
|
|
87
|
+
`parserOptions.project: "./tsconfig.json"` упадёт с ошибкой вида
|
|
88
|
+
*"file was not found by the project"*, пока файлы не включены в какую-либо
|
|
89
|
+
TS-программу. Поэтому ESLint и tsc должны подключаться **в связке**.
|
|
90
|
+
|
|
91
|
+
Вывод: текущее исключение — **осознанная техническая необходимость**, которая
|
|
92
|
+
до сих пор была не задокументирована. Настоящий документ делает её явной.
|
|
93
|
+
|
|
94
|
+
## 3. Решение QA-A2.6
|
|
95
|
+
|
|
96
|
+
Исключение GUI/TUI из `tsc`-сборки и из ESLint объявляется **явным и
|
|
97
|
+
обоснованным** (п. 2). Эпик QA-A2 считается закрытым в части GUI/TUI не через
|
|
98
|
+
«включить любой ценой», а через фиксацию причины и конкретный план
|
|
99
|
+
подключения (п. 4), который выполняется отдельной правкой с полными тестами.
|
|
100
|
+
|
|
101
|
+
> Важно: «полностью типизированный плагин» в контексте QA-A2 означает полную
|
|
102
|
+
> типизацию **серверного контура** (`src/**/*.ts`, собираемого `tsc` и
|
|
103
|
+
> проверяемого ESLint). GUI/TUI — отдельные рантайм-контуры со своей сборкой;
|
|
104
|
+
> их подключение к проверке типов желательно, но не должно ломать dual-entry и
|
|
105
|
+
> V1/V2-совместимость.
|
|
106
|
+
|
|
107
|
+
## 4. План подключения GUI/TUI с JSX-парсером (выполняется отдельной правкой)
|
|
108
|
+
|
|
109
|
+
### Шаг 1 — выделить отдельную TS-программу для JSX (без эмита)
|
|
110
|
+
|
|
111
|
+
Создать `tsconfig.jsx.json`, расширяющий базовый:
|
|
112
|
+
|
|
113
|
+
```jsonc
|
|
114
|
+
{
|
|
115
|
+
"extends": "./tsconfig.json",
|
|
116
|
+
"compilerOptions": {
|
|
117
|
+
"noEmit": true,
|
|
118
|
+
"declaration": false,
|
|
119
|
+
"declarationMap": false,
|
|
120
|
+
"jsx": "preserve",
|
|
121
|
+
"jsxImportSource": "@opentui/solid" // дефолт; GUI переопределит директивой
|
|
122
|
+
},
|
|
123
|
+
"include": ["src/gui.tsx", "src/tui.tsx", "src/tui-v1.tsx", "src/**/*.d.ts"],
|
|
124
|
+
"exclude": []
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- `noEmit: true` гарантирует: программа используется **только для проверки типов**,
|
|
129
|
+
`dist/` не трогается, dual-entry и Vite-бандл не затрагиваются.
|
|
130
|
+
- Базовый `tsconfig.json` остаётся со своим `exclude` — именно он управляет
|
|
131
|
+
*эмитом*; `tsconfig.jsx.json` — отдельный контур *проверки*.
|
|
132
|
+
|
|
133
|
+
### Шаг 2 — переключить JSX-рантайм на уровне файлов
|
|
134
|
+
|
|
135
|
+
- `src/tui.tsx` уже содержит `/** @jsxImportSource @opentui/solid */` — оставить.
|
|
136
|
+
- `src/tui-v1.tsx` — проверить и при необходимости добавить ту же директиву.
|
|
137
|
+
- `src/gui.tsx` — добавить `/** @jsxImportSource solid-js */` в первую строку,
|
|
138
|
+
чтобы JSX-типы разрешались из Solid, а не из OpenTUI (директива файла имеет
|
|
139
|
+
приоритет над `jsxImportSource` из `compilerOptions`).
|
|
140
|
+
- Альтернатива при желании избежать директив: `jsx: "react-jsx"` + два
|
|
141
|
+
`tsconfig` (по одному на рантайм) — сложнее, рекомендуется вариант с pragma.
|
|
142
|
+
|
|
143
|
+
### Шаг 3 — подключить ESLint к JSX-программе
|
|
144
|
+
|
|
145
|
+
Добавить в `eslint.config.mjs` блок **после** базового (до блока `src/core/**` или
|
|
146
|
+
после — порядок не важен, но блок должен быть не шире базового):
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
{
|
|
150
|
+
files: ["src/**/*.tsx"],
|
|
151
|
+
languageOptions: {
|
|
152
|
+
parserOptions: { project: "./tsconfig.jsx.json" }
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
- Отдельный `@typescript-eslint/parser` подключать не нужно: `typescript-eslint`
|
|
158
|
+
уже парсит TSX его собственным парсером (espree с TSX не справился бы).
|
|
159
|
+
- Наследованные правила (`recommendedTypeChecked`, `stylisticTypeChecked`,
|
|
160
|
+
`semi`, `quotes`, `indent`, `no-console`, `no-explicit-any: warn` и т.д.)
|
|
161
|
+
применятся к `.tsx` автоматически. При желании — добавить точечные
|
|
162
|
+
JSX-специфичные правила после стабилизации baseline.
|
|
163
|
+
- Убедиться, что `npm run lint` (`eslint src`) теперь действительно посещает
|
|
164
|
+
`.tsx` (проверить `--debug`/списком файлов), иначе явно перечислить их в
|
|
165
|
+
`files`.
|
|
166
|
+
|
|
167
|
+
### Шаг 4 — скрипты и CI
|
|
168
|
+
|
|
169
|
+
- Добавить в `package.json`:
|
|
170
|
+
- `"typecheck:jsx": "tsc -p tsconfig.jsx.json"`;
|
|
171
|
+
- `"lint:jsx": "eslint src --ext .ts,.tsx"` (или включить `.tsx` в общий
|
|
172
|
+
`npm run lint`).
|
|
173
|
+
- Добавить оба вызова в CI-воркфлоу рядом с `npm run lint` / `npm run build`.
|
|
174
|
+
- Обновить `test-docs.mjs`-связанные доки только при изменении счётчиков tools/RPC —
|
|
175
|
+
в данном плане они не меняются.
|
|
176
|
+
|
|
177
|
+
### Шаг 5 — проверки после подключения (обязательно)
|
|
178
|
+
|
|
179
|
+
- `npm run build` — убедиться, что состав `dist/` и `npm pack --dry-run` не
|
|
180
|
+
изменились; `node test-package-exports.mjs` — целостность `exports`.
|
|
181
|
+
- `npm run lint` и `npm run typecheck:jsx` — 0 ошибок; новые `any` в `.tsx`
|
|
182
|
+
разбираются по правилам QA-A2 (сужать через type guard / `z.infer`).
|
|
183
|
+
- GUI/RPC-контур (по правилам AGENTS.md): `npm run test:dlq-gui`,
|
|
184
|
+
`npm run test:pause-gui`, `npm run test:gui-bundle` + smoke в Playwright.
|
|
185
|
+
- V1/V2-совместимость и мета-гейт: `node test-docs.mjs`, `node test-workflows.mjs`.
|
|
186
|
+
- `npm run test:i18n` — `gui.tsx` инлайн-регистрирует `ru/en/zh`-каталоги;
|
|
187
|
+
типизация JSON-импортов не должна сломать паритет ключей.
|
|
188
|
+
|
|
189
|
+
### Риски и оговорки
|
|
190
|
+
|
|
191
|
+
- Добавление `.tsx` в линтер может вскрыть значительный легаси-долг в GUI/TUI;
|
|
192
|
+
чтобы не ронять CI, новые предупреждения временно держать в baseline
|
|
193
|
+
(по образцу QA-A2.0), затем «вылизывать» по QA-A2.1–A2.5.
|
|
194
|
+
- GUI-бандл (`gui-experimental.cjs`) и `dist/` — артефакты сборки, **не редактировать
|
|
195
|
+
вручную** (правило AGENTS.md).
|
|
196
|
+
- Любая правка `exports`/сборки GUI требует синхронизации `docs/COMPATIBILITY.md`
|
|
197
|
+
и повторного `node test-docs.mjs`.
|
|
198
|
+
|
|
199
|
+
## 5. Критерии приёмки QA-A2.6
|
|
200
|
+
|
|
201
|
+
- [x] Прочитаны `ROADMAP.md` (QA-A2.6), `tsconfig.json`, `eslint.config.mjs`.
|
|
202
|
+
- [x] Создан `docs/QA-A2-GUI-TUI.md` с объяснением причин исключения
|
|
203
|
+
(JSX-парсер/рантайм, отдельный Vite-бандл, dual-entry) и планом подключения.
|
|
204
|
+
- [x] `tsconfig.json`, `eslint.config.mjs` и код не изменены.
|
|
205
|
+
- [x] Коммит/push не выполнялись; суб-агенты не спавнились.
|
package/docs/README.ru.md
CHANGED
|
@@ -46,11 +46,11 @@ Translations: [English](../README.md) · [中文](README.zh.md).
|
|
|
46
46
|
| Мультирепо | workspaces с валидацией путей, запуски по workspace, матрица поверх родительской задачи |
|
|
47
47
|
| Наблюдаемость | история SQLite (success / error / timeout / partial / running), метрики (длительность, токены, стоимость), JSONL-логи с `/api/logs`, Prometheus `/metrics`, экспорт OTLP, логи по задачам, веб-дашборд с аналитикой за 14 дней, ретеншн истории и экспорт CSV/JSON |
|
|
48
48
|
| Эксплуатация | dry-run, экспорт/импорт JSON, шаблоны, уведомления по нескольким каналам (webhook, Telegram, нативные toast), тихие часы, дайджест, локальный ассистент для триажа уведомлений (fail-open, shadow-режим), зашифрованные секреты (`${secret:NAME}`), журнал аудита, настройки |
|
|
49
|
-
| Интерфейсы | панель OpenCode GUI, веб-дашборд,
|
|
49
|
+
| Интерфейсы | панель OpenCode GUI, веб-дашборд, 30 инструментов для агента, встроенный скилл |
|
|
50
50
|
|
|
51
51
|
### Язык интерфейса
|
|
52
52
|
|
|
53
|
-
Интерфейс доступен на
|
|
53
|
+
Интерфейс доступен на русском, английском и китайском (упрощённом). По умолчанию выбран режим **«Авто»** — как в OpenCode, язык интерфейса следует за языком OpenCode; русский, английский и китайский можно выбрать явно. Переключатель языка находится в шапке панели планировщика (🌐 Авто / Русский / English / 中文), а также доступен через инструмент `manage_settings` (`action: "update"`, `locale: "zh"`). Значение `locale: "auto"` («Авто», используется по умолчанию) следует за языком интерфейса OpenCode: панель реагирует на смену языка сразу, а разрешённая локаль отправляется на сервер, чтобы уведомления, дайджест и дашборд использовали тот же язык. Переключение применяется без перезапуска. Локализация дашборда ещё не завершена: часть строк на стороне клиента пока остаётся русской. Описания и схемы инструментов агента остаются английскими, диагностика в консоли — русской.
|
|
54
54
|
|
|
55
55
|
Каталоги лежат в `locales/ru.json`, `locales/en.json` и `locales/zh.json`; набор ключей в них должен совпадать, иначе CI падает.
|
|
56
56
|
|
|
@@ -106,7 +106,7 @@ npm run build && npm run build:gui
|
|
|
106
106
|
|
|
107
107
|
## Инструменты для агента
|
|
108
108
|
|
|
109
|
-
Агенту доступен весь функционал —
|
|
109
|
+
Агенту доступен весь функционал — 30 инструментов: расписание, пайплайны, эксплуатация, аналитика и администрирование.
|
|
110
110
|
|
|
111
111
|
| Инструмент | Аргументы | Что делает |
|
|
112
112
|
|---|---|---|
|
|
@@ -136,6 +136,9 @@ npm run build && npm run build:gui
|
|
|
136
136
|
| `manage_secrets` | `action`, `name?`, `value?` | Создание, список и удаление секретов AES-256-GCM для `env` задач |
|
|
137
137
|
| `get_audit_log` | `action?`, `target?`, `actor?`, `since?`, `until?`, `limit?` | Журнал мутаций: кто, что и когда изменил и через какой интерфейс |
|
|
138
138
|
| `emit_event` | `eventName`, `payload?` | Запуск задач, подписанных на MCP-событие |
|
|
139
|
+
| `pipeline_validate` | `path?`, `source?` | Проверяет `opencode.pipeline.yaml`, не меняя задачи |
|
|
140
|
+
| `pipeline_apply` | `path?`, `source?`, `dryRun?` | Идемпотентно создаёт и обновляет задачи конвейера; `dryRun` только показывает diff |
|
|
141
|
+
| `pipeline_export` | `pipeline` | Выгружает задачи конвейера обратно в YAML |
|
|
139
142
|
|
|
140
143
|
`schedule_task` принимает и полную конфигурацию матрицы (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
|
|
141
144
|
|
|
@@ -182,6 +185,41 @@ npm run build && npm run build:gui
|
|
|
182
185
|
|
|
183
186
|
Каждый workspace получает клон `<parent>-matrix-<workspace>`. Родительская задача сама не выполняется: она агрегирует результаты клонов в `success`, `error` или `partial`. Клоны синхронизируются с родителем при его изменении; запущенные клоны не затрагиваются.
|
|
184
187
|
|
|
188
|
+
## Pipeline как код
|
|
189
|
+
|
|
190
|
+
Опишите весь конвейер одним файлом `opencode.pipeline.yaml`, вместо того чтобы создавать задачи по одной:
|
|
191
|
+
|
|
192
|
+
```yaml
|
|
193
|
+
version: 1
|
|
194
|
+
name: nightly-release
|
|
195
|
+
defaults:
|
|
196
|
+
retryCount: 1
|
|
197
|
+
retryDelay: 120
|
|
198
|
+
steps:
|
|
199
|
+
- id: lint
|
|
200
|
+
schedule: "0 2 * * *"
|
|
201
|
+
prompt: Запусти линтер и исправь найденные проблемы.
|
|
202
|
+
qualityGate: npm run lint
|
|
203
|
+
- id: test
|
|
204
|
+
needs: [lint]
|
|
205
|
+
trigger: dag
|
|
206
|
+
prompt: Запусти тесты и исправь падения.
|
|
207
|
+
qualityGate: npm test
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
`needs` превращается в DAG-зависимость, шаг с `trigger: dag` запускается только после успеха зависимостей, а `defaults` наследуются всеми шагами. Каждый шаг становится задачей с именем `<pipeline> <step>`.
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
agent-steward pipeline validate opencode.pipeline.yaml
|
|
214
|
+
agent-steward pipeline apply opencode.pipeline.yaml --dry-run
|
|
215
|
+
agent-steward pipeline apply opencode.pipeline.yaml
|
|
216
|
+
agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Apply идемпотентен: неизменённые шаги пропускаются, изменённые обновляются, а задачи вне конвейера не затрагиваются. Шаги, удалённые из файла, помечаются как устаревшие, но не удаляются. Агенту доступны те же операции через `pipeline_validate`, `pipeline_apply` и `pipeline_export`.
|
|
220
|
+
|
|
221
|
+
Полный формат, матрица, правила валидации и ограничения — в [docs/PIPELINE.md](PIPELINE.md); готовый пример — [opencode.pipeline.yaml](../opencode.pipeline.yaml).
|
|
222
|
+
|
|
185
223
|
## GUI и дашборд
|
|
186
224
|
|
|
187
225
|
В боковой панели OpenCode доступны задачи, история, логи, dry-run, шаблоны, импорт/экспорт, лимит конкурентности и группировка матриц. Локальный веб-дашборд добавляет сводку по workspace, вкладки матриц, вид пайплайна и метрики.
|
|
@@ -224,7 +262,7 @@ src/
|
|
|
224
262
|
npm install
|
|
225
263
|
npm run build # tsc
|
|
226
264
|
npm run build:gui # vite
|
|
227
|
-
npm test #
|
|
265
|
+
npm test # 115 сюит, 600+ проверок
|
|
228
266
|
npm run test:en # те же сюиты с английской локалью
|
|
229
267
|
```
|
|
230
268
|
|
|
@@ -239,6 +277,7 @@ npm run test:en # те же сюиты с английской локаль
|
|
|
239
277
|
- [FEATURES.md](FEATURES.md) — полный каталог возможностей с примерами.
|
|
240
278
|
- [FAQ.md](FAQ.md) — сценарии восстановления и ответы по эксплуатации (English).
|
|
241
279
|
- [MIGRATION.md](MIGRATION.md) — переезд с cron, systemd, launchd или Планировщика Windows.
|
|
280
|
+
- [PIPELINE.md](PIPELINE.md) — конвейер как код: формат, CLI, идемпотентный apply.
|
|
242
281
|
- [SAVINGS.md](SAVINGS.md) — как считается оценка «Сэкономлено $» (English).
|
|
243
282
|
- [../CROSS_PLATFORM.md](../CROSS_PLATFORM.md) — различия и бэкенды Windows / macOS / Linux.
|
|
244
283
|
|