Skip to content

Commit 503f3dd

Browse files
authored
Merge pull request #49 from versionone/claude/admiring-ride-vsq4sa
Plans up to date; plan 004 brief for agility-rooms
2 parents cb5837b + a7d48de commit 503f3dd

4 files changed

Lines changed: 163 additions & 29 deletions

File tree

‎plans/001-sdk-adoption-campaign.md‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -224,10 +224,11 @@ moves.
224224
snapshot, reverseOf — a receipt as data; writing it to disk stays in
225225
gh-v1). gh-v1's tests for these move with them, rewritten against recorded
226226
responses.
227-
- **A6 CI and packaging** — GitHub Actions running `npm run verify` on PRs;
228-
publish prereleases (`0.x`, `next` tag) to GitHub Packages under the
229-
`@versionone` scope (or npmjs — decision below). Until then consumers pin a
230-
git SHA or a tarball from `npm pack`.
227+
- **A6 CI and packaging** — done: CI runs `npm run verify` on Linux (Node
228+
20/22/24) and Windows (Node 24); `@versionone/agility-sdk` is on npmjs
229+
(`1.0.0-alpha.0`, `alpha` dist-tag); `publish.yml` publishes later
230+
versions from a `v*` tag through npm trusted publishing, gated by the
231+
GitHub environment `npm` (an approval). Consumers install from npmjs.
231232
- **A7 Attachments and embedded images** — gap 5's `attachment`/
232233
`EmbeddedImage`, as part of the asset-update abstraction, not a side
233234
channel. Two consumers to serve: gh-v1's `gh v1 attach` (list, get, add,
@@ -361,13 +362,17 @@ Strangler, starting below the call sites so nothing user-visible moves:
361362
delegates to rooms' current axios instance (keeps the SSO refresh
362363
interceptor and snackbar). Point `bulkApiService.tsx` at
363364
`client.assets.*`. Rows arrive translated, so `getApiResults`' `IsReadOnly`
364-
patch goes. This is the whole first PR. Needs A2 for parity of the
365-
command-failure snackbar.
365+
patch goes. This is the whole first PR. (A2 is done:
366+
`CommandFailureError` carries what the snackbar needs.)
366367
- **D2 Domain by domain.** Start with `src/domains/ai` (it already has
367-
adapters and architecture tests), then retire string-boolean decodes per
368-
feature (48 today). Jest + Playwright gate each PR.
368+
adapters, architecture tests, and the injected `IHttpClient` /
369+
`FakeHttpClient` seam), then retire string-boolean decodes per feature
370+
(46 at the 2026-11-07 survey). Attachments and embedded images move to
371+
`client.attachments` / `client.embeddedImages` (A7). Jest + Playwright
372+
gate each PR.
369373
- **D3 Native transport.** Swap the axios-backed Transport for
370-
`createFetchTransport` with `credentials` + `onUnauthorized` (needs A1).
374+
`createFetchTransport` with `credentials` + `onUnauthorized` (A1 is
375+
done).
371376
- **D4 Schema convergence.** Evaluate replacing parts of
372377
`src/metaAssetStore/` field knowledge with the SDK `schema` service.
373378

@@ -419,11 +424,11 @@ ESM" here means finishing the edges:
419424
captured from the local dev instance (spec 000 §2a: fakes send what the
420425
server sends — api/asset spells `"True"`, not `true`).
421426

422-
**agility-rooms** (slow; no handoff yet)
427+
**agility-rooms** (slow; brief: `plans/004-adopt-sdk-agility-rooms.md`)
423428

424-
- **R1** Narrow the axios surface: route the 67 axios importers through
425-
`utils/bulkApiService.tsx` and a small set of helpers, so D1 swaps one
426-
module. Start when Track A2 lands; write the handoff then.
429+
- **R1** Narrow the axios surface: route the axios importers (88 production
430+
files at the 2026-11-07 survey) through `utils/bulkApiService.tsx` and a
431+
small set of helpers, so D1 swaps one module.
427432

428433
## Operating model for the campaign
429434

