Skip to content

Commit a2d68de

Browse files
authored
fix: opt-in OpenCode discovery of hidden Spec Kit files (#5032)
* fix: opt-in OpenCode discovery of hidden Spec Kit files 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 Assisted-by: AI * docs: add a language to the OpenCode .ignore code fence * fix(opencode): validate .ignore before setup and write it atomically Address the rest of the Copilot review on #5032. The code fence fix already landed in b395863; this covers the other four comments: - Document that upgrades still hash-check .ignore, that --force also overwrites edited command files, and that the stored flag must be cleared before removing the two rules. - Check .ignore (symlink, directory, unreadable, unwritable) before command files are rendered, and check it again before the write, so a rejected destination leaves existing command files unchanged. - Match the two rules as ASCII bytes so a non-UTF-8 .ignore is kept byte for byte instead of raising UnicodeDecodeError. - Write .ignore through the journal-aware atomic writer, keeping its file mode, and record partial ownership afterward, so a failed write can no longer truncate existing user rules. Refs #5028 * fix(opencode): check .ignore parent writability on replace - Require a writable project root whenever .ignore must change, including replacing an existing writable file, so setup fails before any command files are written. Add a read-only-root regression test. - Compare post-setup .ignore modes with the mode chmod() actually set, so the mode-preservation test passes on Windows. - Match the atomic writer's ..ignore. temp prefix in the cleanup assertion. * fix(opencode): reject overridden .ignore exceptions and non-UTF-8 files - Evaluate the final .ignore in file order with pathspec's GitIgnoreSpec and fail setup when a later exclusion, such as .specify/** after the !.specify/ and !.specify/** rules, still hides a Spec Kit path. A later exception that restores visibility is accepted. Add ordering regression cases. - Validate UTF-8 during preflight, before command files are written, and reject other encodings with a conversion hint, since ripgrep stops at the first invalid byte. Replace the windows-1252 positive fixture with a rejection test and update the docstring. * fix(opencode): validate planned files and parent dirs in .ignore - Check the bundled templates and scripts, the constitution and .specify/.gitignore even before init creates them, so a later .ignore line such as .specify/templates/plan-template.md fails before any command files are written. Add a regression where that template does not exist yet. - Check each required path's parent directories in file order, since ripgrep prunes an excluded directory before it reaches a re-included child. Add regressions for .specify/memory followed by !.specify/memory/*.md and for a later rule that restores the parent. * opencode: match ripgrep line splitting and gitignore precedence Split .ignore content on LF and strip a trailing CR only, so a bare CR or a Unicode line separator inside a comment no longer starts a new rule. Evaluate the full GitIgnoreSpec with match_file() for the probe paths, keeping the ancestor-directory checks, so file-versus-directory rule precedence matches ripgrep. Add regressions for each case. * opencode: check .ignore before shared writes and only for installed script variants Add an IntegrationBase.preflight_setup() hook that install, switch and upgrade call before they write shared templates or scripts. OpenCode uses it to run the --configure-ignore-file checks, so a symlinked or hiding .ignore now fails a forced upgrade without touching shared files. The .ignore probe now covers only the script variants the selected --script installs (via the new shared_infra.script_variant_dirs()), plus files already under .specify/. * fix: keep extension local-config.yml hidden from OpenCode glob ripgrep ranks .ignore above .gitignore, so !.specify/** also exposed .specify/extensions/*/local-config.yml, which can hold credentials. Append an exclusion for it after the exceptions, and let the later-exclusion check accept exclusions of those files. * fix: harden opencode .ignore preflight and spell opencode consistently - skip ignore lines pathspec rejects with re.error, not just ValueError - read the root .ignore through FileHelper so a link swapped in after the checks is refused - re-read .ignore right before the atomic write and abort if it changed - reject .specify/.ignore and .specify/.rgignore rules that hide Spec Kit files, and document it - skip the chmod-based permission tests when running as root - write opencode in the Hidden Spec Kit Files docs, module comments and --configure-ignore-file help text * fix: protect local configs at every depth in opencode .ignore Exclude .specify/**/local-config.yml and .specify/**/*-config.local.yml so extension removal backups and *-config.local.yml overrides stay hidden, append them after the last negation line so a later ! rule cannot re-include them, and leave .specify/extensions/.backup/ out of the hidden-path probe set. * test: check opencode private-config rules against real ripgrep Run rg on the .ignore that --configure-ignore-file writes. A plain rg --files omits local-config.yml and *-config.local.yml, but a positive --glob that matches them (.specify/**/*, **/*.yml) overrides every ignore file and lists them. Scope the docs, module comment and option help to searches without a matching glob, and point credentials at SPECKIT_{EXTENSION}_* environment variables. * fix: keep opencode workflow run state out of plain searches Workflow run state under .specify/workflows/runs/ (state.json, inputs.json, log.jsonl) holds resolved inputs and captured command output. The !.specify/** exception surfaced it to ripgrep, and the hidden-path check probed existing run files, so a user line that excluded them was rejected. Append .specify/workflows/runs/ with the other private rules and skip run state in the hidden-path check, so a later exclusion of it is allowed. Cover both with captured-output fixtures, including a real ripgrep listing. * fix: check opencode .ignore preflight with ripgrep precedence The preflight only read ignore files directly inside .specify, so a root .rgignore excluding .specify/ (ripgrep ranks .rgignore above .ignore) or a deeper file such as .specify/memory/.ignore could still hide Spec Kit paths after setup succeeded. Evaluate each probe and its ancestors against the root .rgignore and every .ignore/.rgignore under .specify, nearest file first within each kind, and pin the precedence with native ripgrep tests. * fix: reject opencode re-inclusions that expose private .specify files The private exclusions are appended to the root .ignore, but a root .rgignore or a nearer .ignore under .specify outranks it in ripgrep, so a line such as !.specify/**/local-config.yml there listed local configs and workflow run state again after opt-in. Before writing, check each private path (existing ones plus representative examples) through the same ripgrep precedence and reject the file that re-includes it. Cover the .rgignore and nested .ignore cases against native ripgrep. * test: cover clearing opencode options with --integration-options="" Clearing the stored options leaves .ignore as it was through stale-file cleanup, and a later plain upgrade does not restore rules removed after opting out. --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
1 parent d409f59 commit a2d68de

4 files changed

Lines changed: 1167 additions & 2 deletions

File tree

‎docs/integrations/cli.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,7 @@ semantics, examples, and migration caveats live in the relevant agent guide:
420420
| GitHub Copilot | [Skills and commands layouts](copilot.md#commands-layout) |
421421
| IBM Bob | [Legacy commands and migration](bob.md#legacy-commands-and-migration) |
422422
| Kimi Code | [Legacy migration](kimi.md#legacy-migration) |
423+
| opencode | [Hidden Spec Kit files](opencode.md#hidden-spec-kit-files) |
423424

424425
Other agent-specific details are listed in the
425426
[integration directory](index.md).

‎docs/integrations/opencode.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,25 @@ Workflow steps use `opencode run`. Slash-prefixed prompts become
3737
`--command <name>` with the remaining text as the message; other prompts are
3838
passed as message text. The adapter forwards a configured model with `-m` and
3939
requests `--format json` for structured output.
40+
41+
## Hidden Spec Kit Files
42+
43+
opencode 1.18.31 and 1.19.3 on darwin arm64 discover files with a glob tool that calls ripgrep without `--hidden`. In a temporary Spec Kit tree, `opencode debug rg files --glob '.specify/**/*'` (the same `Ripgrep.glob` call the glob tool makes, with no model involved) returned no paths. `**/*.md` on that same command returned only a visible `README.md`, and missed `.specify/memory/constitution.md`, `.specify/templates/spec-template.md`, `.specify/templates/plan-template.md`, and `.specify/scripts/bash/check-prerequisites.sh`. After the project root `.ignore` contained:
44+
45+
```text
46+
!.specify/
47+
!.specify/**
48+
```
49+
50+
those patterns returned the constitution, both templates, and the script. A catch-all `**/*` already listed `.specify` files before the exceptions. `!.specify/**` alone still returned no `.specify/**/*` matches; the directory rule is what re-includes the hidden directory on this ripgrep path. Cloud-model fallback prompts and opencode 2.x were outside this check.
51+
52+
Opt in at install or upgrade:
53+
54+
```bash
55+
specify init my-project --integration opencode --integration-options="--configure-ignore-file"
56+
specify integration upgrade opencode --integration-options="--configure-ignore-file"
57+
```
58+
59+
The flag appends whichever of those two rules is not already an exact line, placing them at the end of the root `.ignore`, followed by `.specify/**/local-config.yml`, `.specify/**/*-config.local.yml` and `.specify/workflows/runs/` unless those exact lines already come after the last `!` line. ripgrep ranks `.ignore` above `.gitignore`, so these lines keep per-machine extension overrides, which can hold credentials, out of ripgrep searches that pass no matching glob, at any depth, including the copies extension removal keeps under `.specify/extensions/.backup/`. The `.specify/workflows/runs/` line does the same for workflow run state (`state.json`, `inputs.json`, `log.jsonl`), which holds resolved inputs and captured command output. They do not hide those files from opencode's glob tool: ripgrep lets a `--glob` pattern that matches a file override every ignore file, so with ripgrep 15.2.0, `rg --files --glob '.specify/**/*'` and `rg --files --glob '**/*.yml'` list `local-config.yml` and `*-config.local.yml` files under `.specify` once the exceptions are in place, while `rg --files` with no glob omits them. Before the exceptions, `**/*` already listed them. Keep credentials out of files under `.specify` (use `SPECKIT_{EXTENSION}_*` environment variables instead) if opencode should not see their paths. A later exclusion of a `local-config.yml` or `*-config.local.yml` file, of `.specify/extensions/.backup/`, or of anything under `.specify/workflows/runs/`, is allowed. A later line that excludes `.specify`, a parent directory such as `.specify/memory`, or a file under it (including a template or script init has not created yet, such as `.specify/templates/plan-template.md`) is rejected; move `!.specify/` and `!.specify/**` below it and rerun. A root `.rgignore`, or a `.ignore` or `.rgignore` anywhere under `.specify` (such as `.specify/memory/.ignore`), that excludes one of those paths is rejected the same way, because ripgrep ranks `.rgignore` above `.ignore` and a nearer ignore file above the root one; remove that line and rerun. A `!` line in any of those files that re-includes a private config or workflow run state (such as `!.specify/**/local-config.yml` in a root `.rgignore`, or `!local-config.yml` in `.specify/extensions/jira/.ignore`) is rejected too, since it would override the appended exclusions; remove that line and rerun. Bundled scripts are checked only for the `--script` variant being installed, plus any script already under `.specify/scripts`. `specify integration install`, `switch` and `upgrade` run this check before they write shared templates or scripts, so a rejected `.ignore` leaves the project unchanged, including with `--force`. A child exception does not uncover a file while its parent directory stays excluded. Bytes already in the file stay as a prefix, including UTF-8 non-ASCII text, CRLF, and a missing final newline. Non-UTF-8 content is rejected before command files are written; convert the file to UTF-8 and rerun, because ripgrep stops at the first invalid byte. Default installs leave `.ignore` untouched. The file is recorded with partial ownership, so `specify integration uninstall` and `specify integration uninstall --force` both leave it in place, exceptions included. Upgrades still compare its hash: adding a user rule blocks a plain `specify integration upgrade opencode` until that change is resolved or `--force` is used, and `--force` also overwrites edited command files. Deleting the two lines is not a lasting opt-out while the stored flag remains, because the next upgrade restores them. Clear the stored flag with `specify integration upgrade opencode --integration-options=""` before removing the lines.
60+
61+
`.ignore` is a shared ignore file. opencode's glob tool sees the rules because it searches with ripgrep, and other tools that read `.ignore` (including fd) can start showing `.specify` as well. `specify integration upgrade opencode` replays the stored flag. Passing `--integration-options` replaces the whole stored set (repeat `--configure-ignore-file` alongside any other flags, such as `--events false`); `--integration-options=""` clears it.

0 commit comments

Comments
 (0)