docks-kit 0.20.9 → 0.21.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.
- package/AGENTS.md +11 -3
- package/README.md +15 -8
- package/cli/docs/command-guards.md +23 -6
- package/cli/docs/flags.md +11 -0
- package/cli/src/argv.ts +4 -0
- package/cli/src/commands/omp.ts +2 -1
- package/cli/src/commands/scratch.ts +75 -0
- package/cli/src/commands/tidy.ts +91 -0
- package/cli/src/engine-native/ompKitPlugin.ts +94 -0
- package/cli/src/engine-native/ompPlugins.ts +41 -8
- package/cli/src/engine-native/ompSync.ts +7 -4
- package/cli/src/engine-native/scratch.ts +188 -0
- package/cli/src/engine-native/tidy.ts +1296 -0
- package/cli/src/engine-native/tidyLock.ts +138 -0
- package/cli/src/engine-native/tidyReport.ts +509 -0
- package/cli/src/generated/sotPayload.ts +13 -5
- package/cli/src/main.ts +6 -0
- package/cli/tsconfig.json +1 -1
- package/package.json +2 -2
package/AGENTS.md
CHANGED
|
@@ -34,6 +34,9 @@ launcher can fall back to Bun source.
|
|
|
34
34
|
| `cli/src/engine-native/ompSync.ts` | omp sync orchestration and summary |
|
|
35
35
|
| `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: renders the free-model run overlay and forwards args to omp |
|
|
36
36
|
| `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render plus catalog parse and thinking-ceiling helpers |
|
|
37
|
+
| `cli/src/engine-native/scratch.ts` / `cli/src/commands/scratch.ts` | `docks-kit scratch new\|remove`: private agent temporary directories under `~/.cache/docks-kit/scratch/`; removal accepts only a real path strictly inside the scratch root, the system temporary directory, or `/var/tmp` |
|
|
38
|
+
| `cli/src/engine-native/tidy.ts` / `tidyReport.ts` / `cli/src/commands/tidy.ts` | `docks-kit tidy [--apply] [--repo <path>] [--report]`: plan and apply the safe leftover sweep (merged idle worktrees and their containers, orphaned processes in agent directories, idle scratch); Docker calls run only against a verified local endpoint (`unix:///…` or `npipe:////./pipe/…`); the report is read-only |
|
|
39
|
+
| `cli/src/engine-native/ompKitPlugin.ts` | Materializes the `SoT/.omp/plugin/` payload to `~/.docks-kit/omp-plugin` with the kit version; `ompPlugins.ts syncPlugins` links it |
|
|
37
40
|
| `cli/src/engine-native/<axis>.ts` | One change axis per file: `codexConfig`/`codexHooks`/`codexPlugins`/`codexStatus`, `claudeSettings`/`claudeRemovals`/`claudePluginPasses`/`claudeOptionalPlugins`/`claudeLsp`, `parseModifiers`/`parseHelp`, `ompFileDeploy`/`ompMarketplace`/`ompPlugins`, `skillsManifest`/`skillsLinks`/`skillsInstall`/`skillsPrune`, `engineCtx`/`syncConcurrency`/`syncDispatch`; orchestrators keep prior exports |
|
|
38
41
|
| `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags, resolved model catalog) |
|
|
39
42
|
| `cli/src/engine-native/kitDb.ts` | Only opener of the SQLite store `~/.docks-kit/kit.db`: append-only migrations, one-time `state.json` import, TTL cache |
|
|
@@ -74,7 +77,7 @@ omp SoT notes:
|
|
|
74
77
|
- `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
|
|
75
78
|
- `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`. Under a named omp profile (`OMP_PROFILE` or `PI_PROFILE`), it deploys to `<profile agentDir>/intercom/config.json`, because omp exports `PI_CODING_AGENT_DIR` as the profile agent directory.
|
|
76
79
|
- `ompFileDeploy.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards and merges `bash.patterns`.
|
|
77
|
-
- `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By the
|
|
80
|
+
- `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. By the 0.20.9 decision, omp does not prompt for other file removal: a non-denied `rm`, `git rm`, `git worktree remove`, `gio trash`, and `docks-kit scratch remove` run without a prompt. The prompts left are the history-loss commands: `git clean`, `git reset --hard`, and every `git push` form that could force. The list order is deny, then prompts, then `trash *`. omp takes the first match. `ompYaml.ts mergeBashPatterns, exception-aware rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit exception (a kit allow listed before the first kit prompt; the kit currently ships none), kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 18.11.1's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
|
|
78
81
|
- `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value. The same pass removes each `bash.patterns` rule listed in `OMP_RETIRED_BASH_RULES` (the 39 file-removal rules retired in 0.20.9). It compares with the merge's kit-rule normalization (approval case-folded, `match` whitespace collapsed), so a user rule with a different `match` or `approval` survives.
|
|
79
82
|
- `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` remains `anthropic/claude-fable-5-1:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
|
|
80
83
|
- `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.1-sol:high`. `task.maxEffort` is `xhigh`: a caller `effort: hi` outranks the role's `:high` suffix and maps to the top of the model ladder, so the cap keeps `hi` at `xhigh` instead of `max`. `advisor` is `anthropic/claude-opus-5-5:medium` with an empty fallback chain, because a GPT-6 Sol advisor looped on repeated reads under an Opus 5.5 session. Never put any GPT model (`openai-codex/gpt-*`, including GPT-6.1 Sol and GPT-6 Astra) in the advisor role or chain; Astra also costs too much for this role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-sol:xhigh` with `anthropic/claude-opus-5-5:xhigh` as its retry fallback, and all four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant. The `SoT/toolchain.json` omp floor is 18.4.4, the oldest release the kit tested with `gpt-6.1-sol`. That release lists and serves the model through the `openai-codex` provider. `cli/docs/omp-models.md` records the checks.
|
|
@@ -86,6 +89,9 @@ omp SoT notes:
|
|
|
86
89
|
- `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)`, which is 231,200 on the 272,000-token Codex window and 850,000 on the 1,000,000-token Anthropic window. The key ships as `-1` rather than being deleted because `ompYaml.ts mergeOmpConfig` is additive, so removing a key from SoT never removes it from a deployed file. `cli/docs/omp-context.md` (topic `omp-context`) carries the derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
|
|
87
90
|
- Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
|
|
88
91
|
- Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
|
|
92
|
+
- Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`: directories 0700, files 0600, `package.json` `version` set to the kit version, stale files removed, no backups because the directory is kit-owned). `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>` unless the `omp plugin list --json` npm row `docks-kit-omp` already has a `path` that resolves to that directory; `--skip-plugin-refresh` does not skip the link. The plugin extension registers `scratch_new`, `scratch_remove`, and `tidy_report`, adds a reminder after each bash command that created a resource, checks at session stop that those resources are gone, and at a main-session start claims `~/.cache/docks-kit/tidy.stamp.claim` and runs `docks-kit tidy --apply` in the background at most once per 12 hours. Every extension subprocess runs without a shell. The plugin also ships the `workspace-hygiene` skill and the `/cleanup` command. The plugin, the deployed rules, and the sweep call `docks-kit scratch` and `docks-kit tidy`, so a checkout sync must not run before the global `docks-kit` carries those commands.
|
|
93
|
+
- `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
|
|
94
|
+
- By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp prompt rules, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH or a provider CLI such as `wrangler`, `vercel`, `kubectl`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
|
|
89
95
|
- The omp CLI is upstream-owned. It updates through `omp update`, or through the external manager that owns the install, such as Tern or Nix. `omp update` refuses to run on an install that an external manager owns. Sync never installs or upgrades the CLI.
|
|
90
96
|
- `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session. The overlay sets the 16 roles in `ompOverlay.ts ROLE_ORDER`, `judge` and `memory` included, to one free model and empties the 13 retry chains in `FALLBACK_ORDER`. Every other deployed chain stays as deployed. In particular, `modelRoles.web` and `retry.fallbackChains.web` keep the deployed web-search provider order. Thus a web search that falls through the `web/*` providers can reach the paid `openai-codex/gpt-6-luna` entry. Higher-precedence model selection can replace those overlay values. It renders the overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600) and passes it through omp's repeatable `--config` flag. `ompOverlay.ts overlayFileName` gives each distinct model-and-level combination its own file, and the digest covers the selector and both levels. omp can re-read the overlay during a live session, so a second launcher with another model or level must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again. Remaining arguments forward verbatim to omp.
|
|
91
97
|
- The session model persists per machine in `~/.docks-kit/kit.db` (table `omp_session`), next to the harness selection. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. Every launch, a plain launch included, runs `omp models --json` (as `omp --profile <name> models --json` when the forwarded arguments select a profile) and checks the remembered or default model against the live free catalog. When that model is not in the catalog, the launcher stops with an error and does not start omp. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only catalog models at zero input and output cost with `pricingStatus` free or unknown.
|
|
@@ -98,7 +104,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
|
|
|
98
104
|
- **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
|
|
99
105
|
- **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `syncDispatch.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, and a missing `SoT/toolchain.json` pin stay warn-only with exit 0; an unavailable plugin inventory warns without a ledger row and falls back to the full refresh, whose failed commands are recorded. `ompMarketplace.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
|
|
100
106
|
- **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
|
|
101
|
-
- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.115` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.
|
|
107
|
+
- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.115` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.3` (inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`; 5.0.3 fixes GHSA-qxg6-89mg-rqv8 and GHSA-xp26-3454-mjgp, and is past the 5.x patch point for GHSA-82fw-gwwq-j7x9, fixed in 5.0.0-rc.2). The lockfile resolves the `vite` peer of `@vitest/mocker` to 7.3.7, which fixes the launch-editor and `server.fs.allow` advisories up to 7.3.6. `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
|
|
102
108
|
- **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
|
|
103
109
|
- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
|
|
104
110
|
- **Per-machine harness selection.** The SQLite store `~/.docks-kit/kit.db` drives a flag-less sync. A missing selection selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection. `docks-kit harnesses` is the only command that writes the `harness_selection` table. With no stored selection, its picker pre-ticks all four harnesses, `omp` included, so a new machine opts out of omp instead of opting in; nothing changes until the picker saves. The same store holds the independent `omp_session` table, which only `docks-kit omp` writes, and a TTL cache (`cache_entry`) for the live Anthropic model list and `toolchain outdated` lookups. `kitDb.ts withKitDb` is the only opener: it runs the append-only `MIGRATIONS`, imports a legacy `state.json` once and renames it to `state.json.migrated`, and refuses a store from a newer schema. Cache rows carry the kit version as fingerprint, so a new release refetches them.
|
|
@@ -177,12 +183,13 @@ The plan record is a GitHub issue. Its body starts with
|
|
|
177
183
|
`<!-- plan-contract: v4 -->`, followed by one blank line and seven `##`
|
|
178
184
|
sections. It has no frontmatter. GitHub owns the title, open-work phase, owner,
|
|
179
185
|
timestamps, and completion. The repository tracks no plan markdown.
|
|
180
|
-
|
|
186
|
+
Three skills own the workflow. `plan-workspace` maintains the workspace.
|
|
181
187
|
Main-context `plan-manager` runs six phases: decide, draft, research, plan
|
|
182
188
|
review, implement, and code review. It uses bounded repair and fresh re-review
|
|
183
189
|
in both review phases, then archives. Internal `plan-reviewer` returns one
|
|
184
190
|
readable pre-implementation verdict block per round. Two read-only reviewer
|
|
185
191
|
wrappers ship: `plan-reviewer` and `code-reviewer`.
|
|
192
|
+
The explicit-only `yolo` skill runs the same workflow and asks only before merge.
|
|
186
193
|
</constraint>
|
|
187
194
|
|
|
188
195
|
After the marker and blank line, the record carries exactly seven sections.
|
|
@@ -228,6 +235,7 @@ before it runs; when `ask` is unavailable the step is set `blocked` and the plan
|
|
|
228
235
|
reason becomes the first `## Open questions` line, `Blocked: <reason>`.
|
|
229
236
|
Persisted effects record intent only. Routine issue publication and landing
|
|
230
237
|
actions are outside the Steps table.
|
|
238
|
+
A user-invoked `yolo` run replaces these asks, the five-round stop, and the `blocked`-verdict question with the Yolo runs section of the installed `plan-lifecycle` contract.
|
|
231
239
|
|
|
232
240
|
Render a plan body verbatim only when the user names that plan and asks to see it. After a write, report the one-line header strip and the changed lines only; a write never re-renders the body.
|
|
233
241
|
|
package/README.md
CHANGED
|
@@ -64,7 +64,7 @@ EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
|
|
|
64
64
|
dry-run output, mutation snapshots, and argv logs. Its dependency graph is
|
|
65
65
|
`effect@4.0.0-rc.115` (including `effect/unstable/cli`),
|
|
66
66
|
`@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer` and
|
|
67
|
-
`BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.
|
|
67
|
+
`BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.3`
|
|
68
68
|
(inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`). `@effect/cli` and
|
|
69
69
|
`@effect/platform` are removed: neither has a 4.x release, the CLI API moved
|
|
70
70
|
into core, and the standalone platform package was unused here.
|
|
@@ -114,12 +114,19 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
|
114
114
|
policy for destructive shell commands; to remove, agents use the trash
|
|
115
115
|
(`gio trash -- <path>`, or `trash <path>` on macOS). `rm` of the home
|
|
116
116
|
directory or `/` and `HOME` reassignment are denied. omp also denies every
|
|
117
|
-
recursive `rm`
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
recursive `rm
|
|
121
|
-
omp rejects it; a Codex ask can go to its
|
|
122
|
-
per-tool differences, and gaps:
|
|
117
|
+
recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`, and runs
|
|
118
|
+
any other `rm` without a prompt. In omp, `git clean`, `git reset --hard`,
|
|
119
|
+
and any `git push` that could force ask; Claude Code and Codex also ask
|
|
120
|
+
before `find -delete`, a recursive `rm`, and every `git rm`. An omp
|
|
121
|
+
subagent cannot answer an ask, so omp rejects it; a Codex ask can go to its
|
|
122
|
+
`auto_review` reviewer. Details, per-tool differences, and gaps:
|
|
123
|
+
`docks-kit docs command-guards`.
|
|
124
|
+
- **Agent cleanup (omp)** — `docks-kit scratch` creates and removes agent
|
|
125
|
+
temporary directories with checked paths, and `docks-kit tidy` removes
|
|
126
|
+
merged idle worktrees, their containers, orphaned processes, and idle
|
|
127
|
+
scratch directories; `--report` lists other disk and memory use. The kit
|
|
128
|
+
omp plugin `docks-kit-omp` exposes these as tools, reminds the agent of
|
|
129
|
+
what it created, and runs the sweep at most once per 12 hours.
|
|
123
130
|
|
|
124
131
|
## Repository map
|
|
125
132
|
|
|
@@ -127,7 +134,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
|
127
134
|
|------|---------|
|
|
128
135
|
| `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
|
|
129
136
|
| `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
|
|
130
|
-
| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json) |
|
|
137
|
+
| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
|
|
131
138
|
| `SoT/.agents/` | Universal-skill manifest |
|
|
132
139
|
| `SoT/models.json` | Curated aliases, notes, and offline Claude/Codex fallback |
|
|
133
140
|
| `SoT/toolchain.json` | Verified-version floors |
|
|
@@ -40,10 +40,12 @@ that `eval` starts.
|
|
|
40
40
|
| Recursive `rm` (`-r`, `-R`, `-rf`, `-fr`, `-rfv`, `-ri`, `-ir`, `-Ri`, `-iR`, `--recursive`, other listed clusters) | deny, also behind any prefix (`env`, `xargs`, `nice`, `find -exec`, `git rm -r`) | ask | ask (every `rm` asks) |
|
|
41
41
|
| `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny | ask if recursive, else classifier | ask |
|
|
42
42
|
| Any other `rm`: one file, several files, a glob, `-f` | allow | glob asks; the rest goes to the classifier | ask |
|
|
43
|
-
| `find ... -delete`, `find ... -exec rm`
|
|
43
|
+
| `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask | ask (every `find` asks) |
|
|
44
44
|
| `git clean`, `git reset --hard` | ask | ask | ask |
|
|
45
45
|
| `git push` that could force: see below | ask | ask | ask (every `git push` asks) |
|
|
46
46
|
| `git rm -- <path>`, `git worktree remove -- <path>` | allow | ask | ask |
|
|
47
|
+
| `git worktree remove --force -- <path>` | allow; the omp prompt permits it once, after the commits are on the remote | ask | ask |
|
|
48
|
+
| `docks-kit scratch remove <path>` | allow; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` | no rule | no rule |
|
|
47
49
|
| Any other non-recursive `git rm` or `git worktree remove` | allow | ask | ask |
|
|
48
50
|
| `gio trash -- <path>` | allow | allow | ask |
|
|
49
51
|
| Any other `gio trash` | allow | ask with `--empty` or `--restore`; the rest goes to the classifier | ask |
|
|
@@ -84,11 +86,16 @@ it shares the `--f` prefix.
|
|
|
84
86
|
every later argument as a path, and a path such as `--empty` cannot empty
|
|
85
87
|
the trash.
|
|
86
88
|
2. `gio trash` does not trash on a system internal mount, such as a `tmpfs`
|
|
87
|
-
`/tmp`.
|
|
89
|
+
`/tmp`. In omp, remove a temporary directory with the `scratch_remove`
|
|
90
|
+
tool or `docks-kit scratch remove <path>`. In Claude Code and Codex, leave
|
|
91
|
+
a temporary file in `/tmp`; the system clears it.
|
|
88
92
|
3. To remove a path from the git index, run `git rm -- <path>`. To remove a
|
|
89
|
-
worktree, run `git worktree remove -- <path>`.
|
|
90
|
-
|
|
91
|
-
`
|
|
93
|
+
worktree, run `git worktree remove -- <path>`. In omp, when git refuses
|
|
94
|
+
because the worktree has changes, the agent may pass `--force` once, after
|
|
95
|
+
each commit is on the remote and `git status --porcelain` lists only
|
|
96
|
+
generated files. Never pass `--force` two times.
|
|
97
|
+
4. In omp, do not use `rm`. omp denies a recursive `rm`, `find -delete`,
|
|
98
|
+
`find -exec rm`, and `xargs rm`. It runs any other `rm` without a prompt.
|
|
92
99
|
5. In Claude Code and Codex, use `rm <file>` without flags only for one file
|
|
93
100
|
that the agent created.
|
|
94
101
|
6. For a recursive or bulk deletion, ask the user in the main session. A
|
|
@@ -131,6 +138,11 @@ The kit therefore denies every `rm` shape that the check can flag:
|
|
|
131
138
|
- `sudo` anywhere before `rm`;
|
|
132
139
|
- `--no-preserve-root`.
|
|
133
140
|
|
|
141
|
+
The kit also denies bulk removal through `find -delete`, `find -exec rm`, and
|
|
142
|
+
`xargs rm`. omp's critical check does not flag these forms, but they can empty
|
|
143
|
+
the home directory, and no glob can express "inside the temporary directory".
|
|
144
|
+
`docks-kit scratch remove` checks the path in code instead.
|
|
145
|
+
|
|
134
146
|
## Matching rules per tool
|
|
135
147
|
|
|
136
148
|
- **omp**:
|
|
@@ -162,7 +174,9 @@ The kit therefore denies every `rm` shape that the check can flag:
|
|
|
162
174
|
|
|
163
175
|
- **omp, literal `*`**: omp cannot match a literal `*`, so it cannot tell a
|
|
164
176
|
glob from a file name. The kit therefore runs every `rm` that it does not
|
|
165
|
-
deny without a prompt.
|
|
177
|
+
deny without a prompt. This includes `rm ~/*`, `rm $HOME/*`, and `rm /*`
|
|
178
|
+
without an `r` or `f` option, because a deny rule for them would also deny
|
|
179
|
+
`rm ~/notes.txt` (owner decision, 0.20.9).
|
|
166
180
|
- **omp, whole-line matching**: omp tests deny rules against the whole command
|
|
167
181
|
line too, so a pattern can span commands. For example, `rm x && cd ~`,
|
|
168
182
|
`rm -i a && ls -R /tmp`, and `sudo apt update && rm x` are denied. Run `rm`
|
|
@@ -176,6 +190,9 @@ The kit therefore denies every `rm` shape that the check can flag:
|
|
|
176
190
|
such as `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, or
|
|
177
191
|
`git rm -r dir`. A `* rm ` rule also matches text, so a line such as
|
|
178
192
|
`echo do not rm -rf b` is denied too.
|
|
193
|
+
- **omp, bulk-removal text**: the `* find *-delete*`, `*-exec rm *`, and
|
|
194
|
+
`*xargs rm` rules also match text, so a line such as
|
|
195
|
+
`echo use find with -delete` is denied. Write such text to a file instead.
|
|
179
196
|
- **Recursive `rm` clusters**: omp and Claude Code match only the listed
|
|
180
197
|
recursive-`rm` clusters. In omp, these are `r` or `R` alone or with `f` and
|
|
181
198
|
`v`, plus `-ri`, `-ir`, `-Ri`, and `-iR`. In Claude Code, they are `r` or `R`
|
package/cli/docs/flags.md
CHANGED
|
@@ -78,6 +78,17 @@ never reach omp:
|
|
|
78
78
|
The same names on omp stay reachable behind an explicit delimiter. Use
|
|
79
79
|
`docks-kit omp -- --help` to ask omp for help.
|
|
80
80
|
|
|
81
|
+
## `scratch` and `tidy`
|
|
82
|
+
|
|
83
|
+
| Command | Effect |
|
|
84
|
+
|------|--------|
|
|
85
|
+
| `scratch new <label>` | Create a private directory (mode 0700) `~/.cache/docks-kit/scratch/<label>-XXXXXX` and print its path; the label matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` |
|
|
86
|
+
| `scratch remove <path>...` | Remove each path whose real path is strictly inside the scratch root, the system temporary directory, or `/var/tmp`; print `removed <path>` or `refused <path>: <reason>`; exit 1 when any path is refused |
|
|
87
|
+
| `tidy` | List the safe leftover actions (`remove`, `stop`) and the kept candidates (`keep`) with reasons; change nothing |
|
|
88
|
+
| `tidy --apply` | Perform those actions under the lock `~/.cache/docks-kit/tidy.lock` and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails |
|
|
89
|
+
| `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
|
|
90
|
+
| `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
|
|
91
|
+
|
|
81
92
|
## Renamed legacy flags (pre-CLI sync.sh)
|
|
82
93
|
|
|
83
94
|
Old flags exit with a rename hint — there is no compat behavior.
|
package/cli/src/argv.ts
CHANGED
|
@@ -10,6 +10,8 @@ import { syncCommand } from "./commands/sync";
|
|
|
10
10
|
import { toolchainCommand } from "./commands/toolchain";
|
|
11
11
|
import { updateCommand } from "./commands/update";
|
|
12
12
|
import { ompCommand } from "./commands/omp";
|
|
13
|
+
import { scratchCommand } from "./commands/scratch";
|
|
14
|
+
import { tidyCommand } from "./commands/tidy";
|
|
13
15
|
import {
|
|
14
16
|
buildSurfaces,
|
|
15
17
|
normalizeArgv,
|
|
@@ -37,6 +39,8 @@ const COMMANDS: ReadonlyArray<CommandValue> = [
|
|
|
37
39
|
skillsCommand,
|
|
38
40
|
docsCommand,
|
|
39
41
|
ompCommand,
|
|
42
|
+
scratchCommand,
|
|
43
|
+
tidyCommand,
|
|
40
44
|
];
|
|
41
45
|
|
|
42
46
|
const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
|
package/cli/src/commands/omp.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { Console, Effect, Option } from "effect";
|
|
|
3
3
|
import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
|
|
4
4
|
import { bail } from "../engine";
|
|
5
5
|
import { capture, p, spawnHost, which } from "../engine-native/exec";
|
|
6
|
+
import { kitCacheDir } from "../engine-native/scratch";
|
|
6
7
|
import {
|
|
7
8
|
DEFAULT_OMP_SESSION_MODEL,
|
|
8
9
|
engineHome,
|
|
@@ -314,7 +315,7 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
|
|
|
314
315
|
// re-read the overlay during a live session. The name carries a digest of
|
|
315
316
|
// the rendered overlay, so a second launcher on another model or level
|
|
316
317
|
// cannot rewrite the file a running session still reads.
|
|
317
|
-
const directory =
|
|
318
|
+
const directory = kitCacheDir(home);
|
|
318
319
|
const overlayPath = p(directory, overlayFileName(session));
|
|
319
320
|
yield* Effect.sync(() => {
|
|
320
321
|
// `mode` applies only when mkdir creates the path, so an existing
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { tmpdir } from "node:os";
|
|
2
|
+
|
|
3
|
+
import { Argument, Command } from "effect/unstable/cli";
|
|
4
|
+
import { Console, Effect } from "effect";
|
|
5
|
+
|
|
6
|
+
import { bail } from "../engine";
|
|
7
|
+
import { engineHome } from "../engine-native/harnesses";
|
|
8
|
+
import {
|
|
9
|
+
allowedRemovalRoots,
|
|
10
|
+
createScratchDir,
|
|
11
|
+
removeTemporaryPath,
|
|
12
|
+
scratchRoot,
|
|
13
|
+
} from "../engine-native/scratch";
|
|
14
|
+
|
|
15
|
+
const action = Argument.String("action").pipe(
|
|
16
|
+
Argument.withDescription("new <label> | remove <path>..."),
|
|
17
|
+
);
|
|
18
|
+
const operands: Argument.Argument<ReadonlyArray<string>> = Argument.String("operands").pipe(
|
|
19
|
+
Argument.withDescription("The label for new, or the paths for remove"),
|
|
20
|
+
Argument.variadic(),
|
|
21
|
+
);
|
|
22
|
+
|
|
23
|
+
export const scratchCommand = Command.make("scratch", { action, operands }, (config) =>
|
|
24
|
+
Effect.gen(function* () {
|
|
25
|
+
const home = engineHome();
|
|
26
|
+
switch (config.action) {
|
|
27
|
+
case "new": {
|
|
28
|
+
const [label, ...rest] = config.operands;
|
|
29
|
+
if (label === undefined || rest.length > 0)
|
|
30
|
+
return yield* bail("scratch new needs one label");
|
|
31
|
+
let created: string;
|
|
32
|
+
try {
|
|
33
|
+
created = createScratchDir(scratchRoot(home), label);
|
|
34
|
+
} catch (cause) {
|
|
35
|
+
return yield* bail(cause instanceof Error ? cause.message : String(cause));
|
|
36
|
+
}
|
|
37
|
+
yield* Console.log(created);
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
case "remove": {
|
|
41
|
+
if (config.operands.length === 0) {
|
|
42
|
+
return yield* bail("scratch remove needs at least one path");
|
|
43
|
+
}
|
|
44
|
+
const roots = allowedRemovalRoots({
|
|
45
|
+
home,
|
|
46
|
+
scratch: scratchRoot(home),
|
|
47
|
+
tmp: tmpdir(),
|
|
48
|
+
platform: process.platform,
|
|
49
|
+
});
|
|
50
|
+
let refused = false;
|
|
51
|
+
for (const operand of config.operands) {
|
|
52
|
+
const outcome = removeTemporaryPath(operand, roots, home);
|
|
53
|
+
if (outcome.kind === "removed") {
|
|
54
|
+
yield* Console.log(`removed ${outcome.path}`);
|
|
55
|
+
} else {
|
|
56
|
+
refused = true;
|
|
57
|
+
yield* Console.log(`refused ${outcome.path}: ${outcome.reason}`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
if (refused) {
|
|
61
|
+
yield* Effect.sync(() => {
|
|
62
|
+
process.exitCode = 1;
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
default:
|
|
68
|
+
return yield* bail(`Unknown scratch action '${config.action}'; use new or remove`);
|
|
69
|
+
}
|
|
70
|
+
}),
|
|
71
|
+
).pipe(
|
|
72
|
+
Command.withDescription(
|
|
73
|
+
"Create or remove agent temporary directories; removal accepts only paths inside the scratch root, the system temporary directory, or /var/tmp.",
|
|
74
|
+
),
|
|
75
|
+
);
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { resolve } from "node:path";
|
|
2
|
+
|
|
3
|
+
import { Command, Flag } from "effect/unstable/cli";
|
|
4
|
+
import { Console, Effect, Option } from "effect";
|
|
5
|
+
|
|
6
|
+
import { bail } from "../engine";
|
|
7
|
+
import { engineHome } from "../engine-native/harnesses";
|
|
8
|
+
import { scratchRoot } from "../engine-native/scratch";
|
|
9
|
+
import {
|
|
10
|
+
actionSubject,
|
|
11
|
+
actionVerb,
|
|
12
|
+
agentWorktreeRoot,
|
|
13
|
+
applyTidy,
|
|
14
|
+
defaultTidyHost,
|
|
15
|
+
mainRepository,
|
|
16
|
+
planTidy,
|
|
17
|
+
type TidyInputs,
|
|
18
|
+
} from "../engine-native/tidy";
|
|
19
|
+
import { buildTidyReport } from "../engine-native/tidyReport";
|
|
20
|
+
|
|
21
|
+
const apply = Flag.Boolean("apply").pipe(
|
|
22
|
+
Flag.withDescription("Perform the listed actions"),
|
|
23
|
+
Flag.withDefault(false),
|
|
24
|
+
);
|
|
25
|
+
const repo = Flag.String("repo").pipe(
|
|
26
|
+
Flag.withDescription("Take worktree candidates only from this repository, at any location"),
|
|
27
|
+
Flag.optional,
|
|
28
|
+
);
|
|
29
|
+
const report = Flag.Boolean("report").pipe(
|
|
30
|
+
Flag.withDescription("Also list other disk and memory use (read-only)"),
|
|
31
|
+
Flag.withDefault(false),
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
export const tidyCommand = Command.make("tidy", { apply, repo, report }, (config) =>
|
|
35
|
+
Effect.gen(function* () {
|
|
36
|
+
const host = defaultTidyHost();
|
|
37
|
+
const home = engineHome();
|
|
38
|
+
let repository: string | undefined;
|
|
39
|
+
if (Option.isSome(config.repo)) {
|
|
40
|
+
const typed = config.repo.value;
|
|
41
|
+
repository = yield* Effect.promise(() => mainRepository(resolve(process.cwd(), typed), host));
|
|
42
|
+
if (repository === undefined) return yield* bail(`--repo ${typed} is not a git repository`);
|
|
43
|
+
}
|
|
44
|
+
const inputs: TidyInputs = {
|
|
45
|
+
home,
|
|
46
|
+
worktreeRoot: agentWorktreeRoot(home, process.env),
|
|
47
|
+
scratchRoot: scratchRoot(home),
|
|
48
|
+
...(repository === undefined ? {} : { repo: repository }),
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const plan = yield* Effect.promise(() => planTidy(inputs, host));
|
|
52
|
+
for (const action of plan.actions) {
|
|
53
|
+
yield* Console.log(`${actionVerb(action)} ${actionSubject(action)}: ${action.reason}`);
|
|
54
|
+
}
|
|
55
|
+
for (const kept of plan.kept) yield* Console.log(`keep ${kept.subject}: ${kept.reason}`);
|
|
56
|
+
for (const note of plan.notes) yield* Console.log(`note: ${note}`);
|
|
57
|
+
|
|
58
|
+
if (plan.actions.length === 0) {
|
|
59
|
+
yield* Console.log("Nothing to tidy.");
|
|
60
|
+
} else if (config.apply) {
|
|
61
|
+
const outcome = yield* Effect.promise(() => applyTidy(plan, inputs, host));
|
|
62
|
+
for (const line of outcome.lines) yield* Console.log(line);
|
|
63
|
+
if (outcome.failures > 0) {
|
|
64
|
+
yield* Effect.sync(() => {
|
|
65
|
+
process.exitCode = 1;
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
} else {
|
|
69
|
+
// In --repo mode a bare `tidy --apply` would perform a different plan.
|
|
70
|
+
const applyCommand =
|
|
71
|
+
repository === undefined
|
|
72
|
+
? "docks-kit tidy --apply"
|
|
73
|
+
: `docks-kit tidy --repo ${repository} --apply`;
|
|
74
|
+
yield* Console.log(
|
|
75
|
+
`Dry run: ${plan.actions.length} actions. Run '${applyCommand}' to perform them.`,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (config.report) {
|
|
80
|
+
const sections = yield* Effect.promise(() => buildTidyReport(inputs, host, plan.docker));
|
|
81
|
+
for (const section of sections) {
|
|
82
|
+
yield* Console.log(`== ${section.title}`);
|
|
83
|
+
for (const line of section.lines) yield* Console.log(line);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}),
|
|
87
|
+
).pipe(
|
|
88
|
+
Command.withDescription(
|
|
89
|
+
"List or remove safe agent leftovers (merged idle worktrees, their containers, orphaned processes in agent directories, idle scratch directories); --report lists other disk and memory use.",
|
|
90
|
+
),
|
|
91
|
+
);
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EngineNative omp kit plugin: writes the embedded `SoT/.omp/plugin/` package
|
|
3
|
+
* into the kit-owned directory `~/.docks-kit/omp-plugin`, which
|
|
4
|
+
* `ompPlugins.ts syncPlugins` links into omp. The kit owns the directory, so
|
|
5
|
+
* a sync replaces changed files without `.bak` copies and removes files that
|
|
6
|
+
* the payload no longer lists. Split from ompSync.ts; the orchestration still
|
|
7
|
+
* lives there.
|
|
8
|
+
*/
|
|
9
|
+
import {
|
|
10
|
+
chmodSync,
|
|
11
|
+
existsSync,
|
|
12
|
+
lstatSync,
|
|
13
|
+
readFileSync,
|
|
14
|
+
readdirSync,
|
|
15
|
+
rmdirSync,
|
|
16
|
+
unlinkSync,
|
|
17
|
+
writeFileSync,
|
|
18
|
+
} from "node:fs";
|
|
19
|
+
|
|
20
|
+
import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
|
|
21
|
+
import { payloadBytes, payloadDisplayPath, payloadPaths } from "../payload";
|
|
22
|
+
import { p } from "./exec";
|
|
23
|
+
import type { Ctx } from "./index";
|
|
24
|
+
import { ensureDirectory } from "./ompFileDeploy";
|
|
25
|
+
|
|
26
|
+
export const KIT_PLUGIN_NAME = "docks-kit-omp";
|
|
27
|
+
|
|
28
|
+
const SOURCE_PREFIX = "SoT/.omp/plugin/";
|
|
29
|
+
|
|
30
|
+
export function kitPluginDir(home: string): string {
|
|
31
|
+
return p(home, ".docks-kit", "omp-plugin");
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Removes every entry under `directory` that is not a target, then empty directories. */
|
|
35
|
+
function pruneStale(directory: string, targets: ReadonlySet<string>): boolean {
|
|
36
|
+
let changed = false;
|
|
37
|
+
for (const name of readdirSync(directory)) {
|
|
38
|
+
const entry = p(directory, name);
|
|
39
|
+
const stat = lstatSync(entry);
|
|
40
|
+
if (stat.isDirectory()) {
|
|
41
|
+
changed = pruneStale(entry, targets) || changed;
|
|
42
|
+
if (readdirSync(entry).length === 0) {
|
|
43
|
+
rmdirSync(entry);
|
|
44
|
+
changed = true;
|
|
45
|
+
}
|
|
46
|
+
} else if (!targets.has(entry)) {
|
|
47
|
+
unlinkSync(entry);
|
|
48
|
+
changed = true;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return changed;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export function syncKitPlugin(ctx: Ctx): void {
|
|
55
|
+
const { change, echo, verbose } = ctx.services.logger;
|
|
56
|
+
const pluginDir = kitPluginDir(ctx.home);
|
|
57
|
+
const files = payloadPaths(SOURCE_PREFIX).map((source) => ({
|
|
58
|
+
source,
|
|
59
|
+
target: p(pluginDir, source.slice(SOURCE_PREFIX.length)),
|
|
60
|
+
}));
|
|
61
|
+
|
|
62
|
+
if (ctx.dryRun) {
|
|
63
|
+
for (const { source, target } of files) {
|
|
64
|
+
echo(`[dry-run] cp ${payloadDisplayPath(source)} -> ${target}`);
|
|
65
|
+
}
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
let changed = false;
|
|
70
|
+
for (const { source, target } of files) {
|
|
71
|
+
let content = payloadBytes(source);
|
|
72
|
+
if (source === `${SOURCE_PREFIX}package.json`) {
|
|
73
|
+
// The SoT manifest carries a placeholder version; the kit version replaces it.
|
|
74
|
+
const manifest = JSON.parse(content.toString("utf8")) as Record<string, unknown>;
|
|
75
|
+
manifest["version"] = GENERATED_PACKAGE_VERSION;
|
|
76
|
+
content = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
|
|
77
|
+
}
|
|
78
|
+
ensureDirectory(target.slice(0, target.lastIndexOf("/")));
|
|
79
|
+
if (existsSync(target) && readFileSync(target).equals(content)) continue;
|
|
80
|
+
writeFileSync(target, content, { mode: 0o600 });
|
|
81
|
+
chmodSync(target, 0o600);
|
|
82
|
+
changed = true;
|
|
83
|
+
}
|
|
84
|
+
if (existsSync(pluginDir)) {
|
|
85
|
+
changed = pruneStale(pluginDir, new Set(files.map(({ target }) => target))) || changed;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
if (changed) {
|
|
89
|
+
change("omp kit plugin files synced");
|
|
90
|
+
ctx.nextStepTriggers.ompRestart = true;
|
|
91
|
+
} else {
|
|
92
|
+
verbose("omp kit plugin files already in sync");
|
|
93
|
+
}
|
|
94
|
+
}
|
|
@@ -1,21 +1,31 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* EngineNative omp plugin pass: marketplace-plugin install/upgrade
|
|
3
|
-
* pinned pi-intercom npm plugin
|
|
4
|
-
*
|
|
2
|
+
* EngineNative omp plugin pass: marketplace-plugin install/upgrade, the
|
|
3
|
+
* pinned pi-intercom npm plugin, and the link of the kit plugin that
|
|
4
|
+
* `ompKitPlugin.ts syncKitPlugin` writes. Split from ompSync.ts; the
|
|
5
|
+
* orchestration still lives there.
|
|
5
6
|
*/
|
|
7
|
+
import { realpathSync } from "node:fs";
|
|
8
|
+
|
|
6
9
|
import { processFailureSummary, spawnProcess } from "./exec";
|
|
7
10
|
import { recordFailure } from "./failures";
|
|
8
11
|
import type { Ctx } from "./index";
|
|
9
12
|
import { isObject, parseJson } from "./jq";
|
|
13
|
+
import { KIT_PLUGIN_NAME, kitPluginDir } from "./ompKitPlugin";
|
|
10
14
|
import { field } from "./toolchain";
|
|
11
15
|
|
|
12
16
|
const MARKETPLACE_PLUGIN_IDS = ["docks@docks", "plan-lifecycle@docks"] as const;
|
|
13
17
|
|
|
14
18
|
// -------------------------------------------------------------- plugins ----
|
|
15
19
|
|
|
20
|
+
interface InstalledNpmPlugin {
|
|
21
|
+
readonly version: string;
|
|
22
|
+
/** The `node_modules` entry of the plugin, a symbolic link for a linked plugin. */
|
|
23
|
+
readonly path: string | undefined;
|
|
24
|
+
}
|
|
25
|
+
|
|
16
26
|
interface InstalledPlugins {
|
|
17
27
|
readonly marketplace: Set<string>;
|
|
18
|
-
readonly npm: Map<string,
|
|
28
|
+
readonly npm: Map<string, InstalledNpmPlugin>;
|
|
19
29
|
}
|
|
20
30
|
|
|
21
31
|
async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
|
|
@@ -46,11 +56,12 @@ async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined
|
|
|
46
56
|
marketplace.add(row["id"]);
|
|
47
57
|
}
|
|
48
58
|
|
|
49
|
-
const npm = new Map<string,
|
|
59
|
+
const npm = new Map<string, InstalledNpmPlugin>();
|
|
50
60
|
for (const row of value["npm"]) {
|
|
51
61
|
if (!isObject(row) || typeof row["name"] !== "string" || typeof row["version"] !== "string")
|
|
52
62
|
continue;
|
|
53
|
-
|
|
63
|
+
const path = typeof row["path"] === "string" ? row["path"] : undefined;
|
|
64
|
+
npm.set(row["name"], { version: row["version"], path });
|
|
54
65
|
}
|
|
55
66
|
return { marketplace, npm };
|
|
56
67
|
}
|
|
@@ -73,6 +84,14 @@ async function runPluginCommand(
|
|
|
73
84
|
return false;
|
|
74
85
|
}
|
|
75
86
|
|
|
87
|
+
function realPath(path: string): string | undefined {
|
|
88
|
+
try {
|
|
89
|
+
return realpathSync(path);
|
|
90
|
+
} catch {
|
|
91
|
+
return undefined;
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
76
95
|
export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
77
96
|
const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
|
|
78
97
|
|
|
@@ -105,6 +124,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
105
124
|
} else {
|
|
106
125
|
echo(`[dry-run] omp install pi-intercom@${piIntercomPin}`);
|
|
107
126
|
}
|
|
127
|
+
echo(`[dry-run] omp plugin link ${kitPluginDir(ctx.home)}`);
|
|
108
128
|
return 0;
|
|
109
129
|
}
|
|
110
130
|
|
|
@@ -121,7 +141,8 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
121
141
|
installed === undefined
|
|
122
142
|
? 0
|
|
123
143
|
: MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
|
|
124
|
-
(piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0)
|
|
144
|
+
(piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0) +
|
|
145
|
+
(installed.npm.has(KIT_PLUGIN_NAME) ? 1 : 0);
|
|
125
146
|
let operationsSucceeded = 0;
|
|
126
147
|
|
|
127
148
|
for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
|
|
@@ -143,7 +164,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
143
164
|
if (piIntercomPin === "") {
|
|
144
165
|
warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin");
|
|
145
166
|
} else {
|
|
146
|
-
const installedVersion = installed?.npm.get("pi-intercom");
|
|
167
|
+
const installedVersion = installed?.npm.get("pi-intercom")?.version;
|
|
147
168
|
const present = installedVersion !== undefined;
|
|
148
169
|
if (installedVersion === piIntercomPin) {
|
|
149
170
|
verbose(`omp npm plugin pi-intercom already installed at ${piIntercomPin}`);
|
|
@@ -160,6 +181,18 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
160
181
|
}
|
|
161
182
|
}
|
|
162
183
|
|
|
184
|
+
// The kit plugin is linked when omp's entry resolves to the kit directory.
|
|
185
|
+
// A refresh never applies: the link always points at the current files.
|
|
186
|
+
const kitDir = kitPluginDir(ctx.home);
|
|
187
|
+
const kitPluginPath = installed?.npm.get(KIT_PLUGIN_NAME)?.path;
|
|
188
|
+
const linkedTarget = kitPluginPath === undefined ? undefined : realPath(kitPluginPath);
|
|
189
|
+
if (linkedTarget !== undefined && linkedTarget === realPath(kitDir)) {
|
|
190
|
+
verbose(`omp kit plugin ${KIT_PLUGIN_NAME} already linked`);
|
|
191
|
+
} else if (await runPluginCommand(ctx, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
|
|
192
|
+
operationsSucceeded++;
|
|
193
|
+
if (installed?.npm.has(KIT_PLUGIN_NAME) !== true) pluginsInstalled++;
|
|
194
|
+
}
|
|
195
|
+
|
|
163
196
|
if (operationsSucceeded > 0) {
|
|
164
197
|
change(`omp plugins synced (plugins: ~${operationsSucceeded})`);
|
|
165
198
|
ctx.nextStepTriggers.ompRestart = true;
|