@@ -487,4 +492,4 @@ ESM" here means finishing the edges:
487492
- [x] C2 gh-v1 rows translated through the schema; `isTrue`/`oidOf` gone — versionone/gh-v1#36
488493
- [x] C3 gh-v1 resolve and batch on `client.resolve`/`client.batch` — versionone/gh-v1#37 (with the SDK fixes from #43)
489494
- [x] C4 gh-v1 `gh v1 attach` on `client.attachments`, `blob` removed — versionone/gh-v1#38 (re-vendored at `d51fb16`; small files now upload inline); `raw` stays CLI-local
490-
- [ ] D1–D4 agility-rooms
495+
- [ ] D1–D4 agility-rooms — brief: `plans/004-adopt-sdk-agility-rooms.md` (first: decide rooms' rest-1 writes and Copy)

‎plans/002-adopt-sdk-gh-v1.md‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
# Plan 002: gh-v1 adopts `@versionone/agility-sdk` (Track C)
22

3-
Brief for a session on `versionone/gh-v1`. Start once the SDK PR that adds
4-
this file has merged into `proposed_type_script_api_version`. Source plan:
3+
Brief for a session on `versionone/gh-v1`. Source plan:
54
`plans/001-sdk-adoption-campaign.md`, Track C.
65

6+
**Status (2026-11-07): done.** C1–C4 merged (versionone/gh-v1#33, #35–#38);
7+
gh-v1 then moved to the renamed, published package (#39, #40). gh-v1
8+
reaches Agility only through the vendored SDK, apart from the `gh v1 api`
9+
passthrough. The rest of this brief is the record of how.
10+
711
## Goal
812

913
gh-v1 talks to Agility only through `@versionone/agility-sdk`. CLI behaviour and
@@ -33,15 +37,18 @@ runtime dependency, but its code ships inside the repo:
3337

3438
- `vendor/versionone-sdk/` holds the SDK's ESM build (`index.js`, which
3539
imports nothing) and types (`index.d.ts`), plus `SOURCE.json` naming
36-
the commit they came from. `lib/api.js` imports from there.
37-
- `package.json` lists `@versionone/agility-sdk` under `devDependencies`, pinned
38-
to a full commit, so the lockfile records exactly what was vendored.
40+
the version they came from and each file's SHA-256. `lib/api.js`
41+
imports from there.
42+
- `package.json` lists `@versionone/agility-sdk` under `devDependencies`,
43+
pinned to an exact published version (`1.0.0-alpha.0` today; before the
44+
first publish it was a git commit), so the lockfile records exactly what
45+
was vendored.
3946
- To move the pin: change it in `package.json`, then
4047
`npm install && npm run vendor:sdk`, and commit the copy.
4148
`test/vendor.test.js` fails if the copy, `SOURCE.json` and the pin
4249
disagree.
43-
- Publishing the SDK to a registry (plan 001, *Decisions needed*) changes
44-
only where the pin points; the copy stays.
50+
- The SDK is on npmjs (plan 001, A6); that changed only where the pin
51+
points. The copy stays, because gh never runs npm.
4552

4653
## Steps, one PR each, on branch `sdk-adoption`
4754

‎plans/003-adopt-sdk-k6i-agility-slack-bot.md‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
# Plan 003: k6i-agility-slack-bot adopts `@versionone/agility-sdk` (Track B)
22

3-
Brief for a session on `digital-ai/k6i-agility-slack-bot`. Start once the
4-
SDK PR that adds this file has merged into `proposed_type_script_api_version`.
5-
Source plan: `plans/001-sdk-adoption-campaign.md`, Track B. Work on
6-
`bolt-migration` (branch `sdk-adoption` from it), never `main`.
3+
Brief for a session on `digital-ai/k6i-agility-slack-bot`. Source plan:
4+
`plans/001-sdk-adoption-campaign.md`, Track B. Work on `bolt-migration`,
5+
never `main`.
6+
7+
**Status (2026-11-07): done.** S1–S4 (digital-ai/k6i-agility-slack-bot#21–#24)
8+
and B1–B4 (#29, #30, #32, #34) merged; the bot installs
9+
`@versionone/agility-sdk@1.0.0-alpha.0` from npmjs (#41). Its SDK requests
10+
(group rows, a shared TypeCache, a registry release, number roots, Template)
11+
are all answered. The rest of this brief is the record of how.
712

813
## Goal
914

@@ -20,15 +25,15 @@ hand-decoding and rest-1 write path go.
2025
`findAssets` (rest-1 `find`/`findin`, `page` up to 200),
2126
`fetchLocalizations` (loc-2), and `queryFor*` helpers built on
2227
`lib/queries.js`. `test/v1-service.test.js` stubs global `fetch`.
23-
- **S1–S4 are not done yet**: `jsconfig.json` still says `commonJS`/`es6`;
28+
- **S1–S4 were not done yet** (then; all merged since): `jsconfig.json` still says `commonJS`/`es6`;
2429
query bodies have no explicit page; `axios`, `botkit*`, `botbuilder-*` are
2530
still dependencies and `lib/v1api.js` still exists. These come first.
2631

2732
## Dependency
2833

29-
No registry package yet. Pin a commit:
30-
`"@versionone/agility-sdk": "github:versionone/VersionOne.SDK.JavaScript#<merge sha>"`.
31-
The SDK's `prepare` script builds `dist` on install. The bot is ESM, so
34+
`"@versionone/agility-sdk": "1.0.0-alpha.0"` from npmjs, an exact pin
35+
(until the first publish it was a git commit, which needed `git` in the
36+
image and wrote a `git+ssh` URL into the lockfile). The bot is ESM, so
3237
`import { AgilityApiClient } from "@versionone/agility-sdk"`.
3338

3439
## Steps, one PR each
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Plan 004: agility-rooms adopts `@versionone/agility-sdk` (Track D)
2+
3+
Brief for a session on `digital-ai/agility-rooms`, a React/Vite SPA that
4+
runs inside Agility (same-origin, cookie auth). Source plan:
5+
`plans/001-sdk-adoption-campaign.md`, Track D. gh-v1 (plan 002) and the
6+
slack bot (plan 003) have finished their adoptions; this is the last
7+
consumer, and the slowest: a strangler that starts below the call sites so
8+
nothing user-visible moves.
9+
10+
## Goal
11+
12+
Rooms talks to the Agility data endpoints (api/asset, query.v1, rest-1,
13+
meta.v1, loc-2, attachments, embedded images) only through
14+
`@versionone/agility-sdk`. Rows arrive translated, so its hand-decoding
15+
goes. UI behaviour stays the same. Rooms' own routes (`api/*` reports,
16+
tags, watch, rooms2config, LLM; `*.mvc` pages) are out of scope unless the
17+
SDK already covers them.
18+
19+
## Where things stand (surveyed 2026-11-07 at `main` `0874590`, read-only)
20+
21+
Full survey: plan 001, *What the consumers do today*, the agility-rooms
22+
re-survey paragraph. In short:
23+
24+
- **HTTP.** `src/utils/axios.tsx` builds the default instance (`baseURL`
25+
the app root, `X-Requested-With`, cookie auth; on 401/403 an SSO popup
26+
via `Account.mvc/Login`, then axios-auth-refresh replays). A response
27+
interceptor turns api/asset `commandFailures` into a localized snackbar
28+
and throws — but only when the URL is exactly `/api/asset`; 9 calls
29+
written `api/asset` bypass it. `getAxiosInstance(...)` variants, a bare
30+
`meta` instance and a plain `axios.create` in `src/navigation/routes.tsx`
31+
skip some interceptors. 88 production files import axios.
32+
- **Endpoints.** api/asset (111 call sites in 57 files), query.v1 (16),
33+
rest-1 reads (4) **and writes** (5 `Data/{T}/{id}` attribute posts, 2
34+
`?op=Copy`, plus `New/{T}?ctx=` templates), meta.v1, loc-2, `loc.v1`,
35+
`config.v1`, attachments (`MultiValueRelations/Attachments.tsx`: inline
36+
Base64 create, `attachment.img` download), embedded images
37+
(`useImageUpload.ts` → `EmbeddedImage.mvc/Upload`).
38+
- **Reads.** Positional `results[n]` with index constants
39+
(`metaAssetStore/constants.ts`); some board and `ID=$Oids` reads are
40+
unbounded (the SDK refuses an unpaged query).
41+
- **Decoding.** 46 `"True"`/`"False"` comparisons; `NULL_OID` used 118
42+
times; `massageApiAssetResponseObject` unwraps single relations. meta.v1
43+
is loaded by `store/metaDefinition/useMetaDefinitionStore.ts`.
44+
- **Tests.** Jest (222 files, module mocks, no MSW); the AI domain's
45+
injected `IHttpClient` / `FakeHttpClient` is the cleanest seam.
46+
Playwright (79 specs) runs against a live server.
47+
48+
## What the SDK offers rooms (1.0.0-alpha.0)
49+
50+
- `AgilityApiClient` with a pluggable `Transport` (D1 wraps rooms' axios),
51+
or `createFetchTransport` with `credentials: "same-origin"` and
52+
`onUnauthorized` (resend an idempotent request after re-auth; a write is
53+
never resent), `signal` / `client.withSignal` for cancellation.
54+
- `client.assets.query/queries/send` (rows translated through the schema;
55+
a failed query throws; `CommandFailureError` carries each failure by
56+
index for the snackbar), `client.queryV1`, `client.data` (rest-1 reads),
57+
`client.localize`, `client.schema` / `TypeCache`, `client.resolve`,
58+
`client.batch` (guarded sends, receipts, undo).
59+
- `client.attachments` (list/page/info/get/add/put/remove/url; inline
60+
Base64 up to 1 MB as rooms does, two-step above) and
61+
`client.embeddedImages` (upload/url/normalize).
62+
- Browser-safe: no `node:` imports, no Buffer. Install
63+
`npm install @versionone/agility-sdk@1.0.0-alpha.0` (an exact pin; it is
64+
an alpha).
65+
66+
## First: a decision for Jim
67+
68+
Rooms writes through rest-1 (attribute posts with `act`, `?op=Copy`) and
69+
reads `New/{T}` templates, which plan 001 assumed no consumer needed.
70+
Before D1, find out (live, on v1sdktesting) whether api/asset covers each:
71+
an update for the attribute posts (likely), an `execute: "Copy"` or similar
72+
for Copy, and whether `New/{T}` has an api/asset equivalent. Report what you
73+
find to the SDK session and Jim, with a recommendation: move them to
74+
api/asset, or have the SDK grow a narrow rest-1 write path.
75+
76+
## Steps, one PR each against `main`, from its own branch
77+
78+
1. **R1 Narrow the axios surface.** Route the axios importers through
79+
`utils/bulkApiService.tsx` and a small set of helpers, so D1 swaps one
80+
module. Fix the `api/asset` vs `/api/asset` interceptor gap on the way.
81+
2. **D1 SDK under the existing axios.** A `Transport` that delegates to
82+
rooms' axios instance (keeps the SSO refresh and the snackbar); point
83+
`bulkApiService.tsx` at `client.assets.*`. Rows arrive translated, so
84+
`getApiResults`' `IsReadOnly` patch goes.
85+
3. **D2 Domain by domain.** Start with `src/domains/ai`, then retire the
86+
string-boolean and `NULL_OID` decodes per feature; attachments onto
87+
`client.attachments`, embedded images onto `client.embeddedImages`;
88+
positional `results[n]` onto named or `queries` results; page every read.
89+
4. **D3 Native transport.** Replace the axios-backed Transport with
90+
`createFetchTransport({ credentials: "same-origin", onUnauthorized })`,
91+
the SSO popup as the hook.
92+
5. **D4 Schema convergence.** Evaluate replacing parts of
93+
`src/metaAssetStore/` and `useMetaDefinitionStore` with the SDK's
94+
`schema` / `TypeCache`.
95+
96+
## Rules
97+
98+
- Jest and the existing Playwright gates pass on every PR. No behaviour or
99+
UI change unless a step says so.
100+
- Live Agility calls go only to `https://www14.v1host.com/v1sdktesting`
101+
(`V1_URL`, token in `V1_ACCESS_TOKEN`; Node's fetch needs
102+
`NODE_USE_ENV_PROXY=1`). Writes are allowed there and nowhere else: name
103+
assets `sdk-integration …` and delete them by exact OID. Every query is
104+
small and explicitly paged. Point Playwright at nothing else.
105+
- An EmbeddedImage cannot be deleted; upload one only when a test needs it.
106+
- If the SDK lacks something, don't work around it in rooms: tell the SDK
107+
session (`session_016NSWj9gL1oCubj5e2anVkb`, `send_message`) with what
108+
you need and why. Don't request reviewers; Jim picks.
109+
110+
## Done when
111+
112+
- Rooms reaches the data endpoints only through the SDK; no file outside
113+
the transport adapter imports axios for them.
114+
- No `"True"`/`"False"` comparisons or `NULL_OID` checks on SDK rows remain.
115+
- Attachments and embedded images go through the SDK.
116+
- Plan 001's checklist line `D1–D4 agility-rooms` is ticked, with PR links
117+
(tell the SDK session as each merges).

0 commit comments

Comments
 (0)