mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-29 07:42:58 +08:00
@fission-ai/openspec@1.12.0
15
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Clay Good
|
f3aa167d6e |
feat(tools): add Zed Agent support (#1659)
* feat(tools): add Zed Agent support * fix(tools): detect Zed projects |
||
|
Clay GoodandClaude Opus 4.8
|
9ae75c86ef |
fix(archive): don't write ANSI escape codes to a redirected (non-TTY) stdout (#1603)
* fix(archive): stop non-TTY confirm prompts from writing ANSI escapes to stdout `openspec archive` asks up to three yes/no questions through @inquirer's `confirm`, which renders by writing ANSI cursor-movement escape sequences — and emits them even when stdout is not a TTY. When archive runs with its output captured to a file or pipe (an agent's background task, CI), those escapes are noise, and in some non-TTY hosts the render loop never settles and repeats `ESC[NNG` moves until the disk fills (reporter hit 19.8 GB). Add `confirmPrompt` in interactive.ts: a real terminal (stdin AND stdout TTY) still gets @inquirer's rich prompt; every other case reads one plain line via node:readline with `terminal:false`, emitting no escapes. Parsing mirrors @inquirer/confirm exactly (prefix match on y/yes and n/no, else the default), and an unreadable stdin rejects with an ExitPromptError-shaped error so the existing #1479 "rerun with --yes" guidance is unchanged. archive's confirmOrBlock now calls confirmPrompt. Closes #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(interactive): cover Windows CRLF and drained-stdin paths; doc note Adds two regression tests surfaced by adversarial review of the #1526 fix: - Windows CRLF piped input (`y\r\n`) parses as a clean yes with no ANSI — the reporter's platform, previously untested (all inputs used `\n`). - A second prompt after stdin was already drained blocks with an ExitPromptError instead of hanging, exercising the readableEnded guard. Also documents in troubleshooting.md that a redirected/agent archive run that pipes an answer no longer writes terminal escape codes into the capture. Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(interactive): align non-interactive classification and handle readline errors Addresses two review findings on the #1526 confirm-prompt fix: - confirmPrompt drops to the plain reader whenever either stream is not a TTY, but isNonInteractivePromptError only checked stdin. A stdin-TTY / stdout-redirected run that hit EOF leaked the raw ExitPromptError instead of the #1479 "rerun with --yes" guidance. Classification now also counts a redirected stdout, matching how the prompt mode is chosen. (isInteractive, used broadly elsewhere, is left untouched.) - readYesNo never listened for the readline/input 'error' event, so a stdin error would hang the promise (and go unhandled). It now settles with the underlying fault, guarded so the promise resolves or rejects exactly once. Tests: TTY-stdin/redirected-stdout EOF is classified non-interactive; an erroring input stream rejects instead of hanging; the archive usable-terminal test now models a full terminal (both streams TTY). Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(archive): gate the change picker on a TTY and tidy the reader Follow-ups from a second review round: - selectChange (the no-argument change picker) called @inquirer's `select` unconditionally. `select` writes ANSI escapes to stdout even when redirected — the same #1526 mechanism the confirm prompts were fixed for — so `openspec archive > log.txt` with no change name still spewed cursor moves into the capture before blocking. Refuse before rendering when either stream is not a TTY, with the same "pass a change name / --yes" guidance the caught ExitPromptError already gives. A new test asserts the picker is never reached in a non-terminal run. - readYesNo now removes its input-stream 'error' listener on every settle path (it lives on the long-lived process.stdin) and closes the readline interface on error too, so nothing accumulates across archive's sequential prompts. - troubleshooting.md now notes the picker also stays clean. Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(changeset): add patch changeset for the archive non-TTY fix (#1526) User-facing patch note for the archive ANSI/disk-fill fix. Also drops an unnecessary optional-chain on the non-nullable readline handle in readYesNo (the listener is only attached after the interface exists). Refs #1526 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Clay GoodandClaude Opus 4.8
|
83be9d113e |
feat(validate): add --archived to lint task completion of archived changes (#1604)
* feat(validate): add --archived to lint task completion of archived changes `openspec validate --archived` scans every change under changes/archive/ and fails (exit 1) if any has unchecked tasks in tasks.md. This catches changes archived with unfinished work — which the normal validate flow never sees, since it only looks at active changes — and is meant for a pre-commit or CI hook. It is a standalone, opt-in scope: it returns before any existing bulk path, so no current `validate` invocation changes behavior, and it does not re-validate already-applied spec deltas. Reuses getTaskProgressForChange (the same counter status/list/archive use) so task counting never forks, and reads root.archiveDir so it is store-aware. Closes #205 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(validate): fail loudly on archive read errors and unreadable task files Address adversarial + CodeRabbit review of `validate --archived`: - listArchivedChangeIds now returns [] only for ENOENT (missing archive dir) and rethrows permission/I/O/ENOTDIR errors, so a real archive-read failure exits 1 instead of silently reading as "no archived changes". - Add getTaskProgressDetailForChange, which reports task files that exist but cannot be read; --archived turns those into an ERROR (naming the file) rather than silently counting them as zero tasks. The shared getTaskProgressForChange now wraps it and drops the detail, so status/list/archive totals are byte-identical. - Start the spinner after listing so a thrown listing error never leaves a spinner running. Adds regression tests (archive path is a file; archived tasks.md is unreadable) and unit tests for the new detail variant. Docs: align the --archived table verb and add a troubleshooting one-liner. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(validate): address CodeRabbit nits on archived-task tests - Build the unreadable-fixture path from separate path.join components instead of a hard-coded Unix-separator string. - Assert the reported unreadable path (canonicalized with realpathSync.native), not just the count, so a wrong path can't pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(validate): address round-3 review of --archived From three fresh adversarial reviews (scale/perf, flag/output-shape, filesystem/security): - perf: memoize schema→glob resolution across archived changes via a run-scoped SchemaGlobCache, so the same schema.yaml isn't re-parsed once per change (the archive is append-only and can hold thousands). Threaded as an optional arg; existing callers are unchanged. Loop stays sequential by design (per-change work is synchronous) — now documented. - output shape: issue `path` now follows validate's convention — 'tasks.md' for incomplete tasks, and the POSIX root-relative file path for an unreadable file (one issue per file) instead of the bare 'tasks'. - plain output: print `change/<id>` (matching the JSON `type` and bulk validation) instead of `archived/<id>`. - docs: correct the "Never throws" docstrings (glob resolution can throw on a malformed/unsafe schema; the caller guards it) and note the load-bearing projectRoot override for the archive path depth. Store-mode resolution confirmed correct by review. Tests updated + a memo regression test added. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Clay Good
|
59bfb27a76 |
fix(codex): install skills in canonical agents directory (#1511)
* fix(codex): install skills in canonical agents directory * fix(codex): preserve shared agents compatibility * fix(codex): harden shared skill migration * fix(codex): preserve customized legacy skills * fix(codex): reject malformed generated versions |
||
|
Clay Good
|
3d0701f871 |
fix(workflows): preserve nested spec paths (#1508)
* fix(workflows): preserve nested spec paths * fix(workflows): key conflicts by capability path * fix(workflows): preserve full paths in examples * fix(workflows): clarify nested path inputs * test(workflows): align parity hashes after rebase |
||
|
Clay GoodandClaude Opus 5
|
2b3d368539 |
fix(archive): tell the caller which flag to pass when archive can't ask its questions (#1483)
* fix(archive): name the flag when a prompt has no terminal to answer it An AI agent runs the CLI with stdin closed, so every confirmation `openspec archive` asks rejects with @inquirer's "User force closed the prompt with 0 null" - true, and useless: it names neither the question nor the flag that answers it, so agents abort and guess (#1479). Each confirmation now reports the same guidance JSON mode has always given for that decision point, with a pasteable command. The change picker got the opposite treatment: it swallowed the same failure, printed "No change selected. Aborting." and exited 0, reporting success for a run that archived nothing. It now exits 1 asking for a change name, matching `openspec show` and `openspec validate`. The detection is reactive - a prompt that already failed, at a stdin that is not a terminal - so piped answers, --yes, --json and Ctrl-C at a real terminal are untouched. Closes #1479 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(archive): carry the caller's flags into the suggested rerun, and honor every non-interactive signal Adversarial review of the first commit found four defects in it: - The suggested rerun dropped the flags the caller had passed. For `archive x --skip-specs` it suggested a bare `--yes` rerun, and following it merged deltas into the main specs - the exact thing --skip-specs was passed to prevent. - The change name went into that command unquoted, so a change named `my change` produced an unrunnable paste and one named `a;touch x` produced a paste that runs a second command. - The predicate keyed on stdin.isTTY alone, so a CI runner that allocates a pty still got the raw @inquirer failure - #1479 unfixed under the very signals `isInteractive()` already treats as authoritative. - A genuine Ctrl-C reaches a process whose stdin is a pipe, and that was reported as "this terminal is not interactive", telling a user who deliberately quit to rerun with --yes. The signal is now `!isInteractive()` with SIGINT excluded, so the terminal proves capability and the signal proves intent. Messages say what happened ("no answer could be read from stdin") rather than asserting a property of the terminal, which was false under MinTTY. Mutation testing found four more gaps in the tests: an unconditional `throw blocked()`, a stripped `withStoreFlag`, and either half of the predicate's `||` all left the suite green. Each now has a test, along with the flag carry-forward, the quoting, the pty-CI case, and the two prompts that had no end-to-end coverage. docs/cli.md documents the behavior without a terminal. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(archive): close two gaps CodeRabbit found in the new guards The template guard required a space after `openspec archive`, so a regression to a bare `openspec archive` line - which blocks agents exactly as #1479 describes - would have passed it. Verified by mutation: the widened pattern fails on that edit. Expected filesystem paths in the new e2e assertions are built from path segments, per the repo's testing guideline. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(archive): make the suggested rerun runnable for dashed names, stores, and Windows shells A second adversarial pass, scoped to the previous two commits, found three defects in the fix itself: - A change named `--force` was emitted bare, and commander reads it as an option however it is quoted, so the suggested command failed with `unknown option`. Such changes do archive, so the case is reachable: the name now goes behind a `--`, with the store flag kept in front of it where it is still read as an option. - The change-name-required path was the one blocked site left hard-coded, so `archive --skip-specs` with nothing to answer the picker suggested a rerun without `--skip-specs` - the same merge the previous commit set out to prevent. - Quoting was POSIX-only: cmd.exe does not treat `'` as quoting at all, and PowerShell escapes an embedded quote by doubling it, so the emitted command was wrong on Windows. Names now use double quotes, which bash, zsh, PowerShell and cmd.exe all read the same way, and a name containing something with no portable spelling (a quote, backslash, `$`, backtick, newline) names the placeholder rather than emitting a command that could expand. Two tests were pinning less than they claimed. The real-terminal cancellation test had become a duplicate of the piped one, since the SIGINT check short-circuits before the terminal is consulted; it now covers the terminal leg with a non-SIGINT failure, which is the leg nothing else guarded. The template guard iterated two identical strings and could not see an indented invocation; it now sweeps every rendered skill and command template, and both mutations were confirmed to fail it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(changeset): name the quoting form the fix actually emits Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(archive): stop quoting change names cmd.exe would expand anyway `%USERNAME%` is a legal change directory name, and cmd.exe expands it inside double quotes, so the suggested rerun `openspec archive "%USERNAME%" --yes` targets a different change than the one that was blocked. `!` has the same problem under cmd.exe's delayed expansion and bash's interactive history expansion. Both characters now fall back to the `<change-name>` placeholder, the same path a `$`/backtick name already took: a rerun the reader has to fill in beats one that silently archives something else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(archive): stop a change directory from forging its own Fix line Four adversarial reviews of this branch turned up one real defect and two guards that were not actually pinned. The human-mode message for an unanswerable incomplete-task confirmation interpolated the change name raw, and archive resolves a change by stat-ing its directory, so the name is attacker-influenceable. A newline in it added a second, forged `Fix:` line - and because `quoteChangeName` degrades the real fix to `<change-name>` for exactly those names, the forged line was the only pasteable command on screen. Control characters are now collapsed. Also pinned two mutations that passed the whole suite green: dropping `withStoreFlag` from only the dash-leading branch of `rerunCommand`, and dropping the `validate === false` leg of the `--no-validate` test - the one leg Commander actually produces. The --yes parity guard only saw invocations that opened a line, so a `$ ` prompt, a list marker or `openspec --store x archive` slipped past it. It now matches those and names the onboarding floor instead of trusting `total > 0`. Docs and spec catch up: a troubleshooting entry under the message people actually search for, and cli-archive scenarios for the unanswerable-prompt paths, including that Ctrl-C stays a cancellation. * test(archive): tokenise the --yes guard instead of pattern-matching it Accepting a global flag between `openspec` and `archive` needed nested quantifiers, and CodeQL was right to call that a ReDoS shape (js/redos, high) even in a test over our own templates. Splitting the line into tokens decides the same question in linear time - a 20k-flag line now costs ~2ms - and reads more plainly than the pattern did. Same classifications as before, plus it correctly ignores `openspec list archive`, where `archive` is an argument rather than the subcommand. * test(archive): skip the forged-Fix-line case on Windows Windows rejects control characters in a filename, so the change directory the test needs cannot be created there - which is also why the hole it covers is POSIX-only. Matches the existing `it.skipIf(process.platform === 'win32')` idiom in the suite. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Clay GoodandClaude Opus 5
|
84ebc57cb3 |
fix(validate): report scenarios a MODIFIED requirement would drop (#1482)
* fix(validate): report scenarios a MODIFIED requirement would drop `openspec validate <change>` accepted a MODIFIED requirement that omits a scenario the main spec still has, even with --strict. Archive refuses to apply that block (a MODIFIED replaces the whole requirement, so the omitted scenario would be lost), so the change could pass validation, be implemented and reviewed, and fail only days later at archive time (#1477). Validate now runs the same non-mutating check against the main specs and reports each omitted scenario, naming the delta file. The comparison itself moved to the parser module so archive and validate share one implementation and cannot drift. The check is silent when the main spec file or the requirement header is absent — a MODIFIED written against a sister change still in flight is a separate condition archive gates — so validate can only report what archive already refuses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(validate): tighten the scenario-loss check after review Keep the moved scenario parser module-private, derive change validate's main specs root from the changes root it already resolved, replace the rename re-keying with a lookup fallback, and say at archive's call site why it does not opt in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(validate): follow rename chains when checking for dropped scenarios A delta that renames A to B and then B to C leaves C holding A's block at archive time. Walk the rename map instead of looking it up once, so the chained case reports the same loss archive refuses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(validate): close the gaps five adversarial reviews found Code: - An unreadable main spec was swallowed, so a change archive aborts on validated clean. Only ENOENT/ENOTDIR mean "no main spec" now; anything else is reported. - A MODIFIED naming a header the same delta renames away no longer names scenarios from the block it would not land on. That contradiction is already reported on its own, and the scenario list pointed at the wrong requirement. Guidance: the sync-specs skill told agents a MODIFIED block may carry only the changed scenario, and its format reference showed one. Both validate and archive reject that shape, so the template, the generated skill, and the golden hashes are updated to match the schema's own rule. Tests: the CLI wiring had no coverage at all — removing the argument that turns the check on broke nothing. Adds end-to-end coverage of every entry point and exit code, plus the non-strict default, a fenced scenario in the delta, an unreadable main spec, the rename-away case, and a rename cycle. Loose assertions now pin the scenario-loss issue itself. Docs: a troubleshooting entry for the new message, and the changeset says that a stale change will newly fail. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(validate): never turn a transient read error into a verdict The unreadable-main-spec report added in the last commit fired for any errno that was not ENOENT/ENOTDIR, which includes resource errors like EMFILE that say nothing about the file. `validate --all` reads six changes at once, so a busy process could have failed a change that is fine. Reported now only for the codes that mean the file itself is unusable and will be just as unusable when archive reads it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(troubleshooting): label the example fence (MD040) Every other fence in the file names its language. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
solanabandClay Good
|
1aa0f2abfc |
feat(init): add shared agents skills target (#1303)
Co-authored-by: Clay Good <hi@claygood.com> |
||
|
Clay GoodandClaude Opus 5
|
9a937cb9b3 |
fix(adapters): reference slash commands by the names each tool registers (#1471)
* fix(adapters): reference slash commands by the names each tool registers Generated command bodies, skills and the post-setup hints all advertised /opsx:<id>, but only 7 of 28 adapter-backed tools register that name. The other 21 write .../opsx-<id>.md, where the filename is the command, so their users were told to type a command their palette never had. Codex, which registers no slash commands at all, was told to type them too. The invocation style is now derived from the command file each adapter writes rather than a hand-maintained tool list, so every tool-specific surface - command bodies, SKILL.md cross-references, and the init, update and migration hints - names the command that tool answers to. Closes #1307 Closes #727 Closes #1379 Closes #1110 Refs #1129 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: name the per-tool invocation exceptions in the table itself Review follow-up: the "every other adapter-backed tool" row swept Amazon Q, Cline and Kilo Code into the plain /opsx-<id> form. Each is now its own row with the wrapper it actually uses, and the command-references tests pass the now-required invocation style explicitly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: make every invocation reference match what OpenSpec generates Review follow-up across the docs, the living specs and two hardcoded strings: - supported-tools: the How To Invoke section no longer splits the "How It Works" profile paragraph from its heading, keys rows on the file shape rather than a `.md` extension the Gemini/Continue/Copilot/Kiro adapters do not use, and drops the Cline/Kilo Code/Amazon Q rows. Kilo Code's docs say the current format drops the `.md` suffix, and the Cline and Amazon Q forms could not be confirmed - a wrong exception row is worse than none, so the caveat now describes the shape without asserting a spelling OpenSpec does not generate. - commands, how-commands-work: the two partial nine-row tables that drifted into #727/#1307 now key on the same file shape and defer to the authoritative table; both note that skill rows carry skill names, which are not command ids. - faq, troubleshooting, installation, README: stop telling skills-only users they have no slash command, stop offering "/opsx autocompletes" as a health check on tools where it never will, and name Hermes with the other adapterless tools. - specs: cli-init no longer claims every tool gets `commands/opsx/`, cli-update no longer frames the hyphen rewrite as OpenCode-specific, and command-generation describes the classifier the code implements. - the legacy-cleanup summary and the pre-selection welcome banner no longer print `/opsx:*` at users whose tool never registers it. - adds the missing changeset; it supersedes the Codex sentence in the pending adapterless-skill-references note. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test: cover the update and migration paths a mutation run found unguarded Mutation testing showed five ways to delete parts of this change without failing a single test. All five now fail: - `openspec update` had no flat-tool coverage at all, so the headline upgrade path - an existing Cursor project still carrying `/opsx:` references - was asserted nowhere. Two tests now cover it: one heals a project seeded with stale references, one runs claude+qwen together and pins each to its own form. - the legacy-upgrade getting-started menu is covered for a newly configured Cursor project, so passing the wrong invocation style there is caught. - migration.ts had no flat-tool case: reverting it to a hard-coded `/opsx:propose` passed the whole suite. A qwen-only migration and a claude+qwen disagreement now pin the message. - the unknown-command-id guard in `transformToHyphenCommands` was new behaviour with no test; removing it was invisible. Also tightened assertions the same run showed were weak: the `resolveCommandInvocationStyle` loop compared the implementation against itself, the per-id consistency check asserted only that a style was uniform rather than which one, and the init test's `/opsx-` assertion was satisfied by frontmatter rather than a body reference. The adapter tests that moved to `generateCommand` are renamed after their real subject, and a new case pins the contract those five adapters now rely on: they stay pure formatters and do not rewrite the body themselves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test: assert the rewritten form, not just the absence of the old one Review follow-up: the refreshed-skill checks were negative-only, so a regression that dropped every command reference rather than rewriting it would have passed. Each now pins the invocation its tool registers, the stale fixture asserts it really seeded a colon reference into the skill, and the claude+qwen case pins Claude's namespaced skill alongside Qwen's. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(adapters): spell Amazon Q's prompts with @, not as slash commands The invocation model derived the whole command name from the file an adapter writes, which covers `/opsx:<id>` versus `/opsx-<id>` but not the wrapper around it. Amazon Q loads `.amazonq/prompts/opsx-<id>.md` into its prompt library, invoked as `@opsx-propose`; it registers no slash command, so its command bodies, skills, and the "Getting started" hint all named something the tool never answers to. The name still comes from the file path. The prefix is now adapter metadata (`invocationPrefix`, defaulting to `/`), so it cannot be guessed wrong and a new adapter has to declare it deliberately — invocation.test.ts fails if one appears undeclared. Also fixes three copy issues: - The FAQ told users to run `openspec update` when command files are missing; update only refreshes files for already-configured tools, so a tool that was never initialized needs `openspec init`. - The installation prompt omitted Kimi Code's `/skill:openspec-propose`. - The welcome screen promised "opsx slash commands" before tool selection, which is wrong for skills-only tools that correctly get no command files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(init): stop naming slash commands where none are registered Two spots still promised a slash command to users who get none: - The welcome screen's quick start shows canonical names (/opsx:propose), but renders one prompt before tools are picked — an Amazon Q user types @opsx-propose and a Codex user $openspec-propose. It now says the spelling varies by tool, so the canonical form stops reading as the literal thing to type. "Getting started" still prints the real form. - The post-setup restart line said "slash commands to take effect" whenever commands were generated. Amazon Q's generated files are prompt library entries, not slash commands, so it now says "the new commands". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: name Amazon Q's @ form where the other exceptions are listed The README's one-line exception list and the troubleshooting checklist both enumerated the per-tool spellings and skipped Amazon Q. The troubleshooting entry was actively misleading: it explains that /opsx never autocompletes for tools without command files, and Amazon Q is not one of those — it has command files, they just land in the prompt library. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(migration): cover the legacy-upgrade hint for amazon-q The migration hint resolves its propose reference through the same transformer as init and update, but no case exercised a non-slash prefix there. The second test is the one that matters: @opsx-propose and /opsx-propose are both "flat", so a style-only model would treat Amazon Q and Qwen as agreeing and advertise one form to both. Reverting the prefix to a constant '/' fails 5 tests, so neither assertion is a tautology. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Clay GoodandClaude Opus 5
|
6295515d4d |
feat(update): offer to upgrade a stale CLI during openspec update (#1470)
* fix(update): flag a stale global CLI during openspec update Instruction files are generated by the installed CLI, so running `openspec update` against an outdated global install printed "All 1 tool(s) up to date (v1.6.0)" while the workflows newer releases ship were never written. Users read that as success and reported the missing workflows as bugs. `openspec update` now checks the npm registry alongside the update and, when the installed CLI is behind, prints the upgrade command instead of leaving the up-to-date line to speak for itself. The check never gets in the way: it runs concurrently with the update, times out after 1.5s, caches the answer for 24h, returns null on any failure, and is skipped in CI, under tests, and whenever OPENSPEC_NO_UPDATE_CHECK is set. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): name the right install in the stale-CLI hint The hint assumed a global install. A project-local dependency is now pointed at that dependency instead of `npm install -g`, and every hint prints the directory the running CLI was loaded from, so anyone who upgraded but still runs an old pnpm/volta/npx shim can see which copy answered. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): drop the temp-file cache and fix prerelease ordering CodeQL flagged the version-check cache twice: a predictable path in the shared OS temp dir (js/insecure-temporary-file, high) and registry data written to that file (js/http-to-file-access, medium). `openspec update` is a rare, human-run command, so the cache bought little — removing it resolves both alerts outright and deletes the code that needed them. Also from review: CI=1 now opts out alongside CI=true, and prerelease tags compare per SemVer (dot-separated identifiers, numeric compared numerically) so 1.7.0-beta.10 outranks 1.7.0-beta.2. Build metadata is ignored per spec. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): make the version check actually reach the registry Adversarial review found the check could never fire: the request sent `accept: application/vnd.npm.install-v1+json`, which npm serves only on the full packument — on `/<pkg>/latest` it answers 406, so every real run returned null. Every test mocked fetch, so nothing caught it. The header is gone, and a new suite exercises the real fetch path against a local HTTP server, including an assertion that we never send that Accept type. Also from review: - Validate the published version against a strict SemVer pattern before printing it. It lands in the terminal beside an install command, so an unvalidated string could smuggle ANSI cursor controls and repaint the surrounding lines. - Honor DO_NOT_TRACK=1 and OPENSPEC_TELEMETRY=0, the opt-outs telemetry already respects, and update SECURITY.md, which promised telemetry was the only network egress. - Anchor project-local detection on the path being updated and its ancestors instead of process.cwd(), so `openspec update <path>` and workspace sub-packages with a hoisted root node_modules are no longer told to install globally. It can no longer throw when the working directory has been deleted. - Send npx/dlx users `npx @fission-ai/openspec@latest update` rather than advice that would create the global install they avoided. - Query npm_config_registry when set, so private mirrors get an answer their own install command can deliver. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(update): make version-check fixtures portable on Windows The new fixtures mixed unresolved POSIX literals with path.join output. On Windows path.resolve adds a drive letter and path.join does not, so the prefix match could never succeed and two assertions failed there. Fixtures now derive from resolved roots. Real installs were unaffected — both sides come from resolved absolute paths — but case and drive-letter casing can still differ between require.resolve and path.resolve on Windows, so the comparison is now case-insensitive on win32. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): stop a blackholed registry from holding the CLI open Verification found the 1.5s timeout did not bound the command. Aborting a fetch still completing its TCP handshake — a firewall dropping packets, a captive portal — leaves the connect handle ref'd, so `openspec update` sat for ~10s after printing everything. Measured against an unroutable address: resolved at 1523ms, process exited at 10558ms. The request now uses node:http(s), whose socket the timeout can actually destroy: same probe resolves at 1547ms and exits at 1550ms. Because the client is no longer fetch, the mocked tests would have gone inert and silently reached the real registry. The whole suite now drives the real code path against a local server, which is also the only way to prove an opt-out sent nothing. Added a child-process guard for the teardown itself (no in-process assertion can see it), a case for a non-JSON body — the captive-portal login page — and order-independence fixes: the mock leak between describes made the 406 regression guard the first casualty under --sequence.shuffle. Also: bound the version pattern and the response body so neither can be absurdly long, and narrow the ephemeral-runner match so a user directory named "dlx" is no longer mistaken for a pnpm cache. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(update): offer to run the upgrade instead of only printing it Being told to run a command, then run the update again, is two steps the CLI can take for you. `openspec update` now asks: A newer OpenSpec CLI is available (v1.6.0 -> v1.7.0). Running from: /usr/local/lib/node_modules/@fission-ai/openspec ? Upgrade to v1.7.0 now? (Y/n) Yes runs `npm install -g` with stdio inherited — so any auth or sudo prompt reaches the user directly — then re-runs the update with the new CLI, because this process still holds the old templates and cannot write the new workflows itself. No prints the command and updates with the CLI you have. It asks rather than acting: a CLI that mutates a global install without consent is the wrong default. Guards: - Interactive terminals only, via the repo's isInteractive() (no TTY, or CI set, means the note prints exactly as before). - Global npm installs only. A project dependency belongs to that project's package manager, and an npx/dlx cache has nothing to upgrade; both get the command instead. - The re-run carries OPENSPEC_NO_UPDATE_CHECK=1, so a PATH that still resolves to the old binary cannot loop. - A failed upgrade, a missing openspec on PATH, and Ctrl-C at the prompt each fall back to the printed command rather than an error. The check now runs before the update rather than alongside it, so an accepted upgrade regenerates files with the new templates in one pass. Verified end to end against a stubbed npm and openspec on PATH, both answers, plus the unchanged non-interactive path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): offer the upgrade only where npm install -g would help Review found `canSelfUpgrade` treated "not a project dependency and not an npx cache" as proof of a global npm install. It is not: a pnpm, bun, yarn or volta global, and a plain git clone, all qualified. Reproduced by running the CLI from this repo — it offered to npm install -g over the checkout, which would have shadowed it with a second copy. The offer now requires npm to own the install, derived from the running node's global root (and APPDATA/npm_config_prefix) rather than by shelling out to `npm prefix -g`. Everything else gets the command that matches how it was installed — `pnpm add -g`, `bun add -g`, `yarn global add`, `volta install` — a project dependency is pointed at its own package manager with no npm command at all, and a source checkout gets no note, since its version is whatever the branch says. Docs corrected where they had drifted from the code: - The check runs before the update, not alongside it; it can delay the update by up to 1.5s. docs/cli.md and the changeset said otherwise. - npm_config_registry is only honored when npm exports it; an .npmrc setting alone is invisible to us. Docs and JSDoc claimed more. - SECURITY.md gains an "Installing software" row: running a package manager on the user's behalf is the most security-relevant behavior here and the table did not mention it. The "Running other programs" row now covers the re-run's path argument and cross-spawn's Windows shim escaping, and the network row lists every opt-out precisely. - troubleshooting.md's "Commands don't show up" — the exact symptom this PR exists to fix — now explains that instruction files come from the installed CLI, and installation.md's Updating section links onward. - The env-var table notes the CI and NODE_ENV skips, and that npm_config_registry must be an http(s) URL. - "the new workflows land in the same command" no longer overpromises: when the upgraded openspec is not on PATH, the CLI now says the files were not regenerated instead of printing a dim aside. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): make the upgrade offer tell the truth about what happened Adversarial review found the flow could claim success it had not earned, and could strand a non-interactive caller. All verified by running the CLI, all fixed: - `npm install -g` exits 0 even when it installs nothing, so "✓ Upgraded to vX" was an assertion, not a fact. The version is now read back from the installed binary; when another install earlier on PATH still answers with the old one — the exact silent staleness this feature exists to fix — it says so instead of claiming the upgrade landed. - The prompt hung forever under `openspec update > log.txt`: the question went to the file while the user watched a blank terminal. The offer now requires stdout to be a terminal too. - Ctrl-C at the prompt read as "no thanks" and carried on into the next prompt. It now stops the command with 130. - `--force` never reached the re-run, so `openspec update --force` could regenerate nothing and exit 0. Flags are forwarded, with `--` before the path so a flag-shaped path stays a path. - A signal-killed re-run, and a re-run with no CLI to hand off to, both reported 0. Both now report failure. - `process.exit()` skipped commander's postAction hook, killing the telemetry flush mid-request. The action sets process.exitCode and returns instead. - The check read only npm_config_registry, which npm exports only under `npm run` — so an enterprise user with a mirror in .npmrc got an unannounced call to public npm. It now reads .npmrc too. - Two different CI predicates: `CI=yes` suppressed the prompt but not the request. One predicate now, and it treats any value except an explicit off-value as CI. - A project-local install was offered a global one when updating a different directory; both anchors are checked now. Tests: the re-run had no coverage at all and now has four cases. Mutation testing over nine mutations (406 header, DO_NOT_TRACK, version validation, prerelease ordering, canSelfUpgrade, the anti-loop env guard, the cwd-vs-target anchor, the timeout) — one survived, the anti-loop guard, so it has a test now and the mutation dies. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(update): compare re-run arguments as tokens, not as a raw line cmd.exe echoes `%*` with every argument quoted, so the Windows job saw `"update" "--force" "--" "--weird-path"` and the substring assertion for `-- --weird-path` failed. The forwarding itself was correct on both platforms; the assertion now splits and unquotes before checking that the separator immediately precedes the path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): read only the user's .npmrc for the registry CodeQL flagged file data reaching an outbound request, and it has a point: the project `.npmrc` travels with the repository, so honoring it let a cloned repo choose where the version check sends its request. Only `~/.npmrc` is read now — which is where a mirror is configured anyway, since `npm config set registry` writes there — and a test pins that a project `.npmrc` cannot redirect the request. Docs and changeset say so explicitly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): detect the install from its own layout, not from node's path Adversarial review found the offer never appeared on Homebrew — a mainstream macOS install — and I reproduced it on this machine: npm root -g: /opt/homebrew/lib/node_modules derived roots: /opt/homebrew/Cellar/node/25.8.1_1/lib/node_modules process.execPath is realpath'd through Homebrew's symlink into the Cellar, so a root derived from the node binary never matches the prefix npm installs into. The same mismatch hits Debian-style layouts. The install's own shape is now the primary signal: <prefix>/lib/node_modules/<pkg> (POSIX) or <prefix>/node_modules/<pkg> (Windows), confirmed by the bin directory npm would have written the shim into. The node-derived roots stay as a fast path. Also from the same review, each reproduced first: - volta nests a whole node install, so its packages sit in exactly npm's layout: we called it npm-owned, ran `npm install -g`, and on failure told the user to run volta. Ownership is now decided before location. - upgradedBinPath returned the first prefix that merely had an openspec in it, preferring a stale one over the prefix npm just wrote to. It now derives from the running install first. - readCliVersion took the first version-shaped token anywhere in stdout, so a wrapper banner ("Node.js v25.8.1 | OpenSpec") was read as the answer — turning a real upgrade into a false "still reports vX", or worse, claiming success for a version nobody installed. It now takes the line that is only a version. - The probe child could outlive its 5s timeout indefinitely: SIGTERM with no escalation and no unref, so a signal-trapping wrapper held the CLI open for as long as it ran. - "Another install earlier on your PATH is answering first" was a misdiagnosis whenever we had asked a known binary directly. - A `registry=${VAR}` or `@scope:registry=` line in .npmrc — both npm's documented syntax, the latter being how a scoped package is normally routed to a mirror — silently fell back to the public registry. - A 3xx from the registry disabled the check permanently and silently. Redirects are followed, bounded, under one timeout budget. - An incidental directory named "pnpm" or "yarn" was read as a global install of one, printing the wrong upgrade command. Plus the earlier docs-audit round: the npx branch no longer tells users to run an update they were just handed, the check no longer fires for a source checkout whose answer is discarded, the offer gate moved into a tested pure function, and the declined command now prints below the update output instead of scrolling away above it. Docs: install-flavor table, CI off-values, empty-value opt-out, the "no cache" fact in SECURITY.md, and a changeset trimmed to a summary that points at the CLI reference. The changeset is now `minor` — this adds a prompt, an env var, an outbound request, and the ability to install software; that is not a patch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(update): stop reading .npmrc for the registry CodeQL flagged file data reaching an outbound request (js/file-access-to-http), and it is right that a file choosing where a request goes is a flow worth avoiding. The convenience did not earn it: reading ~/.npmrc needed three follow-up fixes in one review round (project-vs-user precedence, ${VAR} expansion, scoped registry keys), and none of it is necessary — anyone on a private mirror can export npm_config_registry, which is still honored, or turn the check off. Removes the .npmrc read and its two helpers; a test pins that a registry= line in a .npmrc cannot steer the request. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
Clay GoodandClaude Opus 5
|
9a61f3f30d |
docs(installation): add an AI-assistant setup prompt (#1466)
* docs(installation): add an AI-assistant setup prompt
Adds a provider-neutral "Install with your AI assistant" section to
docs/installation.md with one copyable prompt that detects the runtime and
package manager, installs the CLI, runs `openspec init --tools <id>`, and
verifies the result. Surfaced from the README Quick Start and the docs map.
The manual package-manager instructions stay the source of truth.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(installation): harden the AI-assistant prompt and link it from the install paths
Adversarial review found the first draft's verify step false-failing on healthy
installs and its guardrails unenforceable. The prompt now reports what init
actually printed instead of asserting config.yaml and command files (config.yml
is equally valid; six tools and delivery=skills correctly generate zero
commands), warns that --tools auto-cleans legacy files including opsx-*.md
prompts under $HOME, picks the package manager by what's on PATH rather than by
lockfile, scopes yarn to 1.x, and stops cleanly on EACCES, a missing pnpm global
bin dir, or a version-manager shim.
Also links the flow from getting-started, the docs map, troubleshooting, and the
website CTA; notes Berry dropped `yarn global`; replaces `npm bin -g` (removed in
npm 9) with `npm prefix -g`.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(installation): close the gaps two trial runs found in the setup prompt
Two assistants (different models) ran the prompt end to end in sandboxes, one
on Cursor and one on Codex with deliberately messy legacy files. Both finished
with a working, verified setup. Their findings:
- Cursor's commands are `/opsx-propose`, not `/opsx:propose`. The prompt named
the colon form and init's summary agrees with it, so the assistant would have
handed back a command the tool doesn't match. It now takes the spelling from
the files init created.
- "List whatever you find and wait for my go-ahead" was undefined when the list
is empty, i.e. on every fresh project. It now says to carry on.
- `openspec --version` succeeding doesn't prove it's the copy just installed;
an older one earlier on PATH shadows it. Step 3 now compares the two.
- The request asked for confirmation before privileged/global changes; the
prompt only stopped reactively on failure. It now shows the global install
command and waits.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: correct the core profile to six workflows and the tool count to 30+
Two long-standing inaccuracies, found while verifying the install docs.
`CORE_WORKFLOWS` (src/core/profiles.ts:14) is six — propose, explore, apply,
update, sync, archive — and a real `openspec init` generates six skills and six
commands. Eleven pages listed five, omitting `update`; migration-guide listed
four and filed `sync` under the expanded set. supported-tools also dropped
`update` from the full workflow-ID list. docs/commands.md was already right and
is untouched, as are flow diagrams that show a typical path rather than a
profile roster.
The tool count was written as both "25+" and "30+" against 34 supported tools.
Now consistently "30+".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: address CodeRabbit review on the AI-assisted install flow
- Windows puts global npm binaries directly in the prefix directory, not in a
`bin/` subdirectory; the troubleshooting fix I added said otherwise.
- Tell the assistant to stop rather than improvise when none of npm/pnpm/yarn/bun
is available, and point Nix users at the Nix section.
- Drop the blockquote on the getting-started pointer so it isn't a second `>`
block adjacent to the explore callout (markdownlint MD028).
Two other comments were already fixed in
|
||
|
showmsandshowms
|
79f1dac668 |
feat(codex): make Codex skills-only and retire managed custom prompts (#1283)
* feat: make Codex skills-only * test: cover codex legacy prompt paths * fix: address review feedback for Codex skills-only migration * fix(codex): revalidate managed global prompt paths before cleanup * resolve conflicts with upstream/main * fix(codex): refine legacy prompt migration --------- Co-authored-by: showms <showms@users.noreply.github.com> |
||
|
|
ac656c983f |
feat: add CodeArts Agent skills support (#1266)
* feat/add codeartsagent to tool list * feat/add codeartsagent to tool list * test: clarify CodeArts init log assertions * docs(cli): union hermes and zcode into the supported tool-ID list Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Clay Good <hi@claygood.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
|
3f0ca3f6ce |
feat: add Trae command adapter (#1090)
* feat(tools): add Trae command adapter - Added Trae command adapter for generating `.trae/commands/opsx-<id>.md` files - Complete unit tests (9 test cases) and integration tests - Updated documentation and .gitignore - Fixed YAML escaping for carriage returns (\r) Co-Authored-By: Claude Code <noreply@anthropic.com> * fix: handle empty string in YAML escaping - Add explicit check for empty string in escapeYamlValue - Return quoted empty string '""' instead of unquoted empty scalar - Update test to verify empty string is properly quoted Co-Authored-By: Claude Code <noreply@anthropic.com> * fix: address PR review feedback for Trae adapter - Update docs/commands.md Trae entry to reflect generated opsx-* commands - Export traeAdapter from adapters/index.ts Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: align Trae command adapter docs --------- Co-authored-by: jjxyxsjr <jjxyxsjr@users.noreply.github.com> Co-authored-by: Claude Code <noreply@anthropic.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com> |
||
|
|
bb1f18c483 |
docs: comprehensive overhaul — discoverability, explore-first, and closing recurring doc-request issues (#1237)
* docs: comprehensive documentation overhaul (home, mental model, command location, FAQ, glossary, troubleshooting, recipes) Addresses #1228 (docs are fragmented and hard to discover). Additive, docs-only. The single sharpest gap from the issue thread was that nobody explains where slash commands run, hence the new "How Commands Work" page. New docs: - docs/README.md documentation home / index that maps every doc - docs/how-commands-work.md where /opsx:* (chat) vs openspec (terminal) run; "interactive mode" answered - docs/overview.md core concepts at a glance, one page - docs/faq.md consolidated common questions - docs/glossary.md every term in one place - docs/troubleshooting.md concrete fixes for concrete failures - docs/examples.md real changes start to finish (recipes) Small additive edits: - docs/getting-started.md "where do I type this?" callout + first-five-minutes + richer Next Steps - README.md Docs list points at the new home and key new pages Voice: warm, plain, bottom-line-up-front; no em-dashes in prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: make /opsx:explore front and center, plus general polish Per maintainer feedback (Tabish): "the docs in general need some work, alongside making the explore option a lot more front and center." explore ships in the default core profile but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore -> propose -> apply -> archive and gives explore real prominence. - docs/explore.md (new): dedicated "Explore First" guide. When to use it, what it does/doesn't, a full transcript, handoff to propose, tradeoffs. - getting-started.md: explore added to the flow and first-five-minutes, with a featured callout and Next Steps entry. - overview.md: explore featured in the loop and next-links. - docs/README.md: explore in the opening, pick-your-path, 30-second version, and the doc map. - how-commands-work.md: explore leads the command list with a "good rhythm" note and an optional step in the clean-first-run example. - workflows.md: new first-class "Start by exploring" pattern in the default section (was buried under expanded mode); quick-reference row strengthened. - commands.md / faq.md / glossary.md: explore featured as the place to start. - examples.md: top callout pointing at the explore recipe. - README.md: explore opens the "See it in action" demo and Quick Start, and is added to the Docs list. Docs-only and additive. No em-dashes in prose; links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: close recurring gaps (existing projects, editing changes, uninstall, context limits) + sync tool list Sweep of open issues and discussions surfaced several questions good docs should answer but didn't. This adds the missing guides and fixes a stale list. New guides: - docs/existing-projects.md: adopting OpenSpec on a large brownfield codebase without documenting everything up front (addresses #510, #1100, #176). Delta-first framing, first-change walkthrough, onboard, importing existing requirements docs, domain organization, monorepo/workspace pointers. - docs/editing-changes.md: how to edit any artifact, update a proposal/spec after starting, go back after implementing, and reconcile manual code edits (addresses #684, #976, #355, #1188, #169, #1206). Enhancements: - installation.md: Updating + Uninstalling sections (addresses #308). - faq.md: new entries for existing codebases, editing artifacts, going back, reconciling manual edits, context limits / long sessions, and uninstalling (addresses #257 among others). - cli.md: --tools list now includes `vibe` and matches AI_TOOLS in src/core/config.ts, with a note pointing at the source (fixes #1213). - Wired the new guides into the docs home, getting-started, and the README. Docs-only and additive. No em-dashes in prose; links and section anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: reconcile coordinate-across-repos docs with the stores model The merge with main pulled in the stores rename (#1190), which retired the workspaces/initiatives/context-store vocabulary and deleted docs/workspaces-beta/. This updates the three docs still describing the old model so they match the new stores model, fixing the vocabulary-sweep test and dead links: - glossary.md: Workspace/Link/Context store/Initiative -> Store/Reference/ Working context/Workset; link to stores-beta/user-guide.md - README.md: replace deleted workspaces-beta/* links with the Stores User Guide and Agent Contract - existing-projects.md: reframe the multi-repo section as stores; drop the dead concepts.md#coordination-workspaces anchor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com> |