diff --git a/CHANGELOG.md b/CHANGELOG.md index 058d78dccd..5e812b120f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,35 @@ +## [1.4.1+mas.1] - 2026-11-16 + +MAS fork release based on upstream Spec Kit 1.4.1. Package version uses the local `+mas.N` convention; Git tags for this fork remain `vX.Y.Z-mas.N`. + +## [1.4.1] - 2026-11-16 + +### Changed + +- Add Elephant-Goldfish Model extension to community catalog (#5444) +- Add Spec Kit lifecycle for Jira extension to community catalog (#5438) +- [preset] Add OKR Bet Spec Section preset to community catalog (#5439) +- Add Multi-Repo Workspace Orchestration extension to community catalog (#5436) +- fix(powershell): treat bracketed project paths literally in the git extension (#5404) +- fix(powershell): treat bracketed project paths literally in create-new-feature (#5399) +- fix(powershell): treat project and preset template paths literally (#5396) +- docs(extensions): list the converge hook events (#5328) +- [extension] Add OKR Bets extension to community catalog (#5412) +- Update T-Shirt Sizing Gate extension to v0.2.0 (#5407) +- Update Intake Sequencing Governance preset to v0.2.13 (#5406) +- fix(workflows): expose bundled review verdict inputs (#5392) +- Update Intake Review Governance preset to v0.2.8 (#5388) +- fix(integrations): honor shared refresh for installed targets (#5377) +- Update ado-lifecycle to 0.3.2 (#5345) +- Use handle-based deletion in FileHelper (#5352) +- [extension] Add A·I·DID·IT — Agile Expansion Pack extension to community catalog (#5375) +- Update DocGuard — CDD Enforcement to v0.47.0 (#5374) +- Update Intake Authoring Governance preset to v0.3.12 (#5372) +- chore: release 1.4.0, begin 1.4.1.dev0 development (#5371) + ## [1.4.0] - 2026-11-10 ### Changed diff --git a/bundles/bugfix/README.md b/bundles/bugfix/README.md index 9315568abc..57ad60ba07 100644 --- a/bundles/bugfix/README.md +++ b/bundles/bugfix/README.md @@ -29,6 +29,19 @@ specify workflow run bugfix \ Required inputs must be supplied with `--input`: `report` and `slug`. The slug is used as the working directory under `.specify/bugs//` for all artifacts. +Without an interactive terminal, the run pauses at `review-assessment`. Review +the assessment, then approve it using the optional verdict input: + +```bash +specify workflow resume --input bug_review_assessment_verdict=approve +``` + +`bug_review_assessment_verdict` defaults to `""`. Omitting it or supplying an +empty value preserves the existing interactive prompt or non-interactive pause. +This input is available in `bugfix` workflow version 1.0.1 and requires Specify +CLI 0.15.1 or later. Update the workflow and start a new run to use the input; +existing runs retain the definition saved when they started. + ## Remove ```bash diff --git a/bundles/bugfix/bundle.yml b/bundles/bugfix/bundle.yml index 87a92a3d1c..03848d1a49 100644 --- a/bundles/bugfix/bundle.yml +++ b/bundles/bugfix/bundle.yml @@ -3,14 +3,14 @@ schema_version: "1.0" bundle: id: "bugfix" name: "Guided Bug Fix" - version: "1.0.2" + version: "1.0.3" role: "developer" description: "Orchestrated bug triage: assess a bug report, review the assessment behind a human gate, apply the fix, and verify it with tests." author: "GitHub" license: "MIT" requires: - speckit_version: ">=0.9.0" + speckit_version: ">=0.15.1" tools: [] mcp: [] @@ -20,6 +20,6 @@ provides: version: "1.0.2" workflows: - id: "bugfix" - version: "1.0.0" + version: "1.0.1" tags: ["bug", "triage", "workflow", "qa"] diff --git a/bundles/catalog.json b/bundles/catalog.json index 6d2e70d16f..50c1007599 100644 --- a/bundles/catalog.json +++ b/bundles/catalog.json @@ -1,12 +1,12 @@ { "schema_version": "1.0", - "updated_at": "2026-09-10T00:00:00Z", + "updated_at": "2026-11-11T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/catalog.json", "bundles": { "bugfix": { "id": "bugfix", "name": "Guided Bug Fix", - "version": "1.0.2", + "version": "1.0.3", "role": "developer", "description": "Orchestrated bug triage: assess a bug report, review behind a human gate, apply the fix, and verify with tests.", "author": "GitHub", @@ -14,7 +14,7 @@ "download_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/bugfix/bundle.yml", "repository": "https://github.com/github/spec-kit", "requires": { - "speckit_version": ">=0.9.0" + "speckit_version": ">=0.15.1" }, "provides": { "extensions": 1, diff --git a/design/catalogs.md b/design/catalogs.md index ff8b42cd41..66d4b82e63 100644 --- a/design/catalogs.md +++ b/design/catalogs.md @@ -204,7 +204,10 @@ Current behavior differs by primitive: sources fetch repository catalogs when online and fall back to packaged snapshots only for catalog-unavailable failures; malformed or unsafe content is not masked by the snapshot. Bundle stacks memoize parsed payloads for the - lifetime of one stack instance. + lifetime of one stack instance. When translating an HTTP status error, the + fetcher closes its response body before propagating the catalog error, while + retaining the original exception as its cause and preserving status-based + fallback classification. A future shared fetch boundary may share URL validation, redirect validation, bounded reads, cache records, and error types. It must preserve each diff --git a/design/file-helper.md b/design/file-helper.md index 77ee80fc4a..6fad90eb33 100644 --- a/design/file-helper.md +++ b/design/file-helper.md @@ -67,7 +67,9 @@ the policy. `specify_cli._project.resolve_specify_project_files()` performs the normal existing-project resolution and returns the same handoff for new CLI adapters. Commands using another established root call `project_files` on their actually selected root. Retain a helper only for the current operation; -a later invocation resolves a new helper, so manual edits take effect. +a later invocation resolves a new helper, so manual edits take effect. Use the +returned owner as a context manager, or call `close()` in the owner's cleanup +path, to release retained root handles at that operation boundary. The `specify_cli.integration_state` helpers are an explicit managed-metadata exception to this handoff. Their reads and writes of `.specify/integration.json` @@ -101,12 +103,12 @@ existing lifecycle rollback, including prior policy and unrelated options. ```python from specify_cli.file_helper import FileHelper -files = FileHelper(project_root) # deny symlinks by default -files.mkdir("generated", exist_ok=True) -files.create_text("generated/config.txt", "initial\n") -files.write_text("generated/config.txt", "updated\n") -content = files.read_text("generated/config.txt") -files.delete("generated", recursive=True) +with FileHelper(project_root) as files: # deny symlinks by default + files.mkdir("generated", exist_ok=True) + files.create_text("generated/config.txt", "initial\n") + files.write_text("generated/config.txt", "updated\n") + content = files.read_text("generated/config.txt") + files.delete("generated", recursive=True) ``` ## Boundary and policy @@ -144,6 +146,66 @@ any followed target hierarchy. An unrelated project symlink does not prevent an operation. A helper cannot cross to another root; callers establish separate helpers for independent project/source/managed boundaries. +On supported deletion backends, construction retains a handle to the canonical +root until `close()` or context-manager exit. Keeping the original directory open +prevents its identity from being reused for a different directory while the +helper is alive; stored device/inode numbers alone are not the binding. On POSIX, +the handle uses search-only access where available. On Windows, construction +requests only root metadata access (`FILE_READ_ATTRIBUTES`) and permits delete +sharing; it does not request directory-list access on the canonical ancestors. +The retained reference selects a tagged identity scheme from that handle. +The full 128-bit `FileIdInfo` identity is preferred. If that query reports +`ERROR_INVALID_FUNCTION`, `ERROR_NOT_SUPPORTED`, or `ERROR_INVALID_PARAMETER`, +or returns an all-zero ID, the helper queries the opened volume's filesystem +and uses `GetFileInformationByHandle`'s volume serial plus nonzero 64-bit file +index only for FAT, FAT32, exFAT, or NTFS. The volume query is handle-relative +and works through the filesystem driver rather than a pathname-based volume +lookup, including when a network driver exposes the necessary information. +ReFS and unrecognized filesystems do not fall back to potentially ambiguous +64-bit indexes. Access-denied, sharing, and other unrelated errors still +propagate rather than selecting a weaker identity. +Before accepting it, construction compares Python-native metadata obtained from +the acquired handle with the initially observed root metadata. This comparison +does not reopen the root pathname, so replacement followed by restoration cannot +substitute a different retained object. The metadata query uses a temporary +non-inheritable duplicate and leaves the original reference open. +If that reference or identity query is unavailable, the native capability error +is deferred to `delete()` rather than preventing ordinary read/write operations. +The cached error remains traceback-free; each failed deletion raises an +independent shallow copy retaining the native error type and filesystem details. + +Windows deletion separately pins the canonical ancestry through the drive/share +root without delete sharing, then queries both that root handle and the retained +reference using the already selected scheme. It compares their live identities, +not a cached legacy index: FAT IDs can change after renaming. It neither +renegotiates identity schemes mid-operation nor compares identities from +different schemes. Those operation-time handles require both +`FILE_LIST_DIRECTORY` and `FILE_READ_ATTRIBUTES` on every canonical ancestor, +including those above the helper root, and reject reparse points. An ACL allowing +traversal but not listing can therefore prevent deletion while still allowing +bootstrap reads. Windows deletion also retains non-reparse handles to accessed +parent directories throughout link resolution, before classifying child entries +or reading link targets. Each child is opened relative to its native parent +handle, not by reconstructing an absolute pathname. Metadata and symbolic-link +targets are read from opened leaf handles; directory names are enumerated from +the directory handle. Relative native opens request both +`FILE_SYNCHRONOUS_IO_NONALERT` and `SYNCHRONIZE`, including directories, so +enumeration cannot consume a buffer before a pending directory query completes. +These accessed directories also require +directory-list/read-attribute access. The resolution handles are released after +selection; native mutation parents and root ancestry remain retained during +preflight and removal. Directory sharing locks alone do not prevent in-place +reparse changes: handle-relative operations retain the opened directory object +instead of following its changed pathname. These locks are released at the end of +deletion; the metadata-only reference remains until the helper closes. Automatic +finalization is a compatibility fallback, not a substitute for deterministic +cleanup. Bootstrap configuration and managed integration-state consumers close +their own helpers explicitly. Installed-workflow listing also closes its +`project_files()` owner on every validation, registry-read, and successful exit; +other consumers receiving `project_files()` own its lifetime. +Pinning the root does not make other pathname-based operations +descriptor-relative or change their documented concurrency limitations. + | Operation | Default deny | Explicit allow | |---|---|---| | Read file | Reject accessed parent or leaf links | Follow only existing contained regular-file targets | @@ -158,6 +220,9 @@ helpers for independent project/source/managed boundaries. ## API and failures +- `close()` releases the helper's retained root handles and is idempotent. + `with FileHelper(...) as files:` closes on both success and failure. Operations + on an explicitly closed helper raise `FileHelperError`. - `mkdir(path, parents=False, exist_ok=False)` creates directories. - `read_bytes(path)` / `read_text(path, encoding="utf-8")` read regular files. - `create_bytes(path, content, mode=0o644)` / `create_text(...)` exclusively @@ -224,7 +289,58 @@ helpers for independent project/source/managed boundaries. the attributes of an existing file. - `delete(path, recursive=False)` unlinks files/links or removes directories. Nonrecursive directory deletion requires an empty directory. The established - root cannot be deleted. + root cannot be deleted. Recursive enumeration and each removal use anchored + directories. Each deletion borrows the root handle retained at construction, + checks the currently named root for replacement, and uses that original anchor through + preflight and all removals. POSIX uses this retained root for component + classification, link-target reads and resolution, recursive preflight, and + per-entry revalidation, as well as descriptor-relative enumeration and + `unlink`/`rmdir`. Canonical pathnames identify root-relative entries but are not + reopened for metadata or link resolution. Windows verifies the full canonical + ancestry during root acquisition and then carries native directory handles + through child opens, metadata queries, link-target reads, and enumeration. + Removal opens the leaf itself with `DELETE` access and marks that same handle + with `FileDispositionInfo`; it does not call pathname `unlink` or `rmdir`. + This does not change the trusted treatment of aliases resolved + at root establishment. Allowed contained parent links are resolved within the + retained boundary, and leaf links are still unlinked rather than followed. + Platforms lacking the required directory-descriptor operations fail with + `ENOTSUP`, not pathname-only deletion. + POSIX traversal and removal use search/path-only descriptors (`O_SEARCH` or + `O_PATH`) where available, including Darwin's native `O_SEARCH` value on Python + builds that do not expose it, so known entries in write-and-execute-only parents + can still be removed. Read-capable descriptors are requested only for directories + being enumerated; systems without search/path-only flags retain read-capable + traversal. Recursive enumeration still requires directory read permission, and + removal still requires the operating system's normal directory permissions. + Preflight opens the enumerated child directly as readable, relative to its + anchored parent, without a search-only open or `"."` reopening first. An empty + readable directory therefore does not need its own search permission to be + removed; accessing children in a nonempty directory still requires search + permission. The parent still needs the permissions required to remove its + directory entry. + On systems using the read-capable fallback, root establishment also requires + read permission on the root. + POSIX component resolution and final parent anchoring retain only the current + traversal descriptor, opening its child before releasing the preceding one. + Their live descriptor count is bounded independently of operation-path depth, + in addition to the helper's retained root. Link-target jumps and `..` are + re-anchored through that root rather than following an opened directory's + physical parent after a rename. Windows retains native directory handles for + its child-relative traversal, including during recursive preflight and removal. + POSIX recursive preflight and mutation use explicit worklists and separate + eight-directory handle caches. The selected parent and established root remain + anchored outside those caches. An uncached parent is reacquired component by + component from the nearest retained prefix with no-follow flags, releasing + least-recently-used handles as the cache fills. Removed directories are evicted, + and preflight handles are not reused for mutation. Live descriptors are bounded + independently of recursive depth, including transient opens and enumeration; + worklist and complete-plan memory still scale with the selected tree. + Reacquiring evicted prefixes trades additional opens for that fixed handle + budget. Total opens can grow with the sum of visited path lengths, rather than + being unconditionally linear in the directory count. Windows retains its + native-handle traversal instead of evicting handles needed for child-relative + operations. The complete plan is still preflighted before any removal. - `symlink(target, path)` creates a link exclusively. Relative targets are interpreted relative to the link parent, not the helper root. @@ -283,11 +399,23 @@ substituted symlink. This does not freeze file contents against in-place edits. Preflight detects static policy failures before recursive deletion or parent creation. Atomic writes recheck the original path before replacement, and -deletion rechecks each accessed entry. No operation is a general race-free -sandbox. For operations that still use validated paths, another process can -exchange parents or entries between checks and syscalls. An I/O failure during -any mutation can leave partial results. Protect against concurrent untrusted -mutation separately. +deletion rechecks each accessed entry. Deletion also anchors directory +enumeration and removal so exchanging an accessed parent for a link cannot +redirect those operations. Reopening the absolute root pathname for each entry is +avoided; the established root handle is never rebound to a replacement, even if +device/inode values are reused. POSIX removal stays attached to +the opened directory even if that directory is renamed; validation continues to +inspect that same directory tree. Windows prevents ancestor renames while handles +are held. Concurrent changes may still cause deletion to fail or leave +partial results, and preflight is not a transaction or an immutable tree snapshot. +POSIX leaf removal acts on the current entry in the anchored parent; Windows +removal acts on its opened leaf handle. No operation is a general race-free +sandbox. For operations that still +use validated paths (reads, directory creation, atomic writes, and symlink +creation), portable path checks are **not** +a race-free sandbox: another process can exchange parents or entries between +checks and syscalls, and an I/O failure during mutation can leave partial +results. Protect against concurrent untrusted mutation separately. Exclusive file creation anchors its resolved parent hierarchy as described above. On POSIX, renaming an opened directory does not redirect creation to its replacement: creation stays with the opened directory, even if it is @@ -317,7 +445,9 @@ rather than falling back to path-based overwrite. Windows path classification and directory-mode reparse rejection have portable regression tests. Native Windows path and junction tests also exist and are skipped on other hosts; running the portable cases on macOS does not validate -Windows filesystem syscalls or junction behavior. Exclusive-creation tests +Windows filesystem syscalls or junction behavior. Deletion replacement tests +exercise swaps at enumeration and removal boundaries on the native host; Windows +handle-sharing behavior requires a native Windows run. Exclusive-creation tests cover parent replacement before anchoring and at the final open, along with native Windows parent-handle pinning and portable handle-lifetime checks; portable checks do not substitute for native Windows execution. diff --git a/docs/community/extensions.md b/docs/community/extensions.md index 84ee8c50f8..43d907bd6b 100644 --- a/docs/community/extensions.md +++ b/docs/community/extensions.md @@ -33,6 +33,7 @@ The following community-contributed extensions are available in [`catalog.commun | AgentPay Pre-Pay Audit — Grade an endpoint before your agent pays it | Audit a paid API before money moves: grade the endpoint's 402 terms, see what the live market actually charges, and confirm the wallet can complete the payment right now. | `visibility` | Read-only | [spec-kit-prepay-audit](https://github.com/shawnhvac/spec-kit-prepay-audit) | | AgentPay x402 — Spend Controls for Spec Kit Agents | Set USDC spending caps, check a counterparty's credit before paying it, and pay x402-enabled APIs during spec implementation. Settles on Base or Solana. | `integration` | Read+Write | [spec-kit-pay-x402](https://github.com/shawnhvac/spec-kit-pay-x402) | | Agentstandards Architecture Council | Run a bounded, multi-vendor architecture council between Spec Kit planning and task generation. | `process` | Read+Write | [agentstandards](https://github.com/bbjwz/agentstandards) | +| A·I·DID·IT — Agile Expansion Pack | Runs every work item through Assemble, Ideate, Draft, Iterate, Deliver, Investigate and Tidy, with a simulated agile team and a web-cited practitioner panel in place of human gates. | `process` | Read+Write | [ai-did-it](https://github.com/RubberDuckEngineering/ai-did-it) | | AI-Driven Engineering (AIDE) | A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation | `process` | Read+Write | [aide](https://github.com/mnriem/spec-kit-extensions/tree/main/aide) | | Analytics | Measure what your AI builds, and how much time it saves you | `visibility` | Read+Write | [spec-kit-analytics](https://github.com/Fyloss/spec-kit-analytics) | | API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) | @@ -76,6 +77,7 @@ The following community-contributed extensions are available in [`catalog.commun | Dotdog | Import GitHub Spec Kit artifacts into local knowledge graphs for validation, analysis, search, and MCP queries. | `docs` | Read+Write | [dotdog](https://github.com/specdog/dotdog) | | DUBSAR Memory | Local project memory for Spec Kit with explicit checkpoints, cross-session resume, and SHA-256 freshness for recorded specification, plan, and task references. | `visibility` | Read+Write | [dubsar-memory](https://github.com/kotnisofiane-bit/dubsar-memory) | | EARS Requirements Syntax | Author, lint, and convert requirements using EARS - the five industry-standard sentence patterns for unambiguous, testable requirements | `docs` | Read+Write | [spec-kit-ears](https://github.com/dhruv-15-03/spec-kit-ears) | +| Elephant-Goldfish Model | Design with an elephant. Review with a goldfish. | `process` | Read+Write | [spec-kit-extensions](https://github.com/ksachdeva/spec-kit-extensions) | | Epic | Break work too big for one feature into many, delivered in order, with decisions that hold across them. | `process` | Read+Write | [spec-kit-epic](https://github.com/pmckeown/spec-kit-epic) | | Evaluator Contract | Provider-neutral evaluator contract for evidence, provenance, uncertainty, and recovery across Spec-Driven Development phases. | `process` | Read+Write | [spec-kit-evaluator](https://github.com/electrohire/spec-kit-evaluator) | | Extensify | Create and validate extensions and extension catalogs | `process` | Read+Write | [extensify](https://github.com/mnriem/spec-kit-extensions/tree/main/extensify) | @@ -121,9 +123,11 @@ The following community-contributed extensions are available in [`catalog.commun | Microsoft 365 Integration | Fetch Teams messages, meeting transcripts, and SharePoint/OneDrive files as local Markdown for spec generation | `integration` | Read+Write | [spec-kit-m365](https://github.com/BenBtg/spec-kit-m365) | | Multi-Model Review | Cross-model Spec Kit handoffs for spec authoring, implementation routing, and review. | `process` | Read+Write | [multi-model-review](https://github.com/formin/multi-model-review) | | Multi-Repo Branch Sync | Creates the feature branch in affected sub-repositories and git submodules via plan/tasks hooks | `process` | Read+Write | [multi-repo-sync](https://github.com/fyloss/spec-kit-multi-repo-sync) | +| Multi-Repo Workspace Orchestration | Orchestrate spec-driven implementation across a workspace: a central specs repository dispatches implementation to member repositories | `process` | Read+Write | [speckit-multirepo](https://github.com/joaopaschuino/speckit-multirepo) | | Multi-Sites Spec Kit | Multi-site aware specify command with per-site spec folders, auto-increment, and Drupal support | `process` | Read+Write | [spec-kit-multi-sites](https://github.com/teeyo/spec-kit-multi-sites) | | .NET Framework to Modern .NET Migration | Orchestrate end-to-end .NET Framework to modern .NET migration across 7 phases, with SDD lifecycle integration | `process` | Read+Write | [spec-kit-fx-to-net](https://github.com/RogerBestMsft/spec-kit-FxToNet) | | OKF Knowledge Bundle Generator | Generates and maintains an Open Knowledge Format (OKF v0.1) knowledge bundle from a source-code repository. Mines git history for the rationale behind the code, parks what it cannot establish as open questions rather than guessing, and verifies that the bundle's claims are actually supported by the repository. | `docs` | Read+Write | [catalogify](https://github.com/alexcpn/catalogify) | +| OKR Bets | Treat each spec as a Key Result bet: define a hypothesis and verification contract before /speckit.specify, plan measurement, assess results after launch before scaling. Company OKRs stay read-only. | `process` | Read+Write | [spec-kit-okr](https://github.com/juanl/spec-kit-okr) | | Onboard | Contextual onboarding and progressive growth for developers new to spec-kit projects. Explains specs, maps dependencies, validates understanding, and guides the next step | `process` | Read+Write | [spec-kit-onboard](https://github.com/dmux/spec-kit-onboard) | | OpenProject Integration | Sync fields, status, docs, versions and time between spec-kit and OpenProject via MCP | `integration` | Read+Write | [speckit-openproject](https://github.com/Nachklang-io/speckit-openproject) | | OpenSpec | Adds a spec-driven change-management workflow (propose → implement → verify → archive) to Spec Kit projects, keeping specs, designs, and code in sync | `process` | Read+Write | [spec-kit-openspec](https://github.com/aaronrsun/spec-kit-openspec) | @@ -172,6 +176,7 @@ The following community-contributed extensions are available in [`catalog.commun | Spec Kit Discovery Extension | Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation | `process` | Read+Write | [spec-kit-discovery](https://github.com/bigsmartben/spec-kit-discovery) | | Spec Kit Figma | Grounds SpecKit spec/plan/tasks in Figma design context via REST or MCP, on macOS/Linux/Windows. | `integration` | Read+Write | [spec-kit-figma](https://github.com/Fyloss/spec-kit-figma) | | Spec Kit for Azure DevOps — human-gated lifecycle | Azure DevOps story to Done through Spec Kit, with a human sign-off before every board change. | `integration` | Read+Write | [spec-kit-ado](https://github.com/praveenlavu/spec-kit-ado) | +| Spec Kit lifecycle for Jira | A Jira story to Done through Spec Kit, with a human sign-off before every Jira or PR write. | `integration` | Read+Write | [spec-kit-jira](https://github.com/praveenlavu/spec-kit-jira) | | Spec Kit Memory | Recalls prior specs and decisions from configurable memory tools (e.g. memsearch) before SDLC stages, so planning and specification start from what the project already knows | `docs` | Read+Write | [spec-kit-memory](https://github.com/zaytsevand/spec-kit-memory) | | Spec Kit Preview | Generate evidence-backed low, mid, or high fidelity previews from Spec Kit artifacts as Markdown or self-contained HTML | `docs` | Read+Write | [spec-kit-preview](https://github.com/bigsmartben/spec-kit-preview) | | Spec Kit Schedule — parallel subagent rounds | Zero-config planner that turns tasks.md into optimal parallel rounds for subagents (CP-SAT, critical-path aware, file-conflict safe) and an implement command that runs them round by round with tasks.md checkboxes as the single source of progress. | `process` | Read+Write | [spec-kit-schedule](https://github.com/jfranc38/spec-kit-schedule) | @@ -196,7 +201,7 @@ The following community-contributed extensions are available in [`catalog.commun | Superpowers Bridge | Bridges selected Superpowers disciplines into Spec Kit as evidence-first trust gates for agent workflows. | `process` | Read+Write | [superpowers-bridge](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/superpowers-bridge) | | Superpowers Implementation Bridge | Thin orchestrator between Spec Kit design artifacts and Superpowers implementation discipline. Cross-agent; verified for Codex and Claude Code. | `process` | Read+Write | [speckit-superpowers-bridge](https://github.com/lihan3238/speckit-superpowers-bridge) | | Superspec | Bridges spec-kit with obra/superpowers (brainstorming, TDD, subagent, code-review) into a unified, resumable workflow with graceful degradation and session progress tracking | `process` | Read+Write | [superspec](https://github.com/WangX0111/superspec) | -| T-Shirt Sizing Gate | Adds T-Shirt sizing estimates (XS–XL) and an explicit human approval gate between planning and implementation, with SHA-256 checks to detect changes to approved planning artifacts. | `process` | Read+Write | [spec-kit-sizing](https://github.com/mauriziopinotti/spec-kit-sizing) | +| T-Shirt Sizing Gate | Preliminary XS–XL estimates from change descriptions, plus planned-feature sizing and explicit approval within the Spec Kit workflow, with SHA-256 checks for planning changes. | `process` | Read+Write | [spec-kit-sizing](https://github.com/mauriziopinotti/spec-kit-sizing) | | Taco Review | Packages Spec Kit features for human review and syncs edits and comments back. | `integration` | Read+Write | [taco](https://github.com/Arcadia822/taco) | | Tasks to GitHub Project | Publish and synchronize Spec Kit tasks as cards on a GitHub Project (v2) kanban board, with priority and status sync between spec.md/tasks.md and the board. | `integration` | Read+Write | [spec-kit-tasks-to-project](https://github.com/mancioshell/spec-kit-tasks-to-project) | | TDD Extension | Drives spec-kit implementation with tests: a language-agnostic red-green-refactor loop with a per-feature test list, recorded red and green evidence, and mutation-checked test strength. | `process` | Read+Write | [spec-kit-tdd](https://github.com/d0whc3r/spec-kit-tdd) | diff --git a/docs/community/presets.md b/docs/community/presets.md index a7af3b1b59..4a90608eee 100644 --- a/docs/community/presets.md +++ b/docs/community/presets.md @@ -32,6 +32,7 @@ The following community-contributed presets customize how Spec Kit behaves — o | Model Routing Governance | Discovers harness-local models and maps provider-neutral Spec Kit roles to validated local runner profiles without storing credentials or machine-specific availability in Git. | 4 templates, 2 commands, 6 scripts | — | [spec-kit-preset-model-routing-governance](https://github.com/hindermath/spec-kit-preset-model-routing-governance) | | Multi-Repo Branching | Coordinates feature branch creation across multiple git repositories (independent repos and submodules) during plan and tasks phases | 2 commands | — | [spec-kit-preset-multi-repo-branching](https://github.com/sakitA/spec-kit-preset-multi-repo-branching) | | NIEM Information Exchanges | Adds evidence-based NIEM exchange modeling to the core, assess, and bugfix processes while preserving their commands, artifacts, and scope. | 7 templates, 18 commands | assess extension, bug extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) | +| OKR Bet Spec Section | Adds a Hypothesis & Bet section (with the bet's verification contract) to every spec and teaches /speckit.specify to fill it from an okr:/H-n bet. Companion of the okr extension. | 1 template, 1 command | — | [spec-kit-okr](https://github.com/juanl/spec-kit-okr) | | OpenProject Work Packages | Overrides speckit.taskstoissues to create OpenProject work packages (phases, tasks, sub-tasks, relations) via an OpenProject MCP server instead of GitHub Issues | 1 command | — | [speckit-openproject](https://github.com/Nachklang-io/speckit-openproject) | | OpenUP Governance | Composes OpenUP lifecycle governance into Spec Kit's own constitution, spec, plan and tasks templates, and wraps /tasks and /implement with the governed execution contract. | 4 templates, 2 commands | openup extension | [specup](https://github.com/anvigo12/specup) | | Parallel Autonomous Run Governance | Coordinates isolated autonomous campaigns and optionally gates worker scheduling on a current campaign intake review. | 10 templates, 5 commands, 2 scripts | autonomous-run-governance >=0.2.2; optional: intake-review-governance >=0.1.0 | [spec-kit-preset-parallel-autonomous-run-governance](https://github.com/hindermath/spec-kit-preset-parallel-autonomous-run-governance) | diff --git a/docs/community/workflows.md b/docs/community/workflows.md index 4bef4cfcd2..996562453b 100644 --- a/docs/community/workflows.md +++ b/docs/community/workflows.md @@ -15,7 +15,7 @@ Entries in the [community workflow catalog](https://github.com/github/spec-kit/b | Workflow | Version | Description | | --- | --- | --- | -| [ADO story lifecycle](https://github.com/praveenlavu/spec-kit-ado/tree/v0.3.1/workflows/ado-lifecycle) (`ado-lifecycle`) | 0.3.1 | Takes an Azure DevOps story to an open pull request with a preview, a human gate and an apply for every Azure Boards or PR change | +| [ADO story lifecycle](https://github.com/praveenlavu/spec-kit-ado/tree/v0.3.2/workflows/ado-lifecycle) (`ado-lifecycle`) | 0.3.2 | Takes an Azure DevOps story to an open pull request with a preview, a human gate and an apply for every Azure Boards or PR change | | [Guided SDD Pipeline](https://github.com/domattioli/spec-kit-workflow-pipeline) (`pipeline`) | 1.1.0 | Chains specify, clarify, plan, tasks, analyze, implement, and converge, with a clarify gate and post-implementation convergence loop | | [Full SDD Cycle - no gates](https://github.com/clintcparker/speckit-addons/tree/yolo-v0.1.0/workflows/yolo) (`yolo`) | 0.1.0 | Runs specify, plan, tasks, and implement without review gates | diff --git a/docs/extensions/api.md b/docs/extensions/api.md index 8c118c3b16..2bc3b5256f 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -691,6 +691,8 @@ Standard events (defined by core): - `after_clarify` - After spec clarification - `before_constitution` - Before constitution update - `after_constitution` - After constitution update +- `before_converge` - Before convergence assessment +- `after_converge` - After convergence assessment #### Bundled `bug` extension events (available when the extension is installed) diff --git a/docs/extensions/developing.md b/docs/extensions/developing.md index 7bacc94b48..5403b5b39b 100644 --- a/docs/extensions/developing.md +++ b/docs/extensions/developing.md @@ -237,6 +237,7 @@ Available hook points: - `before_checklist` / `after_checklist`: Before/after checklist generation - `before_clarify` / `after_clarify`: Before/after spec clarification - `before_constitution` / `after_constitution`: Before/after constitution update +- `before_converge` / `after_converge`: Before/after convergence assessment - `before_bug_assess` / `after_bug_assess`: Before/after bug assessment (bundled `bug` extension) - `before_bug_fix` / `after_bug_fix`: Before/after bug remediation (bundled `bug` extension) - `before_bug_test` / `after_bug_test`: Before/after bug verification (bundled `bug` extension) diff --git a/docs/extensions/overview.md b/docs/extensions/overview.md index d6d1b5b238..2c2552b663 100644 --- a/docs/extensions/overview.md +++ b/docs/extensions/overview.md @@ -448,6 +448,7 @@ settings: # before_tasks, after_tasks, before_implement, after_implement, # before_analyze, after_analyze, before_checklist, after_checklist, # before_clarify, after_clarify, before_constitution, after_constitution, +# before_converge, after_converge, # Bundled bug extension events (when installed): # before_bug_assess, after_bug_assess, before_bug_fix, after_bug_fix, # before_bug_test, after_bug_test diff --git a/docs/integrations/cli.md b/docs/integrations/cli.md index cceddc34aa..b418d83251 100644 --- a/docs/integrations/cli.md +++ b/docs/integrations/cli.md @@ -209,8 +209,8 @@ specify integration switch | Option | Description | | ------------------------ | ------------------------------------------------------------------------ | | `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | -| `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default | -| `--refresh-shared-infra` | Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) | +| `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite customized shared infrastructure | +| `--refresh-shared-infra` | Overwrite customized shared scripts, page templates, and `.specify/.gitignore`, including for installed targets and the current default | | `--integration-options` | Options for the target integration when it is not already installed | | `--trust-integration` | Authorize downloading and executing a reviewed external adapter without the interactive trust prompt | @@ -222,7 +222,14 @@ specify integration switch `switch` rejects setup options for installed targets. Both paths register enabled extensions and presets for the new default. -See the option table for the different meanings of `--force`. +If the target is already the current default, a call without flags does nothing; +`--refresh-shared-infra` or `--force` refreshes only shared infrastructure, without +reinstalling the integration or re-registering extensions and presets. + +For a target that is not installed, `--force` controls removal of the outgoing +integration's edited files; only `--refresh-shared-infra` permits overwriting +shared customizations. For an installed target, either flag permits that shared +overwrite. Symlinked shared paths remain protected with either flag. When switching to an external adapter that must be downloaded and installed, use `--trust-integration` only after reviewing its code: diff --git a/docs/workflows/developing.md b/docs/workflows/developing.md index e6c8da8f0b..1847a51e62 100644 --- a/docs/workflows/developing.md +++ b/docs/workflows/developing.md @@ -26,12 +26,12 @@ schema_version: "1.0" workflow: id: "speckit" name: "Full SDD Cycle" - version: "1.0.1" + version: "1.0.2" author: "GitHub" description: "Runs specify → plan → tasks → implement with review gates" requires: - speckit_version: ">=0.8.5" + speckit_version: ">=0.15.1" integrations: any: - "alquimia" @@ -49,6 +49,12 @@ inputs: type: string default: "auto" prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)" + speckit_review_spec_verdict: + type: string + default: "" + speckit_review_plan_verdict: + type: string + default: "" steps: - id: specify @@ -59,6 +65,7 @@ steps: - id: review-spec type: gate + verdict_input: speckit_review_spec_verdict message: "Review the generated spec before planning." options: [approve, reject] on_reject: abort @@ -71,6 +78,7 @@ steps: - id: review-plan type: gate + verdict_input: speckit_review_plan_verdict message: "Review the plan before generating tasks." options: [approve, reject] on_reject: abort diff --git a/docs/workflows/overview.md b/docs/workflows/overview.md index bb3c6774d4..82677a94b2 100644 --- a/docs/workflows/overview.md +++ b/docs/workflows/overview.md @@ -33,6 +33,32 @@ specify workflow status specify workflow resume ``` +To approve a paused review without an interactive terminal, supply the +corresponding verdict input after reviewing the output: + +| Workflow | Review gate | Verdict input | +| --- | --- | --- | +| `speckit` | `review-spec` | `speckit_review_spec_verdict` | +| `speckit` | `review-plan` | `speckit_review_plan_verdict` | +| `bugfix` | `review-assessment` | `bug_review_assessment_verdict` | + +```bash +specify workflow resume --input speckit_review_spec_verdict=approve +specify workflow resume --input speckit_review_plan_verdict=approve +specify workflow resume --input bug_review_assessment_verdict=approve +``` + +Use the command matching the active review. These string inputs are optional +and default to `""`: omitting an input or supplying an empty value keeps the +existing prompt on an interactive terminal or pause otherwise. Approving the +specification does not approve the plan review. + +The inputs are available in `speckit` workflow version 1.0.2 and `bugfix` version +1.0.1, with Specify CLI 0.15.1 or later. Update the installed workflow and start +a new run to use its new input declarations. Existing runs keep the workflow +definition saved when they started; updating the installed workflow does not +add inputs to those runs. + Each run gets its own ID and state directory. Completed occurrences are replayed into the expression context without re-executing their implementations. Unfinished work continues from its persisted state; a side effect interrupted @@ -53,8 +79,9 @@ specify workflow run ./workflow.yml --input spec="Build a kanban board" | `assess` | Idea intake, research, definition, shaping, and decision | `idea` | Use `specify workflow info ` for metadata, inputs, and the step graph. -The `speckit` workflow declares `spec` and optional `integration`, not a `scope` -input. Workflows using extension commands also need those commands installed; +The `speckit` workflow declares `spec`, optional `integration`, and the two +optional verdict inputs above, not a `scope` input. Workflows using extension +commands also need those commands installed; consult each bundled definition's requirements. ## Customize a workflow diff --git a/extensions/catalog.community.json b/extensions/catalog.community.json index 7920428061..7564dd5b69 100644 --- a/extensions/catalog.community.json +++ b/extensions/catalog.community.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-11-10T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json", "extensions": { "ado": { @@ -198,6 +198,56 @@ "created_at": "2026-03-18T00:00:00Z", "updated_at": "2026-03-18T00:00:00Z" }, + "aididit": { + "name": "A·I·DID·IT — Agile Expansion Pack", + "id": "aididit", + "description": "Runs every work item through Assemble, Ideate, Draft, Iterate, Deliver, Investigate and Tidy, with a simulated agile team and a web-cited practitioner panel in place of human gates.", + "author": "Rubber Duck Engineering", + "version": "0.2.1", + "download_url": "https://github.com/RubberDuckEngineering/ai-did-it/releases/download/v0.2.1/aididit-v0.2.1.zip", + "sha256": "32fd832e46e0972e2f06bab8723dc981ee41a3d0d0bb18daff0a0cb7da97993f", + "repository": "https://github.com/RubberDuckEngineering/ai-did-it", + "homepage": "https://github.com/RubberDuckEngineering/ai-did-it", + "documentation": "https://github.com/RubberDuckEngineering/ai-did-it/blob/v0.2.1/README.md", + "changelog": "https://github.com/RubberDuckEngineering/ai-did-it/blob/v0.2.1/CHANGELOG.md", + "license": "MIT", + "category": "process", + "effect": "read-write", + "requires": { + "speckit_version": ">=1.3.0,<2.0.0", + "tools": [ + { + "name": "git", + "required": true + }, + { + "name": "gh", + "required": true + }, + { + "name": "claude", + "required": false + } + ] + }, + "provides": { + "commands": 14, + "hooks": 0 + }, + "tags": [ + "agile", + "xp", + "workflow", + "orchestration", + "tdd", + "review" + ], + "verified": false, + "downloads": 0, + "stars": 0, + "created_at": "2026-11-10T00:00:00Z", + "updated_at": "2026-11-10T00:00:00Z" + }, "agent-assign": { "name": "Agent Assign", "id": "agent-assign", @@ -2016,9 +2066,9 @@ "id": "docguard", "description": "Documentation integrity for AI-assisted repositories: lifecycle registry, drift validation, traceability, safe archival, SARIF/JUnit, MCP, GitHub Actions, and Spec Kit hooks.", "author": "raccioly", - "version": "0.46.0", - "download_url": "https://github.com/raccioly/docguard/releases/download/v0.46.0/spec-kit-docguard-v0.46.0.zip", - "sha256": "c8d67b15c13d956b118a464bf8c5c362b432daa8bd499a4aa39dc25a9ffff012", + "version": "0.47.0", + "download_url": "https://github.com/raccioly/docguard/releases/download/v0.47.0/spec-kit-docguard-v0.47.0.zip", + "sha256": "69bf3e08acb22b2825637aed7afb38c7b05de0a8a0072de8942405a51370de67", "repository": "https://github.com/raccioly/docguard", "homepage": "https://www.npmjs.com/package/docguard-cli", "documentation": "https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md", @@ -2059,7 +2109,7 @@ "downloads": 0, "stars": 0, "created_at": "2026-03-13T00:00:00Z", - "updated_at": "2026-11-04T00:00:00Z" + "updated_at": "2026-11-10T00:00:00Z" }, "doctor": { "name": "Project Health Check", @@ -2300,6 +2350,41 @@ "created_at": "2026-07-08T00:00:00Z", "updated_at": "2026-07-08T00:00:00Z" }, + "egm": { + "name": "Elephant-Goldfish Model", + "id": "egm", + "description": "Design with an elephant. Review with a goldfish.", + "author": "Kapil Sachdeva", + "version": "0.9.1", + "download_url": "https://github.com/ksachdeva/spec-kit-extensions/releases/download/egm-v0.9.1/egm-0.9.1.zip", + "sha256": "920f2570be2d40f2a5abe359dd7f58658e90aea317b38438bb8444f8a01d4deb", + "repository": "https://github.com/ksachdeva/spec-kit-extensions", + "homepage": "https://github.com/ksachdeva/spec-kit-extensions", + "documentation": "https://github.com/ksachdeva/spec-kit-extensions/blob/main/extensions/egm/README.md", + "changelog": "https://github.com/ksachdeva/spec-kit-extensions/blob/main/extensions/egm/CHANGELOG.md", + "license": "MIT", + "category": "process", + "effect": "read-write", + "requires": { + "speckit_version": ">=0.9.0" + }, + "provides": { + "commands": 7, + "hooks": 0 + }, + "tags": [ + "assessment", + "discovery", + "triage", + "product", + "workflow" + ], + "verified": false, + "downloads": 0, + "stars": 0, + "created_at": "2026-11-16T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z" + }, "epic": { "name": "Epic", "id": "epic", @@ -3251,6 +3336,56 @@ "created_at": "2026-03-05T00:00:00Z", "updated_at": "2026-03-05T00:00:00Z" }, + "jira-lifecycle": { + "name": "Spec Kit lifecycle for Jira", + "id": "jira-lifecycle", + "description": "A Jira story to Done through Spec Kit, with a human sign-off before every Jira or PR write.", + "author": "praveenlavu", + "version": "0.1.0", + "download_url": "https://github.com/praveenlavu/spec-kit-jira/archive/refs/tags/v0.1.0.zip", + "sha256": "2ef9ca5ea40b3cc05b1043fc39dd01019615ad9d5766e46e5d7389d2e1159902", + "repository": "https://github.com/praveenlavu/spec-kit-jira", + "homepage": "https://github.com/praveenlavu/spec-kit-jira", + "documentation": "https://github.com/praveenlavu/spec-kit-jira/blob/v0.1.0/README.md", + "changelog": "https://github.com/praveenlavu/spec-kit-jira/blob/v0.1.0/CHANGELOG.md", + "license": "MIT", + "category": "integration", + "effect": "read-write", + "requires": { + "speckit_version": ">=1.2.1", + "tools": [ + { + "name": "skj", + "version": ">=0.1.0", + "required": true + }, + { + "name": "git", + "required": true + }, + { + "name": "gh", + "required": false + } + ] + }, + "provides": { + "commands": 13, + "hooks": 2 + }, + "tags": [ + "jira", + "issue-tracking", + "hitl", + "workflow", + "governance" + ], + "verified": false, + "downloads": 0, + "stars": 0, + "created_at": "2026-11-16T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z" + }, "jira-mirror": { "name": "Jira Mirror", "id": "jira-mirror", @@ -4178,6 +4313,42 @@ "created_at": "2026-05-04T02:51:52Z", "updated_at": "2026-06-18T00:00:00Z" }, + "multi-repo": { + "name": "Multi-Repo Workspace Orchestration", + "id": "multi-repo", + "description": "Orchestrate spec-driven implementation across a workspace: a central specs repository dispatches implementation to member repositories", + "author": "Joao Victor", + "version": "0.7.1", + "download_url": "https://github.com/joaopaschuino/speckit-multirepo/archive/refs/tags/v0.7.1.zip", + "sha256": "d2206a8285491886f9b548cfca4db5b752d19667239d7d403d7b7ecc075271b9", + "repository": "https://github.com/joaopaschuino/speckit-multirepo", + "homepage": "https://github.com/joaopaschuino/speckit-multirepo", + "documentation": "https://github.com/joaopaschuino/speckit-multirepo/blob/main/README.md", + "changelog": "https://github.com/joaopaschuino/speckit-multirepo/blob/main/CHANGELOG.md", + "license": "MIT", + "category": "process", + "effect": "read-write", + "requires": { + "speckit_version": ">=1.1.0" + }, + "provides": { + "commands": 5, + "hooks": 1 + }, + "tags": [ + "multi-repo", + "orchestration", + "workspace", + "specs", + "spec-driven-development", + "dependency-graph" + ], + "verified": false, + "downloads": 0, + "stars": 0, + "created_at": "2026-11-16T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z" + }, "multi-repo-sync": { "name": "Multi-Repo Branch Sync", "id": "multi-repo-sync", @@ -4303,6 +4474,41 @@ "created_at": "2026-07-17T00:00:00Z", "updated_at": "2026-09-23T00:00:00Z" }, + "okr": { + "name": "OKR Bets", + "id": "okr", + "description": "Treat each spec as a Key Result bet: define a hypothesis and verification contract before /speckit.specify, plan measurement, assess results after launch before scaling. Company OKRs stay read-only.", + "author": "juanl", + "version": "0.2.1", + "download_url": "https://github.com/juanl/spec-kit-okr/releases/download/v0.2.1/spec-kit-okr-0.2.1.zip", + "sha256": "56b17e6dce43b6fd28e0b33778dc13d11695f57a46d755c4d714c716a373292f", + "repository": "https://github.com/juanl/spec-kit-okr", + "homepage": "https://github.com/juanl/spec-kit-okr", + "documentation": "https://github.com/juanl/spec-kit-okr/blob/v0.2.1/README.md", + "changelog": "https://github.com/juanl/spec-kit-okr/blob/v0.2.1/CHANGELOG.md", + "license": "MIT", + "category": "process", + "effect": "read-write", + "requires": { + "speckit_version": ">=0.9.0" + }, + "provides": { + "commands": 7, + "hooks": 3 + }, + "tags": [ + "okr", + "hypothesis", + "metrics", + "experimentation", + "product" + ], + "verified": false, + "downloads": 0, + "stars": 0, + "created_at": "2026-11-12T00:00:00Z", + "updated_at": "2026-11-12T00:00:00Z" + }, "onboard": { "name": "Onboard", "id": "onboard", @@ -5875,15 +6081,15 @@ "sizing": { "name": "T-Shirt Sizing Gate", "id": "sizing", - "description": "Adds T-Shirt sizing estimates (XS–XL) and an explicit human approval gate between planning and implementation, with SHA-256 checks to detect changes to approved planning artifacts.", + "description": "Preliminary XS–XL estimates from change descriptions, plus planned-feature sizing and explicit approval within the Spec Kit workflow, with SHA-256 checks for planning changes.", "author": "Maurizio Pinotti", - "version": "0.1.2", - "download_url": "https://github.com/mauriziopinotti/spec-kit-sizing/archive/refs/tags/v0.1.2.zip", - "sha256": "4815e6b30bffead28befa7f849a79c44e5b93717ccddc27ded6c14d07a6c7e99", + "version": "0.2.0", + "download_url": "https://github.com/mauriziopinotti/spec-kit-sizing/archive/refs/tags/v0.2.0.zip", + "sha256": "86171fe7f654f8ba664a045d473fea994d816b20b23753aabc7b17e9cc5be567", "repository": "https://github.com/mauriziopinotti/spec-kit-sizing", "homepage": "https://github.com/mauriziopinotti/spec-kit-sizing", - "documentation": "https://github.com/mauriziopinotti/spec-kit-sizing/blob/main/README.md", - "changelog": "https://github.com/mauriziopinotti/spec-kit-sizing/blob/main/CHANGELOG.md", + "documentation": "https://github.com/mauriziopinotti/spec-kit-sizing/blob/v0.2.0/README.md", + "changelog": "https://github.com/mauriziopinotti/spec-kit-sizing/blob/v0.2.0/CHANGELOG.md", "license": "MIT", "category": "process", "effect": "read-write", @@ -5898,7 +6104,7 @@ ] }, "provides": { - "commands": 3, + "commands": 4, "hooks": 2 }, "tags": [ @@ -5910,7 +6116,7 @@ "downloads": 0, "stars": 0, "created_at": "2026-11-09T00:00:00Z", - "updated_at": "2026-11-09T00:00:00Z" + "updated_at": "2026-11-12T00:00:00Z" }, "spec-reference-loader": { "name": "Spec Reference Loader", diff --git a/extensions/catalog.json b/extensions/catalog.json index 10ad367461..d9c6760fe7 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -51,7 +51,7 @@ "git": { "name": "Git Branching Workflow", "id": "git", - "version": "1.0.4", + "version": "1.0.5", "description": "Feature branch creation, numbering (sequential/timestamp), validation, and Git remote detection", "author": "spec-kit-core", "repository": "https://github.com/github/spec-kit", diff --git a/extensions/git/extension.yml b/extensions/git/extension.yml index e8a67a405d..3852aae13e 100644 --- a/extensions/git/extension.yml +++ b/extensions/git/extension.yml @@ -3,7 +3,7 @@ schema_version: "1.0" extension: id: git name: "Git Branching Workflow" - version: "1.0.4" + version: "1.0.5" description: "Feature branch creation, numbering (sequential/timestamp), templating, validation, and Git remote detection" author: spec-kit-core repository: https://github.com/github/spec-kit diff --git a/extensions/git/scripts/powershell/auto-commit.ps1 b/extensions/git/scripts/powershell/auto-commit.ps1 index d27b484bad..3504711c52 100644 --- a/extensions/git/scripts/powershell/auto-commit.ps1 +++ b/extensions/git/scripts/powershell/auto-commit.ps1 @@ -27,11 +27,11 @@ param( $ErrorActionPreference = 'Stop' if ($MessageFile) { - if (-not (Test-Path $MessageFile -PathType Leaf)) { + if (-not (Test-Path -LiteralPath $MessageFile -PathType Leaf)) { Write-Warning "[specify] Error: message file '$MessageFile' not found" exit 1 } - $GeneratedMessage = (Get-Content -Path $MessageFile -Raw) + $GeneratedMessage = (Get-Content -LiteralPath $MessageFile -Raw) if ($null -ne $GeneratedMessage) { $GeneratedMessage = $GeneratedMessage.TrimEnd("`r", "`n") } @@ -41,15 +41,15 @@ if ($MessageFile) { # both the "any changes?" check below and by `git add .`, polluting the # commit or defeating the no-changes short-circuit even when nothing # else changed. - Remove-Item -Path $MessageFile -Force -ErrorAction SilentlyContinue + Remove-Item -LiteralPath $MessageFile -Force -ErrorAction SilentlyContinue } function Find-ProjectRoot { param([string]$StartDir) - $current = Resolve-Path $StartDir + $current = Resolve-Path -LiteralPath $StartDir while ($true) { foreach ($marker in @('.specify', '.git')) { - if (Test-Path (Join-Path $current $marker)) { + if (Test-Path -LiteralPath (Join-Path $current $marker)) { return $current } } @@ -61,7 +61,7 @@ function Find-ProjectRoot { $repoRoot = Find-ProjectRoot -StartDir $PSScriptRoot if (-not $repoRoot) { $repoRoot = Get-Location } -Set-Location $repoRoot +Set-Location -LiteralPath $repoRoot # Check if git is available if (-not (Get-Command git -ErrorAction SilentlyContinue)) { @@ -90,9 +90,9 @@ $enabled = $false $commitMsg = "" $commitStyle = "fixed" -if (Test-Path $configFile) { +if (Test-Path -LiteralPath $configFile) { # Top-level scalar key: commit_style (fixed | conventional) - foreach ($line in Get-Content $configFile) { + foreach ($line in Get-Content -LiteralPath $configFile) { if ($line -match '^commit_style:\s*(.+)$') { $styleVal = (($matches[1] -replace '\s+#.*$', '').Trim()) -replace '^["'']' -replace '["'']$' if ($styleVal) { @@ -112,7 +112,7 @@ if (Test-Path $configFile) { $inEvent = $false $defaultEnabled = $false - foreach ($line in Get-Content $configFile) { + foreach ($line in Get-Content -LiteralPath $configFile) { # Detect auto_commit: section if ($line -match '^auto_commit:') { $inAutoCommit = $true @@ -159,7 +159,7 @@ if (Test-Path $configFile) { # If event-specific key not found, use default if (-not $enabled -and $defaultEnabled) { - $hasEventKey = Select-String -Path $configFile -Pattern "^\s*${EventName}:" -Quiet + $hasEventKey = Select-String -LiteralPath $configFile -Pattern "^\s*${EventName}:" -Quiet if (-not $hasEventKey) { $enabled = $true } diff --git a/extensions/git/scripts/powershell/create-new-feature-branch.ps1 b/extensions/git/scripts/powershell/create-new-feature-branch.ps1 index 54452b6999..be4fd06910 100644 --- a/extensions/git/scripts/powershell/create-new-feature-branch.ps1 +++ b/extensions/git/scripts/powershell/create-new-feature-branch.ps1 @@ -67,8 +67,8 @@ function Get-HighestNumberFromSpecs { param([string]$SpecsDir) [long]$highest = 0 - if (Test-Path $SpecsDir) { - Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object { + if (Test-Path -LiteralPath $SpecsDir) { + Get-ChildItem -LiteralPath $SpecsDir -Directory | ForEach-Object { if ($_.Name -match '^(\d{3,})-' -and $_.Name -notmatch '^\d{8}-\d{6}-') { [long]$num = 0 if ([long]::TryParse($matches[1], [ref]$num) -and $num -gt $highest) { @@ -192,10 +192,10 @@ function ConvertTo-CleanBranchName { # --------------------------------------------------------------------------- function Find-ProjectRoot { param([string]$StartDir) - $current = Resolve-Path $StartDir + $current = Resolve-Path -LiteralPath $StartDir while ($true) { foreach ($marker in @('.specify', '.git')) { - if (Test-Path (Join-Path $current $marker)) { + if (Test-Path -LiteralPath (Join-Path $current $marker)) { return $current } } @@ -214,7 +214,7 @@ if ($projectRoot) { (Join-Path $projectRoot "scripts/powershell/common.ps1") ) foreach ($candidate in $candidates) { - if (Test-Path $candidate) { + if (Test-Path -LiteralPath $candidate) { . $candidate $commonLoaded = $true break @@ -222,7 +222,7 @@ if ($projectRoot) { } } -if (-not $commonLoaded -and (Test-Path "$PSScriptRoot/git-common.ps1")) { +if (-not $commonLoaded -and (Test-Path -LiteralPath "$PSScriptRoot/git-common.ps1")) { . "$PSScriptRoot/git-common.ps1" $commonLoaded = $true } @@ -263,7 +263,7 @@ if (Get-Command Test-HasGit -ErrorAction SilentlyContinue) { } } -Set-Location $repoRoot +Set-Location -LiteralPath $repoRoot $specsDir = Join-Path $repoRoot 'specs' $configFile = Join-Path $repoRoot ".specify/extensions/git/git-config.yml" diff --git a/extensions/git/scripts/powershell/git-common.ps1 b/extensions/git/scripts/powershell/git-common.ps1 index a7ea724a31..c6777fcfa8 100644 --- a/extensions/git/scripts/powershell/git-common.ps1 +++ b/extensions/git/scripts/powershell/git-common.ps1 @@ -6,7 +6,7 @@ function Test-HasGit { param([string]$RepoRoot = (Get-Location)) try { - if (-not (Test-Path (Join-Path $RepoRoot '.git'))) { return $false } + if (-not (Test-Path -LiteralPath (Join-Path $RepoRoot '.git'))) { return $false } if (-not (Get-Command git -ErrorAction SilentlyContinue)) { return $false } git -C $RepoRoot rev-parse --is-inside-work-tree 2>$null | Out-Null return ($LASTEXITCODE -eq 0) diff --git a/extensions/git/scripts/powershell/initialize-repo.ps1 b/extensions/git/scripts/powershell/initialize-repo.ps1 index b32e24179b..e4ade69f83 100644 --- a/extensions/git/scripts/powershell/initialize-repo.ps1 +++ b/extensions/git/scripts/powershell/initialize-repo.ps1 @@ -8,10 +8,10 @@ $ErrorActionPreference = 'Stop' # Find project root function Find-ProjectRoot { param([string]$StartDir) - $current = Resolve-Path $StartDir + $current = Resolve-Path -LiteralPath $StartDir while ($true) { foreach ($marker in @('.specify', '.git')) { - if (Test-Path (Join-Path $current $marker)) { + if (Test-Path -LiteralPath (Join-Path $current $marker)) { return $current } } @@ -23,13 +23,13 @@ function Find-ProjectRoot { $repoRoot = Find-ProjectRoot -StartDir $PSScriptRoot if (-not $repoRoot) { $repoRoot = Get-Location } -Set-Location $repoRoot +Set-Location -LiteralPath $repoRoot # Read commit message from extension config, fall back to default $commitMsg = "[Spec Kit] Initial commit" $configFile = Join-Path $repoRoot ".specify/extensions/git/git-config.yml" -if (Test-Path $configFile) { - foreach ($line in Get-Content $configFile) { +if (Test-Path -LiteralPath $configFile) { + foreach ($line in Get-Content -LiteralPath $configFile) { if ($line -match '^init_commit_message:\s*(.+)$') { $val = $matches[1].Trim() -replace '^["'']' -replace '["'']$' if ($val) { $commitMsg = $val } diff --git a/presets/catalog.community.json b/presets/catalog.community.json index 01f0139fc7..0055f13eda 100644 --- a/presets/catalog.community.json +++ b/presets/catalog.community.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-11-09T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json", "presets": { "a11y-governance": { @@ -463,14 +463,14 @@ "intake-authoring-governance": { "name": "Intake Authoring Governance", "id": "intake-authoring-governance", - "version": "0.3.7", + "version": "0.3.12", "description": "Governs traceable intake CRUD, language-aware requirements collections, bounded public HTTPS sources, and explicitly approved single or series authoring.", "author": "Thorsten Hindermann", "repository": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance", - "download_url": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance/archive/refs/tags/v0.3.7.zip", - "sha256": "fc20a010c2124977249f926677d1bb2b03b81e7cd2a549bc4c7489de837e1427", + "download_url": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance/archive/refs/tags/v0.3.12.zip", + "sha256": "109aaa5f2014209695ef9ee3aa4529dfd8be6ea107f077249242ccf5a951bb81", "homepage": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance", - "documentation": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance/blob/v0.3.7/README.md", + "documentation": "https://github.com/hindermath/spec-kit-preset-intake-authoring-governance/blob/v0.3.12/README.md", "license": "MIT", "requires": { "speckit_version": ">=0.8.3" @@ -483,24 +483,24 @@ "tags": [ "intake", "authoring", - "governance", "requirements", - "lifecycle" + "governance", + "provenance" ], "created_at": "2026-07-22T00:00:00Z", - "updated_at": "2026-10-07T00:00:00Z" + "updated_at": "2026-11-10T00:00:00Z" }, "intake-review-governance": { "name": "Intake Review Governance", "id": "intake-review-governance", - "version": "0.2.4", + "version": "0.2.8", "description": "Reviews single, series, campaign, and language-aware requirements collections before Spec Kit execution.", "author": "Thorsten Hindermann", "repository": "https://github.com/hindermath/spec-kit-preset-intake-review-governance", - "download_url": "https://github.com/hindermath/spec-kit-preset-intake-review-governance/archive/refs/tags/v0.2.4.zip", - "sha256": "c4a21c4a99ba6eed0df3028bc1ee19158f1274d9e440f433c504877c997ed816", + "download_url": "https://github.com/hindermath/spec-kit-preset-intake-review-governance/archive/refs/tags/v0.2.8.zip", + "sha256": "ddc36c0608fcf4399d81e8a6dc8de7efc026536319b310827e9f57f7fc73acf2", "homepage": "https://github.com/hindermath/spec-kit-preset-intake-review-governance", - "documentation": "https://github.com/hindermath/spec-kit-preset-intake-review-governance/blob/v0.2.4/README.md", + "documentation": "https://github.com/hindermath/spec-kit-preset-intake-review-governance/blob/v0.2.8/README.md", "license": "MIT", "requires": { "speckit_version": ">=0.8.3" @@ -514,23 +514,23 @@ "intake", "review", "governance", - "requirements", - "quality-gate" + "quality-gate", + "campaign" ], "created_at": "2026-07-21T00:00:00Z", - "updated_at": "2026-10-09T00:00:00Z" + "updated_at": "2026-11-11T00:00:00Z" }, "intake-sequencing-governance": { "name": "Intake Sequencing Governance", "id": "intake-sequencing-governance", - "version": "0.2.8", + "version": "0.2.13", "description": "Manages language-aware intake-series order, typed dependencies, lifecycle, and authority-neutral next-candidate selection.", "author": "Thorsten Hindermann", "repository": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance", - "download_url": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance/archive/refs/tags/v0.2.8.zip", - "sha256": "07dbd79f76927136494fe0742b0e8044d7cb2625c9d5d8f61fbe05b1e8d980ac", + "download_url": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance/archive/refs/tags/v0.2.13.zip", + "sha256": "7dd29964d16bb8a8e0a107c2054ae8e0f69da99bdb7a6d5f320337d055fde3de", "homepage": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance", - "documentation": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance/blob/v0.2.8/README.md", + "documentation": "https://github.com/hindermath/spec-kit-preset-intake-sequencing-governance/blob/v0.2.13/README.md", "license": "MIT", "requires": { "speckit_version": ">=0.8.3" @@ -548,7 +548,7 @@ "lifecycle" ], "created_at": "2026-07-27T00:00:00Z", - "updated_at": "2026-10-09T00:00:00Z" + "updated_at": "2026-11-12T00:00:00Z" }, "inventory-alignment": { "name": "Inventory Alignment", @@ -759,6 +759,34 @@ "created_at": "2026-09-23T00:00:00Z", "updated_at": "2026-09-23T00:00:00Z" }, + "okr-bet": { + "name": "OKR Bet Spec Section", + "id": "okr-bet", + "version": "0.2.1", + "description": "Adds a Hypothesis & Bet section (with the bet's verification contract) to every spec and teaches /speckit.specify to fill it from an okr:/H-n bet. Companion of the okr extension.", + "author": "juanl", + "repository": "https://github.com/juanl/spec-kit-okr", + "download_url": "https://github.com/juanl/spec-kit-okr/releases/download/v0.2.1/spec-kit-okr-bet-preset-0.2.1.zip", + "sha256": "90c6e1e58956696a6b5fd13082ddcf45ab669c3c742e203f81882ef6a8498cc8", + "homepage": "https://github.com/juanl/spec-kit-okr", + "documentation": "https://github.com/juanl/spec-kit-okr/blob/v0.2.1/README.md#install", + "license": "MIT", + "requires": { + "speckit_version": ">=0.9.0" + }, + "provides": { + "templates": 1, + "commands": 1 + }, + "tags": [ + "okr", + "hypothesis", + "spec-template", + "metrics" + ], + "created_at": "2026-11-16T00:00:00Z", + "updated_at": "2026-11-16T00:00:00Z" + }, "openproject": { "name": "OpenProject Work Packages", "id": "openproject", diff --git a/pyproject.toml b/pyproject.toml index 2787cff54f..51b6929c10 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "specify-cli" -version = "1.4.0+mas.1" +version = "1.4.1+mas.1" description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)." readme = "README.md" requires-python = ">=3.11" diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1 index c0aa9154b5..0f254cbdec 100644 --- a/scripts/powershell/common.ps1 +++ b/scripts/powershell/common.ps1 @@ -193,7 +193,7 @@ function Get-FeaturePathsEnv { if (-not $noPersist) { Save-FeatureJson -RepoRoot $repoRoot -FeatureDirectory $env:SPECIFY_FEATURE_DIRECTORY } - } elseif (Test-Path $featureJson) { + } elseif (Test-Path -LiteralPath $featureJson) { $featureJsonRaw = [System.IO.File]::ReadAllText($featureJson, [System.Text.Encoding]::UTF8) try { $featureConfig = $featureJsonRaw | ConvertFrom-Json @@ -417,7 +417,7 @@ function Get-SortedExtensionIds { } } - foreach ($directory in Get-ChildItem -Path $ExtensionsDir -Directory -ErrorAction SilentlyContinue) { + foreach ($directory in Get-ChildItem -LiteralPath $ExtensionsDir -Directory -ErrorAction SilentlyContinue) { if ($directory.Name -cmatch '^[a-z0-9-]+$' -and $directory.Name -cnotin $registeredNames) { $ranked += [PSCustomObject]@{ Priority = 10; Id = $directory.Name } } @@ -442,15 +442,15 @@ function Resolve-Template { # Priority 1: Project overrides $override = Join-Path $base "overrides/$TemplateName.md" - if (Test-Path $override) { return $override } + if (Test-Path -LiteralPath $override) { return $override } # Priority 2: Installed presets (sorted by priority from .registry) $presetsDir = Join-Path $RepoRoot '.specify/presets' - if (Test-Path $presetsDir) { + if (Test-Path -LiteralPath $presetsDir) { $registryFile = Join-Path $presetsDir '.registry' $sortedPresets = @() $registryParsed = $false - if (Test-Path $registryFile) { + if (Test-Path -LiteralPath $registryFile) { try { $registryData = [System.IO.File]::ReadAllText($registryFile, [System.Text.Encoding]::UTF8) | ConvertFrom-Json if ($null -eq $registryData -or $registryData -isnot [PSCustomObject]) { @@ -492,36 +492,36 @@ function Resolve-Template { if ($registryParsed) { foreach ($presetId in $sortedPresets) { $candidate = Join-Path $presetsDir "$presetId/templates/$TemplateName.md" - if (Test-Path $candidate) { return $candidate } + if (Test-Path -LiteralPath $candidate) { return $candidate } $candidate = Join-Path $presetsDir "$presetId/$TemplateName.md" - if (Test-Path $candidate) { return $candidate } + if (Test-Path -LiteralPath $candidate) { return $candidate } } } else { # Fallback: alphabetical directory order - foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) { + foreach ($preset in Get-ChildItem -LiteralPath $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) { $candidate = Join-Path $preset.FullName "templates/$TemplateName.md" - if (Test-Path $candidate) { return $candidate } + if (Test-Path -LiteralPath $candidate) { return $candidate } $candidate = Join-Path $preset.FullName "$TemplateName.md" - if (Test-Path $candidate) { return $candidate } + if (Test-Path -LiteralPath $candidate) { return $candidate } } } } # Priority 3: Extension-provided templates $extDir = Join-Path $RepoRoot '.specify/extensions' - if (Test-Path $extDir) { + if (Test-Path -LiteralPath $extDir) { foreach ($extensionId in Get-SortedExtensionIds -ExtensionsDir $extDir) { $candidate = Join-Path $extDir "$extensionId/templates/$TemplateName.md" - if (-not (Test-Path $candidate)) { + if (-not (Test-Path -LiteralPath $candidate)) { $candidate = Join-Path $extDir "$extensionId/$TemplateName.md" } - if (Test-Path $candidate) { return $candidate } + if (Test-Path -LiteralPath $candidate) { return $candidate } } } # Priority 4: Core templates $core = Join-Path $base "$TemplateName.md" - if (Test-Path $core) { return $core } + if (Test-Path -LiteralPath $core) { return $core } return $null } @@ -547,7 +547,7 @@ function Resolve-TemplateContent { # Priority 1: Project overrides (always "replace") $override = Join-Path $base "overrides/$TemplateName.md" - if (Test-Path $override) { + if (Test-Path -LiteralPath $override) { return [System.IO.File]::ReadAllText( $override, [System.Text.Encoding]::UTF8 @@ -558,11 +558,11 @@ function Resolve-TemplateContent { # Priority 2: Installed presets (sorted by priority from .registry) $presetsDir = Join-Path $RepoRoot '.specify/presets' - if (Test-Path $presetsDir) { + if (Test-Path -LiteralPath $presetsDir) { $registryFile = Join-Path $presetsDir '.registry' $sortedPresets = @() $registryParsed = $false - if (Test-Path $registryFile) { + if (Test-Path -LiteralPath $registryFile) { try { $registryData = [System.IO.File]::ReadAllText($registryFile, [System.Text.Encoding]::UTF8) | ConvertFrom-Json if ($null -eq $registryData -or $registryData -isnot [PSCustomObject]) { @@ -602,7 +602,7 @@ function Resolve-TemplateContent { } if (-not $registryParsed) { - $sortedPresets = Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | + $sortedPresets = Get-ChildItem -LiteralPath $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -cmatch '^[a-z0-9-]+$' } | Sort-Object Name | ForEach-Object { $_.Name } @@ -615,10 +615,10 @@ function Resolve-TemplateContent { $manifestFilePath = '' $manifestDeclared = $false $manifest = Join-Path $presetsDir "$presetId/preset.yml" - if ((Test-Path $manifest) -and -not $pyCmd) { + if ((Test-Path -LiteralPath $manifest) -and -not $pyCmd) { throw "Python 3 and PyYAML are required to resolve preset template composition" } - if (Test-Path $manifest) { + if (Test-Path -LiteralPath $manifest) { try { # Use Python to parse YAML manifest for strategy and file path $pyArgs = if ($pyCmd.Count -gt 1) { $pyCmd[1..($pyCmd.Count-1)] } else { @() } @@ -690,9 +690,9 @@ except Exception as exc: $strategy = $parts[1].ToLowerInvariant() if ($parts.Count -gt 2 -and $parts[2]) { $manifestFilePath = $parts[2] } } - Remove-Item $pyStderrFile -Force -ErrorAction SilentlyContinue + Remove-Item -LiteralPath $pyStderrFile -Force -ErrorAction SilentlyContinue } catch { - if ($pyStderrFile) { Remove-Item $pyStderrFile -Force -ErrorAction SilentlyContinue } + if ($pyStderrFile) { Remove-Item -LiteralPath $pyStderrFile -Force -ErrorAction SilentlyContinue } throw } } @@ -706,14 +706,14 @@ except Exception as exc: } if ($manifestFilePath) { $mf = Join-Path $presetsDir "$presetId/$manifestFilePath" - if (Test-Path $mf) { $candidate = $mf } + if (Test-Path -LiteralPath $mf) { $candidate = $mf } } if (-not $candidate -and -not $manifestDeclared) { $cf = Join-Path $presetsDir "$presetId/templates/$TemplateName.md" - if (Test-Path $cf) { $candidate = $cf } + if (Test-Path -LiteralPath $cf) { $candidate = $cf } if (-not $candidate) { $cf = Join-Path $presetsDir "$presetId/$TemplateName.md" - if (Test-Path $cf) { $candidate = $cf } + if (Test-Path -LiteralPath $cf) { $candidate = $cf } } } if ($candidate) { @@ -729,13 +729,13 @@ except Exception as exc: # Priority 3: Extension-provided templates (always "replace") $extDir = Join-Path $RepoRoot '.specify/extensions' - if (-not $effectiveBaseFound -and (Test-Path $extDir)) { + if (-not $effectiveBaseFound -and (Test-Path -LiteralPath $extDir)) { foreach ($extensionId in Get-SortedExtensionIds -ExtensionsDir $extDir) { $candidate = Join-Path $extDir "$extensionId/templates/$TemplateName.md" - if (-not (Test-Path $candidate)) { + if (-not (Test-Path -LiteralPath $candidate)) { $candidate = Join-Path $extDir "$extensionId/$TemplateName.md" } - if (Test-Path $candidate) { + if (Test-Path -LiteralPath $candidate) { $layerPaths += $candidate $layerStrategies += 'replace' $effectiveBaseFound = $true @@ -746,7 +746,7 @@ except Exception as exc: # Priority 4: Core templates (always "replace") $core = Join-Path $base "$TemplateName.md" - if (-not $effectiveBaseFound -and (Test-Path $core)) { + if (-not $effectiveBaseFound -and (Test-Path -LiteralPath $core)) { $layerPaths += $core $layerStrategies += 'replace' } diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1 index cd8a2d2b3c..717f1f214b 100644 --- a/scripts/powershell/create-new-feature.ps1 +++ b/scripts/powershell/create-new-feature.ps1 @@ -54,8 +54,8 @@ function Get-HighestNumberFromSpecs { param([string]$SpecsDir) [long]$highest = 0 - if (Test-Path $SpecsDir) { - Get-ChildItem -Path $SpecsDir -Directory | ForEach-Object { + if (Test-Path -LiteralPath $SpecsDir) { + Get-ChildItem -LiteralPath $SpecsDir -Directory | ForEach-Object { # Match sequential prefixes (>=3 digits), but skip timestamp dirs. if ($_.Name -match '^(\d{3,})-' -and $_.Name -notmatch '^\d{8}-\d{6}-') { [long]$num = 0 @@ -139,7 +139,7 @@ function Get-FittedBranchName { # Use common.ps1 functions which prioritize .specify $repoRoot = Get-RepoRoot -Set-Location $repoRoot +Set-Location -LiteralPath $repoRoot $specsDir = Join-Path $repoRoot 'specs' if (-not $DryRun) { @@ -297,7 +297,7 @@ if (-not $DryRun) { exit 1 } - $needsSpec = -not (Test-Path -PathType Leaf $specFile) + $needsSpec = -not (Test-Path -LiteralPath $specFile -PathType Leaf) $content = $null if ($needsSpec) { $content = Resolve-TemplateContent -TemplateName 'spec-template' -RepoRoot $repoRoot diff --git a/src/specify_cli/_file_handles.py b/src/specify_cli/_file_handles.py index 6b38baaffe..cdeddafb27 100644 --- a/src/specify_cli/_file_handles.py +++ b/src/specify_cli/_file_handles.py @@ -6,11 +6,25 @@ import os import secrets import stat +import struct import tempfile from pathlib import Path, PureWindowsPath +from typing import Literal, NamedTuple -def _open_windows_child(parent: int, name: str, *, directory: bool, access: int, sharing: int) -> int: +_IdentityKind = Literal["fileid128", "legacy64"] + + +class _WindowsFileIdentity(NamedTuple): + kind: _IdentityKind + volume: int + file_id: bytes + + +def _open_windows_child( + parent: int, name: str, *, directory: bool | None, access: int, + sharing: int, allow_reparse: bool = False, +) -> int: """Open one component relative to an already validated directory handle.""" if PureWindowsPath(name).parts != (name,) or PureWindowsPath(name).anchor or name == ".." or "\0" in name: raise ValueError(f"Expected a single relative Windows path component: {name!r}") @@ -41,13 +55,15 @@ def _open_windows_child(parent: int, name: str, *, directory: bool, access: int, # OBJ_DONT_REPARSE and FILE_OPEN_REPARSE_POINT keep resolution on this handle. attributes = abi._ObjectAttributes( ctypes.sizeof(abi._ObjectAttributes), parent, ctypes.pointer(unicode_name), - 0x40 | 0x1000, None, None, + 0x40 | (0 if allow_reparse else 0x1000), None, None, ) handle = wintypes.HANDLE() status = abi._IoStatusBlock() - options = 0x00200000 | (0x1 if directory else 0x40 | 0x20) + options = 0x00200000 | 0x20 # FILE_OPEN_REPARSE_POINT | FILE_SYNCHRONOUS_IO_NONALERT. + if directory is not None: + options |= 0x1 if directory else 0x40 result = create( - ctypes.byref(handle), access | (0 if directory else 0x100000), + ctypes.byref(handle), access | 0x100000, # SYNCHRONIZE is required for synchronous I/O. ctypes.byref(attributes), ctypes.byref(status), None, 0, sharing, 1, options, None, 0, ) @@ -58,6 +74,121 @@ def _open_windows_child(parent: int, name: str, *, directory: bool, access: int, return handle.value +@contextmanager +def _windows_entry(parent: int, name: str, *, deleting: bool = False) -> Iterator[int]: + """Open the leaf itself relative to its directory, including allowed links.""" + handle = _open_windows_child( + parent, name, directory=None, access=0x80 | (0x10000 if deleting else 0), + sharing=0x7, allow_reparse=True, + ) + try: + yield handle + finally: + _windows_api().CloseHandle(handle) + + +def _windows_mode(handle: int) -> int: + import ctypes + + class Attributes(ctypes.Structure): + _fields_ = [("attributes", ctypes.c_uint32), ("tag", ctypes.c_uint32)] + + info = Attributes() + if not _windows_api().GetFileInformationByHandleEx( + handle, 9, ctypes.byref(info), ctypes.sizeof(info) + ): + raise ctypes.WinError(ctypes.get_last_error()) + if info.attributes & 0x400: + if info.tag != 0xA000000C: + raise OSError(errno.ELOOP, "Unsupported Windows reparse point") + return stat.S_IFLNK + return stat.S_IFDIR if info.attributes & 0x10 else stat.S_IFREG + + +def _windows_readlink(handle: int) -> str: + import ctypes + from ctypes import wintypes + + kernel = ctypes.WinDLL("kernel32", use_last_error=True) + control = kernel.DeviceIoControl + control.argtypes = [ + wintypes.HANDLE, wintypes.DWORD, wintypes.LPVOID, wintypes.DWORD, + wintypes.LPVOID, wintypes.DWORD, wintypes.LPDWORD, wintypes.LPVOID, + ] + control.restype = wintypes.BOOL + buffer = ctypes.create_string_buffer(16384) + length = wintypes.DWORD() + if not control( + handle, 0x900A8, None, 0, buffer, len(buffer), ctypes.byref(length), None + ): + raise ctypes.WinError(ctypes.get_last_error()) + data = buffer.raw[:length.value] + if len(data) < 20: + raise OSError(errno.EIO, "Incomplete Windows symlink data") + tag, size, _, offset, count, _, _, flags = struct.unpack_from(" len(data) or end > 8 + size + ): + raise OSError(errno.EIO, "Invalid Windows symlink data") + target = data[20 + offset:end].decode("utf-16-le", errors="surrogatepass") + if "\0" in target: + raise OSError(errno.EIO, "Invalid Windows symlink target") + if not flags & 1 and target.startswith("\\??\\"): + target = "\\\\?\\" + target[4:] + return target + + +def _windows_directory_names(handle: int) -> list[str]: + import ctypes + + buffer = ctypes.create_string_buffer(131072) + names = [] + kind = 15 # FileFullDirectoryRestartInfo, then FileFullDirectoryInfo. + while True: + if not _windows_api().GetFileInformationByHandleEx(handle, kind, buffer, len(buffer)): + error = ctypes.get_last_error() + if error == 18: # ERROR_NO_MORE_FILES. + return names + raise ctypes.WinError(error) + kind = 14 + data = buffer.raw + offset = 0 + while True: + if offset + 68 > len(data): + raise OSError(errno.EIO, "Incomplete Windows directory entry") + next_entry = struct.unpack_from(" len(data): + raise OSError(errno.EIO, "Invalid Windows directory entry") + name = data[offset + 68:end].decode("utf-16-le", errors="surrogatepass") + if name not in (".", ".."): + if PureWindowsPath(name).parts != (name,) or PureWindowsPath(name).anchor or "\0" in name: + raise OSError(errno.EIO, "Invalid Windows directory component") + names.append(name) + if not next_entry: + break + if next_entry % 8 or next_entry < 68 + size: + raise OSError(errno.EIO, "Invalid Windows directory entry offset") + offset += next_entry + + +def _windows_delete(handle: int) -> None: + """Mark the opened object for removal, never reopen its pathname.""" + import ctypes + from ctypes import wintypes + + kernel = ctypes.WinDLL("kernel32", use_last_error=True) + dispose = kernel.SetFileInformationByHandle + dispose.argtypes = [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD] + dispose.restype = wintypes.BOOL + delete = ctypes.c_int32(True) + if not dispose(handle, 4, ctypes.byref(delete), ctypes.sizeof(delete)): + raise ctypes.WinError(ctypes.get_last_error()) + + def _windows_api(): import ctypes from ctypes import wintypes @@ -85,6 +216,7 @@ def _windows_api(): def _open_windows_handle( path: Path, *, directory: bool, overwrite: bool = False, create_attributes: int | None = None, parent: int | None = None, traverse: bool = False, + pin: bool = True, ) -> int: if parent is not None and (overwrite or create_attributes is not None): raise ValueError("Relative Windows handle opens do not support creation or overwrite") @@ -96,19 +228,24 @@ class AttributeTagInfo(ctypes.Structure): kernel = _windows_api() access = (0x80 | (0x20 if traverse else 0x1)) if directory else 0x80000000 + if not pin: + access = 0x80 if overwrite: access = 0x40000000 | 0x80 + sharing = 0x3 if pin else 0x7 if parent is None: # FILE_TRAVERSE participates in sharing checks without requiring enumeration. handle = kernel.CreateFileW( - str(path), access, 0x3, None, + str(path), access, sharing, None, 3 if create_attributes is None else 1, # OPEN_EXISTING or CREATE_NEW. 0x00200000 | 0x02000000 | (create_attributes or 0), None, ) if handle == wintypes.HANDLE(-1).value: raise ctypes.WinError(ctypes.get_last_error()) else: - handle = _open_windows_child(parent, str(path), directory=directory, access=access, sharing=0x3) + handle = _open_windows_child( + parent, str(path), directory=directory, access=access, sharing=sharing + ) try: attributes = AttributeTagInfo() if not kernel.GetFileInformationByHandleEx( @@ -128,9 +265,14 @@ class AttributeTagInfo(ctypes.Structure): @contextmanager def _windows_handle( path: Path, *, directory: bool, parent: int | None = None, traverse: bool = False, + pin: bool = True, ) -> Iterator[int]: - """Pin a non-reparse path by withholding Windows delete sharing.""" - if parent is None and not traverse: + """Open a non-reparse object, optionally relative to a retained parent.""" + if not pin: + handle = _open_windows_handle( + path, directory=directory, parent=parent, traverse=traverse, pin=False + ) + elif parent is None and not traverse: handle = _open_windows_handle(path, directory=directory) else: handle = _open_windows_handle(path, directory=directory, parent=parent, traverse=traverse) @@ -140,6 +282,132 @@ def _windows_handle( _windows_api().CloseHandle(handle) +def _windows_filesystem(handle: int) -> str: + """Query the opened volume, including network filesystems, without a pathname.""" + import ctypes + from ctypes import wintypes + from . import _windows_abi as abi + + class FilesystemAttributes(ctypes.Structure): + _fields_ = [ + ("attributes", ctypes.c_uint32), + ("maximum_component", ctypes.c_int32), + ("name_length", ctypes.c_uint32), + ("name", ctypes.c_uint16 * 261), + ] + + native = ctypes.WinDLL("ntdll") + query = native.NtQueryVolumeInformationFile + query.argtypes = [ + wintypes.HANDLE, abi._IoStatusBlockPointer, wintypes.LPVOID, + ctypes.c_uint32, ctypes.c_int, + ] + query.restype = ctypes.c_int32 + dos_error = native.RtlNtStatusToDosError + dos_error.argtypes = [ctypes.c_int32] + dos_error.restype = ctypes.c_uint32 + attributes = FilesystemAttributes() + status = abi._IoStatusBlock() + result = query( + handle, ctypes.byref(status), ctypes.byref(attributes), + ctypes.sizeof(attributes), 5, # FileFsAttributeInformation. + ) + if result != 0: + raise ctypes.WinError(dos_error(result)) + length = attributes.name_length + if not length or length % 2 or length > ctypes.sizeof(attributes.name): + raise OSError(errno.EINVAL, "Invalid filesystem name from volume query") + return bytes(attributes.name)[:length].decode("utf-16-le") + + +def _windows_legacy_file_id(handle: int) -> _WindowsFileIdentity: + """Query a live legacy identity only on filesystems with usable 64-bit IDs.""" + import ctypes + from ctypes import wintypes + + filesystem = _windows_filesystem(handle).upper() + # ReFS needs 128 bits; unknown drivers may report non-identifying indexes. + if filesystem not in {"FAT", "FAT32", "EXFAT", "NTFS"}: + raise OSError(errno.ENOTSUP, f"No reliable legacy file identity for {filesystem}") + + class FileInformation(ctypes.Structure): + _fields_ = [ + ("attributes", ctypes.c_uint32), + ("times", ctypes.c_uint32 * 6), + ("volume", ctypes.c_uint32), + ("size_high", ctypes.c_uint32), + ("size_low", ctypes.c_uint32), + ("links", ctypes.c_uint32), + ("index_high", ctypes.c_uint32), + ("index_low", ctypes.c_uint32), + ] + + kernel = ctypes.WinDLL("kernel32", use_last_error=True) + query = kernel.GetFileInformationByHandle + query.argtypes = [wintypes.HANDLE, wintypes.LPVOID] + query.restype = wintypes.BOOL + information = FileInformation() + if not query(handle, ctypes.byref(information)): + raise ctypes.WinError(ctypes.get_last_error()) + index = (information.index_high << 32) | information.index_low + if not index: + raise OSError(errno.ENOTSUP, "No usable legacy file identity") + return _WindowsFileIdentity("legacy64", information.volume, index.to_bytes(8, "little")) + + +def _windows_file_id( + handle: int, *, kind: _IdentityKind | None = None +) -> _WindowsFileIdentity: + """Select a supported identity once, or query the already selected scheme.""" + if kind == "legacy64": + return _windows_legacy_file_id(handle) + import ctypes + from ctypes import wintypes + + class FileIdInfo(ctypes.Structure): + _fields_ = [ + ("volume", ctypes.c_ulonglong), + ("file_id", ctypes.c_ubyte * 16), + ] + + kernel = ctypes.WinDLL("kernel32", use_last_error=True) + info = kernel.GetFileInformationByHandleEx + info.argtypes = [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD] + info.restype = wintypes.BOOL + identity = FileIdInfo() + if not info(handle, 18, ctypes.byref(identity), ctypes.sizeof(identity)): + error = ctypes.get_last_error() + if kind is None and error in (1, 50, 87): + return _windows_legacy_file_id(handle) + raise ctypes.WinError(error) + value = bytes(identity.file_id) + if not any(value): + if kind is None: + return _windows_legacy_file_id(handle) + raise OSError(errno.ENOTSUP, "No usable extended file identity") + return _WindowsFileIdentity("fileid128", identity.volume, value) + + +def _windows_stat(handle: int) -> os.stat_result: + """Get Python's native metadata without taking ownership of a borrowed handle.""" + import _winapi + import msvcrt + + process = _winapi.GetCurrentProcess() + duplicate = _winapi.DuplicateHandle( + process, handle, process, 0, False, _winapi.DUPLICATE_SAME_ACCESS + ) + try: + fd = msvcrt.open_osfhandle(duplicate, os.O_RDONLY | os.O_NOINHERIT) + except BaseException: + _winapi.CloseHandle(duplicate) + raise + try: + return os.fstat(fd) + finally: + os.close(fd) + + @contextmanager def windows_read_fd(handle: int) -> Iterator[int]: """Read the validated object through an independently owned duplicate.""" diff --git a/src/specify_cli/_file_policy.py b/src/specify_cli/_file_policy.py index e675c9b614..1adae7c28e 100644 --- a/src/specify_cli/_file_policy.py +++ b/src/specify_cli/_file_policy.py @@ -33,12 +33,13 @@ def read_project_options(project_root: Path) -> dict[str, Any]: """Read without following configuration links; only absence defaults.""" try: files = FileHelper(project_root) - except (OSError, RuntimeError) as exc: + except (OSError, FileHelperError, RuntimeError) as exc: raise ProjectPolicyError( f"Cannot establish project root for {INIT_OPTIONS_FILE}: {exc}" ) from exc try: - text = files.read_text(INIT_OPTIONS_FILE) + with files: + text = files.read_text(INIT_OPTIONS_FILE) except FileNotFoundError: return {} except (OSError, UnicodeError, FileHelperError) as exc: @@ -60,7 +61,7 @@ def project_files(project_root: Path) -> FileHelper: options = read_project_options(project_root) try: return FileHelper(project_root, allow_symlinks=options.get("allow_symlinks", False)) - except (OSError, RuntimeError) as exc: + except (OSError, FileHelperError, RuntimeError) as exc: raise ProjectPolicyError(f"Cannot establish project filesystem boundary: {exc}") from exc @@ -74,19 +75,19 @@ def save_project_options(project_root: Path, options: dict[str, Any]) -> None: except (TypeError, ValueError, RecursionError) as exc: raise ProjectPolicyError(f"Cannot encode {INIT_OPTIONS_FILE} as JSON: {exc}") from exc try: - files = FileHelper(project_root) - # Validate the entire destination before creating even .specify. - try: - files.read_text(INIT_OPTIONS_FILE) - except FileNotFoundError: - pass - from .integrations._file_changes import after_file_change, before_file_change + with FileHelper(project_root) as files: + # Validate the entire destination before creating even .specify. + try: + files.read_text(INIT_OPTIONS_FILE) + except FileNotFoundError: + pass + from .integrations._file_changes import after_file_change, before_file_change - destination = project_root / INIT_OPTIONS_FILE - before_file_change(destination) - files.mkdir(".specify", exist_ok=True) - files.overwrite_text(INIT_OPTIONS_FILE, content) - after_file_change(destination) + destination = project_root / INIT_OPTIONS_FILE + before_file_change(destination) + files.mkdir(".specify", exist_ok=True) + files.overwrite_text(INIT_OPTIONS_FILE, content) + after_file_change(destination) except (OSError, UnicodeError, FileHelperError, RuntimeError) as exc: raise ProjectPolicyError( f"Cannot write {INIT_OPTIONS_FILE}: {exc}. " @@ -127,11 +128,11 @@ def preflight_init_root(target: Path) -> Path: if target.exists() or target.is_symlink(): read_project_options(target) else: - files = FileHelper(_existing_init_parent(target)) - try: - files.read_bytes(target) - except FileNotFoundError: - pass + with FileHelper(_existing_init_parent(target)) as files: + try: + files.read_bytes(target) + except FileNotFoundError: + pass return target.resolve() except (OSError, FileHelperError, RuntimeError) as exc: raise ProjectPolicyError( @@ -148,7 +149,9 @@ def prepare_init_root(target: Path) -> Path: target = target.absolute() _validate_init_traversal(target) if target.exists() or target.is_symlink(): - FileHelper(target) + with FileHelper(target): + pass return target - FileHelper(_existing_init_parent(target)).mkdir(target, parents=True, exist_ok=True) + with FileHelper(_existing_init_parent(target)) as files: + files.mkdir(target, parents=True, exist_ok=True) return target diff --git a/src/specify_cli/bundles/adapters.py b/src/specify_cli/bundles/adapters.py index b88969400d..7853254d3e 100644 --- a/src/specify_cli/bundles/adapters.py +++ b/src/specify_cli/bundles/adapters.py @@ -268,13 +268,16 @@ def _validate_redirect(_old_url: str, new_url: str) -> None: # server-side availability responses (408, 429, 5xx) fall back to the # snapshot. Any other 4xx (404, 403, ...) is definitive and must # surface as a hard error. - if exc.code in _TRANSIENT_HTTP_STATUS_CODES or exc.code >= 500: - raise _CatalogUnavailable( + try: + if exc.code in _TRANSIENT_HTTP_STATUS_CODES or exc.code >= 500: + raise _CatalogUnavailable( + f"Failed to fetch catalog from {url}: HTTP {exc.code} {exc.reason}" + ) from exc + raise BundlerError( f"Failed to fetch catalog from {url}: HTTP {exc.code} {exc.reason}" ) from exc - raise BundlerError( - f"Failed to fetch catalog from {url}: HTTP {exc.code} {exc.reason}" - ) from exc + finally: + exc.close() except urllib.error.URLError as exc: # urllib wraps a TLS handshake failure as URLError(reason=); # a certificate-verification failure is a security failure, not a diff --git a/src/specify_cli/command_init.py b/src/specify_cli/command_init.py index 77b851f077..2a26d2c89f 100644 --- a/src/specify_cli/command_init.py +++ b/src/specify_cli/command_init.py @@ -207,6 +207,18 @@ def _install_extension_during_init(project_path: Path, ext_spec: str, speckit_ve return f"{manifest.name} v{manifest.version} installed" +def ensure_constitution_from_template(project_path: Path, tracker: Any | None = None) -> None: + """Materialize the resolved constitution template into project memory. + + The implementation lives on the package so init and other commands share + one resolver. This wrapper keeps the historical ``command_init`` import + path used by callers and tests. + """ + from . import ensure_constitution_from_template as materialize + + materialize(project_path, tracker) + + def _shell_quote_arg(value: str) -> str: """Quote *value* as one argument for the shells of the host OS. diff --git a/src/specify_cli/file_helper.py b/src/specify_cli/file_helper.py index f293d53b2e..af15246f66 100644 --- a/src/specify_cli/file_helper.py +++ b/src/specify_cli/file_helper.py @@ -6,15 +6,29 @@ import stat import sys import tempfile +from collections import OrderedDict from collections.abc import Iterator from contextlib import ExitStack, contextmanager +from copy import copy from dataclasses import dataclass, field from pathlib import Path, PurePath, PureWindowsPath from typing import TypeVar +from weakref import finalize + +from specify_cli._file_handles import ( + _WindowsFileIdentity, _windows_delete, _windows_directory_names, _windows_entry, + _windows_file_id, _windows_handle, _windows_mode, _windows_overwrite_fd, + _windows_readlink, _windows_stat, windows_read_fd, +) -from specify_cli._file_handles import _windows_handle, _windows_overwrite_fd, windows_read_fd _PathType = TypeVar("_PathType", bound=PurePath) +_DELETE_DIR_FD_SUPPORTED = ( + {os.open, os.stat, os.readlink, os.unlink, os.rmdir} <= os.supports_dir_fd + and os.stat in os.supports_follow_symlinks + and os.scandir in os.supports_fd +) +_DELETE_DIRECTORY_CACHE_SIZE = 8 # Wrapping os.open must not change the underlying platform capability. _POSIX_OPEN = os.open @@ -45,6 +59,122 @@ class UnsupportedPathError(FileHelperError): """An accessed object cannot be used by the requested operation.""" +@dataclass(frozen=True) +class _WindowsDirectory: + path: Path + handle: int + + +@dataclass +class _WalkDirectories: + root: Path + root_handle: int | _WindowsDirectory + flags: int + resources: ExitStack + opened: dict[Path, _WindowsDirectory] = field(default_factory=dict) + current: tuple[Path, int] | None = field(default=None, init=False) + + def __post_init__(self) -> None: + if isinstance(self.root_handle, int): + self.resources.callback(self._release_current) + + def _release_current(self) -> None: + current, self.current = self.current, None + if current is not None: + os.close(current[1]) + + def _posix_directory(self, path: Path, root_fd: int) -> int: + current_path, parent = self.current or (self.root, root_fd) + if path == current_path: + return parent + if path.parent != current_path: + # Re-anchor jumps, including "..", rather than following a moved + # directory's physical parent outside the retained root. + self._release_current() + current_path, parent = self.root, root_fd + for part in path.relative_to(current_path).parts: + child = os.open(part, self.flags, dir_fd=parent) + previous = self.current + current_path = current_path / part + self.current = (current_path, child) + if previous is not None: + os.close(previous[1]) + parent = child + return parent + + def directory(self, path: Path) -> int | _WindowsDirectory: + path.relative_to(self.root) + if isinstance(self.root_handle, int): + return self._posix_directory(path, self.root_handle) + if path == self.root: + return self.root_handle + if path not in self.opened: + parent = self.directory(path.parent) + if not isinstance(parent, _WindowsDirectory): + raise FileHelperError("Expected a native Windows directory") + try: + handle = self.resources.enter_context(_windows_handle( + Path(path.name), directory=True, parent=parent.handle + )) + except OSError as exc: + if exc.errno == errno.EINVAL and getattr(exc, "winerror", None) is None: + raise NotADirectoryError( + errno.ENOTDIR, "Expected a directory", str(path) + ) from exc + raise + self.opened[path] = _WindowsDirectory(path, handle) + return self.opened[path] + + +@dataclass(frozen=True) +class _DeletionEntry: + path: Path + directory: bool + children: tuple["_DeletionEntry", ...] = () + + +@dataclass +class _DeletionDirectories: + root: Path + root_fd: int + flags: int + resources: ExitStack + opened: OrderedDict[Path, int] = field(default_factory=OrderedDict) + + def __post_init__(self) -> None: + self.resources.callback(self.close) + + def close(self) -> None: + while self.opened: + _, fd = self.opened.popitem() + os.close(fd) + + def discard(self, path: Path) -> None: + fd = self.opened.pop(path, None) + if fd is not None: + os.close(fd) + + def directory(self, path: Path) -> int: + path.relative_to(self.root) + ancestor = path + suffix = [] + while ancestor != self.root and ancestor not in self.opened: + suffix.append(ancestor.name) + ancestor = ancestor.parent + parent = self.root_fd if ancestor == self.root else self.opened[ancestor] + if ancestor in self.opened: + self.opened.move_to_end(ancestor) + for name in reversed(suffix): + child = os.open(name, self.flags, dir_fd=parent) + ancestor = ancestor / name + self.opened[ancestor] = child + if len(self.opened) > _DELETE_DIRECTORY_CACHE_SIZE: + _, oldest = self.opened.popitem(last=False) + os.close(oldest) + parent = child + return parent + + @dataclass(frozen=True) class FileHelper: """Own operations beneath one trusted root with an immutable link policy. @@ -56,14 +186,72 @@ class FileHelper: root: Path allow_symlinks: bool = False _canonical_root: Path = field(init=False, repr=False) + _root_stat: os.stat_result = field(init=False, repr=False, compare=False) + _root_anchor: int | Path | None = field(init=False, repr=False, compare=False) + _root_anchor_error: OSError | None = field(init=False, repr=False, compare=False) + _windows_root_id: _WindowsFileIdentity | None = field(init=False, repr=False, compare=False) + _windows_root_handle: int | None = field(init=False, repr=False, compare=False) + _root_cleanup: finalize = field(init=False, repr=False, compare=False) def __post_init__(self) -> None: root = Path(self.root).absolute() canonical = root.resolve(strict=True) - if not canonical.is_dir(): + root_stat = canonical.stat() + if not stat.S_ISDIR(root_stat.st_mode): raise NotADirectoryError(root) object.__setattr__(self, "root", root) object.__setattr__(self, "_canonical_root", canonical) + object.__setattr__(self, "_root_stat", root_stat) + with ExitStack() as resources: + anchor: int | Path | None = None + anchor_error: OSError | None = None + windows_root_id: _WindowsFileIdentity | None = None + windows_root_handle: int | None = None + if os.name == "nt": + with ExitStack() as reference: + try: + handle = reference.enter_context( + _windows_handle(canonical, directory=True, pin=False) + ) + self._check_deletion_root(_windows_stat(handle)) + windows_root_id = _windows_file_id(handle) + except OSError as exc: + # Other operations do not require deletion's handle capability. + exc.__traceback__ = None + anchor_error = exc + else: + self._check_deletion_root(canonical.stat()) + resources.enter_context(reference.pop_all()) + anchor = canonical + windows_root_handle = handle + elif ( + _DELETE_DIR_FD_SUPPORTED + and getattr(os, "O_NOFOLLOW", 0) + and getattr(os, "O_DIRECTORY", 0) + ): + anchor = os.open(canonical, self._directory_flags()) + resources.callback(os.close, anchor) + self._check_deletion_root(os.fstat(anchor)) + object.__setattr__(self, "_root_anchor", anchor) + object.__setattr__(self, "_root_anchor_error", anchor_error) + object.__setattr__(self, "_windows_root_id", windows_root_id) + object.__setattr__(self, "_windows_root_handle", windows_root_handle) + object.__setattr__(self, "_root_cleanup", finalize(self, resources.pop_all().close)) + + def close(self) -> None: + """Release retained root handles; closing more than once is harmless.""" + self._root_cleanup() + + def _require_open(self) -> None: + if not self._root_cleanup.alive: + raise FileHelperError("FileHelper is closed") + + def __enter__(self) -> "FileHelper": + self._require_open() + return self + + def __exit__(self, *args: object) -> None: + self.close() def _parts(self, path: PurePath) -> tuple[str, ...]: original = path @@ -83,8 +271,11 @@ def _parts(self, path: PurePath) -> tuple[str, ...]: raise PathEscapeError(f"Path is outside root {self.root}: {original}") @staticmethod - def _entry_mode(path: Path) -> int: - entry = path.lstat() + def _entry_mode(path: Path, *, dir_fd: int | None = None) -> int: + entry = ( + path.lstat() if dir_fd is None + else os.stat(path.name, dir_fd=dir_fd, follow_symlinks=False) + ) if ( getattr(entry, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT and not stat.S_ISLNK(entry.st_mode) @@ -101,10 +292,13 @@ def _walk( allow_missing: bool = False, follow_leaf: bool = True, links: tuple[Path, ...] = (), + directories: _WalkDirectories | None = None, ) -> Path: current = self._canonical_root for index, part in enumerate(parts): - if not current.is_dir(): + directory = directories.directory(current) if directories is not None else None + directory_fd = directory if isinstance(directory, int) else None + if directories is None and not current.is_dir(): if not (allow_missing and not current.exists()): raise NotADirectoryError(current) if part == "..": @@ -114,7 +308,9 @@ def _walk( continue candidate = current / part try: - mode = self._entry_mode(candidate) + mode = self._deletion_entry_mode(candidate, parent=directory) if ( + isinstance(directory, _WindowsDirectory) + ) else self._entry_mode(candidate, dir_fd=directory_fd) except FileNotFoundError: if not allow_missing: raise @@ -130,12 +326,20 @@ def _walk( return candidate if candidate in links or len(links) >= 40: raise UnsupportedPathError(f"Symlink cycle or excessive chain: {candidate}") - target = Path(os.readlink(candidate)) + if isinstance(directory, _WindowsDirectory): + with _windows_entry(directory.handle, part) as handle: + target = Path(_windows_readlink(handle)) + elif directory_fd is None: + target = Path(os.readlink(candidate)) + else: + target = Path(os.readlink(part, dir_fd=directory_fd)) target_parts = self._parts(target) if not target.is_absolute(): target_parts = current.relative_to(self._canonical_root).parts + target_parts # Resolve the link target strictly, even when creating a new child. - current = self._walk(target_parts, links=links + (candidate,)) + current = self._walk( + target_parts, links=links + (candidate,), directories=directories + ) elif stat.S_ISDIR(mode) or stat.S_ISREG(mode): current = candidate else: @@ -143,15 +347,25 @@ def _walk( return current def _path( - self, path: Path | str, *, allow_missing: bool = False, follow_leaf: bool = True + self, path: Path | str, *, allow_missing: bool = False, follow_leaf: bool = True, + root_handle: int | _WindowsDirectory | None = None, ) -> Path: + self._require_open() original = Path(path) parts = self._parts(original) if ".." in parts: raise PathEscapeError(f"Parent traversal is not an operation path: {original}") - return self._walk( - parts, allow_missing=allow_missing, follow_leaf=follow_leaf - ) + with ExitStack() as resources: + directories = ( + _WalkDirectories( + self._canonical_root, root_handle, + 0 if isinstance(root_handle, _WindowsDirectory) else self._directory_flags(), resources, + ) + if root_handle is not None else None + ) + return self._walk( + parts, allow_missing=allow_missing, follow_leaf=follow_leaf, directories=directories + ) @staticmethod def _require_file(path: Path) -> None: @@ -211,11 +425,7 @@ def _posix_directory(self, directory: Path, *, unsupported_message: str) -> Iter and _POSIX_OPEN in os.supports_dir_fd ): raise OSError(errno.ENOTSUP, unsupported_message) - access = getattr(os, "O_SEARCH", 0) or getattr(os, "O_PATH", 0) - if not access: - # Older Darwin Python builds omit the kernel's O_EXEC/O_SEARCH bit. - access = 0x40000000 if sys.platform == "darwin" else os.O_RDONLY - flags = access | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) + flags = self._directory_flags() parent = os.open(self._canonical_root, flags) try: for part in parts: @@ -354,37 +564,217 @@ def symlink(self, target: Path | str, path: Path | str) -> None: resolved = self._walk(target_parts) destination.symlink_to(target, target_is_directory=resolved.is_dir()) - def _deletion_plan(self, path: Path, *, recursive: bool) -> list[tuple[Path, bool]]: - mode = self._entry_mode(path) + @staticmethod + def _directory_flags() -> int: + access = getattr(os, "O_PATH", 0) or getattr(os, "O_SEARCH", 0) + if not access: + # Some older Python builds omit Darwin's native search-only flag. + access = (0x40000000 | os.O_DIRECTORY) if sys.platform == "darwin" else os.O_RDONLY + return access | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) + + def _check_deletion_root(self, current: os.stat_result) -> None: + if not os.path.samestat(self._root_stat, current): + raise FileHelperError(f"Established root changed during deletion: {self.root}") + + @contextmanager + def _deletion_root(self) -> Iterator[int | _WindowsDirectory]: + """Borrow the root pinned when this helper was established.""" + self._require_open() + if self._root_anchor is None: + if self._root_anchor_error is not None: + error = copy(self._root_anchor_error) + # OSError's copy protocol omits its native Windows error slot. + if hasattr(self._root_anchor_error, "winerror"): + error.winerror = self._root_anchor_error.winerror + raise error + raise OSError(errno.ENOTSUP, "Handle-based deletion is unsupported on this platform") + if isinstance(self._root_anchor, Path): + reference = self._windows_root_handle + identity = self._windows_root_id + if reference is None or identity is None: + raise FileHelperError("Missing retained Windows root identity") + with ExitStack() as resources: + for ancestor in reversed(self._root_anchor.parents): + resources.enter_context(_windows_handle(ancestor, directory=True)) + handle = resources.enter_context( + _windows_handle(self._root_anchor, directory=True) + ) + selected = _windows_file_id(handle, kind=identity.kind) + retained = _windows_file_id(reference, kind=identity.kind) + if selected != retained: + raise FileHelperError(f"Established root changed during deletion: {self.root}") + yield _WindowsDirectory(self._canonical_root, handle) + else: + self._check_deletion_root(self._canonical_root.stat()) + yield self._root_anchor + + @contextmanager + def _child_deletion_directory( + self, parent: int | _WindowsDirectory, name: str, *, readable: bool = False + ) -> Iterator[int | _WindowsDirectory]: + if isinstance(parent, _WindowsDirectory): + with _windows_handle( + Path(name), directory=True, parent=parent.handle + ) as handle: + yield _WindowsDirectory(parent.path / name, handle) + return + flags = ( + os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0) + if readable else self._directory_flags() + ) + child = os.open(name, flags, dir_fd=parent) + try: + yield child + finally: + os.close(child) + + @contextmanager + def _deletion_directory( + self, path: Path, *, root: int | _WindowsDirectory + ) -> Iterator[int | _WindowsDirectory]: + parts = path.relative_to(self._canonical_root).parts + if isinstance(root, int): + with ExitStack() as resources: + directories = _WalkDirectories( + self._canonical_root, root, self._directory_flags(), resources + ) + yield directories.directory(path) + return + with ExitStack() as resources: + parent = root + for part in parts: + parent = resources.enter_context(self._child_deletion_directory(parent, part)) + yield parent + + @staticmethod + def _windows_entry_mode(handle: int, path: Path) -> int: + try: + return _windows_mode(handle) + except OSError as exc: + if exc.errno == errno.ELOOP and getattr(exc, "winerror", None) is None: + raise UnsupportedPathError(f"Unsupported Windows reparse point: {path}") from exc + raise + + def _deletion_entry_mode(self, path: Path, *, parent: int | _WindowsDirectory) -> int: + if isinstance(parent, _WindowsDirectory): + with _windows_entry(parent.handle, path.name) as handle: + return self._windows_entry_mode(handle, path) + return self._entry_mode(path, dir_fd=parent) + + def _deletion_kind(self, path: Path, mode: int) -> bool: if stat.S_ISLNK(mode): if not self.allow_symlinks: raise SymlinkDeniedError(f"Refusing to delete symlink: {path}") - return [(path, False)] + return False if stat.S_ISREG(mode): - return [(path, False)] + return False if not stat.S_ISDIR(mode): raise UnsupportedPathError(f"Unsupported filesystem object: {path}") - plan: list[tuple[Path, bool]] = [] - if recursive: - with os.scandir(path) as entries: - children = sorted((Path(entry.path) for entry in entries)) - for child in children: - plan.extend(self._deletion_plan(child, recursive=True)) - plan.append((path, True)) - return plan + return True + + def _deletion_plan( + self, path: Path, *, recursive: bool, parent: int | _WindowsDirectory + ) -> _DeletionEntry: + if isinstance(parent, int): + return self._posix_deletion_plan(path, recursive=recursive, parent=parent) + directory = self._deletion_kind(path, self._deletion_entry_mode(path, parent=parent)) + children: tuple[_DeletionEntry, ...] = () + if directory and recursive: + with self._child_deletion_directory(parent, path.name, readable=True) as child_directory: + if not isinstance(child_directory, _WindowsDirectory): + raise FileHelperError("Expected a native Windows directory") + names = sorted(_windows_directory_names(child_directory.handle)) + child_plans = [] + for name in names: + child_plans.append( + self._deletion_plan(path / name, recursive=True, parent=child_directory) + ) + children = tuple(child_plans) + return _DeletionEntry(path, directory, children) + + def _posix_deletion_plan( + self, path: Path, *, recursive: bool, parent: int + ) -> _DeletionEntry: + pending: list[tuple[Path, list[str] | None]] = [(path, None)] + completed: dict[Path, _DeletionEntry] = {} + with ExitStack() as resources: + directories = _DeletionDirectories( + path.parent, parent, self._directory_flags(), resources + ) + while pending: + entry, children = pending.pop() + if children is not None: + completed[entry] = _DeletionEntry( + entry, True, tuple(completed.pop(entry / name) for name in children) + ) + continue + entry_parent = directories.directory(entry.parent) + directory = self._deletion_kind( + entry, self._deletion_entry_mode(entry, parent=entry_parent) + ) + if not (directory and recursive): + completed[entry] = _DeletionEntry(entry, directory) + continue + with self._child_deletion_directory( + entry_parent, entry.name, readable=True + ) as readable: + with os.scandir(readable) as entries: + names = sorted(child.name for child in entries) + pending.append((entry, names)) + for name in reversed(names): + pending.append((entry / name, None)) + return completed[path] + + def _delete_plan(self, entry: _DeletionEntry, *, parent: int | _WindowsDirectory) -> None: + if isinstance(parent, int): + self._posix_delete_plan(entry, parent=parent) + return + with _windows_entry(parent.handle, entry.path.name, deleting=True) as handle: + directory = self._deletion_kind( + entry.path, self._windows_entry_mode(handle, entry.path) + ) + if directory != entry.directory: + raise FileHelperError(f"Destination changed during deletion: {entry.path}") + if directory and entry.children: + child_directory = _WindowsDirectory(entry.path, handle) + for child in entry.children: + self._delete_plan(child, parent=child_directory) + _windows_delete(handle) + + def _posix_delete_plan(self, entry: _DeletionEntry, *, parent: int) -> None: + pending = [(entry, False)] + with ExitStack() as resources: + # Do not reuse preflight handles: parent replacements must be checked + # afresh before any removal. + directories = _DeletionDirectories( + entry.path.parent, parent, self._directory_flags(), resources + ) + while pending: + selected, ready = pending.pop() + selected_parent = directories.directory(selected.path.parent) + directory = self._deletion_kind( + selected.path, + self._deletion_entry_mode(selected.path, parent=selected_parent), + ) + if directory != selected.directory: + raise FileHelperError(f"Destination changed during deletion: {selected.path}") + if directory and selected.children and not ready: + pending.append((selected, True)) + for child in reversed(selected.children): + pending.append((child, False)) + continue + if directory: + os.rmdir(selected.path.name, dir_fd=selected_parent) + directories.discard(selected.path) + else: + os.unlink(selected.path.name, dir_fd=selected_parent) def delete(self, path: Path | str, *, recursive: bool = False) -> None: """Delete an entry; recursive deletion never follows descendant links.""" - destination = self._path(path, follow_leaf=False) - if destination == self._canonical_root: - raise FileHelperError(f"Refusing to delete the established root: {self.root}") - plan = self._deletion_plan(destination, recursive=recursive) - for entry, directory in plan: - # Recheck accessed parents/leaf before each mutation, not just preflight. - checked = self._path(entry, follow_leaf=False) - if checked != entry: - raise FileHelperError(f"Destination changed during deletion: {entry}") - if directory: - entry.rmdir() - else: - entry.unlink() + with self._deletion_root() as root: + destination = self._path(path, follow_leaf=False, root_handle=root) + if destination == self._canonical_root: + raise FileHelperError(f"Refusing to delete the established root: {self.root}") + with self._deletion_directory(destination.parent, root=root) as parent: + plan = self._deletion_plan(destination, recursive=recursive, parent=parent) + self._delete_plan(plan, parent=parent) diff --git a/src/specify_cli/integration_state.py b/src/specify_cli/integration_state.py index ae29b833a8..5e9afb8347 100644 --- a/src/specify_cli/integration_state.py +++ b/src/specify_cli/integration_state.py @@ -46,7 +46,7 @@ def _read_integration_json_data( files = FileHelper(project_root) except FileNotFoundError: return None, None - except (OSError, RuntimeError) as exc: + except (OSError, FileHelperError, RuntimeError) as exc: return None, IntegrationReadError( kind="os", detail=f"Cannot establish project root for {INTEGRATION_JSON}: {exc}" ) @@ -57,7 +57,8 @@ def _read_integration_json_data( # other OSErrors (which become loud errors via the IntegrationReadError # path). try: - raw = files.read_text(INTEGRATION_JSON, encoding="utf-8") + with files: + raw = files.read_text(INTEGRATION_JSON, encoding="utf-8") except FileNotFoundError: return None, None except IsADirectoryError as exc: @@ -245,44 +246,44 @@ def write_integration_json( State reads and writes deny links below that root, independently of any lifecycle transaction or operational symlink opt-in. """ - files = FileHelper(project_root) - # Reject the full destination before an observer can snapshot its target. - try: - files.read_bytes(INTEGRATION_JSON) - except FileNotFoundError: - pass - except SymlinkDeniedError as exc: - raise SymlinkDeniedError(_SYMLINK_STATE_ERROR) from exc - dest = project_root / INTEGRATION_JSON - - integration_key = clean_integration_key(integration_key) - installed = dedupe_integration_keys(installed_integrations or []) - if integration_key and integration_key not in installed: - installed.insert(0, integration_key) - if not integration_key and installed: - integration_key = installed[0] - - normalized_settings = normalize_integration_settings(settings or {}) - normalized_settings = { - key: normalized_settings[key] for key in installed if key in normalized_settings - } - - data: dict[str, Any] = { - "version": version, - "integration_state_schema": INTEGRATION_STATE_SCHEMA, - "installed_integrations": installed, - "integration_settings": normalized_settings, - } - if integration_key: - data["integration"] = integration_key - data["default_integration"] = integration_key - - from .integrations._file_changes import after_file_change, before_file_change - - try: - before_file_change(dest) - files.mkdir(".specify", exist_ok=True) - files.overwrite_text(INTEGRATION_JSON, json.dumps(data, indent=2) + "\n", encoding="utf-8") - after_file_change(dest) - except SymlinkDeniedError as exc: - raise SymlinkDeniedError(_SYMLINK_STATE_ERROR) from exc + with FileHelper(project_root) as files: + # Reject the full destination before an observer can snapshot its target. + try: + files.read_bytes(INTEGRATION_JSON) + except FileNotFoundError: + pass + except SymlinkDeniedError as exc: + raise SymlinkDeniedError(_SYMLINK_STATE_ERROR) from exc + dest = project_root / INTEGRATION_JSON + + integration_key = clean_integration_key(integration_key) + installed = dedupe_integration_keys(installed_integrations or []) + if integration_key and integration_key not in installed: + installed.insert(0, integration_key) + if not integration_key and installed: + integration_key = installed[0] + + normalized_settings = normalize_integration_settings(settings or {}) + normalized_settings = { + key: normalized_settings[key] for key in installed if key in normalized_settings + } + + data: dict[str, Any] = { + "version": version, + "integration_state_schema": INTEGRATION_STATE_SCHEMA, + "installed_integrations": installed, + "integration_settings": normalized_settings, + } + if integration_key: + data["integration"] = integration_key + data["default_integration"] = integration_key + + from .integrations._file_changes import after_file_change, before_file_change + + try: + before_file_change(dest) + files.mkdir(".specify", exist_ok=True) + files.overwrite_text(INTEGRATION_JSON, json.dumps(data, indent=2) + "\n", encoding="utf-8") + after_file_change(dest) + except SymlinkDeniedError as exc: + raise SymlinkDeniedError(_SYMLINK_STATE_ERROR) from exc diff --git a/src/specify_cli/integrations/command_switch.py b/src/specify_cli/integrations/command_switch.py index 35e1d0fc4c..4861e0365f 100644 --- a/src/specify_cli/integrations/command_switch.py +++ b/src/specify_cli/integrations/command_switch.py @@ -36,7 +36,7 @@ def integration_switch( target: str = typer.Argument(help="Integration key to switch to"), script: str | None = typer.Option(None, "--script", help="Script type: sh, ps, or py (default: from init-options.json or platform default)"), force: bool = typer.Option(False, "--force", help="Force removal of modified files during uninstall of the previous integration"), - refresh_shared_infra: bool = typer.Option(False, "--refresh-shared-infra", help="Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved)"), + refresh_shared_infra: bool = typer.Option(False, "--refresh-shared-infra", help="Overwrite customized shared scripts, templates, and .specify/.gitignore, including when the target is already the default"), integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the target integration'), trust_integration: bool = typer.Option(False, "--trust-integration", help="Authorize executing a reviewed external integration package without prompting"), ): @@ -68,7 +68,7 @@ def integration_switch( "to update managed files/options." ) raise typer.Exit(1) - if force: + if force or refresh_shared_infra: raw_options, parsed_options = _resolve_integration_options( target_integration, current, target, None ) @@ -112,7 +112,7 @@ def integration_switch( installed_keys, raw_options=raw_options, parsed_options=parsed_options, - refresh_templates_force=force, + refresh_templates_force=force or refresh_shared_infra, ) manifest, unmodified_files = _snapshot_manifest_before_registration(project_root, target) _register_extensions_for_agent( diff --git a/src/specify_cli/workflows/_operation_list.py b/src/specify_cli/workflows/_operation_list.py index 3f0fa902d5..4844207a42 100644 --- a/src/specify_cli/workflows/_operation_list.py +++ b/src/specify_cli/workflows/_operation_list.py @@ -3,6 +3,7 @@ from __future__ import annotations from dataclasses import dataclass +from contextlib import ExitStack from itertools import islice from pathlib import Path import stat @@ -95,33 +96,34 @@ def list_workflows(request: WorkflowListRequest) -> WorkflowListResult: raise WorkflowListError( "invalid_limit", f"limit must be between 1 and {WORKFLOW_LIST_MAX_LIMIT}" ) - try: - # Unlike is_dir(), stat() preserves permission errors on Python 3.14. + with ExitStack() as owners: try: - root_is_directory = stat.S_ISDIR(root.stat().st_mode) - except (FileNotFoundError, NotADirectoryError, ValueError): - root_is_directory = False - if not root_is_directory: - raise WorkflowListError( - "not_a_spec_kit_project", - "Not a Spec Kit project (no .specify/ directory)", - ) - files = project_files(root) - if not (root / ".specify").is_dir(): - raise WorkflowListError( - "not_a_spec_kit_project", - "Not a Spec Kit project (no .specify/ directory)", - ) - validate_workflow_storage(root) - except (ProjectPolicyError, WorkflowStorageError, OSError) as exc: - raise WorkflowListError("unsafe_workflow_storage", str(exc)) from exc + # Unlike is_dir(), stat() preserves permission errors on Python 3.14. + try: + root_is_directory = stat.S_ISDIR(root.stat().st_mode) + except (FileNotFoundError, NotADirectoryError, ValueError): + root_is_directory = False + if not root_is_directory: + raise WorkflowListError( + "not_a_spec_kit_project", + "Not a Spec Kit project (no .specify/ directory)", + ) + files = owners.enter_context(project_files(root)) + if not (root / ".specify").is_dir(): + raise WorkflowListError( + "not_a_spec_kit_project", + "Not a Spec Kit project (no .specify/ directory)", + ) + validate_workflow_storage(root) + except (ProjectPolicyError, WorkflowStorageError, OSError) as exc: + raise WorkflowListError("unsafe_workflow_storage", str(exc)) from exc - try: - installed = WorkflowRegistry(root, read_files=files).list() - except OSError as exc: - raise WorkflowListError( - "workflow_registry_read_failed", f"Failed to read workflow registry: {exc}" - ) from exc + try: + installed = WorkflowRegistry(root, read_files=files).list() + except OSError as exc: + raise WorkflowListError( + "workflow_registry_read_failed", f"Failed to read workflow registry: {exc}" + ) from exc items: list[WorkflowListEntry | WorkflowListWarning] = [] selected = installed.items() if limit is None else islice(installed.items(), limit) diff --git a/tests/conftest.py b/tests/conftest.py index 6fe0c1e2f7..7e566ebfcd 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -62,8 +62,10 @@ def _has_working_bash() -> bool: return True +HAS_BASH = _has_working_bash() + requires_bash = pytest.mark.skipif( - not _has_working_bash(), reason="working bash not available" + not HAS_BASH, reason="working bash not available" ) diff --git a/tests/extensions/git/test_git_extension.py b/tests/extensions/git/test_git_extension.py index 213c5f562d..9de80fac84 100644 --- a/tests/extensions/git/test_git_extension.py +++ b/tests/extensions/git/test_git_extension.py @@ -186,7 +186,7 @@ def test_manifest_validates(self): m = ExtensionManifest(EXT_DIR / "extension.yml") assert m.id == "git" - assert m.version == "1.0.4" + assert m.version == "1.0.5" def test_manifest_commands(self): """Manifest declares expected commands.""" @@ -400,6 +400,142 @@ def test_commit_failure_is_still_reported(self, tmp_path: Path, exe: str): assert commits.stdout.strip() == "0" +@pytest.mark.parametrize( + "exe", + [ + pytest.param( + "pwsh", + marks=pytest.mark.skipif(not HAS_PWSH, reason="pwsh not available"), + id="pwsh", + ), + pytest.param( + WINDOWS_POWERSHELL, + marks=pytest.mark.skipif( + not WINDOWS_POWERSHELL, reason="Windows PowerShell 5.1 not available" + ), + id="windows-powershell-5.1", + ), + ], +) +class TestPowerShellBracketedProjectPath: + def test_initialize_repo(self, tmp_path: Path, exe: str): + """initialize-repo.ps1 reads its config and commits in a path containing [ and ].""" + project = _setup_project(tmp_path / "proj [v2]", git=False) + _write_config(project, 'init_commit_message: "bracketed init"\n') + + result = _run_pwsh("initialize-repo.ps1", project, exe=exe) + + assert result.returncode == 0, result.stdout + result.stderr + log = subprocess.run( + ["git", "log", "--format=%s", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert log.stdout.strip() == "bracketed init" + + def test_create_feature_branch(self, tmp_path: Path, exe: str): + """create-new-feature-branch.ps1 numbers past existing specs in a bracketed path. + + Core common.ps1 goes under .specify/scripts/powershell, where `specify init` + installs it: Windows PowerShell 5.1 started in a bracketed directory begins + in $PSHOME, so core Get-RepoRoot resolves the project from the script location. + """ + project = _setup_project(tmp_path / "proj [v2]") + core_ps = project / ".specify" / "scripts" / "powershell" + core_ps.mkdir(parents=True) + shutil.copy(CORE_COMMON_PS, core_ps / "common.ps1") + (project / "specs" / "001-login-page").mkdir(parents=True) + + result = _run_pwsh( + "create-new-feature-branch.ps1", project, + "-Json", "-ShortName", "payment-export", "Add payment export", + exe=exe, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert json.loads(result.stdout)["BRANCH_NAME"] == "002-payment-export" + branch = subprocess.run( + ["git", "branch", "--show-current"], + cwd=project, capture_output=True, text=True, + ) + assert branch.stdout.strip() == "002-payment-export" + + def test_create_feature_branch_with_git_common_only(self, tmp_path: Path, exe: str): + """Without core scripts, create-new-feature-branch.ps1 loads git-common.ps1 in a bracketed path.""" + project = _setup_project(tmp_path / "proj [v2]") + (project / "scripts" / "powershell" / "common.ps1").unlink() + + result = _run_pwsh( + "create-new-feature-branch.ps1", project, + "-Json", "-ShortName", "payment-export", "Add payment export", + exe=exe, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert json.loads(result.stdout)["BRANCH_NAME"] == "001-payment-export" + + def test_git_common_detects_git(self, tmp_path: Path, exe: str): + """git-common.ps1 Test-HasGit finds the repository at a bracketed path.""" + project = _setup_project(tmp_path / "proj [v2]") + script = EXT_PS / "git-common.ps1" + + result = subprocess.run( + [ + exe, "-NoProfile", "-Command", + f". '{script}'; if (Test-HasGit -RepoRoot '{project}') {{ exit 0 }} else {{ exit 1 }}", + ], + capture_output=True, text=True, + ) + + assert result.returncode == 0, result.stdout + result.stderr + + def test_auto_commit_message_file(self, tmp_path: Path, exe: str): + """auto-commit.ps1 reads its config and -MessageFile in a bracketed path.""" + project = _setup_project(tmp_path / "proj [v2]") + _write_config(project, ( + "commit_style: conventional\n" + "auto_commit:\n" + " default: false\n" + " after_specify:\n" + " enabled: true\n" + )) + (project / "new-file.txt").write_text("content") + msg_file = project / "commit-msg.txt" + msg_file.write_text("feat: add payment export\n") + + result = _run_pwsh( + "auto-commit.ps1", project, "after_specify", "-MessageFile", str(msg_file), + exe=exe, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert not msg_file.exists() + log = subprocess.run( + ["git", "log", "--format=%s", "-1"], + cwd=project, capture_output=True, text=True, + ) + assert log.stdout.strip() == "feat: add payment export" + + def test_auto_commit_keeps_disabled_event(self, tmp_path: Path, exe: str): + """An event disabled in git-config.yml stays off under default: true in a bracketed path.""" + project = _setup_project(tmp_path / "proj [v2]") + _write_config(project, ( + "auto_commit:\n" + " default: true\n" + " after_specify:\n" + " enabled: false\n" + )) + (project / "new-file.txt").write_text("content") + + result = _run_pwsh("auto-commit.ps1", project, "after_specify", exe=exe) + + assert result.returncode == 0, result.stdout + result.stderr + count = subprocess.run( + ["git", "rev-list", "--count", "HEAD"], + cwd=project, capture_output=True, text=True, + ) + assert count.stdout.strip() == "1" + + # ── create-new-feature-branch.sh Tests ────────────────────────────────────────────── diff --git a/tests/integrations/test_integration_state.py b/tests/integrations/test_integration_state.py index ceaa9cc845..c3f53fcbc8 100644 --- a/tests/integrations/test_integration_state.py +++ b/tests/integrations/test_integration_state.py @@ -5,7 +5,8 @@ import pytest from specify_cli._file_policy import project_files, save_project_options -from specify_cli.file_helper import SymlinkDeniedError +from specify_cli.file_helper import FileHelper, FileHelperError, SymlinkDeniedError +from specify_cli import integration_state from specify_cli.integration_state import ( INTEGRATION_JSON, default_integration_key, @@ -18,6 +19,59 @@ from specify_cli.integrations._file_changes import file_change_observer +@pytest.mark.parametrize("reader", [try_read_integration_json, try_read_integration_json_with_raw]) +def test_state_readers_translate_constructor_contract_failure(tmp_path, monkeypatch, reader): + def failed(*args, **kwargs): + raise FileHelperError("root binding failed") + + monkeypatch.setattr(integration_state, "FileHelper", failed) + *states, error = reader(tmp_path) + assert all(state is None for state in states) + assert error is not None and error.kind == "os" + assert "root binding failed" in error.detail + + +@pytest.mark.parametrize("operation", ["read", "read-with-raw", "write"]) +@pytest.mark.parametrize("failure", [False, True]) +def test_managed_state_consumers_close_retained_helpers(tmp_path, monkeypatch, operation, failure): + (tmp_path / ".specify").mkdir() + (tmp_path / INTEGRATION_JSON).write_text('{"integration": "claude"}') + captured = [] + + def owner(*args, **kwargs): + files = FileHelper(*args, **kwargs) + captured.append(files) + return files + + def denied(*args, **kwargs): + raise PermissionError("managed state access denied") + + monkeypatch.setattr(integration_state, "FileHelper", owner) + if failure: + monkeypatch.setattr(FileHelper, "overwrite_text" if operation == "write" else "read_text", denied) + retained_error = None + if operation == "write": + if failure: + with pytest.raises(PermissionError, match="managed state access denied") as raised: + write_integration_json(tmp_path, version="1", integration_key="claude") + retained_error = raised.value + else: + write_integration_json(tmp_path, version="1", integration_key="claude") + else: + reader = try_read_integration_json if operation == "read" else try_read_integration_json_with_raw + *states, retained_error = reader(tmp_path) + if failure: + assert all(state is None for state in states) + assert retained_error is not None and retained_error.kind == "os" + else: + assert all(state is not None for state in states) + assert retained_error is None + assert len(captured) == 1 + assert not captured[0]._root_cleanup.alive + if failure: + assert retained_error is not None + + def test_normalize_integration_state_strips_default_key_without_duplicates(): state = normalize_integration_state( { diff --git a/tests/specify_cli/bundles/test_adapters.py b/tests/specify_cli/bundles/test_adapters.py index 40a9dd0688..3eac29dad9 100644 --- a/tests/specify_cli/bundles/test_adapters.py +++ b/tests/specify_cli/bundles/test_adapters.py @@ -132,6 +132,32 @@ def fake_open_url(url, timeout=10, extra_headers=None, redirect_validator=None): assert not isinstance(excinfo.value, adapters._CatalogUnavailable) +@pytest.mark.parametrize("status", [403, 404, 408, 429, 500, 503]) +@pytest.mark.parametrize("already_closed", [False, True]) +def test_http_error_response_is_closed_before_catalog_error_translation( + monkeypatch, status, already_closed +): + body = io.BytesIO(b"error response") + error = urllib.error.HTTPError( + "https://example.com/catalog.json", status, "response failed", {}, body, + ) + if already_closed: + error.close() + + def failed(*args, **kwargs): + raise error + + monkeypatch.setattr("specify_cli.authentication.http.open_url", failed) + with pytest.raises(BundlerError, match=f"HTTP {status}") as raised: + adapters._http_get_json("team", error.url) + assert raised.value.__cause__ is error + assert isinstance(raised.value, adapters._CatalogUnavailable) == ( + status in (408, 429) or status >= 500 + ) + assert body.closed + assert error.closed + + def test_http_get_json_preserves_malformed_json(monkeypatch): def fake_open_url(url, timeout=10, extra_headers=None, redirect_validator=None): return _FakeResponse(b"not json", url) diff --git a/tests/specify_cli/bundles/test_command_add.py b/tests/specify_cli/bundles/test_command_add.py index 451ab4acf0..5d116177ba 100644 --- a/tests/specify_cli/bundles/test_command_add.py +++ b/tests/specify_cli/bundles/test_command_add.py @@ -6,6 +6,7 @@ from unittest.mock import patch import pytest +import yaml from typer.testing import CliRunner from specify_cli import app @@ -101,6 +102,11 @@ def fake_open_url( encoding="utf-8" ) ) - assert registry["workflows"][bundle_id]["version"] == "1.0.0" + workflow = yaml.safe_load( + (REPO_ROOT / "workflows" / bundle_id / "workflow.yml").read_text( + encoding="utf-8" + ) + ) + assert registry["workflows"][bundle_id]["version"] == workflow["workflow"]["version"] assert FIRSTPARTY_CATALOG_URL in captured_urls assert expected_manifest_url in captured_urls diff --git a/tests/specify_cli/bundles/test_command_install.py b/tests/specify_cli/bundles/test_command_install.py index fb5d8e19fd..59631ae010 100644 --- a/tests/specify_cli/bundles/test_command_install.py +++ b/tests/specify_cli/bundles/test_command_install.py @@ -133,7 +133,12 @@ def test_local_firstparty_bundle_installs_bundled_components_offline( encoding="utf-8" ) ) - assert registry["workflows"][bundle_id]["version"] == "1.0.0" + workflow = yaml.safe_load( + (REPO_ROOT / "workflows" / bundle_id / "workflow.yml").read_text( + encoding="utf-8" + ) + ) + assert registry["workflows"][bundle_id]["version"] == workflow["workflow"]["version"] def test_local_parent_installs_referenced_catalog_components( diff --git a/tests/specify_cli/integrations/test_command_switch.py b/tests/specify_cli/integrations/test_command_switch.py index 84b8bd52b4..0c928a44a1 100644 --- a/tests/specify_cli/integrations/test_command_switch.py +++ b/tests/specify_cli/integrations/test_command_switch.py @@ -32,10 +32,124 @@ check_cleanup_rollback_preserves_directory_mode, ) + +@pytest.fixture(scope="module") +def switch_copilot_commands_template(tmp_path_factory): + return _init_project( + tmp_path_factory.mktemp("switch-copilot-commands"), "copilot", "--commands" + ) + + +def _init_codex_switch_project(tmp_path, target_state, script="sh"): + project = _init_project(tmp_path, "claude") + if target_state != "new": + result = _run_in_project(project, ["integration", "install", "codex", "--script", script]) + assert result.exit_code == 0, result.output + if target_state == "default": + result = _run_in_project(project, ["integration", "use", "codex"]) + assert result.exit_code == 0, result.output + return project + + +def _project_file_state(project): + return { + path.relative_to(project): (path.read_bytes(), path.stat().st_mtime_ns) + for path in project.rglob("*") + if path.is_file() and ".git" not in path.relative_to(project).parts + } + + class TestIntegrationSwitch: - @pytest.mark.parametrize("installed", [False, True]) + @pytest.mark.parametrize("target_state", ["new", "installed", "default"]) + @pytest.mark.parametrize( + "flags", [[], ["--force"], ["--refresh-shared-infra"], ["--force", "--refresh-shared-infra"]], + ids=["none", "force", "refresh", "both"], + ) + def test_switch_shared_infra_refresh_flag_matrix( + self, tmp_path, switch_copilot_commands_template, target_state, flags + ): + """Shared overwrite consent depends on installation state, not teardown consent.""" + if target_state == "default": + project = _copy_project_template(tmp_path, switch_copilot_commands_template) + else: + project = _init_project(tmp_path, "claude") + if target_state == "installed": + result = _run_in_project(project, [ + "integration", "install", "copilot", "--script", "sh", + "--integration-options", "--commands", "--force", + ]) + assert result.exit_code == 0, result.output + + shared_rels = [ + ".specify/scripts/bash/check-prerequisites.sh", + ".specify/templates/plan-template.md", + ".specify/.gitignore", + ] + clean = {rel: (switch_copilot_commands_template / rel).read_bytes() for rel in shared_rels} + assert b"/speckit.plan" in clean[shared_rels[0]] + assert b"/speckit.plan" in clean[shared_rels[1]] + shared_manifest = project / ".specify/integrations/speckit.manifest.json" + prior_hashes = json.loads(shared_manifest.read_bytes())["files"] + customized = {rel: (project / rel).read_bytes() + b"\n# user customization\n" for rel in shared_rels} + for rel, content in customized.items(): + (project / rel).write_bytes(content) + + old_skill = project / ".claude/skills/speckit-plan/SKILL.md" + if target_state != "default": + old_skill.write_bytes(b"User-edited outgoing skill\n") + target_skill = project / ".github/agents/speckit.plan.agent.md" + if target_state != "new": + target_skill.write_bytes(b"User-edited installed skill\n") + target_manifest = project / ".specify/integrations/copilot.manifest.json" + before_target_manifest = target_manifest.read_bytes() + metadata_rels = [ + ".specify/integration.json", ".specify/init-options.json", + ".specify/integrations/speckit.manifest.json", + ] + before_metadata = {rel: (project / rel).read_bytes() for rel in metadata_rels} + + args = ["integration", "switch", "copilot", *flags] + if target_state == "new": + args += ["--script", "sh", "--integration-options", "--commands"] + result = _run_in_project(project, args) + assert result.exit_code == 0, result.output + + overwrite = "--refresh-shared-infra" in flags or (target_state != "new" and "--force" in flags) + actual = {rel: (project / rel).read_bytes() for rel in shared_rels} + expected = clean if overwrite else customized + retained = [rel for rel in shared_rels if actual[rel] == customized[rel]] + assert actual == expected, f"{target_state=} {flags=}: customized shared files retained: {retained}" + + hashes = json.loads(shared_manifest.read_bytes())["files"] + for rel in shared_rels: + assert hashes[rel] == (hashlib.sha256(clean[rel]).hexdigest() if overwrite else prior_hashes[rel]) + state = json.loads((project / ".specify/integration.json").read_bytes()) + assert state["default_integration"] == state["integration"] == "copilot" + assert set(state["installed_integrations"]) == ( + {"claude", "copilot"} if target_state == "installed" else {"copilot"} + ) + options = json.loads((project / ".specify/init-options.json").read_bytes()) + assert options["integration"] == options["ai"] == "copilot" + assert state["integration_settings"]["copilot"]["parsed_options"] == {"commands": True} + if target_state == "new": + assert old_skill.exists() == ("--force" not in flags) + if old_skill.exists(): + assert old_skill.read_bytes() == b"User-edited outgoing skill\n" + else: + assert target_skill.read_bytes() == b"User-edited installed skill\n" + assert target_manifest.read_bytes() == before_target_manifest + if target_state == "installed": + assert old_skill.read_bytes() == b"User-edited outgoing skill\n" + if target_state == "default" and not flags: + assert {rel: (project / rel).read_bytes() for rel in metadata_rels} == before_metadata + assert "already the default integration" in result.output + + @pytest.mark.parametrize( + ("installed", "refresh"), [(False, False), (True, False), (True, True)], + ids=["new", "installed", "installed-refresh"], + ) def test_switch_syncs_manifest_hash_for_preset_override( - self, tmp_path, tasks_preset_src, installed + self, tmp_path, tasks_preset_src, installed, refresh ): """Both switch paths must record the preset's final bytes (#5078).""" project = _init_project(tmp_path, "claude") @@ -47,7 +161,10 @@ def test_switch_syncs_manifest_hash_for_preset_override( result = _run_in_project(project, ["preset", "add", "--dev", str(tasks_preset_src)]) assert result.exit_code == 0, result.output - result = _run_in_project(project, ["integration", "switch", "codex", "--script", "sh"]) + result = _run_in_project(project, [ + "integration", "switch", "codex", "--script", "sh", + *(["--refresh-shared-infra"] if refresh else []), + ]) assert result.exit_code == 0, result.output rel = ".agents/skills/speckit-tasks/SKILL.md" @@ -116,8 +233,9 @@ def test_switch_installed_target_without_readable_manifest_skips_hash_refresh( assert "snapshot manifest hashes for integration 'codex'" in output @pytest.mark.parametrize("command", ["plan", "tasks"]) + @pytest.mark.parametrize("flags", [[], ["--refresh-shared-infra"]], ids=["normal", "refresh"]) def test_switch_installed_target_preserves_modified_manifest_hash( - self, tmp_path, tasks_preset_src, command + self, tmp_path, tasks_preset_src, command, flags ): """Rescaffolding must not bless earlier user edits as pristine (#5078).""" from specify_cli.integrations.manifest import IntegrationManifest @@ -131,7 +249,7 @@ def test_switch_installed_target_preserves_modified_manifest_hash( before = IntegrationManifest.load("codex", project).files[rel] (project / rel).write_bytes(b"User-edited skill\n") - result = _run_in_project(project, ["integration", "switch", "codex"]) + result = _run_in_project(project, ["integration", "switch", "codex", *flags]) assert result.exit_code == 0, result.output manifest = IntegrationManifest.load("codex", project) assert manifest.files[rel] == before, "pre-existing edits must not be recorded as pristine" @@ -244,6 +362,7 @@ def test_switch_invalid_current_manifest_reports_cli_error(self, tmp_path): def test_switch_same_noop(self, tmp_path): project = _init_project(tmp_path, "copilot") + before = _project_file_state(project) old_cwd = os.getcwd() try: os.chdir(project) @@ -252,9 +371,47 @@ def test_switch_same_noop(self, tmp_path): os.chdir(old_cwd) assert result.exit_code == 0 assert "already the default integration" in result.output + assert _project_file_state(project) == before + + @pytest.mark.parametrize( + "flags", [["--force"], ["--refresh-shared-infra"], ["--force", "--refresh-shared-infra"]], + ids=["force", "refresh", "both"], + ) + def test_switch_same_force_refreshes_shared_templates(self, tmp_path, tasks_preset_src, monkeypatch, flags): + import specify_cli + from specify_cli.integrations import command_switch + from specify_cli.integrations.claude import ClaudeIntegration - def test_switch_same_force_refreshes_shared_templates(self, tmp_path): project = _init_project(tmp_path, "claude") + for args in (["extension", "add", "git"], ["preset", "add", "--dev", str(tasks_preset_src)]): + result = _run_in_project(project, args) + assert result.exit_code == 0, result.output + agent_paths = [ + *list((project / ".claude").rglob("*")), + project / ".specify/extensions/.registry", + project / ".specify/presets/.registry", + project / ".specify/integrations/claude.manifest.json", + ] + before = {path: (path.read_bytes(), path.stat().st_mtime_ns) for path in agent_paths if path.is_file()} + refreshes = [] + install_shared_infra = specify_cli._install_shared_infra + + def record_refresh(*args, **kwargs): + refreshes.append(True) + return install_shared_infra(*args, **kwargs) + + monkeypatch.setattr(specify_cli, "_install_shared_infra", record_refresh) + + def unexpected_lifecycle(*args, **kwargs): + pytest.fail("same-default refresh must not set up, tear down, or re-register") + + monkeypatch.setattr(ClaudeIntegration, "setup", unexpected_lifecycle) + monkeypatch.setattr(ClaudeIntegration, "teardown", unexpected_lifecycle) + for name in ( + "_register_extensions_for_agent", "_register_presets_for_agent", + "_unregister_extensions_for_agent", "_unregister_presets_for_agent", + ): + monkeypatch.setattr(command_switch, name, unexpected_lifecycle) template = project / ".specify" / "templates" / "plan-template.md" script = project / ".specify" / "scripts" / "bash" / "check-prerequisites.sh" template.write_text("# custom shared template\n", encoding="utf-8") @@ -265,7 +422,7 @@ def test_switch_same_force_refreshes_shared_templates(self, tmp_path): os.chdir(project) result = runner.invoke(app, [ "integration", "switch", "claude", - "--force", + *flags, ], catch_exceptions=False) finally: os.chdir(old_cwd) @@ -274,30 +431,102 @@ def test_switch_same_force_refreshes_shared_templates(self, tmp_path): assert "managed shared infrastructure refreshed" not in result.output assert "/speckit-plan" in template.read_text(encoding="utf-8") assert "/speckit-plan" in script.read_text(encoding="utf-8") + assert len(refreshes) == 1 + assert {path: (path.read_bytes(), path.stat().st_mtime_ns) for path in before} == before - def test_switch_installed_target_rejects_integration_options(self, tmp_path): + @pytest.mark.parametrize("same_default", [False, True], ids=["installed", "default"]) + @pytest.mark.parametrize( + "flags", [[], ["--force"], ["--refresh-shared-infra"], ["--force", "--refresh-shared-infra"]], + ids=["none", "force", "refresh", "both"], + ) + def test_switch_installed_target_rejects_integration_options(self, tmp_path, same_default, flags): project = _init_project(tmp_path, "claude") - old_cwd = os.getcwd() - try: - os.chdir(project) - install = runner.invoke(app, [ + target = "claude" if same_default else "codex" + if not same_default: + install = _run_in_project(project, [ "integration", "install", "codex", "--script", "sh", - ], catch_exceptions=False) + ]) assert install.exit_code == 0, install.output + before = _project_file_state(project) - result = runner.invoke(app, [ - "integration", "switch", "codex", - "--integration-options", "--bogus", - ]) - finally: - os.chdir(old_cwd) + result = _run_in_project(project, [ + "integration", "switch", target, *flags, + "--integration-options", "--bogus", + ]) assert result.exit_code != 0 assert "--integration-options cannot be used" in result.output + assert _project_file_state(project) == before data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8")) assert data["default_integration"] == "claude" + @pytest.mark.parametrize("target_state", ["installed", "default"]) + def test_switch_refresh_failure_does_not_persist_default(self, tmp_path, target_state): + """A real unsafe destination must fail before runtime metadata commits.""" + project = _init_codex_switch_project(tmp_path, target_state) + templates = project / ".specify/templates" + shutil.rmtree(templates) + templates.write_bytes(b"blocking file, not a directory\n") + before = _project_file_state(project) + + result = _run_in_project(project, ["integration", "switch", "codex", "--refresh-shared-infra"]) + + assert result.exit_code == 1, result.output + assert "Failed to refresh shared infrastructure" in result.output + assert "shared infrastructure refreshed" not in result.output + assert "Default integration set" not in result.output + assert "Default integration remains" not in result.output + assert _project_file_state(project) == before + + @pytest.mark.parametrize("target_state", ["installed", "default"]) + @pytest.mark.parametrize("script_type", ["ps", "py"]) + def test_switch_refresh_uses_stored_script_runtime(self, tmp_path, target_state, script_type): + """Installed refresh uses target settings rather than the outgoing runtime.""" + project = _init_codex_switch_project(tmp_path, target_state, script_type) + clean = tmp_path / "clean" + clean.mkdir() + result = _run_in_project(clean, [ + "init", "--here", "--integration", "codex", "--script", script_type, + "--ignore-agent-tools", + ]) + assert result.exit_code == 0, result.output + selected = (["powershell"] if script_type == "ps" else [ + "python", "powershell" if os.name == "nt" else "bash", + ]) + rels = [ + path.relative_to(clean) for path in (clean / ".specify/scripts").rglob("*") + if path.is_file() and path.parent.name in selected + ] + assert rels + rels += [Path(".specify/templates/plan-template.md"), Path(".specify/.gitignore")] + expected = {rel: (clean / rel).read_bytes() for rel in rels} + for rel in rels: + (project / rel).write_bytes(b"# edited shared runtime\n") + agent_manifest = project / ".specify/integrations/codex.manifest.json" + before_agent_manifest = agent_manifest.read_bytes() + unselected = project / ".specify/scripts/bash/check-prerequisites.sh" + if script_type == "ps": + unselected.write_bytes(b"# leave unselected bash alone\n") + + result = _run_in_project(project, ["integration", "switch", "codex", "--refresh-shared-infra"]) + + assert result.exit_code == 0, result.output + assert {rel: (project / rel).read_bytes() for rel in rels} == expected + assert b"$speckit-plan" in (project / ".specify/templates/plan-template.md").read_bytes() + state = json.loads((project / ".specify/integration.json").read_bytes()) + assert state["default_integration"] == "codex" + assert state["integration_settings"]["codex"]["script"] == script_type + options = json.loads((project / ".specify/init-options.json").read_bytes()) + assert options["script"] == script_type + assert options["integration"] == options["ai"] == "codex" + assert agent_manifest.read_bytes() == before_agent_manifest + shared_manifest = json.loads((project / ".specify/integrations/speckit.manifest.json").read_bytes()) + for rel, content in expected.items(): + assert shared_manifest["files"][rel.as_posix()] == hashlib.sha256(content).hexdigest() + if script_type == "ps": + assert unselected.read_bytes() == b"# leave unselected bash alone\n" + def test_switch_between_integrations(self, tmp_path): project = _init_project(tmp_path, "claude") # Verify claude files exist (claude uses skills) @@ -510,7 +739,8 @@ def test_switch_migrates_extension_commands(self, tmp_path): assert "claude" in registered_commands assert "opencode" not in registered_commands - def test_switch_installed_target_backfills_extension_commands(self, tmp_path): + @pytest.mark.parametrize("flags", [[], ["--refresh-shared-infra"]], ids=["normal", "refresh"]) + def test_switch_installed_target_backfills_extension_commands(self, tmp_path, flags): """Switching to an already-installed agent should register extensions.""" project = _init_project(tmp_path, "claude") @@ -535,7 +765,7 @@ def test_switch_installed_target_backfills_extension_commands(self, tmp_path): ) assert not codex_git_feature.exists() - result = _run_in_project(project, ["integration", "switch", "codex"]) + result = _run_in_project(project, ["integration", "switch", "codex", *flags]) assert result.exit_code == 0, result.output registered = json.loads(registry_path.read_text(encoding="utf-8"))[ @@ -543,6 +773,9 @@ def test_switch_installed_target_backfills_extension_commands(self, tmp_path): ]["git"]["registered_commands"] assert "codex" in registered assert codex_git_feature.exists() + manifest = json.loads((project / ".specify/integrations/codex.manifest.json").read_bytes()) + for rel, digest in manifest["files"].items(): + assert hashlib.sha256((project / rel).read_bytes()).hexdigest() == digest def test_switch_migrates_copilot_skills_extension_commands(self, tmp_path): """Copilot --skills should receive extension skills, not .agent.md files.""" @@ -766,160 +999,82 @@ def test_switch_refreshes_stale_managed_shared_infra(self, tmp_path): assert "/speckit.plan" in updated assert "/speckit-plan" not in updated - def test_switch_preserves_user_customized_shared_infra(self, tmp_path): - """User customizations (hash divergence from manifest) survive switch without --refresh-shared-infra.""" - project = _init_project(tmp_path, "claude") - shared_script = project / ".specify" / "scripts" / "bash" / "common.sh" - - # User customization: append bytes but do NOT update manifest hash, - # so on-disk hash diverges from the recorded one. - original = shared_script.read_bytes() - custom_bytes = original + b"\n# user customization\n" - shared_script.write_bytes(custom_bytes) - - old_cwd = os.getcwd() - try: - os.chdir(project) - result = runner.invoke(app, [ - "integration", "switch", "copilot", - "--integration-options", "--commands", - "--script", "sh", - ], catch_exceptions=False) - finally: - os.chdir(old_cwd) - assert result.exit_code == 0 - assert shared_script.read_bytes() == custom_bytes - assert "Preserved" in result.output - - def test_switch_refresh_shared_infra_overwrites_customizations(self, tmp_path): - """--refresh-shared-infra explicitly overwrites user customizations on switch.""" - project = _init_project(tmp_path, "claude") - shared_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh" - assert "/speckit-plan" in shared_script.read_text(encoding="utf-8") - rendered_bytes = shared_script.read_bytes() - - # User customization (hash diverges from manifest) - custom_bytes = rendered_bytes + b"\n# user customization\n" - shared_script.write_bytes(custom_bytes) - - old_cwd = os.getcwd() - try: - os.chdir(project) - result = runner.invoke(app, [ - "integration", "switch", "copilot", - "--integration-options", "--commands", - "--script", "sh", - "--refresh-shared-infra", - ], catch_exceptions=False) - finally: - os.chdir(old_cwd) - assert result.exit_code == 0 - # Customization is overwritten with the target integration's rendered version. - updated = shared_script.read_text(encoding="utf-8") - assert "# user customization" not in updated - assert "/speckit.plan" in updated - assert "/speckit-plan" not in updated - - def test_switch_preserves_recovered_files(self, tmp_path): - """Regression for #2918: files marked recovered in the manifest are not overwritten. - - When a file already exists on disk before init and is recorded with - ``recovered=True``, ``integration use``/``switch`` must not treat it as - managed even when the on-disk hash matches the manifest hash. - """ - import hashlib - - project = _init_project(tmp_path, "claude") - shared_script = project / ".specify" / "scripts" / "bash" / "setup-tasks.sh" - assert shared_script.is_file() - - # Simulate a team-customized file that was recorded as recovered: - # write custom content, then update the manifest to record its hash - # with the recovered flag set. - custom_bytes = b"#!/usr/bin/env bash\n# team custom workflow\nexit 0\n" - shared_script.write_bytes(custom_bytes) - - manifest_path = project / ".specify" / "integrations" / "speckit.manifest.json" - manifest_data = json.loads(manifest_path.read_text(encoding="utf-8")) - rel = ".specify/scripts/bash/setup-tasks.sh" - manifest_data["files"][rel] = hashlib.sha256(custom_bytes).hexdigest() - manifest_data.setdefault("recovered_files", []).append(rel) - manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8") - - old_cwd = os.getcwd() - try: - os.chdir(project) - result = runner.invoke(app, [ - "integration", "switch", "copilot", - "--script", "sh", - ], catch_exceptions=False) - finally: - os.chdir(old_cwd) - assert result.exit_code == 0 - # Recovered file must NOT be overwritten — team content preserved. - assert shared_script.read_bytes() == custom_bytes - - def test_switch_skips_symlinked_parent_directory(self, tmp_path): - """Regression: if .specify/scripts/bash is a symlink, switch must not write through it. - - Copilot follow-up on #2375: leaf-only symlink check let writes escape - when an *ancestor* directory was symlinked outside the project root. - """ - import sys - if sys.platform.startswith("win"): - import pytest as _pytest - _pytest.skip("Symlink creation typically requires admin on Windows") + @pytest.mark.parametrize("target_state", ["new", "installed", "default"]) + @pytest.mark.parametrize( + "flags", [[], ["--force"], ["--refresh-shared-infra"], ["--force", "--refresh-shared-infra"]], + ids=["none", "force", "refresh", "both"], + ) + def test_switch_preserves_recovered_files(self, tmp_path, target_state, flags): + """Matching hashes never confer ownership on recovered files (#2918).""" + from specify_cli.integrations.manifest import IntegrationManifest - project = _init_project(tmp_path, "claude") - bash_dir = project / ".specify" / "scripts" / "bash" + project = _init_codex_switch_project(tmp_path, target_state) + rels = [ + ".specify/scripts/bash/setup-tasks.sh", + ".specify/templates/plan-template.md", + ".specify/.gitignore", + ] + custom_bytes = b"# team custom workflow\n" + manifest = IntegrationManifest.load("speckit", project) + for rel in rels: + (project / rel).write_bytes(custom_bytes) + manifest.record_existing(rel, recovered=True) + # Stale recovered and edited scripts remain protected even with consent + # to overwrite current bundle files. + stale_recovered = ".specify/scripts/bash/retired-recovered.sh" + (project / stale_recovered).write_bytes(custom_bytes) + manifest.record_existing(stale_recovered, recovered=True) + stale_edited = ".specify/scripts/bash/retired-edited.sh" + (project / stale_edited).write_bytes(b"# old managed bytes\n") + manifest.record_existing(stale_edited) + (project / stale_edited).write_bytes(custom_bytes) + manifest.save() + + result = _run_in_project(project, ["integration", "switch", "codex", *flags]) + assert result.exit_code == 0, result.output + overwrite = "--refresh-shared-infra" in flags or (target_state != "new" and "--force" in flags) + manifest = IntegrationManifest.load("speckit", project) + for rel in rels: + content = (project / rel).read_bytes() + assert (content != custom_bytes) == overwrite + assert manifest.is_recovered(rel) == (not overwrite) + assert manifest.files[rel] == hashlib.sha256(content).hexdigest() + for rel in (stale_recovered, stale_edited): + assert (project / rel).read_bytes() == custom_bytes + assert rel in manifest.files + assert manifest.is_recovered(stale_recovered) + assert stale_edited in manifest.check_modified() + + @pytest.mark.parametrize("target_state", ["new", "installed", "default"]) + @pytest.mark.parametrize("ancestor", [False, True], ids=["leaves", "ancestors"]) + @pytest.mark.parametrize( + "flags", [[], ["--force"], ["--refresh-shared-infra"], ["--force", "--refresh-shared-infra"]], + ids=["none", "force", "refresh", "both"], + ) + def test_switch_skips_symlinked_parent_directory(self, tmp_path, target_state, ancestor, flags): + """No flag permits writing through shared leaf or ancestor symlinks.""" + if os.name == "nt": + pytest.skip("Symlink creation typically requires admin on Windows") + project = _init_codex_switch_project(tmp_path, target_state) outside = tmp_path / "outside" outside.mkdir() - for child in bash_dir.iterdir(): - child.rename(outside / child.name) - bash_dir.rmdir() - bash_dir.symlink_to(outside, target_is_directory=True) - sentinel = (outside / "common.sh").read_bytes() - - old_cwd = os.getcwd() - try: - os.chdir(project) - result = runner.invoke(app, [ - "integration", "switch", "copilot", - "--script", "sh", - ], catch_exceptions=False) - finally: - os.chdir(old_cwd) - assert result.exit_code == 0 - # Symlinked tree reported, not written through. - assert "symlink" in result.output.lower() - # Outside dir contents unchanged. - assert (outside / "common.sh").read_bytes() == sentinel - - def test_switch_force_alone_does_not_overwrite_shared_customizations(self, tmp_path): - """--force (uninstall semantics) must NOT overwrite shared-infra customizations. - - Regression: ensures the decoupling of --force and --refresh-shared-infra. - """ - project = _init_project(tmp_path, "claude") - shared_script = project / ".specify" / "scripts" / "bash" / "common.sh" - bundled_bytes = shared_script.read_bytes() - - custom_bytes = bundled_bytes + b"\n# user customization\n" - shared_script.write_bytes(custom_bytes) - - old_cwd = os.getcwd() - try: - os.chdir(project) - result = runner.invoke(app, [ - "integration", "switch", "copilot", - "--script", "sh", - "--force", - ], catch_exceptions=False) - finally: - os.chdir(old_cwd) - assert result.exit_code == 0 - # --force alone preserves the customization - assert shared_script.read_bytes() == custom_bytes + rels = [".specify/.gitignore"] + rels += ([".specify/scripts/bash", ".specify/templates"] if ancestor else [ + ".specify/scripts/bash/common.sh", ".specify/templates/plan-template.md", + ]) + for index, rel in enumerate(rels): + path = project / rel + destination = outside / str(index) + path.rename(destination) + path.symlink_to(destination, target_is_directory=destination.is_dir()) + before = {path.relative_to(outside): path.read_bytes() for path in outside.rglob("*") if path.is_file()} + + result = _run_in_project(project, ["integration", "switch", "codex", *flags]) + assert result.exit_code == 0, result.output + if target_state != "default" or flags: + assert "symlink" in result.output.lower() + assert all((project / rel).is_symlink() for rel in rels) + assert {path.relative_to(outside): path.read_bytes() for path in outside.rglob("*") if path.is_file()} == before def test_switch_from_nothing(self, tmp_path): """Switch when no integration is installed should just install the target.""" diff --git a/tests/specify_cli/test_file_policy.py b/tests/specify_cli/test_file_policy.py index 3f7f356545..24df7c6f13 100644 --- a/tests/specify_cli/test_file_policy.py +++ b/tests/specify_cli/test_file_policy.py @@ -11,7 +11,7 @@ from typer.testing import CliRunner from specify_cli import app -from specify_cli.file_helper import FileHelper +from specify_cli.file_helper import FileHelper, FileHelperError def policy_module(): @@ -20,6 +20,66 @@ def policy_module(): return _file_policy +@pytest.mark.parametrize("operation", ["read_project_options", "project_files"]) +def test_policy_translates_constructor_contract_failure(tmp_path, monkeypatch, operation): + policy = policy_module() + if operation == "project_files": + monkeypatch.setattr(policy, "read_project_options", lambda _: {}) + + def failed(*args, **kwargs): + raise FileHelperError("root binding failed") + + monkeypatch.setattr(policy, "FileHelper", failed) + with pytest.raises(policy.ProjectPolicyError, match="root binding failed") as raised: + getattr(policy, operation)(tmp_path) + assert isinstance(raised.value.__cause__, FileHelperError) + + +@pytest.mark.parametrize( + ("operation", "failing_method"), + [ + ("read_project_options", "read_text"), + ("save_project_options", "overwrite_text"), + ("preflight_init_root", "read_bytes"), + ("prepare_init_root", "mkdir"), + ], +) +@pytest.mark.parametrize("failure", [False, True]) +def test_bootstrap_consumers_close_retained_helpers( + tmp_path, monkeypatch, operation, failing_method, failure +): + policy = policy_module() + (tmp_path / ".specify").mkdir() + (tmp_path / ".specify/init-options.json").write_text("{}") + captured = [] + + def owner(*args, **kwargs): + files = FileHelper(*args, **kwargs) + captured.append(files) + return files + + def denied(*args, **kwargs): + raise PermissionError("bootstrap access denied") + + monkeypatch.setattr(policy, "FileHelper", owner) + if failure: + monkeypatch.setattr(FileHelper, failing_method, denied) + target = tmp_path / "missing/project" if operation.endswith("init_root") else tmp_path + args = (target, {}) if operation == "save_project_options" else (target,) + retained_error = None + if failure: + error_type = PermissionError if operation == "prepare_init_root" else policy.ProjectPolicyError + with pytest.raises(error_type, match="bootstrap access denied") as raised: + getattr(policy, operation)(*args) + retained_error = raised.value + else: + getattr(policy, operation)(*args) + assert len(captured) == 1 + assert not captured[0]._root_cleanup.alive + if failure: + assert retained_error is not None + + @pytest.fixture def symlinks(tmp_path): probe = tmp_path / "probe" diff --git a/tests/specify_cli/workflows/test_operation_list.py b/tests/specify_cli/workflows/test_operation_list.py index c2730dcb23..3379e2cd66 100644 --- a/tests/specify_cli/workflows/test_operation_list.py +++ b/tests/specify_cli/workflows/test_operation_list.py @@ -52,6 +52,47 @@ def test_missing_registry_is_empty_without_creating_storage(tmp_path): assert list((tmp_path / ".specify").iterdir()) == [] +@pytest.mark.parametrize("outcome", ["success", "missing-marker", "storage-error", "registry-error"]) +def test_list_workflows_closes_owner_on_every_exit(tmp_path, monkeypatch, outcome): + if outcome != "missing-marker": + _registry(tmp_path, {}) + captured = [] + original = operation.project_files + + def owner(root): + files = original(root) + captured.append(files) + return files + + def storage_error(*args): + raise operation.WorkflowStorageError("storage unavailable") + + def registry_error(*args): + raise OSError("registry unavailable") + + monkeypatch.setattr(operation, "project_files", owner) + if outcome == "storage-error": + monkeypatch.setattr(operation, "validate_workflow_storage", storage_error) + elif outcome == "registry-error": + monkeypatch.setattr(operation.WorkflowRegistry, "list", registry_error) + error = None + if outcome == "success": + assert operation.list_workflows(operation.WorkflowListRequest(tmp_path)).items == () + else: + with pytest.raises(operation.WorkflowListError) as raised: + operation.list_workflows(operation.WorkflowListRequest(tmp_path)) + error = raised.value + assert error.code == { + "missing-marker": "not_a_spec_kit_project", + "storage-error": "unsafe_workflow_storage", + "registry-error": "workflow_registry_read_failed", + }[outcome] + assert len(captured) == 1 + assert not captured[0]._root_cleanup.alive + if outcome != "success": + assert error is not None + + @pytest.mark.parametrize("contents", ["{", "[]", '{"workflows": []}', "\udcff"]) def test_corrupt_registry_fails_closed(tmp_path, contents): path = _registry(tmp_path, {}) diff --git a/tests/test_create_new_feature_python_parity.py b/tests/test_create_new_feature_python_parity.py index 315973558b..14f1bc0c89 100644 --- a/tests/test_create_new_feature_python_parity.py +++ b/tests/test_create_new_feature_python_parity.py @@ -1123,6 +1123,43 @@ def test_python_json_output_matches_powershell( assert json_stdout(py) == json_stdout(ps) +@pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available") +def test_powershell_handles_bracketed_repo_path(tmp_path: Path) -> None: + ps_repo = _setup_repo(tmp_path, "ps [v2]") + py_repo = _setup_repo(tmp_path, "py [v2]") + existing_spec = b"# My spec\r\n\r\nKeep this.\r\n" + for repo in (ps_repo, py_repo): + existing = repo / "specs" / "001-login-page" + existing.mkdir(parents=True) + (existing / "spec.md").write_bytes(existing_spec) + + ps = run(ps_cmd(ps_repo, SCRIPT, "-Json", "Add payment export"), ps_repo) + py = run(py_cmd(py_repo, SCRIPT, "--json", "Add payment export"), py_repo) + + assert py.returncode == 0, py.stderr + assert ps.returncode == 0, ps.stderr + assert json_stdout(ps)["BRANCH_NAME"] == json_stdout(py)["BRANCH_NAME"] == "002-payment-export" + + reuse = run( + ps_cmd( + ps_repo, + SCRIPT, + "-Json", + "-AllowExistingBranch", + "-Number", + "1", + "-ShortName", + "login-page", + "x", + ), + ps_repo, + ) + + assert reuse.returncode == 0, reuse.stderr + assert json_stdout(reuse)["BRANCH_NAME"] == "001-login-page" + assert (ps_repo / "specs" / "001-login-page" / "spec.md").read_bytes() == existing_spec + + @requires_bash @pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available") @pytest.mark.parametrize("number", ["-1", "+1"], ids=["negative", "positive_sign"]) diff --git a/tests/test_file_handles.py b/tests/test_file_handles.py index a1201e64b6..520edb437a 100644 --- a/tests/test_file_handles.py +++ b/tests/test_file_handles.py @@ -1,25 +1,384 @@ """Ownership and native Windows evidence for shared handle primitives.""" from concurrent.futures import ThreadPoolExecutor -from contextlib import contextmanager +from contextlib import contextmanager, nullcontext import ctypes from ctypes import wintypes import errno import gc import os +import stat from pathlib import Path import sys import subprocess +import struct from types import SimpleNamespace import weakref import pytest from specify_cli import _file_handles, file_helper -from specify_cli._file_handles import _windows_handle +from specify_cli import _file_handles as handles +from specify_cli._file_handles import ( + _WindowsFileIdentity, _windows_file_id, _windows_handle, _windows_stat, +) from specify_cli.file_helper import FileHelper, UnsupportedPathError +@pytest.mark.parametrize("directory", [False, True]) +@pytest.mark.parametrize("pin", [False, True]) +@pytest.mark.parametrize("outcome", ["success", "reparse", "wrong-type", "query-failure", "body-failure", "open-failure"]) +def test_windows_handle_flags_validation_and_cleanup(monkeypatch, directory, pin, outcome): + calls = [] + + def create(*args): + calls.append(("open", args)) + return ctypes.c_void_p(-1).value if outcome == "open-failure" else 123 + + def info(handle, kind, buffer, size): + assert handle == 123 and kind == 9 + attributes = 0x10 if directory else 0 + if outcome == "reparse": + attributes |= 0x400 + if outcome == "wrong-type": + attributes ^= 0x10 + buffer._obj.attributes = attributes + return outcome != "query-failure" + + def close(handle): + calls.append(("close", handle)) + return True + + # Real ctypes functions accept signature attributes; plain Python functions + # do too, allowing this contract to run without loading a Windows DLL. + kernel = SimpleNamespace( + CreateFileW=create, GetFileInformationByHandleEx=info, CloseHandle=close + ) + monkeypatch.setattr(ctypes, "WinDLL", lambda *args, **kwargs: kernel, raising=False) + monkeypatch.setattr(ctypes, "get_last_error", lambda: 5, raising=False) + monkeypatch.setattr( + ctypes, "WinError", lambda code: PermissionError(code, "handle denied"), raising=False + ) + + def use(): + with _windows_handle(Path("selected"), directory=directory, pin=pin) as handle: + assert handle == 123 + assert calls == [calls[0]] + if outcome == "body-failure": + raise RuntimeError("body failed") + + if outcome == "success": + use() + elif outcome == "body-failure": + with pytest.raises(RuntimeError, match="body failed"): + use() + else: + with pytest.raises(OSError) as exc: + use() + if outcome in ("reparse", "wrong-type"): + assert exc.value.errno == (errno.ELOOP if outcome == "reparse" else errno.EINVAL) + args = calls[0][1] + assert args == ( + "selected", (0x81 if directory else 0x80000000) if pin else 0x80, + 0x3 if pin else 0x7, None, 3, 0x00200000 | 0x02000000, None, + ) + assert calls[1:] == ([] if outcome == "open-failure" else [("close", 123)]) + + +@pytest.mark.parametrize("failure", [False, True]) +def test_windows_file_identity_uses_full_volume_and_file_id(monkeypatch, failure): + def info(handle, kind, buffer, size): + assert handle == 0x1FFFFFFFF and kind == 18 and size == 24 + buffer._obj.volume = 0x1FFFFFFFF + buffer._obj.file_id[:] = bytes(range(16)) + return not failure + + monkeypatch.setattr( + ctypes, "WinDLL", + lambda *args, **kwargs: SimpleNamespace(GetFileInformationByHandleEx=info), + raising=False, + ) + monkeypatch.setattr(ctypes, "get_last_error", lambda: 5, raising=False) + monkeypatch.setattr(ctypes, "WinError", lambda code: PermissionError(code, "identity denied"), raising=False) + if failure: + with pytest.raises(PermissionError, match="identity denied"): + _windows_file_id(0x1FFFFFFFF) + else: + assert _windows_file_id(0x1FFFFFFFF) == _WindowsFileIdentity( + "fileid128", 0x1FFFFFFFF, bytes(range(16)) + ) + assert info.argtypes == [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD] + assert info.restype is wintypes.BOOL + + +@pytest.fixture +def identity_kernel(monkeypatch): + state = SimpleNamespace( + extended_error=87, legacy_error=0, last_error=0, filesystem="FAT32", + volume=0xABCDEF12, index=0x123456789ABCDEF, zero_extended=False, + ) + calls = [] + + def extended(handle, kind, output, size): + assert handle == 0x1FFFFFFFF and kind == 18 and size == 24 + calls.append("extended") + if state.extended_error: + state.last_error = state.extended_error + return False + output._obj.volume = state.volume + output._obj.file_id[:] = bytes(16) if state.zero_extended else bytes(range(16)) + return True + + def legacy(handle, output): + assert handle == 0x1FFFFFFFF + assert ctypes.sizeof(output._obj) == 52 + calls.append("legacy") + if state.legacy_error: + state.last_error = state.legacy_error + return False + output._obj.volume = state.volume + output._obj.index_high = state.index >> 32 + output._obj.index_low = state.index & 0xFFFFFFFF + return True + + def native_error(code): + error = OSError(errno.EACCES if code == 5 else errno.ENOTSUP, f"native error {code}") + error.winerror = code + return error + + monkeypatch.setattr(ctypes, "WinDLL", lambda *args, **kwargs: SimpleNamespace( + GetFileInformationByHandleEx=extended, GetFileInformationByHandle=legacy, + ), raising=False) + monkeypatch.setattr(ctypes, "get_last_error", lambda: state.last_error, raising=False) + monkeypatch.setattr(ctypes, "WinError", native_error, raising=False) + monkeypatch.setattr( + handles, "_windows_filesystem", lambda _: state.filesystem, raising=False + ) + return state, calls + + +@pytest.mark.parametrize("unsupported", [1, 50, 87]) +@pytest.mark.parametrize("filesystem", ["FAT", "FAT32", "exFAT", "NTFS"]) +def test_windows_identity_falls_back_only_for_supported_legacy_filesystems( + identity_kernel, unsupported, filesystem +): + state, calls = identity_kernel + state.extended_error = unsupported + state.filesystem = filesystem + identity = _windows_file_id(0x1FFFFFFFF) + assert identity.kind == "legacy64" + assert identity.volume == state.volume + assert identity.file_id == state.index.to_bytes(8, "little") + assert calls == ["extended", "legacy"] + + +@pytest.mark.parametrize("error_code", [5, 6, 32]) +def test_windows_identity_does_not_hide_unrelated_native_errors(identity_kernel, error_code): + state, calls = identity_kernel + state.extended_error = error_code + with pytest.raises(OSError) as raised: + _windows_file_id(0x1FFFFFFFF) + assert raised.value.winerror == error_code + assert calls == ["extended"] + + +@pytest.mark.parametrize("filesystem", ["ReFS", "unknown"]) +def test_windows_identity_rejects_unreliable_legacy_scheme(identity_kernel, filesystem): + state, calls = identity_kernel + state.filesystem = filesystem + with pytest.raises(OSError, match="legacy.*identity"): + _windows_file_id(0x1FFFFFFFF) + assert calls == ["extended"] + + +@pytest.mark.parametrize("scheme", ["legacy64", "fileid128"]) +def test_windows_identity_uses_selected_scheme_without_renegotiating(identity_kernel, scheme): + state, calls = identity_kernel + state.extended_error = 0 + identity = _windows_file_id(0x1FFFFFFFF, kind=scheme) + assert identity.kind == scheme + assert calls == (["legacy"] if scheme == "legacy64" else ["extended"]) + + +def test_windows_identity_selected_extended_scheme_does_not_downgrade(identity_kernel): + state, calls = identity_kernel + with pytest.raises(OSError) as raised: + _windows_file_id(0x1FFFFFFFF, kind="fileid128") + assert raised.value.winerror == state.extended_error + assert calls == ["extended"] + + +@pytest.mark.parametrize("invalid", [False, True]) +def test_windows_filesystem_query_is_handle_relative_and_preserves_abi(monkeypatch, invalid): + from specify_cli import _windows_abi as abi + + def query(handle, status, output, size, kind): + assert handle == 0x1FFFFFFFF and size == 536 and kind == 5 + assert isinstance(status._obj, abi._IoStatusBlock) + name = "exFAT".encode("utf-16-le") + output._obj.name_length = 1 if invalid else len(name) + ctypes.memmove(output._obj.name, name, len(name)) + return 0 + + def dos_error(status): + pytest.fail("A successful native query must not query an error") + + monkeypatch.setattr(ctypes, "WinDLL", lambda *args: SimpleNamespace( + NtQueryVolumeInformationFile=query, RtlNtStatusToDosError=dos_error, + ), raising=False) + if invalid: + with pytest.raises(OSError, match="Invalid filesystem name"): + handles._windows_filesystem(0x1FFFFFFFF) + else: + assert handles._windows_filesystem(0x1FFFFFFFF) == "exFAT" + assert query.argtypes == [ + wintypes.HANDLE, abi._IoStatusBlockPointer, wintypes.LPVOID, + ctypes.c_uint32, ctypes.c_int, + ] + assert query.restype is ctypes.c_int32 + + +def test_windows_filesystem_query_preserves_native_failure(monkeypatch): + def query(*args): + return -1 + + def dos_error(status): + assert status == -1 + return 5 + + def win_error(code): + assert code == 5 + error = PermissionError("volume query denied") + error.winerror = code + return error + + monkeypatch.setattr(ctypes, "WinDLL", lambda *args: SimpleNamespace( + NtQueryVolumeInformationFile=query, RtlNtStatusToDosError=dos_error, + ), raising=False) + monkeypatch.setattr(ctypes, "WinError", win_error, raising=False) + with pytest.raises(PermissionError, match="volume query denied"): + handles._windows_filesystem(123) + + +def test_windows_identity_zero_extended_id_uses_reliable_legacy_identity(identity_kernel): + state, calls = identity_kernel + state.extended_error = 0 + state.zero_extended = True + identity = _windows_file_id(0x1FFFFFFFF) + assert identity.kind == "legacy64" + assert calls == ["extended", "legacy"] + + +def test_windows_identity_zero_legacy_id_is_not_accepted(identity_kernel): + state, calls = identity_kernel + state.index = 0 + with pytest.raises(OSError, match="identity"): + _windows_file_id(0x1FFFFFFFF) + assert calls == ["extended", "legacy"] + + +def test_windows_identity_legacy_query_error_remains_native(identity_kernel): + state, _ = identity_kernel + state.legacy_error = 5 + with pytest.raises(OSError) as raised: + _windows_file_id(0x1FFFFFFFF) + assert raised.value.winerror == 5 + + +@pytest.mark.parametrize("failure", [None, "duplicate", "convert", "stat"]) +def test_windows_stat_preserves_borrowed_handle_and_closes_duplicate(tmp_path, monkeypatch, failure): + expected = tmp_path.stat() + closed = [] + + def duplicate(source_process, handle, target_process, access, inherit, options): + assert source_process == target_process == 0x1FFFFFFFF + assert handle == 0x2FFFFFFFF + assert access == 0 and inherit is False and options == 2 + if failure == "duplicate": + raise OSError("duplicate failed") + return 456 + + def convert(handle, flags): + assert handle == 456 and flags == 128 + if failure == "convert": + raise OSError("convert failed") + return 789 + + def fstat(fd): + assert fd == 789 + if failure == "stat": + raise OSError("stat failed") + return expected + + monkeypatch.setitem(sys.modules, "_winapi", SimpleNamespace( + GetCurrentProcess=lambda: 0x1FFFFFFFF, + DuplicateHandle=duplicate, + DUPLICATE_SAME_ACCESS=2, + CloseHandle=lambda handle: closed.append(("handle", handle)), + )) + monkeypatch.setitem(sys.modules, "msvcrt", SimpleNamespace(open_osfhandle=convert)) + monkeypatch.setattr(handles, "os", SimpleNamespace( + O_RDONLY=0, O_NOINHERIT=128, fstat=fstat, close=lambda fd: closed.append(("fd", fd)), + )) + if failure: + with pytest.raises(OSError, match=f"{failure} failed"): + _windows_stat(0x2FFFFFFFF) + else: + assert _windows_stat(0x2FFFFFFFF) is expected + assert closed == { + None: [("fd", 789)], "duplicate": [], "convert": [("handle", 456)], "stat": [("fd", 789)], + }[failure] + + +@pytest.mark.skipif(os.name != "nt", reason="Native Windows directory-handle metadata") +def test_native_windows_stat_matches_path_metadata_without_closing_reference(tmp_path): + with _windows_handle(tmp_path, directory=True, pin=False) as handle: + identity = _windows_file_id(handle) + assert os.path.samestat(tmp_path.stat(), _windows_stat(handle)) + assert _windows_file_id(handle) == identity + + +@pytest.mark.skipif(os.name != "nt", reason="Native Windows legacy identity APIs") +@pytest.mark.parametrize("recursive", [False, True]) +@pytest.mark.parametrize("allow", [False, True]) +def test_native_windows_delete_uses_legacy_identity_when_extended_query_is_unsupported( + tmp_path, monkeypatch, recursive, allow +): + parent = tmp_path / "tree/nested" + parent.mkdir(parents=True) + (parent / "victim").write_text("selected") + native = handles._windows_api() + win_dll = ctypes.WinDLL + extended_queries = [] + + def query(handle, kind, output, size): + if kind == 18: + extended_queries.append(handle) + ctypes.set_last_error(87) + return False + return native.GetFileInformationByHandleEx(handle, kind, output, size) + + kernel = SimpleNamespace( + CreateFileW=native.CreateFileW, + CloseHandle=native.CloseHandle, + GetFileInformationByHandleEx=query, + GetFileInformationByHandle=native.GetFileInformationByHandle, + SetFileInformationByHandle=native.SetFileInformationByHandle, + DeviceIoControl=native.DeviceIoControl, + ) + + def load(name, *args, **kwargs): + return kernel if name == "kernel32" else win_dll(name, *args, **kwargs) + + monkeypatch.setattr(ctypes, "WinDLL", load) + with FileHelper(tmp_path, allow_symlinks=allow) as files: + assert files._windows_root_id is not None + assert files._windows_root_id.kind == "legacy64" + files.delete("tree" if recursive else "tree/nested/victim", recursive=recursive) + assert len(extended_queries) == 1 + assert not (parent / "victim").exists() + + @pytest.mark.skipif(os.name == "nt", reason="POSIX startup must not require Windows ctypes support") @pytest.mark.parametrize("operation", ["help", "files"]) def test_posix_usage_without_optional_ctypes(tmp_path, operation): @@ -684,9 +1043,9 @@ def create_child(output, access, attributes, status, allocation, file_attributes name = attributes.ObjectName.contents length = len(child_name.encode("utf-16-le", errors="surrogatepass")) assert (name.Buffer, name.Length, name.MaximumLength) == (child_name, length, length + 2) - assert access == (0xA0 if directory else 0x80100000) + assert access == (0x1000A0 if directory else 0x80100000) assert sharing == 3 and disposition == 1 - assert options == (0x200001 if directory else 0x200060) + assert options == (0x200021 if directory else 0x200060) assert allocation is None and file_attributes == 0 and ea is None and ea_length == 0 assert ctypes.sizeof(status._obj) == 2 * ctypes.sizeof(ctypes.c_void_p) if failure == "status": @@ -737,6 +1096,34 @@ def load(name, **kwargs): assert {role: len(declarations) for role, declarations in abi_types.items()} == dict.fromkeys(abi_types, 1) +@pytest.mark.skipif(os.name != "nt", reason="Native Windows synchronous directory I/O") +@pytest.mark.parametrize("traverse", [False, True]) +def test_native_windows_relative_directory_handle_has_synchronous_mode(tmp_path, traverse): + from specify_cli import _windows_abi as abi + + directory = tmp_path / "directory" + directory.mkdir() + (directory / "file").write_text("selected") + native = ctypes.WinDLL("ntdll") + query = native.NtQueryInformationFile + query.argtypes = [ + wintypes.HANDLE, abi._IoStatusBlockPointer, wintypes.LPVOID, + ctypes.c_uint32, ctypes.c_int, + ] + query.restype = ctypes.c_int32 + status = abi._IoStatusBlock() + mode = ctypes.c_uint32() + with _windows_handle(tmp_path, directory=True) as parent: + with _windows_handle( + Path("directory"), directory=True, parent=parent, traverse=traverse, + ) as child: + result = query(child, ctypes.byref(status), ctypes.byref(mode), 4, 16) + assert result == 0 + assert mode.value & 0x20 # FILE_SYNCHRONOUS_IO_NONALERT. + if not traverse: + assert handles._windows_directory_names(child) == ["file"] + + @pytest.mark.skipif(os.name != "nt", reason="Native Windows repeated-read lifetime regression") @pytest.mark.parametrize("allow", [False, True]) def test_repeated_windows_reads_do_not_accumulate_abi_types(tmp_path, allow): @@ -776,6 +1163,203 @@ def test_windows_child_open_rejects_oversized_unicode_name(): assert error.value.errno == errno.ENAMETOOLONG +@pytest.mark.parametrize("deleting", [False, True]) +@pytest.mark.parametrize("body_failure", [False, True]) +def test_windows_entry_open_uses_native_parent_and_closes_its_handle( + monkeypatch, deleting, body_failure +): + closed = [] + + def create(output, access, attributes, status, allocation, file_attributes, + sharing, disposition, options, ea, ea_length): + assert access == 0x100080 | (0x10000 if deleting else 0) + assert attributes._obj.RootDirectory == 51 + assert attributes._obj.Attributes == 0x40 + assert attributes._obj.ObjectName.contents.Buffer == "entry" + assert sharing == 7 and disposition == 1 and options == 0x200020 + output._obj.value = 77 + return 0 + + def dos_error(status): + pytest.fail("A successful native open must not query an error") + + monkeypatch.setattr(ctypes, "WinDLL", lambda *args: SimpleNamespace( + NtCreateFile=create, RtlNtStatusToDosError=dos_error, + ), raising=False) + monkeypatch.setattr(handles, "_windows_api", lambda: SimpleNamespace(CloseHandle=closed.append)) + expected = pytest.raises(RuntimeError, match="body failed") if body_failure else nullcontext() + with expected: + with handles._windows_entry(51, "entry", deleting=deleting) as handle: + assert handle == 77 and not closed + if body_failure: + raise RuntimeError("body failed") + assert closed == [77] + + +@pytest.mark.parametrize( + ("attributes", "tag", "mode"), + [(0, 0, stat.S_IFREG), (0x10, 0, stat.S_IFDIR), (0x400, 0xA000000C, stat.S_IFLNK)], +) +def test_windows_mode_queries_the_opened_object(monkeypatch, attributes, tag, mode): + def query(handle, kind, output, size): + assert handle == 51 and kind == 9 and size == 8 + output._obj.attributes = attributes + output._obj.tag = tag + return True + + monkeypatch.setattr(handles, "_windows_api", lambda: SimpleNamespace( + GetFileInformationByHandleEx=query, + )) + assert handles._windows_mode(51) == mode + + +def test_windows_mode_rejects_non_symlink_reparse_points(monkeypatch): + def query(handle, kind, output, size): + output._obj.attributes = 0x410 + output._obj.tag = 0xA0000003 + return True + + monkeypatch.setattr(handles, "_windows_api", lambda: SimpleNamespace( + GetFileInformationByHandleEx=query, + )) + with pytest.raises(OSError, match="Unsupported Windows reparse"): + handles._windows_mode(51) + + +@pytest.mark.parametrize("target", ["directory/../caf\u00e9", "name\ud800", "\\??\\C:\\target"]) +def test_windows_readlink_reads_the_opened_reparse_buffer(monkeypatch, target): + encoded = target.encode("utf-16-le", errors="surrogatepass") + relative = not target.startswith("\\??\\") + data = struct.pack("= 2 + for fd in opened: + with pytest.raises(OSError) as exc: + os.fstat(fd) + assert exc.value.errno == errno.EBADF + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX capability check") +def test_delete_unsupported_backend_does_not_remove(root, monkeypatch): + (root / "victim").write_text("keep") + monkeypatch.setattr("specify_cli.file_helper._DELETE_DIR_FD_SUPPORTED", False) + with pytest.raises(OSError) as exc: + FileHelper(root).delete("victim") + assert exc.value.errno == errno.ENOTSUP + assert (root / "victim").read_text() == "keep" + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX root descriptor acquisition") +@pytest.mark.parametrize("allow", [False, True]) +@pytest.mark.parametrize("recursive", [False, True]) +def test_delete_rejects_root_ancestor_exchange_at_open(root, link, monkeypatch, allow, recursive): + ancestor = root / "ancestor" + project = ancestor / "project" + project.mkdir(parents=True) + (project / "tree").mkdir() + (project / "tree/victim").write_text("selected") + outside = root / "outside" + (outside / "project/tree").mkdir(parents=True) + (outside / "project/tree/victim").write_text("keep") + retained = root / "retained" + open_directory = os.open + attempted = False + opened = [] + + def exchange(path, flags, *args, **kwargs): + nonlocal attempted + if not attempted and path == project: + attempted = True + ancestor.rename(retained) + link(ancestor, outside) + fd = open_directory(path, flags, *args, **kwargs) + opened.append(fd) + return fd + + monkeypatch.setattr(os, "open", exchange) + with pytest.raises(FileHelperError, match="root changed"): + with FileHelper(project, allow_symlinks=allow) as files: + files.delete("tree" if recursive else "tree/victim", recursive=recursive) + assert attempted + assert (outside / "project/tree/victim").read_text() == "keep" + assert (retained / "project/tree/victim").read_text() == "selected" + assert len(opened) == 1 + with pytest.raises(OSError) as exc: + os.fstat(opened[0]) + assert exc.value.errno == errno.EBADF + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX root descriptor lifetime") +@pytest.mark.parametrize("allow", [False, True]) +@pytest.mark.parametrize("recursive", [False, True]) +def test_delete_reuses_root_after_ancestor_exchange(root, link, monkeypatch, allow, recursive): + ancestor = root / "ancestor" + project = ancestor / "project" + project.mkdir(parents=True) + (project / "tree").mkdir() + (project / "tree/victim").write_text("selected") + outside = root / "outside" + (outside / "project/tree").mkdir(parents=True) + (outside / "project/tree/victim").write_text("keep") + files = FileHelper(project, allow_symlinks=allow) + retained = root / "retained" + check = FileHelper._path + attempted = False + + def exchange(self, path, **kwargs): + nonlocal attempted + result = check(self, path, **kwargs) + if not attempted: + attempted = True + ancestor.rename(retained) + link(ancestor, outside) + return result + + monkeypatch.setattr(FileHelper, "_path", exchange) + files.delete("tree" if recursive else "tree/victim", recursive=recursive) + assert attempted + assert (outside / "project/tree/victim").read_text() == "keep" + assert not (retained / "project/tree/victim").exists() + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX retained-root path resolution") +@pytest.mark.parametrize("kind", ["file", "directory", "recursive-tree"]) +@pytest.mark.parametrize("target", ["relative", "absolute", "chain", "parent-traversal"]) +def test_delete_resolves_links_in_retained_root(root, link, monkeypatch, kind, target): + ancestor = root / "ancestor" + project = ancestor / "project" + outside = root / "outside/project" + for boundary in (project, outside): + for name in ("selected", "unrelated"): + directory = boundary / name + directory.mkdir(parents=True) + victim = directory / "victim" + if kind == "file": + victim.write_text("keep") + else: + victim.mkdir() + if kind == "recursive-tree": + (victim / "child").write_text("keep") + for boundary, selected in ((project, "selected"), (outside, "unrelated")): + if target == "absolute": + destination = boundary / selected + elif target == "chain": + link(boundary / "first", selected) + destination = "first" + elif target == "parent-traversal": + (boundary / "nested").mkdir() + destination = f"nested/../{selected}" + else: + destination = selected + link(boundary / "alias", destination) + files = FileHelper(project, allow_symlinks=True) + retained = root / "retained" + acquire = FileHelper._deletion_root + + @contextmanager + def exchange(self): + with acquire(self) as handle: + ancestor.rename(retained) + link(ancestor, outside.parent) + yield handle + + monkeypatch.setattr(FileHelper, "_deletion_root", exchange) + files.delete("alias/victim", recursive=kind == "recursive-tree") + assert not (retained / "project/selected/victim").exists() + assert (retained / "project/unrelated/victim").exists() + assert (retained / "project/alias").is_symlink() + assert (outside / "selected/victim").exists() + assert (outside / "unrelated/victim").exists() + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX retained-root preflight") +def test_delete_classifies_descendants_in_retained_root(root, link, monkeypatch): + ancestor = root / "ancestor" + project = ancestor / "project" + outside = root / "outside/project" + for boundary in (project, outside): + (boundary / "tree").mkdir(parents=True) + (boundary / "tree/a-file").write_text("keep") + link(project / "tree/z-link", root / "missing") + (outside / "tree/z-link").write_text("replacement") + files = FileHelper(project) + retained = root / "retained" + acquire = FileHelper._deletion_root + + @contextmanager + def exchange(self): + with acquire(self) as handle: + ancestor.rename(retained) + link(ancestor, outside.parent) + yield handle + + monkeypatch.setattr(FileHelper, "_deletion_root", exchange) + with pytest.raises(SymlinkDeniedError): + files.delete("tree", recursive=True) + assert (retained / "project/tree/a-file").read_text() == "keep" + assert (retained / "project/tree/z-link").is_symlink() + assert (outside / "tree/z-link").read_text() == "replacement" + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX descriptor-relative metadata") +@pytest.mark.parametrize("recursive", [False, True]) +def test_delete_metadata_and_links_use_retained_descriptors(root, link, monkeypatch, recursive): + (root / "selected/tree").mkdir(parents=True) + (root / "selected/tree/victim").write_text("selected") + link(root / "alias", "selected") + files = FileHelper(root, allow_symlinks=True) + acquire = FileHelper._deletion_root + stat_entry = os.stat + readlink = os.readlink + calls = [] + + def relative_stat(path, *args, **kwargs): + assert isinstance(kwargs.get("dir_fd"), int) + assert kwargs.get("follow_symlinks") is False + assert not Path(path).is_absolute() + calls.append("stat") + return stat_entry(path, *args, **kwargs) + + def relative_readlink(path, *args, **kwargs): + assert isinstance(kwargs.get("dir_fd"), int) + assert not Path(path).is_absolute() + calls.append("readlink") + return readlink(path, *args, **kwargs) + + def no_path_metadata(*args, **kwargs): + pytest.fail("Deletion metadata must not reopen an absolute pathname") + + @contextmanager + def observe(self): + with acquire(self) as handle, monkeypatch.context() as scoped: + scoped.setattr(Path, "lstat", no_path_metadata) + scoped.setattr(os, "stat", relative_stat) + scoped.setattr(os, "readlink", relative_readlink) + yield handle + + monkeypatch.setattr(FileHelper, "_deletion_root", observe) + files.delete("alias/tree" if recursive else "alias/tree/victim", recursive=recursive) + assert "stat" in calls and "readlink" in calls + assert not (root / "selected/tree/victim").exists() + assert (root / "alias").is_symlink() + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX retained-root revalidation") +@pytest.mark.parametrize("recursive", [False, True]) +def test_delete_revalidates_entries_in_retained_root(root, link, monkeypatch, recursive): + ancestor = root / "ancestor" + project = ancestor / "project" + (project / "selected").mkdir(parents=True) + (project / "selected/victim").write_text("selected") + outside = root / "outside/project" + outside.mkdir(parents=True) + link(outside / "selected", root / "missing") + files = FileHelper(project) + retained = root / "retained" + plan = FileHelper._deletion_plan + selected = project / ("selected" if recursive else "selected/victim") + attempted = False + + def exchange(self, path, **kwargs): + nonlocal attempted + result = plan(self, path, **kwargs) + if path == selected: + attempted = True + ancestor.rename(retained) + link(ancestor, outside.parent) + return result + + monkeypatch.setattr(FileHelper, "_deletion_plan", exchange) + files.delete(selected, recursive=recursive) + assert attempted + assert not (retained / "project/selected/victim").exists() + assert (outside / "selected").is_symlink() + + +@pytest.mark.parametrize( + ("kind", "error"), + [ + ("dangling", FileNotFoundError), + ("cycle", UnsupportedPathError), + ("excessive", UnsupportedPathError), + ("non-directory", NotADirectoryError), + ("escape-and-return", PathEscapeError), + ], +) +def test_delete_parent_link_targets_preserve_failure_contract(root, link, kind, error): + (root / "target").mkdir() + (root / "target/victim").write_text("keep") + if kind == "dangling": + target = "missing" + elif kind == "cycle": + target = "alias" + elif kind == "excessive": + for index in reversed(range(41)): + link(root / f"chain-{index}", "target" if index == 40 else f"chain-{index + 1}") + target = "chain-0" + elif kind == "non-directory": + (root / "file").write_text("keep") + target = "file/../target" + else: + target = f"../{root.name}/target" + link(root / "alias", target) + with pytest.raises(error): + FileHelper(root, allow_symlinks=True).delete("alias/victim") + assert (root / "target/victim").read_text() == "keep" + assert (root / "alias").is_symlink() + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX directory permissions") +@pytest.mark.parametrize("parent_is_root", [False, True]) +@pytest.mark.parametrize("kind", ["file", "empty-directory", "recursive-tree"]) +def test_delete_through_write_execute_only_parent(root, parent_is_root, kind): + if not (sys.platform == "darwin" or getattr(os, "O_SEARCH", 0) or getattr(os, "O_PATH", 0)): + pytest.skip("Search/path-only directory descriptors are unavailable") + if os.geteuid() == 0: + pytest.skip("Root bypasses directory read permissions") + parent = root if parent_is_root else root / "parent" + parent.mkdir(exist_ok=True) + control = parent / "control" + control.write_text("control") + victim = parent / "victim" + if kind == "file": + victim.write_text("selected") + else: + victim.mkdir() + if kind == "recursive-tree": + (victim / "child").write_text("selected") + files = FileHelper(root) + parent.chmod(0o300) + try: + control.unlink() + files.delete(victim, recursive=kind == "recursive-tree") + assert not victim.exists() + finally: + parent.chmod(0o700) + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX directory permissions") +@pytest.mark.parametrize("mode", [0o400, 0o600, 0o444, 0o644]) +@pytest.mark.parametrize("nested", [False, True]) +@pytest.mark.parametrize("allow", [False, True]) +def test_recursive_delete_readable_empty_directory_without_search(root, mode, nested, allow): + if os.geteuid() == 0: + pytest.skip("Root bypasses directory permission checks") + tree = root / "tree" + tree.mkdir() + restricted = tree + if nested: + (tree / "a-first").write_text("selected") + restricted = tree / "z-empty" + restricted.mkdir() + restricted.chmod(mode) + try: + with FileHelper(root, allow_symlinks=allow) as files: + files.delete(tree, recursive=True) + assert not tree.exists() + finally: + if restricted.exists(): + restricted.chmod(0o700) + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX directory permissions") +@pytest.mark.parametrize("mode", [0o400, 0o600]) +@pytest.mark.parametrize("allow", [False, True]) +def test_recursive_delete_nonempty_directory_without_search_fails_preflight(root, mode, allow): + if os.geteuid() == 0: + pytest.skip("Root bypasses directory permission checks") + tree = root / "tree" + restricted = tree / "z-restricted" + restricted.mkdir(parents=True) + (tree / "a-first").write_text("keep") + (restricted / "victim").write_text("keep") + restricted.chmod(mode) + try: + with FileHelper(root, allow_symlinks=allow) as files: + with pytest.raises(PermissionError): + files.delete(tree, recursive=True) + assert (tree / "a-first").read_text() == "keep" + finally: + restricted.chmod(0o700) + assert (restricted / "victim").read_text() == "keep" + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX directory permissions") +@pytest.mark.parametrize("nonempty", [False, True]) +def test_recursive_delete_still_requires_read_permission_for_enumeration(root, nonempty): + if os.geteuid() == 0: + pytest.skip("Root bypasses directory read permissions") + tree = root / "tree" + tree.mkdir() + if nonempty: + (tree / "victim").write_text("keep") + tree.chmod(0o300) + try: + with FileHelper(root) as files: + with pytest.raises(PermissionError): + files.delete(tree, recursive=True) + if nonempty: + assert (tree / "victim").read_text() == "keep" + else: + assert tree.is_dir() + finally: + tree.chmod(0o700) + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX directory permissions") +def test_delete_still_requires_write_permission_on_parent(root): + if os.geteuid() == 0: + pytest.skip("Root bypasses directory write permissions") + parent = root / "parent" + parent.mkdir() + (parent / "victim").write_text("keep") + parent.chmod(0o100) + try: + with pytest.raises(PermissionError): + FileHelper(root).delete(parent / "victim") + assert (parent / "victim").read_text() == "keep" + finally: + parent.chmod(0o700) + + +@pytest.mark.parametrize("allow", [False, True]) +def test_delete_rejects_replaced_root_before_validation(root, monkeypatch, allow): + (root / "victim").write_text("selected") + files = FileHelper(root, allow_symlinks=allow) + retained = root.parent / "retained" + root.rename(retained) + root.mkdir() + (root / "victim").write_text("keep") + + def unexpected(*args, **kwargs): + pytest.fail("A replacement root must be rejected before path validation") + + monkeypatch.setattr(FileHelper, "_path", unexpected) + with pytest.raises(FileHelperError, match="root changed"): + files.delete("victim") + assert (root / "victim").read_text() == "keep" + assert (retained / "victim").read_text() == "selected" + + +def test_windows_delete_rejects_replaced_root_during_acquisition_portably( + root, link, monkeypatch +): + import specify_cli.file_helper as module + + ancestor = root / "ancestor" + project = ancestor / "project" + project.mkdir(parents=True) + (project / "victim").write_text("selected") + outside = root / "outside" + (outside / "project").mkdir(parents=True) + (outside / "project/victim").write_text("keep") + retained = root / "retained" + active = [] + identities = {} + metadata = {} + attempted = False + + @contextmanager + def handle(path, *, directory, pin=True): + nonlocal attempted + assert directory + value = len(identities) + 1 + active.append(path) + try: + if pin and path == project: + # Simulate a replacement just before the root handle is acquired. + attempted = True + ancestor.rename(retained) + link(ancestor, outside) + metadata[value] = path.stat() + identities[value] = (1, b"replacement" if attempted else b"original") + yield value + finally: + assert active.pop() == path + + backend = SimpleNamespace(**vars(os)) + backend.name = "nt" + monkeypatch.setattr(module, "os", backend) + monkeypatch.setattr(module, "_windows_handle", handle) + monkeypatch.setattr( + module, "_windows_file_id", + lambda value, **kwargs: _WindowsFileIdentity("fileid128", *identities[value]), + ) + monkeypatch.setattr(module, "_windows_stat", lambda value: metadata[value]) + with FileHelper(project) as files: + assert not attempted + with pytest.raises(FileHelperError, match="root changed"): + files.delete("victim") + assert active == [project] + assert attempted + assert active == [] + assert (outside / "project/victim").read_text() == "keep" + assert (retained / "project/victim").read_text() == "selected" + + +@pytest.mark.parametrize("kind", ["file", "directory", "recursive"]) +def test_windows_link_resolution_pins_accessed_parents_portably( + root, link, monkeypatch, kind, windows_delete_model +): + parent = root / "parent" + parent.mkdir() + outside = root.parent / "outside" + outside.mkdir() + selected = root / "selected" + unrelated = root / "unrelated" + for directory in (selected, unrelated): + directory.mkdir() + if kind == "file": + (directory / "victim").write_text("keep") + else: + (directory / "victim").mkdir() + if kind == "recursive": + (directory / "victim/child").write_text("keep") + link(parent / "alias", selected) + link(outside / "alias", unrelated) + retained = root / "retained" + pinned = [] + attempted = False + blocked = False + lstat = Path.lstat + + @contextmanager + def handle(path, *, directory, pin=True, parent=None): + assert directory + actual = path if parent is None else windows_delete_model.locations[parent] / path + if pin: + pinned.append(actual) + try: + with windows_delete_model.opened(path, parent=parent) as value: + yield value + finally: + if pin: + assert pinned.pop() == actual + + def exchange(path, **kwargs): + nonlocal attempted, blocked + if path == parent / "alias" and not attempted: + attempted = True + blocked = parent in pinned + if not blocked: + parent.rename(retained) + link(parent, outside) + return lstat(path, **kwargs) + + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr( + file_helper, "_windows_file_id", + lambda _, **kwargs: _WindowsFileIdentity("fileid128", 1, b"root"), + ) + monkeypatch.setattr(file_helper, "_windows_stat", lambda _: root.stat()) + monkeypatch.setattr(Path, "lstat", exchange) + with FileHelper(root, allow_symlinks=True) as files: + files.delete("parent/alias/victim", recursive=kind == "recursive") + assert attempted + assert (unrelated / "victim").exists() + assert not (selected / "victim").exists() + assert blocked + assert (parent / "alias").is_symlink() + assert pinned == [] + + +@pytest.mark.skipif(os.name != "nt", reason="Native Windows directory-handle semantics") +def test_native_windows_link_resolution_blocks_accessed_parent_exchange(root, link, monkeypatch): + parent = root / "parent" + parent.mkdir() + selected = root / "selected" + selected.mkdir() + (selected / "victim").write_text("selected") + link(parent / "alias", selected) + attempted = False + original_entry = file_helper._windows_entry + + @contextmanager + def exchange(directory, name, *, deleting=False): + nonlocal attempted + with original_entry(directory, name, deleting=deleting) as handle: + if name == "alias" and not attempted: + attempted = True + with pytest.raises(PermissionError): + parent.rename(root / "retained") + yield handle + + monkeypatch.setattr(file_helper, "_windows_entry", exchange) + with FileHelper(root, allow_symlinks=True) as files: + files.delete("parent/alias/victim") + assert attempted + assert not (selected / "victim").exists() + parent.rename(root / "retained") + + +@pytest.mark.parametrize("error_number", [errno.EINVAL, errno.EACCES]) +def test_windows_walk_preserves_parent_type_and_access_errors_portably( + root, monkeypatch, error_number +): + @contextmanager + def denied(*args, **kwargs): + raise OSError(error_number, "directory unavailable") + yield + + monkeypatch.setattr(file_helper, "_windows_handle", denied) + expected = NotADirectoryError if error_number == errno.EINVAL else PermissionError + with file_helper.ExitStack() as resources: + directories = file_helper._WalkDirectories( + root, file_helper._WindowsDirectory(root, 123), 0, resources + ) + with pytest.raises(expected): + directories.directory(root / "child") + + +def test_windows_constructor_rejects_replaced_then_restored_root(root, monkeypatch): + project = root / "project" + replacement = root / "replacement" + saved = root / "saved" + project.mkdir() + replacement.mkdir() + (project / "victim").write_text("selected") + (replacement / "victim").write_text("keep") + acquired = {} + active = [] + + @contextmanager + def handle(path, *, directory, pin=True): + assert path == project and directory and not pin + project.rename(saved) + replacement.rename(project) + acquired[123] = project.stat() + project.rename(replacement) + saved.rename(project) + active.append(123) + try: + yield 123 + finally: + assert active.pop() == 123 + + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr( + file_helper, "_windows_file_id", + lambda _, **kwargs: _WindowsFileIdentity("fileid128", 1, b"replacement"), + ) + monkeypatch.setattr(file_helper, "_windows_stat", lambda value: acquired[value], raising=False) + with pytest.raises(FileHelperError, match="root changed"): + with FileHelper(project): + pytest.fail("A handle to the replacement root must not be accepted") + assert active == [] + assert (project / "victim").read_text() == "selected" + assert (replacement / "victim").read_text() == "keep" + + +@pytest.mark.parametrize("simulate_missing_winerror", [False, True]) +def test_windows_cached_capability_error_has_independent_tracebacks( + root, monkeypatch, simulate_missing_winerror +): + native = PermissionError(errno.EACCES, "reference denied", "source", 5, "destination") + if not hasattr(native, "winerror"): + native.winerror = 5 + if simulate_missing_winerror: + original_copy = file_helper.copy + + def copy_without_winerror(error): + result = original_copy(error) + result.winerror = None + return result - def observe(source, destination): - replacements.append((Path(source), destination)) - assert first.is_symlink() and second.is_symlink() - assert target.read_bytes() == b"old" - replace(source, destination) + monkeypatch.setattr(file_helper, "copy", copy_without_winerror) - monkeypatch.setattr("specify_cli.file_helper.os.replace", observe) - files.write_text(second, "new") - assert len(replacements) == 1 - assert replacements[0][0].parent == target.parent - assert replacements[0][1] == target - assert os.readlink(first) == "target" - assert os.readlink(second) == "first" - assert target.read_bytes() == b"new" - assert sorted(p.name for p in root.iterdir()) == ["first", "second", "target"] + @contextmanager + def denied(*args, **kwargs): + raise native + yield + + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", denied) + with FileHelper(root) as files: + errors = [] + for _ in range(3): + with pytest.raises(PermissionError) as raised: + files.delete("victim") + errors.append(raised.value) + assert files._root_anchor_error is native + assert native.__traceback__ is None + assert len({id(error) for error in errors}) == 3 + for error in errors: + assert error is not native and type(error) is type(native) + assert (error.errno, error.strerror, error.filename, error.filename2, error.winerror) == ( + native.errno, native.strerror, native.filename, native.filename2, native.winerror, + ) + assert error.__traceback__ is not None -def test_allow_operations_through_linked_parent(root, link): - target = root / "target" - target.mkdir() - alias = link(root / "alias", target) - files = FileHelper(root, allow_symlinks=True) - files.mkdir(alias / "created/child", parents=True) - files.create_text(alias / "created/file", "old") - assert files.read_text(alias / "created/file") == "old" - files.write_text(alias / "created/file", "new") - assert (target / "created/file").read_text() == "new" - files.delete(alias / "created", recursive=True) - assert alias.is_symlink() and target.is_dir() - assert list(target.iterdir()) == [] +@pytest.fixture +def windows_victim_read_fd(root, monkeypatch): + @contextmanager + def duplicate(handle): + with (root / "victim").open("rb") as stream: + yield stream.fileno() + monkeypatch.setattr(file_helper, "windows_read_fd", duplicate) -def test_delete_through_parent_link_removes_real_file_not_parent_link(root, link): - target = root / "target" - target.mkdir() - (target / "file").write_text("delete") - alias = link(root / "alias", target) - FileHelper(root, allow_symlinks=True).delete(alias / "file") - assert alias.is_symlink() - assert target.is_dir() - assert not (target / "file").exists() +def test_windows_read_does_not_require_ancestor_listing_portably( + root, monkeypatch, windows_victim_read_fd +): + (root / "victim").write_text("keep") + active = [] -@pytest.mark.parametrize("allow", [False, True]) -def test_empty_directory_nonrecursive_delete(root, allow): - files = FileHelper(root, allow_symlinks=allow) - files.mkdir("empty") - files.delete("empty") - assert not (root / "empty").exists() + @contextmanager + def handle(path, *, directory, pin=True, parent=None, traverse=False): + if pin and directory and not traverse and path != root: + raise PermissionError("ancestor listing denied") + active.append((path, pin)) + try: + yield 123 + finally: + assert active.pop() == (path, pin) + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr( + file_helper, "_windows_file_id", + lambda _, **kwargs: _WindowsFileIdentity("fileid128", 1, b"root"), + ) + monkeypatch.setattr(file_helper, "_windows_stat", lambda _: root.stat()) + with FileHelper(root) as files: + assert files.read_text("victim") == "keep" + with pytest.raises(PermissionError, match="ancestor listing denied"): + files.delete("victim") + assert files.read_text("victim") == "keep" + assert active == [] + + +@pytest.mark.parametrize("failure", ["open", "identity"]) +def test_windows_read_preserves_native_deletion_capability_error( + root, monkeypatch, failure, windows_victim_read_fd +): + (root / "victim").write_text("keep") + active = [] -@pytest.mark.parametrize("operation", ["mkdir", "create_bytes", "write_bytes", "delete"]) -def test_dangling_parent_cannot_be_used_for_mutation(root, link, operation): - alias = link(root / "alias", root / "missing") - files = FileHelper(root, allow_symlinks=True) - path = alias / "child" - args = (path, b"bad") if operation in ("create_bytes", "write_bytes") else (path,) - with pytest.raises(FileNotFoundError): - getattr(files, operation)(*args) - assert alias.is_symlink() - assert not (root / "missing").exists() + @contextmanager + def denied(*args, **kwargs): + if failure == "open" and not kwargs.get("pin", True): + raise PermissionError("root reference denied") + active.append(123) + try: + yield 123 + finally: + active.pop() + def identity(*args): + raise PermissionError("root reference denied") -def test_multi_link_cycle_and_excessive_chain_fail_explicitly(root, link): - link(root / "first", "second") - link(root / "second", "first") - files = FileHelper(root, allow_symlinks=True) - with pytest.raises(UnsupportedPathError, match="cycle"): - files.read_bytes("first") - (root / "target").write_text("ok") - for index in reversed(range(41)): - link(root / f"chain-{index}", "target" if index == 40 else f"chain-{index + 1}") - with pytest.raises(UnsupportedPathError, match="excessive chain"): - files.read_bytes("chain-0") + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", denied) + monkeypatch.setattr(file_helper, "_windows_file_id", identity) + monkeypatch.setattr(file_helper, "_windows_stat", lambda _: root.stat()) + with FileHelper(root) as files: + assert active == [] + assert files.read_text("victim") == "keep" + with pytest.raises(PermissionError, match="root reference denied"): + files.delete("victim") + assert not files._root_cleanup.alive -@pytest.mark.parametrize("operation", ["read_bytes", "write_bytes", "mkdir", "create_bytes", "delete"]) -def test_external_parent_is_never_traversed(root, link, operation): - outside = root.parent / "outside" - outside.mkdir() - (outside / "file").write_bytes(b"old") - alias = link(root / "alias", outside) - files = FileHelper(root, allow_symlinks=True) - path = alias / "file" - args = (path, b"new") if operation in ("write_bytes", "create_bytes") else (path,) - with pytest.raises(PathEscapeError): - getattr(files, operation)(*args) - assert (outside / "file").read_bytes() == b"old" - assert alias.is_symlink() +def test_windows_delete_checks_retained_handle_identity_portably( + root, monkeypatch, windows_victim_read_fd +): + (root / "victim").write_text("keep") + active = [] + identities = {} + @contextmanager + def handle(path, *, directory, pin=True, parent=None, traverse=False): + value = len(identities) + 1 + identities[value] = (1, b"replacement" if pin else b"original") + active.append(value) + try: + yield value + finally: + assert active.pop() == value -@pytest.mark.parametrize("kind", ["external", "dangling", "cycle"]) -@pytest.mark.parametrize("operation", ["read_bytes", "write_bytes"]) -def test_allow_reads_and_updates_reject_invalid_targets(root, link, kind, operation): - if kind == "external": - target = root.parent / "outside" - target.write_bytes(b"old") - error = PathEscapeError - elif kind == "dangling": - target = root / "missing" - error = FileNotFoundError - else: - target = root / "alias" - error = UnsupportedPathError - alias = link(root / "alias", target) - args = (alias, b"new") if operation == "write_bytes" else (alias,) - with pytest.raises(error): - getattr(FileHelper(root, allow_symlinks=True), operation)(*args) - assert alias.is_symlink() - if kind == "external": - assert target.read_bytes() == b"old" - if kind == "dangling": - assert not target.exists() + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr( + file_helper, "_windows_file_id", + lambda value, **kwargs: _WindowsFileIdentity("fileid128", *identities[value]), + ) + monkeypatch.setattr(file_helper, "_windows_stat", lambda _: root.stat()) + with FileHelper(root) as files: + with pytest.raises(FileHelperError, match="root changed"): + files.delete("victim") + assert len(active) == 1 + assert files.read_text("victim") == "keep" + assert active == [] -@pytest.mark.parametrize("kind", ["file", "directory", "external", "dangling", "cycle"]) +@pytest.mark.parametrize("scenario", ["same", "renamed-reference", "replacement-reused-id"]) @pytest.mark.parametrize("recursive", [False, True]) -def test_allow_leaf_delete_unlinks_only_link(root, link, kind, recursive): - target = root / "target" - if kind == "file": - target.write_bytes(b"keep") - elif kind == "directory": - target.mkdir() - (target / "keep").write_bytes(b"keep") - elif kind == "external": - target = root.parent / "outside" - target.write_bytes(b"keep") - elif kind == "cycle": - target = root / "alias" - alias = link(root / "alias", target) - FileHelper(root, allow_symlinks=True).delete(alias, recursive=recursive) - assert not os.path.lexists(alias) - if kind in ("file", "external"): - assert target.read_bytes() == b"keep" - elif kind == "directory": - assert (target / "keep").read_bytes() == b"keep" +def test_windows_legacy_root_identity_is_compared_live_with_the_selected_scheme( + root, monkeypatch, scenario, recursive, windows_delete_model +): + (root / "tree").mkdir() + (root / "tree/victim").write_text("keep") + active = [] + reference = None + queries = [] + changed = False + + @contextmanager + def handle(path, *, directory, pin=True, parent=None): + nonlocal reference + assert directory + with windows_delete_model.opened(path, parent=parent) as value: + active.append(value) + if not pin: + reference = value + try: + yield value + finally: + assert active.pop() == value + + def identity(value, *, kind=None): + queries.append((value, kind)) + assert kind in (None, "legacy64") + index = 1 + if changed and scenario != "same": + index = 2 if value == reference or scenario == "renamed-reference" else 1 + return _WindowsFileIdentity("legacy64", 1, index.to_bytes(8, "little")) + + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr(file_helper, "_windows_file_id", identity) + monkeypatch.setattr(file_helper, "_windows_stat", lambda _: root.stat()) + with FileHelper(root) as files: + assert files._windows_root_id is not None + assert files._windows_root_id.kind == "legacy64" + changed = True + selected = "tree" if recursive else "tree/victim" + if scenario == "replacement-reused-id": + with pytest.raises(FileHelperError, match="root changed"): + files.delete(selected, recursive=recursive) + assert (root / "tree/victim").read_text() == "keep" + else: + files.delete(selected, recursive=recursive) + assert not (root / "tree/victim").exists() + assert active == [reference] + assert active == [] + assert queries[0] == (reference, None) + assert len(queries) == 3 + assert queries[-1] == (reference, "legacy64") + assert all(kind == "legacy64" for _, kind in queries[1:]) + + +@pytest.mark.skipif(os.name != "nt", reason="Native Windows directory ACL semantics") +@pytest.mark.parametrize("consumer", ["helper", "policy", "state"]) +def test_windows_readonly_helper_supports_traverse_only_ancestor(root, consumer): + ancestor = root / "ancestor" + project = ancestor / "project" + project.mkdir(parents=True) + (project / "victim").write_text("keep") + (project / ".specify").mkdir() + (project / ".specify/init-options.json").write_text("{}") + (project / ".specify/integration.json").write_text('{"integration": "claude"}') + user = subprocess.check_output(["whoami"], text=True).strip() + subprocess.run( + ["icacls", str(ancestor), "/deny", f"{user}:(RD)"], + check=True, capture_output=True, text=True, + ) + try: + with FileHelper(project) as files: + if consumer == "helper": + assert files.read_text("victim") == "keep" + elif consumer == "policy": + from specify_cli._file_policy import read_project_options + assert read_project_options(project) == {} + else: + from specify_cli.integration_state import try_read_integration_json + state, error = try_read_integration_json(project) + assert error is None and state is not None and state["integration"] == "claude" + with pytest.raises(PermissionError): + files.delete("victim") + assert files.read_text("victim") == "keep" + finally: + subprocess.run( + ["icacls", str(ancestor), "/remove:d", user], + check=True, capture_output=True, text=True, + ) -def test_recursive_deny_preflight_leaves_entire_tree_untouched(root, link): - tree = root / "tree" - tree.mkdir() - (tree / "a-file").write_bytes(b"keep") - (tree / "b-dir").mkdir() - (tree / "b-dir/keep").write_bytes(b"keep") - alias = link(tree / "z-link", root / "missing") - with pytest.raises(SymlinkDeniedError): - FileHelper(root).delete(tree, recursive=True) - assert (tree / "a-file").read_bytes() == b"keep" - assert (tree / "b-dir/keep").read_bytes() == b"keep" +@pytest.mark.parametrize("failure", [False, True]) +@pytest.mark.parametrize("recursive", [False, True]) +def test_windows_delete_holds_ancestors_until_io_completes_portably( + root, link, monkeypatch, failure, recursive, windows_delete_model +): + import specify_cli.file_helper as module + + parent = root / "target/nested" + parent.mkdir(parents=True) + (parent / "victim").write_text("selected") + alias = link(root / "alias", root / "target") + active = [] + references = [] + events = [] + + @contextmanager + def handle(path, *, directory, pin=True, parent=None): + assert directory + actual = path if parent is None else windows_delete_model.locations[parent] / path + selected_handles = active if pin else references + selected_handles.append(actual) + try: + with windows_delete_model.opened(path, parent=parent) as value: + yield value + finally: + assert selected_handles.pop() == actual + + def assert_anchored(handle): + assert handle in windows_delete_model.locations + assert active[0] == Path(root.anchor) + assert root.resolve() in active + assert all(not part.is_symlink() for part in active) + events.append(windows_delete_model.locations[handle]) + + def observe_scan(handle): + assert_anchored(handle) + return windows_delete_model.names(handle) + + def remove(handle): + assert_anchored(handle) + if failure: + raise PermissionError("removal denied") + windows_delete_model.remove(handle) + + backend = SimpleNamespace(**vars(os)) + backend.name = "nt" + monkeypatch.setattr(module, "os", backend) + monkeypatch.setattr(module, "_windows_handle", handle) + monkeypatch.setattr(module, "_windows_directory_names", observe_scan) + monkeypatch.setattr(module, "_windows_delete", remove) + monkeypatch.setattr( + module, "_windows_file_id", + lambda _, **kwargs: _WindowsFileIdentity("fileid128", 1, b"root"), + ) + monkeypatch.setattr(module, "_windows_stat", lambda _: root.stat()) + files = FileHelper(root, allow_symlinks=True) + selected = alias / "nested" if recursive else alias / "nested/victim" + if failure: + with pytest.raises(PermissionError, match="removal denied"): + files.delete(selected, recursive=recursive) + assert (parent / "victim").read_text() == "selected" + else: + files.delete(selected, recursive=recursive) + assert not (parent / "victim").exists() + assert events + assert active == [] + assert references == [root.resolve()] + files.close() + assert references == [] assert alias.is_symlink() -def test_recursive_allow_does_not_descend_through_links(root, link): - tree = root / "tree" - tree.mkdir() - target = root / "retained" - target.mkdir() - (target / "keep").write_bytes(b"keep") +@pytest.mark.skipif(os.name == "nt", reason="POSIX descriptor model of native Windows handles") +@pytest.mark.parametrize("allow", [False, True]) +@pytest.mark.parametrize("recursive", [False, True]) +def test_windows_deletion_does_not_reopen_changed_parent_path( + root, link, monkeypatch, allow, recursive +): + parent = root / "tree" + parent.mkdir() + victim = parent / "victim" + victim.write_text("selected") outside = root.parent / "outside" outside.mkdir() - (outside / "keep").write_bytes(b"keep") - link(tree / "internal", target) - link(tree / "external", outside) - link(tree / "dangling", root / "missing") - link(tree / "cycle", tree) - (tree / "ordinary").write_bytes(b"delete") - FileHelper(root, allow_symlinks=True).delete(tree, recursive=True) - assert not tree.exists() - assert (target / "keep").read_bytes() == b"keep" - assert (outside / "keep").read_bytes() == b"keep" + (outside / "victim").write_text("keep") + retained = root / "retained" + opened = {} + changed = False + @contextmanager + def handle(path, *, directory, parent=None, **kwargs): + fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent) + try: + yield fd + finally: + os.close(fd) -def test_deletion_rechecks_parents_after_preflight(root, link, monkeypatch): - tree = root / "tree" - (tree / "nested").mkdir(parents=True) - (tree / "nested/file").write_text("keep") - plan = FileHelper._deletion_plan + @contextmanager + def entry(parent, name, *, deleting=False): + fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent) + opened[fd] = (parent, name) + try: + yield fd + finally: + del opened[fd] + os.close(fd) - def exchange(self, path, *, recursive): - result = plan(self, path, recursive=recursive) - if path == tree: - (tree / "nested").rename(root / "retained") - link(tree / "nested", root / "retained") - return result + @contextmanager + def anchored_root(self): + with handle(root, directory=True) as fd: + wrapper = getattr(file_helper, "_WindowsDirectory", None) + yield root if wrapper is None else wrapper(root, fd) + + def names(fd): + with os.scandir(fd) as entries: + return [item.name for item in entries] + + def remove(fd): + directory, name = opened[fd] + selected = os.fstat(fd) + current = os.stat(name, dir_fd=directory, follow_symlinks=False) + if not os.path.samestat(selected, current): + raise OSError(errno.ESTALE, "Model cannot remove an object renamed after opening") + if stat.S_ISDIR(selected.st_mode): + os.rmdir(name, dir_fd=directory) + else: + os.unlink(name, dir_fd=directory) - monkeypatch.setattr(FileHelper, "_deletion_plan", exchange) - with pytest.raises(FileHelperError, match="changed during deletion"): - FileHelper(root, allow_symlinks=True).delete(tree, recursive=True) - assert (root / "retained/file").read_text() == "keep" - assert (tree / "nested").is_symlink() + original_delete = FileHelper._delete_plan + + def exchange(self, selected, **kwargs): + nonlocal changed + if selected.path == victim and not changed: + changed = True + parent.rename(retained) + link(parent, outside) + return original_delete(self, selected, **kwargs) + + monkeypatch.setattr(file_helper, "_windows_handle", handle) + monkeypatch.setattr(file_helper, "_windows_entry", entry, raising=False) + monkeypatch.setattr(file_helper, "_windows_mode", lambda fd: os.fstat(fd).st_mode, raising=False) + monkeypatch.setattr(file_helper, "_windows_directory_names", names, raising=False) + monkeypatch.setattr(file_helper, "_windows_delete", remove, raising=False) + monkeypatch.setattr(FileHelper, "_deletion_root", anchored_root) + monkeypatch.setattr(FileHelper, "_delete_plan", exchange) + with FileHelper(root, allow_symlinks=allow) as files: + try: + files.delete(parent if recursive else victim, recursive=recursive) + except OSError: + assert changed + assert changed + assert (outside / "victim").read_text() == "keep" + assert not (retained / "victim").exists() + assert opened == {} + + +@pytest.mark.parametrize("allow", [False, True]) +def test_delete_through_trusted_root_alias(root, link, allow): + alias = link(root.parent / "alias", root) + (root / "tree/nested").mkdir(parents=True) + (root / "tree/nested/file").write_text("selected") + FileHelper(alias, allow_symlinks=allow).delete(alias / "tree", recursive=True) + assert alias.is_symlink() + assert root.is_dir() + assert not (root / "tree").exists() @pytest.mark.parametrize("allow", [False, True]) @@ -1081,6 +2914,7 @@ def test_exclusive_create_rejects_existing_leaf_before_open( target.write_bytes(b"keep") alias = link(root / "alias", root / "alias" if cyclic else target) original_target = os.readlink(alias) + files = FileHelper(root, allow_symlinks=True) opened = [] real_open = os.open @@ -1091,7 +2925,8 @@ def recording_open(path, flags, mode): monkeypatch.setattr("specify_cli.file_helper.os.open", recording_open) content = b"bad" if operation == "create_bytes" else "bad" with pytest.raises(FileExistsError) as error: - getattr(FileHelper(root, allow_symlinks=True), operation)(alias, content) + getattr(files, operation)(alias, content) + files.close() assert error.value.errno == errno.EEXIST assert opened == [] assert alias.is_symlink() @@ -1508,7 +3343,8 @@ def try_exchange(path, flags, *args, **kwargs): monkeypatch.setattr(os, "open", try_exchange) content = b"new" if operation == "create_bytes" else "new" - getattr(FileHelper(root, allow_symlinks=allow), operation)("parent/nested/new", content) + with FileHelper(root, allow_symlinks=allow) as files: + getattr(files, operation)("parent/nested/new", content) assert attempted assert (root / "parent/nested/new").read_bytes() == b"new" parent.rename(retained) @@ -1866,18 +3702,39 @@ def test_directory_reparse_entries_rejected_before_traversal_portably( junction.mkdir() (junction / "keep").write_text("keep") lstat = Path.lstat + stat_entry = os.stat + junction_identity = lstat(junction) + + def as_reparse(result): + return SimpleNamespace( + st_mode=result.st_mode, + st_file_attributes=0x400, + st_reparse_tag=0xA0000003, + ) def directory_reparse(path, **kwargs): result = lstat(path, **kwargs) if path == junction: - return SimpleNamespace( - st_mode=result.st_mode, - st_file_attributes=0x400, - st_reparse_tag=0xA0000003, - ) + return as_reparse(result) + return result + + def directory_reparse_stat(path, *args, **kwargs): + result = stat_entry(path, *args, **kwargs) + if kwargs.get("dir_fd") is not None and Path(path).name == junction.name: + return as_reparse(result) return result monkeypatch.setattr(Path, "lstat", directory_reparse) + monkeypatch.setattr(os, "stat", directory_reparse_stat) + if os.name == "nt": + native_mode = file_helper._windows_mode + + def reparse_mode(handle): + if os.path.samestat(file_helper._windows_stat(handle), junction_identity): + raise OSError(errno.ELOOP, "Unsupported Windows reparse point") + return native_mode(handle) + + monkeypatch.setattr(file_helper, "_windows_mode", reparse_mode) files = FileHelper(root, allow_symlinks=allow) for operation in ( lambda: files.read_bytes(junction / "keep"), diff --git a/tests/test_file_helper_overwrite.py b/tests/test_file_helper_overwrite.py index 6ed2238560..2a785a32d5 100644 --- a/tests/test_file_helper_overwrite.py +++ b/tests/test_file_helper_overwrite.py @@ -370,6 +370,7 @@ def test_unsupported_descriptor_backend_fails_without_path_fallback( path = tmp_path / "file" if existing: path.write_text("old") + files = FileHelper(tmp_path) def unexpected_open(*args, **kwargs): raise AssertionError("An unsupported backend must not open a destination") @@ -382,8 +383,9 @@ def unexpected_open(*args, **kwargs): else: attributes[capability] = value monkeypatch.setattr(file_helper, "os", SimpleNamespace(**attributes)) - with pytest.raises(OSError, match="unsupported") as caught: - FileHelper(tmp_path).overwrite_text("file", "new") + with files: + with pytest.raises(OSError, match="unsupported") as caught: + files.overwrite_text("file", "new") assert caught.value.errno == errno.ENOTSUP if existing: assert path.read_text() == "old" @@ -470,6 +472,7 @@ def test_overwrite_closes_descriptors_on_failure(tmp_path, monkeypatch, failure) parent.mkdir() (parent / "file").write_text("old") opened = [] + opened_leaves = [] original = os.open fstat = os.fstat @@ -478,6 +481,8 @@ def observe(path, flags, *args, **kwargs): raise PermissionError("test failure") fd = original(path, flags, *args, **kwargs) opened.append(fd) + if Path(path).name == "file": + opened_leaves.append(fd) return fd def fail(*args, **kwargs): @@ -497,10 +502,13 @@ def __exit__(self, *args): replacements["fdopen"] = lambda *args, **kwargs: FailedStream() elif failure != "open": replacements[failure] = fail - monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), **replacements})) - with pytest.raises(OSError, match="test failure"): - FileHelper(tmp_path).overwrite_text("parent/file", "new") + with FileHelper(tmp_path) as files: + monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), **replacements})) + with pytest.raises(OSError, match="test failure"): + files.overwrite_text("parent/file", "new") assert opened + if failure != "open": + assert len(opened_leaves) == 1 for fd in opened: with pytest.raises(OSError): fstat(fd) @@ -514,6 +522,7 @@ def test_windows_overwrite_pins_resolved_hierarchy_until_stream_closes( parent.mkdir() leaf = parent / "file" leaf.write_text("old") + files = FileHelper(tmp_path) events = [] active = [] @@ -546,13 +555,14 @@ def open_leaf(path): monkeypatch.setattr(file_helper, "os", SimpleNamespace(**{**vars(os), "name": "nt"})) monkeypatch.setattr(file_helper, "_windows_handle", pin) monkeypatch.setattr(file_helper, "_windows_overwrite_fd", open_leaf) - if failed_parent: - with pytest.raises(PermissionError, match="pin failed"): - FileHelper(tmp_path).overwrite_text("parent/file", "new") - assert leaf.read_text() == "old" - else: - FileHelper(tmp_path).overwrite_text("parent/file", "new") - assert events[-3:] == [("close", leaf), ("unpin", parent), ("unpin", tmp_path)] + with files: + if failed_parent: + with pytest.raises(PermissionError, match="pin failed"): + files.overwrite_text("parent/file", "new") + assert leaf.read_text() == "old" + else: + files.overwrite_text("parent/file", "new") + assert events[-3:] == [("close", leaf), ("unpin", parent), ("unpin", tmp_path)] assert not active diff --git a/tests/test_resolve_template_python_parity.py b/tests/test_resolve_template_python_parity.py index 9696358459..9a3cad1334 100644 --- a/tests/test_resolve_template_python_parity.py +++ b/tests/test_resolve_template_python_parity.py @@ -4,6 +4,7 @@ import json import os +import shutil import subprocess import sys import time @@ -12,9 +13,10 @@ import pytest from scripts.python import common as python_common -from tests.conftest import requires_bash +from tests.conftest import HAS_BASH, requires_bash from tests.parity_helpers import ( HAS_POWERSHELL, + _bash_posix_path, bash_cmd, clean_env, install_composition_stack, @@ -32,6 +34,99 @@ TEMPLATE = "constitution-template" +@pytest.mark.parametrize( + "layer", + [ + "core", "override", "preset", "preset-flat", "preset-unregistered", + "preset-flat-unregistered", "manifest", "manifest-path", "extension", + "extension-flat", "missing", + ], +) +def test_all_variants_resolve_templates_in_bracketed_project( + tmp_path: Path, layer: str +) -> None: + repo = make_repo(tmp_path, "project" if layer == "manifest-path" else "project [v1]") + install_scripts(repo, SCRIPT) + base = repo / ".specify/templates" + base.mkdir(parents=True) + (base / f"{TEMPLATE}.md").write_bytes(b"# Core\n") + expected = "# Core\n" + if layer == "missing": + (base / f"{TEMPLATE}.md").unlink() + elif layer == "override": + (base / "overrides").mkdir() + (base / "overrides" / f"{TEMPLATE}.md").write_bytes(b"# Override\n") + expected = "# Override\n" + elif layer.startswith("preset") or layer.startswith("manifest"): + presets = repo / ".specify/presets" + # Alphabetical fallback must differ from the registered priority order. + decoy = presets / "aaa/templates" / f"{TEMPLATE}.md" + decoy.parent.mkdir(parents=True) + decoy.write_bytes(b"# Decoy\n") + registered = "unregistered" not in layer + if registered: + (presets / ".registry").write_bytes( + b'{"presets":{"zzz":{"priority":1},"aaa":{"enabled":false}}}' + ) + else: + shutil.rmtree(presets / "aaa") + relative = f"{TEMPLATE}.md" if "flat" in layer else f"templates/{TEMPLATE}.md" + if layer.startswith("manifest"): + relative = "templates/custom [v1].md" + candidate = presets / "zzz" / relative + candidate.parent.mkdir(parents=True, exist_ok=True) + candidate.write_bytes(b"# Preset\n") + if layer.startswith("manifest"): + (presets / "zzz/preset.yml").write_bytes( + ( + "provides:\n templates:\n - type: template\n" + f" name: {TEMPLATE}\n file: {relative}\n" + ).encode("utf-8") + ) + expected = "# Preset\n" + elif layer.startswith("extension"): + relative = f"{TEMPLATE}.md" if layer.endswith("flat") else f"templates/{TEMPLATE}.md" + candidate = repo / ".specify/extensions/demo" / relative + candidate.parent.mkdir(parents=True) + candidate.write_bytes(b"# Extension\n") + expected = "# Extension\n" + + # The scripts parse preset.yml with Python; pin the interpreter that has + # PyYAML, since an ambient python3 (on Windows runners, say) may not. + env = clean_env() + env["SPECKIT_PYTHON_EXECUTABLE"] = sys.executable + commands = [(py_cmd(repo, SCRIPT, TEMPLATE, "--json"), env)] + if HAS_BASH: + bash_env = dict(env, SPECKIT_PYTHON_EXECUTABLE=_bash_posix_path(Path(sys.executable))) + commands.append((bash_cmd(repo, SCRIPT, TEMPLATE, "--json"), bash_env)) + if HAS_POWERSHELL: + commands.append((ps_cmd(repo, SCRIPT, TEMPLATE, "-Json"), env)) + for command, command_env in commands: + result = run(command, repo, command_env) + assert result.returncode == (1 if layer == "missing" else 0), result.stderr + if layer == "missing": + assert result.stdout == "" + else: + assert json_stdout(result)["TEMPLATE_CONTENT"] == expected + + +@pytest.mark.skipif(not HAS_POWERSHELL, reason="PowerShell not available") +def test_powershell_bracketed_manifest_reports_missing_python(tmp_path: Path) -> None: + repo = make_repo(tmp_path, "project [v1]") + install_scripts(repo, SCRIPT) + install_composition_stack(repo, TEMPLATE, "# Core\n") + command = ps_cmd(repo, SCRIPT, TEMPLATE, "-Json") + command[0] = shutil.which(command[0]) + env = clean_env() + env["PATH"] = str(tmp_path / "empty-bin") + + result = run(command, repo, env) + + assert result.returncode == 1 + assert result.stdout == "" + assert "Python 3 and PyYAML are required" in result.stderr + + def test_python_json_preserves_constitution_on_legacy_stdout(tmp_path: Path) -> None: repo = make_repo(tmp_path) install_scripts(repo, SCRIPT) diff --git a/tests/test_setup_tasks_python_parity.py b/tests/test_setup_tasks_python_parity.py index 5a341b57d5..3d34091626 100644 --- a/tests/test_setup_tasks_python_parity.py +++ b/tests/test_setup_tasks_python_parity.py @@ -6,9 +6,10 @@ import pytest -from tests.conftest import requires_bash +from tests.conftest import HAS_BASH, requires_bash from tests.parity_helpers import ( HAS_POWERSHELL, + _bash_posix_path, bash_cmd, break_wrap_layer, clean_env, @@ -26,6 +27,63 @@ SCRIPT = "setup-tasks" +@pytest.mark.parametrize("feature_env", [False, True], ids=["persisted", "env"]) +@pytest.mark.parametrize( + "layer", + [ + "core", "override", "preset", "preset-flat", "preset-registered", + "preset-flat-registered", "extension", "extension-flat", + ], +) +def test_all_variants_setup_tasks_in_bracketed_project( + tmp_path: Path, feature_env: bool, layer: str +) -> None: + repo = _setup_repo(tmp_path / "project [v1]") + feature = repo / "specs/001-my-feature" + for name in ["spec", "plan", "tasks"]: + (feature / f"{name}.md").write_bytes(f"# User {name}\r\n".encode("utf-8")) + before = {p: p.read_bytes() for p in feature.iterdir()} + expected_path = repo / ".specify/templates/tasks-template.md" + if layer == "override": + expected_path = repo / ".specify/templates/overrides/tasks-template.md" + expected_path.parent.mkdir(parents=True) + expected_path.write_bytes(b"# Custom Tasks\n") + elif layer != "core": + folder = "presets" if layer.startswith("preset") else "extensions" + relative = "tasks-template.md" if "flat" in layer else "templates/tasks-template.md" + expected_path = repo / ".specify" / folder / "demo" / relative + expected_path.parent.mkdir(parents=True) + expected_path.write_bytes(b"# Custom Tasks\n") + if layer.endswith("registered"): + presets = repo / ".specify/presets" + (presets / "aaa/templates").mkdir(parents=True) + (presets / "aaa/templates/tasks-template.md").write_bytes(b"# Decoy\n") + (presets / ".registry").write_bytes( + b'{"presets":{"demo":{"priority":1},"aaa":{"enabled":false}}}' + ) + env = clean_env() + if feature_env: + env["SPECIFY_FEATURE_DIRECTORY"] = "specs/001-my-feature" + env["SPECIFY_FEATURE"] = "001-my-feature" + commands = [("python", py_cmd(repo, SCRIPT, "--json"))] + if HAS_BASH: + commands.append(("bash", bash_cmd(repo, SCRIPT, "--json"))) + if HAS_POWERSHELL: + commands.append(("powershell", ps_cmd(repo, SCRIPT, "-Json"))) + for variant, command in commands: + result = run(command, repo, env) + assert result.returncode == 0, result.stderr + payload = json_stdout(result) + for key, path in (("FEATURE_DIR", feature), ("TASKS_TEMPLATE", expected_path)): + expected = {path} + if variant == "bash": + # Git Bash on Windows can print MSYS paths such as /c/Users/... + expected.add(Path(_bash_posix_path(path))) + assert Path(payload[key]) in expected, (variant, key, payload[key]) + assert payload["TASKS_TEMPLATE_CONTENT"] == expected_path.read_bytes().decode("utf-8") + assert {p: p.read_bytes() for p in feature.iterdir()} == before + + def test_installed_python_json_preserves_stock_tasks_template( tmp_path: Path, ) -> None: diff --git a/tests/test_stack_external_skills.py b/tests/test_stack_external_skills.py index 61e40424e6..404ba87a55 100644 --- a/tests/test_stack_external_skills.py +++ b/tests/test_stack_external_skills.py @@ -388,7 +388,6 @@ def test_init_with_skip_external_skills_no_npx(tmp_path, monkeypatch): "moodle5-plugin", "--skip-external-skills", "--ignore-agent-tools", - "--no-git", "--script", "sh", ], @@ -456,7 +455,6 @@ def fake_sync(project_root, *, skills_agent, integration_skills_dir, skill_names "--stack", "laravel-inertia-react", "--ignore-agent-tools", - "--no-git", "--script", "sh", ], @@ -512,7 +510,6 @@ def fake_sync(project_root, *, skills_agent, integration_skills_dir, skill_names "--stack", "laravel-inertia-react", "--ignore-agent-tools", - "--no-git", "--script", "sh", ], diff --git a/tests/workflows/conftest.py b/tests/workflows/conftest.py index 03d28890dd..e8fc59828e 100644 --- a/tests/workflows/conftest.py +++ b/tests/workflows/conftest.py @@ -6,6 +6,7 @@ import sys import tempfile from pathlib import Path +from types import SimpleNamespace import pytest @@ -24,3 +25,74 @@ def project_dir(temp_dir): workflows_dir = temp_dir / ".specify" / "workflows" workflows_dir.mkdir(parents=True, exist_ok=True) return temp_dir + + +@pytest.fixture +def bundled_review(monkeypatch, project_dir): + """Run a canonical workflow up to a review, without invoking an agent.""" + from specify_cli.workflows.base import RunStatus, StepResult, StepStatus + from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine + from specify_cli.workflows.step import gate as gate_module + from specify_cli.workflows.step.command import CommandStep + + def start(workflow_id: str, gate_id: str): + commands: list[str] = [] + tty = gate_id == "review-plan" + + def execute_command(self, config, context): + commands.append(config["command"]) + return StepResult(status=StepStatus.COMPLETED) + + def approve_previous_review(message, options): + nonlocal tty + assert tty + tty = False + return "approve" + + monkeypatch.setattr(CommandStep, "execute", execute_command) + monkeypatch.setattr( + gate_module, "sys", + SimpleNamespace(stdin=SimpleNamespace(isatty=lambda: tty)), + ) + monkeypatch.setattr( + gate_module.GateStep, "_prompt", staticmethod(approve_previous_review) + ) + definition = WorkflowDefinition.from_yaml( + Path(__file__).resolve().parents[2] + / "workflows" / workflow_id / "workflow.yml" + ) + engine = WorkflowEngine(project_dir) + assert engine.validate(definition) == [] + inputs = ( + {"spec": "Test feature"} + if workflow_id == "speckit" + else {"report": "Test bug report", "slug": "test-bug"} + ) + state = engine.execute(definition, inputs={**inputs, "integration": "copilot"}) + assert state.status is RunStatus.PAUSED + assert state.current_step_id == gate_id + monkeypatch.setattr( + gate_module.GateStep, "_prompt", + staticmethod(lambda *_: pytest.fail("Unexpected review prompt")), + ) + return engine, state, commands + + return start + + +@pytest.fixture +def resume_bundled_review(monkeypatch, project_dir): + from typer.testing import CliRunner + + from specify_cli import app + from specify_cli.workflows.engine import RunState + + monkeypatch.setenv("SPECIFY_INIT_DIR", str(project_dir)) + + def resume(state, input_name: str, value: str): + result = CliRunner().invoke( + app, ["workflow", "resume", state.run_id, "--input", f"{input_name}={value}"] + ) + return result, RunState.load(state.run_id, project_dir) + + return resume diff --git a/tests/workflows/test_bundled_bugfix_assess_workflows.py b/tests/workflows/test_bundled_bugfix_assess_workflows.py index f9467abf62..37b3c6eea2 100644 --- a/tests/workflows/test_bundled_bugfix_assess_workflows.py +++ b/tests/workflows/test_bundled_bugfix_assess_workflows.py @@ -2,10 +2,14 @@ from __future__ import annotations +from types import SimpleNamespace + import pytest from specify_cli._assets import _locate_bundled_workflow +from specify_cli.workflows.base import RunStatus from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow +from specify_cli.workflows.step import gate as gate_module def _load_workflow(workflow_id: str) -> WorkflowDefinition: @@ -91,3 +95,72 @@ def test_bundled_workflow_has_required_inputs( for input_id in required_inputs: assert definition.inputs[input_id].get("required") is True assert definition.inputs.get("integration", {}).get("default") == "auto" + + +def test_verdict_resume(bundled_review, resume_bundled_review) -> None: + _, state, commands = bundled_review("bugfix", "review-assessment") + + result, resumed = resume_bundled_review( + state, "bug_review_assessment_verdict", "approve" + ) + + assert result.exit_code == 0, result.output + assert resumed.status is RunStatus.COMPLETED + assert resumed.step_results["review-assessment"]["output"]["choice"] == "approve" + assert resumed.step_results["review-assessment"]["status"] == "completed" + assert commands == ["speckit.bug.assess", "speckit.bug.fix", "speckit.bug.test"] + + +@pytest.mark.parametrize("explicit_empty", [False, True], ids=["omitted", "empty"]) +@pytest.mark.parametrize("tty", [False, True], ids=["non-tty", "tty"]) +def test_empty_verdict_preserves_review( + bundled_review, monkeypatch, explicit_empty, tty +) -> None: + engine, state, commands = bundled_review("bugfix", "review-assessment") + assert state.inputs["bug_review_assessment_verdict"] == "" + prompts = [] + + def prompt(message, options): + prompts.append((message, options)) + return "reject" + + monkeypatch.setattr( + gate_module, "sys", + SimpleNamespace(stdin=SimpleNamespace(isatty=lambda: tty)), + ) + monkeypatch.setattr(gate_module.GateStep, "_prompt", staticmethod(prompt)) + + resumed = engine.resume( + state.run_id, + {"bug_review_assessment_verdict": ""} if explicit_empty else None, + ) + + assert resumed.status is (RunStatus.ABORTED if tty else RunStatus.PAUSED) + assert len(prompts) == int(tty) + assert resumed.inputs["bug_review_assessment_verdict"] == "" + assert resumed.step_results["review-assessment"]["output"]["choice"] == ( + "reject" if tty else None + ) + assert commands == ["speckit.bug.assess"] + + +@pytest.mark.parametrize("value", ["reject", "maybe", " ", "aPpRoVe"]) +def test_bound_verdict_preserves_decisions(bundled_review, value) -> None: + engine, state, commands = bundled_review("bugfix", "review-assessment") + + resumed = engine.resume( + state.run_id, {"bug_review_assessment_verdict": value} + ) + + if value == "aPpRoVe": + assert resumed.status is RunStatus.COMPLETED + assert resumed.step_results["review-assessment"]["output"]["choice"] == "approve" + assert commands == ["speckit.bug.assess", "speckit.bug.fix", "speckit.bug.test"] + else: + expected = RunStatus.ABORTED if value == "reject" else RunStatus.FAILED + assert resumed.status is expected + assert commands == ["speckit.bug.assess"] + if value == "reject": + assert resumed.step_results["review-assessment"]["output"]["aborted"] is True + else: + assert "does not match any configured option" in resumed.error diff --git a/tests/workflows/test_bundled_speckit_workflow.py b/tests/workflows/test_bundled_speckit_workflow.py index d8b07cb908..83dabf76ad 100644 --- a/tests/workflows/test_bundled_speckit_workflow.py +++ b/tests/workflows/test_bundled_speckit_workflow.py @@ -3,10 +3,14 @@ from __future__ import annotations from pathlib import Path +from types import SimpleNamespace +import pytest import yaml +from specify_cli.workflows.base import RunStatus from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow +from specify_cli.workflows.step import gate as gate_module REPO_ROOT = Path(__file__).resolve().parents[2] BUNDLED = REPO_ROOT / "workflows" / "speckit" / "workflow.yml" @@ -56,3 +60,124 @@ def test_reference_doc_matches_the_shipped_workflow() -> None: format lists however reads best; only the content has to agree. """ assert _documented_workflow() == yaml.safe_load(BUNDLED.read_text(encoding="utf-8")) + + +@pytest.mark.parametrize( + ("gate_id", "input_name", "next_command"), + [ + ("review-spec", "speckit_review_spec_verdict", "speckit.plan"), + ("review-plan", "speckit_review_plan_verdict", "speckit.tasks"), + ], +) +def test_verdict_resume( + bundled_review, resume_bundled_review, gate_id, input_name, next_command +) -> None: + _, state, commands = bundled_review("speckit", gate_id) + previous_commands = commands.copy() + + result, resumed = resume_bundled_review(state, input_name, "approve") + + assert result.exit_code == 0, result.output + assert resumed.step_results[gate_id]["output"]["choice"] == "approve" + assert resumed.step_results[gate_id]["status"] == "completed" + assert commands[:len(previous_commands)] == previous_commands + assert commands[len(previous_commands)] == next_command + assert all(commands.count(command) == 1 for command in previous_commands) + if gate_id == "review-spec": + assert resumed.status is RunStatus.PAUSED + assert resumed.current_step_id == "review-plan" + assert resumed.inputs["speckit_review_plan_verdict"] == "" + assert resumed.step_results["review-plan"]["output"]["choice"] is None + else: + assert resumed.status is RunStatus.COMPLETED + + +@pytest.mark.parametrize( + ("gate_id", "input_name"), + [ + ("review-spec", "speckit_review_spec_verdict"), + ("review-plan", "speckit_review_plan_verdict"), + ], +) +@pytest.mark.parametrize("explicit_empty", [False, True], ids=["omitted", "empty"]) +@pytest.mark.parametrize("tty", [False, True], ids=["non-tty", "tty"]) +def test_empty_verdict_preserves_review( + bundled_review, monkeypatch, gate_id, input_name, explicit_empty, tty +) -> None: + engine, state, commands = bundled_review("speckit", gate_id) + previous_commands = commands.copy() + assert state.inputs[input_name] == "" + prompts = [] + + def prompt(message, options): + prompts.append((message, options)) + return "reject" + + monkeypatch.setattr( + gate_module, "sys", + SimpleNamespace(stdin=SimpleNamespace(isatty=lambda: tty)), + ) + monkeypatch.setattr(gate_module.GateStep, "_prompt", staticmethod(prompt)) + + resumed = engine.resume( + state.run_id, {input_name: ""} if explicit_empty else None + ) + + assert resumed.status is (RunStatus.ABORTED if tty else RunStatus.PAUSED) + assert len(prompts) == int(tty) + assert resumed.inputs[input_name] == "" + assert resumed.step_results[gate_id]["output"]["choice"] == ( + "reject" if tty else None + ) + assert commands == previous_commands + + +@pytest.mark.parametrize( + ("gate_id", "input_name"), + [ + ("review-spec", "speckit_review_spec_verdict"), + ("review-plan", "speckit_review_plan_verdict"), + ], +) +@pytest.mark.parametrize("value", ["reject", "maybe", " ", "aPpRoVe"]) +def test_bound_verdict_preserves_decisions( + bundled_review, gate_id, input_name, value +) -> None: + engine, state, commands = bundled_review("speckit", gate_id) + previous_commands = commands.copy() + + resumed = engine.resume(state.run_id, {input_name: value}) + + if value == "aPpRoVe": + assert resumed.step_results[gate_id]["output"]["choice"] == "approve" + assert resumed.step_results[gate_id]["status"] == "completed" + assert len(commands) > len(previous_commands) + else: + expected = RunStatus.ABORTED if value == "reject" else RunStatus.FAILED + assert resumed.status is expected + assert commands == previous_commands + if value == "reject": + assert resumed.step_results[gate_id]["output"]["aborted"] is True + else: + assert "does not match any configured option" in resumed.error + + +@pytest.mark.parametrize( + ("gate_id", "other_input"), + [ + ("review-spec", "speckit_review_plan_verdict"), + ("review-plan", "speckit_review_spec_verdict"), + ], +) +def test_other_review_verdict_does_not_approve_gate( + bundled_review, gate_id, other_input +) -> None: + engine, state, commands = bundled_review("speckit", gate_id) + previous_commands = commands.copy() + + resumed = engine.resume(state.run_id, {other_input: "approve"}) + + assert resumed.status is RunStatus.PAUSED + assert resumed.current_step_id == gate_id + assert resumed.step_results[gate_id]["output"]["choice"] is None + assert commands == previous_commands diff --git a/workflows/bugfix/workflow.yml b/workflows/bugfix/workflow.yml index a914eeafa9..ff44a1b89c 100644 --- a/workflows/bugfix/workflow.yml +++ b/workflows/bugfix/workflow.yml @@ -2,13 +2,13 @@ schema_version: "1.0" workflow: id: "bugfix" name: "Guided Bug Fix" - version: "1.0.0" + version: "1.0.1" author: "GitHub" description: "Runs bug assess → human review gate → bug fix → bug test on a bug report" requires: - # Matches the composed bug extension's requirement (extensions/bug/extension.yml). - speckit_version: ">=0.9.0" + # Gate verdict inputs require CLI 0.15.1 or later. + speckit_version: ">=0.15.1" inputs: report: @@ -23,6 +23,9 @@ inputs: type: string default: "auto" prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)" + bug_review_assessment_verdict: + type: string + default: "" steps: - id: assess @@ -33,6 +36,7 @@ steps: - id: review-assessment type: gate + verdict_input: bug_review_assessment_verdict message: "Review the assessment before any code change." options: [approve, reject] on_reject: abort diff --git a/workflows/catalog.community.json b/workflows/catalog.community.json index b500dff1fd..d2b34b0ef3 100644 --- a/workflows/catalog.community.json +++ b/workflows/catalog.community.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-11-08T00:00:00Z", + "updated_at": "2026-11-09T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/catalog.community.json", "workflows": { "ado-lifecycle": { @@ -8,12 +8,12 @@ "name": "ADO story lifecycle", "description": "Azure DevOps story to an open PR: spec, plan, tasks, push, implement, gate, review, PR. Every board or PR change is preview, human gate, apply. The story closes after merge.", "author": "praveenlavu", - "version": "0.3.1", - "url": "https://raw.githubusercontent.com/praveenlavu/spec-kit-ado/v0.3.1/workflows/ado-lifecycle/workflow.yml", - "sha256": "eaa2d4fa2bf3f5134771639549c1da5d7401dd5f4035cf008a0021b14c648c40", + "version": "0.3.2", + "url": "https://raw.githubusercontent.com/praveenlavu/spec-kit-ado/v0.3.2/workflows/ado-lifecycle/workflow.yml", + "sha256": "85a52faeeefe793c22afb694d0484b906dabca84eb6b5cfa4db10c23003da52a", "repository": "https://github.com/praveenlavu/spec-kit-ado", - "documentation": "https://github.com/praveenlavu/spec-kit-ado/blob/v0.3.1/workflows/ado-lifecycle/README.md", - "changelog": "https://github.com/praveenlavu/spec-kit-ado/blob/v0.3.1/workflows/ado-lifecycle/CHANGELOG.md", + "documentation": "https://github.com/praveenlavu/spec-kit-ado/blob/v0.3.2/workflows/ado-lifecycle/README.md", + "changelog": "https://github.com/praveenlavu/spec-kit-ado/blob/v0.3.2/workflows/ado-lifecycle/CHANGELOG.md", "license": "MIT", "requires": { "speckit_version": ">=1.2.1", @@ -35,7 +35,7 @@ "governance" ], "created_at": "2026-11-08T00:00:00Z", - "updated_at": "2026-11-08T00:00:00Z" + "updated_at": "2026-11-09T00:00:00Z" }, "pipeline": { "id": "pipeline", diff --git a/workflows/catalog.json b/workflows/catalog.json index d55754a819..55a29c5672 100644 --- a/workflows/catalog.json +++ b/workflows/catalog.json @@ -1,6 +1,6 @@ { "schema_version": "1.0", - "updated_at": "2026-09-10T00:00:00Z", + "updated_at": "2026-11-11T00:00:00Z", "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/catalog.json", "workflows": { "speckit": { @@ -8,7 +8,7 @@ "name": "Full SDD Cycle", "description": "Runs specify \u2192 plan \u2192 tasks \u2192 implement with review gates", "author": "GitHub", - "version": "1.0.1", + "version": "1.0.2", "url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/speckit/workflow.yml", "tags": ["sdd", "full-cycle"], "bundled": true @@ -18,7 +18,7 @@ "name": "Guided Bug Fix", "description": "Runs bug assess → human review gate → bug fix → bug test on a bug report", "author": "GitHub", - "version": "1.0.0", + "version": "1.0.1", "url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/bugfix/workflow.yml", "tags": ["bug", "triage", "workflow", "qa"], "bundled": true diff --git a/workflows/speckit/workflow.yml b/workflows/speckit/workflow.yml index 571318af4d..5b91f379b8 100644 --- a/workflows/speckit/workflow.yml +++ b/workflows/speckit/workflow.yml @@ -2,15 +2,13 @@ schema_version: "1.0" workflow: id: "speckit" name: "Full SDD Cycle" - version: "1.0.1" + version: "1.0.2" author: "GitHub" description: "Runs specify → plan → tasks → implement with review gates" requires: - # 0.8.5 is the first release with engine-side resolution of the - # ``integration: "auto"`` default. Older versions would treat "auto" - # as a literal integration key and fail at dispatch. - speckit_version: ">=0.8.5" + # Gate verdict inputs require CLI 0.15.1 or later. + speckit_version: ">=0.15.1" integrations: # The four commands below (specify, plan, tasks, implement) are core # spec-kit commands provided by every integration. The list here is an @@ -35,6 +33,12 @@ inputs: type: string default: "auto" prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)" + speckit_review_spec_verdict: + type: string + default: "" + speckit_review_plan_verdict: + type: string + default: "" steps: - id: specify @@ -45,6 +49,7 @@ steps: - id: review-spec type: gate + verdict_input: speckit_review_spec_verdict message: "Review the generated spec before planning." options: [approve, reject] on_reject: abort @@ -57,6 +62,7 @@ steps: - id: review-plan type: gate + verdict_input: speckit_review_plan_verdict message: "Review the plan before generating tasks." options: [approve, reject] on_reject: abort