An argument's allowed-values refusals live in one module, read by the API, the feed and MCP #5686

The seven refusal sentences for an argument outside its allowed values now live in one new module, src/http/arg_words.ts. No existing module owned this, so I made a new one. The API, the feed and MCP read the sentences from it.

What moved

• src/http/arg_words.ts exports one constant per sentence: ANSWER_WORDS, ENABLED_WORDS, HIDDEN_WORDS, PIN_OP_WORDS, ORDER_WORDS, SIGNUP_WORDS and VISIBILITY_WORDS. The wording is unchanged.
• src/http/api.ts (6 lines), src/http/feed.ts (1 line) and src/http/mcp.ts (9 lines) now use the constant instead of the typed-out string. Only the lines with the sentences changed, plus one import block at the end of each file's imports.
• src/contract/openapi.ts also had three copies (bad_enabled, the make-it-yours invalid, and /api/v1/asked's invalid_order). The issue doesn't list this file, but its done-criterion needs grep -rn under src/ to find only the module, so these now read the constants too. Two are template literals (` 422: ${ENABLED_WORDS} `) that produce the same string as before. Look at this file first, since it is the one change beyond the issue's file list.

Test

• The new test/arg-words.test.ts checks that the module holds exactly the seven sentences. For each of the four files, it reads the source as text, checks the file imports arg_words.ts, and fails if any sentence is typed back in.

Checks run

• bun x tsc --noEmit is clean.
• 29 test files, 147 tests, all pass: the new test, every openapi* test, and the feed, MCP and API tests that cover these refusals (test/mcp-reposet.test.ts asserts the visibility sentence verbatim). No existing test was changed.
• src/web was not touched, so I didn't run bun scripts/design-lint.ts.

Try it

• grep -rn "visibility is public or private" src/ returns only src/http/arg_words.ts.
• bun test test/arg-words.test.ts

🤖 Generated with Claude Code

Closes #5644

The seven refusal sentences for an argument outside its allowed values now live in one new module, src/http/arg_words.ts. No existing module owned this, so I made a new one. The API, the feed and MCP read the sentences from it.

What moved

• src/http/arg_words.ts exports one constant per sentence: ANSWER_WORDS, ENABLED_WORDS, HIDDEN_WORDS, PIN_OP_WORDS, ORDER_WORDS, SIGNUP_WORDS and VISIBILITY_WORDS. The wording is unchanged.
• src/http/api.ts (6 lines), src/http/feed.ts (1 line) and src/http/mcp.ts (9 lines) now use the constant instead of the typed-out string. Only the lines with the sentences changed, plus one import block at the end of each file's imports.
• src/contract/openapi.ts also had three copies (bad_enabled, the make-it-yours invalid, and /api/v1/asked's invalid_order). The issue doesn't list this file, but its done-criterion needs grep -rn under src/ to find only the module, so these now read the constants too. Two are template literals (` 422: ${ENABLED_WORDS} `) that produce the same string as before. Look at this file first, since it is the one change beyond the issue's file list.

Test

• The new test/arg-words.test.ts checks that the module holds exactly the seven sentences. For each of the four files, it reads the source as text, checks the file imports arg_words.ts, and fails if any sentence is typed back in.

Checks run

• bun x tsc --noEmit is clean.
• 29 test files, 147 tests, all pass: the new test, every openapi* test, and the feed, MCP and API tests that cover these refusals (test/mcp-reposet.test.ts asserts the visibility sentence verbatim). No existing test was changed.
• src/web was not touched, so I didn't run bun scripts/design-lint.ts.

Try it

• grep -rn "visibility is public or private" src/ returns only src/http/arg_words.ts.
• bun test test/arg-words.test.ts

🤖 Generated with Claude Code

An argument's allowed values and the sentence that refuses a wrong one are now written once, in src/http/arg_words.ts. Before this, each route spelled out its own list and refusal. The REST routes (src/http/api.ts), the MCP tools and the OpenAPI contract (src/contract/openapi.ts) all import them from there, so the refusal you see is the same at every entry point. test/arg-words.test.ts fails if a refusal sentence is typed back into a route instead of imported.

Lists moved into arg_words.ts: ANSWER_WORDS, ENABLED_WORDS, ORDER_WORDS, PIN_OP_WORDS, SIGNUP_WORDS, VISIBILITY_WORDS.

This update merges main. The two conflicts were only in imports: main added SELF_WAIT (in src/contract/openapi.ts) and SPEND_WORDS (in src/http/api.ts) next to this branch's arg_words.ts import. Both are kept, and no behaviour changed in the merge. The type check is clean, and 267 tests across the arg-words, OpenAPI, MCP and API error/list-shape suites pass with no failures.

To try it, send a value outside the allowed list to a route that checks it, for example visibility or order, through the API and through the MCP. Both should give the same refusal sentence.

🤖 Generated with Claude Code

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

Each of the seven allowed-values refusals is now written once, in src/core/arg_words.ts. The API, the feed, the MCP tools and the published contract all import it from there. This closes #5644, and the wording is unchanged.

Brought up to date with main. #5932 split src/http/mcp.ts into one file per tool, and #5936 split src/contract/openapi.ts into one file per route. To resolve the merge I took main's version of api.ts, mcp.ts and openapi.ts, then replaced the sentences again in the new layout:

• MCP tools: src/http/mcp/tools/{asked,board_pins,feed_chips,make_it_yours,repo_settings,signup,upstream,variant}.ts
• Contract routes: src/contract/openapi/routes/{getApiV1Asked,postApiV1ReposOwnerNameMakeItYours,putApiV1ReposOwnerNameUpstream}.ts
• API and feed: src/http/api.ts and src/http/feed.ts

No tool's name, schema or doc changed, so there are no MCP docs to regenerate.

Review note from @sentinel. I moved the module from src/http/arg_words.ts to src/core/arg_words.ts. The contract already imports from core/, so it no longer depends on the HTTP layer.

Test. test/arg-words.test.ts names all 13 files that use these sentences and checks that each one imports them rather than typing them out. It also scans every file under src/ and fails if a copy of any sentence comes back anywhere outside the module.

How to check:

• bun x tsc --noEmit is clean.
• bun test test/arg-words.test.ts test/openapi.test.ts test/mcp*.test.ts passes (389 tests).
• A wider run of the related suites had 1536 passing and 4 failing. All 4 are in the "fork at the origin" suite, which needs a host (maria--forge.test) the sandbox blocks; the forge's check will run them.
• On the preview, GET /contract/openapi.json should still publish 422: enabled is true or false, 422: visibility is public or private and order is oldest or newest, exactly as before.

🤖 Generated with Claude Code

The full gate on land was red; the pull is open again. Red tests:

• lists the 100 public repositories and none of the 20 private ones, built in under 15 ms
• lists the 100 public repositories and none of the 20 private ones, built in under 15 ms [19.73ms] [shard 900]

Each of the seven allowed-values refusals is now written once, in src/core/arg_words.ts. The API, the feed, eight MCP tool files and three contract route files all import it from there. This closes #5644, and the wording is unchanged.

Why the gate was red. The failing test, test/sitemap.test.ts ("built in under 15 ms", from #6159 on main), had a bug in the test itself; this pull's code didn't cause it. In the Server-Timing header, app is the whole request, and repos, render and etag are stretches inside it. The test added all four together, so those three phases were counted twice.

• Here the real request takes about 7–9 ms, but the sum came to 10–12 ms. Any slow moment on a busy check machine pushed it past 15.
• On main it failed 1 run in 5 here.
• It now checks app alone against the same 15 ms limit. The limit and the other checks are unchanged. 20 runs in a row passed.

Also in this push:

• Merged main again; there were no conflicts.
• Took @sentinel's naming nit: the shared import path in test/arg-words.test.ts is now called DEEP, because MCP tools and contract routes both sit three folders down.

How to check: bun x tsc --noEmit is clean, and bun test test/arg-words.test.ts test/sitemap.test.ts passes. On the preview, /contract/openapi.json still publishes 422: enabled is true or false, 422: visibility is public or private and order is oldest or newest.

🤖 Generated with Claude Code

Steward tick: this pull is red on its own merge with current main (gated alone, failed) and was held out of the landing queue so the others can land. Rebase on main, fix the failing test, push - then the hold comes off.

Each of the seven allowed-values refusals is now written once, in src/core/arg_words.ts. The API, the feed, eight MCP tool files and three contract route files all import it from there. This closes #5644, and the wording is unchanged.

Why the gate was red. My last push broke a different test. test/flake.test.ts enforces #4429: a test may only bound a speed through expectBudget, never with a raw ms number. My edit to test/sitemap.test.ts, expect(total(timing)).toBeLessThan(15), was a raw number the lint catches.

• Main's version, expect(phases(timing)).toBeLessThan(15), was the same kind of raw budget, but its form got past the lint.
• That raw budget is also why the sitemap test flaked under load. Main's version also counted phases twice: it added repos, render and etag on top of app, which already contains them.
• Now the test takes app alone and checks it with expectBudget(total(timing), { ms: 15, against: await baselineMs(servers.url) }). That is 15 ms on a quiet machine, measured against a same-run baseline under load, and never more than 60 ms.

Rebase. The branch already contains current main (81b4324a), so there was nothing to rebase.

Checks run here:

• bun x tsc --noEmit is clean.
• bun test test/sitemap.test.ts test/flake.test.ts passed 10 runs out of 10.
• The full suite here gives 8513 pass and 32 fail. One failure was the lint above, now fixed. The other 31 need chromium, outside hosts, ports or unix sockets, which this sandbox blocks, and none of them test the refusal sentences.

@sentinel's follow-up note (similar sentences for archived, sealed, stop and others are still typed out) is outside #5644's seven and is left for a separate issue.

🤖 Generated with Claude Code

Taken over by nobody; stopped @scout.

Each of the seven refusals for an argument outside its allowed values is now written once, in src/core/arg_words.ts. The API, the feed, the MCP tool files and the contract route files all import it from there, and the wording hasn't changed. This closes #5644.

This push. The pull could no longer merge because main had moved on 61 commits and test/sitemap.test.ts conflicted. Main had fixed the same flaky timing test its own way in #6194: it measures five times, keeps the fastest, and checks that against expectBudget. The merge keeps main's five runs and swaps in this pull's measure. That measure reads app;dur alone, because app already includes repos, render and etag, and main's version still added them on top. The now-unused phases helper is gone. No other file conflicted.

What to look at:

• test/sitemap.test.ts: the five-run loop now calls total(...) instead of phases(...). The limit and the other checks are as main has them.
• I searched all of src/ for each of the seven sentences, and each appears only in src/core/arg_words.ts. So none of main's new commits typed one back in.

Checks run: bun x tsc --noEmit is clean, and bun test test/sitemap.test.ts test/flake.test.ts test/arg-words.test.ts passes (45 tests). I didn't run the full suite here; the forge runs it on this push.

@trevato's latest comment ("Taken over by nobody; stopped @scout.") is a status note with nothing to change.

🤖 Generated with Claude Code

Closes #5644