Skip to content
Back to search

640-skills

Agent Skills for Solopreneurs & Teams.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/KunoLu/640-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/KunoLu/640-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunolu--640-skills/badge.svg)](/listings/kunolu--640-skills)

HTML

<a href="/listings/kunolu--640-skills"><img src="/api/listings/kunolu--640-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the Onboard Skill only

Paste this into your coding agent; replace the target agent if needed:

Install only sbtd-workflow-onboard from the KunoLu/640-skills v2.0.1 tag
into my user-level global Skills directory for Codex, not this project.
First resolve that revision and verify it exists; do not silently substitute main or a v1 package.
Use the official skills CLI and copy the full directory. Show the resolved source and target.
Do not run init/reset, install other tools, or change AGENTS/MCP configuration yet.

Prefer the terminal? With Node/npm available, use the [official Skills CLI](https://github.com/vercel-labs/skills):

npx --yes skills@latest add https://github.com/KunoLu/640-skills \
  --skill sbtd-workflow-onboard --global --agent codex --yes --copy
npx skills list --global --agent codex

`skills@latest` selects the CLI version, **not a Skill release**. An unpinned repository source reads the default branch, not the latest tag. Pinning syntax is `'KunoLu/640-skills#<reviewed-ref>@sbtd-workflow-onboard'`: replace `<reviewed-ref>` with an existing v2 tag or reviewed commit, and follow that revision's documentation. **Do not combine a historical v1 package with the v2 setup prompts below**: its initialization may install or invoke the retired Trellis/GitNexus workflow. For v1 data, use the migration prompt below instead of init/reset.

**Bootstrap is not setup.** It copies the self-contained Onboard package; it does not execute `onboard.py`, install the remaining Skills or Python dependencies, configure MCP, or initialize projects. Find the actual installed directory rather than assuming a HOME path. For OMP or another host, confirm its supported Skills CLI agent identifier and discovery path instead of assuming Onboard's platform name is the same identifier.

2. Review and initialize selected projects

Use sbtd-workflow-onboard to initialize /abs/project-one,/abs/project-two.
Target platform: codex. These are the existing absolute project roots I want initialized;
install project AGENTS.md in both. First check the installed package's Python dependencies
and show plan --json, including global Skills, global AGENTS and host/MCP targets.
Ask before installing missing prerequisites or applying the plan. After I approve,
run init and report each project's writes, backups, skipped checks and remaining actions.

Use `omp` instead of `codex` for OMP setup. Multiple project roots are separated by English commas. A normal setup installs the **14 bundled + 19 required external Skills globally**; optional tools retain their own confirmation gates.

Onboard needs **Python 3.10+** and its declared dependencies for contract/state/migration validation. After reviewing and authorizing dependency installation, run this with the interpreter that will execute the installed copy:

python -m pip install -r /path/to/installed/sbtd-workflow-onboard/requirements.txt

> **Check the write scope.** Normal `init`/`reset` writes global Codex rules by default, and also backs up and overwrites `~/.omp/agent/AGENTS.md` when `~/.omp` already exists. Selecting a platform does not select the global AGENTS destination. `--global-agents-path` changes only the Codex target. Use project-only mode when global writes are not wanted.

[Bootstrap guide](sbtd-workflow-onboard/REFERENCE.md#official-skills-cli-bootstrap) · [Setup contract](sbtd-workflow-onboard/REFERENCE.md#two-execution-modes) · [Path resolution](sbtd-workflow-onboard/REFERENCE.md#paths)

<a id="usage"></a>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 538 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # SBTD Workflow
  3. **Reusable agent rules, skills and onboarding for evidence-driven development.**
  4. [![Bundled skills](https://img.shields.io/badge/bundled_skills-14-7c3aed?style=flat-square)](#skills) [![External skills](https://img.shields.io/badge/external_skills-19-0d9488?style=flat-square)](#external-skills) [![License](https://img.shields.io/badge/license-Apache_2.0-blue?style=flat-square)](LICENSE)
  5. **English** · [简体中文](README.zh.md)
  6. [Install](#install) · [Usage & prompts](#usage) · [Workflow](#workflow) · [Skills](#skills) · [Reference](#reference)
  7. </div>
  8. SBTD connects **specifications, behavior, tests and domain language**. Your coding agent does the work; the workflow makes scope, permissions and verification explicit.
  9. This repository is a **configuration and Skill source**, not a business application. The main workflow targets **Codex and Oh My Pi (OMP)**; the installers also expose Claude Code and Kimi adapters. Adapter availability is not proof of identical host behavior.
  10. > **Latest stable [v2.1.0](https://github.com/KunoLu/640-skills/releases/tag/v2.1.0) is released.** The catalog contains 14 bundled and 19 required external Skills. See the [English CHANGELOG](CHANGELOG.md) and [Chinese counterpart](CHANGELOG.zh.md) for the same release history. Code, CI, installation, native checks and actual host acceptance remain separate evidence layers; publishing a tag does not upgrade your environment. See the [delivery plan and acceptance boundaries](docs/prd/sbtd-workflow-v2-trellis-removal-graft-migration-prd.md).
  11. | [New installation](#install) | [Already installed](#onboard-prompts) | [Start a task](#task-prompts) |
  12. |---|---|---|
  13. | Bootstrap Onboard, then review setup | Check, upgrade or initialize another project | Choose a mode and copy a task prompt |
  14. <a id="install"></a>
  15. ## Install: start with your agent
  16. ### 1. Install the Onboard Skill only
  17. Paste this into your coding agent; replace the target agent if needed:
  18. ```text
  19. Install only sbtd-workflow-onboard from the KunoLu/640-skills v2.1.0 tag
  20. into my user-level global Skills directory for Codex, not this project.
  21. First resolve that revision and verify it exists; do not silently substitute main or a v1 package.
  22. Use the official skills CLI and copy the full directory. Show the resolved source and target.
  23. Do not run init/reset, install other tools, or change AGENTS/MCP configuration yet.
  24. ```
  25. Prefer the terminal? With Node/npm available, use the [official Skills CLI](https://github.com/vercel-labs/skills):
  26. ```bash
  27. npx --yes skills@latest add https://github.com/KunoLu/640-skills \
  28. --skill sbtd-workflow-onboard --global --agent codex --yes --copy
  29. npx skills list --global --agent codex
  30. ```
  31. `skills@latest` selects the CLI version, **not a Skill release**. An unpinned repository source reads the default branch, not the latest tag. Pinning syntax is `'KunoLu/640-skills#<reviewed-ref>@sbtd-workflow-onboard'`: replace `<reviewed-ref>` with an existing v2 tag or reviewed commit, and follow that revision's documentation. **Do not combine a historical v1 package with the v2 setup prompts below**: its initialization may install or invoke the retired Trellis/GitNexus workflow. For v1 data, use the migration prompt below instead of init/reset.
  32. **Bootstrap is not setup.** It copies the self-contained Onboard package; it does not execute `onboard.py`, install the remaining Skills or Python dependencies, configure MCP, or initialize projects. Find the actual installed directory rather than assuming a HOME path. For OMP or another host, confirm its supported Skills CLI agent identifier and discovery path instead of assuming Onboard's platform name is the same identifier.
  33. ### 2. Review and initialize selected projects
  34. ```text
  35. Use sbtd-workflow-onboard to initialize /abs/project-one,/abs/project-two.
  36. Target platform: codex. These are the existing absolute project roots I want initialized;
  37. install project AGENTS.md in both. First check the installed package's Python dependencies
  38. and show plan --json, including global Skills, global AGENTS and host/MCP targets.
  39. Ask before installing missing prerequisites or applying the plan. After I approve,
  40. run init and report each project's writes, backups, skipped checks and remaining actions.
  41. ```
  42. Use `omp` instead of `codex` for OMP setup. Multiple project roots are separated by English commas. A normal setup installs the **14 bundled + 19 required external Skills globally**; optional tools retain their own confirmation gates.
  43. Onboard needs **Python 3.10+** and its declared dependencies for contract/state/migration validation. After reviewing and authorizing dependency installation, run this with the interpreter that will execute the installed copy:
  44. ```bash
  45. python -m pip install -r /path/to/installed/sbtd-workflow-onboard/requirements.txt
  46. ```
  47. > **Check the write scope.** Normal `init`/`reset` writes global Codex rules by default, and also backs up and overwrites the OMP global rules file, following omp 18.19.0's own resolution: `$PI_CODING_AGENT_DIR/AGENTS.md` when `PI_CODING_AGENT_DIR` is non-empty (relative values, including a leading `~`, resolve against the process current directory — `~/x` means a folder literally named `~` there — and the directory is created when missing); a named profile (`OMP_PROFILE` before `PI_PROFILE`) targets `profiles/<name>/agent/AGENTS.md` and ignores the variable; otherwise `~/.omp/agent/AGENTS.md` only when `~/.omp` already exists, with `PI_CONFIG_DIR` naming the home subdirectory that replaces `.omp` (an absolute value is joined under home too, never used as an absolute path). Selecting a platform does not select the global AGENTS destination. `--global-agents-path` changes only the Codex target. Use project-only mode when global writes are not wanted.
  48. [Bootstrap guide](sbtd-workflow-onboard/REFERENCE.md#official-skills-cli-bootstrap) · [Setup contract](sbtd-workflow-onboard/REFERENCE.md#two-execution-modes) · [Path resolution](sbtd-workflow-onboard/REFERENCE.md#paths)
  49. <a id="usage"></a>
  50. ## Usage: copy a prompt for your goal
  51. These are **natural-language requests to your agent**, not new CLI commands. Replace bracketed inputs and `/abs/...` paths. The agent should read local facts first and ask only for missing choices or required authorization.
  52. <a id="onboard-prompts"></a>
  53. ### Manage an installation
  54. | Goal | Choose | What it means |
  55. |---|---|---|
  56. | Inspect without installing | `check` / `plan` | Read-only inventory and proposed work; not proof that setup ran |
  57. | First full setup | `init` | Install missing/invalid Skills; preserve valid Skill shells, not necessarily current content |
  58. | Add a project only | `init-projects` | Project AGENTS/ignore and applicable local assets; no global installation or user MCP/hooks |
  59. | Align an existing environment | `upgrade` | Fixed-baseline plan/apply/verify, explicit drift decisions, backups and recovery |
  60. | Deliberately reinstall | `reset` | Overwrite bundled Skills **without backup**, reinstall required externals; not an upgrade recovery protocol |
  61. | Move legacy data | `migration` | Approved projections, retained originals and verified receipts; separate deployment authorization; interrupted deployment evidence is reconciled from current state, never backfilled |
  62. | Retire detected legacy assets | `cleanup-legacy` | Display actual candidates, then obtain separate execution consent |
  63. | Restore an authorized batch | `recovery` | Plan and confirm restoration from trusted batch evidence; not a general undo command |
  64. The [first-time initialization prompt](#install) covers a new v2 installation after bootstrap. Use the following prompts for an existing installation or a v1 project; substitute the exact reviewed v2 source, project roots and configuration domains before execution.
  65. <details>
  66. <summary><strong>Run v2 init again — not a version upgrade</strong></summary>
  67. ```text
  68. Use the reviewed v2 sbtd-workflow-onboard package to plan init for platform codex
  69. and the existing project /abs/project. I want project AGENTS.md installed.
  70. Inspect the installed package revision and interpreter dependencies first.
  71. Show plan --json, exact global Skills/AGENTS/MCP targets and project writes/backups;
  72. wait for my approval before init. Preserve tasks, identity, lessons and legacy data.
  73. Explain which valid Skill shells init will skip; do not claim their contents were upgraded.
  74. If version alignment is needed, stop and propose an explicit upgrade plan instead.
  75. Do not reset, migrate, remove legacy assets or enable hooks under this request.
  76. ```
  77. </details>
  78. <details>
  79. <summary><strong>Inspection and project-only setup prompts</strong></summary>
  80. **Inspect the existing environment:**
  81. ```text
  82. Use sbtd-workflow-onboard to check my codex environment and /abs/project.
  83. This is read-only: report installed Skills, resolved paths, project conflicts,
  84. and missing prerequisites. Do not install, reset, migrate, clean up or change configuration.
  85. ```
  86. **Add a project without changing global configuration:**
  87. ```text
  88. Use sbtd-workflow-onboard in init-projects mode for /abs/project, platform omp.
  89. Install project AGENTS.md. First run project-only preflight and show the local write scope;
  90. wait for approval before writing. Do not install or modify global tools, Skills,
  91. AGENTS, MCP or hooks. Report whether the local Graft graph was built or unavailable.
  92. ```
  93. </details>
  94. <details>
  95. <summary><strong>Upgrade and reset prompts — different operations</strong></summary>
  96. **Recommended for an existing environment: explicit upgrade.**
  97. ```text
  98. Use sbtd-workflow-onboard to plan an upgrade to the reviewed Onboard package baseline.
  99. First confirm the exact global Skills root, global AGENTS targets, codex/omp configuration
  100. homes, any shell profiles, and an existing private backup vault. Inventory only that scope.
  101. Show upgrade --phase plan and all replace/preserve decisions for custom content; wait for
  102. approval before apply. Then verify disk content separately from protocol and real host loading.
  103. Ask separately before host probes. Do not clean up old assets or sync other environments.
  104. ```
  105. An isolated probe still rejects linked Skills by default. To retain a link, explicitly approve its physical target with `upgrade --phase authorize-link`, then pass the resulting document to `verify --probe --yes --link-authorization`. This grants only exact local target access and a temporary plain-directory projection; it does not replace the original link, follow nested links or prove a live session reload. See the [authorization commands and refusal boundaries](sbtd-workflow-onboard/REFERENCE.md#probe-skill-link-authorization).
  106. **Apply only the plan you have reviewed and approved:**
  107. ```text
  108. I approve the exact upgrade scope and replace/preserve decisions already shown in
  109. [upgrade-plan file]. Use the matching trusted v2 Onboard executor and recheck the source,
  110. targets and private vault. Read plan_id from that file and run upgrade --phase apply
  111. with the required confirmation; do not ask me to transcribe hashes.
  112. Save the actual receipt and backups. If scope or state has changed, stop rather than silently
  113. replanning under this approval. On partial failure, report measured writes and the retry path.
  114. Do not probe hosts, migrate projects, clean up or sync other environments.
  115. ```
  116. **Verify the applied upgrade without starting host probes:**
  117. ```text
  118. Use upgrade --phase verify with [the approved plan] and [its actual upgrade receipt].
  119. Verify the installed package and selected resources against that exact baseline.
  120. Report disk, runtime/protocol, host loading and legacy cleanup separately; mark unexecuted
  121. layers unverified. Do not add --probe or --yes, repair configuration, or delete backups.
  122. ```
  123. **Optional host and linked-Skill verification — approve the scope first:**
  124. ```text
  125. Show the exact host probes proposed for [upgrade plan and receipt], including configuration
  126. domains, subprocesses, temporary projections and potential side effects. These upgrade probes
  127. need no real authentication or model request; do not read or copy credential files.
  128. Wait for my explicit probe approval.
  129. For a linked Skill, show its logical path, physical target, identity and content boundary.
  130. Only after I approve that target, use upgrade --phase authorize-link and preserve its output.
  131. Then run upgrade --phase verify --probe --yes with that authorization where required.
  132. Keep the original link and unrelated configuration; report isolated host loading separately
  133. from any live session reload. Unproven isolation is blocked, not bypassed; real model/behavior
  134. smoke requires its own scope and controlled authentication, outside this upgrade probe.
  135. ```
  136. **Plan recovery of this upgrade, not a migration rollback:**
  137. ```text
  138. Use recovery --phase plan with --upgrade-plan [plan] and --upgrade-receipt [receipt].
  139. Confirm the private vault is trusted, inspect current drift and show the exact restoration
  140. scope and limits. Save the recovery plan only to the approved private location.
  141. Wait for separate recovery approval before recovery --phase apply; use the actual
  142. --upgrade-recovery-plan and read its recovery_id for --confirm-recovery.
  143. Preserve user changes, backups and partial receipts; do not execute untrusted historical code.
  144. ```
  145. These prompts map to the [implemented upgrade and recovery commands](sbtd-workflow-onboard/REFERENCE.md#upgrade-alignment). A successful `verify` does not grant cleanup permission; an old plan does not authorize a newly changed package or target set.
  146. **Use reset only when you intend to replace Skill content:**
  147. ```text
  148. Use the reviewed v2 sbtd-workflow-onboard package to plan reset for platform codex
  149. and /abs/project. I want project AGENTS.md rewritten, subject to the displayed plan.
  150. Verify the package revision and interpreter dependencies. Explain that bundled Skills
  151. will be overwritten without backup and required external Skills reinstalled.
  152. Identify custom Skill content; if I need it preserved, stop for a separately approved backup
  153. or propose upgrade instead. Show all global/project targets, AGENTS backups and MCP impact;
  154. preserve detected React Bits tier/registry. Wait for approval before reset.
  155. Preserve tasks, developer identity, specs, lessons, handoffs and legacy data.
  156. Reset is not migration, cleanup, a full-machine upgrade, or an automatic rollback guarantee.
  157. ```
  158. </details>
  159. <details>
  160. <summary><strong>Legacy migration, cleanup and recovery prompts</strong></summary>
  161. **Migrate an SBTD v1 project to v2 — package upgrade and data migration are separate:**
  162. ```text
  163. I use SBTD v1 in /abs/project and want to move to [reviewed v2 tag or commit]
  164. for [codex and/or omp, with the exact selected configuration domains].
  165. Start read-only: identify the installed Onboard version, old Trellis/GitNexus layout,
  166. project branch, custom rules, tasks/specs/lessons, shared HOME/Skills users and active processes.
  167. Do not run v1 init/reset, copy credentials, create directories or modify configuration yet.
  168. Separate the plan for upgrading the Onboard/Skills package from the project-data migration.
  169. If the old executor lacks the v2 upgrade entry point, show how to prepare the reviewed v2
  170. executor and preserve the existing installation; request that installation approval separately.
  171. Agree an external private vault, custodian, retained originals, publication decisions,
  172. approved candidates and recovery limits. Show the real migration plan before requesting apply.
  173. After authorized apply, request deployment approval separately; consume the bound
  174. manifest/receipts for new rules/Skills/wiring, then verify data, host behavior and recovery evidence.
  175. Only after verification, display batch and fresh cleanup candidates and request deletion
  176. approval separately. Keep unknown content and backups; do not promise writable Trellis rollback.
  177. Stop at each unapproved phase. Do not use reset as a substitute for upgrade or migration.
  178. ```
  179. **Request cleanup planning, not immediate deletion:**
  180. ```text
  181. sbtd cleanup for /abs/project. Show verified batch candidates if available and run a fresh
  182. cleanup-legacy plan. List every target and disclose shared global MCP impact before asking
  183. for execution consent. Preserve unknown content, CLI packages, global data and backups.
  184. ```
  185. **Recover a specific batch:**
  186. ```text
  187. Use sbtd-workflow-onboard recovery for [the explicitly selected migration or upgrade batch].
  188. Verify the trusted private vault and bound receipts. Show recovery --phase plan,
  189. current drift, exact restoration scope and what cannot be restored. Wait for my approval
  190. before apply; retain backups and report partial results honestly.
  191. ```
  192. **Reconcile interrupted deployment evidence:**
  193. ```text
  194. Use sbtd-workflow-onboard migration --phase reconcile for [the batch whose apply completed
  195. but whose cumulative deployment evidence was never saved]. Bind the exact manifest and
  196. complete apply receipt, prove the historical evidence path genuinely absent, and freshly
  197. observe current state into one new typed evidence document at a new private path.
  198. Do not forge the missing receipt or claim the original deployment ran to completion;
  199. I confirm --yes explicitly and run the standard verify afterwards.
  200. ```
  201. The migration planner accepts characterized Trellis **0.6.15 / 0.6.17 data layouts**, not arbitrary old versions. Hash claims on user content are not deletion authority; missing approvals, contradictory task relationships and unknown host configuration still block. A genuinely host-free project can retain an empty platform list without inventing host files. Vendor-uninstall runtime support remains separately pinned.
  202. Stale recorded template hashes may be reconciled only against the installed package's reviewed **exact path/version/content pins**; migration neither refreshes the old hash file nor fetches templates at runtime. Mixed project `AGENTS.md` content is not generated-file ownership: replacing it still requires the existing signed approval, bound to the actual before-state and exact candidate. Recognition is not authorization to apply or clean up.
  203. Migration deployment retains the approved project-rule body, removing only the maintenance pause and adding the managed Graft fence; it does not silently swap that body for the generic template.
  204. OMP deployment also recognizes configuration-input changes already proved by bound successful migration receipts and intact originals. Unrecorded drift still blocks; this does not waive runtime-version checks or authorize a deployment retry.
  205. An interrupted deployment whose evidence was never saved is reconciled from **current state**, not backfilled: `migration --phase reconcile` requires the complete successful apply receipt, a genuinely absent historical evidence path, a new non-overwriting output path and explicit `--yes`. It revalidates the signed runtime lineage, retained originals and sealed resources, then writes one new evidence document explicitly typed `kind: current-state` / `historical_execution: unknown` — each result pairs a before-state proven by the retained original with a freshly measured after-state, and no historical exit code, success claim or timestamp is invented. Acceptance means the current postconditions hold, not that the original process exited cleanly or wrote new targets; the subsequent standard `verify` reports `acceptance_basis: current-state`. This authorizes no install, deployment retry or cleanup, and the regular deploy/retry/recovery gates are unchanged.
  206. Consumers recheck that the cited manifest/apply objects are safe files with the recorded digests. The observer must match the manifest runtime or its exact signature-approved successor; reverse or unrelated lineage is rejected. Historical observers need not match the current consumer, and cumulative retries never rewrite their provenance. This does not authenticate historical execution or authorize refreshing old evidence.
  207. New cross-runtime observations retain the verified signed authorization in `observer_lineage`, so later pair-file rotation does not erase historical observer authority. Consumers verify it with the installed trusted key, never a key supplied by the evidence. Legacy records without this proof still require the matching current pair (unless observer and manifest runtimes match); lost authority is not invented. Accepted plans and evidence recheck direct and followup-ancestor provenance at output; cleanup and recovery also recheck before writes. Post-write refusals preserve measured results without claiming successful acceptance.
  208. Current-state acceptance completes semantic/lineage validation before its final snapshot-only pass over observed artifacts and pinned inputs. That pass includes absent resources; it is not an atomic cross-process snapshot and does not promise objects can never change afterward.
  209. Already aligned project rules can remain untouched under exact-template evidence. Document-only legacy task folders are archived as documents, not fabricated tasks; historical task branches remain historical, with explicit deferred recovery instead of an automatic checkout or rebinding.
  210. Ordinary RC upgrades use content comparison and native upgrade receipts, not a new local lineage signature on every release. To retire an already verified original migration after one Onboard replacement, cleanup can consume paired `--upgrade-plan` / `--upgrade-receipt` and the intact old package backup. This is cleanup-only: it verifies existing historical signatures without executing old code and does not authorize followup or migration recovery. Proven unrelated deployment-discovery file/absent drift may be left untouched; target, retained-asset, profile, tool, footprint and provenance drift still block. See the [cleanup contract](sbtd-workflow-onboard/REFERENCE.md#cleanup-runtime).
  211. [Upgrade & recovery](sbtd-workflow-onboard/REFERENCE.md#upgrade-alignment) · [Migration](sbtd-workflow-onboard/REFERENCE.md#migration-runtime) · [Cleanup](sbtd-workflow-onboard/REFERENCE.md#cleanup-runtime)
  212. </details>
  213. <a id="task-prompts"></a>
  214. ### Use SBTD in daily development
  215. **Start here for ordinary work:**
  216. ```text
  217. Use sbtd-task in default mode for [goal] in this repository.
  218. Read the project rules and relevant lessons, inspect the existing implementation,
  219. make the smallest correct change, and exercise the changed path.
  220. Report changed files, actual verification, skipped checks and remaining risks.
  221. Do not install tools, migrate data, deploy or sync configuration without separate authorization.
  222. ```
  223. | Situation | Recommended prompt |
  224. |---|---|
  225. | Small, bounded change | “Use sbtd-task in **lite** mode for [change]. Keep a shared short task card, acceptance checklist and focused verification; preserve all project safety requirements.” |
  226. | High-risk or audited delivery | “Use sbtd-task in **strict** mode for [goal]. Create a new branch, record requirements and acceptance, produce the Book Gate Plan, complete applicable gates and independent review, then report evidence.” |
  227. | Unclear requirements | “Use **grill-with-docs** for [idea]. Read repository facts first, clarify decisions and record domain language. After the full interview, run **book-ddd-distilled-modeling** and show the independent DDD Boundary Review before design or implementation.” |
  228. | Reproducible bug | “Use **diagnosing-bugs** for [observed failure]. Establish a failing feedback loop, identify the cause, then use **tdd** for a regression test where appropriate. Verify the preserved behavior as well as the fix.” |
  229. | UI and regression | “For [page/flow], use **ui-ux-pro-max**, **shadcn** if the project uses it, and **impeccable** for visual review. Use **gherkin-bdd** and **project-validation**; persist Playwright assets with **web-ui-autotest-generator** only if maintainable inputs are available.” |
  230. | Mobile / Hybrid | “Use **maestro-mobile-e2e** for [journey] on [iOS/Android]. Confirm the BDD source, app, device, backend, accounts and selectors before creating flows. Run the applicable Maestro validation and retain native reports plus Chinese summaries.” |
  231. | Simplicity review | “Use **ponytail-review** on this diff. Propose deletions and simpler native solutions without weakening correctness, readability or safety.” Use **ponytail-audit** for a whole-repository audit, **ponytail-debt** for existing deferral markers. |
  232. | Resume or hand off | “Continue SBTD task [task ID]. Check its root, branch and effective mode; preserve that mode and ask if candidates conflict.” / “Prepare an **sbtd-task** handoff for [task ID], preserving completed work, evidence, next action and limitations.” |
  233. | Read behavior into a knowledge base | “Use **knowledge-base-integration** to read [configured product/repositories] at [target ref]. Resolve exact SHAs, produce the behavior catalog, and report missing mappings. **Mutation: none**; do not rewrite `.feature` or publish evidence.” |
  234. Want tracker deliverables? Explicitly request **to-spec** or **to-tickets**, identify the tracker and authorize publication. These are not substitutes for local task state, and their tracker setup is not automatically supplied by Onboard.
  235. Want a different reply style? `adhd mode` opts into **i-have-adhd**; `/caveman` requests compact replies when Caveman is available. `normal mode` exits both. **Reply style never changes default/lite/strict execution requirements.**
  236. <a id="workflow"></a>
  237. ## How the workflow fits together
  238. SBTD is this repository's combination of four practices, not a new runtime or framework:
  239. | Practice | Question it answers | Typical artifact or method |
  240. |---|---|---|
  241. | **SDD** — Specification-Driven Development | What are we building, and why? | Requirements, PRD/design, acceptance criteria |
  242. | **BDD** — Behavior-Driven Development | What can a user observe? | Project-owned Gherkin scenarios and traceable tests |
  243. | **TDD** — Test-Driven Development | How do we prove a change at the right boundary? | Red–green–refactor at agreed test seams |
  244. | **DDD** — Domain-Driven Design | Which terms, rules and boundaries must agree? | Glossary, context/ADR decisions, independent boundary review |
  245. ```text
  246. Read project facts and lessons → resolve task, branch, scope and mode
  247. → clarify requirements / domain language as needed
  248. → full grill-with-docs? Independent DDD Boundary Review must be confirmed
  249. → specify observable behavior → design and applicable pre-development gates
  250. → implement with risk-appropriate TDD → smoke and readability review
  251. → project-native validation + applicable Web / Mobile / evidence checks
  252. → release-readiness review when triggered → record actual completion
  253. ```
  254. ### Choose an execution mode
  255. | Mode | Use it for | Working contract |
  256. |---|---|---|
  257. | `default` | Ordinary tasks | On-demand investigation, implementation and focused validation; only needed local records |
  258. | `lite` | Bounded tasks needing a shared trail | Short checklist and shared task card, not a mandatory full document pack |
  259. | `strict` | Explicitly rigorous delivery | Applicable before-dev/check/finish obligations, Book Gate Plan and required evidence |
  260. Mode precedence is **your current explicit choice → the same task's valid record → default for a genuinely new task**. A suggested change waits for your decision; continuing a task does not reset its mode. All modes preserve explicit deliverables, project rules and safety. Every completed full `grill-with-docs` requires the independent DDD review in **all three modes**.
  261. Strict gates are triggered by facts: domain ambiguity, persistent/shared data, uncertain legacy behavior, existing production-code edits, or production runtime/deployment changes. Not every gate runs on every task; a required but unavailable gate is **blocked**, not passed. [Strict contract](sbtd-workflow-onboard/templates/skills/sbtd-task/references/strict.md) · [Method routing](sbtd-workflow-onboard/templates/skills/sbtd-task/references/methods.md) · [Workflow paths](docs/assets/sbtd-workflow-paths.md)
  262. ### State without a second source of truth
  263. - `task.md` owns mode, status and events. Ordinary default tasks use `.sbtd/tasks/<id>/`; lite/strict or explicitly shared tasks use `ai/tasks/<id>/`. `.sbtd/active-task.json` is only a bookmark.
  264. - `cancelled` is a terminal cancellation, **not successful completion**: `completed_at` stays null. Cancellation never cascades to children; archive and explicit reopen preserve its history. Imported `blocked` records with an unknown prior phase require an explicit recovery choice. Update the task runtime, schema and Skill references together before using these records with older installations.
  265. - Handoffs live under protected `docs/handoffs/` on a real pause/switch or explicit request; they never override the task. Pure Q&A/read-only work creates no task, identity or handoff files.
  266. - Developer identity is needed for a durable lesson write, not ordinary work. A valid local `.sbtd/developer` wins; only genuine absence in a verified linked worktree allows reading the main checkout's identity. Never guess names or replace a malformed identity.
  267. [Task state](sbtd-workflow-onboard/templates/skills/sbtd-task/references/state.md) · [Handoffs](sbtd-workflow-onboard/templates/skills/sbtd-task/references/handoff.md) · [Lessons](sbtd-workflow-onboard/templates/skills/lessons-record/SKILL.md)
  268. <a id="skills"></a>
  269. ## Skill catalog
  270. **Installed together, used when relevant.** Normal Onboard `init`/`reset` targets global Skills. Bootstrap alone and project-only initialization do not install or activate the complete global workflow. The [catalog](sbtd-workflow-onboard/catalog.json) owns membership; click a Skill for its full instructions and references.
  271. ### 14 bundled Skills
  272. | Skill | Job / when to use it |
  273. |---|---|
  274. | [sbtd-workflow-onboard](sbtd-workflow-onboard/SKILL.md) | Check, install, initialize, upgrade, migrate and recover explicitly selected environments |
  275. | [sbtd-task](sbtd-workflow-onboard/templates/skills/sbtd-task/SKILL.md) | Route work through default/lite/strict; manage task state and continuation |
  276. | [gherkin-bdd](sbtd-workflow-onboard/templates/skills/gherkin-bdd/SKILL.md) | Author observable behavior; distinguish writable BDD sync from read-only ingest |
  277. | [project-validation](sbtd-workflow-onboard/templates/skills/project-validation/SKILL.md) | Select native checks, applicable testing tools and truthful evidence/report status |
  278. | [web-ui-autotest-generator](sbtd-workflow-onboard/templates/skills/web-ui-autotest-generator/SKILL.md) | Generate/audit maintainable Playwright assets and selector/coverage manifests |
  279. | [maestro-mobile-e2e](sbtd-workflow-onboard/templates/skills/maestro-mobile-e2e/SKILL.md) | Derive Mobile/Hybrid Maestro flows from BDD and verify real device prerequisites |
  280. | [knowledge-base-integration](sbtd-workflow-onboard/templates/skills/knowledge-base-integration/SKILL.md) | Product registry, Evidence Policy, Revision Sets, read-only ingest and staged smoke |
  281. | [lessons-record](sbtd-workflow-onboard/templates/skills/lessons-record/SKILL.md) | Record durable lessons with validated author identity and topic/index ownership |
  282. | [book-ddd-distilled-modeling](sbtd-workflow-onboard/templates/skills/book-ddd-distilled-modeling/SKILL.md) | Review domain language and boundaries; mandatory after every full grill-with-docs |
  283. | [book-ddia-data-design](sbtd-workflow-onboard/templates/skills/book-ddia-data-design/SKILL.md) | Review data ownership, consistency, schema, cache, migration and recovery design |
  284. | [book-legacy-change-safety](sbtd-workflow-onboard/templates/skills/book-legacy-change-safety/SKILL.md) | Characterize existing behavior and establish a safety net before risky changes |
  285. | [book-refactoring-pass](sbtd-workflow-onboard/templates/skills/book-refactoring-pass/SKILL.md) | Review the smallest safe structure change before production-code edits |
  286. | [book-release-readiness](sbtd-workflow-onboard/templates/skills/book-release-readiness/SKILL.md) | Review operational risk and rollback after required validation |
  287. | [seo-geo](sbtd-workflow-onboard/templates/skills/seo-geo/SKILL.md) | Audit search/AI visibility for public web surfaces, not internal apps or API regression |
  288. <a id="external-skills"></a>
  289. ### 19 required external Skills
  290. These are reviewed **upstream mirrors**, not local forks. `auto` and `stable` install from the bundled snapshot without fetching upstream; only an explicit `upstream` selection opts into current upstream evaluation. Exact revisions, checksums and licenses live in the [stable manifest](sbtd-workflow-onboard/assets/external-skills/stable/MANIFEST.json).
  291. | Area | Skills | Purpose |
  292. |---|---|---|
  293. | Clarification | [grilling](sbtd-workflow-onboard/assets/external-skills/stable/skills/grilling/SKILL.md), [grill-me](sbtd-workflow-onboard/assets/external-skills/stable/skills/grill-me/SKILL.md), [grill-with-docs](sbtd-workflow-onboard/assets/external-skills/stable/skills/grill-with-docs/SKILL.md) | Stress-test decisions; use the documented variant for domain records |
  294. | Specifications | [to-spec](sbtd-workflow-onboard/assets/external-skills/stable/skills/to-spec/SKILL.md), [to-tickets](sbtd-workflow-onboard/assets/external-skills/stable/skills/to-tickets/SKILL.md) | Turn agreed discussions into tracker specs and dependency-aware work slices |
  295. | Design | [domain-modeling](sbtd-workflow-onboard/assets/external-skills/stable/skills/domain-modeling/SKILL.md), [codebase-design](sbtd-workflow-onboard/assets/external-skills/stable/skills/codebase-design/SKILL.md) | Shared language, context decisions, module interfaces and test seams |
  296. | Debug & test | [diagnosing-bugs](sbtd-workflow-onboard/assets/external-skills/stable/skills/diagnosing-bugs/SKILL.md), [tdd](sbtd-workflow-onboard/assets/external-skills/stable/skills/tdd/SKILL.md) | Evidence-first diagnosis and red–green feedback loops |
  297. | UI | [ui-ux-pro-max](sbtd-workflow-onboard/assets/external-skills/stable/skills/ui-ux-pro-max/SKILL.md), [impeccable](sbtd-workflow-onboard/assets/external-skills/stable/skills/impeccable/SKILL.md), [shadcn](sbtd-workflow-onboard/assets/external-skills/stable/skills/shadcn/SKILL.md) | UX/design systems, visual refinement and shadcn/ui-specific implementation |
  298. | Simplicity | [ponytail](sbtd-workflow-onboard/assets/external-skills/stable/skills/ponytail/SKILL.md), [ponytail-review](sbtd-workflow-onboard/assets/external-skills/stable/skills/ponytail-review/SKILL.md), [ponytail-audit](sbtd-workflow-onboard/assets/external-skills/stable/skills/ponytail-audit/SKILL.md), [ponytail-debt](sbtd-workflow-onboard/assets/external-skills/stable/skills/ponytail-debt/SKILL.md) | Minimal implementation, diff review, whole-repo audit and deferral ledger |
  299. | Agent collaboration | [handoff](sbtd-workflow-onboard/assets/external-skills/stable/skills/handoff/SKILL.md), [writing-for-agents](sbtd-workflow-onboard/assets/external-skills/stable/skills/writing-for-agents/SKILL.md) | General handoff prose and agent-facing documentation; SBTD state remains owned by sbtd-task |
  300. | Reply structure | [i-have-adhd](sbtd-workflow-onboard/assets/external-skills/stable/skills/i-have-adhd/SKILL.md) | Opt-in, session-level, action-first replies; installation does not activate it |
  301. Onboard uses the **Ponytail skill-only provider**. An enabled official Ponytail plugin is a conflict, not permission to disable it; plugin management and `ponytail-gain`/`ponytail-help` are outside Onboard. [Provider boundary](sbtd-workflow-onboard/REFERENCE.md#ponytail-provider-boundary)
  302. <a id="verification"></a>
  303. ## Tools and verification boundaries
  304. | Tool / layer | Owns | Does not prove |
  305. |---|---|---|
  306. | Graft | Pinned, scoped structural analysis and impact assistance | Compiler semantics, business correctness or automatic host readiness |
  307. | Chrome DevTools MCP | Browser runtime, console/network/performance diagnosis | Repeatable CI regression |
  308. | Playwright MCP | Page exploration and locator assistance | A passing project Playwright suite |
  309. | Playwright CLI | Project-local Web regression and E2E | Full-stack behavior when only mocks/contracts are available |
  310. | Maestro CLI / MCP | Mobile/Hybrid flows; device/flow diagnostics; optional Web smoke | Primary Web regression or unavailable real-device behavior |
  311. | RTK / Caveman | Terminal-output / reply compression | Test execution, reports or reduced workflow obligations |
  312. Graft installation is separately confirmed and pinned by the [managed runtime](sbtd-workflow-onboard/scripts/graft_runtime.py). One global `sbtd-graft` connection per effective Codex/OMP configuration domain locks the real repository/worktree from startup cwd; project initialization prepares local graphs. No parent-directory multi-project graph, implicit cloud enrichment, or silent legacy binding replacement. Codex hooks are a separate opt-in; OMP setup does not write hooks. [Wiring contract](sbtd-workflow-onboard/REFERENCE.md#codex-and-omp-wiring-and-deployment)
  313. Managed Graft stays on the Graft command/tool contract even when Trail is installed: child environments disable automatic Trail switching and inherited Trail configuration. Project `.trail` notes are subject to the same no-link/no-special-file scope checks as native graph inputs. See [pin acceptance scenarios](sbtd-workflow-onboard/REFERENCE.md#graft-pin-acceptance-scenarios).
  314. **Report what actually ran.** Native commands are preferred for report-producing tests. Keep failed runs, named native/raw reports and same-stem **Chinese** summaries. Distinguish `full-stack`, `contract-backed`, `mock-backed`/`app-mocked`, `backend-only`, `smoke-only` and `blocked`; a generated report is not a passing test. Dirty local evidence is not exact PR-head CI proof.
  315. Agent-authored execution summaries use the [fixed Chinese report template](sbtd-workflow-onboard/templates/skills/project-validation/references/run-summary.zh-CN.md.template): conclusion/counts, run metadata, commands, BDD/scope, case results, failures/reruns, API URI coverage, artifacts/status, and limitations. Preserve failed rounds and source/deployment boundaries; unsupported fields need an explicit reason, not fabricated values. Coverage scoring is an appendix, not a substitute for execution results. Historical reports remain unchanged; reformatting retained evidence is a separately labeled preview, not a new test run.
  316. | Asset | Default location in a target project |
  317. |---|---|
  318. | BDD source | Existing project `.feature` convention; Chinese scenario text + English keywords when no convention exists |
  319. | Playwright test manifests | `tests/e2e/manifest/` — pass explicit paths, not root-level generator defaults |
  320. | Playwright retained reports | `tests/e2e/reports/html/` |
  321. | API reports | `tests/api/reports/` |
  322. | Maestro flows / reports | `maestro/flow/` / `.maestro/reports/` |
  323. | Unit reports | Project convention; otherwise `tests/unit/reports/` when required |
  324. | SBTD task-local evidence | `ai/tasks/**/reports/` — ignored; task documents remain shareable |
  325. Knowledge-base P1.1 produces read-only catalogs and smoke bundles; remote Evidence Store/PR Checks and publication remain P2 scope. BDD `sync` is a separate writable workflow. [Knowledge-base guide](sbtd-workflow-onboard/templates/skills/knowledge-base-integration/SKILL.md) · [Evidence contract](sbtd-workflow-onboard/templates/skills/project-validation/SKILL.md)
  326. <details>
  327. <summary><strong>Optional tools and common pitfalls</strong></summary>
  328. - Playwright is project-local. Java 17+ and Maestro, optional MCPs, RTK and Caveman require their applicable setup choices; an installed Skill does not prove its CLI/server is callable.
  329. - Caveman may compress repeated status updates under the global auto-lite policy; `normal mode` opts out for the task. ADHD structure is explicit opt-in only. See [presentation rules](sbtd-workflow-onboard/templates/skills/sbtd-task/references/presentation.md).
  330. - React Bits is an optional project enhancement, not a shadcn dependency. Free registries must be known; paid tiers require an existing entitlement and local key handling. Never put keys in chat, examples or reports. [React Bits scope](sbtd-workflow-onboard/REFERENCE.md#react-bits)
  331. - `init` is not content alignment; `reset` is not safe upgrade recovery. Upgrade verification separates disk, protocol and actual host loading; a preserved customization is not full alignment.
  332. - Legacy Trellis/GitNexus is migration input, not the current workflow. Normal setup does not initialize Trellis or perform legacy cleanup. Cleanup requires a displayed list and consent; backups have a separate retention/destruction boundary.
  333. </details>
  334. <a id="reference"></a>
  335. ## Reference and manual entrypoints
  336. | Need | Read |
  337. |---|---|
  338. | Full Onboard commands, scope and troubleshooting | [SKILL](sbtd-workflow-onboard/SKILL.md) · [REFERENCE](sbtd-workflow-onboard/REFERENCE.md) |
  339. | Bootstrap / init / reset / project-only flowcharts | [Bootstrap](docs/assets/npx-skills-global-onboard-install.md) · [Init](docs/assets/onboard-skill-init.md) · [Reset](docs/assets/onboard-skill-reset.md) · [Project-only](docs/assets/onboard-init-projects.md) |
  340. | Upgrade / migration / cleanup / recovery | [Upgrade](sbtd-workflow-onboard/REFERENCE.md#upgrade-alignment) · [Migration & recovery](sbtd-workflow-onboard/REFERENCE.md#migration-runtime) · [Cleanup](sbtd-workflow-onboard/REFERENCE.md#cleanup-runtime) |
  341. | Global / project rules | [Global template](sbtd-workflow-onboard/templates/agents/AGENTS.global.md) · [Project template](sbtd-workflow-onboard/templates/agents/AGENTS.project.md) |
  342. | Release history / monitored versions | [English CHANGELOG](CHANGELOG.md) · [中文变更日志](CHANGELOG.zh.md) · [ENTRYPOINT](ENTRYPOINT.md) · [Bilingual release/tag template](docs/release-notes-template.md) |
  343. <details>
  344. <summary><strong>Manual setup after bootstrap, or from a cloned checkout</strong></summary>
  345. Set `SBTD_ONBOARD_DIR` to the **actual installed package directory**, with dependencies prepared. First inspect:
  346. ```bash
  347. python "$SBTD_ONBOARD_DIR/scripts/onboard.py" plan \
  348. --platform codex --projects-root /abs/project-one,/abs/project-two --json
  349. ```
  350. Only after reviewing and approving that same scope:
  351. ```bash
  352. python "$SBTD_ONBOARD_DIR/scripts/onboard.py" init \
  353. --platform codex --projects-root /abs/project-one,/abs/project-two --yes --json
  354. ```
  355. A cloned checkout also provides complete interactive installers:
  356. ```bash
  357. bash install.sh
  358. ```
  359. ```powershell
  360. pwsh -File .\install.ps1
  361. ```
  362. For project-only setup, use `bash install.sh --platform codex --init-projects /abs/project` or `pwsh -File .\install.ps1 -Platform codex -InitProjects "C:\work\project"`. This is mutually exclusive with ordinary `--projects-root`/`--action` selections. Normal root-installer `init`/`reset` with `--yes`/`-Yes` and no project roots is **global-only**, not an implicit selection of cwd. Confirmation flags approve selected operations; they do not bypass conflicts or authorize migration.
  363. </details>
  364. <a id="repository"></a>
  365. ## Repository and maintenance
  366. | Path | Role |
  367. |---|---|
  368. | `README.md` / `README.zh.md` | English and Chinese reader entrypoints; detailed contracts stay in linked sources |
  369. | `sbtd-workflow-onboard/` | Self-contained installable Skill: runtime `scripts/`, payload `templates/`, mirrored `assets/`, catalog and reference |
  370. | `sbtd-runtime/` | Optional local statistics runtime and contracts, including a runnable Dashboard `serve` ([installation and use](sbtd-runtime/docs/install-and-use.md)). Not installed or copied by Onboard; start it manually from the repository root after installing the documented dependencies |
  371. | `install.sh` / `install.ps1` | Root installation interfaces; source root is the Onboard directory |
  372. | `ENTRYPOINT.md` | Tracked monitoring baseline and recoverable maintenance entrypoint |
  373. | `docs/lessons.md` | Required short lessons entry; index/topic detail is loaded only when relevant |
  374. | `prompts/automations/sbtd-workflow-tools-version-check.md` | Versioned automation prompt, not a live automation update |
  375. | `prompts/automations/references/` | Mandatory version-check scope policy and topic-routed compatibility checks |
  376. | `.github/workflows/validation.yml` | Project-native validation matrix |
  377. This source repository's root `AGENTS.md` is **optional, ignored and local-only**; it is not the project template or a fresh-clone prerequisite. Its root `.gitignore` is intentionally separate from the [target-project template](sbtd-workflow-onboard/templates/project/.gitignore):
  378. ```gitignore
  379. .DS_Store
  380. /.sbtd
  381. /docs/handoffs
  382. /ai/tasks/**/reports
  383. /graft
  384. /.graft
  385. __pycache__/
  386. /.pytest_cache/
  387. /.ruff_cache/
  388. AGENTS.md
  389. .chrome-devtools-mcp/
  390. .playwright-mcp/
  391. ```
  392. Ignore rules do not sanitize secrets, untrack existing files or authorize deletion. Task reports are local by default; publishing evidence requires redaction and a separately approved destination. **This template-source repository does not create `.feature` files**; its durable behavioral specifications use Markdown and existing tests.
  393. For source changes, assess both language READMEs, [English CHANGELOG](CHANGELOG.md), [Chinese CHANGELOG](CHANGELOG.zh.md) and the [versioned automation prompt](prompts/automations/sbtd-workflow-tools-version-check.md). The changelogs must match entry for entry: same versions, dates, order, facts, URLs, commit SHAs and code identifiers; only prose language differs. Update the top unpublished section in both, and preserve published history. Ordinary edits do **not** sync installed copies or live automation. Repository-maintenance `sync` requires explicit authorization; `update` advances monitored baselines other than Graft and archives the analyzed update. Graft's ENTRYPOINT baseline follows the pin in a published SBTD workflow version and is not advanced by official Graft releases or `update`. These are not Onboard upgrade commands or BDD sync requests.
  394. The version-check automation uses a short main prompt, a per-run scope policy and an on-demand impact checklist. It validates the assigned Orca workspace, protects existing changes, distinguishes unavailable evidence from “no update”, and keeps `ENTRYPOINT.md` as the fixed baseline for official tool releases. Graft is the exception: its recorded baseline changes only when a published workflow version contains a new agreed pin. Native tag names are retained separately from comparison versions. When no confirmed unpublished CHANGELOG section exists, release-note proposals stay in `UPDATE.md` or the run output; the automation does not invent the next tag. Updating these source files does not update the live automation; that remains an explicit `sync` operation.
  395. The native full-suite command remains `python -B -m unittest discover -s tests -p 'test_*.py'`. CI discovers that complete Linux set and partitions it into disjoint shards weighted by measured per-case seconds, splitting fixture-free cases individually and keeping class/module fixtures together (cases without a recorded weight are estimated at the median and listed in each shard inventory); Windows partitions its native scope without repeating overlapping PowerShell/Unicode selectors. macOS keeps its native scope. The existing check names aggregate all required shards; any failed, cancelled or missing shard blocks success. The minimum supported TOML-editor run remains a separate dependency variant, not a duplicate. Per-case timings, skip reasons and Chinese result summaries are retained as CI artifacts. Consult the [workflow](.github/workflows/validation.yml) and [runner](tests/run_ci.py) for exact scope. Source checks, installed-copy checks, real host loading and release acceptance remain separate evidence.
  396. Catalog-independent migration boundary tests narrow only their installation inputs: they retain the complete Onboard launcher package, multiple sibling Skills and all file-routing operations. Full-catalog lifecycle and installed-copy tests remain separate anchors. Every stage still runs the real migration/recovery APIs and fresh safety checks; smaller fixtures do not authorize cached verdicts, reused receipts or omitted drift cases. Compare total runner cost separately from parallel wall-clock time.
  397. Required native Windows checks (including ACLs, junctions, Unicode, PowerShell and enabled case-sensitive paths) and Linux case-sensitive checks must pass, not merely be selected: skip or expected failure blocks their shard.
  398. CI artifacts retain each native run attempt without overwriting failures. Partial retries may reuse successful shards from the same SHA; aggregation selects each shard's newest report, rejects newer failures or ambiguous duplicates, and proves that the union covers the complete scope exactly once. Skip totals count native events, including skipped subtests; parent-case status counts can differ. Preserve subtest identities and reasons when comparing runs.
  399. Windows currently uses four shards, Linux three, and macOS one job. After downloading a complete successful native report set, refresh scheduling inputs with `python -B tests/run_ci.py --platform windows --output <downloaded-reports> --refresh-weights` (use `linux` for Linux). Refresh requires a nonempty source revision and an unambiguous, complete, disjoint latest-attempt set; duplicate measurements or noncanonical shard filenames are rejected. Weights only change allocation, never test selection. Equal line/branch coverage alone does not justify removing a behavioral or platform boundary test.
  400. <a id="license"></a>
  401. ## License and credits
  402. Original repository and bundled original content use [Apache License 2.0](LICENSE), with [Onboard LICENSE](sbtd-workflow-onboard/LICENSE) and [NOTICE](sbtd-workflow-onboard/NOTICE) shipped in the package. Third-party mirrors retain their own licenses and pinned provenance; the adapted [seo-geo NOTICE](sbtd-workflow-onboard/templates/skills/seo-geo/NOTICE) records its upstream source and local changes.
sbtd-workflow-onboard/scripts/onboard.py · Bundled script · 7,594 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. from __future__ import annotations
  3. import argparse
  4. import datetime as dt
  5. import filecmp
  6. import hashlib
  7. import json
  8. import os
  9. import platform
  10. import re
  11. import shlex
  12. import shutil
  13. import stat
  14. import subprocess
  15. import sys
  16. import tarfile
  17. import tempfile
  18. import urllib.error
  19. import urllib.request
  20. from collections.abc import Callable
  21. from dataclasses import dataclass
  22. from pathlib import Path
  23. from typing import TYPE_CHECKING, cast
  24. if __name__ == "__main__":
  25. # Installed source directories can themselves be sealed deployment inputs.
  26. # CLI imports must not mutate those inputs by adding bytecode caches.
  27. sys.dont_write_bytecode = True
  28. if TYPE_CHECKING:
  29. from sbtd_identity import IdentityResult
  30. from graft_runtime import check_graft, install_graft
  31. from onboard_arguments import (
  32. SingleValueAction,
  33. WorkflowArgumentParser,
  34. _add_migration_context,
  35. _check_migration_context,
  36. add_cleanup_legacy_parser,
  37. add_migration_parser,
  38. add_recovery_parser,
  39. add_upgrade_parser,
  40. validate_cleanup_legacy_args,
  41. validate_developer_name,
  42. validate_migration_args,
  43. validate_recovery_args,
  44. validate_upgrade_args,
  45. )
  46. from sbtd_project import StateInspection, TaskDataError, inspect_project_state
  47. SKILL_DIR = Path(__file__).resolve().parents[1]
  48. SKILL_ENTRY_DIR = Path(__file__).absolute().parents[1]
  49. ONBOARD_SCRIPT_PATH = Path(__file__).absolute()
  50. CATALOG_PATH = SKILL_DIR / "catalog.json"
  51. EXTERNAL_STABLE_ROOT = SKILL_DIR / "assets" / "external-skills" / "stable"
  52. EXTERNAL_STABLE_MANIFEST = EXTERNAL_STABLE_ROOT / "MANIFEST.json"
  53. def read_skill_frontmatter_name(skill_md: Path) -> str | None:
  54. try:
  55. content = skill_md.read_bytes()
  56. except OSError:
  57. return None
  58. return skill_frontmatter_name_from_bytes(content)
  59. def skill_frontmatter_name_from_bytes(content: bytes) -> str | None:
  60. try:
  61. lines = content.decode("utf-8").splitlines()
  62. except UnicodeDecodeError:
  63. lines = content.decode("utf-8", errors="ignore").splitlines()
  64. if not lines or lines[0].strip() != "---":
  65. return None
  66. for line in lines[1:80]:
  67. stripped = line.strip()
  68. if stripped == "---":
  69. return None
  70. if stripped.startswith("name:"):
  71. return stripped.split(":", 1)[1].strip().strip("'\"")
  72. return None
  73. def validate_relative_catalog_path(value: object, field: str) -> str:
  74. if not isinstance(value, str) or not value:
  75. raise RuntimeError(f"{field} must be a non-empty relative path")
  76. if (
  77. Path(value).is_absolute()
  78. or re.match(r"^(?:[A-Za-z]:[\\/]|[\\/])", value)
  79. or re.search(r"(^|[\\/])\.\.([\\/]|$)", value)
  80. ):
  81. raise RuntimeError(
  82. f"{field} must be a relative path contained by its root: {value}"
  83. )
  84. return value
  85. def resolve_local_catalog_source(value: object, entry_id: str) -> Path:
  86. relative = validate_relative_catalog_path(
  87. value, f"SBTD Onboard catalog source for {entry_id}"
  88. )
  89. source = (SKILL_DIR / relative).resolve()
  90. try:
  91. source.relative_to(SKILL_DIR)
  92. except ValueError as exc:
  93. raise RuntimeError(
  94. f"SBTD Onboard catalog source escapes the Skill root: {relative}"
  95. ) from exc
  96. if not source.exists():
  97. raise RuntimeError(
  98. f"SBTD Onboard catalog source is missing for {entry_id}: {source}"
  99. )
  100. return source
  101. def valid_https_repository_url(value: object) -> bool:
  102. return (
  103. isinstance(value, str)
  104. and re.fullmatch(r"https://[^/?#\s]+/(?:[^/?#\s]+/)*[^/?#\s]+/?", value)
  105. is not None
  106. )
  107. CATALOG_KIND_CONTRACTS: dict[str, tuple[str, frozenset[str]]] = {
  108. "agent-template": (
  109. "agent:",
  110. frozenset({"codex-global-agents", "project-agents"}),
  111. ),
  112. "project-template": ("project:", frozenset({"project-gitignore"})),
  113. "bundled-skill": (
  114. "skill:",
  115. frozenset({"skill", "skill:sbtd-workflow-onboard"}),
  116. ),
  117. "external-skill": ("skill:", frozenset({"external-skill"})),
  118. }
  119. def load_catalog() -> dict[str, object]:
  120. try:
  121. catalog = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
  122. except (OSError, json.JSONDecodeError) as exc:
  123. raise RuntimeError(f"cannot read SBTD Onboard catalog: {exc}") from exc
  124. if (
  125. catalog.get("schemaVersion") != 1
  126. or catalog.get("name") != "sbtd-workflow-onboard"
  127. ):
  128. raise RuntimeError("SBTD Onboard catalog identity or schema version is invalid")
  129. entries = catalog.get("entries")
  130. if not isinstance(entries, list) or not entries:
  131. raise RuntimeError("SBTD Onboard catalog must contain entries")
  132. seen: set[str] = set()
  133. for entry in entries:
  134. if not isinstance(entry, dict):
  135. raise RuntimeError("SBTD Onboard catalog entries must be objects")
  136. if set(entry) != {"id", "kind", "source", "targetRole"}:
  137. raise RuntimeError("SBTD Onboard catalog entries have invalid fields")
  138. entry_id = entry.get("id")
  139. entry_kind = entry.get("kind")
  140. source_value = entry.get("source")
  141. target_role = entry.get("targetRole")
  142. if (
  143. not isinstance(entry_id, str)
  144. or re.fullmatch(r"(agent|project|skill):[a-z0-9][a-z0-9-]*", entry_id)
  145. is None
  146. or entry_id in seen
  147. ):
  148. raise RuntimeError(
  149. f"SBTD Onboard catalog entry id is invalid or duplicated: {entry_id}"
  150. )
  151. contract = CATALOG_KIND_CONTRACTS.get(str(entry_kind))
  152. if contract is None:
  153. raise RuntimeError(f"SBTD Onboard catalog kind is invalid for {entry_id}")
  154. expected_prefix, allowed_roles = contract
  155. if not entry_id.startswith(expected_prefix):
  156. raise RuntimeError(
  157. f"SBTD Onboard catalog id does not match kind {entry_kind}: {entry_id}"
  158. )
  159. if not isinstance(target_role, str) or target_role not in allowed_roles:
  160. raise RuntimeError(
  161. f"SBTD Onboard catalog target role is invalid for {entry_id}: {target_role}"
  162. )
  163. if entry_kind == "external-skill":
  164. if not isinstance(source_value, dict) or set(source_value) != {
  165. "repo",
  166. "subpath",
  167. "aliases",
  168. }:
  169. raise RuntimeError(
  170. f"SBTD Onboard external source is invalid for {entry_id}"
  171. )
  172. repo = source_value.get("repo")
  173. subpath = source_value.get("subpath")
  174. aliases = source_value.get("aliases")
  175. if not valid_https_repository_url(repo):
  176. raise RuntimeError(
  177. f"SBTD Onboard external source repo must be a valid HTTPS "
  178. f"repository URL for {entry_id}"
  179. )
  180. validate_relative_catalog_path(
  181. subpath, f"SBTD Onboard external source subpath for {entry_id}"
  182. )
  183. if (
  184. not isinstance(aliases, list)
  185. or not aliases
  186. or any(not isinstance(alias, str) or not alias for alias in aliases)
  187. or len(aliases) != len(set(aliases))
  188. ):
  189. raise RuntimeError(
  190. f"SBTD Onboard external source is invalid for {entry_id}"
  191. )
  192. else:
  193. source = resolve_local_catalog_source(source_value, entry_id)
  194. if entry_kind in {"agent-template", "project-template"}:
  195. if not source.is_file():
  196. raise RuntimeError(
  197. f"SBTD Onboard {entry_kind} source must be a regular file "
  198. f"for {entry_id}: {source}"
  199. )
  200. else:
  201. if not source.is_dir():
  202. raise RuntimeError(
  203. f"SBTD Onboard bundled-skill source must be a directory "
  204. f"for {entry_id}: {source}"
  205. )
  206. expected_name = entry_id.removeprefix("skill:")
  207. actual_name = read_skill_frontmatter_name(source / "SKILL.md")
  208. if actual_name != expected_name:
  209. raise RuntimeError(
  210. f"SBTD Onboard bundled-skill frontmatter name must match "
  211. f"{entry_id}: expected {expected_name}, got "
  212. f"{actual_name or '<missing>'}"
  213. )
  214. seen.add(entry_id)
  215. return cast(dict[str, object], catalog)
  216. def catalog_source(catalog: dict[str, object], entry_id: str) -> Path:
  217. entries = cast(list[dict[str, object]], catalog["entries"])
  218. for entry in entries:
  219. if entry["id"] == entry_id:
  220. return (SKILL_DIR / str(entry["source"])).resolve()
  221. raise RuntimeError(f"SBTD Onboard catalog entry is missing: {entry_id}")
  222. def catalog_external_skill_sources(
  223. catalog: dict[str, object],
  224. ) -> dict[str, dict[str, object]]:
  225. sources: dict[str, dict[str, object]] = {}
  226. for entry in cast(list[dict[str, object]], catalog["entries"]):
  227. if entry.get("kind") != "external-skill":
  228. continue
  229. source = cast(dict[str, object], entry["source"])
  230. sources[str(entry["id"]).removeprefix("skill:")] = {
  231. "repo": str(source["repo"]),
  232. "subpath": str(source["subpath"]),
  233. "aliases": tuple(cast(list[str], source["aliases"])),
  234. }
  235. return sources
  236. CATALOG = load_catalog()
  237. GLOBAL_AGENTS_TEMPLATE = catalog_source(CATALOG, "agent:codex-global")
  238. PROJECT_AGENTS_TEMPLATE = catalog_source(CATALOG, "agent:project")
  239. PROJECT_GITIGNORE_TEMPLATE = catalog_source(CATALOG, "project:gitignore")
  240. SKILL_SOURCES = {
  241. str(entry["id"]).removeprefix("skill:"): (
  242. SKILL_DIR / str(entry["source"])
  243. ).resolve()
  244. for entry in cast(list[dict[str, object]], CATALOG["entries"])
  245. if entry.get("kind") == "bundled-skill"
  246. }
  247. EXTERNAL_SKILL_SOURCES = catalog_external_skill_sources(CATALOG)
  248. NVM_INSTALL_URL = "https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh"
  249. RTK_INSTALL_URL = (
  250. "https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh"
  251. )
  252. TEMURIN21_RELEASES_URL = "https://github.com/adoptium/temurin21-binaries/releases"
  253. TEMURIN_RELEASES_API_TEMPLATE = (
  254. "https://api.github.com/repos/adoptium/temurin{major}-binaries/releases/latest"
  255. )
  256. MAESTRO_INSTALL_URL = "https://get.maestro.mobile.dev"
  257. CAVEMAN_SOURCE_REPO = "https://github.com/JuliusBrussee/caveman.git"
  258. CAVEMAN_PINNED_REF = "v4.0.1"
  259. CAVEMAN_PINNED_REVISION = "d262ab3882952a59312ff3537cd86d894523c5ab"
  260. CAVEMAN_CORE_SKILL_SHA256 = "415d43518f2b1a9498c15a445d4657117b129ee5e81b19454ce348439cc6672b"
  261. CAVEMAN_KNOWN_CORE_SKILL_SHA256 = {
  262. "v4.0.1": CAVEMAN_CORE_SKILL_SHA256,
  263. "v2.6.0": "c4d7354b4b063d54601fcdd5097a5b1713d1a1a2e386ac39efa438aa1ffef8ce",
  264. "v2.5.0": "fec5718a391dd9d8c89746d39e0cc0fa7aa5b50447669a15e44c3244167828c0",
  265. }
  266. CAVEMAN_KNOWN_FAMILY_SHA256 = {
  267. # Reviewed at CAVEMAN_PINNED_REVISION.
  268. "v4.0.1": {
  269. "cavecrew": "2ba088a27199b7c41b9f9765bf6e8d6f580a645ce0094051f8f5d5733d6cb4de",
  270. "caveman": "7d9d77c6a276780f9295d377bb8dfb1fb5be5c16ccb5043e0d1b2acef23508ed",
  271. "caveman-commit": "68fce6cc3c50050e8ede6df99d4f478582d9b5952782c441acf2477b16d706db",
  272. "caveman-compress": "bf58594d45b03e559935a94a56528835f199808c282a6d7f29105e9599321db5",
  273. "caveman-discover": "0a52f133aef4d3b81e9554cc43132bcf1accedb1154f6ac8e75df24f5f58f537",
  274. "caveman-evidence-review": "fc5959727ef2f822d756c7e837abea51be91c32e0ca87758c1b77f68c98d5552",
  275. "caveman-explore": "8fa46ff537d60dba875442db7530918fe4790cfddfb2d60d23e3a82ba6c95a94",
  276. "caveman-help": "346cdf9f89e8be8e8006f2ec01836dd87f365f7b70853dc871aedff58f5c50ad",
  277. "caveman-learn": "2c2f56c8792c975a5b250348f970f24eb2654a364fd1162fb08c35625502fda9",
  278. "caveman-manage": "e6ad788986936cbe49bdf12cf122fa966dd9e20c0ea7716397e0049d9f833d5a",
  279. "caveman-optimize": "35dd36fa4b6fe800e9c1db8818b5e79ee18448372f33bd48ee593516d131a947",
  280. "caveman-review": "d50a54e5b5a5bae7fcac1a4472cfd34ce47c9a8183d1357928eac4c2bd8322db",
  281. "caveman-setup": "546eb697be5b87cec06117c4eb6d3e9eac55331cb860d2743c2d7b6f45c261b4",
  282. "caveman-stats": "00a8e24bd1544e07bf2e372700015746dc7ba3937b1d161bcf9377b2147921e4",
  283. },
  284. # Reviewed at f9a039a93d249f3fcdb47a9e02544cd1ce37ba4a.
  285. "v2.5.0": {
  286. "cavecrew": "673643f8c42f06f0904eb975a56923583c2cd47ce4bf5a5ac1e5e49b8e4b2c66",
  287. "caveman": "cfe5ad82c6b43421624d20dd30dc83100bb9516f889b0b2a8bb2cdd0dbd2a6be",
  288. "caveman-commit": "68fce6cc3c50050e8ede6df99d4f478582d9b5952782c441acf2477b16d706db",
  289. "caveman-compress": "3d618a06313658b3f108bf82c2f97591643e7fee83cb5990c30e5a044e9a0587",
  290. "caveman-discover": "0a52f133aef4d3b81e9554cc43132bcf1accedb1154f6ac8e75df24f5f58f537",
  291. "caveman-evidence-review": "fc5959727ef2f822d756c7e837abea51be91c32e0ca87758c1b77f68c98d5552",
  292. "caveman-explore": "81c49c489e8d94ffb4cf47e05632235a88d125c4a05e6d2cf64bc0535aa87895",
  293. "caveman-help": "63b42410962891586b7a5317391e39b8b0a90370144be4d7281e43c68b140947",
  294. "caveman-learn": "9c1442a0b61945e1bc37240d9a494be4658768e56e61b76943fb0cbc18d805cd",
  295. "caveman-manage": "e6ad788986936cbe49bdf12cf122fa966dd9e20c0ea7716397e0049d9f833d5a",
  296. "caveman-optimize": "35dd36fa4b6fe800e9c1db8818b5e79ee18448372f33bd48ee593516d131a947",
  297. "caveman-review": "d50a54e5b5a5bae7fcac1a4472cfd34ce47c9a8183d1357928eac4c2bd8322db",
  298. "caveman-setup": "546eb697be5b87cec06117c4eb6d3e9eac55331cb860d2743c2d7b6f45c261b4",
  299. "caveman-stats": "652eaffb8f6c635431ed238fa7ae2126e138ad7b1d26fae7390f8edc1af17bb0",
  300. },
  301. # Reviewed at b82c0ad42c2bedc1f2cd78e414dadfaffbaaeec3.
  302. "v2.6.0": {
  303. "cavecrew": "673643f8c42f06f0904eb975a56923583c2cd47ce4bf5a5ac1e5e49b8e4b2c66",
  304. "caveman": "26b5e133a79a0251dad5e57acaa22ef601731fe59fb4637f9f150d7dfc250bad",
  305. "caveman-commit": "68fce6cc3c50050e8ede6df99d4f478582d9b5952782c441acf2477b16d706db",
  306. "caveman-compress": "3d618a06313658b3f108bf82c2f97591643e7fee83cb5990c30e5a044e9a0587",
  307. "caveman-discover": "0a52f133aef4d3b81e9554cc43132bcf1accedb1154f6ac8e75df24f5f58f537",
  308. "caveman-evidence-review": "fc5959727ef2f822d756c7e837abea51be91c32e0ca87758c1b77f68c98d5552",
  309. "caveman-explore": "81c49c489e8d94ffb4cf47e05632235a88d125c4a05e6d2cf64bc0535aa87895",
  310. "caveman-help": "63b42410962891586b7a5317391e39b8b0a90370144be4d7281e43c68b140947",
  311. "caveman-learn": "9c1442a0b61945e1bc37240d9a494be4658768e56e61b76943fb0cbc18d805cd",
  312. "caveman-manage": "e6ad788986936cbe49bdf12cf122fa966dd9e20c0ea7716397e0049d9f833d5a",
  313. "caveman-optimize": "35dd36fa4b6fe800e9c1db8818b5e79ee18448372f33bd48ee593516d131a947",
  314. "caveman-review": "d50a54e5b5a5bae7fcac1a4472cfd34ce47c9a8183d1357928eac4c2bd8322db",
  315. "caveman-setup": "546eb697be5b87cec06117c4eb6d3e9eac55331cb860d2743c2d7b6f45c261b4",
  316. "caveman-stats": "652eaffb8f6c635431ed238fa7ae2126e138ad7b1d26fae7390f8edc1af17bb0",
  317. },
  318. }
  319. CAVEMAN_DRIFT_ADVICE = (
  320. "Local caveman family payload is newer or customized; "
  321. "review it before replacing the pinned baseline."
  322. )
  323. # Monitoring the v* installer/skill tag line only reports drift. A baseline
  324. # bump requires a human review of SKILL.md and installer behavior, then updates
  325. # ref, revision, hashes, and tests together in one change.
  326. JAVA_MIN_MAJOR = 17
  327. BUNDLED_SKILL_LEGACY_NAMES = {
  328. "sbtd-workflow-onboard": ("kuno-workflow-onboard-skills",),
  329. }
  330. CLI_TOOLS = (
  331. {
  332. "name": "rtk",
  333. "versionArgs": ("--version",),
  334. "globalInstall": "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh",
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 359 on GitHub
  335. "projectInstall": None,
  336. "advice": "Install RTK from rtk-ai/rtk and verify with `rtk gain`; do not treat the unrelated Rust Type Kit package as valid.",
  337. },
  338. )
  339. AGENT_CLI_SPECS = {
  340. "codex": {
  341. "label": "Codex",
  342. "command": "codex",
  343. "npmPackage": "@openai/codex",
  344. "versionArgs": ("--version",),
  345. "advice": "Install the latest Codex CLI globally from the official @openai/codex npm package.",
  346. },
  347. "claude": {
  348. "label": "Claude Code",
  349. "command": "claude",
  350. "npmPackage": "@anthropic-ai/claude-code",
  351. "versionArgs": ("--version",),
  352. "advice": "Install the latest Claude Code CLI globally from the official @anthropic-ai/claude-code npm package.",
  353. },
  354. "kimi": {
  355. "label": "Kimi Code",
  356. "command": "kimi",
  357. "npmPackage": "@moonshot-ai/kimi-code",
  358. "versionArgs": ("--version",),
  359. "advice": "Install the latest Kimi Code CLI globally from the official @moonshot-ai/kimi-code npm package. The npm distribution requires a supported Node.js runtime.",
  360. },
  361. "oh-my-pi": {
  362. "label": "Oh My Pi",
  363. "command": "omp",
  364. "npmPackage": "@oh-my-pi/pi-coding-agent",
  365. "versionArgs": ("--version",),
  366. "advice": "Install the latest Oh My Pi CLI globally from @oh-my-pi/pi-coding-agent and verify the omp command. Upstream recommends its native or Bun installer, so npm installation must pass the command verification gate.",
  367. },
  368. }
  369. AGENT_PLATFORM_ALIASES = {
  370. "codex": "codex",
  371. "claude": "claude",
  372. "claude-code": "claude",
  373. "claudecode": "claude",
  374. "kimi": "kimi",
  375. "kimi-code": "kimi",
  376. "kimicode": "kimi",
  377. "oh-my-pi": "oh-my-pi",
  378. "ohmypi": "oh-my-pi",
  379. "omp": "oh-my-pi",
  380. }
  381. BUNDLED_SKILLS = tuple(SKILL_SOURCES.keys())
  382. MATTPOCOCK_CANONICAL_SKILLS = (
  383. "diagnosing-bugs",
  384. "tdd",
  385. "grill-me",
  386. "grill-with-docs",
  387. "grilling",
  388. "domain-modeling",
  389. "codebase-design",
  390. "handoff",
  391. "writing-for-agents",
  392. "to-spec",
  393. "to-tickets",
  394. )
  395. MATTPOCOCK_LEGACY_RENAMES = {
  396. "diagnose": "diagnosing-bugs",
  397. "write-a-skill": "writing-for-agents",
  398. "writing-great-skills": "writing-for-agents",
  399. "to-prd": "to-spec",
  400. "to-issues": "to-tickets",
  401. }
  402. MATTPOCOCK_REMOVED_SKILLS = {
  403. "zoom-out": "Removed upstream; use repo exploration, codebase-design, or book-refactoring-pass instead.",
  404. }
  405. MATTPOCOCK_REQUIRED_DEPENDENCIES = {
  406. "tdd": ("codebase-design",),
  407. "grill-me": ("grilling",),
  408. "grill-with-docs": ("grilling", "domain-modeling"),
  409. }
  410. PONYTAIL_REQUIRED_SKILLS = (
  411. "ponytail",
  412. "ponytail-review",
  413. "ponytail-audit",
  414. "ponytail-debt",
  415. )
  416. REFERENCED_SKILLS = (
  417. *MATTPOCOCK_CANONICAL_SKILLS,
  418. "ui-ux-pro-max",
  419. "impeccable",
  420. "shadcn",
  421. *PONYTAIL_REQUIRED_SKILLS,
  422. "i-have-adhd",
  423. )
  424. INTERACTION_SKILLS = ("caveman",)
  425. if set(EXTERNAL_SKILL_SOURCES) != set(REFERENCED_SKILLS):
  426. raise RuntimeError(
  427. "SBTD Onboard catalog external Skills do not match the referenced Skill contract"
  428. )
  429. MATTPOCOCK_REPO = str(EXTERNAL_SKILL_SOURCES["diagnosing-bugs"]["repo"])
  430. MATTPOCOCK_SKILL_SUBPATHS = {
  431. name: str(EXTERNAL_SKILL_SOURCES[name]["subpath"])
  432. for name in MATTPOCOCK_CANONICAL_SKILLS
  433. }
  434. if any(
  435. EXTERNAL_SKILL_SOURCES[name]["repo"] != MATTPOCOCK_REPO
  436. for name in MATTPOCOCK_CANONICAL_SKILLS
  437. ):
  438. raise RuntimeError(
  439. "SBTD Onboard catalog mattpocock Skills must share one repository"
  440. )
  441. EXTERNAL_REPO_TO_SKILLS: dict[str, tuple[str, ...]] = {}
  442. for _skill_name, _source_spec in EXTERNAL_SKILL_SOURCES.items():
  443. _repo = str(_source_spec["repo"])
  444. EXTERNAL_REPO_TO_SKILLS[_repo] = (
  445. *EXTERNAL_REPO_TO_SKILLS.get(_repo, ()),
  446. _skill_name,
  447. )
  448. BASE_MANUAL_CHECKS = (
  449. {
  450. "name": "Chrome DevTools MCP",
  451. "category": "mcp",
  452. "advice": "Confirm the active Agent or IDE exposes Chrome DevTools MCP tools before relying on it for Web runtime diagnostics.",
  453. "steps": (
  454. "Configure or enable the Chrome DevTools MCP server in the active Agent or IDE MCP settings.",
  455. "Confirm Google Chrome or Chrome for Testing is available when the MCP server requires it.",
  456. "Restart or reload the Agent environment so the MCP server is discovered.",
  457. "Confirm Chrome DevTools MCP tools are visible before relying on it for console, network, screenshot, or performance diagnostics.",
  458. "Treat Chrome DevTools MCP output as diagnostic evidence, not as a replacement for project tests or Playwright E2E.",
  459. ),
  460. },
  461. {
  462. "name": "Playwright MCP",
  463. "category": "mcp",
  464. "advice": "Confirm Playwright MCP tools are visible before relying on them for page exploration, accessibility snapshots, or locator assistance.",
  465. "steps": (
  466. "When the selected Playwright distribution exposes it, prefer its bundled `npx playwright mcp` entrypoint; otherwise configure a compatible dedicated Playwright MCP server.",
  467. "Restart or reload the Agent environment so the MCP server is discovered.",
  468. "Confirm Playwright MCP tools are visible to the Agent.",
  469. "Use Playwright MCP for exploration and locator assistance only; do not treat it as a substitute for project-level Playwright CLI.",
  470. ),
  471. },
  472. )
  473. @dataclass(frozen=True)
  474. class Operation:
  475. label: str
  476. source: Path
  477. target: Path
  478. kind: str
  479. same_location: bool = False
  480. skip_when_valid: bool = False
  481. def expand_path(value: str | None) -> Path | None:
  482. if not value:
  483. return None
  484. return Path(value).expanduser().resolve()
  485. def default_codex_home() -> Path:
  486. env_value = os.environ.get("CODEX_HOME")
  487. if env_value:
  488. return Path(env_value).expanduser().resolve()
  489. return (Path.home() / ".codex").resolve()
  490. def user_home() -> Path:
  491. if os.name == "nt":
  492. raw = os.environ.get("USERPROFILE") or os.environ.get("HOME")
  493. if raw:
  494. return Path(raw).expanduser()
  495. return Path.home()
  496. def detect_omp_root() -> Path | None:
  497. """Probe the default OMP config root (PI_CONFIG_DIR aware) for existence.
  498. The root mirrors Node ``path.join(home, PI_CONFIG_DIR or ".omp")``: an
  499. absolute-looking value stays under home and ``..`` may escape it, exactly
  500. as OMP 18.19.0 resolves it. An explicit PI_CODING_AGENT_DIR or named
  501. profile does not move this root.
  502. """
  503. from sbtd_omp_sources import omp_config_root
  504. root = omp_config_root(user_home(), os.environ)
  505. try:
  506. resolved = root.resolve()
  507. except OSError:
  508. return None
  509. return resolved if resolved.is_dir() else None
  510. def omp_agents_target() -> tuple[Path, bool]:
  511. """Resolve the OMP user-level AGENTS.md OMP 18.19.0 reads, plus explicitness.
  512. Explicit means a non-empty PI_CODING_AGENT_DIR or a named profile selected
  513. the agent directory; onboard then writes the target even when it does not
  514. exist yet. Without an explicit selector the historical rule stands: the
  515. target lives under the default config root and onboard writes only when
  516. that root already exists, never creating it.
  517. """
  518. from sbtd_omp_sources import active_omp_agent_dir
  519. resolved = active_omp_agent_dir(home=user_home(), environ=os.environ)
  520. agent_dir = resolved["agent_dir"]
  521. assert isinstance(agent_dir, Path)
  522. explicit = bool(resolved["override"]) or resolved["profile"] is not None
  523. return agent_dir / "AGENTS.md", explicit
  524. def omp_global_agents_path(omp_root: Path) -> Path:
  525. return omp_root / "agent" / "AGENTS.md"
  526. def known_global_skills_dirs() -> tuple[Path, ...]:
  527. home = Path.home()
  528. return tuple(
  529. path.resolve()
  530. for path in (
  531. home / ".agents" / "skills",
  532. home / ".agent" / "skills",
  533. home / ".codex" / "skills",
  534. home / ".claude" / "skills",
  535. home / ".pi" / "agent" / "skills",
  536. default_codex_home() / "skills",
  537. )
  538. )
  539. def installed_global_skills_dir() -> Path | None:
  540. known_roots = set(known_global_skills_dirs())
  541. for skill_dir in (SKILL_ENTRY_DIR, SKILL_DIR):
  542. if skill_dir.name != "sbtd-workflow-onboard":
  543. continue
  544. parent = skill_dir.parent.resolve()
  545. if parent in known_roots and (skill_dir / "SKILL.md").is_file():
  546. return parent
  547. return None
  548. def resolve_global_skills_dir(value: str | None = None) -> tuple[Path, str]:
  549. explicit = expand_path(value)
  550. if explicit:
  551. return explicit, "argument"
  552. environment = os.environ.get("AGENT_SKILLS_DIR")
  553. if environment:
  554. return Path(environment).expanduser().resolve(), "environment"
  555. installed = installed_global_skills_dir()
  556. if installed:
  557. return installed, "installed-skill-parent"
  558. return (default_codex_home() / "skills").resolve(), "platform-default"
  559. def default_global_skills_dir() -> Path:
  560. return resolve_global_skills_dir()[0]
  561. def resolve_project_root(
  562. args: argparse.Namespace, required: bool = False
  563. ) -> Path | None:
  564. """Resolve the single-project interface used by project-only tool installers."""
  565. project_root = expand_path(getattr(args, "project_root", None))
  566. if project_root and not project_root.is_dir():
  567. raise SystemExit(
  568. f"--project-root must be an existing directory: {project_root}"
  569. )
  570. if required and not project_root:
  571. raise SystemExit(
  572. "--project-root is required unless --skip-project-agents is used"
  573. )
  574. return project_root
  575. def resolve_project_roots(
  576. args: argparse.Namespace, required: bool = False
  577. ) -> list[Path]:
  578. raw = (getattr(args, "projects_root", None) or "").strip()
  579. if not raw:
  580. if required:
  581. raise SystemExit("--projects-root is required")
  582. return []
  583. roots: list[Path] = []
  584. for value in raw.split(","):
  585. candidate_text = value.strip()
  586. if not candidate_text:
  587. continue
  588. candidate = Path(candidate_text).expanduser()
  589. if not candidate.is_absolute():
  590. raise SystemExit(
  591. f"--projects-root only accepts absolute paths: {candidate_text}"
  592. )
  593. candidate = candidate.resolve()
  594. if not candidate.is_dir():
  595. raise SystemExit(f"Project root does not exist: {candidate}")
  596. if candidate not in roots:
  597. roots.append(candidate)
  598. if required and not roots:
  599. raise SystemExit("--projects-root must contain at least one absolute path")
  600. return roots
  601. def subprocess_command(command: tuple[str, ...]) -> tuple[str, ...] | str:
  602. """Return an executable form of ``command`` for ``subprocess.run``.
  603. Windows npm-style global CLIs are ``.CMD``/``.BAT`` batch launchers, not
  604. PE executables; starting them directly fails with error 193 or returns
  605. empty output. Resolve the real launcher and route batch files through
  606. ``cmd.exe /d /s /c``; other platforms and native executables keep the
  607. original argv tuple without a shell.
  608. """
  609. if platform.system() != "Windows" or not command:
  610. return command
  611. resolved = shutil.which(command[0])
  612. if not resolved or Path(resolved).suffix.lower() not in {".cmd", ".bat"}:
  613. return command
  614. return f'cmd.exe /d /s /c "{subprocess.list2cmdline([resolved, *command[1:]])}"'
  615. def run_command(
  616. command: tuple[str, ...],
  617. timeout: int = 30,
  618. env: dict[str, str] | None = None,
  619. cwd: Path | None = None,
  620. ) -> subprocess.CompletedProcess[str] | None:
  621. try:
  622. return subprocess.run(
  623. subprocess_command(command),
  624. check=False,
  625. capture_output=True,
  626. text=True,
  627. errors="replace",
  628. timeout=timeout,
  629. env=env,
  630. cwd=str(cwd) if cwd else None,
  631. )
  632. except (OSError, subprocess.TimeoutExpired):
  633. return None
  634. def shell_result(
  635. script: str, timeout: int = 300
  636. ) -> subprocess.CompletedProcess[str] | None:
  637. shell = shutil.which("bash") or shutil.which("sh")
  638. if not shell:
  639. return None
  640. return run_command((shell, "-lc", script), timeout=timeout)
  641. def command_output(
  642. command: tuple[str, ...], timeout: int = 10, env: dict[str, str] | None = None
  643. ) -> tuple[int | None, str]:
  644. completed = run_command(command, timeout=timeout, env=env)
  645. if completed is None:
  646. return None, ""
  647. output = (completed.stdout or completed.stderr).strip()
  648. return completed.returncode, output
  649. def command_version(command: str, version_args: tuple[str, ...]) -> str | None:
  650. _, output = command_output((command, *version_args), timeout=5)
  651. return output.splitlines()[0] if output else None
  652. def nvm_dir_shell_expr() -> str:
  653. return '${NVM_DIR:-$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "$HOME/.nvm" || printf %s "$XDG_CONFIG_HOME/nvm")}'
  654. def nvm_load_script() -> str:
  655. nvm_dir = nvm_dir_shell_expr()
  656. return (
  657. f'export NVM_DIR="{nvm_dir}"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"'
  658. )
  659. def check_nvm() -> dict[str, object]:
  660. system = platform.system() or sys.platform
  661. if system == "Windows":
  662. path = shutil.which("nvm")
  663. version = command_version("nvm", ("version",)) if path else None
  664. return {
  665. "name": "nvm",
  666. "installed": bool(path),
  667. "path": path,
  668. "version": version,
  669. "installableByScript": False,
  670. "advice": "Native Windows should use nvm-windows, nvs, or WSL; the nvm-sh installer is for POSIX shells.",
  671. }
  672. completed = shell_result(
  673. f"{nvm_load_script()}; command -v nvm; nvm --version", timeout=10
  674. )
  675. installed = bool(completed and completed.returncode == 0)
  676. lines = (completed.stdout if completed else "").strip().splitlines()
  677. return {
  678. "name": "nvm",
  679. "installed": installed,
  680. "path": lines[0] if lines else None,
  681. "version": lines[-1] if len(lines) > 1 else None,
  682. "installableByScript": system in {"Darwin", "Linux"},
  683. "advice": "Install nvm first, then use `nvm install --lts`, `nvm alias default 'lts/*'`, and `nvm use --lts`.",
  684. }
  685. def activate_nvm_node_path() -> str | None:
  686. if platform.system() == "Windows":
  687. return None
  688. completed = shell_result(
  689. f"{nvm_load_script()}; "
  690. "(nvm use --lts >/dev/null 2>&1 || nvm use default >/dev/null 2>&1 || true); "
  691. "command -v npm",
  692. timeout=20,
  693. )
  694. if not completed or completed.returncode != 0:
  695. return None
  696. npm_path = (
  697. completed.stdout.strip().splitlines()[-1] if completed.stdout.strip() else ""
  698. )
  699. if not npm_path:
  700. return None
  701. npm_bin = str(Path(npm_path).parent)
  702. current = os.environ.get("PATH", "")
  703. if npm_bin not in current.split(os.pathsep):
  704. os.environ["PATH"] = f"{npm_bin}{os.pathsep}{current}"
  705. return npm_bin
  706. def check_npm_runtime() -> dict[str, object]:
  707. if not shutil.which("npm"):
  708. activate_nvm_node_path()
  709. npm_path = shutil.which("npm")
  710. node_path = shutil.which("node")
  711. npm_version = command_version("npm", ("--version",)) if npm_path else None
  712. node_version = command_version("node", ("--version",)) if node_path else None
  713. nvm = check_nvm()
  714. return {
  715. "platform": platform.system() or sys.platform,
  716. "npm": {
  717. "installed": bool(npm_path and npm_version),
  718. "path": npm_path,
  719. "version": npm_version,
  720. },
  721. "node": {
  722. "installed": bool(node_path and node_version),
  723. "path": node_path,
  724. "version": node_version,
  725. },
  726. "nvm": nvm,
  727. "advice": "Local tool detection does not require npm. Installing a selected npm-backed tool requires npm and explicit confirmation.",
  728. }
  729. def check_cli_tool(spec: dict[str, str | tuple[str, ...]]) -> dict[str, object]:
  730. name = str(spec["name"])
  731. path = shutil.which(name)
  732. version = command_version(name, spec["versionArgs"]) if path else None
  733. installed = bool(path and version)
  734. result = {
  735. "name": name,
  736. "category": "cli",
  737. "installed": installed,
  738. "path": path,
  739. "version": version,
  740. "globalInstall": spec["globalInstall"],
  741. "projectInstall": spec["projectInstall"],
  742. "advice": spec["advice"],
  743. }
  744. if name == "rtk" and path:
  745. with tempfile.TemporaryDirectory(prefix="sbtd-rtk-probe-") as probe_home:
  746. probe_env = {
  747. key: value
  748. for key, value in os.environ.items()
  749. if not key.upper().startswith("RTK_")
  750. }
  751. probe_env.update(
  752. HOME=probe_home,
  753. USERPROFILE=probe_home,
  754. XDG_CONFIG_HOME=str(Path(probe_home) / "config"),
  755. XDG_CACHE_HOME=str(Path(probe_home) / "cache"),
  756. XDG_DATA_HOME=str(Path(probe_home) / "data"),
  757. XDG_STATE_HOME=str(Path(probe_home) / "state"),
  758. )
  759. completed = run_command(
  760. (str(Path(path).resolve()), "gain"),
  761. timeout=10,
  762. env=probe_env,
  763. cwd=Path(probe_home),
  764. )
  765. code = completed.returncode if completed else None
  766. output = (
  767. (completed.stdout or completed.stderr).strip() if completed else ""
  768. )
  769. result["verificationScope"] = "isolated-probe"
  770. correct = code == 0
  771. version_looks_correct = bool(version and version.lower().startswith("rtk "))
  772. result["installed"] = correct
  773. result["rtkGainVerified"] = correct
  774. result["wrongPackageSuspected"] = not correct and not version_looks_correct
  775. result["verificationFailed"] = not correct and version_looks_correct
  776. result["verifyCommand"] = "rtk gain"
  777. result["verifyOutput"] = output.splitlines()[0] if output else None
  778. if result["wrongPackageSuspected"]:
  779. result["advice"] = (
  780. "An `rtk` command exists but `rtk gain` failed, so this may be the wrong rtk package. Confirm before uninstalling or replacing it."
  781. )
  782. elif result["verificationFailed"]:
  783. result["advice"] = (
  784. "The rtk binary looks like rtk-ai/rtk, but its isolated gain probe failed. Inspect the binary and probe error before choosing repair; the user's history directory was not tested."
  785. )
  786. elif name == "rtk":
  787. result["rtkGainVerified"] = False
  788. result["wrongPackageSuspected"] = False
  789. result["verificationFailed"] = False
  790. result["verifyCommand"] = "rtk gain"
  791. return result
  792. def normalize_agent_platform(value: str) -> str:
  793. normalized = value.strip().lower().replace("_", "-")
  794. platform_name = AGENT_PLATFORM_ALIASES.get(normalized)
  795. if not platform_name:
  796. allowed = ", ".join(("codex", "claude", "kimi", "oh-my-pi", "omp"))
  797. raise SystemExit(
  798. f"Unsupported Agent platform: {value}. Allowed values: {allowed}"
  799. )
  800. return platform_name
  801. def check_agent_cli(platform_value: str) -> dict[str, object]:
  802. platform_name = normalize_agent_platform(platform_value)
  803. spec = AGENT_CLI_SPECS[platform_name]
  804. command = str(spec["command"])
  805. version_args = tuple(str(item) for item in spec["versionArgs"])
  806. path = shutil.which(command)
  807. code, output = (
  808. command_output((command, *version_args), timeout=10) if path else (None, "")
  809. )
  810. version = output.splitlines()[0] if code == 0 and output else None
  811. npm_package = str(spec["npmPackage"])
  812. result: dict[str, object] = {
  813. "mode": "check-agent-cli",
  814. "platform": platform_name,
  815. "label": spec["label"],
  816. "command": command,
  817. "path": path,
  818. "version": version,
  819. "installed": bool(path and version),
  820. "npmPackage": npm_package,
  821. "installCommand": f"npm install -g {npm_package}@latest",
  822. "verifyCommand": command_display((command, *version_args)),
  823. "advice": spec["advice"],
  824. "runtime": check_npm_runtime(),
  825. }
  826. if path and not version:
  827. result["verificationFailed"] = True
  828. result["verifyOutput"] = output.splitlines()[0] if output else None
  829. return result
  830. def print_agent_cli_check(result: dict[str, object], as_json: bool) -> None:
  831. if as_json:
  832. print(json.dumps(result, indent=2, ensure_ascii=False))
  833. return
  834. status = "installed" if result["installed"] else "missing"
  835. if result.get("verificationFailed"):
  836. status = "verification-failed"
  837. print(f"Target Agent CLI: {result['label']}")
  838. print(f"- status: {status}")
  839. print(f"- command: {result['command']}")
  840. if result.get("path"):
  841. print(f"- path: {result['path']}")
  842. if result.get("version"):
  843. print(f"- version: {result['version']}")
  844. if not result["installed"]:
  845. print(f"- install: {result['installCommand']}")
  846. print(f"- advice: {result['advice']}")
  847. def parse_java_major(output: str | None) -> int | None:
  848. if not output:
  849. return None
  850. match = re.search(
  851. r'(?:openjdk|java)?\s*version\s+"?(\d+)(?:\.(\d+))?', output, re.IGNORECASE
  852. )
  853. if not match:
  854. match = re.search(r"\b(\d+)(?:\.(\d+))?\.\d+", output)
  855. if not match:
  856. return None
  857. first = int(match.group(1))
  858. second = match.group(2)
  859. if first == 1 and second:
  860. return int(second)
  861. return first
  862. def java_version_output() -> tuple[str | None, str | None]:
  863. code, output = command_output(("java", "--version"), timeout=5)
  864. if code == 0 and output:
  865. return output.splitlines()[0], "java --version"
  866. code, output = command_output(("java", "-version"), timeout=5)
  867. if code == 0 and output:
  868. return output.splitlines()[0], "java -version"
  869. return None, "java --version"
  870. def java_binary_path(java_home: str | Path) -> Path:
  871. """Resolve the Java launcher inside a JDK home directory.
  872. Windows JDKs ship ``bin/java.exe``; other platforms ship ``bin/java``.
  873. Windows accepts both names so cross-platform JDK layouts still resolve.
  874. """
  875. home = Path(java_home)
  876. if platform.system() == "Windows":
  877. for name in ("java.exe", "java"):
  878. candidate = home / "bin" / name
  879. if candidate.is_file():
  880. return candidate
  881. return home / "bin" / "java.exe"
  882. return home / "bin" / "java"
  883. def usable_java_home(candidate: str | Path | None) -> Path | None:
  884. if not candidate:
  885. return None
  886. path = Path(candidate).expanduser()
  887. if java_binary_path(path).is_file():
  888. return path.resolve()
  889. return None
  890. def java_binary_version(java_binary: Path) -> tuple[str | None, str | None]:
  891. code, output = command_output((str(java_binary), "--version"), timeout=5)
  892. if code == 0 and output:
  893. return output.splitlines()[0], f"{java_binary} --version"
  894. code, output = command_output((str(java_binary), "-version"), timeout=5)
  895. if code == 0 and output:
  896. return output.splitlines()[0], f"{java_binary} -version"
  897. return None, f"{java_binary} --version"
  898. def java_home_major(java_home: Path) -> int | None:
  899. version, _ = java_binary_version(java_binary_path(java_home))
  900. return parse_java_major(version)
  901. def macos_java_home(major: int | None = None) -> Path | None:
  902. if platform.system() != "Darwin":
  903. return None
  904. helper = Path("/usr/libexec/java_home")
  905. if not helper.is_file():
  906. return None
  907. command = (str(helper), "-v", str(major)) if major else (str(helper),)
  908. code, output = command_output(command, timeout=5)
  909. if code != 0 or not output:
  910. return None
  911. return usable_java_home(output.splitlines()[0].strip())
  912. def infer_java_home_from_path(java_path: str | None) -> Path | None:
  913. if java_path:
  914. java_bin = Path(java_path).expanduser().resolve()
  915. if platform.system() == "Darwin" and java_bin == Path("/usr/bin/java"):
  916. return None
  917. is_java_launcher = (
  918. java_bin.name.lower() in {"java", "java.exe"}
  919. if platform.system() == "Windows"
  920. else java_bin.name == "java"
  921. )
  922. if is_java_launcher and java_bin.parent.name == "bin":
  923. inferred = usable_java_home(java_bin.parent.parent)
  924. if inferred:
  925. return inferred
  926. return None
  927. def java_home_candidates(java_path: str | None) -> list[Path]:
  928. candidates: list[Path] = []
  929. def add(candidate: str | Path | None) -> None:
  930. java_home = usable_java_home(candidate)
  931. if java_home and java_home not in candidates:
  932. candidates.append(java_home)
  933. add(infer_java_home_from_path(java_path))
  934. add(os.environ.get("JAVA_HOME"))
  935. add(macos_java_home())
  936. add(macos_java_home(JAVA_MIN_MAJOR))
  937. patterns = (
  938. Path.home() / "JDK" / "*" / "Contents" / "Home",
  939. Path.home() / "JDK" / "*",
  940. Path.home()
  941. / "Library"
  942. / "Java"
  943. / "JavaVirtualMachines"
  944. / "*"
  945. / "Contents"
  946. / "Home",
  947. Path("/Library/Java/JavaVirtualMachines") / "*" / "Contents" / "Home",
  948. Path("/usr/lib/jvm") / "*",
  949. )
  950. for pattern in patterns:
  951. for candidate in pattern.parent.glob(pattern.name):
  952. add(candidate)
  953. return candidates
  954. def select_java_home(
  955. java_path: str | None,
  956. ) -> tuple[Path | None, int | None, str | None]:
  957. candidates = java_home_candidates(java_path)
  958. candidate_info: list[tuple[Path, int | None]] = [
  959. (candidate, java_home_major(candidate)) for candidate in candidates
  960. ]
  961. if (
  962. candidate_info
  963. and candidate_info[0][1]
  964. and candidate_info[0][1] >= JAVA_MIN_MAJOR
  965. ):
  966. return candidate_info[0][0], candidate_info[0][1], "current-java-home"
  967. for candidate, major in candidate_info[1:] if candidate_info else []:
  968. if major and major >= JAVA_MIN_MAJOR:
  969. return candidate, major, "alternate-installed-jdk"
  970. return None, None, None
  971. def unique_path_entries(entries: list[str | None]) -> list[str]:
  972. result: list[str] = []
  973. seen: set[str] = set()
  974. for entry in entries:
  975. if not entry or entry in seen:
  976. continue
  977. seen.add(entry)
  978. result.append(entry)
  979. return result
  980. def maestro_bin_dir(maestro_path: str | None) -> str:
  981. if maestro_path:
  982. return str(Path(maestro_path).expanduser().parent)
  983. return str(Path.home() / ".maestro" / "bin")
  984. def mcp_path_value(java_home: str | None, maestro_path: str | None) -> str:
  985. java_bin = f"{java_home}/bin" if java_home else "<JAVA_HOME>/bin"
  986. return os.pathsep.join(
  987. unique_path_entries(
  988. [
  989. maestro_bin_dir(maestro_path),
  990. java_bin,
  991. "/usr/local/bin",
  992. "/opt/homebrew/bin",
  993. "/usr/bin",
  994. "/bin",
  995. "/usr/sbin",
  996. "/sbin",
  997. ]
  998. )
  999. )
  1000. def toml_string(value: str) -> str:
  1001. return value.replace("\\", "\\\\").replace('"', '\\"')
  1002. def maestro_mcp_environment(
  1003. java_check: dict[str, object], maestro_check: dict[str, object]
  1004. ) -> dict[str, str]:
  1005. java_home = str(java_check.get("javaHome") or "<JAVA_HOME>")
  1006. path_value = mcp_path_value(
  1007. str(java_check.get("javaHome")) if java_check.get("javaHome") else None,
  1008. str(maestro_check.get("path")) if maestro_check.get("path") else None,
  1009. )
  1010. return {"JAVA_HOME": java_home, "PATH": path_value}
  1011. def maestro_mcp_server_config(
  1012. java_check: dict[str, object], maestro_check: dict[str, object]
  1013. ) -> dict[str, object]:
  1014. return {
  1015. "command": "maestro",
  1016. "args": ["mcp"],
  1017. "env": maestro_mcp_environment(java_check, maestro_check),
  1018. }
  1019. def maestro_mcp_toml_example(
  1020. java_check: dict[str, object], maestro_check: dict[str, object]
  1021. ) -> str:
  1022. env = maestro_mcp_environment(java_check, maestro_check)
  1023. return "\n".join(
  1024. [
  1025. "[mcp_servers.maestro]",
  1026. 'command = "maestro"',
  1027. 'args = ["mcp"]',
  1028. "",
  1029. "[mcp_servers.maestro.env]",
  1030. f'JAVA_HOME = "{toml_string(env["JAVA_HOME"])}"',
  1031. f'PATH = "{toml_string(env["PATH"])}"',
  1032. ]
  1033. )
  1034. def maestro_mcp_json_example(
  1035. java_check: dict[str, object], maestro_check: dict[str, object]
  1036. ) -> str:
  1037. return json.dumps(
  1038. {
  1039. "mcpServers": {
  1040. "maestro": maestro_mcp_server_config(java_check, maestro_check)
  1041. }
  1042. },
  1043. indent=2,
  1044. ensure_ascii=False,
  1045. )
  1046. def maestro_mcp_config_examples(
  1047. java_check: dict[str, object], maestro_check: dict[str, object]
  1048. ) -> dict[str, str]:
  1049. return {
  1050. "genericJson": maestro_mcp_json_example(java_check, maestro_check),
  1051. "toml": maestro_mcp_toml_example(java_check, maestro_check),
  1052. }
  1053. def maestro_cli_env(java_check: dict[str, object]) -> dict[str, str] | None:
  1054. java_home = java_check.get("javaHome")
  1055. if not java_home:
  1056. return None
  1057. env = os.environ.copy()
  1058. env["JAVA_HOME"] = str(java_home)
  1059. env["PATH"] = os.pathsep.join(
  1060. unique_path_entries([f"{java_home}/bin", os.environ.get("PATH")])
  1061. )
  1062. return env
  1063. def build_maestro_mcp_manual_check(
  1064. java_check: dict[str, object],
  1065. maestro_check: dict[str, object],
  1066. ) -> dict[str, object]:
  1067. java_home = java_check.get("javaHome")
  1068. maestro_ready = bool(maestro_check.get("installed"))
  1069. server_config = maestro_mcp_server_config(java_check, maestro_check)
  1070. config_examples = maestro_mcp_config_examples(java_check, maestro_check)
  1071. readiness = (
  1072. "Detected Java 17+ and Maestro CLI; adapt the generated command, args, and env values to the active Agent or IDE MCP configuration format."
  1073. if java_home and maestro_ready
  1074. else "Complete Java 17+ and Maestro CLI setup first, then replace any placeholder values before enabling Maestro MCP in the active Agent or IDE."
  1075. )
  1076. return {
  1077. "name": "Maestro MCP",
  1078. "category": "mcp",
  1079. "advice": "Maestro MCP depends on Java 17+, a working Maestro CLI, and explicit MCP environment variables for JAVA_HOME and PATH.",
  1080. "mcpServerConfig": server_config,
  1081. "environment": server_config["env"],
  1082. "configExample": config_examples["genericJson"],
  1083. "configExamples": config_examples,
  1084. "steps": (
  1085. "Confirm Java 17+ is available with `java --version` or `java -version`; prefer the JDK currently used by the local machine when it is 17+, otherwise choose an installed JDK that is 17 or higher before installing a new JDK.",
  1086. "Confirm the Maestro CLI works, for example with `maestro --help` and `maestro test --help`; ensure the MCP PATH includes the directory that contains the `maestro` binary.",
  1087. readiness,
  1088. "Configure the active Agent or IDE MCP settings with `command = maestro`, `args = [mcp]`, and the generated env values. Do not configure only command and args; include `JAVA_HOME` and `PATH` so `maestro mcp` can find Java and Maestro in the MCP server process environment.",
  1089. "Restart or reload the Agent environment so the MCP server is discovered.",
  1090. "Confirm Maestro MCP tools are visible before relying on device inspection, view hierarchy, screenshots, or flow assistance.",
  1091. "If Maestro MCP is unavailable but Maestro CLI works, continue deterministic flow execution through `maestro test` and report MCP separately.",
  1092. ),
  1093. }
  1094. REACT_PROJECT_DEPENDENCY_MARKERS = (
  1095. "react",
  1096. "react-dom",
  1097. "next",
  1098. "@vitejs/plugin-react",
  1099. "@vitejs/plugin-react-swc",
  1100. "@remix-run/react",
  1101. "@tanstack/react-router",
  1102. "@tanstack/react-start",
  1103. )
  1104. def project_dependencies(package_data: dict[str, object] | None) -> dict[str, object]:
  1105. dependencies: dict[str, object] = {}
  1106. if not package_data:
  1107. return dependencies
  1108. for key in (
  1109. "dependencies",
  1110. "devDependencies",
  1111. "optionalDependencies",
  1112. "peerDependencies",
  1113. ):
  1114. value = package_data.get(key)
  1115. if isinstance(value, dict):
  1116. dependencies.update(value)
  1117. return dependencies
  1118. def is_react_project(project_root: Path | None) -> bool:
  1119. dependencies = project_dependencies(project_package_json(project_root))
  1120. return any(marker in dependencies for marker in REACT_PROJECT_DEPENDENCY_MARKERS)
  1121. def has_shadcn_components_config(project_root: Path | None) -> bool:
  1122. return bool(project_root and (project_root / "components.json").is_file())
  1123. def should_check_react_bits_tier(project_root: Path | None) -> bool:
  1124. return bool(
  1125. project_root
  1126. and is_react_project(project_root)
  1127. and has_shadcn_components_config(project_root)
  1128. )
  1129. def build_react_bits_tier_manual_check(project_root: Path) -> dict[str, object]:
  1130. components_json = project_root / "components.json"
  1131. return {
  1132. "name": "React Bits tier selection",
  1133. "category": "conditional-project-skill",
  1134. "advice": "A React + shadcn/ui project was detected. Keep the default as shadcn/ui only; ask before adding React Bits Free, Starter, Pro, or Ultimate. Do not print or store any React Bits license key.",
  1135. "detected": {
  1136. "projectRoot": str(project_root),
  1137. "componentsJson": str(components_json),
  1138. "reactProject": True,
  1139. },
  1140. "steps": (
  1141. "Tell the user that shadcn/ui covers normal application components, while React Bits Free or paid tiers are optional sources for more expressive animated components, blocks, or landing sections.",
  1142. "Ask whether this project should stay with shadcn/ui only, add React Bits Free, or use an existing paid Starter / Pro / Ultimate entitlement.",
  1143. "For React Bits Free, install only after the user confirms and a free source or registry has been explicitly configured for this workflow.",
  1144. "For paid tiers, require explicit user confirmation and verify the current environment can read `REACTBITS_LICENSE_KEY` without printing it.",
  1145. "When paid prerequisites are met and the user selects a paid tier, run `npx shadcn@latest add @reactbits-starter/skill --path .agents/skills/react-bits-pro --overwrite --yes` from the project root even when the target Skill already exists, then confirm `.agents/skills/react-bits-pro/SKILL.md` exists before using it.",
  1146. "During reset, preserve the detected React Bits tier and registry; do not replace Free, Starter, Pro, or Ultimate with a different default tier without confirmation.",
  1147. ),
  1148. }
  1149. def build_manual_checks(
  1150. java_check: dict[str, object],
  1151. maestro_check: dict[str, object],
  1152. project_root: Path | None,
  1153. ) -> tuple[dict[str, object], ...]:
  1154. checks = list(cast(tuple[dict[str, object], ...], BASE_MANUAL_CHECKS))
  1155. checks.insert(2, build_maestro_mcp_manual_check(java_check, maestro_check))
  1156. if project_root and should_check_react_bits_tier(project_root):
  1157. checks.append(build_react_bits_tier_manual_check(project_root))
  1158. return tuple(checks)
  1159. def check_java_for_maestro() -> dict[str, object]:
  1160. path = shutil.which("java")
  1161. current_version, current_version_command = (
  1162. java_version_output() if path else (None, "java --version")
  1163. )
  1164. current_major = parse_java_major(current_version)
  1165. java_home, java_home_major_value, java_home_source = select_java_home(path)
  1166. if java_home:
  1167. selected_version, selected_version_command = java_binary_version(
  1168. java_binary_path(java_home)
  1169. )
  1170. selected_major = parse_java_major(selected_version) or java_home_major_value
  1171. else:
  1172. selected_version, selected_version_command, selected_major = (
  1173. current_version,
  1174. current_version_command,
  1175. current_major,
  1176. )
  1177. installed = bool(java_home and selected_major and selected_major >= JAVA_MIN_MAJOR)
  1178. result: dict[str, object] = {
  1179. "name": "java",
  1180. "category": "runtime",
  1181. "installed": installed,
  1182. "path": str(java_binary_path(java_home)) if installed and java_home else path,
  1183. "currentPath": path,
  1184. "currentVersion": current_version,
  1185. "currentVersionMajor": current_major,
  1186. "currentVersionCommand": current_version_command,
  1187. "javaHome": str(java_home) if java_home else None,
  1188. "javaHomeSource": java_home_source,
  1189. "version": selected_version,
  1190. "versionMajor": selected_major,
  1191. "versionCommand": selected_version_command,
  1192. "globalInstall": f"Install the latest OpenJDK Temurin 21 JDK from {TEMURIN21_RELEASES_URL}",
  1193. "projectInstall": None,
  1194. "advice": "Maestro requires Java 17+. Prefer the local machine's current JDK when it is 17+; if it is missing or lower than 17, use another installed JDK that is 17+ before asking to install a new JDK. Default new installs to the latest OpenJDK Temurin 21 JDK; user-selected versions must be 17 or higher.",
  1195. }
  1196. if not installed and path and current_major and current_major < JAVA_MIN_MAJOR:
  1197. result["incompatibleVersion"] = True
  1198. if (
  1199. installed
  1200. and current_major
  1201. and current_major < JAVA_MIN_MAJOR
  1202. and java_home_source == "alternate-installed-jdk"
  1203. ):
  1204. result["reason"] = (
  1205. "The current `java` is lower than 17, but another installed JDK satisfies Maestro's Java prerequisite."
  1206. )
  1207. return result
  1208. def check_maestro_cli(java_check: dict[str, object]) -> dict[str, object]:
  1209. if not java_check.get("installed"):
  1210. return {
  1211. "name": "maestro",
  1212. "category": "cli",
  1213. "installed": False,
  1214. "path": None,
  1215. "version": None,
  1216. "notChecked": True,
  1217. "reason": "Java 17+ is required before Maestro CLI can be checked.",
  1218. "globalInstall": "Install Java 17+ first, then install Maestro CLI with the official Maestro instructions.",
  1219. "projectInstall": None,
  1220. "advice": "Resolve the Java 17+ prerequisite first. Maestro MCP is unavailable until Maestro CLI works.",
  1221. }
  1222. path = shutil.which("maestro")
  1223. env = maestro_cli_env(java_check)
  1224. code, output = (
  1225. command_output(("maestro", "--version"), timeout=10, env=env)
  1226. if path
  1227. else (None, "")
  1228. )
  1229. first_line = output.splitlines()[0] if output else None
  1230. version = (
  1231. first_line
  1232. if code == 0 and first_line and not first_line.lower().startswith("exception")
  1233. else None
  1234. )
  1235. result: dict[str, object] = {
  1236. "name": "maestro",
  1237. "category": "cli",
  1238. "installed": bool(path and version),
  1239. "path": path,
  1240. "binDir": maestro_bin_dir(path),
  1241. "version": version,
  1242. "globalInstall": "Install Maestro CLI with the official Maestro installer or Homebrew tap after user confirmation.",
  1243. "projectInstall": None,
  1244. "advice": "Install Maestro CLI into the local development environment or CI runner after Java 17+ is available. Then configure Maestro MCP separately if needed.",
  1245. }
  1246. if path and not version:
  1247. result["verificationFailed"] = True
  1248. result["verifyCommand"] = "maestro --version"
  1249. result["verifyOutput"] = first_line
  1250. return result
  1251. def project_package_json(project_root: Path | None) -> dict[str, object] | None:
  1252. if not project_root:
  1253. return None
  1254. package_json = project_root / "package.json"
  1255. if not package_json.is_file():
  1256. return None
  1257. try:
  1258. return json.loads(package_json.read_text(encoding="utf-8"))
  1259. except json.JSONDecodeError:
  1260. return None
  1261. def check_playwright_project(project_root: Path | None) -> dict[str, object]:
  1262. package_data = project_package_json(project_root)
  1263. config_paths: list[str] = []
  1264. e2e_paths: list[str] = []
  1265. if project_root:
  1266. for name in (
  1267. "playwright.config.ts",
  1268. "playwright.config.js",
  1269. "playwright.config.mts",
  1270. "playwright.config.cts",
  1271. ):
  1272. candidate = project_root / name
  1273. if candidate.is_file():
  1274. config_paths.append(str(candidate))
  1275. for name in ("tests/e2e", "e2e", "playwright-report", "test-results"):
  1276. candidate = project_root / name
  1277. if candidate.exists():
  1278. e2e_paths.append(str(candidate))
  1279. dependencies: dict[str, object] = {}
  1280. scripts: dict[str, object] = {}
  1281. if package_data:
  1282. for key in ("dependencies", "devDependencies", "optionalDependencies"):
  1283. value = package_data.get(key)
  1284. if isinstance(value, dict):
  1285. dependencies.update(value)
  1286. value = package_data.get("scripts")
  1287. if isinstance(value, dict):
  1288. scripts = value
  1289. has_dependency = "@playwright/test" in dependencies or "playwright" in dependencies
  1290. playwright_scripts = {
  1291. key: value
  1292. for key, value in scripts.items()
  1293. if isinstance(value, str) and "playwright" in value
  1294. }
  1295. installed = bool(has_dependency or config_paths or playwright_scripts)
  1296. has_project_markers = bool(
  1297. has_dependency or config_paths or e2e_paths or playwright_scripts
  1298. )
  1299. not_checked = project_root is None or not has_project_markers
  1300. reason = None
  1301. if project_root is None:
  1302. reason = "No project root was provided, so project-level Playwright readiness was not checked."
  1303. elif not has_project_markers:
  1304. reason = "No package.json, Playwright config, or E2E directory was detected under the target project root."
  1305. return {
  1306. "name": "Playwright CLI",
  1307. "category": "project-cli",
  1308. "installed": installed,
  1309. "applicable": not not_checked,
  1310. "path": str(project_root) if project_root else None,
  1311. "version": dependencies.get("@playwright/test")
  1312. or dependencies.get("playwright"),
  1313. "notChecked": not_checked,
  1314. "reason": reason,
  1315. "configPaths": config_paths,
  1316. "e2ePaths": e2e_paths,
  1317. "scripts": playwright_scripts,
  1318. "globalInstall": "Do not install Playwright globally by default.",
  1319. "projectInstall": "npm init playwright@latest or npm install -D @playwright/test, then npx playwright install",
  1320. "advice": "Playwright CLI is a project-level Web E2E dependency. If Web regression or web-ui-autotest-generator needs it and it is missing, ask the user before installing it into the target project.",
  1321. }
  1322. def check_react_bits_project(project_root: Path) -> dict[str, object]:
  1323. applicable = should_check_react_bits_tier(project_root)
  1324. result: dict[str, object] = {
  1325. "applicable": applicable,
  1326. "projectRoot": str(project_root),
  1327. "componentsJson": str(project_root / "components.json") if applicable else None,
  1328. "selectionRequired": applicable,
  1329. }
  1330. if applicable:
  1331. result["manualCheck"] = build_react_bits_tier_manual_check(project_root)
  1332. else:
  1333. result["reason"] = (
  1334. "React Bits applies only when the project is React-based and has "
  1335. "shadcn/ui initialized through components.json."
  1336. )
  1337. return result
  1338. def build_project_check(
  1339. project_root: Path, skip_agents: bool = False
  1340. ) -> dict[str, object]:
  1341. from sbtd_language_tooling import detect_project_languages
  1342. return {
  1343. "projectRoot": str(project_root),
  1344. "playwright": check_playwright_project(project_root),
  1345. "reactBits": check_react_bits_project(project_root),
  1346. "sbtd": inspect_project_setup(project_root, skip_agents),
  1347. "languages": detect_project_languages(project_root),
  1348. }
  1349. def build_projects_check_results(args: argparse.Namespace) -> dict[str, object]:
  1350. project_roots = resolve_project_roots(args, required=True)
  1351. return {
  1352. "mode": "check-projects",
  1353. "projects": [
  1354. build_project_check(
  1355. project_root, bool(getattr(args, "skip_project_agents", False))
  1356. )
  1357. for project_root in project_roots
  1358. ],
  1359. }
  1360. def print_projects_check_results(results: dict[str, object], as_json: bool) -> None:
  1361. if as_json:
  1362. print(json.dumps(results, indent=2, ensure_ascii=False))
  1363. return
  1364. print("Project checks:")
  1365. for item in results["projects"]:
  1366. print(f"- project root: {item['projectRoot']}")
  1367. playwright = item["playwright"]
  1368. print(
  1369. " Playwright CLI: "
  1370. + (
  1371. "installed"
  1372. if playwright["installed"]
  1373. else "missing"
  1374. if playwright["applicable"]
  1375. else "not-needed"
  1376. )
  1377. )
  1378. react_bits = item["reactBits"]
  1379. print(
  1380. " React Bits tier selection: "
  1381. + ("required" if react_bits["applicable"] else "not-needed")
  1382. )
  1383. sbtd = item["sbtd"]
  1384. print(f" SBTD state: {sbtd['status']}")
  1385. print(f" Reason: {sbtd['reason']}")
  1386. if sbtd["nextStep"]:
  1387. print(f" Next step: {sbtd['nextStep']}")
  1388. languages = item.get("languages") or []
  1389. names = (
  1390. ", ".join(str(entry["display"]) for entry in languages)
  1391. if languages
  1392. else "none detected"
  1393. )
  1394. print(f" Languages: {names}")
  1395. def check_skill(
  1396. name: str, group: str, global_dir: Path, project_dir: Path | None
  1397. ) -> dict[str, object]:
  1398. locations: list[dict[str, str]] = []
  1399. global_candidate = global_dir / name / "SKILL.md"
  1400. global_valid = (
  1401. external_skill_target_is_valid(global_dir, name)
  1402. if group == "referenced"
  1403. else global_candidate.is_file()
  1404. )
  1405. if global_valid:
  1406. locations.append({"scope": "global", "path": str(global_candidate)})
  1407. if project_dir:
  1408. project_candidate = project_dir / name / "SKILL.md"
  1409. project_valid = (
  1410. external_skill_target_is_valid(project_dir, name)
  1411. if group == "referenced"
  1412. else project_candidate.is_file()
  1413. )
  1414. if project_valid:
  1415. locations.append({"scope": "project", "path": str(project_candidate)})
  1416. return {
  1417. "name": name,
  1418. "category": "skill",
  1419. "group": group,
  1420. "installed": bool(locations),
  1421. "locations": locations,
  1422. "globalTarget": str(global_dir / name / "SKILL.md"),
  1423. "projectTarget": str(project_dir / name / "SKILL.md") if project_dir else None,
  1424. "sourceRepo": EXTERNAL_SKILL_SOURCES.get(name, {}).get("repo")
  1425. if group == "referenced"
  1426. else None,
  1427. }
  1428. def report_entry(
  1429. name: str,
  1430. status: str,
  1431. *,
  1432. path: str | None = None,
  1433. version: str | None = None,
  1434. scope: str | None = None,
  1435. reason: str | None = None,
  1436. next_step: str | None = None,
  1437. source_repo: str | None = None,
  1438. ) -> dict[str, object]:
  1439. entry: dict[str, object] = {"name": name, "status": status}
  1440. optional = {
  1441. "path": path,
  1442. "version": version,
  1443. "scope": scope,
  1444. "reason": reason,
  1445. "nextStep": next_step,
  1446. "sourceRepo": source_repo,
  1447. }
  1448. for key, value in optional.items():
  1449. if value:
  1450. entry[key] = value
  1451. return entry
  1452. def cli_failure_reason(item: dict[str, object]) -> str:
  1453. name = str(item["name"])
  1454. if item.get("category") == "project-cli":
  1455. reason = f"No project-level Playwright dependency, config, script, or E2E directory was detected under {item.get('path') or 'the target project root'}."
  1456. elif item.get("incompatibleVersion"):
  1457. reason = f"`{name}` exists at {item.get('path')}, but version {item.get('version')} is lower than the required Java {JAVA_MIN_MAJOR}+ for Maestro."
  1458. elif item.get("notChecked") and item.get("reason"):
  1459. reason = str(item["reason"])
  1460. elif item.get("wrongPackageSuspected"):
  1461. reason = f"`{name}` exists at {item.get('path')}, but `{item.get('verifyCommand')}` failed; it may be a different same-name package."
  1462. elif item.get("verificationFailed"):
  1463. reason = f"`{name}` exists at {item.get('path')}, but `{item.get('verifyCommand')}` failed."
  1464. elif not item.get("path"):
  1465. reason = f"`{name}` command was not found in PATH."
  1466. elif not item.get("version"):
  1467. reason = f"`{name}` exists at {item.get('path')}, but the version command returned no usable output."
  1468. else:
  1469. reason = f"`{name}` did not pass the installer verification checks."
  1470. verify_output = item.get("verifyOutput")
  1471. if verify_output:
  1472. reason += f" First verification output: {verify_output}"
  1473. return reason
  1474. def cli_next_step(item: dict[str, object]) -> str:
  1475. if item.get("notChecked") and item.get("advice"):
  1476. return str(item["advice"])
  1477. return (
  1478. "Install or repair the required global tool, then rerun the check. "
  1479. f"Suggested command: {item['globalInstall']}"
  1480. )
  1481. def skill_failure_reason(item: dict[str, object]) -> str:
  1482. if item["name"] == "caveman":
  1483. return (
  1484. "No `caveman/SKILL.md` was found in the checked global skills directory: "
  1485. + str(item["globalTarget"])
  1486. )
  1487. targets = [str(item["globalTarget"])]
  1488. if item.get("projectTarget"):
  1489. targets.append(str(item["projectTarget"]))
  1490. return "No `SKILL.md` was found at the checked target path(s): " + ", ".join(
  1491. targets
  1492. )
  1493. def _powershell_quote(part: str) -> str:
  1494. """Quote one token for PowerShell, only when it actually needs quoting.
  1495. A conservative whitelist of characters passes through unquoted (same idea
  1496. as `shlex.join` on POSIX); anything else is wrapped in a single-quoted
  1497. literal, where `'` is the only character requiring escape (doubling) and
  1498. `$`, `%VAR%`, `!VAR!` stay literal. cmd.exe is not a supported target.
  1499. """
  1500. if re.fullmatch(r"[A-Za-z0-9_./:\\=-]+", part):
  1501. return part
  1502. return "'" + part.replace("'", "''") + "'"
  1503. def shell_quote_path(path: Path) -> str:
  1504. """Quote one path for the shell that `onboard_command()` targets.
  1505. POSIX hosts get `shlex.quote`, so whitespace, `$`, backticks and glob
  1506. characters stay literal in sh / bash / zsh. Windows hosts get PowerShell
  1507. quoting via `_powershell_quote()`.
  1508. """
  1509. text = str(path)
  1510. if os.name == "nt":
  1511. return _powershell_quote(text)
  1512. return shlex.quote(text)
  1513. def render_shell_command(argv: list[str]) -> str:
  1514. """Render argv as one runnable command for the host shell.
  1515. POSIX: `shlex.join`. Windows: tokens that need it get PowerShell single
  1516. quoting; the call operator `&` is only prefixed when the program name had
  1517. to be quoted, because a leading quoted string is otherwise evaluated as an
  1518. expression instead of being executed.
  1519. """
  1520. if os.name == "nt":
  1521. quoted = [_powershell_quote(part) for part in argv]
  1522. command = " ".join(quoted)
  1523. return ("& " + command) if quoted[0].startswith("'") else command
  1524. return shlex.join(argv)
  1525. def onboard_command(*args: str) -> str:
  1526. """Build a cwd-independent `python <onboard.py> ...` command string.
  1527. Repair hints are read from arbitrary project directories, so the script
  1528. path must be the installed absolute path rather than `scripts/onboard.py`.
  1529. On Windows the rendered command is PowerShell-only; see `shell_prefix()`.
  1530. """
  1531. return render_shell_command(["python", str(ONBOARD_SCRIPT_PATH), *args])
  1532. def shell_prefix() -> str:
  1533. """Human-readable lead-in naming the shell a hint is rendered for."""
  1534. return "Run in PowerShell: " if os.name == "nt" else ""
  1535. def skill_next_step(item: dict[str, object]) -> str:
  1536. name = str(item["name"])
  1537. if name == "caveman":
  1538. return (
  1539. f"{shell_prefix()}After user confirmation, install the Codex skill with "
  1540. f"`{onboard_command('install-caveman', '--yes')}`, then rerun `check`."
  1541. )
  1542. if item.get("sourceRepo"):
  1543. return (
  1544. f"{shell_prefix()}Install the required global Skill from the configured repository with "
  1545. f"`{onboard_command('install-external-skills', '--skills', name, '--scope', 'global', '--source', 'auto', '--yes')}`."
  1546. )
  1547. return "Run `init` or `reset` to install the required global bundled Skills, then rerun `check`."
  1548. def skipped_already_installed_entry(
  1549. entry: dict[str, object],
  1550. reason: str,
  1551. next_step: str,
  1552. ) -> dict[str, object]:
  1553. skipped = dict(entry)
  1554. skipped["status"] = "skipped-already-installed"
  1555. skipped["reason"] = reason
  1556. skipped["nextStep"] = next_step
  1557. return skipped
  1558. def build_installation_report(results: dict[str, object]) -> dict[str, object]:
  1559. runtime = results["runtime"]
  1560. installed: dict[str, list[dict[str, object]]] = {
  1561. "runtime": [],
  1562. "tools": [],
  1563. "skills": [],
  1564. }
  1565. skipped_already_installed: dict[str, list[dict[str, object]]] = {
  1566. "runtime": [],
  1567. "tools": [],
  1568. "skills": [],
  1569. }
  1570. failed_or_missing: dict[str, list[dict[str, object]]] = {
  1571. "runtime": [],
  1572. "tools": [],
  1573. "skills": [],
  1574. }
  1575. not_checked: dict[str, list[dict[str, object]]] = {"tools": []}
  1576. conditional_runtime: list[dict[str, object]] = []
  1577. for name in ("npm", "node"):
  1578. item = runtime[name]
  1579. entry = report_entry(
  1580. name,
  1581. "installed" if item["installed"] else "missing",
  1582. path=item.get("path"),
  1583. version=item.get("version"),
  1584. )
  1585. if item["installed"]:
  1586. installed["runtime"].append(entry)
  1587. skipped_already_installed["runtime"].append(
  1588. skipped_already_installed_entry(
  1589. entry,
  1590. f"`{name}` is already available in PATH.",
  1591. "Skip bootstrap installation unless the user explicitly requests a reinstall or version change.",
  1592. )
  1593. )
  1594. else:
  1595. entry["status"] = "conditional"
  1596. entry["reason"] = f"`{name}` is not available in PATH."
  1597. entry["nextStep"] = (
  1598. "Only if a selected npm-backed install or upgrade needs npm: " + str(runtime["advice"])
  1599. if name == "npm"
  1600. else "Prepare Node.js only for a selected Node-backed operation."
  1601. )
  1602. conditional_runtime.append(entry)
  1603. nvm = runtime["nvm"]
  1604. nvm_entry = report_entry(
  1605. "nvm",
  1606. "installed" if nvm["installed"] else "missing",
  1607. path=nvm.get("path"),
  1608. version=nvm.get("version"),
  1609. )
  1610. if nvm["installed"]:
  1611. installed["runtime"].append(nvm_entry)
  1612. skipped_already_installed["runtime"].append(
  1613. skipped_already_installed_entry(
  1614. nvm_entry,
  1615. "`nvm` is already available.",
  1616. "Skip nvm bootstrap unless the user explicitly requests a reinstall or version manager change.",
  1617. )
  1618. )
  1619. elif not runtime["npm"]["installed"]:
  1620. nvm_entry["status"] = "conditional"
  1621. nvm_entry["reason"] = "npm and nvm are missing; bootstrap is conditional on a selected npm-backed operation."
  1622. nvm_entry["nextStep"] = "Only prepare nvm if that operation requires it. " + str(nvm["advice"])
  1623. conditional_runtime.append(nvm_entry)
  1624. for item in results["tools"]:
  1625. if item.get("optional"):
  1626. continue
  1627. if item.get("notChecked"):
  1628. not_checked["tools"].append(
  1629. report_entry(
  1630. str(item["name"]),
  1631. "not-checked",
  1632. reason=str(
  1633. item.get("reason") or "Prerequisites are not satisfied yet."
  1634. ),
  1635. next_step=cli_next_step(item),
  1636. )
  1637. )
  1638. continue
  1639. entry = report_entry(
  1640. str(item["name"]),
  1641. "installed" if item["installed"] else "missing",
  1642. path=item.get("path"),
  1643. version=item.get("version"),
  1644. )
  1645. if item["installed"]:
  1646. installed["tools"].append(entry)
  1647. skipped_already_installed["tools"].append(
  1648. skipped_already_installed_entry(
  1649. entry,
  1650. f"`{item['name']}` is already installed and passed the current verification checks.",
  1651. "Skip CLI installation unless the user explicitly requests reinstall, upgrade, replacement, or project-local installation.",
  1652. )
  1653. )
  1654. else:
  1655. if item.get("incompatibleVersion"):
  1656. entry["status"] = "incompatible"
  1657. elif item.get("wrongPackageSuspected"):
  1658. entry["status"] = "wrong-package-suspected"
  1659. elif item.get("verificationFailed"):
  1660. entry["status"] = "verification-failed"
  1661. entry["reason"] = cli_failure_reason(item)
  1662. entry["nextStep"] = cli_next_step(item)
  1663. failed_or_missing["tools"].append(entry)
  1664. for item in results["skills"]:
  1665. locations = item["locations"]
  1666. if item["installed"]:
  1667. for location in locations:
  1668. installed["skills"].append(
  1669. report_entry(
  1670. str(item["name"]),
  1671. "installed",
  1672. path=location["path"],
  1673. scope=location["scope"],
  1674. source_repo=item.get("sourceRepo"),
  1675. )
  1676. )
  1677. continue
  1678. failed_or_missing["skills"].append(
  1679. report_entry(
  1680. str(item["name"]),
  1681. "missing",
  1682. reason=skill_failure_reason(item),
  1683. next_step=skill_next_step(item),
  1684. source_repo=item.get("sourceRepo"),
  1685. )
  1686. )
  1687. manual_configuration = []
  1688. for item in results["manualChecks"]:
  1689. manual_item = {
  1690. "name": item["name"],
  1691. "category": item["category"],
  1692. "status": "manual-required",
  1693. "reason": "This item cannot be proven or completed safely by the installer alone.",
  1694. "advice": item["advice"],
  1695. "steps": item["steps"],
  1696. }
  1697. for key in (
  1698. "mcpServerConfig",
  1699. "environment",
  1700. "configExample",
  1701. "configExamples",
  1702. ):
  1703. if item.get(key):
  1704. manual_item[key] = item[key]
  1705. manual_configuration.append(manual_item)
  1706. installed_count = sum(len(items) for items in installed.values())
  1707. skipped_count = sum(len(items) for items in skipped_already_installed.values())
  1708. failed_count = sum(len(items) for items in failed_or_missing.values())
  1709. not_checked_count = sum(len(items) for items in not_checked.values())
  1710. return {
  1711. "summary": {
  1712. "installed": installed_count,
  1713. "skippedAlreadyInstalled": skipped_count,
  1714. "failedOrMissing": failed_count,
  1715. "notChecked": not_checked_count,
  1716. "conditionalRuntime": len(conditional_runtime),
  1717. "manualConfiguration": len(manual_configuration),
  1718. },
  1719. "installed": installed,
  1720. "skippedAlreadyInstalled": skipped_already_installed,
  1721. "failedOrMissing": failed_or_missing,
  1722. "notChecked": not_checked,
  1723. "conditionalRuntime": conditional_runtime,
  1724. "manualConfiguration": manual_configuration,
  1725. }
  1726. def normalized_ponytail_repo_identity(value: str) -> str:
  1727. identity = value.strip().lower().strip("/")
  1728. for prefix in ("git+ssh://", "ssh://", "https://", "http://", "git://"):
  1729. if identity.startswith(prefix):
  1730. identity = identity[len(prefix):]
  1731. break
  1732. if identity.startswith("git@"):
  1733. identity = identity[len("git@"):]
  1734. elif identity.startswith("git:"):
  1735. identity = identity[len("git:"):]
  1736. if ":" in identity.split("/")[0]:
  1737. identity = identity.replace(":", "/", 1)
  1738. identity = identity.strip("/").removesuffix(".git").strip("/")
  1739. return identity
  1740. def is_official_ponytail_plugin(platform_name: str, record: object) -> bool:
  1741. if not isinstance(record, dict):
  1742. return False
  1743. entry = cast(dict[str, object], record)
  1744. if platform_name == "codex":
  1745. canonical = str(entry.get("id") or entry.get("canonical") or "").lower()
  1746. if canonical == "ponytail@ponytail":
  1747. return True
  1748. return (
  1749. str(entry.get("name") or "") == "ponytail"
  1750. and str(entry.get("marketplace") or "") == "ponytail"
  1751. )
  1752. if platform_name == "omp":
  1753. if str(entry.get("name") or "") != "ponytail":
  1754. return False
  1755. expected = normalized_ponytail_repo_identity(
  1756. str(EXTERNAL_SKILL_SOURCES["ponytail"]["repo"])
  1757. )
  1758. for key in ("source", "installSpec", "install", "url", "repository", "spec"):
  1759. value = entry.get(key)
  1760. if isinstance(value, str) and normalized_ponytail_repo_identity(value) == expected:
  1761. return True
  1762. return False
  1763. return False
  1764. def ponytail_plugin_record_enabled(record: dict[str, object]) -> bool:
  1765. enabled = record.get("enabled")
  1766. if isinstance(enabled, bool):
  1767. return enabled
  1768. status = str(record.get("status") or record.get("state") or "").lower()
  1769. return status in {"enabled", "active", "on"}
  1770. def plugin_records_from_map(mapping: dict[str, object]) -> list[dict[str, object]]:
  1771. records: list[dict[str, object]] = []
  1772. for key, value in mapping.items():
  1773. if not isinstance(value, dict):
  1774. continue
  1775. record = {"name": str(key), **cast(dict[str, object], value)}
  1776. if "@" in str(key):
  1777. record.setdefault("id", str(key))
  1778. records.append(record)
  1779. return records
  1780. def list_platform_plugins(platform_name: str) -> tuple[str, list[dict[str, object]]]:
  1781. executable = shutil.which(platform_name)
  1782. if executable is None:
  1783. return "cli-unavailable", []
  1784. try:
  1785. completed = subprocess.run(
  1786. subprocess_command((executable, "plugin", "list", "--json")),
  1787. check=False,
  1788. capture_output=True,
  1789. text=True,
  1790. errors="replace",
  1791. timeout=10,
  1792. )
  1793. except (OSError, subprocess.TimeoutExpired):
  1794. return "cli-unavailable", []
  1795. if completed.returncode != 0:
  1796. return "cli-unavailable", []
  1797. try:
  1798. payload = json.loads(completed.stdout)
  1799. except json.JSONDecodeError:
  1800. return "cli-unavailable", []
  1801. records: list[dict[str, object]] = []
  1802. if isinstance(payload, list):
  1803. candidates: list[object] = payload
  1804. for candidate in candidates:
  1805. if isinstance(candidate, dict):
  1806. records.append(cast(dict[str, object], candidate))
  1807. return "ok", records
  1808. if not isinstance(payload, dict):
  1809. return "cli-unavailable", []
  1810. body = cast(dict[str, object], payload)
  1811. for key in ("plugins", "items", "data", "installed"):
  1812. value = body.get(key)
  1813. if isinstance(value, list):
  1814. for candidate in value:
  1815. if isinstance(candidate, dict):
  1816. records.append(cast(dict[str, object], candidate))
  1817. return "ok", records
  1818. if isinstance(value, dict):
  1819. return "ok", plugin_records_from_map(cast(dict[str, object], value))
  1820. if body and all(isinstance(value, dict) for value in body.values()):
  1821. records = plugin_records_from_map(body)
  1822. return "ok", records
  1823. def detect_ponytail_provider(global_skills_dir: Path) -> dict[str, object]:
  1824. valid = [
  1825. name
  1826. for name in PONYTAIL_REQUIRED_SKILLS
  1827. if external_skill_target_is_valid(global_skills_dir, name)
  1828. ]
  1829. existing = [
  1830. name
  1831. for name in PONYTAIL_REQUIRED_SKILLS
  1832. if filesystem_entry_exists(global_skills_dir / name)
  1833. ]
  1834. if len(valid) == len(PONYTAIL_REQUIRED_SKILLS):
  1835. skill_status = "complete"
  1836. elif not existing:
  1837. skill_status = "missing"
  1838. elif valid:
  1839. skill_status = "partial"
  1840. else:
  1841. skill_status = "invalid"
  1842. platforms: dict[str, object] = {}
  1843. any_unavailable = False
  1844. enabled_found = False
  1845. disabled_found = False
  1846. for platform_name in ("codex", "omp"):
  1847. if platform_name == "omp" and detect_omp_root() is None:
  1848. platforms[platform_name] = {"status": "not-configured"}
  1849. continue
  1850. status, records = list_platform_plugins(platform_name)
  1851. if status != "ok":
  1852. platforms[platform_name] = {"status": "cli-unavailable"}
  1853. any_unavailable = True
  1854. continue
  1855. official = [
  1856. record
  1857. for record in records
  1858. if is_official_ponytail_plugin(platform_name, record)
  1859. ]
  1860. if any(ponytail_plugin_record_enabled(record) for record in official):
  1861. enabled_found = True
  1862. platforms[platform_name] = {"status": "installed-enabled"}
  1863. elif official:
  1864. disabled_found = True
  1865. platforms[platform_name] = {"status": "installed-disabled"}
  1866. else:
  1867. platforms[platform_name] = {"status": "missing"}
  1868. if enabled_found:
  1869. provider = "conflict"
  1870. plugin_status = "installed-enabled"
  1871. elif any_unavailable:
  1872. provider = "unknown"
  1873. plugin_status = "cli-unavailable"
  1874. elif disabled_found:
  1875. provider = "onboard-stable"
  1876. plugin_status = "installed-disabled"
  1877. else:
  1878. provider = "onboard-stable"
  1879. plugin_status = "missing"
  1880. if provider == "conflict":
  1881. next_step = "disable-or-remove-plugin"
  1882. elif skill_status == "missing":
  1883. next_step = "install-required"
  1884. elif skill_status in {"partial", "invalid"}:
  1885. next_step = "repair-required"
  1886. else:
  1887. next_step = "none"
  1888. return {
  1889. "provider": provider,
  1890. "skillStatus": skill_status,
  1891. "requiredSkills": list(PONYTAIL_REQUIRED_SKILLS),
  1892. "pluginStatus": plugin_status,
  1893. "platforms": platforms,
  1894. "nextStep": next_step,
  1895. }
  1896. def check_content_alignment(global_skills_dir: Path) -> dict[str, object]:
  1897. """Report selected Skills content, never global rules or host readiness."""
  1898. from onboard_contracts import ContractError
  1899. try:
  1900. from sbtd_upgrade_inventory import build_inventory
  1901. inventory = build_inventory(
  1902. {"schema_version": 1, "skills_roots": [str(global_skills_dir)]},
  1903. package_root=SKILL_DIR,
  1904. )
  1905. resources = inventory["resources"]
  1906. return {
  1907. "scope": "skills-only",
  1908. "checkedRoots": [str(global_skills_dir)],
  1909. "status": "aligned" if all(
  1910. row["classification"] == "current" for row in resources
  1911. ) else "needs-alignment",
  1912. "baseline": inventory["baseline"]["baseline_id"],
  1913. "resources": [
  1914. {key: row[key] for key in ("target", "classification", "decision", "details")}
  1915. for row in resources
  1916. ],
  1917. "nextStep": "Use upgrade --phase plan with an explicit scope before replacing retained content.",
  1918. }
  1919. except (ContractError, OSError, ValueError, RuntimeError, ImportError) as error:
  1920. return {
  1921. "scope": "skills-only",
  1922. "checkedRoots": [str(global_skills_dir)],
  1923. "status": "unverified",
  1924. "reason": getattr(error, "code", "inventory-unavailable"),
  1925. "nextStep": "Run explicit upgrade planning with the complete installed package and declared dependencies.",
  1926. }
  1927. def build_check_results(args: argparse.Namespace) -> dict[str, object]:
  1928. project_roots = resolve_project_roots(args)
  1929. global_skills_dir, global_skills_dir_source = resolve_global_skills_dir(
  1930. getattr(args, "global_skills_dir", None)
  1931. )
  1932. runtime = check_npm_runtime()
  1933. skills = [
  1934. check_skill(name, "bundled", global_skills_dir, None) for name in BUNDLED_SKILLS
  1935. ]
  1936. skills.extend(
  1937. check_skill(name, "referenced", global_skills_dir, None)
  1938. for name in REFERENCED_SKILLS
  1939. )
  1940. skills.extend(
  1941. check_skill(name, "interaction", global_skills_dir, None)
  1942. for name in INTERACTION_SKILLS
  1943. )
  1944. for item in skills:
  1945. if item["name"] == "caveman":
  1946. maintenance = caveman_maintenance_plan(global_skills_dir)
  1947. item["maintenanceState"] = maintenance["state"]
  1948. item["pinnedRef"] = maintenance["pinnedRef"]
  1949. item["maintenanceScope"] = maintenance["scope"]
  1950. item["maintenancePlannedAction"] = maintenance["plannedAction"]
  1951. if maintenance.get("blockedReason"):
  1952. item["maintenanceBlockedReason"] = maintenance["blockedReason"]
  1953. tools = [check_cli_tool(spec) for spec in CLI_TOOLS]
  1954. graft_check = check_graft()
  1955. tools.append(graft_check)
  1956. java_check = check_java_for_maestro()
  1957. maestro_check = check_maestro_cli(java_check)
  1958. tools.append(java_check)
  1959. tools.append(maestro_check)
  1960. manual_checks = build_manual_checks(java_check, maestro_check, None)
  1961. project_checks = [
  1962. build_project_check(
  1963. project_root, bool(getattr(args, "skip_project_agents", False))
  1964. )
  1965. for project_root in project_roots
  1966. ]
  1967. missing = {
  1968. "runtime": [],
  1969. "tools": [
  1970. item["name"]
  1971. for item in tools
  1972. if not item["installed"]
  1973. and not item.get("notChecked")
  1974. and not item.get("optional")
  1975. ],
  1976. "skills": [item["name"] for item in skills if not item["installed"]],
  1977. }
  1978. omp_root = detect_omp_root()
  1979. omp_agents, omp_agents_explicit = omp_agents_target()
  1980. from sbtd_language_tooling import check_language_tooling
  1981. language_tooling = check_language_tooling(project_roots)
  1982. results = {
  1983. "mode": "check",
  1984. "platform": platform.system() or sys.platform,
  1985. "paths": {
  1986. "globalSkillsDir": str(global_skills_dir),
  1987. "globalSkillsDirSource": global_skills_dir_source,
  1988. "projectRoots": [str(project_root) for project_root in project_roots],
  1989. "ompRoot": str(omp_root) if omp_root else None,
  1990. "ompGlobalAgents": (
  1991. str(omp_agents)
  1992. if omp_agents_explicit
  1993. else (
  1994. str(omp_global_agents_path(omp_root).resolve())
  1995. if omp_root is not None
  1996. else None
  1997. )
  1998. ),
  1999. },
  2000. "runtime": runtime,
  2001. "graft": graft_check,
  2002. "tools": tools,
  2003. "skills": skills,
  2004. "manualChecks": manual_checks,
  2005. "projectChecks": project_checks,
  2006. "missing": missing,
  2007. "ponytailProvider": detect_ponytail_provider(global_skills_dir),
  2008. "contentAlignment": check_content_alignment(global_skills_dir),
  2009. "languageTooling": language_tooling,
  2010. }
  2011. results["installationReport"] = build_installation_report(results)
  2012. return results
  2013. def print_report_entries(
  2014. entries: list[dict[str, object]], empty_message: str = "- none"
  2015. ) -> None:
  2016. if not entries:
  2017. print(empty_message)
  2018. return
  2019. for item in entries:
  2020. detail = []
  2021. if item.get("scope"):
  2022. detail.append(f"scope={item['scope']}")
  2023. if item.get("path"):
  2024. detail.append(f"path={item['path']}")
  2025. if item.get("version"):
  2026. detail.append(f"version={item['version']}")
  2027. suffix = f" ({', '.join(detail)})" if detail else ""
  2028. print(f"- {item['name']}: {item['status']}{suffix}")
  2029. if item.get("sourceRepo"):
  2030. print(f" source repo: {item['sourceRepo']}")
  2031. if item.get("reason"):
  2032. print(f" reason: {item['reason']}")
  2033. if item.get("nextStep"):
  2034. print(f" next: {item['nextStep']}")
  2035. def print_indented_block(value: object, indent: int = 4) -> None:
  2036. prefix = " " * indent
  2037. for line in str(value).splitlines():
  2038. print(f"{prefix}{line}")
  2039. def print_config_examples(item: dict[str, object]) -> None:
  2040. examples = item.get("configExamples")
  2041. if isinstance(examples, dict) and examples:
  2042. print(" config examples:")
  2043. for name, example in examples.items():
  2044. label = "generic MCP JSON" if name == "genericJson" else name
  2045. print(f" {label}:")
  2046. print_indented_block(example)
  2047. return
  2048. if item.get("configExample"):
  2049. print(" config example:")
  2050. print_indented_block(item["configExample"])
  2051. def print_installation_report(
  2052. report: dict[str, object], heading: str = "Installation report"
  2053. ) -> None:
  2054. print(f"\n{heading}:")
  2055. summary = report["summary"]
  2056. print(
  2057. "Summary: "
  2058. f"installed={summary['installed']}, "
  2059. f"skipped_already_installed={summary['skippedAlreadyInstalled']}, "
  2060. f"failed_or_missing={summary['failedOrMissing']}, "
  2061. f"not_checked={summary['notChecked']}, "
  2062. f"manual_configuration={summary['manualConfiguration']}"
  2063. )
  2064. print("\nInstalled runtime:")
  2065. print_report_entries(report["installed"]["runtime"])
  2066. print("\nInstalled CLI tools:")
  2067. print_report_entries(report["installed"]["tools"])
  2068. print("\nInstalled skills:")
  2069. print_report_entries(report["installed"]["skills"])
  2070. print("\nSkipped because already installed - runtime:")
  2071. print_report_entries(report["skippedAlreadyInstalled"]["runtime"])
  2072. print("\nSkipped because already installed - CLI tools:")
  2073. print_report_entries(report["skippedAlreadyInstalled"]["tools"])
  2074. print("\nFailed or missing runtime:")
  2075. print_report_entries(report["failedOrMissing"]["runtime"])
  2076. print("\nFailed or missing CLI tools:")
  2077. print_report_entries(report["failedOrMissing"]["tools"])
  2078. print("\nFailed or missing skills:")
  2079. print_report_entries(report["failedOrMissing"]["skills"])
  2080. print("\nNot checked:")
  2081. print_report_entries(report["notChecked"]["tools"])
  2082. print("\nConditional runtime prerequisites (no install selected):")
  2083. print_report_entries(cast(list[dict[str, object]], report["conditionalRuntime"]))
  2084. print("\nManual configuration required:")
  2085. manual_items = report["manualConfiguration"]
  2086. if not manual_items:
  2087. print("- none")
  2088. for item in manual_items:
  2089. print(f"- {item['name']} [{item['category']}]: {item['status']}")
  2090. print(f" reason: {item['reason']}")
  2091. print(f" advice: {item['advice']}")
  2092. print_config_examples(item)
  2093. print(" steps:")
  2094. for index, step in enumerate(item["steps"], start=1):
  2095. print(f" {index}. {step}")
  2096. def print_language_tooling(
  2097. report: dict[str, object], heading: str = "Language tooling"
  2098. ) -> None:
  2099. print(f"\n{heading}: {report.get('status', 'unknown')}")
  2100. for project in cast(list[dict[str, object]], report.get("projects") or []):
  2101. languages = cast(list[dict[str, object]], project.get("languages") or [])
  2102. if languages:
  2103. names = ", ".join(str(item["display"]) for item in languages)
  2104. print(f"- {project['root']}: {names}")
  2105. ast_grep = cast(dict[str, object], report.get("astGrep") or {})
  2106. if ast_grep:
  2107. print(f"- omp ast-grep: {ast_grep.get('status')}")
  2108. languages_map = cast(dict[str, dict[str, object]], report.get("languages") or {})
  2109. for name in sorted(languages_map):
  2110. entry = languages_map[name]
  2111. if entry.get("builtIn"):
  2112. for server in cast(list[dict[str, object]], entry.get("servers") or []):
  2113. state = "available" if server.get("available") else "missing"
  2114. print(f"- {entry['display']} server {server['command']}: {state}")
  2115. else:
  2116. state = (
  2117. "custom lsp.yml entry configured"
  2118. if entry.get("customConfigured")
  2119. else "custom lsp.yml entry missing"
  2120. )
  2121. print(f"- {entry['display']}: {state}")
  2122. for item in cast(list[dict[str, object]], report.get("guidance") or []):
  2123. print(f" guidance: {item['summary']}")
  2124. for step in cast(list[str], item.get("steps") or []):
  2125. print(f" - {step}")
  2126. if item.get("requiresConsent"):
  2127. print(f" skip impact: {item['skipImpact']}")
  2128. for write in cast(list[dict[str, object]], report.get("writes") or []):
  2129. print(f" wrote: {write['action']} -> {write['path']}")
  2130. for failure in cast(list[dict[str, object]], report.get("failures") or []):
  2131. print(f" failed: {failure['action']} -> {failure['path']}: {failure['error']}")
  2132. if report.get("nextStep") and report.get("status") in {
  2133. "needs-confirmation",
  2134. "configured",
  2135. "failed",
  2136. }:
  2137. print(f" next: {report['nextStep']}")
  2138. def run_language_tooling_step(
  2139. mode: str, args: argparse.Namespace
  2140. ) -> dict[str, object] | None:
  2141. """omp LSP/ast-grep readiness plus consent-gated config writes.
  2142. Detection and guidance are always read-only; the pending configuration
  2143. writes run only with the separate ``--language-tooling`` consent flag.
  2144. """
  2145. if mode not in {"init", "init-projects"}:
  2146. return None
  2147. from sbtd_language_tooling import apply_language_tooling, check_language_tooling
  2148. report = check_language_tooling(resolve_project_roots(args))
  2149. if report["status"] == "skipped":
  2150. return report
  2151. return apply_language_tooling(
  2152. report, confirmed=bool(getattr(args, "language_tooling", False))
  2153. )
  2154. def print_check_results(results: dict[str, object], as_json: bool) -> None:
  2155. if as_json:
  2156. print(json.dumps(results, indent=2, ensure_ascii=False))
  2157. return
  2158. print("Preflight check")
  2159. print(f"Platform: {results['platform']}")
  2160. paths = results["paths"]
  2161. print(f"Global skills: {paths['globalSkillsDir']}")
  2162. alignment = results.get("contentAlignment", {})
  2163. print(f"Skills-only content alignment: {alignment.get('status', 'unverified')}")
  2164. if alignment.get("status") != "aligned":
  2165. print(" Installation validity does not prove content alignment; use explicit upgrade planning.")
  2166. for project_root in paths["projectRoots"]:
  2167. print(f"Project root: {project_root}")
  2168. runtime = results["runtime"]
  2169. print("\nRuntime preflight:")
  2170. npm = runtime["npm"]
  2171. node = runtime["node"]
  2172. nvm = runtime["nvm"]
  2173. npm_status = "installed" if npm["installed"] else "missing"
  2174. node_status = "installed" if node["installed"] else "missing"
  2175. nvm_status = "installed" if nvm["installed"] else "missing"
  2176. print(
  2177. f"- npm: {npm_status}"
  2178. + (f" at {npm['path']} ({npm['version']})" if npm.get("path") else "")
  2179. )
  2180. print(
  2181. f"- node: {node_status}"
  2182. + (f" at {node['path']} ({node['version']})" if node.get("path") else "")
  2183. )
  2184. print(
  2185. f"- nvm: {nvm_status}" + (f" ({nvm['version']})" if nvm.get("version") else "")
  2186. )
  2187. if not npm["installed"]:
  2188. print(
  2189. f" action: npm is needed only for a selected npm-backed install or upgrade; if that action is confirmed, {shell_prefix()}run `{onboard_command('ensure-npm', '--yes')}`."
  2190. )
  2191. print("\nCLI tools:")
  2192. for item in results["tools"]:
  2193. if item.get("optional"):
  2194. continue
  2195. status = "installed" if item["installed"] else "missing"
  2196. if item.get("notChecked"):
  2197. status = "not-checked"
  2198. elif item.get("incompatibleVersion"):
  2199. status = "incompatible"
  2200. elif item.get("wrongPackageSuspected"):
  2201. status = "wrong-package-suspected"
  2202. elif item.get("verificationFailed"):
  2203. status = "verification-failed"
  2204. detail = f" ({item['version']})" if item.get("version") else ""
  2205. path = f" at {item['path']}" if item.get("path") else ""
  2206. print(f"- {item['name']}: {status}{path}{detail}")
  2207. if item.get("verifyCommand"):
  2208. verified = "passed" if item.get("installed") else "not passed"
  2209. print(f" verify: {item['verifyCommand']} ({verified})")
  2210. if item.get("verificationScope"):
  2211. print(f" verification scope: {item['verificationScope']}")
  2212. if item.get("reason"):
  2213. print(f" reason: {item['reason']}")
  2214. if not item["installed"]:
  2215. print(f" global: {item['globalInstall']}")
  2216. if item.get("projectInstall"):
  2217. print(f" project: {item['projectInstall']}")
  2218. print(f" advice: {item['advice']}")
  2219. graft = results["graft"]
  2220. assert isinstance(graft, dict)
  2221. print("\nOptional Graft CLI:")
  2222. print(f"- graft: {graft['status']}")
  2223. if graft.get("reason"):
  2224. print(f" reason: {graft['reason']}")
  2225. if graft.get("nextStep"):
  2226. print(f" next: {graft['nextStep']}")
  2227. wiring = results.get("graftWiring")
  2228. if isinstance(wiring, dict):
  2229. print(f"\nGraft wiring: {wiring.get('status')}")
  2230. if wiring.get("reason"):
  2231. print(f" reason: {wiring['reason']}")
  2232. if wiring.get("nextStep"):
  2233. print(f" next: {wiring['nextStep']}")
  2234. print("\nSkills:")
  2235. for item in results["skills"]:
  2236. status = "installed" if item["installed"] else "missing"
  2237. print(f"- {item['name']} [{item['group']}]: {status}")
  2238. for location in item["locations"]:
  2239. print(f" {location['scope']}: {location['path']}")
  2240. if not item["installed"]:
  2241. print(f" global target: {item['globalTarget']}")
  2242. if item["projectTarget"]:
  2243. print(f" project target: {item['projectTarget']}")
  2244. if item.get("sourceRepo"):
  2245. print(f" source repo: {item['sourceRepo']}")
  2246. if item.get("maintenanceState"):
  2247. print(
  2248. f" maintenance: {item['maintenanceState']}"
  2249. f" (pinned {item.get('pinnedRef')}, {item.get('maintenanceScope')})"
  2250. )
  2251. if item.get("maintenancePlannedAction"):
  2252. print(f" planned action: {item['maintenancePlannedAction']}")
  2253. if item.get("maintenanceBlockedReason"):
  2254. print(f" blocked: {item['maintenanceBlockedReason']}")
  2255. print("\nManual checks:")
  2256. for item in results["manualChecks"]:
  2257. print(f"- {item['name']} [{item['category']}]: {item['advice']}")
  2258. print_config_examples(item)
  2259. provider = cast(dict[str, object], results["ponytailProvider"])
  2260. print("\nPonytail provider:")
  2261. print(f"- provider: {provider['provider']}")
  2262. print(f"- skillStatus: {provider['skillStatus']}")
  2263. print(f"- pluginStatus: {provider['pluginStatus']}")
  2264. print(f"- nextStep: {provider['nextStep']}")
  2265. if results["projectChecks"]:
  2266. print("")
  2267. print_projects_check_results(
  2268. {"mode": "check-projects", "projects": results["projectChecks"]},
  2269. False,
  2270. )
  2271. missing = results["missing"]
  2272. if missing["runtime"] or missing["tools"] or missing["skills"]:
  2273. print("\nMissing summary:")
  2274. if missing["runtime"]:
  2275. print("- runtime: " + ", ".join(missing["runtime"]))
  2276. if missing["tools"]:
  2277. print("- tools: " + ", ".join(missing["tools"]))
  2278. if missing["skills"]:
  2279. print("- skills: " + ", ".join(missing["skills"]))
  2280. print(
  2281. "Resolve prerequisites for the selected operation only; missing npm and optional Graft do not block unrelated safe work."
  2282. )
  2283. else:
  2284. print("\nMissing summary: none")
  2285. print_installation_report(results["installationReport"])
  2286. language_tooling = results.get("languageTooling")
  2287. if isinstance(language_tooling, dict):
  2288. print_language_tooling(language_tooling)
  2289. def backup_path(target: Path) -> Path:
  2290. today = dt.date.today().isoformat()
  2291. index = 1
  2292. while True:
  2293. candidate = target.with_name(f"{target.name}.{today}-{index}")
  2294. if not candidate.exists():
  2295. return candidate
  2296. index += 1
  2297. def remove_existing_target(target: Path) -> None:
  2298. if target.is_dir() and not target.is_symlink():
  2299. shutil.rmtree(target)
  2300. else:
  2301. target.unlink()
  2302. EXTERNAL_TREE_DIGEST_EXCLUDED_DIRS = frozenset(
  2303. {"__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache"}
  2304. )
  2305. EXTERNAL_TREE_DIGEST_EXCLUDED_SUFFIXES = frozenset({".pyc", ".pyo"})
  2306. EXTERNAL_TREE_COMPARE_EXCLUDED_DIRS = {".git", *EXTERNAL_TREE_DIGEST_EXCLUDED_DIRS}
  2307. def external_copy_ignore(*extra: str) -> Callable[[str, list[str]], set[str]]:
  2308. """Copies drop exactly what the pinned digest drops; otherwise unauthenticated
  2309. cache files reach installed Skills without changing treeSha256."""
  2310. match_names = shutil.ignore_patterns(
  2311. *extra, *sorted(EXTERNAL_TREE_DIGEST_EXCLUDED_DIRS)
  2312. )
  2313. def ignore(directory: str, names: list[str]) -> set[str]:
  2314. ignored = set(match_names(directory, names))
  2315. # The digest drops cache entries by file suffix and never rejects a
  2316. # directory for its name, so a directory called `pkg.pyc` must still be
  2317. # copied; a bare glob would drop that whole subtree while its files kept
  2318. # counting toward treeSha256.
  2319. for name in names:
  2320. if name in ignored:
  2321. continue
  2322. if Path(name).suffix not in EXTERNAL_TREE_DIGEST_EXCLUDED_SUFFIXES:
  2323. continue
  2324. if Path(directory, name).is_dir():
  2325. continue
  2326. ignored.add(name)
  2327. return ignored
  2328. return ignore
  2329. def compare_tree(
  2330. source: Path, target: Path, ignored_names: set[str] | None = None
  2331. ) -> list[str]:
  2332. failures: list[str] = []
  2333. ignored = ignored_names or set()
  2334. for item in source.rglob("*"):
  2335. rel = item.relative_to(source)
  2336. if any(part in ignored for part in rel.parts):
  2337. continue
  2338. if rel.suffix in EXTERNAL_TREE_DIGEST_EXCLUDED_SUFFIXES and not item.is_dir():
  2339. continue
  2340. other = target / rel
  2341. if item.is_dir():
  2342. if not other.is_dir():
  2343. failures.append(str(rel))
  2344. continue
  2345. if not other.is_file() or not filecmp.cmp(item, other, shallow=False):
  2346. failures.append(str(rel))
  2347. return failures
  2348. def missing_file_lines(source_text: str, target_text: str) -> list[str]:
  2349. target_lines = target_text.splitlines()
  2350. if target_lines:
  2351. target_lines[0] = target_lines[0].removeprefix("\ufeff")
  2352. existing_lines = set(target_lines)
  2353. missing_lines: list[str] = []
  2354. pending_separator = False
  2355. for line in source_text.splitlines():
  2356. if not line:
  2357. pending_separator = bool(missing_lines)
  2358. continue
  2359. if line in existing_lines:
  2360. continue
  2361. if pending_separator and missing_lines[-1] != "":
  2362. missing_lines.append("")
  2363. missing_lines.append(line)
  2364. existing_lines.add(line)
  2365. pending_separator = False
  2366. return missing_lines
  2367. def ensure_file_contains(source: Path, target: Path) -> str:
  2368. source_text = source.read_text(encoding="utf-8")
  2369. target.parent.mkdir(parents=True, exist_ok=True)
  2370. if not target.exists():
  2371. if not source_text.endswith("\n"):
  2372. source_text += "\n"
  2373. target.write_text(source_text, encoding="utf-8")
  2374. return "created"
  2375. existing = target.read_text(encoding="utf-8")
  2376. missing_lines = missing_file_lines(source_text, existing)
  2377. if not missing_lines:
  2378. return "skipped-already-present"
  2379. prefix = "" if not existing or existing.endswith("\n") else "\n"
  2380. separator = "\n" if existing.strip() else ""
  2381. addition = "\n".join(missing_lines) + "\n"
  2382. target.write_text(
  2383. f"{existing}{prefix}{separator}{addition}",
  2384. encoding="utf-8",
  2385. )
  2386. return "updated"
  2387. def copy_operation(operation: Operation) -> str:
  2388. if operation.same_location:
  2389. return "skipped-same-location"
  2390. if (
  2391. operation.kind == "dir"
  2392. and operation.skip_when_valid
  2393. and external_skill_target_is_valid(
  2394. operation.target.parent, operation.target.name
  2395. )
  2396. ):
  2397. return "skipped-already-valid"
  2398. operation.target.parent.mkdir(parents=True, exist_ok=True)
  2399. if operation.kind == "ensure-file-block":
  2400. return ensure_file_contains(operation.source, operation.target)
  2401. if operation.kind == "file":
  2402. shutil.copy2(operation.source, operation.target)
  2403. return "copied"
  2404. if operation.target.exists():
  2405. remove_existing_target(operation.target)
  2406. action = "overwritten-without-backup"
  2407. else:
  2408. action = "copied"
  2409. shutil.copytree(operation.source, operation.target)
  2410. return action
  2411. GITIGNORE_MUST_TRACK_PROBES = (
  2412. ".gitignore",
  2413. ".gitattributes",
  2414. "AGENTS.md",
  2415. "CLAUDE.md",
  2416. ".agents/skills/example/SKILL.md",
  2417. ".agents/skills/react-bits-pro/SKILL.md",
  2418. "ai/tasks/index.md",
  2419. "ai/tasks/example/task.md",
  2420. "ai/tasks/example/legacy-task.json",
  2421. "ai/tasks/example/prd.md",
  2422. "ai/tasks/example/design.md",
  2423. "ai/tasks/example/implement.md",
  2424. "ai/tasks/example/reports.md",
  2425. "ai/tasks/00-bootstrap-guidelines/task.md",
  2426. "ai/tasks/parent/child/task.md",
  2427. "ai/tasks/archive/2026-Q1/example/task.md",
  2428. "ai/tasks/archive/undated/example/task.md",
  2429. "docs/spec/lessons.md",
  2430. "docs/lessons.md",
  2431. "docs/lessons/index.md",
  2432. "docs/lessons/topics/example.md",
  2433. "docs/lessons/archive/2026-Q1.md",
  2434. "docs/CONTEXT.md",
  2435. "docs/adr/example.md",
  2436. "docs/contexts/example/CONTEXT.md",
  2437. "docs/contexts/example/adr/example.md",
  2438. "docs/PRODUCT.md",
  2439. "docs/DESIGN.md",
  2440. "features/example.feature",
  2441. "maestro/flow/smoke.yml",
  2442. "maestro/flow/ios/smoke.yml",
  2443. "maestro/flow/android/smoke.yml",
  2444. "tests/unit/test_example.py",
  2445. "tests/api/test_example.py",
  2446. "tests/e2e/example.spec.ts",
  2447. "tests/e2e/manifest/ui-test-manifest.json",
  2448. "tests/e2e/manifest/ui-selector-audit.json",
  2449. "tests/e2e/manifest/ui-test-coverage.json",
  2450. )
  2451. GITIGNORE_MUST_IGNORE_PROBES = (
  2452. ".sbtd",
  2453. ".sbtd/developer",
  2454. ".sbtd/active-task.json",
  2455. ".sbtd/tasks/example/task.md",
  2456. "docs/handoffs",
  2457. "docs/handoffs/session.md",
  2458. "ai/tasks/example/reports",
  2459. "ai/tasks/example/reports/raw.json",
  2460. "ai/tasks/parent/child/reports",
  2461. "ai/tasks/parent/child/reports/raw.json",
  2462. "ai/tasks/archive/2026-Q1/example/reports",
  2463. "ai/tasks/archive/2026-Q1/example/reports/raw.json",
  2464. "ai/tasks/archive/undated/example/reports",
  2465. "ai/tasks/archive/undated/example/reports/raw.json",
  2466. "graft",
  2467. "graft/index.json",
  2468. ".graft",
  2469. ".graft/state.json",
  2470. ".env",
  2471. ".env.local",
  2472. ".impeccable/config.local.json",
  2473. )
  2474. GITIGNORE_PROBE_UNAVAILABLE = "unavailable"
  2475. GITIGNORE_PROBE_ERROR = "error"
  2476. # Checks that could not be evaluated. They are not failures, but the final
  2477. # summary must not read as "everything was verified" once one is recorded.
  2478. UNVERIFIED_CHECKS: list[str] = []
  2479. def note_unverified(message: str) -> None:
  2480. UNVERIFIED_CHECKS.append(message)
  2481. print(f"Note: {message}", file=sys.stderr)
  2482. @dataclass(frozen=True)
  2483. class GitignoreVerdict:
  2484. ignored: bool
  2485. origin: str
  2486. def gitignore_verdicts(
  2487. project_root: Path,
  2488. probes: tuple[str, ...],
  2489. *,
  2490. env: dict[str, str] | None = None,
  2491. ) -> dict[str, GitignoreVerdict] | str:
  2492. """Resolve every probe in one `git check-ignore` pass.
  2493. `-v --non-matching` names the deciding line for both outcomes, so a
  2494. negation that re-exposes a runtime path is reported as precisely as a broad
  2495. exclusion that buries a workflow file. The verdict follows git's own rule:
  2496. the last matching pattern wins and a `!` pattern means "not ignored", which
  2497. `--quiet` alone cannot distinguish from "no pattern matched".
  2498. `-z --stdin` is what makes that verdict trustworthy. It emits
  2499. `source NUL linenum NUL pattern NUL pathname NUL`, so the deciding pattern
  2500. arrives as its own field. Splitting the textual `source:linenum:pattern`
  2501. form instead truncates any pattern containing a colon: `!.en[v:]` reduces
  2502. to `]`, which drops the leading `!` and reports a re-included `.env` as
  2503. ignored -- inverting the verdict for the exact case this check exists to
  2504. catch.
  2505. """
  2506. result = run_project_command(
  2507. (
  2508. "git",
  2509. "check-ignore",
  2510. "--no-index",
  2511. "-v",
  2512. "--non-matching",
  2513. "-z",
  2514. "--stdin",
  2515. ),
  2516. project_root,
  2517. timeout=60,
  2518. stdin_text="".join(f"{probe}\0" for probe in probes),
  2519. env=env,
  2520. )
  2521. if result is None or result.returncode == 128:
  2522. return GITIGNORE_PROBE_UNAVAILABLE
  2523. if result.returncode not in (0, 1):
  2524. return GITIGNORE_PROBE_ERROR
  2525. fields = result.stdout.split("\0")
  2526. if fields and fields[-1] == "":
  2527. fields.pop()
  2528. if len(fields) % 4:
  2529. return GITIGNORE_PROBE_ERROR
  2530. verdicts: dict[str, GitignoreVerdict] = {}
  2531. for index in range(0, len(fields), 4):
  2532. source, linenum, pattern, path = fields[index : index + 4]
  2533. verdicts[path] = GitignoreVerdict(
  2534. ignored=bool(pattern) and not pattern.startswith("!"),
  2535. origin=f"{source}:{linenum}:{pattern}" if pattern else "",
  2536. )
  2537. if set(verdicts) != set(probes):
  2538. return GITIGNORE_PROBE_ERROR
  2539. return verdicts
  2540. def gitignore_effectiveness_failures(target: Path) -> list[str]:
  2541. """Verify shared SBTD paths and local-state protection using Git semantics."""
  2542. project_root = target.parent
  2543. verdicts = gitignore_verdicts(
  2544. project_root, GITIGNORE_MUST_TRACK_PROBES + GITIGNORE_MUST_IGNORE_PROBES
  2545. )
  2546. if isinstance(verdicts, str):
  2547. if verdicts == GITIGNORE_PROBE_ERROR:
  2548. return [
  2549. "git check-ignore could not evaluate the merged .gitignore --"
  2550. " resolve the repository error instead of trusting rules that"
  2551. " were never verified"
  2552. ]
  2553. # git is missing or the project is outside a work tree: there is no
  2554. # ignore semantics to query, so say the check was skipped instead of
  2555. # letting a silent pass read as "verified effective".
  2556. note_unverified(
  2557. ".gitignore effectiveness verification skipped for"
  2558. f" {project_root} -- git could not evaluate it (no git binary or no"
  2559. " work tree), so the merged rules remain unverified."
  2560. )
  2561. return []
  2562. failures: list[str] = []
  2563. blocked: dict[str, list[str]] = {}
  2564. for probe in GITIGNORE_MUST_TRACK_PROBES:
  2565. verdict = verdicts[probe]
  2566. if verdict.ignored:
  2567. key = verdict.origin or "an unknown gitignore pattern"
  2568. blocked.setdefault(key, []).append(probe)
  2569. for origin, paths in blocked.items():
  2570. shown = ", ".join(paths[:3])
  2571. extra = f" (+{len(paths) - 3} more)" if len(paths) > 3 else ""
  2572. failures.append(
  2573. f"{origin} ignores paths that must stay trackable: {shown}{extra}"
  2574. " -- confirm the intended shared paths before narrowing that pattern;"
  2575. " do not remove unrelated project exclusions automatically"
  2576. )
  2577. for probe in GITIGNORE_MUST_IGNORE_PROBES:
  2578. verdict = verdicts[probe]
  2579. if verdict.ignored:
  2580. continue
  2581. if verdict.origin:
  2582. failures.append(
  2583. f"{verdict.origin} re-includes {probe}, which must stay ignored"
  2584. " -- narrow that re-inclusion so local runtime state and"
  2585. " secrets cannot be committed"
  2586. )
  2587. else:
  2588. failures.append(
  2589. f"{probe} must stay ignored but no pattern covers it -- restore"
  2590. " the removed rule so local runtime state and secrets cannot be"
  2591. " committed"
  2592. )
  2593. return failures
  2594. def verify_operation(operation: Operation) -> list[str]:
  2595. if operation.same_location:
  2596. return []
  2597. if (
  2598. operation.kind == "dir"
  2599. and operation.skip_when_valid
  2600. and external_skill_target_is_valid(
  2601. operation.target.parent, operation.target.name
  2602. )
  2603. ):
  2604. return []
  2605. if operation.kind == "ensure-file-block":
  2606. if not operation.target.is_file():
  2607. return [operation.label]
  2608. source_text = operation.source.read_text(encoding="utf-8")
  2609. target_text = operation.target.read_text(encoding="utf-8")
  2610. if missing_file_lines(source_text, target_text):
  2611. return [operation.label]
  2612. return gitignore_effectiveness_failures(operation.target)
  2613. if operation.kind == "file":
  2614. if operation.target.is_file() and filecmp.cmp(
  2615. operation.source, operation.target, shallow=False
  2616. ):
  2617. return []
  2618. return [operation.label]
  2619. return compare_tree(operation.source, operation.target)
  2620. def canonical_external_skill_name(name: str) -> str:
  2621. return MATTPOCOCK_LEGACY_RENAMES.get(name, name)
  2622. def legacy_external_skill_names_for(canonical_name: str) -> list[str]:
  2623. return [
  2624. legacy_name
  2625. for legacy_name, replacement_name in MATTPOCOCK_LEGACY_RENAMES.items()
  2626. if replacement_name == canonical_name
  2627. ]
  2628. def filesystem_entry_exists(path: Path) -> bool:
  2629. return path.exists() or path.is_symlink()
  2630. def legacy_external_skill_identity_error(target: Path, legacy_name: str) -> str | None:
  2631. if not target.is_dir() or target.is_symlink():
  2632. return f"legacy target is not a regular Skill directory: {target}"
  2633. skill_md = target / "SKILL.md"
  2634. if not skill_md.is_file() or skill_md.is_symlink():
  2635. return f"legacy target has no regular SKILL.md: {target}"
  2636. actual_name = read_skill_frontmatter_name(skill_md)
  2637. if actual_name != legacy_name:
  2638. return (
  2639. f"legacy Skill identity conflict: expected {legacy_name}, "
  2640. f"found {actual_name or '<missing>'}"
  2641. )
  2642. return None
  2643. def external_skill_dependency_closure(skill_names: list[str]) -> list[str]:
  2644. selected: list[str] = []
  2645. def add(name: str) -> None:
  2646. if name in selected:
  2647. return
  2648. selected.append(name)
  2649. for dependency in MATTPOCOCK_REQUIRED_DEPENDENCIES.get(name, ()):
  2650. add(dependency)
  2651. for skill_name in skill_names:
  2652. add(skill_name)
  2653. return selected
  2654. def parse_skill_names(args: argparse.Namespace) -> list[str]:
  2655. if getattr(args, "all", False):
  2656. return external_skill_dependency_closure(list(EXTERNAL_SKILL_SOURCES.keys()))
  2657. raw = getattr(args, "skills", None)
  2658. if not raw:
  2659. raise SystemExit("--skills or --all is required")
  2660. requested = [item.strip() for item in raw.split(",") if item.strip()]
  2661. if "all" in requested:
  2662. return external_skill_dependency_closure(list(EXTERNAL_SKILL_SOURCES.keys()))
  2663. removed = [name for name in requested if name in MATTPOCOCK_REMOVED_SKILLS]
  2664. if removed:
  2665. details = "; ".join(
  2666. f"{name}: {MATTPOCOCK_REMOVED_SKILLS[name]}" for name in removed
  2667. )
  2668. raise SystemExit(f"Removed external skill(s): {details}")
  2669. canonical_requested = [canonical_external_skill_name(name) for name in requested]
  2670. unknown = [
  2671. name for name in canonical_requested if name not in EXTERNAL_SKILL_SOURCES
  2672. ]
  2673. if unknown:
  2674. known = ", ".join(EXTERNAL_SKILL_SOURCES.keys())
  2675. raise SystemExit(
  2676. f"Unknown external skill(s): {', '.join(unknown)}. Known: {known}"
  2677. )
  2678. names = canonical_requested
  2679. if getattr(args, "expand_dependencies", True):
  2680. names = external_skill_dependency_closure(canonical_requested)
  2681. unique: list[str] = []
  2682. for name in names:
  2683. if name not in unique:
  2684. unique.append(name)
  2685. return unique
  2686. def resolve_install_skills_dir(args: argparse.Namespace) -> Path:
  2687. return resolve_global_skills_dir(args.global_skills_dir)[0]
  2688. def external_install_plan(
  2689. args: argparse.Namespace, selected: list[str], target_dir: Path
  2690. ) -> dict[str, object]:
  2691. legacy_targets = [
  2692. {
  2693. "name": legacy_name,
  2694. "replacement": name,
  2695. "target": str(target_dir / legacy_name),
  2696. "targetExists": (target_dir / legacy_name).exists(),
  2697. }
  2698. for name in selected
  2699. for legacy_name in legacy_external_skill_names_for(name)
  2700. if (target_dir / legacy_name).exists()
  2701. ]
  2702. return {
  2703. "mode": "install-external-skills",
  2704. "scope": args.scope,
  2705. "requestedSource": args.source,
  2706. "targetDir": str(target_dir),
  2707. "forceOverwriteExisting": True,
  2708. "backupExistingTargets": "temporary-rollback",
  2709. "transactionalInstall": True,
  2710. "replaceFlagProvided": bool(args.replace),
  2711. "removeLegacyAfterCanonicalCommit": legacy_targets,
  2712. "skills": [
  2713. {
  2714. "name": name,
  2715. "repo": EXTERNAL_SKILL_SOURCES[name]["repo"],
  2716. "target": str(target_dir / name),
  2717. "targetExists": (target_dir / name).exists(),
  2718. }
  2719. for name in selected
  2720. ],
  2721. }
  2722. def print_external_install_plan(plan: dict[str, object], as_json: bool) -> None:
  2723. if as_json:
  2724. print(json.dumps(plan, indent=2, ensure_ascii=False))
  2725. return
  2726. print("External skill install plan")
  2727. print(f"Scope: {plan['scope']}")
  2728. print(f"Requested source: {plan['requestedSource']}")
  2729. print(f"Target skills dir: {plan['targetDir']}")
  2730. print(
  2731. "Transactional install: yes, existing targets use a temporary rollback backup"
  2732. )
  2733. legacy_items = plan.get("removeLegacyAfterCanonicalCommit")
  2734. if isinstance(legacy_items, list) and legacy_items:
  2735. print("Legacy targets removed after canonical commit:")
  2736. for item in legacy_items:
  2737. if not isinstance(item, dict):
  2738. raise RuntimeError(
  2739. "external install legacy plan entry must be an object"
  2740. )
  2741. entry = cast(dict[str, object], item)
  2742. status = "exists" if entry["targetExists"] else "missing"
  2743. print(
  2744. f"- {entry['name']} -> {entry['replacement']}: "
  2745. f"{entry['target']} ({status})"
  2746. )
  2747. skill_items = plan.get("skills")
  2748. if not isinstance(skill_items, list):
  2749. raise RuntimeError("external install plan skills must be a list")
  2750. for item in skill_items:
  2751. if not isinstance(item, dict):
  2752. raise RuntimeError("external install skill plan entry must be an object")
  2753. entry = cast(dict[str, object], item)
  2754. status = "exists" if entry["targetExists"] else "missing"
  2755. print(f"- {entry['name']}: {entry['target']} ({status})")
  2756. print(f" source: {entry['repo']}")
  2757. def discover_skill_dirs(repo_root: Path) -> list[Path]:
  2758. dirs: list[Path] = []
  2759. for skill_md in repo_root.rglob("SKILL.md"):
  2760. try:
  2761. rel = skill_md.relative_to(repo_root)
  2762. except ValueError:
  2763. continue
  2764. if ".git" in rel.parts:
  2765. continue
  2766. dirs.append(skill_md.parent)
  2767. return dirs
  2768. def resolve_contained_relative_path(root: Path, value: object, field: str) -> Path:
  2769. raw = str(value or "")
  2770. relative = Path(raw)
  2771. if not raw or relative.is_absolute() or ".." in relative.parts:
  2772. raise RuntimeError(
  2773. f"{field} must be a non-empty relative path without '..': {raw or '<missing>'}"
  2774. )
  2775. resolved_root = root.resolve()
  2776. candidate = (resolved_root / relative).resolve()
  2777. try:
  2778. candidate.relative_to(resolved_root)
  2779. except ValueError as exc:
  2780. raise RuntimeError(
  2781. f"{field} must stay within its declared root: {raw}"
  2782. ) from exc
  2783. return candidate
  2784. def source_dir_for_external_skill(repo_root: Path, skill_name: str) -> Path:
  2785. spec = EXTERNAL_SKILL_SOURCES[skill_name]
  2786. configured_subpath = spec.get("subpath")
  2787. if configured_subpath:
  2788. candidate = resolve_contained_relative_path(
  2789. repo_root, configured_subpath, f"configured subpath for {skill_name}"
  2790. )
  2791. if (candidate / "SKILL.md").is_file():
  2792. return candidate
  2793. raise RuntimeError(
  2794. f"configured subpath for {skill_name} does not contain SKILL.md: {configured_subpath}"
  2795. )
  2796. subpath = MATTPOCOCK_SKILL_SUBPATHS.get(skill_name)
  2797. if subpath:
  2798. candidate = resolve_contained_relative_path(
  2799. repo_root, subpath, f"fallback subpath for {skill_name}"
  2800. )
  2801. if (candidate / "SKILL.md").is_file():
  2802. return candidate
  2803. aliases = {str(alias) for alias in spec["aliases"]}
  2804. candidates = discover_skill_dirs(repo_root)
  2805. if not candidates:
  2806. raise RuntimeError("no SKILL.md files found in cloned repository")
  2807. by_dir_name = [candidate for candidate in candidates if candidate.name in aliases]
  2808. if len(by_dir_name) == 1:
  2809. return by_dir_name[0]
  2810. by_frontmatter = [
  2811. candidate
  2812. for candidate in candidates
  2813. if read_skill_frontmatter_name(candidate / "SKILL.md") in aliases
  2814. ]
  2815. if len(by_frontmatter) == 1:
  2816. return by_frontmatter[0]
  2817. repo = str(spec["repo"])
  2818. if len(EXTERNAL_REPO_TO_SKILLS[repo]) == 1 and len(candidates) == 1:
  2819. return candidates[0]
  2820. rel_candidates = ", ".join(
  2821. str(candidate.relative_to(repo_root)) for candidate in candidates[:20]
  2822. )
  2823. if len(candidates) > 20:
  2824. rel_candidates += ", ..."
  2825. raise RuntimeError(
  2826. f"could not uniquely locate {skill_name}; candidates: {rel_candidates}"
  2827. )
  2828. def external_tree_digest_excluded(relative: Path) -> bool:
  2829. """Locally generated caches must not change a pinned Skill's identity."""
  2830. if EXTERNAL_TREE_DIGEST_EXCLUDED_DIRS.intersection(relative.parts):
  2831. return True
  2832. return relative.suffix in EXTERNAL_TREE_DIGEST_EXCLUDED_SUFFIXES
  2833. def external_tree_sha256(root: Path) -> str:
  2834. digest = hashlib.sha256()
  2835. files = [candidate for candidate in root.rglob("*") if candidate.is_file()]
  2836. # Plain relative POSIX order, stable across operating systems: sorting
  2837. # Path objects applies normcase folding on Windows, which reorders
  2838. # case-differing names and would make pinned digests platform-dependent.
  2839. files.sort(key=lambda candidate: candidate.relative_to(root).as_posix())
  2840. for path in files:
  2841. if external_tree_digest_excluded(path.relative_to(root)):
  2842. continue
  2843. if path.is_symlink():
  2844. raise RuntimeError(
  2845. f"external Skill contains an unsupported symlink: {path.relative_to(root)}"
  2846. )
  2847. relative = path.relative_to(root).as_posix().encode("utf-8")
  2848. digest.update(len(relative).to_bytes(8, "big"))
  2849. digest.update(relative)
  2850. content = path.read_bytes()
  2851. digest.update(len(content).to_bytes(8, "big"))
  2852. digest.update(content)
  2853. return digest.hexdigest()
  2854. def prune_unmanaged_stable_skill_directories(
  2855. manifest: dict[str, object], stable_root: Path
  2856. ) -> list[str]:
  2857. skills = manifest.get("skills")
  2858. if not isinstance(skills, dict):
  2859. raise RuntimeError("stable External Skills manifest skills must be an object")
  2860. unresolved_skills_root = stable_root / "skills"
  2861. if (
  2862. not unresolved_skills_root.is_dir()
  2863. or unresolved_skills_root.is_symlink()
  2864. ):
  2865. raise RuntimeError("stable External Skills skills directory is invalid")
  2866. skills_root = unresolved_skills_root.resolve()
  2867. expected: set[str] = set()
  2868. for skill_name, entry in skills.items():
  2869. if not isinstance(skill_name, str) or not isinstance(entry, dict):
  2870. raise RuntimeError("stable External Skills manifest contains invalid skill metadata")
  2871. target = resolve_contained_relative_path(
  2872. stable_root,
  2873. entry.get("stablePath"),
  2874. f"stablePath for {skill_name}",
  2875. ).resolve()
  2876. try:
  2877. relative = target.relative_to(skills_root)
  2878. except ValueError as exc:
  2879. raise RuntimeError(
  2880. f"stablePath for {skill_name} must be under skills/"
  2881. ) from exc
  2882. if len(relative.parts) != 1:
  2883. raise RuntimeError(
  2884. f"stablePath for {skill_name} must be a direct child of skills/"
  2885. )
  2886. expected.add(relative.name)
  2887. pruned: list[str] = []
  2888. for candidate in unresolved_skills_root.iterdir():
  2889. if candidate.name in expected:
  2890. continue
  2891. remove_existing_target(candidate)
  2892. pruned.append(candidate.name)
  2893. return sorted(pruned)
  2894. def validate_external_skill_source(skill_name: str, source: Path) -> None:
  2895. if not source.is_dir() or source.is_symlink():
  2896. raise RuntimeError(
  2897. f"external Skill source is not a regular directory: {source}"
  2898. )
  2899. skill_md = source / "SKILL.md"
  2900. if not skill_md.is_file() or skill_md.is_symlink():
  2901. raise RuntimeError(
  2902. f"external Skill {skill_name} does not contain a regular SKILL.md"
  2903. )
  2904. frontmatter_name = read_skill_frontmatter_name(skill_md)
  2905. if frontmatter_name != skill_name:
  2906. raise RuntimeError(
  2907. f"external Skill {skill_name} frontmatter name is {frontmatter_name or '<missing>'}"
  2908. )
  2909. for path in source.rglob("*"):
  2910. if path.is_symlink():
  2911. raise RuntimeError(
  2912. f"external Skill {skill_name} contains an unsupported symlink: {path.relative_to(source)}"
  2913. )
  2914. def external_skill_target_is_valid(skills_root: Path, skill_name: str) -> bool:
  2915. try:
  2916. validate_external_skill_source(skill_name, skills_root / skill_name)
  2917. except (OSError, RuntimeError):
  2918. return False
  2919. return True
  2920. def load_external_stable_manifest(relaxed: bool = False) -> dict[str, object]:
  2921. try:
  2922. manifest = json.loads(EXTERNAL_STABLE_MANIFEST.read_text(encoding="utf-8"))
  2923. except (OSError, json.JSONDecodeError) as exc:
  2924. raise RuntimeError(
  2925. f"cannot read stable External Skills manifest: {exc}"
  2926. ) from exc
  2927. if manifest.get("schemaVersion") != 1:
  2928. raise RuntimeError("stable External Skills manifest schemaVersion must be 1")
  2929. repositories = manifest.get("repositories")
  2930. skills = manifest.get("skills")
  2931. if not isinstance(repositories, dict) or not isinstance(skills, dict):
  2932. raise RuntimeError(
  2933. "stable External Skills manifest must contain repositories and skills objects"
  2934. )
  2935. if not relaxed and set(skills) != set(EXTERNAL_SKILL_SOURCES):
  2936. missing = sorted(set(EXTERNAL_SKILL_SOURCES) - set(skills))
  2937. extra = sorted(set(skills) - set(EXTERNAL_SKILL_SOURCES))
  2938. raise RuntimeError(
  2939. "stable External Skills manifest does not match the canonical set; "
  2940. f"missing={missing}, extra={extra}"
  2941. )
  2942. validate_external_stable_metadata(manifest, EXTERNAL_STABLE_ROOT)
  2943. return manifest
  2944. def validate_external_stable_metadata(
  2945. manifest: dict[str, object], stable_root: Path
  2946. ) -> None:
  2947. repositories = manifest.get("repositories")
  2948. if not isinstance(repositories, dict):
  2949. raise RuntimeError(
  2950. "stable External Skills manifest repositories must be an object"
  2951. )
  2952. for repository_id, repository in repositories.items():
  2953. if not isinstance(repository, dict):
  2954. raise RuntimeError(
  2955. f"stable repository metadata is invalid: {repository_id}"
  2956. )
  2957. revision = str(repository.get("revision") or "")
  2958. if not re.fullmatch(r"[0-9a-f]{40}", revision):
  2959. raise RuntimeError(
  2960. f"stable repository revision is invalid: {repository_id}"
  2961. )
  2962. license_files = repository.get("licenseFiles")
  2963. if not isinstance(license_files, list) or not license_files:
  2964. raise RuntimeError(
  2965. f"stable repository has no licenseFiles: {repository_id}"
  2966. )
  2967. for license_entry in license_files:
  2968. if not isinstance(license_entry, dict):
  2969. raise RuntimeError(
  2970. f"stable repository has an invalid license entry: {repository_id}"
  2971. )
  2972. source = str(license_entry.get("source") or "")
  2973. stable_path = str(license_entry.get("stablePath") or "")
  2974. if not source or not stable_path:
  2975. raise RuntimeError(
  2976. f"stable repository license file is missing or invalid: {repository_id}/{stable_path}"
  2977. )
  2978. license_path = resolve_contained_relative_path(
  2979. stable_root,
  2980. stable_path,
  2981. f"license stablePath for {repository_id}",
  2982. )
  2983. if not license_path.is_file():
  2984. raise RuntimeError(
  2985. f"stable repository license file is missing or invalid: {repository_id}/{stable_path}"
  2986. )
  2987. def stable_external_skill_source(
  2988. manifest: dict[str, object],
  2989. skill_name: str,
  2990. stable_root: Path = EXTERNAL_STABLE_ROOT,
  2991. ) -> tuple[Path, str, str]:
  2992. skills = manifest["skills"]
  2993. repositories = manifest["repositories"]
  2994. assert isinstance(skills, dict)
  2995. assert isinstance(repositories, dict)
  2996. skill = skills.get(skill_name)
  2997. if not isinstance(skill, dict):
  2998. raise RuntimeError(f"stable manifest has no entry for {skill_name}")
  2999. repository_id = skill.get("repository")
  3000. repository = repositories.get(repository_id)
  3001. if not isinstance(repository_id, str) or not isinstance(repository, dict):
  3002. raise RuntimeError(f"stable manifest repository is invalid for {skill_name}")
  3003. source = resolve_contained_relative_path(
  3004. stable_root,
  3005. skill.get("stablePath"),
  3006. f"stablePath for {skill_name}",
  3007. )
  3008. validate_external_skill_source(skill_name, source)
  3009. expected_digest = str(skill.get("treeSha256") or "")
  3010. actual_digest = external_tree_sha256(source)
  3011. if not expected_digest or actual_digest != expected_digest:
  3012. raise RuntimeError(
  3013. f"stable External Skill checksum mismatch for {skill_name}: "
  3014. f"expected {expected_digest or '<missing>'}, got {actual_digest}"
  3015. )
  3016. revision = str(repository.get("revision") or "")
  3017. repo = str(repository.get("url") or "")
  3018. if not re.fullmatch(r"[0-9a-f]{40}", revision):
  3019. raise RuntimeError(
  3020. f"stable External Skill revision is invalid for {skill_name}"
  3021. )
  3022. if repo != str(EXTERNAL_SKILL_SOURCES[skill_name]["repo"]):
  3023. raise RuntimeError(
  3024. f"stable External Skill repository does not match configured source for {skill_name}"
  3025. )
  3026. return source, revision, str(manifest.get("stableSet") or "")
  3027. def clone_repo(repo: str, destination: Path) -> tuple[bool, str]:
  3028. if not shutil.which("git"):
  3029. return False, "git command not found"
  3030. try:
  3031. completed = subprocess.run(
  3032. ("git", "clone", "--depth", "1", repo, str(destination)),
  3033. check=False,
  3034. capture_output=True,
  3035. text=True,
  3036. errors="replace",
  3037. timeout=180,
  3038. )
  3039. except subprocess.TimeoutExpired:
  3040. return False, "git clone timed out after 180 seconds"
  3041. except OSError as exc:
  3042. return False, str(exc)
  3043. if completed.returncode == 0:
  3044. return True, ""
  3045. message = (completed.stderr or completed.stdout).strip()
  3046. return False, message or f"git clone exited with {completed.returncode}"
  3047. def cloned_repo_revision(repo_root: Path) -> str:
  3048. try:
  3049. completed = subprocess.run(
  3050. ("git", "-C", str(repo_root), "rev-parse", "HEAD"),
  3051. check=False,
  3052. capture_output=True,
  3053. text=True,
  3054. errors="replace",
  3055. timeout=30,
  3056. )
  3057. except (subprocess.TimeoutExpired, OSError) as exc:
  3058. raise RuntimeError(
  3059. f"cannot determine cloned repository revision: {exc}"
  3060. ) from exc
  3061. revision = completed.stdout.strip()
  3062. if completed.returncode != 0 or not re.fullmatch(r"[0-9a-f]{40}", revision):
  3063. message = (completed.stderr or completed.stdout).strip()
  3064. raise RuntimeError(
  3065. message or "cloned repository did not return a full commit revision"
  3066. )
  3067. return revision
  3068. def clone_repo_at_revision(
  3069. repo: str, revision: str, destination: Path
  3070. ) -> tuple[bool, str]:
  3071. if not shutil.which("git"):
  3072. return False, "git command not found"
  3073. if not re.fullmatch(r"[0-9a-f]{40}", revision):
  3074. return False, "revision must be a full 40-character lowercase commit SHA"
  3075. commands = (
  3076. ("git", "init", str(destination)),
  3077. ("git", "-C", str(destination), "remote", "add", "origin", repo),
  3078. ("git", "-C", str(destination), "fetch", "--depth", "1", "origin", revision),
  3079. ("git", "-C", str(destination), "checkout", "--detach", "FETCH_HEAD"),
  3080. )
  3081. for command in commands:
  3082. try:
  3083. completed = subprocess.run(
  3084. command,
  3085. check=False,
  3086. capture_output=True,
  3087. text=True,
  3088. errors="replace",
  3089. timeout=180,
  3090. )
  3091. except subprocess.TimeoutExpired:
  3092. return False, f"command timed out after 180 seconds: {shlex.join(command)}"
  3093. except OSError as exc:
  3094. return False, str(exc)
  3095. if completed.returncode != 0:
  3096. message = (completed.stderr or completed.stdout).strip()
  3097. return False, message or f"command failed: {shlex.join(command)}"
  3098. return True, ""
  3099. def copy_external_skill(source: Path, target: Path) -> tuple[str, bool, str | None]:
  3100. replaced_existing = target.exists()
  3101. if target.exists():
  3102. remove_existing_target(target)
  3103. target.parent.mkdir(parents=True, exist_ok=True)
  3104. try:
  3105. shutil.copytree(
  3106. source,
  3107. target,
  3108. ignore=external_copy_ignore(".git"),
  3109. )
  3110. except OSError as exc:
  3111. return "failed", replaced_existing, str(exc)
  3112. failures = compare_tree(source, target, EXTERNAL_TREE_COMPARE_EXCLUDED_DIRS)
  3113. if failures:
  3114. return (
  3115. "failed",
  3116. replaced_existing,
  3117. "verification failed: " + ", ".join(failures[:20]),
  3118. )
  3119. return ("replaced" if replaced_existing else "installed"), replaced_existing, None
  3120. def resolve_external_install_sources(
  3121. selected: list[str], requested_source: str, workspace: Path
  3122. ) -> dict[str, dict[str, object]]:
  3123. manifest = (
  3124. load_external_stable_manifest()
  3125. if requested_source in {"auto", "stable"}
  3126. else None
  3127. )
  3128. repo_groups: dict[str, list[str]] = {}
  3129. for name in selected:
  3130. repo = str(EXTERNAL_SKILL_SOURCES[name]["repo"])
  3131. repo_groups.setdefault(repo, []).append(name)
  3132. resolved: dict[str, dict[str, object]] = {}
  3133. for index, (repo, names) in enumerate(repo_groups.items(), start=1):
  3134. if requested_source == "upstream":
  3135. try:
  3136. repo_root = workspace / f"repo-{index}"
  3137. ok, clone_error = clone_repo(repo, repo_root)
  3138. if not ok:
  3139. raise RuntimeError(clone_error)
  3140. revision = cloned_repo_revision(repo_root)
  3141. upstream_sources: dict[str, Path] = {}
  3142. for name in names:
  3143. source = source_dir_for_external_skill(repo_root, name)
  3144. validate_external_skill_source(name, source)
  3145. upstream_sources[name] = source
  3146. for name, source in upstream_sources.items():
  3147. resolved[name] = {
  3148. "source": source,
  3149. "repo": repo,
  3150. "sourceUsed": "upstream",
  3151. "sourceRevision": revision,
  3152. "stableSet": None,
  3153. "fallbackReason": None,
  3154. }
  3155. continue
  3156. except (OSError, RuntimeError) as exc:
  3157. raise RuntimeError(
  3158. f"upstream External Skill group failed for {repo}: {exc}"
  3159. ) from exc
  3160. assert manifest is not None
  3161. stable_group: dict[str, tuple[Path, str, str]] = {}
  3162. for name in names:
  3163. stable_group[name] = stable_external_skill_source(manifest, name)
  3164. for name, (source, revision, stable_set) in stable_group.items():
  3165. resolved[name] = {
  3166. "source": source,
  3167. "repo": repo,
  3168. "sourceUsed": "stable",
  3169. "sourceRevision": revision,
  3170. "stableSet": stable_set,
  3171. "fallbackReason": None,
  3172. }
  3173. return resolved
  3174. def stage_external_skills(
  3175. selected: list[str], resolved: dict[str, dict[str, object]], target_dir: Path
  3176. ) -> Path:
  3177. target_dir.mkdir(parents=True, exist_ok=True)
  3178. staging = Path(tempfile.mkdtemp(prefix=".sbtd-external-staging-", dir=target_dir))
  3179. try:
  3180. for name in selected:
  3181. source = Path(str(resolved[name]["source"]))
  3182. destination = staging / name
  3183. shutil.copytree(
  3184. source,
  3185. destination,
  3186. ignore=external_copy_ignore(".git"),
  3187. )
  3188. validate_external_skill_source(name, destination)
  3189. failures = compare_tree(source, destination, EXTERNAL_TREE_COMPARE_EXCLUDED_DIRS)
  3190. if failures:
  3191. raise RuntimeError(
  3192. f"staging verification failed for {name}: "
  3193. + ", ".join(failures[:20])
  3194. )
  3195. return staging
  3196. except Exception:
  3197. shutil.rmtree(staging, ignore_errors=True)
  3198. raise
  3199. def commit_external_skill_transaction(
  3200. selected: list[str],
  3201. resolved: dict[str, dict[str, object]],
  3202. target_dir: Path,
  3203. staging: Path,
  3204. ) -> tuple[list[dict[str, object]], dict[str, object]]:
  3205. legacy_names: list[str] = []
  3206. for name in selected:
  3207. for legacy_name in legacy_external_skill_names_for(name):
  3208. if legacy_name not in legacy_names:
  3209. legacy_names.append(legacy_name)
  3210. identity_conflicts = [
  3211. {
  3212. "name": legacy_name,
  3213. "replacement": canonical_external_skill_name(legacy_name),
  3214. "target": str(target_dir / legacy_name),
  3215. "status": "failed",
  3216. "phase": "preflight-legacy-identity",
  3217. "error": identity_error,
  3218. }
  3219. for legacy_name in legacy_names
  3220. if filesystem_entry_exists(target_dir / legacy_name)
  3221. if (
  3222. identity_error := legacy_external_skill_identity_error(
  3223. target_dir / legacy_name, legacy_name
  3224. )
  3225. )
  3226. is not None
  3227. ]
  3228. if identity_conflicts:
  3229. shutil.rmtree(staging, ignore_errors=True)
  3230. return identity_conflicts, {
  3231. "status": "aborted-before-commit",
  3232. "rolledBack": False,
  3233. "rollbackErrors": [],
  3234. "rollbackPath": None,
  3235. }
  3236. rollback = Path(
  3237. tempfile.mkdtemp(prefix=".sbtd-external-rollback-", dir=target_dir)
  3238. )
  3239. existed = {name: filesystem_entry_exists(target_dir / name) for name in selected}
  3240. moved: list[tuple[Path, Path]] = []
  3241. committed: list[Path] = []
  3242. results: list[dict[str, object]] = []
  3243. rollback_errors: list[str] = []
  3244. retain_rollback = False
  3245. try:
  3246. for name in (*selected, *legacy_names):
  3247. target = target_dir / name
  3248. if not filesystem_entry_exists(target):
  3249. continue
  3250. backup = rollback / name
  3251. shutil.move(str(target), str(backup))
  3252. moved.append((target, backup))
  3253. for name in selected:
  3254. target = target_dir / name
  3255. shutil.move(str(staging / name), str(target))
  3256. committed.append(target)
  3257. source_info = resolved[name]
  3258. result = {
  3259. "name": name,
  3260. "repo": source_info["repo"],
  3261. "target": str(target),
  3262. "status": "replaced" if existed[name] else "installed",
  3263. "phase": "commit",
  3264. "replacedExisting": existed[name],
  3265. "sourceUsed": source_info["sourceUsed"],
  3266. "sourceRevision": source_info["sourceRevision"],
  3267. "stableSet": source_info.get("stableSet"),
  3268. "fallbackReason": source_info.get("fallbackReason"),
  3269. }
  3270. results.append(result)
  3271. for legacy_name in legacy_names:
  3272. if (rollback / legacy_name).exists():
  3273. results.append(
  3274. {
  3275. "name": legacy_name,
  3276. "replacement": canonical_external_skill_name(legacy_name),
  3277. "target": str(target_dir / legacy_name),
  3278. "status": "removed",
  3279. "phase": "remove-legacy-after-commit",
  3280. }
  3281. )
  3282. transaction = {
  3283. "status": "committed",
  3284. "rolledBack": False,
  3285. "rollbackErrors": [],
  3286. "rollbackPath": None,
  3287. }
  3288. return results, transaction
  3289. except Exception as exc: # noqa: BLE001 - rollback must cover every local commit failure.
  3290. for target in reversed(committed):
  3291. try:
  3292. remove_existing_target(target)
  3293. except Exception as rollback_exc: # noqa: BLE001 - aggregate rollback failures.
  3294. rollback_errors.append(f"remove {target}: {rollback_exc}")
  3295. for target, backup in reversed(moved):
  3296. try:
  3297. if target.exists():
  3298. remove_existing_target(target)
  3299. shutil.move(str(backup), str(target))
  3300. except Exception as rollback_exc: # noqa: BLE001 - aggregate rollback failures.
  3301. rollback_errors.append(f"restore {target}: {rollback_exc}")
  3302. results = [
  3303. {
  3304. "name": name,
  3305. "repo": resolved[name]["repo"],
  3306. "target": str(target_dir / name),
  3307. "status": "failed",
  3308. "phase": "commit",
  3309. "sourceUsed": resolved[name]["sourceUsed"],
  3310. "sourceRevision": resolved[name]["sourceRevision"],
  3311. "stableSet": resolved[name].get("stableSet"),
  3312. "fallbackReason": resolved[name].get("fallbackReason"),
  3313. "error": str(exc),
  3314. }
  3315. for name in selected
  3316. ]
  3317. retain_rollback = bool(rollback_errors)
  3318. return results, {
  3319. "status": "rollback-failed" if rollback_errors else "rolled-back",
  3320. "rolledBack": True,
  3321. "rollbackErrors": rollback_errors,
  3322. "rollbackPath": str(rollback) if retain_rollback else None,
  3323. }
  3324. finally:
  3325. shutil.rmtree(staging, ignore_errors=True)
  3326. if not retain_rollback:
  3327. shutil.rmtree(rollback, ignore_errors=True)
  3328. def remove_legacy_external_targets(
  3329. target_dir: Path,
  3330. selected: list[str],
  3331. extra_legacy_names: list[str] | None = None,
  3332. ) -> list[dict[str, object]]:
  3333. results: list[dict[str, object]] = []
  3334. legacy_names: list[str] = []
  3335. for name in selected:
  3336. for legacy_name in legacy_external_skill_names_for(name):
  3337. if legacy_name not in legacy_names:
  3338. legacy_names.append(legacy_name)
  3339. for legacy_name in extra_legacy_names or []:
  3340. if legacy_name not in legacy_names:
  3341. legacy_names.append(legacy_name)
  3342. for legacy_name in legacy_names:
  3343. target = target_dir / legacy_name
  3344. if not filesystem_entry_exists(target):
  3345. continue
  3346. identity_error = legacy_external_skill_identity_error(target, legacy_name)
  3347. if identity_error is not None:
  3348. results.append(
  3349. {
  3350. "name": legacy_name,
  3351. "replacement": canonical_external_skill_name(legacy_name),
  3352. "target": str(target),
  3353. "status": "failed",
  3354. "phase": "preflight-legacy-identity",
  3355. "error": identity_error,
  3356. }
  3357. )
  3358. continue
  3359. try:
  3360. remove_existing_target(target)
  3361. results.append(
  3362. {
  3363. "name": legacy_name,
  3364. "replacement": canonical_external_skill_name(legacy_name),
  3365. "target": str(target),
  3366. "status": "removed",
  3367. "phase": "remove-legacy",
  3368. }
  3369. )
  3370. except Exception as exc: # noqa: BLE001 - keep cleanup report per target.
  3371. results.append(
  3372. {
  3373. "name": legacy_name,
  3374. "replacement": canonical_external_skill_name(legacy_name),
  3375. "target": str(target),
  3376. "status": "failed",
  3377. "phase": "remove-legacy",
  3378. "error": str(exc),
  3379. }
  3380. )
  3381. return results
  3382. def scoped_skills_root(args: argparse.Namespace) -> Path:
  3383. return resolve_global_skills_dir(args.global_skills_dir)[0]
  3384. def external_migration_timestamp() -> str:
  3385. return dt.datetime.now().strftime("%Y%m%d-%H%M%S")
  3386. def external_migration_backup_root(skills_root: Path) -> Path:
  3387. return skills_root.with_name(f"{skills_root.name}-backups")
  3388. def detected_mattpocock_skill_names(skills_root: Path) -> list[str]:
  3389. candidates = (
  3390. *MATTPOCOCK_CANONICAL_SKILLS,
  3391. *MATTPOCOCK_LEGACY_RENAMES.keys(),
  3392. *MATTPOCOCK_REMOVED_SKILLS.keys(),
  3393. )
  3394. detected: list[str] = []
  3395. for name in candidates:
  3396. target = skills_root / name
  3397. if filesystem_entry_exists(target):
  3398. detected.append(name)
  3399. return detected
  3400. def canonical_migration_targets(detected: list[str]) -> list[str]:
  3401. selected: list[str] = []
  3402. for name in detected:
  3403. if name in MATTPOCOCK_REMOVED_SKILLS:
  3404. continue
  3405. selected.append(canonical_external_skill_name(name))
  3406. return external_skill_dependency_closure(selected)
  3407. def build_external_migration_plan(args: argparse.Namespace) -> dict[str, object]:
  3408. skills_root = scoped_skills_root(args)
  3409. detected = detected_mattpocock_skill_names(skills_root)
  3410. legacy = [
  3411. name
  3412. for name in detected
  3413. if name in MATTPOCOCK_LEGACY_RENAMES or name in MATTPOCOCK_REMOVED_SKILLS
  3414. ]
  3415. selected = canonical_migration_targets(legacy)
  3416. canonical = [name for name in detected if name in MATTPOCOCK_CANONICAL_SKILLS]
  3417. return {
  3418. "mode": "mattpocock-external-migration",
  3419. "status": "planned" if legacy else "skipped",
  3420. "reason": None
  3421. if legacy
  3422. else "no legacy mattpocock skills detected in global skills root",
  3423. "targetDir": str(skills_root),
  3424. "detectedLegacy": legacy,
  3425. "detectedCanonical": canonical,
  3426. "requiredCanonical": selected,
  3427. "removeLegacy": legacy,
  3428. "backupRoot": str(external_migration_backup_root(skills_root)),
  3429. "autoMode": "legacy-only",
  3430. }
  3431. def backup_skill_target(target: Path, backup_dir: Path) -> str | None:
  3432. if not target.exists():
  3433. return None
  3434. destination = backup_dir / target.name
  3435. if destination.exists():
  3436. remove_existing_target(destination)
  3437. backup_dir.mkdir(parents=True, exist_ok=True)
  3438. if target.is_dir() and not target.is_symlink():
  3439. shutil.copytree(target, destination, ignore=external_copy_ignore())
  3440. else:
  3441. shutil.copy2(target, destination)
  3442. return str(destination)
  3443. def run_external_migration(plan: dict[str, object]) -> list[dict[str, object]]:
  3444. if plan["status"] != "planned":
  3445. return [
  3446. {
  3447. "status": "skipped",
  3448. "reason": plan.get("reason"),
  3449. }
  3450. ]
  3451. target_dir = Path(str(plan["targetDir"]))
  3452. remove_legacy = plan.get("removeLegacy")
  3453. if not isinstance(remove_legacy, list):
  3454. raise RuntimeError("external migration removeLegacy must be a list")
  3455. legacy = [
  3456. str(name)
  3457. for name in remove_legacy
  3458. if filesystem_entry_exists(target_dir / str(name))
  3459. ]
  3460. if not legacy:
  3461. return [
  3462. {
  3463. "status": "skipped",
  3464. "reason": "legacy targets were already handled by canonical installation",
  3465. }
  3466. ]
  3467. backup_dir = (
  3468. external_migration_backup_root(target_dir)
  3469. / f"mattpocock-1.0-migration-{external_migration_timestamp()}"
  3470. )
  3471. results: list[dict[str, object]] = []
  3472. for name in legacy:
  3473. identity_error = legacy_external_skill_identity_error(target_dir / name, name)
  3474. if identity_error is not None:
  3475. results.append(
  3476. {
  3477. "name": name,
  3478. "replacement": canonical_external_skill_name(name),
  3479. "target": str(target_dir / name),
  3480. "status": "failed",
  3481. "phase": "preflight-legacy-identity",
  3482. "error": identity_error,
  3483. }
  3484. )
  3485. continue
  3486. if name in MATTPOCOCK_LEGACY_RENAMES:
  3487. replacement = canonical_external_skill_name(name)
  3488. if not external_skill_target_is_valid(target_dir, replacement):
  3489. results.append(
  3490. {
  3491. "name": name,
  3492. "status": "failed",
  3493. "phase": "preflight",
  3494. "error": f"canonical replacement is missing: {replacement}",
  3495. }
  3496. )
  3497. if results:
  3498. return results
  3499. for name in legacy:
  3500. try:
  3501. backup = backup_skill_target(target_dir / name, backup_dir)
  3502. results.append({"name": name, "status": "backed-up", "backup": backup})
  3503. except Exception as exc: # noqa: BLE001 - keep migration report per target.
  3504. results.append(
  3505. {"name": name, "status": "failed", "phase": "backup", "error": str(exc)}
  3506. )
  3507. if any(item["status"] == "failed" for item in results):
  3508. return results
  3509. legacy_removals = remove_legacy_external_targets(target_dir, [], legacy)
  3510. results.extend(legacy_removals)
  3511. return results
  3512. def execute_external_skill_install(
  3513. args: argparse.Namespace, selected: list[str], target_dir: Path
  3514. ) -> tuple[list[dict[str, object]], dict[str, object]]:
  3515. try:
  3516. with tempfile.TemporaryDirectory(
  3517. prefix="sbtd-onboard-external-sources-"
  3518. ) as tmp:
  3519. resolved = resolve_external_install_sources(
  3520. selected, args.source, Path(tmp)
  3521. )
  3522. staging = stage_external_skills(selected, resolved, target_dir)
  3523. return commit_external_skill_transaction(
  3524. selected, resolved, target_dir, staging
  3525. )
  3526. except Exception as exc: # noqa: BLE001 - no target is changed before the transaction begins.
  3527. return (
  3528. [
  3529. {
  3530. "name": name,
  3531. "repo": EXTERNAL_SKILL_SOURCES[name]["repo"],
  3532. "target": str(target_dir / name),
  3533. "status": "failed",
  3534. "phase": "prepare",
  3535. "error": str(exc),
  3536. }
  3537. for name in selected
  3538. ],
  3539. {
  3540. "status": "aborted-before-commit",
  3541. "rolledBack": False,
  3542. "rollbackErrors": [],
  3543. "rollbackPath": None,
  3544. },
  3545. )
  3546. def external_migration_identity_failures(
  3547. plan: dict[str, object]
  3548. ) -> list[dict[str, object]]:
  3549. target_dir = Path(str(plan["targetDir"]))
  3550. remove_legacy = plan.get("removeLegacy")
  3551. if not isinstance(remove_legacy, list):
  3552. raise TypeError("external migration removeLegacy must be a list")
  3553. return [
  3554. {
  3555. "name": name,
  3556. "replacement": canonical_external_skill_name(name),
  3557. "target": str(target_dir / name),
  3558. "status": "failed",
  3559. "phase": "preflight-legacy-identity",
  3560. "error": identity_error,
  3561. }
  3562. for name in (str(name) for name in remove_legacy)
  3563. if filesystem_entry_exists(target_dir / name)
  3564. if (
  3565. identity_error := legacy_external_skill_identity_error(
  3566. target_dir / name, name
  3567. )
  3568. )
  3569. is not None
  3570. ]
  3571. def migrate_external_skills(args: argparse.Namespace) -> int:
  3572. plan = build_external_migration_plan(args)
  3573. payload: dict[str, object] = {
  3574. "mode": "migrate-external-skills",
  3575. "scope": args.scope,
  3576. "requestedSource": args.source,
  3577. "targetDir": plan["targetDir"],
  3578. "plan": plan,
  3579. "installationResults": [],
  3580. "transaction": {
  3581. "status": "not-required",
  3582. "rolledBack": False,
  3583. "rollbackErrors": [],
  3584. "rollbackPath": None,
  3585. },
  3586. "results": [],
  3587. }
  3588. if plan["status"] == "skipped":
  3589. payload["status"] = "skipped"
  3590. payload["results"] = [
  3591. {"status": "skipped", "reason": plan.get("reason")}
  3592. ]
  3593. if args.json:
  3594. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3595. else:
  3596. print_external_migration_report(cast(list[dict[str, object]], payload["results"]))
  3597. return 0
  3598. identity_failures = external_migration_identity_failures(plan)
  3599. if identity_failures:
  3600. payload["status"] = "failed"
  3601. payload["results"] = identity_failures
  3602. if args.json:
  3603. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3604. else:
  3605. print_external_migration_report(identity_failures)
  3606. return 1
  3607. if not args.yes:
  3608. payload["status"] = "needs-confirmation"
  3609. if args.json:
  3610. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3611. else:
  3612. print_external_migration_report(
  3613. [{"status": "needs-confirmation", "reason": "rerun with --yes"}]
  3614. )
  3615. return 2
  3616. required_canonical = plan["requiredCanonical"]
  3617. if not isinstance(required_canonical, list):
  3618. raise TypeError("external migration requiredCanonical must be a list")
  3619. selected = [str(name) for name in required_canonical]
  3620. installation_results: list[dict[str, object]] = []
  3621. if selected:
  3622. target_dir = Path(str(plan["targetDir"]))
  3623. installation_results, transaction = execute_external_skill_install(
  3624. args, selected, target_dir
  3625. )
  3626. payload["installationResults"] = installation_results
  3627. payload["transaction"] = transaction
  3628. if transaction["status"] != "committed":
  3629. payload["status"] = "failed"
  3630. payload["results"] = installation_results
  3631. if args.json:
  3632. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3633. else:
  3634. print_external_migration_report(installation_results)
  3635. return 1
  3636. migration_results = run_external_migration(build_external_migration_plan(args))
  3637. results = [*installation_results, *migration_results]
  3638. payload["results"] = results
  3639. failed = [item for item in results if item["status"] == "failed"]
  3640. payload["status"] = "failed" if failed else "migrated"
  3641. if args.json:
  3642. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3643. else:
  3644. print_external_migration_report(results)
  3645. return 1 if failed else 0
  3646. def perform_external_skill_install(
  3647. args: argparse.Namespace,
  3648. selected: list[str],
  3649. target_dir: Path,
  3650. plan: dict[str, object],
  3651. ) -> dict[str, object]:
  3652. """Install one transaction and return its report without printing."""
  3653. results, transaction = execute_external_skill_install(args, selected, target_dir)
  3654. post_check = build_check_results(args)
  3655. return {
  3656. "mode": "install-external-skills",
  3657. "scope": args.scope,
  3658. "requestedSource": args.source,
  3659. "targetDir": str(target_dir),
  3660. "forceOverwriteExisting": True,
  3661. "backupExistingTargets": "temporary-rollback",
  3662. "replaceFlagProvided": bool(args.replace),
  3663. "plan": plan,
  3664. "results": results,
  3665. "transaction": transaction,
  3666. "postCheck": post_check,
  3667. "installationReport": post_check["installationReport"],
  3668. }
  3669. def print_external_skill_install_result(
  3670. payload: dict[str, object], as_json: bool
  3671. ) -> None:
  3672. if as_json:
  3673. print(json.dumps(payload, indent=2, ensure_ascii=False))
  3674. return
  3675. results = cast(list[dict[str, object]], payload["results"])
  3676. transaction = cast(dict[str, object], payload["transaction"])
  3677. print("\nExternal skill install results")
  3678. for item in results:
  3679. print(f"- {item['name']}: {item['status']}")
  3680. if item.get("target"):
  3681. print(f" target: {item['target']}")
  3682. if item.get("sourceUsed"):
  3683. print(f" source: {item['sourceUsed']} ({item.get('sourceRevision')})")
  3684. if item.get("fallbackReason"):
  3685. print(f" fallback: {item['fallbackReason']}")
  3686. if item.get("error"):
  3687. print(f" note: {item['error']}")
  3688. print(f"Transaction: {transaction['status']}")
  3689. if transaction.get("rollbackPath"):
  3690. print(f"Rollback backup retained at: {transaction['rollbackPath']}")
  3691. rollback_errors = transaction.get("rollbackErrors")
  3692. if isinstance(rollback_errors, list):
  3693. for rollback_error in rollback_errors:
  3694. print(f" rollback error: {rollback_error}")
  3695. print_installation_report(
  3696. cast(dict[str, object], payload["installationReport"]),
  3697. "Final installation report",
  3698. )
  3699. def install_external_skills(args: argparse.Namespace) -> int:
  3700. selected = parse_skill_names(args)
  3701. target_dir = resolve_install_skills_dir(args)
  3702. plan = external_install_plan(args, selected, target_dir)
  3703. if not args.yes:
  3704. print_external_install_plan(plan, args.json)
  3705. print(
  3706. "Refusing to install external skills without --yes. Confirm with the user, then rerun with --yes.",
  3707. file=sys.stderr,
  3708. )
  3709. return 2
  3710. if not args.json:
  3711. print_external_install_plan(plan, False)
  3712. payload = perform_external_skill_install(args, selected, target_dir, plan)
  3713. print_external_skill_install_result(payload, args.json)
  3714. transaction = cast(dict[str, object], payload["transaction"])
  3715. return 1 if transaction["status"] != "committed" else 0
  3716. def stable_notice_attribution(repository_url: str) -> str:
  3717. path_parts = [
  3718. part for part in repository_url.removesuffix(".git").split("/") if part
  3719. ]
  3720. if len(path_parts) < 2:
  3721. raise RuntimeError(
  3722. f"cannot derive repository attribution from {repository_url}"
  3723. )
  3724. return "/".join(path_parts[-2:])
  3725. def upsert_stable_third_party_notice(
  3726. notice_path: Path,
  3727. repository_url: str,
  3728. license_name: str,
  3729. license_file_mappings: list[dict[str, str]],
  3730. ) -> str:
  3731. attribution = stable_notice_attribution(repository_url)
  3732. license_refs = ", ".join(
  3733. f"`{mapping['stablePath']}`" for mapping in license_file_mappings
  3734. )
  3735. row = f"| `{attribution}` | {license_name} | {license_refs} |"
  3736. text = (
  3737. notice_path.read_text(encoding="utf-8") if notice_path.is_file() else ""
  3738. )
  3739. marker = f"| `{attribution}` |"
  3740. if marker in text:
  3741. text = "\n".join(
  3742. line for line in text.splitlines() if not line.startswith(marker)
  3743. )
  3744. if text and not text.endswith("\n"):
  3745. text += "\n"
  3746. notice_path.write_text(text + row + "\n", encoding="utf-8")
  3747. return row
  3748. def parse_license_file_mappings(values: object) -> list[dict[str, str]]:
  3749. if values is None:
  3750. return []
  3751. mappings: list[dict[str, str]] = []
  3752. for raw in cast(list[str], values):
  3753. source, separator, stable_path = str(raw).partition("=")
  3754. if not separator or not source.strip() or not stable_path.strip():
  3755. raise SystemExit(
  3756. "--license-file must use SOURCE=STABLE_PATH, for example "
  3757. "LICENSE=licenses/ponytail-LICENSE"
  3758. )
  3759. mappings.append({"source": source.strip(), "stablePath": stable_path.strip()})
  3760. return mappings
  3761. def promote_external_skills_stable(args: argparse.Namespace) -> int:
  3762. if not re.fullmatch(r"[0-9a-f]{40}", str(args.revision)):
  3763. raise SystemExit(
  3764. "--revision must be a full 40-character lowercase commit SHA"
  3765. )
  3766. manifest = load_external_stable_manifest(relaxed=True)
  3767. repositories = cast(dict[str, object], manifest["repositories"])
  3768. skills = cast(dict[str, object], manifest["skills"])
  3769. existing_repository = repositories.get(args.repository)
  3770. registration = not isinstance(existing_repository, dict)
  3771. license_name = ""
  3772. license_file_mappings: list[dict[str, str]]
  3773. if registration:
  3774. if re.fullmatch(r"[a-z0-9][a-z0-9-]*", str(args.repository)) is None:
  3775. raise SystemExit(f"Invalid stable repository id: {args.repository}")
  3776. repository_url = str(getattr(args, "repo", None) or "")
  3777. if not valid_https_repository_url(repository_url):
  3778. raise SystemExit(
  3779. "First-time stable repository registration requires --repo with a "
  3780. "valid HTTPS repository URL."
  3781. )
  3782. license_name = str(getattr(args, "license", None) or "").strip()
  3783. if not license_name:
  3784. raise SystemExit(
  3785. "First-time stable repository registration requires --license with "
  3786. "an SPDX license id."
  3787. )
  3788. license_file_mappings = parse_license_file_mappings(
  3789. getattr(args, "license_files", None)
  3790. )
  3791. if not license_file_mappings:
  3792. raise SystemExit(
  3793. "First-time stable repository registration requires at least one "
  3794. "--license-file SOURCE=STABLE_PATH mapping."
  3795. )
  3796. selected = [
  3797. name
  3798. for name, source_spec in EXTERNAL_SKILL_SOURCES.items()
  3799. if str(source_spec["repo"]) == repository_url
  3800. ]
  3801. if not selected:
  3802. raise SystemExit(
  3803. f"No catalog external Skills match --repo {repository_url}; register "
  3804. "the catalog entries before promotion."
  3805. )
  3806. else:
  3807. repository = cast(dict[str, object], existing_repository)
  3808. repository_url = str(repository.get("url") or "")
  3809. if getattr(args, "repo", None) and str(args.repo) != repository_url:
  3810. raise SystemExit(
  3811. f"--repo {args.repo} does not match the stable repository URL "
  3812. f"{repository_url}; refusing to rewrite repository metadata."
  3813. )
  3814. if getattr(args, "license", None) or getattr(args, "license_files", None):
  3815. raise SystemExit(
  3816. "--license/--license-file are only valid for first-time repository "
  3817. "registration; refusing to rewrite existing repository metadata."
  3818. )
  3819. existing_license_files = repository.get("licenseFiles")
  3820. if not isinstance(existing_license_files, list):
  3821. raise SystemExit(
  3822. f"stable repository {args.repository} has no licenseFiles list"
  3823. )
  3824. license_file_mappings = cast(
  3825. list[dict[str, str]], existing_license_files
  3826. )
  3827. selected = [
  3828. name
  3829. for name, entry in skills.items()
  3830. if isinstance(entry, dict) and entry.get("repository") == args.repository
  3831. ]
  3832. plan = {
  3833. "mode": "promote-external-skills-stable",
  3834. "repository": args.repository,
  3835. "repo": repository_url,
  3836. "registration": registration,
  3837. "revision": args.revision,
  3838. "stableSet": args.stable_set,
  3839. "skills": selected,
  3840. "target": str(EXTERNAL_STABLE_ROOT),
  3841. }
  3842. if not args.yes:
  3843. if args.json:
  3844. print(json.dumps(plan, indent=2, ensure_ascii=False))
  3845. else:
  3846. print("Stable External Skills promotion plan")
  3847. for key, value in plan.items():
  3848. print(f"- {key}: {value}")
  3849. print("Refusing to promote without --yes.", file=sys.stderr)
  3850. return 2
  3851. payload: dict[str, object] = {**plan, "status": "failed"}
  3852. with tempfile.TemporaryDirectory(prefix="sbtd-external-promotion-source-") as tmp:
  3853. repo_root = Path(tmp) / "repository"
  3854. ok, error = clone_repo_at_revision(repository_url, args.revision, repo_root)
  3855. if not ok:
  3856. payload["error"] = error
  3857. print(
  3858. json.dumps(payload, indent=2, ensure_ascii=False)
  3859. if args.json
  3860. else error
  3861. )
  3862. return 1
  3863. candidate_container = Path(
  3864. tempfile.mkdtemp(
  3865. prefix=".sbtd-stable-promotion-", dir=EXTERNAL_STABLE_ROOT.parent
  3866. )
  3867. )
  3868. candidate_root = candidate_container / "stable"
  3869. previous_root = candidate_container / "previous"
  3870. retain_candidate_container = False
  3871. try:
  3872. shutil.copytree(
  3873. EXTERNAL_STABLE_ROOT,
  3874. candidate_root,
  3875. ignore=external_copy_ignore(".git"),
  3876. )
  3877. candidate_manifest = json.loads(json.dumps(manifest))
  3878. candidate_repositories = cast(
  3879. dict[str, object], candidate_manifest["repositories"]
  3880. )
  3881. candidate_skills = cast(dict[str, object], candidate_manifest["skills"])
  3882. if registration:
  3883. candidate_repositories[args.repository] = {
  3884. "url": repository_url,
  3885. "revision": args.revision,
  3886. "license": license_name,
  3887. "licenseFiles": license_file_mappings,
  3888. }
  3889. for name in selected:
  3890. candidate_skills[name] = {
  3891. "repository": args.repository,
  3892. "sourceSubpath": str(
  3893. EXTERNAL_SKILL_SOURCES[name]["subpath"]
  3894. ),
  3895. "stablePath": f"skills/{name}",
  3896. }
  3897. for name in selected:
  3898. entry = candidate_skills[name]
  3899. if not isinstance(entry, dict):
  3900. raise RuntimeError(f"stable Skill metadata is invalid: {name}")
  3901. entry = cast(dict[str, object], entry)
  3902. source = resolve_contained_relative_path(
  3903. repo_root,
  3904. entry.get("sourceSubpath"),
  3905. f"sourceSubpath for {name}",
  3906. )
  3907. validate_external_skill_source(name, source)
  3908. destination = resolve_contained_relative_path(
  3909. candidate_root,
  3910. entry.get("stablePath"),
  3911. f"stablePath for {name}",
  3912. )
  3913. if destination.exists():
  3914. remove_existing_target(destination)
  3915. shutil.copytree(
  3916. source,
  3917. destination,
  3918. ignore=external_copy_ignore(".git"),
  3919. )
  3920. validate_external_skill_source(name, destination)
  3921. entry["treeSha256"] = external_tree_sha256(destination)
  3922. payload["prunedStableSkills"] = prune_unmanaged_stable_skill_directories(
  3923. candidate_manifest, candidate_root
  3924. )
  3925. for license_entry in license_file_mappings:
  3926. source = resolve_contained_relative_path(
  3927. repo_root,
  3928. license_entry.get("source"),
  3929. f"license source for {args.repository}",
  3930. )
  3931. destination = resolve_contained_relative_path(
  3932. candidate_root,
  3933. license_entry.get("stablePath"),
  3934. f"license stablePath for {args.repository}",
  3935. )
  3936. if not source.is_file():
  3937. raise RuntimeError(
  3938. f"required upstream license file is missing: {source}"
  3939. )
  3940. destination.parent.mkdir(parents=True, exist_ok=True)
  3941. shutil.copy2(source, destination)
  3942. if registration:
  3943. upsert_stable_third_party_notice(
  3944. candidate_root / "THIRD_PARTY_NOTICES.md",
  3945. repository_url,
  3946. license_name,
  3947. license_file_mappings,
  3948. )
  3949. notice_text = (candidate_root / "THIRD_PARTY_NOTICES.md").read_text(
  3950. encoding="utf-8"
  3951. )
  3952. attribution = stable_notice_attribution(repository_url)
  3953. if f"| `{attribution}` |" not in notice_text:
  3954. raise RuntimeError(
  3955. "candidate THIRD_PARTY_NOTICES.md has no attribution row for "
  3956. f"{attribution}"
  3957. )
  3958. candidate_repository = candidate_repositories[args.repository]
  3959. if not isinstance(candidate_repository, dict):
  3960. raise RuntimeError(
  3961. f"stable repository metadata is invalid: {args.repository}"
  3962. )
  3963. candidate_repository = cast(dict[str, object], candidate_repository)
  3964. candidate_repository["revision"] = args.revision
  3965. candidate_manifest["stableSet"] = args.stable_set
  3966. candidate_manifest["promotedAt"] = dt.date.today().isoformat()
  3967. (candidate_root / "MANIFEST.json").write_text(
  3968. json.dumps(candidate_manifest, indent=2, ensure_ascii=False) + "\n",
  3969. encoding="utf-8",
  3970. )
  3971. candidate_skill_names = set(
  3972. cast(dict[str, object], candidate_manifest["skills"])
  3973. )
  3974. if candidate_skill_names != set(EXTERNAL_SKILL_SOURCES):
  3975. missing_names = sorted(
  3976. set(EXTERNAL_SKILL_SOURCES) - candidate_skill_names
  3977. )
  3978. extra_names = sorted(
  3979. candidate_skill_names - set(EXTERNAL_SKILL_SOURCES)
  3980. )
  3981. raise RuntimeError(
  3982. "candidate stable manifest does not match the canonical "
  3983. f"catalog set; missing={missing_names}, extra={extra_names}"
  3984. )
  3985. validate_external_stable_metadata(candidate_manifest, candidate_root)
  3986. for name in EXTERNAL_SKILL_SOURCES:
  3987. stable_external_skill_source(candidate_manifest, name, candidate_root)
  3988. shutil.move(str(EXTERNAL_STABLE_ROOT), str(previous_root))
  3989. try:
  3990. shutil.move(str(candidate_root), str(EXTERNAL_STABLE_ROOT))
  3991. except Exception as commit_exc:
  3992. try:
  3993. shutil.move(str(previous_root), str(EXTERNAL_STABLE_ROOT))
  3994. except Exception as restore_exc:
  3995. retain_candidate_container = True
  3996. raise RuntimeError(
  3997. "stable promotion commit and rollback failed; previous stable set retained at "
  3998. f"{previous_root}: commit={commit_exc}; rollback={restore_exc}"
  3999. ) from restore_exc
  4000. raise
  4001. payload["status"] = "promoted"
  4002. payload["promotedSkills"] = selected
  4003. except Exception as exc: # noqa: BLE001 - promotion keeps the prior stable set on every failure.
  4004. payload["error"] = str(exc)
  4005. finally:
  4006. if not retain_candidate_container:
  4007. shutil.rmtree(candidate_container, ignore_errors=True)
  4008. if args.json:
  4009. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4010. else:
  4011. print(f"Stable External Skills promotion: {payload['status']}")
  4012. if payload.get("error"):
  4013. print(f"- error: {payload['error']}")
  4014. elif payload.get("promotedSkills"):
  4015. print("- promoted: " + ", ".join(selected))
  4016. return 0 if payload["status"] == "promoted" else 1
  4017. def missing_required_external_skills(args: argparse.Namespace) -> list[str]:
  4018. global_skills_dir = resolve_global_skills_dir(
  4019. getattr(args, "global_skills_dir", None)
  4020. )[0]
  4021. return [
  4022. name
  4023. for name in EXTERNAL_SKILL_SOURCES
  4024. if not external_skill_target_is_valid(global_skills_dir, name)
  4025. ]
  4026. def install_required_external_skills(
  4027. args: argparse.Namespace, *, overwrite: bool = False
  4028. ) -> dict[str, object] | None:
  4029. if overwrite:
  4030. selected = list(EXTERNAL_SKILL_SOURCES)
  4031. if not args.json:
  4032. print(
  4033. "Reset will overwrite all required global external Skills: "
  4034. + ", ".join(selected)
  4035. )
  4036. else:
  4037. selected = missing_required_external_skills(args)
  4038. if not selected:
  4039. return None
  4040. if not args.json:
  4041. print(
  4042. "Required global external Skills are missing and will be installed: "
  4043. + ", ".join(selected)
  4044. )
  4045. install_args = argparse.Namespace(
  4046. all=overwrite,
  4047. skills=None if overwrite else ",".join(selected),
  4048. scope="global",
  4049. source="auto",
  4050. global_skills_dir=getattr(args, "global_skills_dir", None),
  4051. replace=False,
  4052. yes=True,
  4053. json=args.json,
  4054. expand_dependencies=overwrite,
  4055. )
  4056. selected = parse_skill_names(install_args)
  4057. target_dir = resolve_install_skills_dir(install_args)
  4058. plan = external_install_plan(install_args, selected, target_dir)
  4059. if not args.json:
  4060. print_external_install_plan(plan, False)
  4061. payload = perform_external_skill_install(install_args, selected, target_dir, plan)
  4062. if not args.json:
  4063. print_external_skill_install_result(payload, False)
  4064. return payload
  4065. def default_shell_profile() -> Path:
  4066. shell_name = Path(os.environ.get("SHELL", "")).name
  4067. if shell_name == "zsh":
  4068. return Path.home() / ".zshrc"
  4069. if shell_name == "bash" and platform.system() == "Darwin":
  4070. return Path.home() / ".bash_profile"
  4071. if shell_name == "bash":
  4072. return Path.home() / ".bashrc"
  4073. return Path.home() / ".profile"
  4074. def ensure_profile_line(profile: Path, line: str, marker: str) -> bool:
  4075. profile.parent.mkdir(parents=True, exist_ok=True)
  4076. existing = profile.read_text(encoding="utf-8") if profile.exists() else ""
  4077. if line in existing:
  4078. return False
  4079. prefix = "" if not existing or existing.endswith("\n") else "\n"
  4080. with profile.open("a", encoding="utf-8") as handle:
  4081. handle.write(f"{prefix}# {marker}\n{line}\n")
  4082. return True
  4083. def ensure_npm(args: argparse.Namespace) -> int:
  4084. before = check_npm_runtime()
  4085. payload: dict[str, object] = {
  4086. "mode": "ensure-npm",
  4087. "platform": before["platform"],
  4088. "before": before,
  4089. "actions": [],
  4090. }
  4091. if before["npm"]["installed"]:
  4092. payload["status"] = "already-installed"
  4093. if args.json:
  4094. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4095. else:
  4096. print("npm is already available.")
  4097. print(f"npm: {before['npm']['path']} ({before['npm']['version']})")
  4098. print(f"node: {before['node']['path']} ({before['node']['version']})")
  4099. return 0
  4100. system = platform.system() or sys.platform
  4101. if system == "Windows":
  4102. payload["status"] = "unsupported-platform"
  4103. payload["advice"] = (
  4104. "Native Windows is not supported by the nvm-sh installer. Use WSL with nvm-sh, "
  4105. "or install a Windows Node version manager such as nvm-windows/nvs, then rerun check."
  4106. )
  4107. if args.json:
  4108. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4109. else:
  4110. print(
  4111. "npm is missing, but native Windows cannot be fully configured by this nvm-sh installer."
  4112. )
  4113. print(payload["advice"])
  4114. return 1
  4115. install_actions = payload["actions"]
  4116. install_actions.append(f"install or update nvm with {NVM_INSTALL_URL}")
  4117. install_actions.append("install latest Node.js LTS with nvm")
  4118. install_actions.append("set nvm default alias to lts/*")
  4119. install_actions.append("switch current shell to Node.js LTS")
  4120. if not args.yes:
  4121. payload["status"] = "needs-confirmation"
  4122. if args.json:
  4123. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4124. else:
  4125. print("npm is missing.")
  4126. print(f"Platform: {system}")
  4127. for action in install_actions:
  4128. print(f"- {action}")
  4129. print("Rerun with --yes after user confirmation.")
  4130. return 2
  4131. installer_tool = (
  4132. "curl" if shutil.which("curl") else "wget" if shutil.which("wget") else None
  4133. )
  4134. if not installer_tool:
  4135. payload["status"] = "failed"
  4136. payload["error"] = (
  4137. "Neither curl nor wget is available to download the nvm installer."
  4138. )
  4139. print(
  4140. json.dumps(payload, indent=2, ensure_ascii=False)
  4141. if args.json
  4142. else payload["error"]
  4143. )
  4144. return 1
  4145. if installer_tool == "curl":
  4146. install_script = f"curl -o- {NVM_INSTALL_URL} | bash"
  4147. else:
  4148. install_script = f"wget -qO- {NVM_INSTALL_URL} | bash"
  4149. install_result = shell_result(install_script, timeout=300)
  4150. if not install_result or install_result.returncode != 0:
  4151. payload["status"] = "failed"
  4152. payload["error"] = (
  4153. (install_result.stderr or install_result.stdout).strip()
  4154. if install_result
  4155. else "Unable to execute shell installer."
  4156. )
  4157. print(
  4158. json.dumps(payload, indent=2, ensure_ascii=False)
  4159. if args.json
  4160. else payload["error"]
  4161. )
  4162. return 1
  4163. node_script = (
  4164. f"{nvm_load_script()}; "
  4165. "nvm install --lts; "
  4166. "nvm alias default 'lts/*'; "
  4167. "nvm use --lts; "
  4168. "node --version; "
  4169. "npm --version"
  4170. )
  4171. node_result = shell_result(node_script, timeout=600)
  4172. if not node_result or node_result.returncode != 0:
  4173. payload["status"] = "failed"
  4174. payload["error"] = (
  4175. (node_result.stderr or node_result.stdout).strip()
  4176. if node_result
  4177. else "Unable to run nvm after installation."
  4178. )
  4179. print(
  4180. json.dumps(payload, indent=2, ensure_ascii=False)
  4181. if args.json
  4182. else payload["error"]
  4183. )
  4184. return 1
  4185. after = check_npm_runtime()
  4186. payload["after"] = after
  4187. payload["status"] = "installed" if after["npm"]["installed"] else "failed"
  4188. if args.json:
  4189. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4190. else:
  4191. print(f"ensure-npm status: {payload['status']}")
  4192. if after["npm"]["installed"]:
  4193. print(f"npm: {after['npm']['path']} ({after['npm']['version']})")
  4194. print(f"node: {after['node']['path']} ({after['node']['version']})")
  4195. else:
  4196. print(
  4197. "npm still is not available in PATH. Restart the shell or source the profile file, then rerun check."
  4198. )
  4199. return 0 if after["npm"]["installed"] else 1
  4200. def install_agent_cli(args: argparse.Namespace) -> int:
  4201. before = check_agent_cli(args.platform)
  4202. payload: dict[str, object] = {
  4203. "mode": "install-agent-cli",
  4204. "platform": before["platform"],
  4205. "label": before["label"],
  4206. "command": before["command"],
  4207. "npmPackage": before["npmPackage"],
  4208. "installCommand": before["installCommand"],
  4209. "verifyCommand": before["verifyCommand"],
  4210. "runtime": before["runtime"],
  4211. "before": before,
  4212. }
  4213. if before["installed"]:
  4214. payload["status"] = "already-installed"
  4215. if args.json:
  4216. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4217. else:
  4218. print(f"{before['label']} CLI is already installed and verified.")
  4219. print(f"{before['command']}: {before['path']} ({before['version']})")
  4220. return 0
  4221. runtime = before["runtime"]
  4222. if not runtime["npm"]["installed"]:
  4223. payload["status"] = "npm-required"
  4224. payload["advice"] = (
  4225. f"{shell_prefix()}Install npm first with `{onboard_command('ensure-npm', '--yes')}` after user confirmation, "
  4226. "then rerun install-agent-cli."
  4227. )
  4228. if args.json:
  4229. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4230. else:
  4231. print(f"{before['label']} CLI is missing and npm is not usable.")
  4232. print(payload["advice"])
  4233. return 2
  4234. if not args.yes:
  4235. payload["status"] = "needs-confirmation"
  4236. payload["actions"] = [
  4237. f"run `{before['installCommand']}`",
  4238. f"verify `{before['verifyCommand']}`",
  4239. ]
  4240. if args.json:
  4241. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4242. else:
  4243. print(f"{before['label']} CLI is missing or failed verification.")
  4244. for action in payload["actions"]:
  4245. print(f"- {action}")
  4246. print("Rerun with --yes after user confirmation.")
  4247. return 2
  4248. npm_package = f"{before['npmPackage']}@latest"
  4249. install_result = run_command(("npm", "install", "-g", npm_package), timeout=900)
  4250. payload["installOutput"] = command_excerpt(install_result)
  4251. if not install_result or install_result.returncode != 0:
  4252. payload["status"] = "failed"
  4253. payload["error"] = (
  4254. command_excerpt(install_result) or "npm global install failed."
  4255. )
  4256. print(
  4257. json.dumps(payload, indent=2, ensure_ascii=False)
  4258. if args.json
  4259. else payload["error"]
  4260. )
  4261. return 1
  4262. after = check_agent_cli(str(before["platform"]))
  4263. payload["after"] = after
  4264. payload["status"] = "installed" if after["installed"] else "verification-failed"
  4265. if args.json:
  4266. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4267. else:
  4268. print(f"install-agent-cli status: {payload['status']}")
  4269. if after["installed"]:
  4270. print(f"{after['command']}: {after['path']} ({after['version']})")
  4271. else:
  4272. print(
  4273. f"npm completed, but `{after['verifyCommand']}` did not pass. "
  4274. "Check the npm global bin PATH and the package runtime prerequisites."
  4275. )
  4276. if after.get("verifyOutput"):
  4277. print(f"First verification output: {after['verifyOutput']}")
  4278. return 0 if after["installed"] else 1
  4279. def install_rtk(args: argparse.Namespace) -> int:
  4280. before = check_cli_tool(CLI_TOOLS[0])
  4281. local_bin = Path.home() / ".local" / "bin"
  4282. profile = expand_path(args.profile) or default_shell_profile()
  4283. payload: dict[str, object] = {
  4284. "mode": "install-rtk",
  4285. "platform": platform.system() or sys.platform,
  4286. "before": before,
  4287. "installUrl": RTK_INSTALL_URL,
  4288. "targetDir": str(local_bin),
  4289. "profile": str(profile),
  4290. }
  4291. if before["installed"]:
  4292. payload["status"] = "already-installed"
  4293. if args.json:
  4294. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4295. else:
  4296. print("rtk is already installed and verified with `rtk gain`.")
  4297. print(f"rtk: {before['path']} ({before['version']})")
  4298. return 0
  4299. if before.get("wrongPackageSuspected") and not args.replace_wrong:
  4300. payload["status"] = "wrong-package-suspected"
  4301. payload["advice"] = (
  4302. "An `rtk` command exists but `rtk gain` failed. Confirm whether to remove or replace it before installing rtk-ai/rtk."
  4303. )
  4304. if args.json:
  4305. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4306. else:
  4307. print(payload["advice"])
  4308. print(
  4309. "Rerun with --replace-wrong after user confirmation if replacement is intended."
  4310. )
  4311. return 2
  4312. if before.get("verificationFailed") and not args.reinstall:
  4313. payload["status"] = "verification-failed"
  4314. payload["advice"] = (
  4315. "`rtk --version` looks like rtk-ai/rtk, but `rtk gain` failed. "
  4316. "Check RTK data directory permissions first, or rerun with --reinstall after user confirmation."
  4317. )
  4318. if args.json:
  4319. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4320. else:
  4321. print(payload["advice"])
  4322. return 2
  4323. system = platform.system() or sys.platform
  4324. if system == "Windows":
  4325. payload["status"] = "manual-required"
  4326. payload["advice"] = (
  4327. "Download the Windows release zip from rtk-ai/rtk, extract rtk.exe into a directory on PATH "
  4328. "such as %USERPROFILE%\\.local\\bin, then verify with `rtk --version` and `rtk gain`."
  4329. )
  4330. if args.json:
  4331. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4332. else:
  4333. print(payload["advice"])
  4334. return 1
  4335. if not args.yes:
  4336. payload["status"] = "needs-confirmation"
  4337. payload["actions"] = [
  4338. f"run {RTK_INSTALL_URL}",
  4339. f"ensure {local_bin} is in PATH via {profile}",
  4340. "verify `rtk --version` and `rtk gain`",
  4341. ]
  4342. if args.json:
  4343. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4344. else:
  4345. print("rtk is missing or not verified.")
  4346. for action in payload["actions"]:
  4347. print(f"- {action}")
  4348. print("Rerun with --yes after user confirmation.")
  4349. return 2
  4350. if (
  4351. before.get("wrongPackageSuspected")
  4352. and args.replace_wrong
  4353. and shutil.which("cargo")
  4354. ):
  4355. run_command(("cargo", "uninstall", "rtk"), timeout=120)
  4356. if not shutil.which("curl"):
  4357. payload["status"] = "failed"
  4358. payload["error"] = "curl is required for the rtk-ai/rtk quick install script."
  4359. print(
  4360. json.dumps(payload, indent=2, ensure_ascii=False)
  4361. if args.json
  4362. else payload["error"]
  4363. )
  4364. return 1
  4365. install_result = shell_result(f"curl -fsSL {RTK_INSTALL_URL} | sh", timeout=300)
  4366. if not install_result or install_result.returncode != 0:
  4367. payload["status"] = "failed"
  4368. payload["error"] = (
  4369. (install_result.stderr or install_result.stdout).strip()
  4370. if install_result
  4371. else "Unable to run rtk installer."
  4372. )
  4373. print(
  4374. json.dumps(payload, indent=2, ensure_ascii=False)
  4375. if args.json
  4376. else payload["error"]
  4377. )
  4378. return 1
  4379. os.environ["PATH"] = f"{local_bin}{os.pathsep}{os.environ.get('PATH', '')}"
  4380. profile_updated = ensure_profile_line(
  4381. profile,
  4382. 'export PATH="$HOME/.local/bin:$PATH"',
  4383. "Added by sbtd-workflow-onboard for rtk",
  4384. )
  4385. after = check_cli_tool(CLI_TOOLS[0])
  4386. payload["after"] = after
  4387. payload["profileUpdated"] = profile_updated
  4388. payload["status"] = "installed" if after["installed"] else "failed"
  4389. if args.json:
  4390. print(json.dumps(payload, indent=2, ensure_ascii=False))
  4391. else:
  4392. print(f"install-rtk status: {payload['status']}")
  4393. if profile_updated:
  4394. print(f"Updated PATH in {profile}")
  4395. if after["installed"]:
  4396. print(f"rtk: {after['path']} ({after['version']})")
  4397. print("Verification passed: rtk gain")
  4398. else:
  4399. print(
  4400. "rtk was installed but did not pass `rtk gain`. Check PATH, release download, and name-collision risk."
  4401. )
  4402. return 0 if after["installed"] else 1
  4403. def is_caveman_family_name(name: str) -> bool:
  4404. """Narrow matcher: entries Onboard may back up or replace."""
  4405. return (
  4406. name == "caveman"
  4407. or name.startswith("caveman-")
  4408. or name == "cavecrew"
  4409. or name.startswith("cavecrew-")
  4410. )
  4411. def is_caveman_family_prefix_name(name: str) -> bool:
  4412. """Broad, detection-only matcher for the fail-closed symlink guard.
  4413. Anything named `caveman*` / `cavecrew*` (for example `caveman.local`)
  4414. blocks maintenance when symlinked, but is never selected for mutation.
  4415. """
  4416. return name.startswith("caveman") or name.startswith("cavecrew")
  4417. def caveman_family_dirs(skills_dir: Path) -> list[Path]:
  4418. if not skills_dir.is_dir():
  4419. return []
  4420. return sorted(
  4421. (
  4422. entry
  4423. for entry in skills_dir.iterdir()
  4424. if (entry.is_dir() or entry.is_symlink() or entry.is_file())
  4425. and is_caveman_family_name(entry.name)
  4426. ),
  4427. key=lambda entry: entry.name,
  4428. )
  4429. def caveman_family_fingerprints(skills_dir: Path) -> dict[str, str | None]:
  4430. fingerprints: dict[str, str | None] = {}
  4431. for entry in caveman_family_dirs(skills_dir):
  4432. try:
  4433. validate_external_skill_source(entry.name, entry)
  4434. except RuntimeError:
  4435. fingerprints[entry.name] = None
  4436. else:
  4437. fingerprints[entry.name] = external_tree_sha256(entry)
  4438. return fingerprints
  4439. def copy_caveman_entry(source: Path, destination: Path) -> None:
  4440. if source.is_symlink():
  4441. destination.symlink_to(source.readlink())
  4442. elif source.is_dir():
  4443. shutil.copytree(source, destination, symlinks=True)
  4444. else:
  4445. shutil.copy2(source, destination)
  4446. def remove_caveman_entry(target: Path) -> None:
  4447. if target.is_symlink() or not target.is_dir():
  4448. target.unlink()
  4449. else:
  4450. shutil.rmtree(target)
  4451. def caveman_payload_symlink_error(global_skills_dir: Path) -> str | None:
  4452. """Return a fail-closed reason when any caveman family payload is a symlink.
  4453. Covers the top-level `caveman` directory, its core `caveman/SKILL.md`
  4454. (including dangling links), and every sibling `caveman*` / `cavecrew*`
  4455. entry. Symlinked payloads are reported and never replaced.
  4456. """
  4457. skill_dir = global_skills_dir / "caveman"
  4458. if skill_dir.is_symlink():
  4459. return "Refusing to replace a symlinked caveman skill directory"
  4460. if (skill_dir / "SKILL.md").is_symlink():
  4461. return "Refusing to replace a symlinked caveman/SKILL.md core payload"
  4462. if caveman_family_has_sibling_symlink(global_skills_dir):
  4463. return "Refusing to touch a caveman family that contains a symlinked sibling entry"
  4464. return None
  4465. def classify_caveman_state(global_skills_dir: Path) -> str:
  4466. skill_dir = global_skills_dir / "caveman"
  4467. skill_md = skill_dir / "SKILL.md"
  4468. if caveman_payload_symlink_error(global_skills_dir) is not None:
  4469. return "abnormal"
  4470. try:
  4471. fingerprints = caveman_family_fingerprints(global_skills_dir)
  4472. except (OSError, RuntimeError):
  4473. return "unknown-drift"
  4474. companions = {
  4475. name: digest for name, digest in fingerprints.items() if name != "caveman"
  4476. }
  4477. if companions and not any(
  4478. companions
  4479. == {name: digest for name, digest in family.items() if name != "caveman"}
  4480. for family in CAVEMAN_KNOWN_FAMILY_SHA256.values()
  4481. ):
  4482. return "unknown-drift"
  4483. if not skill_dir.exists():
  4484. # Partial family (surviving companions without the core) is drift:
  4485. # only a fully absent family is an ordinary missing install.
  4486. return "missing" if not fingerprints else "unknown-drift"
  4487. if not skill_md.is_file():
  4488. return "abnormal"
  4489. try:
  4490. core_bytes = skill_md.read_bytes()
  4491. except OSError:
  4492. return "abnormal"
  4493. if skill_frontmatter_name_from_bytes(core_bytes) != "caveman":
  4494. return "abnormal"
  4495. digest = hashlib.sha256(core_bytes).hexdigest()
  4496. for ref, core_digest in CAVEMAN_KNOWN_CORE_SKILL_SHA256.items():
  4497. if digest == core_digest and fingerprints == CAVEMAN_KNOWN_FAMILY_SHA256.get(
  4498. ref
  4499. ):
  4500. return "current" if ref == CAVEMAN_PINNED_REF else "outdated"
  4501. return "unknown-drift"
  4502. def caveman_maintenance_plan(global_skills_dir: Path) -> dict[str, object]:
  4503. state = classify_caveman_state(global_skills_dir)
  4504. symlink_error = caveman_payload_symlink_error(global_skills_dir)
  4505. blocked_reason = symlink_error or caveman_family_nested_symlink_reason(
  4506. global_skills_dir
  4507. )
  4508. if state == "abnormal" and blocked_reason is not None:
  4509. action = "blocked"
  4510. else:
  4511. action = {
  4512. "outdated": "upgrade",
  4513. "abnormal": "repair",
  4514. }.get(state, "none")
  4515. plan: dict[str, object] = {
  4516. "state": state,
  4517. "plannedAction": action,
  4518. "pinnedRef": CAVEMAN_PINNED_REF,
  4519. "pinnedRevision": CAVEMAN_PINNED_REVISION,
  4520. "scope": "workflow-skill-payload-only",
  4521. }
  4522. if blocked_reason is not None and action == "blocked":
  4523. plan["blockedReason"] = blocked_reason
  4524. return plan
  4525. def restore_caveman_family(global_skills_dir: Path, backup_dir: Path | None) -> str | None:
  4526. try:
  4527. for target in caveman_family_dirs(global_skills_dir):
  4528. remove_caveman_entry(target)
  4529. if backup_dir:
  4530. for source in backup_dir.iterdir():
  4531. copy_caveman_entry(source, global_skills_dir / source.name)
  4532. except (OSError, shutil.Error) as exc:
  4533. return str(exc)
  4534. return None
  4535. def caveman_family_has_sibling_symlink(global_skills_dir: Path) -> bool:
  4536. if not global_skills_dir.is_dir():
  4537. return False
  4538. try:
  4539. return any(
  4540. entry.is_symlink()
  4541. for entry in global_skills_dir.iterdir()
  4542. if entry.name != "caveman" and is_caveman_family_prefix_name(entry.name)
  4543. )
  4544. except OSError:
  4545. # Cannot prove there is no symlink -> fail closed.
  4546. return True
  4547. def caveman_family_nested_symlink_reason(global_skills_dir: Path) -> str | None:
  4548. """Return a fail-closed reason when a family payload nests a symlink.
  4549. Recursively covers every path inside the broad ``caveman*`` / ``cavecrew*``
  4550. prefix entries; a valid core with a nested link already lands in
  4551. ``unknown-drift`` through the fingerprint scan, so this guard exists to
  4552. stop an *abnormal* core containing a nested link from being repaired.
  4553. Top-level links themselves are reported by
  4554. ``caveman_payload_symlink_error`` and skipped here.
  4555. """
  4556. if not global_skills_dir.is_dir():
  4557. return None
  4558. try:
  4559. entries = sorted(global_skills_dir.iterdir())
  4560. except OSError:
  4561. # Cannot prove there is no nested symlink -> fail closed.
  4562. return "Refusing to repair a caveman payload whose entries cannot be read"
  4563. for entry in entries:
  4564. if not is_caveman_family_prefix_name(entry.name):
  4565. continue
  4566. if entry.is_symlink() or not entry.is_dir():
  4567. continue
  4568. walk_errors: list[OSError] = []
  4569. try:
  4570. has_nested = any(
  4571. os.path.islink(os.path.join(dirpath, name))
  4572. for dirpath, dirnames, filenames in os.walk(
  4573. entry, followlinks=False, onerror=walk_errors.append
  4574. )
  4575. for name in (*dirnames, *filenames)
  4576. )
  4577. except OSError:
  4578. has_nested = True # Cannot prove clean -> fail closed.
  4579. if walk_errors:
  4580. # Unreadable descendants can hide a symlink -> fail closed.
  4581. has_nested = True
  4582. if has_nested:
  4583. return (
  4584. "Refusing to repair a caveman payload that contains a nested "
  4585. f"symlink under {entry.name}"
  4586. )
  4587. return None
  4588. def install_caveman_payload(global_skills_dir: Path) -> dict[str, object]:
  4589. result = caveman_maintenance_plan(global_skills_dir)
  4590. result["status"] = "pending"
  4591. result["sourceRepo"] = CAVEMAN_SOURCE_REPO
  4592. result["familyScope"] = "caveman, caveman-*, cavecrew, cavecrew-* only"
  4593. symlink_error = caveman_payload_symlink_error(global_skills_dir)
  4594. if symlink_error is not None:
  4595. result["status"] = "failed"
  4596. result["error"] = symlink_error
  4597. return result
  4598. if result["state"] == "unknown-drift":
  4599. result["status"] = "attention-required"
  4600. result["advice"] = CAVEMAN_DRIFT_ADVICE
  4601. return result
  4602. if result["plannedAction"] == "blocked":
  4603. result["status"] = "failed"
  4604. result["error"] = str(
  4605. result.get(
  4606. "blockedReason",
  4607. "Refusing to replace a caveman payload containing a symlink",
  4608. )
  4609. )
  4610. return result
  4611. try:
  4612. return _install_caveman_payload_staged(global_skills_dir, result)
  4613. except (OSError, shutil.Error) as exc:
  4614. # Staging-directory creation/cleanup, staged reads and the source scan
  4615. # sit outside the transactional backup/replace block; keep the
  4616. # structured JSON contract instead of surfacing a traceback.
  4617. result["status"] = "failed"
  4618. result["error"] = f"Caveman staging failed: {exc}"
  4619. return result
  4620. def _install_caveman_payload_staged(
  4621. global_skills_dir: Path, result: dict[str, object]
  4622. ) -> dict[str, object]:
  4623. with tempfile.TemporaryDirectory(prefix="sbtd-caveman-stage-") as temp_dir:
  4624. stage_root = Path(temp_dir)
  4625. repository = stage_root / "repository"
  4626. cloned, clone_error = clone_repo_at_revision(
  4627. CAVEMAN_SOURCE_REPO, CAVEMAN_PINNED_REVISION, repository
  4628. )
  4629. if not cloned:
  4630. result["status"] = "blocked"
  4631. result["error"] = clone_error
  4632. return result
  4633. source_skills_dir = repository / "skills"
  4634. source_core = source_skills_dir / "caveman" / "SKILL.md"
  4635. if (
  4636. not source_core.is_file()
  4637. or read_skill_frontmatter_name(source_core) != "caveman"
  4638. ):
  4639. result["status"] = "blocked"
  4640. result["error"] = "Pinned caveman source has no valid caveman/SKILL.md"
  4641. return result
  4642. if (
  4643. hashlib.sha256(source_core.read_bytes()).hexdigest()
  4644. != CAVEMAN_CORE_SKILL_SHA256
  4645. ):
  4646. result["status"] = "blocked"
  4647. result["error"] = (
  4648. "Pinned caveman source does not match the reviewed core hash"
  4649. )
  4650. return result
  4651. source_family = caveman_family_dirs(source_skills_dir)
  4652. if (
  4653. caveman_family_fingerprints(source_skills_dir)
  4654. != CAVEMAN_KNOWN_FAMILY_SHA256[CAVEMAN_PINNED_REF]
  4655. ):
  4656. result["status"] = "blocked"
  4657. result["error"] = (
  4658. "Pinned caveman family does not match the reviewed payload"
  4659. )
  4660. return result
  4661. try:
  4662. global_skills_dir.parent.mkdir(parents=True, exist_ok=True)
  4663. global_skills_dir.mkdir(parents=True, exist_ok=True)
  4664. except OSError as exc:
  4665. result["status"] = "failed"
  4666. result["error"] = f"Unable to create global skills directory: {exc}"
  4667. return result
  4668. target_family = caveman_family_dirs(global_skills_dir)
  4669. symlink_error = caveman_payload_symlink_error(global_skills_dir)
  4670. if symlink_error is not None or any(
  4671. target.is_symlink() for target in target_family
  4672. ):
  4673. result["status"] = "failed"
  4674. result["error"] = (
  4675. symlink_error
  4676. or "Refusing to replace a symlinked caveman skill directory"
  4677. )
  4678. return result
  4679. latest_plan = caveman_maintenance_plan(global_skills_dir)
  4680. if latest_plan["state"] == "unknown-drift":
  4681. result.update(latest_plan)
  4682. result["status"] = "attention-required"
  4683. result["advice"] = CAVEMAN_DRIFT_ADVICE
  4684. return result
  4685. if latest_plan["plannedAction"] == "blocked":
  4686. result.update(latest_plan)
  4687. result["status"] = "failed"
  4688. result["error"] = str(
  4689. latest_plan.get(
  4690. "blockedReason",
  4691. "Refusing to replace a caveman payload containing a symlink",
  4692. )
  4693. )
  4694. return result
  4695. # Back up whenever a family payload exists at mutation time. Anything
  4696. # computed before the clone cannot see a family that appeared during
  4697. # staging, so the recomputed `target_family` is the only safe
  4698. # decision point.
  4699. backup_dir: Path | None = None
  4700. if target_family:
  4701. try:
  4702. timestamp = dt.datetime.now().strftime("%Y%m%d%H%M%S")
  4703. backup_dir = Path(
  4704. tempfile.mkdtemp(
  4705. prefix=f"{global_skills_dir.name}.caveman.bak-{timestamp}-",
  4706. dir=global_skills_dir.parent,
  4707. )
  4708. )
  4709. for target in target_family:
  4710. copy_caveman_entry(target, backup_dir / target.name)
  4711. except (OSError, shutil.Error) as exc:
  4712. result["status"] = "failed"
  4713. result["error"] = (
  4714. f"Unable to back up caveman workflow skill payload: {exc}"
  4715. )
  4716. if backup_dir:
  4717. result["backup"] = str(backup_dir)
  4718. return result
  4719. mutation_started = False
  4720. try:
  4721. mutation_started = True
  4722. for target in target_family:
  4723. remove_caveman_entry(target)
  4724. for source in source_family:
  4725. copy_caveman_entry(source, global_skills_dir / source.name)
  4726. except (OSError, shutil.Error) as exc:
  4727. restore_error = (
  4728. restore_caveman_family(global_skills_dir, backup_dir)
  4729. if mutation_started
  4730. else None
  4731. )
  4732. result["status"] = "failed"
  4733. result["error"] = f"Unable to sync caveman workflow skill payload: {exc}"
  4734. if restore_error:
  4735. result["restoreError"] = restore_error
  4736. if backup_dir:
  4737. result["backup"] = str(backup_dir)
  4738. return result
  4739. after_state = classify_caveman_state(global_skills_dir)
  4740. if after_state != "current":
  4741. restore_error = (
  4742. restore_caveman_family(global_skills_dir, backup_dir)
  4743. if mutation_started
  4744. else None
  4745. )
  4746. result["status"] = "failed"
  4747. result["error"] = "Caveman workflow skill payload did not verify after sync"
  4748. result["afterState"] = after_state
  4749. if restore_error:
  4750. result["restoreError"] = restore_error
  4751. if backup_dir:
  4752. result["backup"] = str(backup_dir)
  4753. return result
  4754. result["status"] = "success"
  4755. result["afterState"] = after_state
  4756. result["familySkills"] = [source.name for source in source_family]
  4757. if backup_dir:
  4758. result["backup"] = str(backup_dir)
  4759. return result
  4760. def maintain_caveman_payload(global_skills_dir: Path) -> dict[str, object]:
  4761. plan = caveman_maintenance_plan(global_skills_dir)
  4762. if plan["state"] == "unknown-drift":
  4763. return {
  4764. **plan,
  4765. "status": "attention-required",
  4766. "advice": CAVEMAN_DRIFT_ADVICE,
  4767. }
  4768. if plan["plannedAction"] == "blocked":
  4769. return {
  4770. **plan,
  4771. "status": "failed",
  4772. "error": plan.get(
  4773. "blockedReason", "Refusing to replace a symlinked caveman payload"
  4774. ),
  4775. }
  4776. if plan["plannedAction"] == "none":
  4777. return {**plan, "status": "skipped"}
  4778. return install_caveman_payload(global_skills_dir)
  4779. def print_caveman_maintenance_details(maintenance: dict[str, object]) -> None:
  4780. for label, value in (
  4781. ("reason", maintenance.get("error") or maintenance.get("blockedReason")),
  4782. ("backup", maintenance.get("backup")),
  4783. ("restore error", maintenance.get("restoreError")),
  4784. ("advice", maintenance.get("advice")),
  4785. ):
  4786. if value:
  4787. print(f"- {label}: {value}")
  4788. def install_caveman(args: argparse.Namespace) -> int:
  4789. try:
  4790. global_skills_dir = resolve_global_skills_dir(args.global_skills_dir)[0]
  4791. except (OSError, RuntimeError) as exc:
  4792. payload = {
  4793. "mode": "install-caveman",
  4794. "status": "failed",
  4795. "error": f"Unable to resolve the global skills directory: {exc}",
  4796. }
  4797. print(
  4798. json.dumps(payload, indent=2, ensure_ascii=False)
  4799. if args.json
  4800. else payload["error"]
  4801. )
  4802. return 1
  4803. before = check_skill("caveman", "interaction", global_skills_dir, None)
  4804. maintenance = caveman_maintenance_plan(global_skills_dir)
  4805. payload: dict[str, object] = {
  4806. "mode": "install-caveman",
  4807. "agent": args.agent,
  4808. "platform": platform.system() or sys.platform,
  4809. "before": before,
  4810. "maintenance": maintenance,
  4811. "globalSkillsDir": str(global_skills_dir),
  4812. "scope": "workflow-skill-payload-only",
  4813. }
  4814. if maintenance["state"] == "current":
  4815. payload["status"] = "already-installed"
  4816. print(
  4817. json.dumps(payload, indent=2, ensure_ascii=False)
  4818. if args.json
  4819. else "caveman workflow skill payload is already current."
  4820. )
  4821. return 0
  4822. if not args.yes:
  4823. payload["status"] = "needs-confirmation"
  4824. payload["actions"] = [
  4825. f"stage pinned caveman {CAVEMAN_PINNED_REF} skill payload",
  4826. f"sync caveman, caveman-*, cavecrew, cavecrew-* into {global_skills_dir}",
  4827. "preserve plugins, hooks, statusline, and extensions unchanged",
  4828. ]
  4829. print(
  4830. json.dumps(payload, indent=2, ensure_ascii=False)
  4831. if args.json
  4832. else "caveman workflow skill payload needs confirmation; rerun with --yes."
  4833. )
  4834. if not args.json:
  4835. print_caveman_maintenance_details(maintenance)
  4836. return 2
  4837. if maintenance["state"] == "unknown-drift":
  4838. payload["status"] = "attention-required"
  4839. payload["advice"] = CAVEMAN_DRIFT_ADVICE
  4840. print(
  4841. json.dumps(payload, indent=2, ensure_ascii=False)
  4842. if args.json
  4843. else payload["advice"]
  4844. )
  4845. return 2
  4846. try:
  4847. result = install_caveman_payload(global_skills_dir)
  4848. except Exception as exc: # noqa: BLE001 - preserve the install JSON/text failure contract.
  4849. result = {
  4850. **maintenance,
  4851. "status": "failed",
  4852. "error": str(exc),
  4853. }
  4854. payload["maintenance"] = result
  4855. after = check_skill("caveman", "interaction", global_skills_dir, None)
  4856. payload["after"] = after
  4857. payload["status"] = (
  4858. "installed"
  4859. if result["status"] == "success" and after["installed"]
  4860. else result["status"]
  4861. )
  4862. print(
  4863. json.dumps(payload, indent=2, ensure_ascii=False)
  4864. if args.json
  4865. else f"install-caveman status: {payload['status']}"
  4866. )
  4867. if not args.json:
  4868. print_caveman_maintenance_details(result)
  4869. return 0 if payload["status"] == "installed" else 1
  4870. def command_excerpt(
  4871. completed: subprocess.CompletedProcess[str] | None, limit: int = 20
  4872. ) -> str | None:
  4873. if completed is None:
  4874. return None
  4875. output = "\n".join(part for part in (completed.stdout, completed.stderr) if part)
  4876. lines = output.strip().splitlines()
  4877. if not lines:
  4878. return None
  4879. return "\n".join(lines[-limit:])
  4880. def github_json(url: str, timeout: int = 30) -> dict[str, object]:
  4881. request = urllib.request.Request(
  4882. url, headers={"User-Agent": "sbtd-workflow-onboard"}
  4883. )
  4884. with urllib.request.urlopen(request, timeout=timeout) as response:
  4885. return json.loads(response.read().decode("utf-8"))
  4886. def download_url(url: str, destination: Path, timeout: int = 900) -> None:
  4887. request = urllib.request.Request(
  4888. url, headers={"User-Agent": "sbtd-workflow-onboard"}
  4889. )
  4890. with (
  4891. urllib.request.urlopen(request, timeout=timeout) as response,
  4892. destination.open("wb") as handle,
  4893. ):
  4894. shutil.copyfileobj(response, handle)
  4895. def temurin_platform_ids() -> tuple[str | None, str | None, str | None]:
  4896. system = platform.system() or sys.platform
  4897. machine = platform.machine().lower()
  4898. if system == "Darwin":
  4899. os_id = "mac"
  4900. elif system == "Linux":
  4901. os_id = "linux"
  4902. else:
  4903. return (
  4904. None,
  4905. None,
  4906. f"Temurin tarball auto-install is only supported on macOS and Linux; current platform is {system}.",
  4907. )
  4908. if machine in {"x86_64", "amd64"}:
  4909. arch_id = "x64"
  4910. elif machine in {"arm64", "aarch64"}:
  4911. arch_id = "aarch64"
  4912. else:
  4913. return (
  4914. None,
  4915. None,
  4916. f"Unsupported CPU architecture for Temurin auto-install: {machine}.",
  4917. )
  4918. return os_id, arch_id, None
  4919. def select_temurin_asset(major: int) -> dict[str, object]:
  4920. os_id, arch_id, reason = temurin_platform_ids()
  4921. if reason:
  4922. raise RuntimeError(reason)
  4923. release = github_json(TEMURIN_RELEASES_API_TEMPLATE.format(major=major))
  4924. assets = release.get("assets")
  4925. if not isinstance(assets, list):
  4926. raise RuntimeError("GitHub release payload did not include assets.")
  4927. prefix = f"OpenJDK{major}U-jdk_{arch_id}_{os_id}_hotspot_"
  4928. for asset in assets:
  4929. if not isinstance(asset, dict):
  4930. continue
  4931. name = str(asset.get("name") or "")
  4932. url = str(asset.get("browser_download_url") or "")
  4933. if (
  4934. name.startswith(prefix)
  4935. and name.endswith(".tar.gz")
  4936. and "debugimage" not in name
  4937. and "testimage" not in name
  4938. and "static-libs" not in name
  4939. and url
  4940. ):
  4941. return {
  4942. "release": release.get("tag_name"),
  4943. "name": name,
  4944. "url": url,
  4945. }
  4946. raise RuntimeError(
  4947. f"No matching Temurin {major} JDK tar.gz asset found for {arch_id}/{os_id}."
  4948. )
  4949. def safe_extract_tar(archive: Path, destination: Path) -> None:
  4950. destination.mkdir(parents=True, exist_ok=True)
  4951. destination_root = destination.resolve()
  4952. with tarfile.open(archive, "r:gz") as tar:
  4953. for member in tar.getmembers():
  4954. target = (destination / member.name).resolve()
  4955. if target != destination_root and destination_root not in target.parents:
  4956. raise RuntimeError(f"Unsafe path in archive: {member.name}")
  4957. tar.extractall(destination)
  4958. def find_java_home(root: Path) -> Path:
  4959. names = (
  4960. ("bin/java.exe", "bin/java")
  4961. if platform.system() == "Windows"
  4962. else ("bin/java",)
  4963. )
  4964. candidates = sorted(
  4965. candidate for name in names for candidate in root.rglob(name)
  4966. )
  4967. for java_bin in candidates:
  4968. if java_bin.is_file():
  4969. return java_bin.parent.parent
  4970. expected = "bin/java.exe or bin/java" if platform.system() == "Windows" else "bin/java"
  4971. raise RuntimeError(f"Extracted JDK archive did not contain {expected}.")
  4972. def activate_java_home(java_home: Path) -> None:
  4973. os.environ["JAVA_HOME"] = str(java_home)
  4974. os.environ["PATH"] = f"{java_home / 'bin'}{os.pathsep}{os.environ.get('PATH', '')}"
  4975. def install_java(args: argparse.Namespace) -> int:
  4976. major = int(args.major)
  4977. if major < JAVA_MIN_MAJOR:
  4978. raise SystemExit(
  4979. f"Refusing to install Java {major}. Maestro requires Java {JAVA_MIN_MAJOR}+."
  4980. )
  4981. before = check_java_for_maestro()
  4982. install_root = expand_path(args.install_root) or (
  4983. Path.home() / ".local" / "share" / "sbtd-workflow" / "jdks"
  4984. )
  4985. target_home = install_root / f"temurin-{major}"
  4986. profile = expand_path(args.profile) or default_shell_profile()
  4987. payload: dict[str, object] = {
  4988. "mode": "install-java",
  4989. "platform": platform.system() or sys.platform,
  4990. "before": before,
  4991. "major": major,
  4992. "minimumMajor": JAVA_MIN_MAJOR,
  4993. "releaseSource": TEMURIN21_RELEASES_URL,
  4994. "targetJavaHome": str(target_home),
  4995. "profile": str(profile),
  4996. }
  4997. if before["installed"] and not args.force:
  4998. payload["status"] = "already-installed"
  4999. payload["advice"] = (
  5000. "An installed JDK already satisfies Maestro's Java 17+ prerequisite. Use --force only after confirming a version replacement is intended."
  5001. )
  5002. if args.json:
  5003. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5004. else:
  5005. print("An installed JDK already satisfies Maestro's Java 17+ prerequisite.")
  5006. print(f"java: {before['path']} ({before['version']})")
  5007. if before.get("javaHome"):
  5008. print(f"JAVA_HOME: {before['javaHome']}")
  5009. print(payload["advice"])
  5010. return 0
  5011. os_id, arch_id, platform_reason = temurin_platform_ids()
  5012. if platform_reason:
  5013. payload["status"] = "manual-required"
  5014. payload["reason"] = platform_reason
  5015. if args.json:
  5016. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5017. else:
  5018. print(platform_reason)
  5019. print(
  5020. f"Download a Java {major}+ JDK manually from {TEMURIN21_RELEASES_URL}."
  5021. )
  5022. return 1
  5023. payload["targetPlatform"] = {"os": os_id, "arch": arch_id}
  5024. payload["actions"] = [
  5025. f"fetch the latest Temurin {major} JDK release asset from {TEMURIN21_RELEASES_URL}",
  5026. f"extract it into {target_home}",
  5027. f"write JAVA_HOME and PATH exports into {profile}",
  5028. "verify `java --version` reports Java 17 or higher",
  5029. ]
  5030. if not args.yes:
  5031. payload["status"] = "needs-confirmation"
  5032. if args.json:
  5033. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5034. else:
  5035. print(
  5036. f"Java {JAVA_MIN_MAJOR}+ is missing or a Java {major} install was explicitly requested."
  5037. )
  5038. for action in payload["actions"]:
  5039. print(f"- {action}")
  5040. print("Rerun with --yes after user confirmation.")
  5041. return 2
  5042. try:
  5043. asset = select_temurin_asset(major)
  5044. payload["selectedAsset"] = asset
  5045. with tempfile.TemporaryDirectory(prefix="sbtd-temurin-") as temp_dir:
  5046. archive = Path(temp_dir) / str(asset["name"])
  5047. extracted = Path(temp_dir) / "extracted"
  5048. download_url(str(asset["url"]), archive)
  5049. safe_extract_tar(archive, extracted)
  5050. extracted_java_home = find_java_home(extracted)
  5051. target_home.parent.mkdir(parents=True, exist_ok=True)
  5052. if target_home.exists():
  5053. backup = backup_path(target_home)
  5054. shutil.move(str(target_home), str(backup))
  5055. payload["backup"] = str(backup)
  5056. shutil.move(str(extracted_java_home), str(target_home))
  5057. except (OSError, RuntimeError, urllib.error.URLError, json.JSONDecodeError) as exc:
  5058. payload["status"] = "failed"
  5059. payload["error"] = str(exc)
  5060. print(
  5061. json.dumps(payload, indent=2, ensure_ascii=False)
  5062. if args.json
  5063. else payload["error"]
  5064. )
  5065. return 1
  5066. activate_java_home(target_home)
  5067. profile_updated = ensure_profile_line(
  5068. profile,
  5069. f'export JAVA_HOME="{target_home}"; export PATH="$JAVA_HOME/bin:$PATH"',
  5070. f"Added by sbtd-workflow-onboard for Temurin {major}",
  5071. )
  5072. after = check_java_for_maestro()
  5073. payload["after"] = after
  5074. payload["profileUpdated"] = profile_updated
  5075. payload["status"] = "installed" if after["installed"] else "failed"
  5076. if args.json:
  5077. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5078. else:
  5079. print(f"install-java status: {payload['status']}")
  5080. if profile_updated:
  5081. print(f"Updated JAVA_HOME/PATH in {profile}")
  5082. if after["installed"]:
  5083. print(f"java: {after['path']} ({after['version']})")
  5084. else:
  5085. print(
  5086. "Java was installed but did not pass the Java 17+ verification. Check JAVA_HOME and PATH."
  5087. )
  5088. return 0 if after["installed"] else 1
  5089. def install_maestro(args: argparse.Namespace) -> int:
  5090. java_before = check_java_for_maestro()
  5091. before = check_maestro_cli(java_before)
  5092. profile = expand_path(args.profile) or default_shell_profile()
  5093. maestro_bin = Path.home() / ".maestro" / "bin"
  5094. payload: dict[str, object] = {
  5095. "mode": "install-maestro",
  5096. "platform": platform.system() or sys.platform,
  5097. "before": before,
  5098. "java": java_before,
  5099. "installUrl": MAESTRO_INSTALL_URL,
  5100. "profile": str(profile),
  5101. "maestroMcpConfig": maestro_mcp_server_config(java_before, before),
  5102. "maestroMcpConfigExamples": maestro_mcp_config_examples(java_before, before),
  5103. }
  5104. if before["installed"] and not args.reinstall:
  5105. payload["status"] = "already-installed"
  5106. if args.json:
  5107. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5108. else:
  5109. print("Maestro CLI is already installed and verified.")
  5110. print(f"maestro: {before['path']} ({before['version']})")
  5111. print("Maestro MCP configuration:")
  5112. print_config_examples(
  5113. {"configExamples": payload["maestroMcpConfigExamples"]}
  5114. )
  5115. return 0
  5116. if not java_before["installed"]:
  5117. payload["status"] = "java-required"
  5118. payload["advice"] = (
  5119. f"Install Java {JAVA_MIN_MAJOR}+ first. Default command: "
  5120. f"{shell_prefix()}`{onboard_command('install-java', '--major', '21', '--yes')}` after user confirmation."
  5121. )
  5122. if args.json:
  5123. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5124. else:
  5125. print(f"Maestro CLI requires Java {JAVA_MIN_MAJOR}+ before installation.")
  5126. print(payload["advice"])
  5127. return 2
  5128. system = platform.system() or sys.platform
  5129. if system == "Windows":
  5130. payload["status"] = "manual-required"
  5131. payload["advice"] = (
  5132. "Use WSL with the official install script, or follow Maestro's regular Windows installation guide manually."
  5133. )
  5134. if args.json:
  5135. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5136. else:
  5137. print(payload["advice"])
  5138. return 1
  5139. if before.get("verificationFailed") and not args.reinstall:
  5140. payload["status"] = "verification-failed"
  5141. payload["advice"] = (
  5142. "A maestro command exists but failed verification. Rerun with --reinstall only after confirming replacement is intended."
  5143. )
  5144. if args.json:
  5145. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5146. else:
  5147. print(payload["advice"])
  5148. return 2
  5149. payload["actions"] = [
  5150. f'run the official Maestro installer: curl -fsSL "{MAESTRO_INSTALL_URL}" | bash',
  5151. f"ensure {maestro_bin} is in PATH via {profile}",
  5152. "verify `maestro --version` and `maestro test --help`",
  5153. ]
  5154. if not args.yes:
  5155. payload["status"] = "needs-confirmation"
  5156. if args.json:
  5157. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5158. else:
  5159. print("Maestro CLI is missing or not verified.")
  5160. for action in payload["actions"]:
  5161. print(f"- {action}")
  5162. print("Maestro MCP configuration after CLI installation:")
  5163. print_config_examples(
  5164. {"configExamples": payload["maestroMcpConfigExamples"]}
  5165. )
  5166. print("Rerun with --yes after user confirmation.")
  5167. return 2
  5168. if not shutil.which("curl"):
  5169. payload["status"] = "failed"
  5170. payload["error"] = "curl is required for the official Maestro install script."
  5171. print(
  5172. json.dumps(payload, indent=2, ensure_ascii=False)
  5173. if args.json
  5174. else payload["error"]
  5175. )
  5176. return 1
  5177. install_result = shell_result(
  5178. f'curl -fsSL "{MAESTRO_INSTALL_URL}" | bash', timeout=600
  5179. )
  5180. if not install_result or install_result.returncode != 0:
  5181. payload["status"] = "failed"
  5182. payload["error"] = (
  5183. command_excerpt(install_result) or "Unable to run the Maestro installer."
  5184. )
  5185. print(
  5186. json.dumps(payload, indent=2, ensure_ascii=False)
  5187. if args.json
  5188. else payload["error"]
  5189. )
  5190. return 1
  5191. os.environ["PATH"] = f"{maestro_bin}{os.pathsep}{os.environ.get('PATH', '')}"
  5192. profile_updated = ensure_profile_line(
  5193. profile,
  5194. 'export PATH="$HOME/.maestro/bin:$PATH"',
  5195. "Added by sbtd-workflow-onboard for Maestro CLI",
  5196. )
  5197. java_after = check_java_for_maestro()
  5198. after = check_maestro_cli(java_after)
  5199. payload["after"] = after
  5200. payload["maestroMcpConfig"] = maestro_mcp_server_config(java_after, after)
  5201. payload["maestroMcpConfigExamples"] = maestro_mcp_config_examples(java_after, after)
  5202. payload["profileUpdated"] = profile_updated
  5203. payload["status"] = "installed" if after["installed"] else "failed"
  5204. if args.json:
  5205. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5206. else:
  5207. print(f"install-maestro status: {payload['status']}")
  5208. if profile_updated:
  5209. print(f"Updated PATH in {profile}")
  5210. if after["installed"]:
  5211. print(f"maestro: {after['path']} ({after['version']})")
  5212. print("Maestro MCP configuration:")
  5213. print_config_examples(
  5214. {"configExamples": payload["maestroMcpConfigExamples"]}
  5215. )
  5216. else:
  5217. print(
  5218. "Maestro installer completed but `maestro --version` did not pass. Check PATH, Java, and installer output."
  5219. )
  5220. return 0 if after["installed"] else 1
  5221. def run_project_command(
  5222. command: tuple[str, ...],
  5223. cwd: Path,
  5224. timeout: int = 900,
  5225. stdin_text: str | None = None,
  5226. env: dict[str, str] | None = None,
  5227. ) -> subprocess.CompletedProcess[str] | None:
  5228. try:
  5229. return subprocess.run(
  5230. subprocess_command(command),
  5231. cwd=str(cwd),
  5232. check=False,
  5233. capture_output=True,
  5234. text=True,
  5235. errors="replace",
  5236. timeout=timeout,
  5237. input=stdin_text,
  5238. env=env,
  5239. )
  5240. except (OSError, subprocess.TimeoutExpired):
  5241. return None
  5242. def command_display(command: tuple[str, ...]) -> str:
  5243. return shlex.join(command)
  5244. def aggregate_project_status(projects: list[dict[str, object]]) -> str:
  5245. statuses = {str(item.get("status")) for item in projects}
  5246. for status in ("failed", "blocked", "needs-user", "bootstrap-required"):
  5247. if status in statuses:
  5248. return status
  5249. return "success" if projects else "skipped"
  5250. def project_status_exit_code(status: object) -> int:
  5251. if status in {"blocked", "needs-user"}:
  5252. return 2
  5253. if status == "failed":
  5254. return 5
  5255. if status == "bootstrap-required":
  5256. return 6
  5257. return 0
  5258. def project_scaffold_conflict(project_root: Path, skip_agents: bool) -> str | None:
  5259. """Reject unsafe destinations and newly hiding existing reserved data."""
  5260. names = (".gitignore",) if skip_agents else (".gitignore", "AGENTS.md")
  5261. try:
  5262. for name in names:
  5263. target = project_root / name
  5264. try:
  5265. metadata = target.lstat()
  5266. except FileNotFoundError:
  5267. continue
  5268. if not stat.S_ISREG(metadata.st_mode):
  5269. return f"{name} is not a regular installation target."
  5270. if name == ".gitignore" and metadata.st_nlink > 1:
  5271. return ".gitignore has multiple hard links; appending would modify another file."
  5272. target = project_root / ".gitignore"
  5273. current = target.read_text(encoding="utf-8") if target.exists() else ""
  5274. missing = set(
  5275. missing_file_lines(
  5276. PROJECT_GITIGNORE_TEMPLATE.read_text(encoding="utf-8"), current
  5277. )
  5278. )
  5279. existing: list[str] = []
  5280. for relative in (".sbtd", "docs/handoffs", "graft", ".graft"):
  5281. if f"/{relative}" not in missing:
  5282. continue
  5283. if "/" in relative:
  5284. parent = project_root / "docs"
  5285. if parent.is_symlink():
  5286. return "docs is a symlink; reserved handoff ownership is not established."
  5287. path = project_root / relative
  5288. try:
  5289. path.lstat()
  5290. except FileNotFoundError:
  5291. continue
  5292. existing.append(relative)
  5293. if not existing:
  5294. return None
  5295. verdicts = gitignore_verdicts(project_root, tuple(existing))
  5296. if isinstance(verdicts, str) or any(
  5297. not verdicts[path].ignored for path in existing
  5298. ):
  5299. return "Adding ignore rules would newly hide existing reserved data or its protection is unverified."
  5300. tracked = run_project_command(
  5301. ("git", "ls-files", "-z", "--", *existing), project_root, timeout=60
  5302. )
  5303. if tracked is None or tracked.returncode != 0 or tracked.stdout:
  5304. return "Existing reserved data is tracked or its tracked state could not be verified."
  5305. except (OSError, UnicodeError):
  5306. return "Project installation targets could not be safely inspected."
  5307. return None
  5308. def inspect_project_setup(project_root: Path, skip_agents: bool) -> StateInspection:
  5309. inspection = inspect_project_state(project_root)
  5310. if inspection["status"] == "success":
  5311. conflict = project_scaffold_conflict(project_root, skip_agents)
  5312. if conflict:
  5313. inspection.update(
  5314. status="needs-user",
  5315. reason=conflict,
  5316. nextStep="Inspect the existing data and resolve the target or authorize its narrow protection before retrying; Onboard will not hide or replace it.",
  5317. )
  5318. return inspection
  5319. def build_sbtd_project_setup(
  5320. mode: str, args: argparse.Namespace, *, project_roots: list[Path] | None = None
  5321. ) -> dict[str, object]:
  5322. projects: list[dict[str, object]] = []
  5323. roots = resolve_project_roots(args) if project_roots is None else project_roots
  5324. for root in roots:
  5325. projects.append(
  5326. {
  5327. "projectRoot": str(root),
  5328. **inspect_project_setup(
  5329. root, bool(getattr(args, "skip_project_agents", False))
  5330. ),
  5331. }
  5332. )
  5333. status = aggregate_project_status(projects)
  5334. return {
  5335. "mode": mode,
  5336. "status": status,
  5337. "projects": projects,
  5338. "reason": (
  5339. "Only selected project state is inspected; optional artifacts are not created."
  5340. if projects
  5341. else "--projects-root was not provided."
  5342. ),
  5343. "nextStep": (
  5344. "Resolve each reported project condition before installation."
  5345. if project_status_exit_code(status)
  5346. else ""
  5347. ),
  5348. }
  5349. def print_sbtd_project_setup_report(report: dict[str, object]) -> None:
  5350. print("\nSBTD project setup:")
  5351. print(f"- status: {report.get('status')}")
  5352. if report.get("reason"):
  5353. print(f" reason: {report['reason']}")
  5354. for project in cast(list[dict[str, object]], report.get("projects", [])):
  5355. print(f"- project root: {project['projectRoot']}")
  5356. print(f" status: {project['status']}")
  5357. print(f" reason: {project['reason']}")
  5358. if project["nextStep"]:
  5359. print(f" next step: {project['nextStep']}")
  5360. # Explicit --developer identity integration. The library is imported lazily
  5361. # inside each function because sbtd_identity -> sbtd_task_state -> onboard is
  5362. # an intentional one-way dependency; a module-level import would be circular.
  5363. _DEVELOPER_BLOCKING_STATUSES = (
  5364. "failed",
  5365. "conflict",
  5366. "blocked",
  5367. "needs-confirmation",
  5368. "needs-protection",
  5369. )
  5370. def _developer_result(
  5371. root: Path, requested: str, *, create: bool = False, protect: bool = False
  5372. ) -> IdentityResult:
  5373. from sbtd_identity import DeveloperStore, IdentityResult
  5374. try:
  5375. store = DeveloperStore(root, read_only=not create)
  5376. if create:
  5377. return store.ensure(requested, confirmed=True, protect=protect)
  5378. return store.plan(requested)
  5379. except (TaskDataError, OSError, RuntimeError) as error:
  5380. return IdentityResult(
  5381. "failed" if create else "blocked",
  5382. path=str(root / ".sbtd/developer"),
  5383. topology="unknown",
  5384. reason="developer identity could not be safely inspected or initialized for this project",
  5385. completed_steps=tuple(getattr(error, "completed_steps", ())),
  5386. )
  5387. def _developer_plan_entry(
  5388. root: Path, requested: str, result: IdentityResult
  5389. ) -> dict[str, object]:
  5390. return {
  5391. "projectRoot": str(root),
  5392. "requestedName": requested,
  5393. "status": result.status,
  5394. "name": result.name,
  5395. "source": result.source,
  5396. "target": result.path,
  5397. "topology": result.topology,
  5398. "needsProtection": result.needs_protection,
  5399. "reason": result.reason,
  5400. "completedSteps": list(result.completed_steps),
  5401. }
  5402. def aggregate_developer_status(projects: list[dict[str, object]]) -> str:
  5403. statuses = [str(project["status"]) for project in projects]
  5404. if not statuses:
  5405. return "blocked"
  5406. for blocking in _DEVELOPER_BLOCKING_STATUSES:
  5407. if blocking in statuses:
  5408. return blocking
  5409. if "created" in statuses:
  5410. return "created"
  5411. if "planned" in statuses:
  5412. return "planned"
  5413. return "unchanged"
  5414. def _developer_plan_payload(
  5415. requested: str, projects: list[dict[str, object]]
  5416. ) -> dict[str, object]:
  5417. return {
  5418. "requestedName": requested,
  5419. "status": aggregate_developer_status(projects),
  5420. "reason": (
  5421. None
  5422. if projects
  5423. else "--developer requires at least one explicit --projects-root; "
  5424. "the name is never derived from or written to the cwd or HOME."
  5425. ),
  5426. "projects": projects,
  5427. }
  5428. def developer_plan_exit_code(developer_plan: dict[str, object]) -> int:
  5429. status = str(developer_plan["status"])
  5430. if status == "failed":
  5431. return 5
  5432. if status in _DEVELOPER_BLOCKING_STATUSES:
  5433. return 2
  5434. return 0
  5435. def build_developer_plan(args: argparse.Namespace) -> dict[str, object] | None:
  5436. """Read-only per-project identity plan for an explicit --developer name.
  5437. Only the roots listed via --projects-root are inspected; without them the
  5438. plan is blocked rather than falling back to the cwd or HOME.
  5439. """
  5440. requested = getattr(args, "developer", None)
  5441. if requested is None:
  5442. return None
  5443. projects = [
  5444. _developer_plan_entry(
  5445. root, requested, _developer_result(root, requested)
  5446. )
  5447. for root in resolve_project_roots(args)
  5448. ]
  5449. return _developer_plan_payload(requested, projects)
  5450. def ensure_developer_identities(
  5451. developer_plan: dict[str, object],
  5452. ) -> dict[str, object]:
  5453. """Post-scaffold verified identity creation for the preflighted projects.
  5454. Runs after scaffold writes. Only protection explicitly included in the
  5455. confirmed identity plan may be completed by the shared narrow helper.
  5456. """
  5457. requested = str(developer_plan["requestedName"])
  5458. projects: list[dict[str, object]] = []
  5459. for entry in cast(list[dict[str, object]], developer_plan["projects"]):
  5460. root = Path(str(entry["projectRoot"]))
  5461. result = _developer_result(
  5462. root, requested, create=True, protect=entry.get("needsProtection") is True
  5463. )
  5464. projects.append(_developer_plan_entry(root, requested, result))
  5465. return _developer_plan_payload(requested, projects)
  5466. def print_developer_plan(developer_plan: dict[str, object]) -> None:
  5467. print("\nDeveloper identity:")
  5468. print(f"- requested name: {developer_plan['requestedName']}")
  5469. print(f"- status: {developer_plan['status']}")
  5470. if developer_plan.get("reason"):
  5471. print(f" reason: {developer_plan['reason']}")
  5472. for project in cast(list[dict[str, object]], developer_plan["projects"]):
  5473. print(f"- project root: {project['projectRoot']}")
  5474. print(f" status: {project['status']}")
  5475. if project.get("name"):
  5476. print(f" name: {project['name']} (source: {project.get('source')})")
  5477. if project.get("target"):
  5478. print(f" target: {project['target']}")
  5479. if project.get("needsProtection"):
  5480. print(" needs protection: yes")
  5481. if project.get("reason"):
  5482. print(f" reason: {project['reason']}")
  5483. def install_playwright_cli(args: argparse.Namespace) -> int:
  5484. project_root = resolve_project_root(args, required=True)
  5485. runtime = check_npm_runtime()
  5486. before = check_playwright_project(project_root)
  5487. package_json = project_root / "package.json"
  5488. payload: dict[str, object] = {
  5489. "mode": "install-playwright-cli",
  5490. "projectRoot": str(project_root),
  5491. "before": before,
  5492. "runtime": runtime,
  5493. }
  5494. if before["installed"] and not args.reinstall:
  5495. payload["status"] = "already-installed"
  5496. if args.json:
  5497. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5498. else:
  5499. print("Project-level Playwright CLI is already present.")
  5500. if before.get("version"):
  5501. print(f"Playwright dependency: {before['version']}")
  5502. return 0
  5503. if not runtime["npm"]["installed"]:
  5504. payload["status"] = "npm-required"
  5505. payload["advice"] = (
  5506. f"{shell_prefix()}Install npm first, for example with `{onboard_command('ensure-npm', '--yes')}` after user confirmation."
  5507. )
  5508. if args.json:
  5509. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5510. else:
  5511. print(
  5512. "Playwright CLI is project-level Node tooling, but npm is not usable."
  5513. )
  5514. print(payload["advice"])
  5515. return 2
  5516. if not package_json.is_file():
  5517. payload["status"] = "not-applicable"
  5518. payload["reason"] = (
  5519. "No package.json exists at the project root; do not create a Node test stack automatically."
  5520. )
  5521. payload["fallback"] = (
  5522. "Use Playwright MCP or Chrome DevTools MCP for exploratory Web diagnostics, and add Playwright CLI only after the project accepts a Node test dependency."
  5523. )
  5524. if args.json:
  5525. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5526. else:
  5527. print(payload["reason"])
  5528. print(payload["fallback"])
  5529. return 2
  5530. payload["actions"] = [
  5531. "install project dependency: npm install -D @playwright/test",
  5532. "install Playwright browser binaries: npx playwright install",
  5533. ]
  5534. if args.skip_browsers:
  5535. payload["actions"][-1] = (
  5536. "skip browser binary installation because --skip-browsers was provided"
  5537. )
  5538. if not args.yes:
  5539. payload["status"] = "needs-confirmation"
  5540. if args.json:
  5541. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5542. else:
  5543. print("Project-level Playwright CLI is missing.")
  5544. for action in payload["actions"]:
  5545. print(f"- {action}")
  5546. print("Rerun with --yes after user confirmation.")
  5547. return 2
  5548. install_result = run_project_command(
  5549. ("npm", "install", "-D", "@playwright/test"), project_root, timeout=900
  5550. )
  5551. payload["npmInstallOutput"] = command_excerpt(install_result)
  5552. if not install_result or install_result.returncode != 0:
  5553. payload["status"] = "failed"
  5554. payload["error"] = command_excerpt(install_result) or "npm install failed."
  5555. print(
  5556. json.dumps(payload, indent=2, ensure_ascii=False)
  5557. if args.json
  5558. else payload["error"]
  5559. )
  5560. return 1
  5561. if not args.skip_browsers:
  5562. browsers_result = run_project_command(
  5563. ("npx", "playwright", "install"), project_root, timeout=1200
  5564. )
  5565. payload["browserInstallOutput"] = command_excerpt(browsers_result)
  5566. if not browsers_result or browsers_result.returncode != 0:
  5567. payload["status"] = "browser-install-failed"
  5568. payload["error"] = (
  5569. command_excerpt(browsers_result) or "npx playwright install failed."
  5570. )
  5571. print(
  5572. json.dumps(payload, indent=2, ensure_ascii=False)
  5573. if args.json
  5574. else payload["error"]
  5575. )
  5576. return 1
  5577. after = check_playwright_project(project_root)
  5578. payload["after"] = after
  5579. payload["status"] = "installed" if after["installed"] else "failed"
  5580. if args.json:
  5581. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5582. else:
  5583. print(f"install-playwright-cli status: {payload['status']}")
  5584. if after["installed"]:
  5585. print(
  5586. "Project-level Playwright CLI dependency/config marker is now present."
  5587. )
  5588. else:
  5589. print(
  5590. "Playwright install completed but no dependency/config/script marker was detected."
  5591. )
  5592. return 0 if after["installed"] else 1
  5593. def build_operations(mode: str, args: argparse.Namespace) -> list[Operation]:
  5594. project_roots = resolve_project_roots(args)
  5595. operations: list[Operation] = []
  5596. if mode != "init-projects":
  5597. global_agents = expand_path(args.global_agents_path) or (
  5598. default_codex_home() / "AGENTS.md"
  5599. )
  5600. operations.append(
  5601. Operation(
  5602. "codex global AGENTS.md",
  5603. GLOBAL_AGENTS_TEMPLATE,
  5604. global_agents,
  5605. "file",
  5606. )
  5607. )
  5608. omp_agents_path, omp_agents_explicit = omp_agents_target()
  5609. if omp_agents_explicit or detect_omp_root() is not None:
  5610. omp_agents = omp_agents_path.resolve()
  5611. if omp_agents != global_agents.resolve():
  5612. operations.append(
  5613. Operation(
  5614. "omp global AGENTS.md",
  5615. GLOBAL_AGENTS_TEMPLATE,
  5616. omp_agents,
  5617. "file",
  5618. )
  5619. )
  5620. skills_root = scoped_skills_root(args)
  5621. for name, source in SKILL_SOURCES.items():
  5622. target = skills_root / name
  5623. operations.append(
  5624. Operation(
  5625. f"global skill {name}",
  5626. source,
  5627. target,
  5628. "dir",
  5629. source.resolve() == target.resolve(),
  5630. skip_when_valid=mode == "init",
  5631. )
  5632. )
  5633. for project_root in project_roots:
  5634. if not args.skip_project_agents:
  5635. operations.append(
  5636. Operation(
  5637. f"project AGENTS.md [{project_root}]",
  5638. PROJECT_AGENTS_TEMPLATE,
  5639. project_root / "AGENTS.md",
  5640. "file",
  5641. )
  5642. )
  5643. operations.append(
  5644. Operation(
  5645. f"project .gitignore [{project_root}]",
  5646. PROJECT_GITIGNORE_TEMPLATE,
  5647. project_root / ".gitignore",
  5648. "ensure-file-block",
  5649. )
  5650. )
  5651. return dedupe_file_operations(operations)
  5652. def dedupe_file_operations(operations: list[Operation]) -> list[Operation]:
  5653. seen: set[Path] = set()
  5654. unique: list[Operation] = []
  5655. for operation in operations:
  5656. if operation.kind == "file":
  5657. target = operation.target.resolve()
  5658. if target in seen:
  5659. continue
  5660. seen.add(target)
  5661. unique.append(operation)
  5662. return unique
  5663. def build_bundled_skill_migration_plan(
  5664. mode: str, args: argparse.Namespace
  5665. ) -> dict[str, object]:
  5666. if mode == "init-projects":
  5667. return {
  5668. "mode": "bundled-skill-rename",
  5669. "status": "skipped",
  5670. "reason": "init-projects does not inspect or modify global skills.",
  5671. }
  5672. skills_root = scoped_skills_root(args)
  5673. migrations: list[dict[str, object]] = []
  5674. conflicts: list[dict[str, object]] = []
  5675. for canonical_name, legacy_names in BUNDLED_SKILL_LEGACY_NAMES.items():
  5676. canonical_target = skills_root / canonical_name
  5677. legacy_targets: list[Path] = []
  5678. for legacy_name in legacy_names:
  5679. legacy_target = skills_root / legacy_name
  5680. if not legacy_target.exists():
  5681. continue
  5682. actual_name = (
  5683. read_skill_frontmatter_name(legacy_target / "SKILL.md")
  5684. if legacy_target.is_dir()
  5685. else None
  5686. )
  5687. if actual_name != legacy_name:
  5688. conflicts.append(
  5689. {
  5690. "path": str(legacy_target),
  5691. "expectedName": legacy_name,
  5692. "actualName": actual_name,
  5693. }
  5694. )
  5695. continue
  5696. legacy_targets.append(legacy_target)
  5697. migrations.append(
  5698. {
  5699. "canonicalName": canonical_name,
  5700. "canonicalTarget": str(canonical_target),
  5701. "legacyTargets": [str(path) for path in legacy_targets],
  5702. }
  5703. )
  5704. return {
  5705. "mode": "bundled-skill-rename",
  5706. "status": (
  5707. "blocked"
  5708. if conflicts
  5709. else "required"
  5710. if any(item["legacyTargets"] for item in migrations)
  5711. else "not-needed"
  5712. ),
  5713. "reason": (
  5714. "A legacy path exists but its Skill identity does not match the "
  5715. "legacy name; no files were changed."
  5716. if conflicts
  5717. else None
  5718. ),
  5719. "targetDir": str(skills_root),
  5720. "migrations": migrations,
  5721. "conflicts": conflicts,
  5722. }
  5723. def run_bundled_skill_migration(plan: dict[str, object]) -> list[dict[str, object]]:
  5724. if plan.get("status") == "skipped":
  5725. return []
  5726. results: list[dict[str, object]] = []
  5727. for raw_item in cast(list[dict[str, object]], plan.get("migrations") or []):
  5728. canonical_name = str(raw_item["canonicalName"])
  5729. canonical_target = Path(str(raw_item["canonicalTarget"]))
  5730. legacy_targets = [
  5731. Path(str(path)) for path in raw_item.get("legacyTargets") or []
  5732. ]
  5733. if read_skill_frontmatter_name(canonical_target / "SKILL.md") != canonical_name:
  5734. results.append(
  5735. {
  5736. "name": canonical_name,
  5737. "status": "failed",
  5738. "target": str(canonical_target),
  5739. "error": "canonical bundled Skill is missing or has invalid frontmatter",
  5740. }
  5741. )
  5742. continue
  5743. for legacy_target in legacy_targets:
  5744. try:
  5745. remove_existing_target(legacy_target)
  5746. except OSError as exc:
  5747. results.append(
  5748. {
  5749. "name": legacy_target.name,
  5750. "status": "failed",
  5751. "target": str(legacy_target),
  5752. "canonicalTarget": str(canonical_target),
  5753. "error": str(exc),
  5754. }
  5755. )
  5756. continue
  5757. results.append(
  5758. {
  5759. "name": legacy_target.name,
  5760. "status": "removed",
  5761. "target": str(legacy_target),
  5762. "canonicalTarget": str(canonical_target),
  5763. }
  5764. )
  5765. return results
  5766. def print_bundled_skill_migration_report(results: list[dict[str, object]]) -> None:
  5767. print("\nBundled Skill rename migration report:")
  5768. if not results:
  5769. print("- none")
  5770. return
  5771. for item in results:
  5772. print(f"- {item['name']}: {item['status']}")
  5773. print(f" target: {item['target']}")
  5774. if item.get("canonicalTarget"):
  5775. print(f" canonical target: {item['canonicalTarget']}")
  5776. if item.get("error"):
  5777. print(f" error: {item['error']}")
  5778. def operation_plan_entry(operation: Operation) -> dict[str, object]:
  5779. entry: dict[str, object] = {
  5780. "label": operation.label,
  5781. "source": str(operation.source),
  5782. "target": str(operation.target),
  5783. "kind": operation.kind,
  5784. "targetExists": operation.target.exists(),
  5785. "sameLocation": operation.same_location,
  5786. }
  5787. if operation.kind != "dir":
  5788. return entry
  5789. valid = external_skill_target_is_valid(
  5790. operation.target.parent, operation.target.name
  5791. )
  5792. entry["targetValid"] = valid
  5793. if operation.same_location:
  5794. action = "skipped-same-location"
  5795. entry["plannedActionOnInit"] = action
  5796. entry["plannedActionOnReset"] = action
  5797. return entry
  5798. if valid:
  5799. entry["plannedActionOnInit"] = "skipped-already-valid"
  5800. entry["plannedActionOnReset"] = "overwritten-without-backup"
  5801. return entry
  5802. action = (
  5803. "overwritten-without-backup" if operation.target.exists() else "copied"
  5804. )
  5805. entry["plannedActionOnInit"] = action
  5806. entry["plannedActionOnReset"] = action
  5807. return entry
  5808. def build_plan_payload(
  5809. mode: str,
  5810. operations: list[Operation],
  5811. bundled_migration_plan: dict[str, object] | None = None,
  5812. external_migration_plan: dict[str, object] | None = None,
  5813. global_skills_dir: Path | None = None,
  5814. global_skills_dir_source: str | None = None,
  5815. sbtd_init_plan: dict[str, object] | None = None,
  5816. ) -> dict[str, object]:
  5817. payload: dict[str, object] = {
  5818. "mode": mode,
  5819. "platform": platform.system() or sys.platform,
  5820. "skillDir": str(SKILL_DIR),
  5821. "globalSkillsDir": str(global_skills_dir) if global_skills_dir else None,
  5822. "globalSkillsDirSource": global_skills_dir_source,
  5823. "skillWritePolicy": {
  5824. "init": "skip-valid-shells",
  5825. "reset": "overwrite-all",
  5826. },
  5827. "operations": [operation_plan_entry(op) for op in operations],
  5828. }
  5829. if bundled_migration_plan:
  5830. payload["bundledMigration"] = bundled_migration_plan
  5831. if external_migration_plan:
  5832. payload["externalMigration"] = external_migration_plan
  5833. if sbtd_init_plan:
  5834. payload["sbtdInit"] = sbtd_init_plan
  5835. if global_skills_dir and mode in {"plan", "init", "reset"}:
  5836. payload["cavemanMaintenance"] = caveman_maintenance_plan(global_skills_dir)
  5837. payload["contentAlignment"] = check_content_alignment(global_skills_dir)
  5838. if mode != "init-projects":
  5839. payload["graft"] = check_graft()
  5840. return payload
  5841. def print_plan(payload: dict[str, object]) -> None:
  5842. print(f"Mode: {payload['mode']}")
  5843. print(f"Platform: {payload['platform']}")
  5844. if "contentAlignment" in payload:
  5845. print(f"Skills-only content alignment: {payload['contentAlignment']['status']}")
  5846. if payload["contentAlignment"]["status"] != "aligned":
  5847. print(" Existing valid Skills may be retained; use upgrade for confirmed content alignment.")
  5848. for label, key in (("Optional Graft CLI", "graft"), ("Graft wiring", "graftWiring")):
  5849. details = payload.get(key)
  5850. if isinstance(details, dict):
  5851. print(f"{label}: {details.get('status')}")
  5852. if details.get("reason"):
  5853. print(f" reason: {details['reason']}")
  5854. if details.get("nextStep"):
  5855. print(f" next: {details['nextStep']}")
  5856. if key == "graftWiring" and details.get("status") == "planned":
  5857. for operation in details.get("sharedOperations", []):
  5858. print(f" host resource: {operation['target']}")
  5859. if details.get("retireLegacy"):
  5860. print(" retire only exact owned fixed-root MCP entries for:")
  5861. for root in details.get("roots", []):
  5862. print(f" {root}")
  5863. for binding in details.get("bindings", []):
  5864. if "legacy" in binding:
  5865. print(f" approved old runtime: {json.dumps(binding['legacy'], sort_keys=True)}")
  5866. print(" preserve originals; no runtime-directory or backup deletion")
  5867. for item in payload["operations"]:
  5868. if item["sameLocation"]:
  5869. exists = "same source and target"
  5870. else:
  5871. exists = "exists" if item["targetExists"] else "missing"
  5872. if item.get("plannedActionOnInit"):
  5873. exists += (
  5874. f", init={item['plannedActionOnInit']}"
  5875. f", reset={item['plannedActionOnReset']}"
  5876. )
  5877. print(f"- {item['label']}: {item['target']} ({exists})")
  5878. caveman_maintenance = payload.get("cavemanMaintenance")
  5879. if caveman_maintenance:
  5880. print("\nCaveman maintenance:")
  5881. print(
  5882. f"- state: {caveman_maintenance['state']}, "
  5883. f"action: {caveman_maintenance['plannedAction']}, "
  5884. f"pinned: {caveman_maintenance['pinnedRef']}"
  5885. )
  5886. print_caveman_maintenance_details(cast(dict[str, object], caveman_maintenance))
  5887. bundled_migration_plan = payload.get("bundledMigration")
  5888. if bundled_migration_plan:
  5889. print("\nBundled Skill rename migration:")
  5890. print(f"- status: {bundled_migration_plan['status']}")
  5891. if bundled_migration_plan.get("targetDir"):
  5892. print(f"- target skills dir: {bundled_migration_plan['targetDir']}")
  5893. if bundled_migration_plan.get("reason"):
  5894. print(f"- reason: {bundled_migration_plan['reason']}")
  5895. for item in bundled_migration_plan.get("migrations") or []:
  5896. if item.get("legacyTargets"):
  5897. print(
  5898. "- remove legacy: "
  5899. + ", ".join(str(path) for path in item["legacyTargets"])
  5900. )
  5901. for item in bundled_migration_plan.get("conflicts") or []:
  5902. print(
  5903. "- legacy identity conflict: "
  5904. f"{item['path']} (expected {item['expectedName']}, "
  5905. f"got {item.get('actualName') or '<missing>'})"
  5906. )
  5907. external_migration_plan = payload.get("externalMigration")
  5908. if external_migration_plan:
  5909. print("\nExternal mattpocock migration:")
  5910. print(f"- status: {external_migration_plan['status']}")
  5911. if external_migration_plan.get("targetDir"):
  5912. print(f"- target skills dir: {external_migration_plan['targetDir']}")
  5913. if external_migration_plan.get("reason"):
  5914. print(f"- reason: {external_migration_plan['reason']}")
  5915. if external_migration_plan.get("detectedLegacy"):
  5916. print(
  5917. "- detected legacy: "
  5918. + ", ".join(
  5919. str(name) for name in external_migration_plan["detectedLegacy"]
  5920. )
  5921. )
  5922. if external_migration_plan.get("detectedCanonical"):
  5923. print(
  5924. "- detected canonical: "
  5925. + ", ".join(
  5926. str(name) for name in external_migration_plan["detectedCanonical"]
  5927. )
  5928. )
  5929. if external_migration_plan.get("requiredCanonical"):
  5930. print(
  5931. "- required canonical: "
  5932. + ", ".join(
  5933. str(name) for name in external_migration_plan["requiredCanonical"]
  5934. )
  5935. )
  5936. if external_migration_plan.get("removeLegacy"):
  5937. print(
  5938. "- remove legacy: "
  5939. + ", ".join(
  5940. str(name) for name in external_migration_plan["removeLegacy"]
  5941. )
  5942. )
  5943. sbtd_init_plan = payload.get("sbtdInit")
  5944. if sbtd_init_plan:
  5945. print_sbtd_project_setup_report(cast(dict[str, object], sbtd_init_plan))
  5946. def operation_allows_existing_target(operation: Operation) -> bool:
  5947. return operation.kind == "ensure-file-block"
  5948. def operation_result(
  5949. operation: Operation,
  5950. status: str,
  5951. action: str,
  5952. *,
  5953. backup: Path | None = None,
  5954. reason: str | None = None,
  5955. ) -> dict[str, object]:
  5956. result: dict[str, object] = {
  5957. "label": operation.label,
  5958. "target": str(operation.target),
  5959. "kind": operation.kind,
  5960. "status": status,
  5961. "action": action,
  5962. }
  5963. if backup:
  5964. result["backup"] = str(backup)
  5965. if reason:
  5966. result["reason"] = reason
  5967. return result
  5968. def print_operation_report(
  5969. results: list[dict[str, object]], heading: str = "Operation report"
  5970. ) -> None:
  5971. print(f"\n{heading}:")
  5972. if not results:
  5973. print("- none")
  5974. return
  5975. for item in results:
  5976. print(f"- {item['label']}: {item['status']}")
  5977. print(f" target: {item['target']}")
  5978. print(f" action: {item['action']}")
  5979. if item.get("backup"):
  5980. print(f" backup: {item['backup']}")
  5981. if item.get("reason"):
  5982. print(f" reason: {item['reason']}")
  5983. def print_external_migration_report(results: list[dict[str, object]]) -> None:
  5984. print("\nExternal mattpocock migration report:")
  5985. if not results:
  5986. print("- none")
  5987. return
  5988. for item in results:
  5989. label = item.get("name") or item.get("repo") or "migration"
  5990. print(f"- {label}: {item['status']}")
  5991. if item.get("phase"):
  5992. print(f" phase: {item['phase']}")
  5993. if item.get("target"):
  5994. print(f" target: {item['target']}")
  5995. if item.get("backup"):
  5996. print(f" backup: {item['backup']}")
  5997. if item.get("error"):
  5998. print(f" error: {item['error']}")
  5999. if item.get("reason"):
  6000. print(f" reason: {item['reason']}")
  6001. def ensure_confirmed(args: argparse.Namespace, mode: str) -> None:
  6002. if mode == "plan":
  6003. return
  6004. if not args.yes:
  6005. raise SystemExit(
  6006. "Refusing to change files without --yes. Run plan first, then rerun with --yes."
  6007. )
  6008. def run(mode: str, args: argparse.Namespace) -> int:
  6009. # One process may run several modes; a note left by an earlier run would
  6010. # make a later one report checks it never skipped.
  6011. UNVERIFIED_CHECKS.clear()
  6012. if mode == "upgrade":
  6013. from sbtd_upgrade_cli import run_upgrade
  6014. return run_upgrade(args)
  6015. if mode == "recovery" and (
  6016. getattr(args, "upgrade_plan", None) is not None
  6017. or getattr(args, "upgrade_recovery_plan", None) is not None
  6018. ):
  6019. from sbtd_upgrade_cli import run_upgrade_recovery
  6020. return run_upgrade_recovery(args)
  6021. if mode == "migration":
  6022. try:
  6023. from sbtd_migration import run_migration
  6024. except ImportError:
  6025. reason = "the installed migration runtime or its declared dependencies are unavailable"
  6026. response = {
  6027. "mode": "migration",
  6028. "phase": args.phase,
  6029. "status": "blocked",
  6030. "manifest_id": None,
  6031. "verification_id": None,
  6032. "projects": [],
  6033. "reason": reason,
  6034. "nextStep": "Restore the complete installed Skill and its declared dependencies before retrying.",
  6035. "migration": {},
  6036. }
  6037. if args.json:
  6038. print(json.dumps(response, ensure_ascii=False, allow_nan=False))
  6039. else:
  6040. print(f"Migration {args.phase}: blocked")
  6041. print(reason)
  6042. print(response["nextStep"])
  6043. return 2
  6044. return run_migration(args)
  6045. if mode == "recovery":
  6046. from sbtd_recovery import run_recovery
  6047. return run_recovery(args)
  6048. if mode == "cleanup-legacy":
  6049. from sbtd_cleanup_legacy import run_cleanup_legacy
  6050. return run_cleanup_legacy(args)
  6051. if mode in {"init", "init-projects"} and getattr(args, "migration_manifest", None):
  6052. from sbtd_graft_deployment import run_migration_init
  6053. return run_migration_init(mode, args)
  6054. if mode == "check":
  6055. results = build_check_results(args)
  6056. if (
  6057. getattr(args, "platform", None) in {"codex", "omp", "oh-my-pi"}
  6058. or getattr(args, "graft_hooks", False)
  6059. or getattr(args, "graft_retire_legacy", False)
  6060. or getattr(args, "graft_legacy_bindings", None)
  6061. ):
  6062. from sbtd_graft_deployment import plan_normal_wiring
  6063. results["graftWiring"] = plan_normal_wiring(
  6064. mode, args,
  6065. installation_targets=[
  6066. op.target for op in build_operations(mode, args) if not op.same_location
  6067. ],
  6068. )
  6069. developer_plan = build_developer_plan(args)
  6070. if developer_plan is not None:
  6071. results["developerPlan"] = developer_plan
  6072. print_check_results(results, args.json)
  6073. if cast(dict[str, object], results.get("graftWiring", {})).get("status") == "blocked":
  6074. return 2
  6075. if developer_plan is not None:
  6076. if not args.json:
  6077. print_developer_plan(developer_plan)
  6078. developer_exit = developer_plan_exit_code(developer_plan)
  6079. if developer_exit:
  6080. print(
  6081. "Developer identity preflight failed: resolve each "
  6082. "conflicting or blocked project, or pass an explicit "
  6083. "--projects-root.",
  6084. file=sys.stderr,
  6085. )
  6086. return developer_exit
  6087. provider = cast(dict[str, object], results["ponytailProvider"])
  6088. if provider["provider"] == "conflict":
  6089. print(
  6090. "Ponytail provider conflict: the official Ponytail plugin is "
  6091. "enabled; disable or remove it before using Onboard stable Skills.",
  6092. file=sys.stderr,
  6093. )
  6094. return 4
  6095. projects = cast(list[dict[str, object]], results["projectChecks"])
  6096. return project_status_exit_code(
  6097. aggregate_project_status(
  6098. [cast(dict[str, object], item["sbtd"]) for item in projects]
  6099. )
  6100. )
  6101. if mode == "check-projects":
  6102. results = build_projects_check_results(args)
  6103. print_projects_check_results(results, args.json)
  6104. projects = cast(list[dict[str, object]], results["projects"])
  6105. return project_status_exit_code(
  6106. aggregate_project_status(
  6107. [cast(dict[str, object], item["sbtd"]) for item in projects]
  6108. )
  6109. )
  6110. if mode == "check-agent-cli":
  6111. print_agent_cli_check(check_agent_cli(args.platform), args.json)
  6112. return 0
  6113. if mode == "ensure-npm":
  6114. return ensure_npm(args)
  6115. if mode == "install-agent-cli":
  6116. return install_agent_cli(args)
  6117. if mode == "install-rtk":
  6118. return install_rtk(args)
  6119. if mode == "install-graft":
  6120. payload, code = install_graft(
  6121. confirmed=bool(args.yes),
  6122. telemetry_only=bool(args.telemetry_only),
  6123. )
  6124. if args.json:
  6125. print(json.dumps(payload, indent=2, ensure_ascii=False))
  6126. else:
  6127. print("Graft installation:")
  6128. print(json.dumps(payload, indent=2, ensure_ascii=False))
  6129. return code
  6130. if mode == "install-caveman":
  6131. return install_caveman(args)
  6132. if mode == "install-java":
  6133. return install_java(args)
  6134. if mode == "install-maestro":
  6135. return install_maestro(args)
  6136. if mode == "install-playwright-cli":
  6137. return install_playwright_cli(args)
  6138. if mode == "install-external-skills":
  6139. return install_external_skills(args)
  6140. if mode == "migrate-external-skills":
  6141. return migrate_external_skills(args)
  6142. if mode == "promote-external-skills-stable":
  6143. return promote_external_skills_stable(args)
  6144. if mode in {"init", "reset"} and not args.json:
  6145. print_check_results(build_check_results(args), False)
  6146. print("")
  6147. global_skills_dir, global_skills_dir_source = resolve_global_skills_dir(
  6148. getattr(args, "global_skills_dir", None)
  6149. )
  6150. operations = build_operations(mode, args)
  6151. bundled_migration_plan = build_bundled_skill_migration_plan(mode, args)
  6152. external_migration_plan = (
  6153. {
  6154. "mode": "mattpocock-external-migration",
  6155. "status": "skipped",
  6156. "reason": "init-projects does not inspect or modify global skills.",
  6157. }
  6158. if mode == "init-projects"
  6159. else build_external_migration_plan(args)
  6160. )
  6161. plan_payload = build_plan_payload(
  6162. mode,
  6163. operations,
  6164. bundled_migration_plan,
  6165. external_migration_plan,
  6166. global_skills_dir,
  6167. global_skills_dir_source,
  6168. build_sbtd_project_setup(mode, args),
  6169. )
  6170. from sbtd_graft_deployment import plan_normal_wiring
  6171. wiring_plan = plan_normal_wiring(
  6172. mode, args,
  6173. installation_targets=[op.target for op in operations if not op.same_location],
  6174. )
  6175. if wiring_plan["status"] != "skipped":
  6176. plan_payload["graftWiring"] = wiring_plan
  6177. developer_plan = build_developer_plan(args)
  6178. if developer_plan is not None:
  6179. plan_payload["developerPlan"] = developer_plan
  6180. if mode in {"init", "reset"}:
  6181. plan_payload["requiredExternalInstall"] = None
  6182. plan_json_emitted = False
  6183. def emit_plan_json() -> None:
  6184. """Release the held-back plan as this run's single `--json` document.
  6185. Write modes fold the plan into one merged document at the end of the
  6186. run, so any path that returns before that has to emit the plan itself
  6187. or `--json` would leave stdout empty.
  6188. """
  6189. nonlocal plan_json_emitted
  6190. if args.json and not plan_json_emitted:
  6191. plan_json_emitted = True
  6192. print(json.dumps(plan_payload, indent=2, ensure_ascii=False))
  6193. if not args.json:
  6194. print_plan(plan_payload)
  6195. if developer_plan is not None:
  6196. print_developer_plan(developer_plan)
  6197. if mode == "plan":
  6198. emit_plan_json()
  6199. if wiring_plan["status"] == "blocked":
  6200. return 2
  6201. if developer_plan is not None:
  6202. return developer_plan_exit_code(developer_plan)
  6203. return 0
  6204. ensure_confirmed(args, mode)
  6205. if wiring_plan["status"] == "blocked":
  6206. emit_plan_json()
  6207. return 2
  6208. if developer_plan is not None:
  6209. # Whole-batch identity preflight before any global or project
  6210. # mutation: a conflict or unknown checkout anywhere stops the run
  6211. # before the first project is written.
  6212. developer_exit = developer_plan_exit_code(developer_plan)
  6213. if developer_exit:
  6214. print(
  6215. "Developer identity preflight failed; no files were changed.",
  6216. file=sys.stderr,
  6217. )
  6218. plan_payload["backups"] = []
  6219. emit_plan_json()
  6220. return developer_exit
  6221. sbtd_preflight = cast(dict[str, object], plan_payload["sbtdInit"])
  6222. preflight_exit = project_status_exit_code(sbtd_preflight["status"])
  6223. if preflight_exit:
  6224. plan_payload["sbtdProjectSetup"] = sbtd_preflight
  6225. plan_payload["backups"] = []
  6226. emit_plan_json()
  6227. return preflight_exit
  6228. if bundled_migration_plan.get("status") == "blocked":
  6229. print(
  6230. "Bundled Skill rename migration blocked: legacy Skill identity "
  6231. "does not match the configured legacy name.",
  6232. file=sys.stderr,
  6233. )
  6234. emit_plan_json()
  6235. return 4
  6236. external_identity_failures = (
  6237. external_migration_identity_failures(external_migration_plan)
  6238. if external_migration_plan.get("status") == "planned"
  6239. else []
  6240. )
  6241. if external_identity_failures:
  6242. print(
  6243. "External mattpocock migration blocked: legacy Skill identity "
  6244. "does not match the configured legacy name.",
  6245. file=sys.stderr,
  6246. )
  6247. for item in external_identity_failures:
  6248. label = item.get("name") or item.get("repo") or "migration"
  6249. print(f"- {label}: {item.get('error', 'unknown failure')}", file=sys.stderr)
  6250. emit_plan_json()
  6251. return 4
  6252. if mode in {"init", "reset"}:
  6253. ponytail_provider = detect_ponytail_provider(global_skills_dir)
  6254. if ponytail_provider["provider"] == "conflict":
  6255. print(
  6256. "Ponytail provider conflict: the official Ponytail plugin is "
  6257. "enabled; disable or remove it before init/reset writes Onboard "
  6258. "stable Skills.",
  6259. file=sys.stderr,
  6260. )
  6261. emit_plan_json()
  6262. return 4
  6263. from sbtd_graft_deployment import legacy_bindings_unchanged
  6264. if not legacy_bindings_unchanged(wiring_plan):
  6265. plan_payload["graftWiring"] = {
  6266. **wiring_plan,
  6267. "status": "blocked",
  6268. "reason": "the approved legacy bindings changed before installation",
  6269. }
  6270. plan_payload["backups"] = []
  6271. emit_plan_json()
  6272. print("Legacy binding approval changed; no installation writes were performed.", file=sys.stderr)
  6273. return 2
  6274. external_install = install_required_external_skills(
  6275. args, overwrite=mode == "reset"
  6276. )
  6277. plan_payload["requiredExternalInstall"] = external_install
  6278. if (
  6279. external_install is not None
  6280. and cast(dict[str, object], external_install["transaction"])["status"]
  6281. != "committed"
  6282. ):
  6283. print(
  6284. "Required global external Skill installation failed.", file=sys.stderr
  6285. )
  6286. emit_plan_json()
  6287. return 4
  6288. active_operations = [op for op in operations if not op.same_location]
  6289. conflicts = [
  6290. op
  6291. for op in active_operations
  6292. if op.target.exists() and not operation_allows_existing_target(op)
  6293. ]
  6294. backups: list[tuple[Path, Path]] = []
  6295. backup_by_target: dict[Path, Path] = {}
  6296. backed_up: set[Path] = set()
  6297. for op in conflicts:
  6298. if op.kind != "file":
  6299. continue
  6300. target = op.target.resolve()
  6301. if target in backed_up or not op.target.exists():
  6302. continue
  6303. backup = backup_path(op.target)
  6304. op.target.parent.mkdir(parents=True, exist_ok=True)
  6305. shutil.move(str(op.target), str(backup))
  6306. backups.append((op.target, backup))
  6307. backup_by_target[op.target] = backup
  6308. backup_by_target[target] = backup
  6309. backed_up.add(target)
  6310. operation_results: list[dict[str, object]] = []
  6311. for op in active_operations:
  6312. try:
  6313. action = copy_operation(op)
  6314. failures = verify_operation(op)
  6315. if failures:
  6316. operation_results.append(
  6317. operation_result(
  6318. op,
  6319. "failed",
  6320. action,
  6321. backup=backup_by_target.get(op.target),
  6322. reason="verification failed: " + ", ".join(failures[:20]),
  6323. )
  6324. )
  6325. continue
  6326. status = "skipped" if action.startswith("skipped") else "success"
  6327. operation_results.append(
  6328. operation_result(
  6329. op,
  6330. status,
  6331. action,
  6332. backup=backup_by_target.get(op.target),
  6333. )
  6334. )
  6335. except Exception as exc: # noqa: BLE001 - report each file operation failure with context.
  6336. operation_results.append(
  6337. operation_result(
  6338. op,
  6339. "failed",
  6340. "error",
  6341. backup=backup_by_target.get(op.target),
  6342. reason=str(exc),
  6343. )
  6344. )
  6345. failed_operations = [
  6346. item for item in operation_results if item["status"] == "failed"
  6347. ]
  6348. if backups and not args.json:
  6349. # `--json` keeps stdout to a single document, and that document carries
  6350. # `backups`, so the prose list would only corrupt the payload here.
  6351. print("Backups:")
  6352. for original, backup in backups:
  6353. print(f"- {original} -> {backup}")
  6354. if not args.json:
  6355. print_operation_report(operation_results)
  6356. if failed_operations:
  6357. print("Verification failed:", file=sys.stderr)
  6358. for item in failed_operations:
  6359. print(
  6360. f"- {item['label']}: {item.get('reason', 'unknown failure')}",
  6361. file=sys.stderr,
  6362. )
  6363. emit_plan_json()
  6364. return 3
  6365. if developer_plan is not None:
  6366. # Capture completed writes before identity work: its failure must not
  6367. # leave automation with a plan that hides already-applied changes.
  6368. plan_payload["operationResults"] = operation_results
  6369. identity_roots = [
  6370. Path(str(entry["projectRoot"]))
  6371. for entry in cast(list[dict[str, object]], developer_plan["projects"])
  6372. ]
  6373. developer_plan = ensure_developer_identities(developer_plan)
  6374. plan_payload["developerPlan"] = developer_plan
  6375. if not args.json:
  6376. print_developer_plan(developer_plan)
  6377. developer_exit = developer_plan_exit_code(developer_plan)
  6378. if developer_exit:
  6379. plan_payload["sbtdProjectSetup"] = build_sbtd_project_setup(
  6380. mode, args, project_roots=identity_roots
  6381. )
  6382. plan_payload["unverifiedChecks"] = list(UNVERIFIED_CHECKS)
  6383. print(
  6384. "Developer identity initialization failed; completed project "
  6385. "writes are kept and reported.",
  6386. file=sys.stderr,
  6387. )
  6388. plan_payload["backups"] = [
  6389. {"target": str(target), "backup": str(backup)}
  6390. for target, backup in backups
  6391. ]
  6392. emit_plan_json()
  6393. return developer_exit
  6394. bundled_migration_results = run_bundled_skill_migration(bundled_migration_plan)
  6395. failed_bundled_migrations = [
  6396. item for item in bundled_migration_results if item["status"] == "failed"
  6397. ]
  6398. if not args.json:
  6399. print_bundled_skill_migration_report(bundled_migration_results)
  6400. if failed_bundled_migrations:
  6401. print("Bundled Skill rename migration failed:", file=sys.stderr)
  6402. for item in failed_bundled_migrations:
  6403. print(
  6404. f"- {item['name']}: {item.get('error', 'unknown failure')}",
  6405. file=sys.stderr,
  6406. )
  6407. emit_plan_json()
  6408. return 4
  6409. migration_results = run_external_migration(external_migration_plan)
  6410. failed_migrations = [
  6411. item for item in migration_results if item["status"] == "failed"
  6412. ]
  6413. if not args.json:
  6414. print_external_migration_report(migration_results)
  6415. if failed_migrations:
  6416. print("External mattpocock migration failed:", file=sys.stderr)
  6417. for item in failed_migrations:
  6418. label = item.get("name") or item.get("repo") or "migration"
  6419. print(f"- {label}: {item.get('error', 'unknown failure')}", file=sys.stderr)
  6420. emit_plan_json()
  6421. return 4
  6422. caveman_maintenance: dict[str, object] = {
  6423. "status": "skipped",
  6424. "scope": "workflow-skill-payload-only",
  6425. }
  6426. if mode in {"init", "reset"}:
  6427. try:
  6428. caveman_maintenance = maintain_caveman_payload(global_skills_dir)
  6429. except Exception as exc: # noqa: BLE001 - optional payload maintenance must not abort init/reset.
  6430. caveman_maintenance = {
  6431. "state": "abnormal",
  6432. "plannedAction": "repair",
  6433. "pinnedRef": CAVEMAN_PINNED_REF,
  6434. "pinnedRevision": CAVEMAN_PINNED_REVISION,
  6435. "scope": "workflow-skill-payload-only",
  6436. "status": "failed",
  6437. "error": str(exc),
  6438. }
  6439. if not args.json:
  6440. print("\nCaveman maintenance:")
  6441. print(
  6442. f"- state: {caveman_maintenance['state']}, "
  6443. f"action: {caveman_maintenance['plannedAction']}, "
  6444. f"status: {caveman_maintenance['status']}"
  6445. )
  6446. print_caveman_maintenance_details(caveman_maintenance)
  6447. sbtd_report = build_sbtd_project_setup(mode, args)
  6448. from sbtd_graft_deployment import execute_normal_wiring
  6449. wiring_result, wiring_exit = execute_normal_wiring(
  6450. wiring_plan, template_written=not bool(getattr(args, "skip_project_agents", False)),
  6451. )
  6452. language_tooling = run_language_tooling_step(mode, args)
  6453. if language_tooling is not None:
  6454. plan_payload["languageTooling"] = language_tooling
  6455. if wiring_plan["status"] != "skipped":
  6456. plan_payload["graftWiring"] = wiring_result
  6457. plan_payload["operationResults"] = operation_results
  6458. if wiring_exit:
  6459. wiring_status = "blocked" if wiring_exit == 2 else "failed"
  6460. for project in cast(list[dict[str, object]], sbtd_report["projects"]):
  6461. project.update(status=wiring_status, reason="host wiring did not complete", nextStep="Inspect the preserved wiring results and originals.")
  6462. sbtd_report["status"] = wiring_status
  6463. if args.json:
  6464. # One run, one root object. The plan was held back above so it can be
  6465. # merged here; flushing it earlier made stdout two concatenated
  6466. # documents, which `json.loads` rejects on every successful write mode.
  6467. #
  6468. # The plan keys stay at the root so `mode` sits in the same place for
  6469. # every mode -- `plan` and the check modes already answer there, and
  6470. # nesting only write modes would make `--json` a different contract
  6471. # depending on which mode produced it.
  6472. plan_json_emitted = True
  6473. print(
  6474. json.dumps(
  6475. {
  6476. **plan_payload,
  6477. "backups": [
  6478. {"target": str(target), "backup": str(backup)}
  6479. for target, backup in backups
  6480. ],
  6481. "sbtdProjectSetup": sbtd_report,
  6482. "cavemanMaintenance": caveman_maintenance,
  6483. "unverifiedChecks": list(UNVERIFIED_CHECKS),
  6484. },
  6485. indent=2,
  6486. ensure_ascii=False,
  6487. )
  6488. )
  6489. else:
  6490. print_sbtd_project_setup_report(sbtd_report)
  6491. if wiring_plan["status"] != "skipped":
  6492. print("Host wiring: " + str(wiring_result["status"]))
  6493. if wiring_result.get("hooks") == "configured-needs-host-trust":
  6494. print("Hooks configured only: enable supported Codex hooks and trust their exact hashes in the host before use.")
  6495. print("Host-event acceptance is separate from file and graph verification.")
  6496. if language_tooling is not None:
  6497. print_language_tooling(language_tooling)
  6498. if wiring_exit:
  6499. return wiring_exit
  6500. setup_exit = project_status_exit_code(sbtd_report["status"])
  6501. if setup_exit:
  6502. return setup_exit
  6503. if not args.json:
  6504. # `--json` promises one machine-readable document on stdout. Each note
  6505. # already went to stderr when it was recorded, and the JSON document
  6506. # carries `unverifiedChecks`, so nothing is lost by staying quiet here.
  6507. if UNVERIFIED_CHECKS:
  6508. print("Verification passed, except for checks that could not be evaluated:")
  6509. for item in UNVERIFIED_CHECKS:
  6510. print(f"- {item}")
  6511. else:
  6512. print("Verification passed.")
  6513. if mode == "init-projects":
  6514. print_projects_check_results(build_projects_check_results(args), False)
  6515. else:
  6516. final_check = build_check_results(args)
  6517. print_installation_report(
  6518. final_check["installationReport"], "Final installation report"
  6519. )
  6520. return 0
  6521. def build_parser() -> argparse.ArgumentParser:
  6522. parser = WorkflowArgumentParser(
  6523. description="Install or reset SBTD workflow AGENTS and skills."
  6524. )
  6525. subparsers = parser.add_subparsers(dest="mode", required=True)
  6526. add_migration_parser(subparsers)
  6527. add_recovery_parser(subparsers)
  6528. add_cleanup_legacy_parser(subparsers)
  6529. add_upgrade_parser(subparsers)
  6530. for mode in ("check", "plan", "init", "reset", "init-projects"):
  6531. sub = subparsers.add_parser(mode)
  6532. if mode in {"init", "init-projects"}:
  6533. _add_migration_context(sub)
  6534. sub.add_argument(
  6535. "--language-tooling",
  6536. action="store_true",
  6537. help="Apply the displayed omp LSP/ast-grep configuration writes after user confirmation; without it they are reported and skipped.",
  6538. )
  6539. sub.add_argument("--graft-hooks", action="store_true", help="Separately authorize the displayed Codex hooks; does not grant host trust.")
  6540. sub.add_argument(
  6541. "--no-mcp", action="store_true",
  6542. help="Skip user-level Graft MCP wiring; selected project graph setup remains local.",
  6543. )
  6544. sub.add_argument(
  6545. "--graft-retire-legacy",
  6546. action="store_true",
  6547. help="Explicitly replace exact owned fixed-project MCP entries for the selected roots; retain originals. Does not authorize environment or backup deletion.",
  6548. )
  6549. sub.add_argument(
  6550. "--graft-legacy-bindings",
  6551. action=SingleValueAction,
  6552. help="Private version-1 JSON contract naming observed old runtime paths for --graft-retire-legacy across runtime changes.",
  6553. )
  6554. sub.add_argument(
  6555. "--projects-root",
  6556. required=mode == "init-projects",
  6557. help="Comma-separated absolute project root paths.",
  6558. )
  6559. sub.add_argument(
  6560. "--developer",
  6561. action=SingleValueAction,
  6562. type=validate_developer_name,
  6563. help="Developer identity name (lowercase letters and digits) "
  6564. "applied only to the explicitly listed --projects-root projects.",
  6565. )
  6566. sub.add_argument(
  6567. "--skip-project-agents",
  6568. action="store_true",
  6569. help="Skip the project AGENTS template; explicitly selected Graft wiring still maintains its managed fence.",
  6570. )
  6571. sub.add_argument(
  6572. "--global-agents-path", help="Override Codex global AGENTS.md path."
  6573. )
  6574. sub.add_argument(
  6575. "--global-skills-dir", help="Override global skills directory."
  6576. )
  6577. sub.add_argument(
  6578. "--yes", action="store_true", help="Allow init/reset to write files."
  6579. )
  6580. sub.add_argument(
  6581. "--json", action="store_true", help="Print machine-readable plan."
  6582. )
  6583. sub.add_argument(
  6584. "--platform",
  6585. help="Target Agent platform: codex, claude, kimi, oh-my-pi, or omp.",
  6586. )
  6587. project_check = subparsers.add_parser("check-projects")
  6588. project_check.add_argument(
  6589. "--projects-root",
  6590. required=True,
  6591. help="Comma-separated absolute project root paths.",
  6592. )
  6593. project_check.add_argument(
  6594. "--json", action="store_true", help="Print machine-readable project checks."
  6595. )
  6596. project_check.add_argument(
  6597. "--skip-project-agents",
  6598. action="store_true",
  6599. help="Exclude project AGENTS.md from installation-target checks.",
  6600. )
  6601. graft_install = subparsers.add_parser("install-graft")
  6602. graft_install.add_argument(
  6603. "--yes", action="store_true",
  6604. help="Confirm the pinned global package/native-script and telemetry-disable plan.",
  6605. )
  6606. graft_install.add_argument(
  6607. "--telemetry-only", action="store_true",
  6608. help="Persist only telemetry opt-out; refuse package installation if the verified CLI is no longer present.",
  6609. )
  6610. graft_install.add_argument(
  6611. "--json", action="store_true", help="Print one machine-readable installation result."
  6612. )
  6613. install = subparsers.add_parser("install-external-skills")
  6614. install.add_argument(
  6615. "--skills",
  6616. help="Comma-separated external skill names to install. Use 'all' for every known external skill.",
  6617. )
  6618. install.add_argument(
  6619. "--all",
  6620. action="store_true",
  6621. help="Install every known external referenced skill.",
  6622. )
  6623. install.add_argument(
  6624. "--scope",
  6625. choices=("global",),
  6626. default="global",
  6627. help="Install into the global skills directory.",
  6628. )
  6629. install.add_argument(
  6630. "--source",
  6631. choices=("auto", "upstream", "stable"),
  6632. default="auto",
  6633. help=(
  6634. "External Skill source policy: auto and stable use the vendored stable set; "
  6635. "upstream is an explicit opt-in with no fallback."
  6636. ),
  6637. )
  6638. install.add_argument(
  6639. "--global-skills-dir", help="Override global skills directory."
  6640. )
  6641. install.add_argument(
  6642. "--replace",
  6643. action="store_true",
  6644. help="Compatibility flag; replacement now uses a temporary transactional rollback backup.",
  6645. )
  6646. install.add_argument(
  6647. "--yes", action="store_true", help="Allow external skill installation."
  6648. )
  6649. install.add_argument(
  6650. "--json", action="store_true", help="Print machine-readable plan and results."
  6651. )
  6652. migrate = subparsers.add_parser("migrate-external-skills")
  6653. migrate.add_argument(
  6654. "--scope",
  6655. choices=("global",),
  6656. default="global",
  6657. help="Migrate legacy external Skills in the global skills directory.",
  6658. )
  6659. migrate.add_argument(
  6660. "--source",
  6661. choices=("auto", "upstream", "stable"),
  6662. default="auto",
  6663. help=(
  6664. "Canonical replacement source: auto and stable use the vendored stable "
  6665. "set; upstream is an explicit opt-in with no fallback."
  6666. ),
  6667. )
  6668. migrate.add_argument(
  6669. "--global-skills-dir", help="Override global skills directory."
  6670. )
  6671. migrate.add_argument(
  6672. "--yes", action="store_true", help="Allow external Skill migration."
  6673. )
  6674. migrate.add_argument(
  6675. "--json", action="store_true", help="Print machine-readable migration results."
  6676. )
  6677. promote = subparsers.add_parser("promote-external-skills-stable")
  6678. promote.add_argument(
  6679. "--repository",
  6680. required=True,
  6681. help="Repository id from the stable External Skills manifest, or the new id for first-time registration.",
  6682. )
  6683. promote.add_argument(
  6684. "--repo",
  6685. help=(
  6686. "Upstream HTTPS repository URL. Required for first-time repository "
  6687. "registration; afterwards it may only repeat the manifest URL."
  6688. ),
  6689. )
  6690. promote.add_argument(
  6691. "--revision",
  6692. required=True,
  6693. help="Full 40-character lowercase upstream commit SHA to promote.",
  6694. )
  6695. promote.add_argument(
  6696. "--stable-set",
  6697. required=True,
  6698. help="New Onboard stable set identifier, for example 2026-07-11.2.",
  6699. )
  6700. promote.add_argument(
  6701. "--license",
  6702. help="SPDX license id; required only for first-time repository registration.",
  6703. )
  6704. promote.add_argument(
  6705. "--license-file",
  6706. dest="license_files",
  6707. action="append",
  6708. help=(
  6709. "License mapping SOURCE=STABLE_PATH, repeatable; required only for "
  6710. "first-time repository registration."
  6711. ),
  6712. )
  6713. promote.add_argument(
  6714. "--yes", action="store_true", help="Allow stable snapshot replacement."
  6715. )
  6716. promote.add_argument(
  6717. "--json", action="store_true", help="Print machine-readable plan and results."
  6718. )
  6719. npm = subparsers.add_parser("ensure-npm")
  6720. npm.add_argument(
  6721. "--yes",
  6722. action="store_true",
  6723. help="Install nvm and Node.js LTS when npm is missing.",
  6724. )
  6725. npm.add_argument(
  6726. "--json", action="store_true", help="Print machine-readable results."
  6727. )
  6728. agent_check = subparsers.add_parser("check-agent-cli")
  6729. agent_check.add_argument(
  6730. "--platform",
  6731. required=True,
  6732. help="Target Agent platform: codex, claude, kimi, oh-my-pi, or omp.",
  6733. )
  6734. agent_check.add_argument(
  6735. "--json", action="store_true", help="Print machine-readable results."
  6736. )
  6737. agent_install = subparsers.add_parser("install-agent-cli")
  6738. agent_install.add_argument(
  6739. "--platform",
  6740. required=True,
  6741. help="Target Agent platform: codex, claude, kimi, oh-my-pi, or omp.",
  6742. )
  6743. agent_install.add_argument(
  6744. "--yes",
  6745. action="store_true",
  6746. help="Install the target Agent CLI globally from its official npm package after user confirmation.",
  6747. )
  6748. agent_install.add_argument(
  6749. "--json", action="store_true", help="Print machine-readable results."
  6750. )
  6751. rtk = subparsers.add_parser("install-rtk")
  6752. rtk.add_argument(
  6753. "--yes", action="store_true", help="Install rtk-ai/rtk when missing."
  6754. )
  6755. rtk.add_argument(
  6756. "--replace-wrong",
  6757. action="store_true",
  6758. help="If an existing rtk command fails `rtk gain`, allow replacing it after user confirmation.",
  6759. )
  6760. rtk.add_argument(
  6761. "--reinstall",
  6762. action="store_true",
  6763. help="Reinstall when rtk exists but `rtk gain` verification fails.",
  6764. )
  6765. rtk.add_argument(
  6766. "--profile", help="Shell profile file to update with ~/.local/bin PATH."
  6767. )
  6768. rtk.add_argument(
  6769. "--json", action="store_true", help="Print machine-readable results."
  6770. )
  6771. caveman = subparsers.add_parser("install-caveman")
  6772. caveman.add_argument(
  6773. "--agent",
  6774. default="codex",
  6775. help="Retained for compatibility; the official caveman installer selects the platform-specific install path.",
  6776. )
  6777. caveman.add_argument(
  6778. "--global-skills-dir",
  6779. help="Override global skills directory used for post-install verification.",
  6780. )
  6781. caveman.add_argument(
  6782. "--yes",
  6783. action="store_true",
  6784. help="Install the caveman Codex skill after user confirmation.",
  6785. )
  6786. caveman.add_argument(
  6787. "--json", action="store_true", help="Print machine-readable results."
  6788. )
  6789. java = subparsers.add_parser("install-java")
  6790. java.add_argument(
  6791. "--major",
  6792. type=int,
  6793. default=21,
  6794. help="Temurin JDK major version to install. Must be 17 or higher; defaults to 21.",
  6795. )
  6796. java.add_argument(
  6797. "--install-root",
  6798. help="Directory that should contain the extracted Temurin JDK.",
  6799. )
  6800. java.add_argument(
  6801. "--profile", help="Shell profile file to update with JAVA_HOME and PATH."
  6802. )
  6803. java.add_argument(
  6804. "--force",
  6805. action="store_true",
  6806. help="Install even when an existing Java 17+ runtime is already available.",
  6807. )
  6808. java.add_argument(
  6809. "--yes",
  6810. action="store_true",
  6811. help="Download and install the selected Temurin JDK after user confirmation.",
  6812. )
  6813. java.add_argument(
  6814. "--json", action="store_true", help="Print machine-readable results."
  6815. )
  6816. maestro = subparsers.add_parser("install-maestro")
  6817. maestro.add_argument(
  6818. "--profile", help="Shell profile file to update with ~/.maestro/bin PATH."
  6819. )
  6820. maestro.add_argument(
  6821. "--reinstall",
  6822. action="store_true",
  6823. help="Run the official installer even when a maestro command already exists but fails verification.",
  6824. )
  6825. maestro.add_argument(
  6826. "--yes",
  6827. action="store_true",
  6828. help="Run the official Maestro installer after user confirmation.",
  6829. )
  6830. maestro.add_argument(
  6831. "--json", action="store_true", help="Print machine-readable results."
  6832. )
  6833. playwright = subparsers.add_parser("install-playwright-cli")
  6834. playwright.add_argument(
  6835. "--project-root",
  6836. required=True,
  6837. help="Target project root where package.json exists.",
  6838. )
  6839. playwright.add_argument(
  6840. "--reinstall",
  6841. action="store_true",
  6842. help="Run npm install even when Playwright project markers already exist.",
  6843. )
  6844. playwright.add_argument(
  6845. "--skip-browsers",
  6846. action="store_true",
  6847. help="Install @playwright/test but skip `npx playwright install`.",
  6848. )
  6849. playwright.add_argument(
  6850. "--yes",
  6851. action="store_true",
  6852. help="Install Playwright into the target project after user confirmation.",
  6853. )
  6854. playwright.add_argument(
  6855. "--json", action="store_true", help="Print machine-readable results."
  6856. )
  6857. return parser
  6858. def main() -> int:
  6859. parser = build_parser()
  6860. args = parser.parse_args()
  6861. if args.mode == "migration":
  6862. validate_migration_args(args, parser=parser)
  6863. elif args.mode == "recovery":
  6864. validate_recovery_args(args, parser=parser)
  6865. elif args.mode == "cleanup-legacy":
  6866. validate_cleanup_legacy_args(args, parser=parser)
  6867. elif args.mode == "upgrade":
  6868. validate_upgrade_args(args, parser=parser)
  6869. elif args.mode in {"init", "init-projects"}:
  6870. _check_migration_context(parser, args)
  6871. return run(args.mode, args)
  6872. if __name__ == "__main__":
  6873. raise SystemExit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.