opencode-windows-scheduler 0.0.0-stage → 1.0.0

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.
Files changed (172) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/CROSS_PLATFORM.md +113 -0
  3. package/LICENSE +21 -0
  4. package/README.md +173 -2
  5. package/README.ru.md +131 -0
  6. package/ROADMAP-STRATEGY.md +217 -0
  7. package/ROADMAP.md +87 -0
  8. package/dist/core/cron-to-schtasks.d.ts +20 -0
  9. package/dist/core/cron-to-schtasks.d.ts.map +1 -0
  10. package/dist/core/cron-to-schtasks.js +233 -0
  11. package/dist/core/dry-run.d.ts +44 -0
  12. package/dist/core/dry-run.d.ts.map +1 -0
  13. package/dist/core/dry-run.js +252 -0
  14. package/dist/core/file-watcher.d.ts +31 -0
  15. package/dist/core/file-watcher.d.ts.map +1 -0
  16. package/dist/core/file-watcher.js +128 -0
  17. package/dist/core/lock.d.ts +43 -0
  18. package/dist/core/lock.d.ts.map +1 -0
  19. package/dist/core/lock.js +118 -0
  20. package/dist/core/matrix.d.ts +167 -0
  21. package/dist/core/matrix.d.ts.map +1 -0
  22. package/dist/core/matrix.js +687 -0
  23. package/dist/core/ps-wrapper.d.ts +60 -0
  24. package/dist/core/ps-wrapper.d.ts.map +1 -0
  25. package/dist/core/ps-wrapper.js +538 -0
  26. package/dist/core/record-history.d.ts +14 -0
  27. package/dist/core/record-history.d.ts.map +1 -0
  28. package/dist/core/record-history.js +360 -0
  29. package/dist/core/scheduler/index.d.ts +20 -0
  30. package/dist/core/scheduler/index.d.ts.map +1 -0
  31. package/dist/core/scheduler/index.js +32 -0
  32. package/dist/core/scheduler/linux.d.ts +32 -0
  33. package/dist/core/scheduler/linux.d.ts.map +1 -0
  34. package/dist/core/scheduler/linux.js +115 -0
  35. package/dist/core/scheduler/logs.d.ts +11 -0
  36. package/dist/core/scheduler/logs.d.ts.map +1 -0
  37. package/dist/core/scheduler/logs.js +34 -0
  38. package/dist/core/scheduler/mac.d.ts +39 -0
  39. package/dist/core/scheduler/mac.d.ts.map +1 -0
  40. package/dist/core/scheduler/mac.js +175 -0
  41. package/dist/core/scheduler/posix.d.ts +40 -0
  42. package/dist/core/scheduler/posix.d.ts.map +1 -0
  43. package/dist/core/scheduler/posix.js +86 -0
  44. package/dist/core/scheduler/registry.d.ts +36 -0
  45. package/dist/core/scheduler/registry.d.ts.map +1 -0
  46. package/dist/core/scheduler/registry.js +56 -0
  47. package/dist/core/scheduler/types.d.ts +63 -0
  48. package/dist/core/scheduler/types.d.ts.map +1 -0
  49. package/dist/core/scheduler/types.js +1 -0
  50. package/dist/core/scheduler/windows.d.ts +47 -0
  51. package/dist/core/scheduler/windows.d.ts.map +1 -0
  52. package/dist/core/scheduler/windows.js +375 -0
  53. package/dist/core/wrappers/bash.d.ts +58 -0
  54. package/dist/core/wrappers/bash.d.ts.map +1 -0
  55. package/dist/core/wrappers/bash.js +223 -0
  56. package/dist/db/history-repo.d.ts +69 -0
  57. package/dist/db/history-repo.d.ts.map +1 -0
  58. package/dist/db/history-repo.js +150 -0
  59. package/dist/db/index.d.ts +47 -0
  60. package/dist/db/index.d.ts.map +1 -0
  61. package/dist/db/index.js +120 -0
  62. package/dist/db/metrics-repo.d.ts +43 -0
  63. package/dist/db/metrics-repo.d.ts.map +1 -0
  64. package/dist/db/metrics-repo.js +95 -0
  65. package/dist/db/migrate.d.ts +24 -0
  66. package/dist/db/migrate.d.ts.map +1 -0
  67. package/dist/db/migrate.js +237 -0
  68. package/dist/db/recovery.d.ts +11 -0
  69. package/dist/db/recovery.d.ts.map +1 -0
  70. package/dist/db/recovery.js +38 -0
  71. package/dist/db/schema.d.ts +24 -0
  72. package/dist/db/schema.d.ts.map +1 -0
  73. package/dist/db/schema.js +97 -0
  74. package/dist/db/settings-repo.d.ts +8 -0
  75. package/dist/db/settings-repo.d.ts.map +1 -0
  76. package/dist/db/settings-repo.js +27 -0
  77. package/dist/db/tasks-repo.d.ts +26 -0
  78. package/dist/db/tasks-repo.d.ts.map +1 -0
  79. package/dist/db/tasks-repo.js +120 -0
  80. package/dist/db/templates-repo.d.ts +17 -0
  81. package/dist/db/templates-repo.d.ts.map +1 -0
  82. package/dist/db/templates-repo.js +57 -0
  83. package/dist/gui-experimental.cjs +1 -0
  84. package/dist/history.d.ts +53 -0
  85. package/dist/history.d.ts.map +1 -0
  86. package/dist/history.js +57 -0
  87. package/dist/index.d.ts +156 -0
  88. package/dist/index.d.ts.map +1 -0
  89. package/dist/index.js +2077 -0
  90. package/dist/notifications.d.ts +45 -0
  91. package/dist/notifications.d.ts.map +1 -0
  92. package/dist/notifications.js +135 -0
  93. package/dist/rpc.d.ts +2052 -0
  94. package/dist/rpc.d.ts.map +1 -0
  95. package/dist/rpc.js +863 -0
  96. package/dist/schtasks.d.ts +32 -0
  97. package/dist/schtasks.d.ts.map +1 -0
  98. package/dist/schtasks.js +45 -0
  99. package/dist/server.d.ts +106 -0
  100. package/dist/server.d.ts.map +1 -0
  101. package/dist/server.js +1478 -0
  102. package/dist/settings.d.ts +43 -0
  103. package/dist/settings.d.ts.map +1 -0
  104. package/dist/settings.js +96 -0
  105. package/dist/shared/jobs-view.d.ts +21 -0
  106. package/dist/shared/jobs-view.d.ts.map +1 -0
  107. package/dist/shared/jobs-view.js +28 -0
  108. package/dist/skill.d.ts +15 -0
  109. package/dist/skill.d.ts.map +1 -0
  110. package/dist/skill.js +93 -0
  111. package/dist/task-transfer.d.ts +176 -0
  112. package/dist/task-transfer.d.ts.map +1 -0
  113. package/dist/task-transfer.js +442 -0
  114. package/dist/templates.d.ts +57 -0
  115. package/dist/templates.d.ts.map +1 -0
  116. package/dist/templates.js +16 -0
  117. package/dist/types.d.ts +78 -0
  118. package/dist/types.d.ts.map +1 -0
  119. package/dist/types.js +88 -0
  120. package/dist/workspaces.d.ts +55 -0
  121. package/dist/workspaces.d.ts.map +1 -0
  122. package/dist/workspaces.js +183 -0
  123. package/docs/ARCHITECTURE.md +302 -0
  124. package/docs/FEATURES.md +288 -0
  125. package/docs/MIGRATION.md +266 -0
  126. package/docs/dashboard.png +0 -0
  127. package/gui-experimental.cjs +2 -0
  128. package/index.js +1 -0
  129. package/package.json +92 -4
  130. package/scripts/demo-dashboard.mjs +199 -0
  131. package/skills/scheduled-job-best-practices/SKILL.md +155 -0
  132. package/skills/scheduled-job-best-practices/references/recipes.md +123 -0
  133. package/src/core/cron-to-schtasks.ts +269 -0
  134. package/src/core/dry-run.ts +315 -0
  135. package/src/core/file-watcher.ts +171 -0
  136. package/src/core/lock.ts +134 -0
  137. package/src/core/matrix.ts +907 -0
  138. package/src/core/ps-wrapper.ts +572 -0
  139. package/src/core/record-history.ts +493 -0
  140. package/src/core/scheduler/index.ts +44 -0
  141. package/src/core/scheduler/linux.ts +125 -0
  142. package/src/core/scheduler/logs.ts +37 -0
  143. package/src/core/scheduler/mac.ts +222 -0
  144. package/src/core/scheduler/posix.ts +111 -0
  145. package/src/core/scheduler/registry.ts +93 -0
  146. package/src/core/scheduler/types.ts +67 -0
  147. package/src/core/scheduler/windows.ts +469 -0
  148. package/src/core/wrappers/bash.ts +282 -0
  149. package/src/db/history-repo.ts +303 -0
  150. package/src/db/index.ts +166 -0
  151. package/src/db/metrics-repo.ts +158 -0
  152. package/src/db/migrate.ts +322 -0
  153. package/src/db/recovery.ts +46 -0
  154. package/src/db/schema.ts +109 -0
  155. package/src/db/settings-repo.ts +31 -0
  156. package/src/db/tasks-repo.ts +162 -0
  157. package/src/db/templates-repo.ts +77 -0
  158. package/src/gui.tsx +2725 -0
  159. package/src/history.ts +107 -0
  160. package/src/index.ts +2672 -0
  161. package/src/notifications.ts +174 -0
  162. package/src/rpc.ts +933 -0
  163. package/src/schtasks.ts +75 -0
  164. package/src/server.ts +1663 -0
  165. package/src/settings.ts +157 -0
  166. package/src/shared/jobs-view.ts +38 -0
  167. package/src/skill.ts +113 -0
  168. package/src/task-transfer.ts +648 -0
  169. package/src/templates.ts +67 -0
  170. package/src/tui.tsx +46 -0
  171. package/src/types.ts +145 -0
  172. package/src/workspaces.ts +236 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows [Semantic Versioning](https://semver.org/).
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Added
8
+
9
+ - **Full agent parity:** `schedule_task` now accepts `qualityGate`, `dependsOn`, `retryCount`, `retryDelay`, `nextTaskOnSuccess`, `nextTaskOnError` and the complete matrix configuration (`concurrency`, `overrides`).
10
+ - **New agent tools:** `update_task` (partial update, `matrix: null` removes the matrix), `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`, `manage_workspaces` (list/add/update/delete) and `matrix_control` (results/cancel/cleanup). 12 tools total.
11
+ - Agent tool descriptions are in English; runtime messages stay localized.
12
+ - `get_task_logs` supports a `lines` limit (1–1000).
13
+ - `update_task` keeps every field that is not passed, so the agent can change one setting without resending the whole task.
14
+ - **Built-in agent skill** `scheduled-job-best-practices`, registered by the plugin itself: guidance on schedule design, prompt structure, safety defaults, matrix concurrency, DAG rules and failure diagnosis, plus `references/recipes.md` with seven complete examples. No manual `.opencode/skills` setup.
15
+ - **Documentation:** `docs/ARCHITECTURE.md` (process model, modules, backends, data model, security model), `docs/FEATURES.md` (full feature catalog with examples and limits) and `docs/MIGRATION.md` (from cron, systemd timers, launchd and Windows Task Scheduler), linked from both READMEs.
16
+ - `test-docs.mjs` — 30 checks that the guides exist, stay complete and ship in the npm package.
17
+
18
+ ### Planned
19
+
20
+ - One-shot scheduling, session continuity, guards, worktree isolation, declarative job files.
21
+
22
+ ## [1.0.0] — 2026-11-13
23
+
24
+ First public release.
25
+
26
+ ### Added
27
+
28
+ - **Scheduling:** cron expressions registered with the native OS scheduler (Windows Task Scheduler, launchd, crontab), pause/resume, timeouts with hard kill, retries with delay, lock-file no-overlap protection.
29
+ - **Quality and lifecycle:** Quality Gate command, before/after scripts, allowed/denied tool lists, crash recovery for interrupted runs.
30
+ - **Orchestration:** `dependsOn` DAG, `nextTaskOnSuccess` / `nextTaskOnError` chains, file and MCP event triggers.
31
+ - **Matrix builds:** fan-out into `<parent>-matrix-<workspace>` clones, parallel/sequential strategies, `continue`/`stop` failure modes, per-matrix concurrency, per-workspace overrides, aggregator task, family sync on edit, cascade delete, cancel, orphan cleanup, `partial` status.
32
+ - **Workspaces:** multi-repo registry with path validation, per-task working directory and tool scoping.
33
+ - **Observability:** SQLite history and metrics, per-task logs, local web dashboard with pipeline view, matrix grouping and workspace summaries.
34
+ - **Operations:** dry-run preview, export/import JSON, templates, webhook notifications, settings.
35
+ - **Interfaces:** OpenCode sidebar GUI, web dashboard, agent tools `schedule_task`, `list_tasks`, `delete_task`, `run_task_now`.
36
+ - **Cross-platform:** scheduler abstraction with Windows, Linux and macOS backends.
37
+
38
+ ### Known limitations
39
+
40
+ - Matrix parents are started by `runMatrix()` / DAG only; they are not cron-scheduled.
41
+ - Deleting a matrix parent deletes its family, but deleting a workspace does not touch existing matrix jobs.
42
+ - Agent tools cover a subset of the RPC surface (see roadmap item 0.4).
43
+
44
+ [Unreleased]: https://github.com/DeadSno/opencode-windows-scheduler/compare/v1.0.0...HEAD
45
+ [1.0.0]: https://github.com/DeadSno/opencode-windows-scheduler/releases/tag/v1.0.0
@@ -0,0 +1,113 @@
1
+ # Кроссплатформенность: Windows → macOS → Linux
2
+
3
+ Плагин больше не привязан к `schtasks`. Планировщик вынесен в абстрактный слой с тремя реализациями,
4
+ а обёртки запуска генерируются под целевую ОС.
5
+
6
+ ## Архитектура
7
+
8
+ ```
9
+ src/
10
+ index.ts # инструменты, RPC, жизненный цикл плагина
11
+ gui.tsx # панель GUI (заголовок берётся из RPC)
12
+ server.ts # веб-дашборд (заголовок динамический)
13
+ core/
14
+ scheduler/
15
+ types.ts # SchedulerBackend, CreateTaskOptions, RunTaskResult
16
+ index.ts # фабрика createSchedulerBackend() + getSchedulerTitle()
17
+ windows.ts # WindowsScheduler (schtasks)
18
+ linux.ts # LinuxScheduler (crontab)
19
+ mac.ts # MacScheduler (launchd / LaunchAgents)
20
+ posix.ts # общая база для Linux/macOS (реестр задач)
21
+ registry.ts # персистентный реестр задач POSIX-бэкендов
22
+ logs.ts # чтение логов задач (кроссплатформенно)
23
+ wrappers/
24
+ bash.ts # генератор .sh-обёрток для Linux/macOS
25
+ ps-wrapper.ts # .ps1/.cmd-обёртки для Windows (как раньше)
26
+ record-history.ts # метрики/история + retry/цепочки (через бэкенд)
27
+ cron-to-schtasks.ts # cron → schtasks (только Windows)
28
+ ```
29
+
30
+ ### Интерфейс
31
+
32
+ ```ts
33
+ interface SchedulerBackend {
34
+ readonly platform: NodeJS.Platform;
35
+ readonly title: string; // «Планировщик Windows» / «OpenCode Scheduler»
36
+ createTask(options: CreateTaskOptions): Promise<void>;
37
+ deleteTask(name: string): Promise<void>;
38
+ runTask(name: string): Promise<RunTaskResult>;
39
+ listTasks(): Promise<ScheduledTaskInfo[]>;
40
+ pauseTask(name: string): Promise<void>;
41
+ resumeTask(name: string): Promise<void>;
42
+ }
43
+ ```
44
+
45
+ Фабрика выбирает реализацию по `process.platform`:
46
+ `win32 → WindowsScheduler`, `darwin → MacScheduler`, остальные → `LinuxScheduler`.
47
+
48
+ ## Как работает каждая ОС
49
+
50
+ ### Windows (поведение не изменилось)
51
+ - Задачи регистрируются в Планировщике Windows через `schtasks` в папке `\OpenCode\windows-scheduler\`.
52
+ - Обёртка: `run-task.ps1` + персональный `run-<name>.cmd` в `%APPDATA%\opencode\windows-scheduler\wrapper`.
53
+ - Логи: `%APPDATA%\opencode\windows-scheduler\logs\<name>.log`.
54
+ - cron конвертируется в schtasks (`convertCronToSchTasks`) — поддерживается тот же набор шаблонов.
55
+
56
+ ### Linux
57
+ - Задачи живут в управляемом блоке `crontab`:
58
+ ```
59
+ # >>> opencode-scheduler >>>
60
+ # task: my-task
61
+ */5 * * * * /bin/bash '/…/wrapper/run-my-task.sh' >> '/…/logs/my-task.log' 2>&1
62
+ # <<< opencode-scheduler <<<
63
+ ```
64
+ - Пауза = строка с префиксом `# PAUSED: ` (блок пересобирается из реестра).
65
+ - Задачи с триггером `file` в crontab не попадают — их запускает FileWatchManager плагина.
66
+ - Обёртка: `~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh` (chmod 0755).
67
+ - Полный cron-синтаксис (в отличие от Windows), т.к. crontab понимает его нативно.
68
+ - Удаление/пересборка — только своего блока, остальные строки `crontab` не трогаются.
69
+
70
+ ### macOS
71
+ - Задачи — LaunchAgent-плисты `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
72
+ - Расписание: `StartInterval` для `* * * * *` и `*/N`, `StartCalendarInterval` для `M * * * *`,
73
+ `M H * * *`, `M H * * D`.
74
+ - Пауза = `launchctl unload -w`, возобновление = `launchctl load -w`.
75
+ - Обёртка — тот же `.sh`, что и на Linux; пути конфигов:
76
+ `~/.config/opencode/windows-scheduler/` (или `$XDG_CONFIG_HOME`).
77
+
78
+ ### Общая POSIX-обёртка (`.sh`)
79
+ - `cd` в рабочую директорию, `opencode run` с промптом из файла.
80
+ - Логи пишутся в файл через `>>` и дублируются метками времени.
81
+ - Блокировка через атомарный `mkdir` — защита от параллельных запусков.
82
+ - Таймаут: дочерний процесс + watchdog (`TERM`, затем `KILL`).
83
+ - Quality Gate: `bash -lc "<команда>"` (аналог `cmd.exe /c` на Windows).
84
+ - Метрики: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
85
+ тот же контракт, что и в PowerShell-обёртке, поэтому история/метрики/retry/цепочки работают везде.
86
+ - `PATH` дополняется `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.bun/bin`.
87
+
88
+ ## GUI и дашборд
89
+ - Заголовок динамический: на Windows — «Планировщик Windows», на macOS/Linux — «OpenCode Scheduler».
90
+ - Источник заголовка — новый RPC-метод `get_platform` → `{ platform, title }`.
91
+ - Заголовок используется и в панели GUI, и в fallback-панели ошибки, и в `<title>/<h1>` веб-дашборда.
92
+ - Кнопки, статусы, таблица, DAG и метрики не зависят от ОС.
93
+ - Описания инструментов (`schedule_task` и др.) подставляют актуальное название планировщика.
94
+
95
+ ## Сборка и проверки
96
+ - `npm run build` — OK, ошибок нет.
97
+ - `npm run build:gui` — OK (`gui-experimental.cjs`, ~47.7 kB).
98
+ - Проверено в runtime:
99
+ - заголовки для win32/darwin/linux;
100
+ - `cronToLaunchdSchedule` на нескольких выражениях;
101
+ - живой `listTasks()` на Windows — задачи возвращаются короткими именами (без префикса);
102
+ - экранирование `shellQuote` (кавычки, пробелы, кириллица);
103
+ - импорт `dist/index.js` проходит, `dist` не тянет `schtasks.js` напрямую.
104
+
105
+ ## Ограничения и что проверить на реальных машинах
106
+ 1. `.sh`-обёртки и crontab/launchd **не исполнялись** — на текущей Windows-машине нет `bash`/WSL.
107
+ Синтаксис и экранирование проверены вручную; нужен прогон на Linux и macOS.
108
+ 2. cron → launchd поддерживает тот же ограниченный набор шаблонов, что и Windows
109
+ (`* * * * *`, `*/N * * * *`, `M * * * *`, `M H * * *`, `M H * * D`).
110
+ На Linux доступен полный cron.
111
+ 3. Префикс задач Windows (`\OpenCode\windows-scheduler\`) и id плагина сохранены для обратной совместимости.
112
+ 4. `src/schtasks.ts` оставлен как тонкий shim для старых скриптов (`test-create.cjs`, `test-run.cjs`),
113
+ вся логика теперь в `core/scheduler/windows.ts`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 opencode-windows-scheduler contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,174 @@
1
- # Temporary Holding Version
1
+ # opencode-windows-scheduler
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Local-first orchestration for AI agent jobs in OpenCode v2 — cron, DAG pipelines, matrix fan-out, quality gates and observability. Free and open source (MIT).
4
+
5
+ [![CI](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml)
6
+ [![npm](https://img.shields.io/npm/v/opencode-windows-scheduler.svg)](https://www.npmjs.com/package/opencode-windows-scheduler)
7
+ [![license](https://img.shields.io/npm/l/opencode-windows-scheduler.svg)](LICENSE)
8
+ [![node](https://img.shields.io/node/v/opencode-windows-scheduler.svg)](package.json)
9
+
10
+ Русская версия: [README.ru.md](README.ru.md).
11
+
12
+ ---
13
+
14
+ ## Why
15
+
16
+ Most schedulers for AI agents are cron wrappers: they run a prompt on a timer and write a log file. This plugin treats agent jobs as **workflows**:
17
+
18
+ - **DAG pipelines** — a job waits for its dependencies, chains on success/error.
19
+ - **Matrix builds** — one template, N repositories, parallel or sequential, with concurrency limits and per-workspace overrides.
20
+ - **Quality gates** — a job is marked successful only if `npm test` (or any command) passes.
21
+ - **Observability** — SQLite history, metrics, logs, and a local web dashboard.
22
+ - **Runs without OpenCode open** - jobs are registered with the native OS scheduler (Windows Task Scheduler, launchd, crontab) and survive reboots.
23
+
24
+ Everything runs on your machine. No SaaS, no telemetry, no accounts.
25
+
26
+ ![Local web dashboard: matrix builds, DAG graph, metrics and run history](docs/dashboard.png)
27
+
28
+ Want to see it without installing OpenCode? `node scripts/demo-dashboard.mjs` starts the dashboard with demo data at http://localhost:4380.
29
+
30
+ ## Features
31
+
32
+ | Area | What you get |
33
+ |---|---|
34
+ | Scheduling | cron expressions, native OS scheduler (Windows / macOS / Linux), timezone-free local time, pause/resume |
35
+ | Reliability | lock-file no-overlap protection, timeouts with hard kill, retries with delay, crash recovery |
36
+ | Quality | Quality Gate command, before/after hooks, per-task allowed/denied tool lists |
37
+ | Orchestration | `dependsOn` DAG, `nextTaskOnSuccess` / `nextTaskOnError` chains, matrix fan-out (parallel/sequential, `continue`/`stop`, concurrency, per-workspace overrides, aggregator task) |
38
+ | Triggers | cron, file change (chokidar), MCP events |
39
+ | Multi-repo | workspaces with path validation, per-workspace runs, matrix over one parent task |
40
+ | Observability | SQLite history (success / error / timeout / partial / running), metrics (duration, tokens, cost), per-task logs, local web dashboard |
41
+ | Operations | dry-run preview, export/import JSON, templates, webhook notifications, settings |
42
+ | Interfaces | OpenCode GUI panel, web dashboard, 12 agent tools, built-in agent skill |
43
+
44
+ ## Install
45
+
46
+ Requires OpenCode v2 and Node.js 20+.
47
+
48
+ ```bash
49
+ npm install -g opencode-windows-scheduler
50
+ ```
51
+
52
+ Add the plugin to `opencode.jsonc`:
53
+
54
+ ```jsonc
55
+ {
56
+ "plugin": ["opencode-windows-scheduler"],
57
+ "experimental": {
58
+ "schedules": false
59
+ }
60
+ }
61
+ ```
62
+
63
+ `experimental.schedules: false` disables the built-in OpenCode scheduler so the agent does not confuse built-in job tools with this plugin's tools. Restart OpenCode after changing the config.
64
+
65
+ From source:
66
+
67
+ ```bash
68
+ git clone https://github.com/DeadSno/opencode-windows-scheduler.git
69
+ cd opencode-windows-scheduler
70
+ npm install
71
+ npm run build && npm run build:gui
72
+ ```
73
+
74
+ ## Agent tools
75
+
76
+ The agent gets the full feature set — 12 tools covering scheduling, pipelines, operations and observability:
77
+
78
+ | Tool | Arguments | What it does |
79
+ |---|---|---|
80
+ | `schedule_task` | `name`, `schedule`, `prompt`, optional `timeoutSeconds`, `model`, `priority`, `beforeScript`, `afterScript`, `qualityGate`, `dependsOn`, `retryCount`, `retryDelay`, `nextTaskOnSuccess`, `nextTaskOnError`, `triggerType`, `mcpEvent`, `workingDirectory`, `workspaceId`, `allowedTools`, `deniedTools`, `matrix` | Registers a job with the OS scheduler (cron, file or MCP-event trigger) |
81
+ | `list_tasks` | — | Returns jobs with schedule, status, next run, chains, workspace and matrix summary |
82
+ | `update_task` | `name` + any field to change | Partial update; omitted fields keep their values, empty values clear them, `matrix: null` removes the matrix |
83
+ | `delete_task` | `name` | Deletes a job (a matrix parent deletes clones and aggregator) |
84
+ | `run_task_now` | `name` | Runs a job immediately (matrix parent starts the fan-out) |
85
+ | `pause_task` | `name` | Pauses a job (matrix parent pauses every clone) |
86
+ | `resume_task` | `name` | Resumes a paused job |
87
+ | `get_history` | `taskName?`, `status?`, `limit?` | Recent runs with duration, tokens, cost, model, quality gate and hooks |
88
+ | `get_task_logs` | `name`, `lines?` | Tail of the run log |
89
+ | `dry_run` | `name?` | Simulates a pipeline (or every task): order, DAG, matrix fan-out, estimates |
90
+ | `manage_workspaces` | `action`, `id?`, `name?`, `path?`, `color?` | Multi-repo workspaces: list, add, update, delete |
91
+ | `matrix_control` | `action`, `name?` | Matrix results, cancel pending clones, clean up orphans |
92
+
93
+ `schedule_task` also accepts the full matrix configuration (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
94
+
95
+ ## Agent skill
96
+
97
+ The plugin registers a built-in skill, `scheduled-job-best-practices`, so the agent loads guidance only when it is relevant: cron design, self-contained prompts, Quality Gates, matrix concurrency, DAG rules and post-incident diagnosis. No manual `.opencode/skills` setup is needed. The skill ships with `references/recipes.md` — seven copy-ready configurations.
98
+
99
+ ## Matrix builds
100
+
101
+ ```jsonc
102
+ {
103
+ "name": "deploy",
104
+ "schedule": "0 3 * * *",
105
+ "prompt": "Build, test and deploy",
106
+ "matrix": {
107
+ "workspaceIds": ["frontend-id", "backend-id", "mobile-id"],
108
+ "strategy": "parallel",
109
+ "failureMode": "continue",
110
+ "aggregation": "summary",
111
+ "concurrency": 2,
112
+ "createAggregator": true,
113
+ "overrides": {
114
+ "mobile-id": { "qualityGate": "npm run test:mobile" }
115
+ }
116
+ }
117
+ }
118
+ ```
119
+
120
+ Each workspace gets a clone named `<parent>-matrix-<workspace>`. The parent never runs itself: it aggregates clone results into `success`, `error` or `partial`. Clones stay in sync with the parent when you edit it; running clones are never touched.
121
+
122
+ ## GUI and dashboard
123
+
124
+ The OpenCode sidebar shows jobs, history, logs, dry-run, templates, import/export, concurrency limit and matrix grouping. The local web dashboard adds per-workspace summaries, matrix tabs, a pipeline view and metrics.
125
+
126
+ ```bash
127
+ npm run build:gui # produces gui-experimental.cjs
128
+ ```
129
+
130
+ ## How it works
131
+
132
+ ```
133
+ src/
134
+ index.ts plugin lifecycle, agent tools, RPC
135
+ gui.tsx OpenCode sidebar panel
136
+ server.ts local web dashboard
137
+ core/
138
+ scheduler/ Windows / Linux / macOS backends
139
+ matrix.ts fan-out, aggregation, sync, cancel
140
+ record-history.ts history, retries, chains, matrix continuation
141
+ dry-run.ts pipeline simulation
142
+ lock.ts no-overlap protection
143
+ file-watcher.ts chokidar triggers
144
+ db/ SQLite: tasks, history, metrics, settings
145
+ task-transfer.ts export / import / validation
146
+ ```
147
+
148
+ Job wrappers run `opencode run` in the task working directory, so project MCP servers are picked up automatically.
149
+
150
+ ## Development
151
+
152
+ ```bash
153
+ npm install
154
+ npm run build # tsc
155
+ npm run build:gui # vite
156
+ npm test # 11 test suites, 200+ checks
157
+ ```
158
+
159
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
160
+
161
+ ## Documentation
162
+
163
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — process model, modules, backends, data model.
164
+ - [docs/FEATURES.md](docs/FEATURES.md) — full feature catalog with examples.
165
+ - [docs/MIGRATION.md](docs/MIGRATION.md) — moving from cron, systemd, launchd or Task Scheduler.
166
+
167
+ ## Roadmap
168
+
169
+ - [ROADMAP.md](ROADMAP.md) — sprint history and next sprints.
170
+ - [ROADMAP-STRATEGY.md](ROADMAP-STRATEGY.md) — positioning and 6-month plan.
171
+
172
+ ## License
173
+
174
+ [MIT](LICENSE).
package/README.ru.md ADDED
@@ -0,0 +1,131 @@
1
+ # opencode-windows-scheduler
2
+
3
+ > Локальная оркестрация задач AI-агентов для OpenCode v2: cron, DAG-пайплайны, матричные сборки, Quality Gate и наблюдаемость. Бесплатно и с открытым кодом (MIT).
4
+
5
+ [![CI](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml/badge.svg)](https://github.com/DeadSno/opencode-windows-scheduler/actions/workflows/ci.yml)
6
+ [![npm](https://img.shields.io/npm/v/opencode-windows-scheduler.svg)](https://www.npmjs.com/package/opencode-windows-scheduler)
7
+ [![license](https://img.shields.io/npm/l/opencode-windows-scheduler.svg)](LICENSE)
8
+
9
+ English version: [README.md](README.md).
10
+
11
+ ---
12
+
13
+ ![Локальный веб-дашборд: матричные сборки, граф DAG, метрики и история запусков](docs/dashboard.png)
14
+
15
+ Хотите посмотреть без установки OpenCode? `node scripts/demo-dashboard.mjs` поднимет дашборд с демо-данными на http://localhost:4380.
16
+
17
+ ## Зачем
18
+
19
+ Плагин для OpenCode v2: планировщик задач на нативном планировщике ОС (Планировщик Windows, launchd, crontab) с cron-расписанием, защитой от наложения запусков (lock-файл), таймаутами, повторами, Quality Gate, DAG-цепочками, матричными сборками и файловыми триггерами. Всё работает локально: без SaaS, телеметрии и аккаунтов.
20
+
21
+ ## Возможности
22
+
23
+ | Область | Что есть |
24
+ |---|---|
25
+ | Расписание | cron, нативный планировщик ОС (Windows / macOS / Linux), пауза/возобновление |
26
+ | Надёжность | lock-файл от наложения, таймауты с жёстким kill, повторы с задержкой, crash recovery |
27
+ | Качество | Quality Gate, before/after hooks, allow/deny списки инструментов |
28
+ | Оркестрация | DAG `dependsOn`, цепочки success/error, матрицы (parallel/sequential, continue/stop, concurrency, overrides, агрегатор) |
29
+ | Триггеры | cron, изменение файла (chokidar), MCP-события |
30
+ | Мультирепо | workspaces с валидацией путей, запуск по workspace, матрица поверх родительской задачи |
31
+ | Наблюдаемость | история SQLite (success / error / timeout / partial / running), метрики, логи, веб-дашборд |
32
+ | Эксплуатация | dry-run, экспорт/импорт JSON, шаблоны, webhook-уведомления, настройки |
33
+ | Интерфейсы | панель OpenCode GUI, веб-дашборд, 12 инструментов для агента, встроенный скилл |
34
+
35
+ ## Установка
36
+
37
+ Нужны OpenCode v2 и Node.js 20+.
38
+
39
+ ```bash
40
+ npm install -g opencode-windows-scheduler
41
+ ```
42
+
43
+ Добавьте плагин в `opencode.jsonc`:
44
+
45
+ ```jsonc
46
+ {
47
+ "plugin": ["opencode-windows-scheduler"],
48
+ "experimental": {
49
+ "schedules": false
50
+ }
51
+ }
52
+ ```
53
+
54
+ `experimental.schedules: false` отключает встроенный планировщик OpenCode, чтобы агент не путал встроенные инструменты расписаний с инструментами этого плагина. После изменения конфигурации перезапустите OpenCode.
55
+
56
+ Из исходников:
57
+
58
+ ```bash
59
+ git clone https://github.com/DeadSno/opencode-windows-scheduler.git
60
+ cd opencode-windows-scheduler
61
+ npm install
62
+ npm run build && npm run build:gui
63
+ ```
64
+
65
+ ## Инструменты для агента
66
+
67
+ Агенту доступен весь функционал — 12 инструментов: расписание, пайплайны, эксплуатация и наблюдаемость.
68
+
69
+ | Инструмент | Аргументы | Что делает |
70
+ |---|---|---|
71
+ | `schedule_task` | `name`, `schedule`, `prompt`, опционально `timeoutSeconds`, `model`, `priority`, `beforeScript`, `afterScript`, `qualityGate`, `dependsOn`, `retryCount`, `retryDelay`, `nextTaskOnSuccess`, `nextTaskOnError`, `triggerType`, `mcpEvent`, `workingDirectory`, `workspaceId`, `allowedTools`, `deniedTools`, `matrix` | Регистрирует задачу в планировщике ОС (cron, файл или MCP-событие) |
72
+ | `list_tasks` | — | Задачи: расписание, статус, следующее время запуска, цепочки, workspace, сводка матрицы |
73
+ | `update_task` | `name` + изменяемые поля | Частичное обновление: незаданные поля сохраняются, пустые — очищаются, `matrix: null` убирает матрицу |
74
+ | `delete_task` | `name` | Удаляет задачу (родитель матрицы — вместе с клонами и агрегатором) |
75
+ | `run_task_now` | `name` | Немедленный запуск (для матрицы — запуск fan-out) |
76
+ | `pause_task` | `name` | Пауза (для матрицы — все клоны) |
77
+ | `resume_task` | `name` | Возобновление |
78
+ | `get_history` | `taskName?`, `status?`, `limit?` | История запусков: длительность, токены, стоимость, модель, Quality Gate, хуки |
79
+ | `get_task_logs` | `name`, `lines?` | Хвост лога запуска |
80
+ | `dry_run` | `name?` | Симуляция пайплайна (или всех задач): порядок, DAG, fan-out, оценки |
81
+ | `manage_workspaces` | `action`, `id?`, `name?`, `path?`, `color?` | Multi-repo workspace: список, добавление, изменение, удаление |
82
+ | `matrix_control` | `action`, `name?` | Результаты матрицы, отмена клонов, очистка осиротевших задач |
83
+
84
+ `schedule_task` принимает и полную конфигурацию матрицы (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
85
+
86
+ ## Скилл для агента
87
+
88
+ Плагин сам регистрирует встроенный скилл `scheduled-job-best-practices`: агент подгружает инструкцию только когда она действительно нужна — проектирование cron, самодостаточные промпты, Quality Gate, лимиты матрицы, правила DAG и разбор падений. Ручная настройка `.opencode/skills` не требуется. Вместе со скиллом поставляется `references/recipes.md` — семь готовых конфигураций.
89
+
90
+ ## MCP-серверы проекта
91
+
92
+ Фоновые задачи запускаются через `opencode run` в рабочей директории задачи. По умолчанию это папка проекта, где лежит `opencode.json` / `opencode.jsonc`, поэтому MCP-серверы проекта подхватываются автоматически — отдельный мост не нужен.
93
+
94
+ - Поле **«Рабочая директория»** в GUI позволяет указать другую папку. Пустое значение = папка проекта.
95
+ - Значение сохраняется как `workingDirectory` и экспортируется вместе с задачей.
96
+ - Старое поле `workdir` читается при импорте для обратной совместимости.
97
+
98
+ ## GUI и дашборд
99
+
100
+ В боковой панели OpenCode доступны создание, редактирование, запуск, пауза, удаление задач, просмотр логов и истории, экспорт/импорт, лимит одновременных задач и зимняя тема. Локальный веб-дашборд добавляет сводку по workspace, вкладку матриц, вид пайплайна и метрики.
101
+
102
+ ```bash
103
+ npm run build:gui # gui-experimental.cjs
104
+ ```
105
+
106
+ ## Сборка и тесты
107
+
108
+ ```bash
109
+ npm run build # tsc: серверная часть плагина
110
+ npm run build:gui # vite: GUI-бандл gui-experimental.cjs
111
+ npm test # 11 сюит, 200+ проверок
112
+ ```
113
+
114
+ ## Документация
115
+
116
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — модель процессов, модули, бэкенды, модель данных.
117
+ - [docs/FEATURES.md](docs/FEATURES.md) — полный каталог возможностей с примерами.
118
+ - [docs/MIGRATION.md](docs/MIGRATION.md) — переезд с cron, systemd, launchd или Планировщика Windows.
119
+
120
+ ## Дальнейшее развитие
121
+
122
+ - [ROADMAP.md](ROADMAP.md) — история спринтов и ближайшие планы.
123
+ - [ROADMAP-STRATEGY.md](ROADMAP-STRATEGY.md) — позиционирование и горизонт 0–6 месяцев.
124
+
125
+ ## Кроссплатформенность
126
+
127
+ Архитектура и различия Windows / macOS / Linux описаны в [CROSS_PLATFORM.md](CROSS_PLATFORM.md).
128
+
129
+ ## Лицензия
130
+
131
+ [MIT](LICENSE).