Skip to content

Commit 4dc41e6

Browse files
docs(spec): name the producer of ConnectorConnectionState.redirectUri (#29795)
domain:spec#3 · os-support-ai · session_01WGufziW5z48GckZ3oXYCab <!-- claude-projects-attribution: {"github_login":"os-support-ai"} --> _Requested by **Yibo Wang** · [project thread](https://claude.ai/code/project/chan_01BVUyyPie8gHwoPM18iABwB?thread=cmsg_01BVUyyPie8gHwoPM18iABwB9wL8eUVeLSJG2twNqGtFc8)_ Fixes #29715 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`ConnectorConnectionState.redirectUri` 的 TSDoc 末句,原来说「先声明、服务还没答,任何回答都不带它」,现在改成点名生产者:`@objectstack/service-automation` 的 `AutomationServicePlugin.getConnectorConnection` 在能推导出地址时设上它,否则不带。 - 为什么改:连接读取已经会返回 `redirectUri`(服务端那半已合并),但 spec 文档还说「没有回答带它」。这段注释随 `dist` 发布,照着它写客户端的人或 AI 会为一个其实总会返回的键写兜底逻辑。 - 风险与回滚:只改注释文字和新增一条 changeset,没有任何类型、schema 或取值变化;回滚即还原本 PR。 - 先看:`packages/spec/src/contracts/automation-service.ts`(`redirectUri` 上方注释的最后一句)、`.changeset/29715-connector-redirect-uri-producer.md`(同版本 changelog 的更正段)。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/contracts/connector-connection-redirect-uri.pin.test.ts`,应见全部用例通过;`git grep "until the automation service sets" packages/spec` 应无命中。 - 需要你做的:无,席位落地。 ## What changes **Before** (`origin/main` `3eeb81d1`), `packages/spec/src/contracts/automation-service.ts` L1196–L1198, the end of the `ConnectorConnectionState.redirectUri` TSDoc: > Read-only: no connection request takes it. Declared ahead of the service that answers it: until the automation service sets it, no answer carries it. **After:** > Read-only: no connection request takes it. Its producer is `@objectstack/service-automation`: `AutomationServicePlugin.getConnectorConnection` (`packages/services/service-automation/src/plugin.ts`) sets it whenever the derivation has a base, and it is absent otherwise. Read against the producer on `origin/main`: `getConnectorConnection` (`plugin.ts` L4128–L4134) spreads `redirectUri` into the state only when `derivedConnectorOAuthRedirectUri()` returns a value, and that helper (L3861–L3866) answers `undefined` when neither the `connectorOAuthRedirectUri` option nor an `http(s)` `OS_AUTH_URL` / `OS_BASE_URL` base exists. The wording follows `approval-service.ts`, which names its producer the same way ("plugin-approvals' `rowFromRequest` serves it"). Other copies, searched with `git grep` over `packages/spec/**`: no other "declared ahead" or "no answer carries" prose about `redirectUri` (the other "declared ahead" hits are about unrelated keys). `content/docs/automation/connectors.mdx` already says the status read answers `redirectUri`. No reference page is generated from this docblock: `ConnectorConnectionState` is a TypeScript interface, not a Zod schema, so neither `json-schema/` nor `content/docs/references/` carries it. **Changeset route (the seat's call).** `.changeset/29574-connector-redirect-uri.md` is left untouched: the pending `.changeset/29463-connector-redirect-uri-read.md` in the same release already says the read now answers `redirectUri`. This PR's own changeset (`@objectstack/spec` patch) carries a "Supersedes, in the same release" paragraph saying the earlier "Declared ahead of the service" note no longer holds. ## Tests No test changes. The existing pin `connector-connection-redirect-uri.pin.test.ts` reads this docblock and asserts the callback path, the derivation chain and both absence conditions; the edit leaves those sentences unchanged and the pin stays green. All on head `3a5cdb13`, under `os-verify-lock`: <details><summary>spec build + local suite + typecheck, full build + spec repo suite</summary> - `pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec test && pnpm --filter @objectstack/spec typecheck`: `Test Files 803 passed (803)`, `Tests 23800 passed | 1 todo (23801)`; `check:test-typecheck: OK`; VERDICT command-exit 0. - `pnpm turbo run build --concurrency=2 && pnpm --filter @objectstack/spec test:repo`: `Tasks: 118 successful, 118 total`; `Test Files 89 passed (89)`, `Tests 1522 passed (1522)`; VERDICT command-exit 0. </details> No dogfood run: no `!` in the title and no `(narrowing)` arm. No ablation: no tested behaviour changes (prose only). ## Acceptance notes - `.changeset/29574-connector-redirect-uri.md` still says "until the automation service sets the key, no answer carries it". Left as the seat ruled; this PR's changeset supersedes it in the same release. ## Verification `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 72 families on `3a5cdb13` (2 paths vs merge base `3eeb81d1`). <details><summary>72 derived gates: 72 exit 0</summary> - First serial pass: 68 exit 0, 4 exit 3 (built-output prerequisites: `check-plugin-teardown-shape --self-test` needs its pinned fixture commit on the shallow clone; lint `check:doc-formula-expressions`, `check:dual-build-cjs-loads`, `check:lean-entry-closure` need a full build). - After `git fetch origin 621a487` and the full `turbo run build --concurrency=2` above, the 4 were rerun: all exit 0. - `dispatch-gates --ran`: "72 derived famil(ies) accounted for — 72 run, 0 NOT-MEASURED". </details> `check-changeset-no-major` with this body as the event: exit 0 (direction arm none declared, `Metadata-protocol: none`). `check-closing-keyword-parity --body`: the only closing target is `Fixes #29715`. CI families are read from this PR's check-runs. --- _Generated by [Claude Code](https://claude.ai/code/session_01WGufziW5z48GckZ3oXYCab)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01WGufziW5z48GckZ3oXYCab Co-authored-by: Claude <noreply@anthropic.com>
1 parent 0e4b0fa commit 4dc41e6

2 files changed

Lines changed: 16 additions & 3 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
docs(spec): the `ConnectorConnectionState.redirectUri` TSDoc names the service that sets it
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The `ConnectorConnectionState.redirectUri` docblock no longer says that no answer carries the key. It now names its producer: `AutomationServicePlugin.getConnectorConnection` in `@objectstack/service-automation` sets it whenever the redirect URI derivation has a base, and it is absent otherwise. Prose only: no type, schema or accepted value moves.
11+
12+
**Supersedes, in the same release.** The `@objectstack/spec` note "Declared ahead of the service" (until the automation service sets the key, no answer carries it) no longer holds: the `@objectstack/service-automation` note in this release says the connection read now answers `redirectUri`.

‎packages/spec/src/contracts/automation-service.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1193,9 +1193,10 @@ export interface ConnectorConnectionState {
11931193
* the deployment has no base to derive it from — a connect is then refused
11941194
* `503` — and ⛔ never guessed from the request's origin. Only an
11951195
* `authorization_code` instance has a connection, so no other grant ever
1196-
* carries it. Read-only: no connection request takes it. Declared ahead of
1197-
* the service that answers it: until the automation service sets it, no
1198-
* answer carries it.
1196+
* carries it. Read-only: no connection request takes it. Its producer is
1197+
* `@objectstack/service-automation`: `AutomationServicePlugin.getConnectorConnection`
1198+
* (`packages/services/service-automation/src/plugin.ts`) sets it whenever
1199+
* the derivation has a base, and it is absent otherwise.
11991200
*/
12001201
redirectUri?: string;
12011202
}

0 commit comments

Comments
 (0)