feat(connector-openapi): declarative providerConfig.include operation allowlist - #27387

Part of #26709 (Work item 1 only). Item 3(c) is held for a contract decision, reported on the card; item 4 lives on #27373.

Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: follow-up owed — skills/objectstack-automation/references/integration-recipes.md, skills/objectstack-automation/evals/integrations-declared.json

维护者速读

• 改了什么:声明式 openapi 连接器实例新增 providerConfig.include(操作白名单),只有列出的操作成为 action;条目写 operationId,无 operationId 的操作写生成的 method_path 键。
• 为什么改:大型 API(GitHub 1,242 个操作、Graph 约 1.8 万)今天只能整份暴露或手工裁剪文档;条目写错或上游改名时启动直接失败并列出文档里的键,不会静默少一个 action。
• 风险与回滚:纯新增键,不写 include 的实例行为不变;回滚即还原本 PR,已写 include 的实例会重新暴露全部操作。
• 先看:packages/connectors/connector-openapi/src/openapi-provider.ts(未知条目拒收与形状校验两段),openapi-connector.ts(抽出唯一的 action 键推导 operationActionKey),openapi-provider.test.ts。
• 两分钟验证:pnpm --filter @objectstack/connector-openapi exec vitest run --maxWorkers=2 src/openapi-provider.test.ts,预期 38 passed,其中 providerConfig.include 组 9 个用例全绿。
• 需要你做的:无,席位落地。

What changes

• connector-openapi provider: providerConfig.include (optional) is an array of action keys: an operation's operationId, or, when it has none, the generated method_path key (delete /customers/{id} is delete_customers_id). It is handed to the generator's existing include predicate (createOpenApiConnector's include?: (op: OperationInfo) => boolean), which the provider did not forward before.
• Unknown entry = fatal configuration fault. An entry the document does not carry throws a plain Error after the bundle is generated: fatal at boot, a skipped entry on reload, never ConnectorUpstreamUnavailableError. The message names the entry and lists up to 20 of the document's keys.
• Shape checked before the document loads. include that is not an array of non-empty strings throws plain before any spec fetch, so a malformed allowlist never exposes the whole document.
• One key derivation. operationActionKey (exported from openapi-connector.ts, not from the package index) is the single spelling of "operationId, else the method_path slug". The generator keys its actions with it, and the provider matches include entries against it, so the entry and the action it admits can never be spelled two ways.
• Docs: content/docs/automation/connectors.mdx documents the key in the openapi section. One changeset (@objectstack/connector-openapi: minor).

Same allowlist meaning as the mcp provider's include (mcp-provider.ts:48, :223-226): a list of names, and only listed names become actions. The two providers now differ on bad entries. The card text makes an unknown openapi entry fatal, but the mcp provider still ignores an unknown tool name (zero actions) and drops a non-array include without a word (every tool exposed). This PR does not touch connector-mcp; the divergence is reported on the card for a decision.

Tests

Head 3d7773a5. New describe('openapi provider — providerConfig.include') in openapi-provider.test.ts, 9 cases:

• control: no include gives every operation (listCustomers, createCustomer, delete_customers_id);
• include: ['listCustomers'] gives exactly that action and that handler;
• an operation without operationId is named by its method_path key; document order is kept;
• include: ['listCustomers', 'nope'] is refused with a plain Error (not upstream-unavailable). The message names 'nope' only and lists the document's keys;
• an operation that has an operationId is not named by its method_path key;
• 'listCustomers', ['listCustomers', 7], [''], an object and null are each refused by shape, and the spec URL is fetched 0 times;
• include: [] admits nothing, the same as an empty mcp include;
• real boot (LiteKernel + AutomationServicePlugin + ConnectorOpenApiPlugin, declared through the registry): the instance is ready with exactly ['listCustomers'] in getConnectorDescriptors(); with ['nope'] the bootstrap rejects naming it, and no degraded reason is recorded.

These are provider-level plain-Error faults. No HTTP envelope is involved, so the assertions check the error class, the upstream-unavailable marker and the named entry, the same way this file's existing Swagger 2.0 refusals do.

pnpm --filter @objectstack/connector-openapi test && pnpm --filter @objectstack/connector-openapi typecheck
 Test Files  4 passed (4)
      Tests  50 passed (50)
check:test-typecheck: OK — @objectstack/connector-openapi's test layer compiles under packages/connectors/connector-openapi/tsconfig.test.json; 1 file(s) / 5 error(s) / 1 pinned signature(s) held in test-typecheck-debt.json
os-verify-lock: VERDICT command-exit 0

Acceptance notes

• The card's acceptance line for item 1 (include: ['listCustomers'] exposes exactly that action; include: ['nope'] refuses at materialization with the operation name in the message) is pinned at both the factory and the real-boot layer.
• A key the generator de-duplicates (two operations sharing one operationId, which yields x and x_2) is admitted by its base key, which admits both. The _2 spelling is not an include entry. Noted, not filed: no producer measured.
• skills/objectstack-automation/references/integration-recipes.md (line 63, "The openapi provider has no include key — the trimmed document is the allowlist.") and the integrations-declared.json eval's expected outputs become false when this lands. skills/** is Tier H and outside this PR, so the follow-up is owed and named in the Skills-docs: line.
• File surface: openapi-connector.ts sits outside the claim's declared surface. It was edited because the provider needs the generator's own key derivation. The other way was a second copy of the slug, i.e. two spellings of one key. The edit is the helper plus its one call site.

Verification

Not run locally, CI-owned: test:repo, the repo-wide lint, and the full families of the required checks. connector-mcp is untouched, so it owes no test here. There is no dogfood run: the title has no ! and Clause-② carries no (narrowing) arm.

Generated by Claude Code