mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
feat: vendor permission system source
This commit is contained in:
云服务部-叶林立
@@ -0,0 +1,124 @@
|
||||
---
|
||||
issue: 508
|
||||
issue_title: "fix: bash external_directory gate misses Windows drive-letter absolute paths"
|
||||
---
|
||||
|
||||
# Retro: #508 — fix: bash external_directory gate misses Windows drive-letter absolute paths
|
||||
|
||||
## Stage: Planning (2026-06-27T00:00:00Z)
|
||||
|
||||
### Session summary
|
||||
|
||||
Planned the fix for the bash `external_directory` gate missing Windows drive-letter absolute paths (`C:/…` and `C:\…`).
|
||||
The operator's questions drove the scope progressively deeper: from "which classifier(s)" → "detect the platform?"
|
||||
→ "what makes this change easy (Kent Beck)?"
|
||||
→ "is there an architectural root cause?".
|
||||
The investigation surfaced that the package has a half-threaded, ambient platform dependency (`process.platform` and the host-bound `node:path` import read in ~6 interior modules), which is the real root cause behind the recurring Windows-path bugs.
|
||||
Filed that as a separate architecture issue, #510, and rebased #508's plan to land on #510's clean seam.
|
||||
|
||||
### Observations
|
||||
|
||||
- **Scope decisions (via `ask_user`).**
|
||||
Confirmed: recognize both separator forms in *both* classifiers (not just the strict one); detect drive paths by a drive-letter prefix regex (`/^[a-zA-Z]:[/\\]/`), not "any backslash"; keep gating drive-shaped tokens on POSIX (do not warn/drop — dropping would *reduce* POSIX `path`-surface coverage of the real in-CWD `./C:/foo` access).
|
||||
- **No `process.platform` branch.**
|
||||
The platform-sensitive decision ("is `C:/foo` absolute?") already lives in `node:path` (`path.win32` vs `path.posix`).
|
||||
Shape recognition is platform-independent string matching; absoluteness delegates to the injected flavor.
|
||||
This satisfies the package's own `code-design` rule against reading `process.platform` in utility functions.
|
||||
- **Architectural root cause → #510.**
|
||||
`path-utils.ts` `isPathWithinDirectory` and `rule.ts` already use an injectable `platform: NodeJS.Platform = process.platform` parameter (with the testability rationale in the doc comment), but the seam was never threaded end-to-end: `normalizePathForComparison` hard-codes `process.platform` inline, `canonicalizePath` / `AccessPath.forPath` take no flavor, and `cwd-projection.ts` imports host-bound `node:path` and hand-rolls `startsWith("/")`.
|
||||
Threading an injected `PathSemantics`/platform flavor through the pipeline is the structural correction that makes #382/#345/#418/#508 and future Windows forms (UNC, `\\?\`, drive-relative) a single-home change.
|
||||
- **Sequencing (operator choice).**
|
||||
Refactor first (#510), then rebase #508 onto the clean seam.
|
||||
On that seam #508 collapses to: add the drive-letter shape to the classifiers; the `isRelativeCandidate` → injected `isAbsolute` conversion and the win32 testability both belong to #510 (no `vi.mock("node:path")`).
|
||||
- **Tidy-first insight.**
|
||||
The naive classifier-only fix would briefly over-flag an inside-CWD drive path under an unknown `cd` base (a Windows-absolute path mislabeled "relative" by the hand-rolled check). #510's `isAbsolute` delegation eliminates that window, so #508 needs no transient cleanup.
|
||||
- **`#509`** is the sibling issue (bare-filename `path`-surface bypass) split from the same parent #494 — explicitly out of scope here.
|
||||
|
||||
## Stage: Planning refresh — post-#510/#511 (2026-06-28T00:00:00Z)
|
||||
|
||||
### Session summary
|
||||
|
||||
## 510 and #511 are closed; the platform/path-semantics seam landed as `PathNormalizer` (`src/path-normalizer.ts`), and the old `cwd-projection.ts` is now the class-based `bash-path-resolver.ts` holding `this.normalizer`
|
||||
|
||||
Refreshed the #508 plan from its abstract "injected flavor" wording to the concrete API and confirmed the scope reduction the plan anticipated.
|
||||
|
||||
### Observations
|
||||
|
||||
- **#510 deferred the `isRelativeCandidate` conversion**, exactly the contingency the original plan flagged. `foldCd` already delegates to `this.normalizer.isAbsolute`, but the module-level free function `isRelativeCandidate` (`bash-path-resolver.ts`, two call sites: `projectExternalPaths`, `buildRuleCandidatePath`) still hand-rolls `!startsWith("/") && !startsWith("~")`. #508 folds in converting it to a private method delegating to `this.normalizer.isAbsolute` — load-bearing, since the projection's relative/unknown decision (not just `foldCd`) gates the over-flag.
|
||||
- **Testability is clean as predicted.** `BashProgram.parse(command, normalizer)` and `extractExternalPathsFromBashCommand(command, normalizer)` take a `PathNormalizer`; `bash-external-directory.test.ts` already builds `new PathNormalizer(process.platform, cwd)`. #508's Windows assertions construct `new PathNormalizer("win32", cwd)` — no `vi.mock("node:path")`.
|
||||
- **#508 now reduces to two production edits + docs**: drive-shape recognition in both classifiers (`token-classification.ts`, unchanged by #510) and the `isRelativeCandidate` conversion (`bash-path-resolver.ts`).
|
||||
Single `fix:` commit + `docs:` commit.
|
||||
- Next step: `/tdd-plan`.
|
||||
|
||||
## Stage: Implementation — TDD (2026-06-28T20:15:00Z)
|
||||
|
||||
### Session summary
|
||||
|
||||
Completed 2 TDD cycles in a single session: (1) the core `fix:` commit adding `WINDOWS_DRIVE_PATH_PATTERN` to both classifiers and converting `isRelativeCandidate` to a private method delegating to `this.normalizer.isAbsolute`; (2) the `docs:` commit updating `architecture.md` and `SKILL.md`.
|
||||
Test count went from 2195 to 2211 (+16 tests: 8 new classifier unit tests and 4 new win32 end-to-end assertions across 2 test files).
|
||||
Pre-completion reviewer returned **PASS**.
|
||||
|
||||
### Observations
|
||||
|
||||
- **`isRelativeCandidate` edit required three partial attempts** due to the decorator rule line (`──`) in `bash-path-resolver.ts` — the Unicode box-drawing characters miscount when anchoring `oldText`, causing atomic batch rejections.
|
||||
Resolved by anchoring on adjacent unique code lines rather than the rule itself (as AGENTS.md warns), and by splitting the class-closing brace into a separate edit from the rule line.
|
||||
- **The unknown-base win32 test passed green before the implementation** (tokens were dropped → empty result), so it was not a red test in the strict sense.
|
||||
After the fix it stays green for the correct reason (inside-CWD check fires).
|
||||
This is expected for the "over-flag prevention" path — the red test for the over-flag scenario would require a Windows absolute path that is *outside* CWD under an unknown base, but the plan test chose inside-CWD to exercise the conversion specifically.
|
||||
No deviation: the test does cover the `isRelativeCandidate` routing change as documented in the test comment.
|
||||
- **`c://x` URL rejection confirmed**: the `URL_PATTERN` (`/^[a-z][a-z0-9+.-]*:\/\//i`) fires before the drive pattern for single-letter schemes with `//`, so there is no ambiguity between the URL guard and the new drive pattern.
|
||||
- **Pre-completion reviewer verdict**: PASS.
|
||||
All deterministic checks, invariants, and doc surfaces clean.
|
||||
|
||||
## Stage: Final Retrospective (2026-06-29T01:00:00Z)
|
||||
|
||||
### Session summary
|
||||
|
||||
Shipped #508 cleanly: pushed the two commits, CI green, closed the issue, and merged release-please PR #514 to cut `pi-permission-system-v17.1.1`.
|
||||
This closes a four-stage arc (Planning → Planning refresh → TDD → Ship) in which operator-driven Socratic questioning during planning turned a one-line hand-rolled fix into a clean fix layered on a properly-threaded `PathNormalizer` seam (#510), with #511 as a follow-up.
|
||||
|
||||
### Observations
|
||||
|
||||
#### What went well
|
||||
|
||||
- **Operator-driven architectural depth (planning).**
|
||||
The progressive questioning — "which classifier?"
|
||||
→ "detect the platform?"
|
||||
→ "what makes this change easy?"
|
||||
→ "is there an architectural root cause?"
|
||||
— surfaced the half-threaded ambient-platform dependency and produced #510 / #511.
|
||||
Without it, #508 would have shipped a hand-rolled `startsWith("/")` check that drifts from `node:path` and a fragile `vi.mock("node:path")` test.
|
||||
Strategic judgment applied at exactly the right moment.
|
||||
- **Plan contingency foresight paid off.**
|
||||
The original plan flagged "if #510 defers the `isRelativeCandidate` conversion, fold it into #508." #510 did defer it; the Planning-refresh stage confirmed the contingency and folded it in with zero rework.
|
||||
- **Ship-flow `IN_PROGRESS`-check handling worked as designed.**
|
||||
Release-please PR #514 returned `UNSTABLE` with a CI check still `IN_PROGRESS`.
|
||||
The session polled `statusCheckRollup` until `SUCCESS` and then merged via `release_pr_merge`, rather than falling back to `gh pr merge` while a check was running — exactly the `/ship-issue` step-6.4 refinement.
|
||||
The refined instruction prevented a premature merge.
|
||||
- **Clean TDD execution.**
|
||||
Two cycles, +16 tests, pre-completion PASS, no follow-up fixups.
|
||||
|
||||
#### What caused friction (agent side)
|
||||
|
||||
- `other` — the `isRelativeCandidate` edit needed three attempts because `oldText` spanned the `──` decorator rule line in `bash-path-resolver.ts`; the Unicode box-drawing run miscounts and rejected the atomic batch.
|
||||
Impact: two extra `Edit` calls, no rework — resolved by anchoring on adjacent code lines, which is exactly what AGENTS.md already prescribes.
|
||||
The rule exists and is crisp; this was a first-attempt-application slip, not a missing rule.
|
||||
- `other` — the unknown-base win32 test passed green before implementation (the token was dropped upstream → empty result), so it was not a strict red test for the over-flag path.
|
||||
Impact: none — documented in the test comment and the TDD stage notes; a true red test for over-flag would need an outside-CWD drive path under an unknown base.
|
||||
This is a manifestation of the existing package-SKILL rule ("trace the token through the classifier first"), already covered.
|
||||
|
||||
#### What caused friction (user side)
|
||||
|
||||
- None.
|
||||
Operator involvement was strategic (planning depth, sequencing choice, scope confirmation via `ask_user`), not mechanical oversight.
|
||||
|
||||
### Considered but not proposed
|
||||
|
||||
- No `AGENTS.md` change for the decorator-line edit trap — the rule already exists and is crisp; adding salience text to an already-dense file would not improve first-attempt recall.
|
||||
- No `testing`-skill change for the green-before-red test — the package SKILL's "trace the token through the classifier first" already covers the underlying principle.
|
||||
- No `/ship-issue` change — the `IN_PROGRESS` refinement worked; nothing to add.
|
||||
|
||||
### Changes made
|
||||
|
||||
1. Added this Final Retrospective stage entry to `packages/pi-permission-system/docs/retro/0508-bash-external-directory-windows-drive-letter.md`.
|
||||
2. No `AGENTS.md`, prompt, or skill changes — operator confirmed retro-only; existing rules covered every friction point.
|
||||
Reference in New Issue
Block a user