diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md index d580061b37c..12864bffe95 100644 --- a/.agents/skills/add-block/SKILL.md +++ b/.agents/skills/add-block/SKILL.md @@ -177,7 +177,7 @@ When adding or changing an OAuth integration block: `packages/sim-setup/src/capability-config.ts`. The CLI catalog is exhaustively typed and checked against the runtime field list; do not infer secrecy from the field name. 4. If the canonical OAuth service declares `serviceAccountProviderId`, run - `bun run deployment-config:generate`; this regenerates the provider-ID facts in + `bun run generate:deployment-config`; this regenerates the provider-ID facts in `packages/deployment-config/src/service-account-providers.generated.ts`. Never hand-edit that generated map. Add `deploymentRequirement` policy in `packages/deployment-config/src/service-account-metadata.ts` only when the service-account path @@ -959,11 +959,11 @@ Verify it with `bun run check:block-successors`. Adding a block on its own needs no **tool metadata** regeneration — a block references existing tool IDs through `tools.access` and does not change any tool's shape. -But if the same change also adds, edits **or removes** a tool, run `bun run tool-metadata:generate` and commit the result, or CI fails on stale artifacts. That matters here because a block's `outputs` are authored to match its tools' outputs, and the UI reads those from the generated metadata, not the executable registry — an unregenerated tool change makes the block's outputs disagree with what the panel renders. See `.agents/skills/tool-registry-boundary/SKILL.md`. +But if the same change also adds, edits **or removes** a tool, run `bun run generate:tool-metadata` and commit the result, or CI fails on stale artifacts. That matters here because a block's `outputs` are authored to match its tools' outputs, and the UI reads those from the generated metadata, not the executable registry — an unregenerated tool change makes the block's outputs disagree with what the panel renders. See `.agents/skills/tool-registry-boundary/SKILL.md`. A visible integration block does require the generated integration catalog and docs to be refreshed: -`bun run tool-metadata:generate` (only when a tool changed), `bun run scripts/generate-docs.ts`, -`bun run deployment-config:generate`, then `bun run check:audits`. Also run +`bun run generate:tool-metadata` (only when a tool changed), `bun run scripts/generate-docs.ts`, +`bun run generate:deployment-config`, then `bun run check:audits`. Also run `bun run apps/sim/scripts/check-block-registry.ts origin/staging` (CI runs it outside `check:audits`). Commit the full generator output. For what each check verifies, see the `validate-integration` skill → Regenerate Derived Artifacts. @@ -986,10 +986,10 @@ Regenerate Derived Artifacts. - [ ] Outputs match tool outputs - [ ] Block + meta registered in registry-maps.ts (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`) - [ ] If `sunset.replacedBy` changed: regenerated and committed the block successor map; `bun run check:block-successors` passes -- [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts +- [ ] If any tool was added, changed or removed alongside the block: ran `bun run generate:tool-metadata` and committed the artifacts - [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes -- [ ] `bun run integration-catalog:check` passes -- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page) +- [ ] `bun run check:integration-catalog` passes +- [ ] `bun run check:docs` passes (CI gate — fails on any stale generated docs page) - [ ] If icon missing: asked user to provide SVG - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread - [ ] Optional/rarely-used fields set to `mode: 'advanced'` diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md index a9f614bd387..94ab90181b0 100644 --- a/.agents/skills/add-integration/SKILL.md +++ b/.agents/skills/add-integration/SKILL.md @@ -293,7 +293,7 @@ export const tools: Record = { Then regenerate the generated tool metadata and commit it: ```bash -bun run tool-metadata:generate +bun run generate:tool-metadata ``` Client code reads `params`/`outputs` from these artifacts rather than importing @@ -370,7 +370,7 @@ the OAuth service configuration, deployment availability, and the setup CLI. infer secret fields from naming; the CLI mapping is exhaustively checked against the runtime fields. 4. If the canonical OAuth service has `serviceAccountProviderId`, run - `bun run deployment-config:generate` to refresh + `bun run generate:deployment-config` to refresh `packages/deployment-config/src/service-account-providers.generated.ts`; never hand-edit the generated provider-ID map. In `packages/deployment-config/src/service-account-metadata.ts`, use: - no `deploymentRequirement` when the service-account path works independently of OAuth client fields; @@ -386,8 +386,8 @@ a resolvable capability must fail validation; an independent service account use ## Step 8: Generate and Validate the Catalog -Run `bun run tool-metadata:generate`, `bun run scripts/generate-docs.ts`, -`bun run deployment-config:generate`, then `bun run check:audits` (see the `validate-integration` +Run `bun run generate:tool-metadata`, `bun run scripts/generate-docs.ts`, +`bun run generate:deployment-config`, then `bun run check:audits` (see the `validate-integration` skill → Regenerate Derived Artifacts for the full list and what each check verifies). The docs generator creates `apps/docs/content/docs/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`). @@ -457,7 +457,7 @@ If creating V2 versions (API-aligned outputs): - [ ] All optional outputs have `optional: true` - [ ] Created `index.ts` barrel export - [ ] Registered all tools in `tools/registry.ts` -- [ ] Ran `bun run tool-metadata:generate` and committed the regenerated artifacts +- [ ] Ran `bun run generate:tool-metadata` and committed the regenerated artifacts - [ ] Classified every model-visible, opaque, Sim-durable, and internal-execution request field - [ ] Added shared model-input projection or private provenance only where required; ordinary external resource locators and control inputs retain their request semantics @@ -530,15 +530,15 @@ If creating V2 versions (API-aligned outputs): ### Docs and deployment metadata - [ ] Ran `bun run scripts/generate-docs.ts` -- [ ] Ran `bun run deployment-config:generate` for OAuth or service-account changes +- [ ] Ran `bun run generate:deployment-config` for OAuth or service-account changes - [ ] Verified docs file created - [ ] Wrote the `{/* MANUAL-CONTENT-START:intro */}` section under `` and confirmed it survives a regenerate - [ ] Reviewed and committed the generated `packages/deployment-config/src/integrations.json` change -- [ ] `bun run integration-catalog:check` passes -- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator +- [ ] `bun run check:integration-catalog` passes +- [ ] `bun run check:docs` passes — CI fails on stale generated docs, so commit the full generator output, including catch-up regeneration for pages another PR left stale (never revert it as "unrelated drift") -- [ ] `bun run deployment-config:check` passes +- [ ] `bun run check:deployment-config` passes ### Final Validation (Required) - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs diff --git a/.agents/skills/add-model/SKILL.md b/.agents/skills/add-model/SKILL.md index 75721721c4b..c311f7afd3d 100644 --- a/.agents/skills/add-model/SKILL.md +++ b/.agents/skills/add-model/SKILL.md @@ -54,7 +54,7 @@ Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string, | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `kimi`, `cerebras`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, openrouter, fireworks, vertex — re-grep before assuming | | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere | | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere | -| `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults | +| `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`check:agent-stream-docs` fails without it); other families fall back to provider defaults | | `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) | | `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap | | `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs | @@ -143,9 +143,9 @@ The Consumption Matrix (Step 2) tells you which capability *flags* are honored b If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page: -- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing. +- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run check:agent-stream-docs` (CI) fails if the field is missing. - Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the model deviates from its family. -- After inserting the entry, run `bun run agent-stream-docs:generate` and commit the regenerated `apps/docs/content/docs/workflows/blocks/agent.mdx` — CI diffs it. +- After inserting the entry, run `bun run generate:agent-stream-docs` and commit the regenerated `apps/docs/content/docs/workflows/blocks/agent.mdx` — CI diffs it. - Include the `streamed` value (with its source URL) in the verification report when set. ### Wrong family entirely? @@ -157,7 +157,7 @@ If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it a ```bash bun run lint -bun run agent-stream-docs:generate # only when the entry has thinking/reasoningEffort +bun run generate:agent-stream-docs # only when the entry has thinking/reasoningEffort ``` Lint must pass before you report done — fix the entry you wrote, never delete it to make lint pass. diff --git a/.agents/skills/add-tools/SKILL.md b/.agents/skills/add-tools/SKILL.md index ec57396720b..2c1982b251c 100644 --- a/.agents/skills/add-tools/SKILL.md +++ b/.agents/skills/add-tools/SKILL.md @@ -455,7 +455,7 @@ export const tools = { 3. Regenerate the tool metadata artifacts: ```bash -bun run tool-metadata:generate +bun run generate:tool-metadata ``` Client code reads a tool's `params`/`outputs` from generated metadata rather than @@ -614,10 +614,10 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix: - [ ] Types file has all interfaces - [ ] Index.ts exports all tools and re-exports types (`export * from './types'`) - [ ] Tools registered in `tools/registry.ts` -- [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed +- [ ] `bun run generate:tool-metadata` run and the regenerated artifacts committed - [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's docs page is rendered from each tool's description, params, and outputs, and CI's - `bun run docs:check` fails on stale pages + `bun run check:docs` fails on stale pages - [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs - [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms only where a concrete Sim `{{...}}` resolution path requires them diff --git a/.agents/skills/add-trigger/SKILL.md b/.agents/skills/add-trigger/SKILL.md index 69f3657649a..b1dc00f591b 100644 --- a/.agents/skills/add-trigger/SKILL.md +++ b/.agents/skills/add-trigger/SKILL.md @@ -539,5 +539,5 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails - [ ] Manually verify output keys match trigger `outputs` keys - [ ] Trigger UI shows correctly in the block - [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections - render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale + render into the owning integration's docs page, and CI's `bun run check:docs` fails on stale pages diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md index fa6e5433ee5..342774b7858 100644 --- a/.agents/skills/ship/SKILL.md +++ b/.agents/skills/ship/SKILL.md @@ -49,10 +49,10 @@ When the user runs `/ship`: - `bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy. 6. **Run pre-ship checks** from the repo root before staging. This has two phases: first **regenerate** every committed artifact so generated files never drift into a CI failure (this is what catches things like `agent-stream-docs` going stale after a `models.ts` edit), then run the **full audit suite** CI's `lint` job enforces. Both phases parallelize — but only across commands that write **disjoint** outputs — and a bare `wait` swallows child exit codes, so both phases below explicitly collect each job's status and abort ship if any failed. - **Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync): + **Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `generate:agent-stream-docs` (derives from the provider model registry), `generate:docs-manifest` (derives from docs page paths), `generate:tool-metadata` (derives from the tool registry), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, `apps/sim/tools/generated/*`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync): ```bash rm -f /tmp/ship-gen-results - for g in agent-stream-docs:generate docs-manifest:generate skills:sync; do + for g in generate:agent-stream-docs generate:docs-manifest generate:tool-metadata skills:sync; do ( bun run "$g" >"/tmp/ship-gen-${g//:/-}.log" 2>&1; echo "$? $g" >>/tmp/ship-gen-results ) & done wait @@ -64,7 +64,7 @@ When the user runs `/ship`: ``` Then `git status --short` to see what regenerated — those files must be staged in step 7 alongside your own changes. - **Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/mothership/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `integration-catalog:check` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present. + **Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/mothership/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `check:integration-catalog` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present. **Phase B — run lint + every audit CI enforces, in parallel, and abort ship if any fails.** Before running the commands, compare this list with `.github/workflows/checks.yml`; when CI adds an audit, run it and update this skill instead of trusting a stale snapshot. The env-flag audit is currently an inline workflow block rather than a package script: when `apps/sim/lib/core/config/env-flags.ts` changed, run that current workflow block verbatim instead of copying a second version into this skill. Run `bun run lint` first (it autofixes formatting and mutates files, so don't parallelize it with the read-only audits), then run the base-sensitive block-registry check, then fan the independent audits out and collect exit codes: ```bash @@ -77,17 +77,13 @@ When the user runs `/ship`: } # Runs every audit CI runs, concurrently, and replays the output of any that fail. # The audit list is derived in scripts/run-audits.ts — do not hand-list audits here. - # Install CI's pinned actionlint version for the host OS/architecture and verify its - # artifact against the official release checksums in a local mktemp directory. - # Preserve CI's -shellcheck= -pyflakes= flags; lint all workflows and abort ship if it fails. + # Workflow lint (actionlint) runs only in CI's "Lint workflows" step. bun run check:audits || { echo "❌ audit(s) failed — do not ship"; exit 1; } bun run type-check || { echo "❌ type-check failed — do not ship"; exit 1; } - # CI's "Verify docs manifest is in sync" step is not a `check:*` script, so the runner above - # does not cover it. (CI's "Security audit" `bun audit` step is `continue-on-error` — advisory - # only, not a gate — so it is deliberately not run here.) - bun run docs-manifest:check || { echo "❌ docs manifest out of sync — do not ship"; exit 1; } + # CI's "Security audit" `bun audit` step is `continue-on-error` — advisory only, not a gate — + # so it is deliberately not run here. ``` - If Phase A regenerated a file, its matching `:check` in Phase B now passes trivially — that parity is the point. Do not ship with any generator or audit failing; fix the cause (never silence it) and re-run. `check:migrations` is covered by step 5 and is not repeated here. + If Phase A regenerated a file, its matching `check:*` audit in Phase B now passes trivially — that parity is the point. Do not ship with any generator or audit failing; fix the cause (never silence it) and re-run. `check:migrations` is covered by step 5 and is not repeated here. 7. **Stage and commit** the changes with the generated message — including any files Phase A regenerated in step 6 8. **Push to origin** using the current branch name — `--force-with-lease` if step 2's sync check did any history rewrite (a clean rebase or a cherry-pick rebuild) on a branch that had diff --git a/.agents/skills/tool-registry-boundary/SKILL.md b/.agents/skills/tool-registry-boundary/SKILL.md index 779fe6e3d2c..c063d66e861 100644 --- a/.agents/skills/tool-registry-boundary/SKILL.md +++ b/.agents/skills/tool-registry-boundary/SKILL.md @@ -40,8 +40,8 @@ All lookups guard with `Object.hasOwn`. `JSON.parse` yields an object with the n `apps/sim/tools/generated/tool-ids.ts`, `tool-metadata.ts` and `tool-outputs.ts` are produced by `scripts/sync-tool-metadata.ts`: ```bash -bun run tool-metadata:generate # after adding/changing a tool -bun run tool-metadata:check # what CI runs; fails if stale +bun run generate:tool-metadata # after adding/changing a tool +bun run check:tool-metadata # what CI runs; fails if stale ``` Never hand-edit them. If you add a tool or change a tool's `params`/`outputs`, regenerate and commit the result, or CI fails. diff --git a/.agents/skills/validate-integration/SKILL.md b/.agents/skills/validate-integration/SKILL.md index dce322e08fc..32c82a5746f 100644 --- a/.agents/skills/validate-integration/SKILL.md +++ b/.agents/skills/validate-integration/SKILL.md @@ -428,28 +428,28 @@ After reporting, fix every **critical** and **warning** issue. Apply **suggestio Several files are generated from tool and block definitions. Editing a tool or block WITHOUT regenerating them fails CI, so run these before pushing: ```bash -bun run tool-metadata:generate # repo root — apps/sim/tools/generated/* +bun run generate:tool-metadata # repo root — apps/sim/tools/generated/* bun run scripts/generate-docs.ts # docs .mdx + deployment-config/integrations.json + docs icons -bun run deployment-config:generate # canonical OAuth registry + catalog → provider-ID facts -bun run integration-catalog:check # registry ↔ committed deployment metadata drift -bun run docs:check # committed docs ↔ what the generator renders today -bun run deployment-config:check # OAuth registry/catalog ↔ provider-ID fact drift -bun run check:audits # every audit CI enforces, including docs:check +bun run generate:deployment-config # canonical OAuth registry + catalog → provider-ID facts +bun run check:integration-catalog # registry ↔ committed deployment metadata drift +bun run check:docs # committed docs ↔ what the generator renders today +bun run check:deployment-config # OAuth registry/catalog ↔ provider-ID fact drift +bun run check:audits # every audit CI enforces, including check:docs bun run apps/sim/scripts/check-block-registry.ts origin/staging # block ↔ tool param coverage (CI, not in check:audits) ``` -- **`tool-metadata:generate`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run tool-metadata:check`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it. +- **`generate:tool-metadata`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run check:tool-metadata`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it. - **`generate-docs`** — required whenever block metadata changes (`bgColor`, `name`, `description`, operations, outputs). Regenerates the integration `.mdx`, `packages/deployment-config/src/integrations.json`, and the docs copy of `components/icons.tsx`. -- **`deployment-config:generate`** — required for OAuth or service-account changes. Regenerates provider-ID facts from the canonical OAuth registry and integration catalog; special deployment requirements remain handwritten policy. -- **`integration-catalog:check`** — loads the executable block registry, derives visible integration +- **`generate:deployment-config`** — required for OAuth or service-account changes. Regenerates provider-ID facts from the canonical OAuth registry and integration catalog; special deployment requirements remain handwritten policy. +- **`check:integration-catalog`** — loads the executable block registry, derives visible integration deployment fields, and compares them with the committed catalog. It catches missing/unexpected entries and stale auth/service IDs without loading the executable registry in client code. -- **`docs:check`** — check mode of `generate-docs.ts`: renders every generated docs artifact in +- **`check:docs`** — check mode of `generate-docs.ts`: renders every generated docs artifact in memory and fails listing any committed file that differs. Runs in CI via `check:audits`. **Always diff the regen output before committing — but commit all of it.** These generators rewrite every file they own, so they also true up drift that accumulated on the base branch (pages whose -source changed without a regen). That catch-up is correct output, not a regression: `docs:check` +source changed without a regen). That catch-up is correct output, not a regression: `check:docs` fails CI on any page left stale, so reverting swept-in hunks with `git checkout --` reintroduces the failure. Review the diff to confirm each hunk is explained by a real source change (yours or an upstream PR that skipped regeneration), and investigate anything that looks like content loss — a @@ -469,10 +469,10 @@ After fixing, confirm: 2. TypeScript compiles clean (no type errors) — check the error list is empty for the files you touched; pre-existing unrelated errors in a worktree usually mean workspace packages resolve to the main checkout 3. The integration's tests pass, and any test you added actually fails without its fix (revert it once and watch it go red) 4. Derived artifacts regenerated and their diffs reviewed (see above) -5. `bun run integration-catalog:check` passes -6. `bun run docs:check` passes +5. `bun run check:integration-catalog` passes +6. `bun run check:docs` passes 7. `bun run apps/sim/scripts/check-block-registry.ts origin/staging` passes -8. For OAuth or service-account changes, `bun run deployment-config:check` passes +8. For OAuth or service-account changes, `bun run check:deployment-config` passes 9. For OAuth or service-account changes, `bun run --cwd apps/sim test lib/integrations/availability.server.test.ts` passes 10. Re-read all modified files to verify fixes are correct 11. Any remaining unknown response schemas were explicitly reported to the user instead of guessed @@ -506,8 +506,8 @@ After fixing, confirm: `selectors.execute` boundary - [ ] Reported all issues grouped by severity - [ ] Fixed all critical and warning issues -- [ ] Ran `bun run tool-metadata:generate` if any tool outputs/params changed, and confirmed `bun run tool-metadata:check` passes -- [ ] Ran `bun run scripts/generate-docs.ts` if any block metadata changed, and committed the full generated diff — including stale-page catch-up for other integrations (`bun run docs:check` fails CI on reverted generator output) +- [ ] Ran `bun run generate:tool-metadata` if any tool outputs/params changed, and confirmed `bun run check:tool-metadata` passes +- [ ] Ran `bun run scripts/generate-docs.ts` if any block metadata changed, and committed the full generated diff — including stale-page catch-up for other integrations (`bun run check:docs` fails CI on reverted generator output) - [ ] Validated the docs page has an accurate `MANUAL-CONTENT-START:intro` section - [ ] Ran `bun run lint` after fixes - [ ] Verified TypeScript compiles clean diff --git a/.agents/skills/validate-model/SKILL.md b/.agents/skills/validate-model/SKILL.md index 7555cc45edf..776df5ab93d 100644 --- a/.agents/skills/validate-model/SKILL.md +++ b/.agents/skills/validate-model/SKILL.md @@ -69,7 +69,7 @@ For each model, evaluate every row. Statuses: ✓ matches docs, ✗ disagrees, - [ ] `reasoningEffort.values` — list matches docs; **omitted** for always-reasoning models that reject the parameter (e.g., grok-4.3, where xAI docs explicitly state `reasoning_effort` is not supported). Verify per model — some always-reasoning models (e.g., OpenAI's o-series) DO accept `reasoning_effort` and should keep the flag. - [ ] `verbosity.values` — only on OpenAI gpt-5.x family; values match docs - [ ] `thinking.levels` + `thinking.default` — only on providers whose code reads `thinking`/`thinkingLevel` (see the add-model Consumption Matrix); values match docs -- [ ] `thinking.streamed` — REQUIRED on Anthropic-family thinking models. Current Claude thinking models use `'summary'` (Sim requests `display: 'summarized'`); use `'full'` only if official API docs explicitly guarantee raw thinking deltas. Verify against the provider's thinking-display docs. After any change, run `bun run agent-stream-docs:generate` so the Agent block docs table stays in sync (CI diffs it) +- [ ] `thinking.streamed` — REQUIRED on Anthropic-family thinking models. Current Claude thinking models use `'summary'` (Sim requests `display: 'summarized'`); use `'full'` only if official API docs explicitly guarantee raw thinking deltas. Verify against the provider's thinking-display docs. After any change, run `bun run generate:agent-stream-docs` so the Agent block docs table stays in sync (CI diffs it) - [ ] `nativeStructuredOutputs` — only on providers whose code consumes it (see the Consumption Matrix); provider must document Structured Outputs / JSON-mode for this model - [ ] `toolUsageControl` — provider supports `tool_choice` semantics - [ ] `computerUse` — provider implements computer-use loop AND model is a computer-use SKU diff --git a/.claude/rules/sim-integrations.md b/.claude/rules/sim-integrations.md index bb71f32beb4..9969be4d046 100644 --- a/.claude/rules/sim-integrations.md +++ b/.claude/rules/sim-integrations.md @@ -20,5 +20,5 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc - `canonicalParamId` may match only the `id` of a member of its own group (as the `add-block` skill's `channel` example does), never any other subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID. - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution. - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer. -- Integration blocks (`category: 'tools'`) must set `integrationType` (`integration-catalog:check` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented. +- Integration blocks (`category: 'tools'`) must set `integrationType` (`check:integration-catalog` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented. - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences". diff --git a/.cursor/rules/sim-integrations.mdc b/.cursor/rules/sim-integrations.mdc index 624d388b8cf..ce8c3d1b690 100644 --- a/.cursor/rules/sim-integrations.mdc +++ b/.cursor/rules/sim-integrations.mdc @@ -19,5 +19,5 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc - `canonicalParamId` may match only the `id` of a member of its own group (as the `add-block` skill's `channel` example does), never any other subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID. - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution. - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer. -- Integration blocks (`category: 'tools'`) must set `integrationType` (`integration-catalog:check` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented. +- Integration blocks (`category: 'tools'`) must set `integrationType` (`check:integration-catalog` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented. - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences". diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 0865cdf99a8..e8f0dcc9432 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -560,9 +560,6 @@ jobs: - name: Repo audits run: bun run check:audits - - name: Verify docs manifest is in sync - run: bun run docs-manifest:check - - name: Migration safety (zero-downtime) audit run: bun run check:migrations "${{ steps.audit_base.outputs.ref }}" diff --git a/.github/workflows/publish-sim-setup.yml b/.github/workflows/publish-sim-setup.yml index f7560f0e65c..981404a121f 100644 --- a/.github/workflows/publish-sim-setup.yml +++ b/.github/workflows/publish-sim-setup.yml @@ -46,7 +46,7 @@ jobs: run: bun run bump:npm-packages sim-setup - name: Check generated deployment config - run: bun run deployment-config:check + run: bun run check:deployment-config - name: Run tests working-directory: packages/sim-setup diff --git a/CLAUDE.md b/CLAUDE.md index d416a2a6463..2a1c9fdb2ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -142,9 +142,8 @@ Before declaring a change done, run the local gate from the repo root; CI runs t ```bash bun run lint # biome format + lint, autofixes (CI runs lint:check) bun run type-check # every workspace -bun run check:audits # every check:* audit plus the generated-artifact checks +bun run check:audits # every check:* audit, generated-artifact checks included bun run test # script tests, then every workspace's Vitest suite -bun run docs-manifest:check git fetch origin staging # the block-registry check diffs against it bun run apps/sim/scripts/check-block-registry.ts origin/staging ``` diff --git a/apps/docs/content/docs/workflows/blocks/agent.mdx b/apps/docs/content/docs/workflows/blocks/agent.mdx index 34be1c7e497..83d38cdb4bb 100644 --- a/apps/docs/content/docs/workflows/blocks/agent.mdx +++ b/apps/docs/content/docs/workflows/blocks/agent.mdx @@ -152,7 +152,7 @@ When a response format is set, its fields are readable directly, like ` = JSON.parse( diff --git a/apps/sim/tools/generated/tool-outputs.ts b/apps/sim/tools/generated/tool-outputs.ts index 3cc24b9f3b0..b577d4b29d9 100644 --- a/apps/sim/tools/generated/tool-outputs.ts +++ b/apps/sim/tools/generated/tool-outputs.ts @@ -1,5 +1,5 @@ // Generated by scripts/sync-tool-metadata.ts — do not edit. -// Regenerate with: bun run tool-metadata:generate +// Regenerate with: bun run generate:tool-metadata /** Declared output shapes for every built-in tool, keyed by tool id. */ const toolOutputs: Record = JSON.parse( diff --git a/apps/sim/tools/metadata-outputs.ts b/apps/sim/tools/metadata-outputs.ts index ad8c9a0521e..444f5846551 100644 --- a/apps/sim/tools/metadata-outputs.ts +++ b/apps/sim/tools/metadata-outputs.ts @@ -12,7 +12,7 @@ import type { ToolConfig } from '@/tools/types' * and never load this module. * * The backing data is generated by `scripts/sync-tool-metadata.ts` and verified - * in CI by `bun run tool-metadata:check`. Never hand-edit it. + * in CI by `bun run check:tool-metadata`. Never hand-edit it. */ type ToolOutputs = NonNullable diff --git a/apps/sim/tools/metadata.test.ts b/apps/sim/tools/metadata.test.ts index d6b17d4f820..dfe81511ff6 100644 --- a/apps/sim/tools/metadata.test.ts +++ b/apps/sim/tools/metadata.test.ts @@ -12,7 +12,7 @@ vi.unmock('@/tools/metadata-outputs') /** * Guards the properties the generated artifacts are relied on for. The - * `tool-metadata:check` script guards that they are in sync with the registry; + * `check:tool-metadata` script guards that they are in sync with the registry; * these guard that what they contain is usable. */ describe('generated tool metadata', () => { diff --git a/apps/sim/tools/metadata.ts b/apps/sim/tools/metadata.ts index 00fde1f6cd4..0c91c66d6e1 100644 --- a/apps/sim/tools/metadata.ts +++ b/apps/sim/tools/metadata.ts @@ -13,7 +13,7 @@ import type { OAuthConfig, PersonalTokenConfig, ToolConfig } from '@/tools/types * exists — read it from here instead, and stay off the registry entirely. * * The backing data is generated by `scripts/sync-tool-metadata.ts` and verified - * in CI by `bun run tool-metadata:check`. Never hand-edit it. + * in CI by `bun run check:tool-metadata`. Never hand-edit it. * * Outputs live in `@/tools/metadata-outputs`, not here: they are the larger half * of the data and have a single consumer, so keeping them in a separate module diff --git a/apps/sim/tools/utils.ts b/apps/sim/tools/utils.ts index f2ce921a70d..08c8d565ac0 100644 --- a/apps/sim/tools/utils.ts +++ b/apps/sim/tools/utils.ts @@ -70,7 +70,7 @@ export function getLatestVersionTools( * deliberately: this one reads the live registry, so a tool added but not yet * regenerated stays resolvable; that one resolves against the generated id list * without pulling 4,300 tools into a client graph. Client code wants that one. - * `tool-metadata:check` asserts the two never diverge. + * `check:tool-metadata` asserts the two never diverge. * * @param toolName The tool name to resolve (may or may not have version suffix) * @returns The actual tool ID in the registry, or the original name if not found diff --git a/package.json b/package.json index 4cac3722380..3a7a6fa8e0a 100644 --- a/package.json +++ b/package.json @@ -91,14 +91,14 @@ "mship-contracts:check": "bun run scripts/sync-mothership-stream-contract.ts --check", "billing-protocol-contract:generate": "bun run scripts/sync-billing-protocol-contract.ts", "billing-protocol-contract:check": "bun run scripts/sync-billing-protocol-contract.ts --check", - "tool-metadata:generate": "bun run scripts/sync-tool-metadata.ts", - "tool-metadata:check": "bun run scripts/sync-tool-metadata.ts --check", - "deployment-config:generate": "bun run scripts/generate-deployment-config.ts", - "deployment-config:check": "bun run scripts/generate-deployment-config.ts --check", + "generate:tool-metadata": "bun run scripts/sync-tool-metadata.ts", + "check:tool-metadata": "bun run scripts/sync-tool-metadata.ts --check", + "generate:deployment-config": "bun run scripts/generate-deployment-config.ts", + "check:deployment-config": "bun run scripts/generate-deployment-config.ts --check", "images:generate": "bun run scripts/generate-image-manifest.ts", "images:check": "bun run scripts/generate-image-manifest.ts --check", - "integration-catalog:check": "bun run scripts/check-integration-catalog.ts", - "docs:check": "bun run scripts/generate-docs.ts --check", + "check:integration-catalog": "bun run scripts/check-integration-catalog.ts", + "check:docs": "bun run scripts/generate-docs.ts --check", "mship-tools:generate": "bun run scripts/sync-tool-catalog.ts", "mship-tools:check": "bun run scripts/sync-tool-catalog.ts --check", "trace-spans-contract:generate": "bun run scripts/sync-trace-spans-contract.ts", @@ -113,8 +113,8 @@ "metrics-contract:check": "bun run scripts/sync-metrics-contract.ts --check", "vfs-snapshot-contract:generate": "bun run scripts/sync-vfs-snapshot-contract.ts", "vfs-snapshot-contract:check": "bun run scripts/sync-vfs-snapshot-contract.ts --check", - "docs-manifest:generate": "bun run scripts/sync-docs-manifest.ts", - "docs-manifest:check": "bun run scripts/sync-docs-manifest.ts --check", + "generate:docs-manifest": "bun run scripts/sync-docs-manifest.ts", + "check:docs-manifest": "bun run scripts/sync-docs-manifest.ts --check", "mship:generate": "bun run scripts/generate-mship-contracts.ts", "mship:check": "bun run scripts/generate-mship-contracts.ts --check", "library:covers": "bun run scripts/generate-library-covers.tsx", @@ -123,8 +123,8 @@ "bump:npm-packages": "bun run scripts/bump-npm-package-versions.ts", "sim": "bun run packages/sim-cli/src/index.ts", "sim-setup": "bun run packages/sim-setup/src/index.ts", - "agent-stream-docs:generate": "bun run scripts/sync-agent-stream-docs.ts", - "agent-stream-docs:check": "bun run scripts/sync-agent-stream-docs.ts --check", + "generate:agent-stream-docs": "bun run scripts/sync-agent-stream-docs.ts", + "check:agent-stream-docs": "bun run scripts/sync-agent-stream-docs.ts --check", "prepare": "bun husky", "test:workflow-sync": "bun --no-env-file scripts/test-integration.ts lib/workspaces/__integration__", "type-check": "turbo run type-check", diff --git a/packages/deployment-config/src/service-account-providers.generated.ts b/packages/deployment-config/src/service-account-providers.generated.ts index 53bc149a374..7d0c703ac54 100644 --- a/packages/deployment-config/src/service-account-providers.generated.ts +++ b/packages/deployment-config/src/service-account-providers.generated.ts @@ -1,5 +1,5 @@ /** - * Generated by `bun run deployment-config:generate` from the canonical OAuth + * Generated by `bun run generate:deployment-config` from the canonical OAuth * registry and integration catalog. Do not edit this file directly. */ export const SERVICE_ACCOUNT_PROVIDER_BY_OAUTH_SERVICE_ID = { diff --git a/packages/testing/src/mocks/tool-registry.mock.ts b/packages/testing/src/mocks/tool-registry.mock.ts index eb9c02f47e2..b3004faaaaa 100644 --- a/packages/testing/src/mocks/tool-registry.mock.ts +++ b/packages/testing/src/mocks/tool-registry.mock.ts @@ -14,7 +14,7 @@ * ``` * * Registration itself is asserted with `hasToolId` from `@/tools/tool-ids`, - * which is generated from the registry and kept in sync by `tool-metadata:check`. + * which is generated from the registry and kept in sync by `check:tool-metadata`. */ export function partialToolRegistry( ...modules: Array> diff --git a/scripts/check-monorepo-boundaries.ts b/scripts/check-monorepo-boundaries.ts index f158e96c714..d4607fab57e 100644 --- a/scripts/check-monorepo-boundaries.ts +++ b/scripts/check-monorepo-boundaries.ts @@ -1,4 +1,21 @@ #!/usr/bin/env bun +/** + * Fails when any file under `packages/*` imports from `apps/*`. + * + * Dependencies point toward shared code: apps consume packages, never the reverse. A package + * that reaches into an app drags that app's module graph (Next.js, the block and tool + * registries, the executor) into every other consumer, including `apps/realtime`, and couples + * the package to an app's internal layout. + * + * Flagged, including type-only imports, re-exports, `import()` and `require()`: an `@/…` or + * `apps/…` specifier, an app's package name (or a subpath of it), and a relative path that + * resolves into `apps/`. + * + * Fix a finding by moving the shared code into a package that both sides import, or by keeping + * the code that needs it in the app. There is no allowlist. + * + * Run: `bun run check:boundaries` + */ import { readdir, readFile } from 'node:fs/promises' import path from 'node:path' import ts from '@typescript/typescript6' diff --git a/scripts/check-openapi.ts b/scripts/check-openapi.ts index 814ab48e571..5ac7f47843a 100644 --- a/scripts/check-openapi.ts +++ b/scripts/check-openapi.ts @@ -1,4 +1,17 @@ #!/usr/bin/env bun +/** + * Fails when the published OpenAPI specs drift from the v2 route contracts. + * + * Runs two checks in order and stops at the first failure: + * + * 1. `generate-openapi.ts --check`: every committed spec matches what the generator renders + * from `apps/sim/lib/api/contracts/v2/openapi/`. Fix by running `bun run generate:openapi` + * and committing the result. + * 2. `check-openapi-specs.ts`: spec integrity, v2 conventions, and the contract cross-check. + * Its header lists each rule; fix the contract or its OpenAPI definition, then regenerate. + * + * Run: `bun run check:openapi` + */ import { spawnSync } from 'node:child_process' import path from 'node:path' diff --git a/scripts/check-realtime-prune-graph.ts b/scripts/check-realtime-prune-graph.ts index 663364165f6..9e2d878466d 100644 --- a/scripts/check-realtime-prune-graph.ts +++ b/scripts/check-realtime-prune-graph.ts @@ -1,4 +1,19 @@ #!/usr/bin/env bun +/** + * Fails when the workspace graph `@sim/realtime` depends on grows past its budget. + * + * The realtime server image is built from `turbo prune @sim/realtime --docker`, and the server + * deliberately avoids Next.js, React, the block and tool registries, provider SDKs, and the + * executor. This check runs the same prune and fails when it pulls in any app other than + * `realtime`, or more than {@link MAX_PRUNED_PACKAGE_COUNT} workspaces in total, which is how a + * new dependency on a heavy package first shows up. + * + * Fix a finding by removing the new dependency from the package realtime consumes, or by + * splitting the part realtime needs into its own pure, single-purpose package. Raise + * {@link MAX_PRUNED_PACKAGE_COUNT} only for a package added to that graph on purpose. + * + * Run: `bun run check:realtime-prune` + */ import { mkdtemp, readdir, rm, stat } from 'node:fs/promises' import { tmpdir } from 'node:os' import path from 'node:path' diff --git a/scripts/generate-deployment-config.ts b/scripts/generate-deployment-config.ts index 12e01aeca9b..0047c59f988 100644 --- a/scripts/generate-deployment-config.ts +++ b/scripts/generate-deployment-config.ts @@ -84,7 +84,7 @@ function renderOAuthDeploymentFacts(facts: CanonicalOAuthDeploymentFacts): strin .join('\n') return `/** - * Generated by \`bun run deployment-config:generate\` from the canonical OAuth + * Generated by \`bun run generate:deployment-config\` from the canonical OAuth * registry and integration catalog. Do not edit this file directly. */ export const SERVICE_ACCOUNT_PROVIDER_BY_OAUTH_SERVICE_ID = { @@ -108,7 +108,7 @@ if (CHECK_MODE) { const current = await readFile(OUTPUT_PATH, 'utf8').catch(() => '') if (current !== generated) { throw new Error( - 'Deployment config is stale. Run `bun run deployment-config:generate` and commit the result.' + 'Deployment config is stale. Run `bun run generate:deployment-config` and commit the result.' ) } process.stdout.write('Deployment config is current.\n') diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index c76f93087ab..c8ca4ae8f5b 100755 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -506,7 +506,7 @@ interface IconRef { /** * Check mode (`--check`): render every generated artifact in memory and compare * it against the committed file instead of writing, so CI can fail on docs - * drift the same way `tool-metadata:check` fails on stale tool metadata. Check + * drift the same way `check:tool-metadata` fails on stale tool metadata. Check * mode performs no filesystem mutations. * * The pipeline writes some pages twice per run — the block pass writes the base diff --git a/scripts/run-audits.ts b/scripts/run-audits.ts index 828d62831be..11f3ee4b00a 100644 --- a/scripts/run-audits.ts +++ b/scripts/run-audits.ts @@ -10,6 +10,12 @@ * hand-maintained list had already drifted: `check:cron-parity` existed, passed, and ran * nowhere. Audits that need a git base ref or write files stay excluded and keep their own * workflow step. + * + * Generated-artifact checks follow the same rule: name the pair `generate:` / `check:` + * and the check runs here. The suffix form `:check` is reserved for checks this job cannot + * run: the mothership contracts (`mship*`, `trace-*`, `metrics`, `vfs`, `billing-protocol`) + * need the sibling copilot repo, `images:check` renders the Helm chart (it runs in + * `.github/workflows/helm.yml`), and `library:covers:check` is only deterministic per machine. */ import path from 'node:path' @@ -20,21 +26,6 @@ const EXCLUDED: Record = { 'check:api-validation': 'superseded by the :strict variant, which this runner does run', } -/** - * Generated-artifact checks that live outside the `check:*` namespace. Listed explicitly - * because the `*:check` namespace also holds checks that need a sibling repo or network. - * - * `images:check` is deliberately absent: it renders the chart, and this job has no Helm. - * It runs in `.github/workflows/helm.yml`, whose path filter covers its generator. - */ -const EXTRA_AUDITS = [ - 'tool-metadata:check', - 'deployment-config:check', - 'integration-catalog:check', - 'docs:check', - 'agent-stream-docs:check', -] as const - const ROOT = path.resolve(import.meta.dir, '..') interface AuditResult { @@ -45,10 +36,7 @@ interface AuditResult { } function auditScripts(scripts: Record): string[] { - const derived = Object.keys(scripts).filter( - (name) => name.startsWith('check:') && !(name in EXCLUDED) - ) - return [...derived, ...EXTRA_AUDITS] + return Object.keys(scripts).filter((name) => name.startsWith('check:') && !(name in EXCLUDED)) } /** diff --git a/scripts/sync-agent-stream-docs.ts b/scripts/sync-agent-stream-docs.ts index a21372a46d9..445ac5751f8 100644 --- a/scripts/sync-agent-stream-docs.ts +++ b/scripts/sync-agent-stream-docs.ts @@ -31,7 +31,7 @@ const rootDir = path.resolve(path.dirname(__filename), '..') const AGENT_DOC_PATH = path.join(rootDir, 'apps/docs/content/docs/workflows/blocks/agent.mdx') const BEGIN_MARKER = - '{/* agent-stream-capabilities:begin — generated by `bun run agent-stream-docs:generate`; do not edit between markers */}' + '{/* agent-stream-capabilities:begin — generated by `bun run generate:agent-stream-docs`; do not edit between markers */}' const END_MARKER = '{/* agent-stream-capabilities:end */}' /** @@ -165,7 +165,7 @@ function main(): void { if (checkMode) { if (next !== doc) { console.error( - 'agent-stream-docs: docs are out of date — run `bun run agent-stream-docs:generate`' + 'agent-stream-docs: docs are out of date — run `bun run generate:agent-stream-docs`' ) process.exit(1) } diff --git a/scripts/sync-docs-manifest.ts b/scripts/sync-docs-manifest.ts index 20cc39184ea..1cf741025d8 100644 --- a/scripts/sync-docs-manifest.ts +++ b/scripts/sync-docs-manifest.ts @@ -20,8 +20,8 @@ * and the root `index.mdx` (its URL is `/`, which redirects). * * Usage: - * bun run docs-manifest:generate # write the manifest - * bun run docs-manifest:check # fail (exit 1) if the manifest is stale + * bun run generate:docs-manifest # write the manifest + * bun run check:docs-manifest # fail (exit 1) if the manifest is stale */ import { readdir, readFile, writeFile } from 'node:fs/promises' import { dirname, resolve } from 'node:path' @@ -71,7 +71,7 @@ function render(paths: string[]): string { return `/** * AUTO-GENERATED FILE. DO NOT EDIT. * Generated from apps/docs/content/docs by scripts/sync-docs-manifest.ts. - * Run: bun run docs-manifest:generate. + * Run: bun run generate:docs-manifest. * * Every page in the copilot's read-only \`docs/\` VFS tree, as a path that is * simultaneously the \`docs/\`-relative VFS path and the docs.sim.ai URL path @@ -103,7 +103,7 @@ async function main() { const existing = await readFile(OUTPUT_PATH, 'utf8').catch(() => null) if (existing !== rendered) { throw new Error( - 'Generated docs manifest is stale — the docs tree changed (page added, removed, or renamed). Run: bun run docs-manifest:generate' + 'Generated docs manifest is stale — the docs tree changed (page added, removed, or renamed). Run: bun run generate:docs-manifest' ) } return diff --git a/scripts/sync-tool-metadata.ts b/scripts/sync-tool-metadata.ts index 4731fe27af4..742d93292f4 100644 --- a/scripts/sync-tool-metadata.ts +++ b/scripts/sync-tool-metadata.ts @@ -230,7 +230,7 @@ function serialize(entries: Record, exportName: string, doc: st function serializeValue(value: unknown, exportName: string, doc: string, type: string): string { const literal = toJsStringLiteral(JSON.stringify(value)) return `// Generated by scripts/sync-tool-metadata.ts — do not edit. -// Regenerate with: bun run tool-metadata:generate +// Regenerate with: bun run generate:tool-metadata ${doc} const ${exportName}: ${type} = JSON.parse( @@ -282,7 +282,7 @@ async function main() { readFile(OUTPUTS_PATH, 'utf8').catch(() => null), ]) if (existingIds !== ids || existingMetadata !== metadata || existingOutputs !== outputs) { - throw new Error('Generated tool metadata is stale. Run: bun run tool-metadata:generate') + throw new Error('Generated tool metadata is stale. Run: bun run generate:tool-metadata') } assertResolverParity() console.log(`✓ tool metadata in sync (${toolCount} tools), resolvers agree`)