[mvanhorn]

Description

OpenCode's file search reports that the hidden Spec Kit project directory contains no files. Local and open-weight models then miss the constitution, templates, and scripts the Spec Kit commands need. Models that retry by reading a known path directly often continue anyway. OpenCode 1.18.31 and 1.19.3 run that glob through ripgrep without --hidden, so dot-directories are skipped. Re-including the tree on that path takes both !.specify/ and !.specify/** in the project-root .ignore; the contents rule alone still returns no .specify/**/* matches. The OpenCode integration only installed command files and never wrote those exceptions.

OpenCode install and upgrade accept an opt-in --configure-ignore-file flag that appends whichever of !.specify/ and !.specify/** is not already an exact line, keeps existing .ignore bytes as a prefix (including non-ASCII text, CRLF, and a missing final newline), and records the root file as partial ownership. Symlinks, non-files, and unwritable paths are rejected before any write. Uninstall, including with --force, leaves .ignore in place, and installs without the flag, along with other integrations, leave it untouched. Upgrade replays the stored flag, a new --integration-options value replaces the whole stored set, and the integrations reference documents the option and the checked ripgrep behavior.

Fixes #5028

Testing

• Tested locally with uv run specify --help
  Ran uv run python -m pytest tests/test_agent_config_consistency.py -q locally on macOS for the spec-kit OpencodeIntegration change; it fails the same way on the base branch, so the failure predates this change (it fails the same way on upstream/main).
• Ran existing tests with uv sync && uv run pytest
uv sync && uv run pytest was not run locally for the spec-kit OpencodeIntegration change either.
• Tested with a sample project (if applicable)
  No one has checked the spec-kit OpencodeIntegration change with a sample project yet.

Ran uv run python -m pytest tests/test_agent_config_consistency.py -q locally on macOS for the spec-kit OpencodeIntegration change; it fails the same way on the base branch, so the failure predates this change (it fails the same way on upstream/main). Tests for the spec-kit OpencodeIntegration change live in tests/integrations/test_integration_opencode.py.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

AI disclosure

AI was used for assistance.

• Extent: AI wrote the code changes and drafted this description.

[Copilot]

🟡 Changes recommended

Write failures can destroy existing ignore rules, and rejected destinations can leave integration updates partially applied.

5 open issues

• Add a language to the Markdown code fence · New
• Document partial ownership effects on upgrades and opt-out · New
• Preflight .ignore before mutating setup files · New
• Preserve non-UTF-8 .ignore files during opt-in · New
• Use atomic journal-aware writes for .ignore updates · New

What changed in this PR

Adds an opt-in OpenCode integration option so file search can discover hidden Spec Kit project files.

Changes:

• Adds .ignore exceptions with partial ownership tracking.
• Tests preservation, upgrade persistence, uninstall, and failure handling.
• Documents usage and checked OpenCode behavior.

Validation used isolated checks; project tests and baseline comparison were not run.

AI-generated for the requester by GitHub Copilot (model: unknown; autonomous review).

File	Description
tests/​integrations/​test_integration_opencode.py	Adds option and lifecycle coverage.
src/​specify_cli/​integrations/​opencode/​__init__.py	Implements opt-in ignore configuration.
docs/​reference/​integrations.md	Explains discovery behavior and usage.

_{Review effort: Max}

[mnriem]

Please address Copilot feedback and fix test & lint errors

[Copilot]

🔵 Needs a closer look

Failed writes can destroy existing .ignore rules, and non-UTF-8 comments abort configuration.

4 open issues

• Use atomic journal-aware writes for .ignore updates
• Preserve non-UTF-8 .ignore files during opt-in
• Preflight .ignore before mutating setup files
• Document partial ownership effects on upgrades and opt-out

4 previously missed issues

In code that hasn't changed since last review

Deleting rules does not persistently opt out while OpenCode is installed

docs/​reference/​integrations.md:518

Deleting these lines is not a persistent opt-out while OpenCode remains installed. Partial ownership still hashes the entire .ignore, so any user edit blocks a normal upgrade (manifest.py:340–364, command_upgrade.py:80–87). Adding --force replays the stored flag and restores the rules; it also permits overwriting customized shared scripts and templates. Document the hash-tracking consequence and the safe order: first upgrade with options that omit this flag while preserving other options, then delete the lines. After uninstall, deleting them directly is sufficient.

AI-generated by GitHub Copilot for the review requester (model: unknown; autonomous).

Non-UTF-8 .ignore content aborts install or upgrade

src/​specify_cli/​integrations/​opencode/​__init__.py:153

An existing .ignore with a non-UTF-8 comment, such as Latin-1 # café, raises UnicodeDecodeError here and aborts the opted-in install or upgrade. Only ASCII rules need recognition. Use lossless decoding for this membership check and add a non-UTF-8 preservation case; the original bytes can then remain untouched.

AI-generated by GitHub Copilot for the review requester (model: unknown; autonomous).

Non-atomic .ignore writes can destroy existing user rules

src/​specify_cli/​integrations/​opencode/​__init__.py:192

record_file() calls Path.write_bytes() (manifest.py:208), which truncates the existing .ignore before writing. A write failure after opening can destroy user rules, and built-in-only installs/upgrades have no lifecycle journal to restore them (_lifecycle.py:468–469). The new disk-full mock raises before opening, so it misses this failure. Use an atomic replacement that preserves permissions, safe-path checks, and lifecycle notifications, and test a failure after output begins.

AI-generated by GitHub Copilot for the review requester (model: unknown; autonomous).

Platform-dependent symlink and permission tests fail unexpectedly

tests/​integrations/​test_integration_opencode.py:341

Direct symlink creation can fail on Windows without the required privilege, and the permission-rejection assertions fail under root, which can still read and write these files. Either condition fails this combined test before its remaining cases run. Split the cases so only unsupported symlink and permission checks are skipped, following tests/integrations/test_integration_kimi.py:17–30 and tests/extensions/github/test_github_extension.py:1408–1411. Keep directory and write-failure checks platform-independent.

AI-generated by GitHub Copilot for the review requester (model: unknown; autonomous).

1 resolved since last review

• Add a language to the Markdown code fence

_{Review effort: Max}

[mnriem]

Please address Copilot feedback. If not applicable please explain why

[mvanhorn]

Addressed the Copilot review: the .ignore section now documents that upgrades still hash-check the file, that --force also overwrites edited command files, and that the stored flag must be cleared before removing the rules. .ignore is checked before command files are rendered and again before the write, the two rules are matched as bytes so a non-UTF-8 file is kept as-is, and the write goes through the journal-aware atomic writer with the file mode kept. Also merged main; since #5034 moved agent docs, the OpenCode section now lives in docs/integrations/opencode.md. ruff, markdownlint and the full pytest suite pass locally.

[Copilot]

🟡 Changes recommended

Permission validation and Windows test compatibility defects remain unresolved.

3 open issues

• Check parent directory writability before replacing command files · New
• Make permission mode assertions platform-independent on Windows · New
• Match temporary-file prefix in cleanup regression test · New

4 resolved since last review

• Use atomic journal-aware writes for .ignore updates
• Preserve non-UTF-8 .ignore files during opt-in
• Preflight .ignore before mutating setup files
• Document partial ownership effects on upgrades and opt-out

_{Review effort: Max}

[mnriem]

Please address Copilot feedback. If not applicable, please explain why. And fix test & lint errors

[mvanhorn]

Addressed the three Copilot comments in 76d791d (the fix plus a merge of main):

• The .ignore preflight now requires a writable project root whenever .ignore has to change, including replacing an existing writable file, so setup fails before any command files are written. Added a regression test for a writable .ignore in a read-only root (skipped on Windows, where directories always report writable).
• The mode-preservation test now compares against the mode recorded right after chmod(), the same pattern as tests/test_merge.py. That was the assert 438 == 416 failure on the Windows jobs.
• The cleanup assertion now matches the atomic writer's ..ignore. temp prefix.

Ran locally on macOS: uvx ruff@0.15.0 check src tests and uv run pytest tests/integrations -q -p no:cacheprovider, both passing. The Windows jobs could not run here.

[Copilot]

🟡 Changes recommended

Existing ignore-file content can still prevent discovery after configuration reports success.

2 open issues

• Detect overridden .ignore re-inclusion exceptions · New
• Reject non-UTF-8 .ignore files before writing commands · New

3 resolved since last review

• Make permission mode assertions platform-independent on Windows
• Check parent directory writability before replacing command files
• Match temporary-file prefix in cleanup regression test

_{Review effort: Max}

[mnriem]

Please address Copilot feedback

[mvanhorn]

@mnriem both Copilot notes from the last review are handled in 5aaaeab:

• The .ignore checks now run before install, switch or upgrade write any shared templates or scripts, so a forced upgrade with a bad .ignore leaves the project as it was.
• Script probes only cover the --script variant being installed, plus scripts already in .specify/scripts.

Both have regression tests. Locally: ruff check src tests passes, markdownlint-cli2 on the OpenCode doc is clean, and the opencode, install/switch/upgrade, shared-infra and related suites pass (1186 passed, 27 skipped).

[Copilot]

🟡 Changes recommended

Preflight omits planned manifest and event-dispatcher outputs, allowing built-in-only installs or upgrades to fail after shared files have been created or overwritten without rollback.

1 open issue

• Move shared lifecycle changes to a prerequisite PR · New

2 resolved since last review

• The script probes include every bundled variant, but install_shared_infra() only copies the…
• [P2] With --force --integration-options="--configure-ignore-file", a built-in-only upgrade…

_{Review effort: Max}

[mvanhorn]

Split out into #5198 as the prerequisite PR. It carries the preflight_setup() hook, the install/switch/upgrade wiring and shared_infra.script_variant_dirs(), with tests that use only existing built-in integrations: a refusal from each command exits 1 and leaves every project file byte-identical, and an accepted setup calls the hook once with the resolved options and script type.

The source changes in #5198 are identical to the shared part of this PR, so once it merges I'll merge main here and this diff drops to the OpenCode package, its tests and docs.

[mnriem]

Please separate the shared changes into its own PR as per the guidance

[mvanhorn]

@mnriem the shared preflight hook went in separately and is now on main, and I merged main into this branch in 7882944. This PR now only touches the OpenCode integration, its docs and its tests.

[Copilot]

🟡 Changes recommended

Blanket ignore exceptions can expose private configuration and API keys, while incomplete preflight checks can leave project files overwritten or the existing integration removed after failure.

9 open issues

• Preserve exclusions for private local configuration files · New
• Read .ignore safely to prevent symlink-swap races · New
• Detect concurrent .ignore edits before replacing the file · New
• Catch regex errors from malformed ignore ranges · New
• Check nested ignore rules for required files · New
• Skip permission tests when running as root · New
• Use consistent opencode spelling in docs and help text · New
• Add coverage for clearing integration options · New
• Move shared lifecycle changes to a prerequisite PR

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Unresolved ignore-rule gaps leave credential-bearing extension configurations discoverable, including backup copies and files re-included by later negations.

10 open issues

• Protect local-config files at every depth and backup directories · New
• Reapply the private exclusion after later ignore negations · New
• Detect concurrent .ignore edits before replacing the file
• Read .ignore safely to prevent symlink-swap races
• Skip permission tests when running as root
• Check nested ignore rules for required files
• Catch regex errors from malformed ignore ranges
• Add coverage for clearing integration options
• Use consistent opencode spelling in docs and help text
• Move shared lifecycle changes to a prerequisite PR

1 resolved since last review

• Preserve exclusions for private local configuration files

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Ignore-rule ordering flaws and missing backup exclusions can leave credential-bearing extension configurations and their backups discoverable.

4 open issues

• Reapply the private exclusion after later ignore negations
• Protect local-config files at every depth and backup directories
• Add coverage for clearing integration options
• Move shared lifecycle changes to a prerequisite PR

6 resolved since last review

• Detect concurrent .ignore edits before replacing the file
• Read .ignore safely to prevent symlink-swap races
• Skip permission tests when running as root
• Check nested ignore rules for required files
• Catch regex errors from malformed ignore ranges
• Use consistent opencode spelling in docs and help text

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Credential-file protection remains unverified on opencode’s native glob discovery path, and the documented flag-clearing flow lacks regression coverage.

3 open issues

• Test credential exclusions with ripgrep-backed globs · New
• Add coverage for clearing integration options
• Move shared lifecycle changes to a prerequisite PR

2 resolved since last review

• Reapply the private exclusion after later ignore negations
• Protect local-config files at every depth and backup directories

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

A race between the .ignore change check and atomic replacement can silently overwrite concurrent edits or a newly created file.

2 open issues

• Add coverage for clearing integration options
• Move shared lifecycle changes to a prerequisite PR

1 resolved since last review

• Test credential exclusions with ripgrep-backed globs

_{Review effort: Max}