feat(M4): Reusable code abstractions and dead-code removal

2026-05-03 21:45:49 -05:00
parent 86ad783f82
commit 7495020a9c
98 changed files with 1696 additions and 950 deletions
@@ -396,3 +396,78 @@ No Docker/Ubuntu run was available at M2 capture time. The portability
 fix (`portable_stat_perms`) replaces the only identified BSD-ism. The
 Ubuntu Docker command is documented in
 [DEVELOPMENT.md](./DEVELOPMENT.md#cross-platform-shell-support-m2).
+
+---
+
+## Post-M4 state
+
+Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
+
+M4 extracted reusable abstractions, consolidated shared helpers, tightened
+types, and removed the legacy dead-code path.  `pnpm run check` remains fully
+green.
+
+### `pnpm run check` aggregate (post-M4)
+
+```text
+PASS  lint
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs
+PASS  verify:generated
+```
+
+Overall exit: **0** — all checks green (no regressions from M3).
+
+### What changed in M4
+
+- **S-401** — `scripts/lib/safe-replace-dir.mjs` added: Node.js helper that
+  validates a target is a strict descendant of a safety root before replacing
+  it.  Thin shell wrapper `scripts/lib/safe-replace-dir.sh` provided for
+  sourcing in shell scripts.  `scripts/sync-pi-package-skills.sh` updated to
+  use `safe_replace_dir` from the shared helper (inline `replace_dir` removed).
+
+- **S-402** — `removeTarget(op)` extracted from `executeOperation()` in
+  `scripts/lib/skill-manager-core.mjs` and exported.  The helper handles
+  skill, helper, and symlink removal with idempotent semantics.
+  `executeOperation` now delegates to `removeTarget` for all remove branches.
+
+- **S-403** — `skills/atlassian/shared/scripts/src/command-helpers.ts` added
+  with `dryRunResponse<T>()` and `resolveFormat()` helpers.  `confluence.ts`,
+  `jira.ts`, and `raw.ts` consume `dryRunResponse` (8 inline objects removed).
+  `cli.ts` imports `resolveFormat` from `command-helpers` instead of defining
+  it locally.  All atlassian agent variants regenerated.
+
+- **S-404** — `skills/web-automation/shared/lib/browser.ts` created with
+  `getProfilePath`, `launchBrowser`, and `getPage`.  `browse.ts` imports and
+  re-exports them.  `auth.ts`, `flow.ts`, and `scan-local-app.ts` now import
+  directly from `lib/browser.js`.  Generator updated to include `lib/`
+  directory in `scriptFiles` for web-automation variants.  `tsconfig.json`
+  updated to include `lib/**/*.ts`.
+
+- **S-405** — `scan-local-app.ts` `page: any` parameters replaced with
+  `Page` from `playwright-core`.  Added `GotoError` discriminated type to
+  narrow the `page.goto().catch()` union type safely.
+
+- **S-406** — `scripts/sync-pi-package-skills.sh` deleted (retired in M3,
+  inline `replace_dir` migrated to shared helper as part of S-401).  Comment
+  in `skill-manager-core.mjs` referencing the deleted file updated.
+  Generator's `clearGeneratedRoot` fixed to preserve `node_modules` at all
+  depths (was only protected at root level, causing pnpm workspace packages
+  inside `scripts/` subdirs to lose their node_modules on regeneration).
+
+- **S-407** — Tests added:
+  - `scripts/tests/safe-replace-dir.test.mjs` (6 tests for S-401 helper)
+  - `scripts/tests/skill-manager-core-remove.test.mjs` (5 tests for S-402)
+  - `skills/atlassian/shared/scripts/tests/command-helpers.test.ts` (7 tests
+    for S-403 `dryRunResponse` and `resolveFormat`)
+
+### Test count (post-M4)
+
+| Suite | Tests |
+|---|---|
+| `pnpm run test:installer` (root scripts) | 80 |
+| `atlassian/shared/scripts` | 29 |
+| **Total** | **109** |