Skip to content

feat(config-manager): agent files are written in the plain shape (record 0054) - #1358

Merged
vscheuber merged 5 commits into
mainfrom
feat/agent-files-plain-shape
Nov 16, 2026
Merged

vscheuber merged 5 commits into
mainfrom
feat/agent-files-plain-shape

Conversation

@vscheuber

Copy link
Copy Markdown
Contributor

Part of #1355 (the live round trip on a tenant stays on the issue, and so does the question about groups below).

Summary

Implements rule 6 of record 0054: every writer of agent files writes a property that is set on the object as its plain value, and leaves out a property that is unset, inherited or null. The committed example files are 4331 lines wrapped and 1748 plain. Push is not changed.

  • One function, toPlainShape in src/ops/AgentFileShape.ts (no imports, so that the generic kind of the deprecated src/configManagerOps/ layer and the tests that mock the library can use it), re-exported from src/ops/ConfigManagerAgentKind.ts, which is where the record puts it. It does not change its input, recognises a wrapper only by its exact shape (an object with only inherited and value members and a boolean inherited), recurses into a value it keeps, and counts what it left out.
  • Every writer uses it, before placeholders are escaped and overrides merged: the shared pull (oauth-issuers, oauth-cimd-profiles, oauth-software-publishers), the generic pull oauth2-agents, and the OAuth2 client file of pull applications. git grep "realm-config/agents" found no other writer; config-manager migrate applications only finds and removes files.
  • CIMD profiles go back to one list request per realm and no request by id: AM's list answer has null for what is not set, and after the function the list item equals the read by id (checked on the library's recordings of two real profiles, one with an unusual id; frodo-lib#1113 is closed as not needed). Record 0054 speaks of the single read; for this kind the list item gives the identical file.
  • Overrides are read through the same function, leniently (a bare { "value": ... } counts as a wrapper and a null that a person wrote is kept), so an overrides file written for the wrapped files of the first 5.0.0 prereleases still works. The help examples now show plain values.
  • Verbose output says once per run how many properties were left out of how many objects written; the application kind says it per client.
  • MIGRATION.md has one entry for the plain shape (a tree written before changes once on the next pull) and the three sentences of config-manager: oauth2-agents leaves CIMD profiles and trusted JWT issuers to their own kinds #1348, fix: config-manager pull oauth-cimd-profiles writes the wrapped shape like the other agent kinds #1353 and feat(config-manager): a kind of its own for software publishers (oauth-software-publishers) #1354 that said the files stay wrapped are gone.

Commits

  1. feat: one function writes an agent object in the plain shape: the function and its 23 tests.
  2. feat: config-manager writes agent files in the plain shape: the four writers, the CIMD list read, the tests that changed with them, and the three e2e snapshot files.
  3. docs: the help examples and MIGRATION say that agent files are plain.
  4. refactor: one condition ... and 5. test: the failure contract of pull oauth2-agents ... (found by the whole suite: that test spies every import of the module under test except pure helpers).

Decisions taken (maintainer: change on review)

  • A group whose members were all left out stays as {} (see the question below). Reversible: one line in the function.
  • A null element of an array stays (a position means something); a wrapper element is left out.
  • null counts as unset for a pulled object and for the generic and kind pulls, but not in an overrides entry.
  • The message is one verbose line per kind run (per pull oauth2-agents run), not one per object.
  • The committed push fixtures under test/e2e/exports/fr-config-manager/ stay wrapped on purpose: they are inputs that show a push accepts both shapes.

Verification

  • npm run check: exit 0, 0 errors, the same 8 warnings as main. npx tsc --noEmit: exit 0. npm run test:guidance: 3 suites, 693 tests.
  • Whole suite on the final head, under the suite lock: 1096 suites passed, 10 skipped, 1 failed; 10794 tests passed, 149 skipped, 1 failed; 10279 snapshots passed. The one failure is ConnectionPageRealmRow.pty.test.js (a terminal test of the connection page, nothing to do with agent files), which passed alone on this tree (18 of 18); the same test failed under machine load for another branch's run. The first whole run, before the last commit, had found 2 failures in BulkConfigManagerRealmConfigFailures.test.js (it spies every import of the module under test except pure helpers); commit 5 fixes that, and its first run is the proof that the exception is needed.
  • The e2e snapshots: 46 entries changed in config-manager-pull-oauth2-agents, config-manager-pull-all and config-manager-pull-trusted-jwt-issuers, 1085 did not. I did not update them blindly: a script written for this (independent of the TypeScript function) checks that each changed entry equals the old entry with the wrappers removed and nothing else, and it reports 46 explained, 0 not explained; it fails on a copy that I changed by hand. No recording was edited.
  • Mutations of my own (17), each turned a test red and was reverted: the function keeps an unset or an inherited wrapper; unwraps an object that only has a member named inherited; changes its input; reads a pulled { value } as a wrapper; drops the null that a person wrote in overrides, or a null array element; does not count a null; the shared pull, the generic pull or the application kind forgets the function; overrides not read as values (shared and generic); push changes the shape of a file; the CIMD kind reads by id again; the verbose count not said, or taken for objects that were not written.
  • Not run: a tenant. Nothing was recorded.

What the maintainer must see

  • Question for the live round trip: a group whose members were all left out is written as {} and not removed. Whether AM's replace-style write needs the group object, or accepts it missing, is not proven without a tenant. The round trip (pull, push to a clean realm, pull again, no diff) for each of the four kinds and one generic type, as config-manager: write agent files without the { inherited, value } wrapper (60 percent fewer lines in the committed samples) #1355 says, settles it.
  • inherited: true is not in any committed sample, so what a real agent-group member looks like is untested.
  • Whether null always means unset for the types of the generic route is known for CIMD profiles (recordings) and expected for the others.
  • A tree written with 5.0.0-27 or earlier shows one large diff on its first pull after this change.

🤖 Generated with Claude Code

trial and others added 5 commits November 16, 2026 09:55
A property that is set on the object becomes its plain value; an unset, an
inherited and a null property are left out; the input is not changed. The
single read and the list read of AM give the same result. Not used yet.

Refs #1355

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The shared agent-kind pull (issuers, CIMD profiles, software publishers), the
generic pull oauth2-agents and the OAuth2 client file of an application write a
property that is set as its value and leave out unset, inherited and null ones.
An overrides file written for the wrapped files still works. The CIMD kind goes
back to the one list request per realm. Push is not changed.

Refs #1355

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The override examples of the three kinds show plain values, the help says an
override in the wrapped form of the first 5.0.0 prereleases still works, and
MIGRATION.md has one entry for the plain shape instead of three sentences that
said the files stay wrapped.

Refs #1355

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…of a wrapper

Refs #1355

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…shape function

The test replaces every relative import of the module under test with a spy,
except pure helpers; the function that writes an agent in the plain shape is
one, and the generic pull needs its result. Found by the whole suite.

Refs #1355

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@vscheuber vscheuber added the no-auto-processing Concierge never touches this item; remove the label to hand it over label Nov 16, 2026
@vscheuber
vscheuber merged commit 846e809 into main Nov 16, 2026
15 checks passed
@vscheuber
vscheuber deleted the feat/agent-files-plain-shape branch November 16, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-auto-processing Concierge never touches this item; remove the label to hand it over

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant