Skip to content

docs(cli): name the admin-owned skip class in os meta resync's docblock - #9183

Merged
os-project-manager merged 1 commit into
mainfrom
claude/issue-9130-resync-admin-skip-docblock
Aug 17, 2026
Merged

docs(cli): name the admin-owned skip class in os meta resync's docblock#9183
os-project-manager merged 1 commit into
mainfrom
claude/issue-9130-resync-admin-skip-docblock

Conversation

@os-project-manager

Copy link
Copy Markdown
Collaborator

Fixes #9130

What

os meta resync's docblock (packages/cli/src/commands/meta/resync.ts, ~line 51) enumerated the rows the command leaves alone as 'user' and 'package', but never named 'admin' — the canonical value of the tri-state managed_by vocabulary (platform / package / admin).

Re-verified the vocabulary on current origin/main before writing, per the triage comment's instruction not to copy it from the card:

'user' is kept in the enumeration (not dropped) since the boot normalizer's existence implies stored legacy rows can still exist; this docblock describes stored data, not just the CLI's own live-boot behavior.

Change

Docblock-only, packages/cli/src/commands/meta/resync.ts:

No runtime behavior change — the command's actual resync/skip logic is untouched.

Out of scope (per triage)

The triage comment on #9130 explicitly deferred whether the CLI's runtime output (the interactive confirm-prompt text and the post-run skip-count message) should also explain a nonzero skip count, with a named restart condition (an operator actually asking). Not built here. While implementing I did not hit a case where the docblock's honesty depended on touching that output, so no scope-conflict to report.

Tests

  • pnpm --filter '@objectstack/cli^...' build (dependency closure) — green.
  • pnpm --filter '@objectstack/cli' typecheck — green (tsc --noEmit, no errors), re-run at final head 58f2faf4d.
  • pnpm --filter '@objectstack/cli' test -- --maxWorkers=2 — 122 test files / 1358 tests passed.
  • node scripts/check-cross-package-test-inputs.mjs (named by node scripts/pm/dispatch-gates.mjs packages/cli/src/commands/meta/resync.ts, both lint.yml/ci.yml copies of this family) — green, re-run at final head.
  • node scripts/check-nul-bytes.mjs — green, re-run at final head.

All re-run at the final commit 58f2faf4d (matches git rev-parse --short HEAD).

Changeset

None — docblock-only change to a CLI source file, releases nothing observable. skip-changeset label applied.

Generated by Claude Code


Generated by Claude Code

Fixes #9130

The `os meta resync` docblock enumerated the rows the command leaves
alone as `'user'` and `'package'`, but never named `'admin'` -- the
canonical tri-state value (`normalizeManagedByVocab` heals the legacy
`'user'` spelling to `'admin'`) that, after #8692's forward-only
ruling (PR #9129), accounts for every skip on every install created
before that ruling. Add `'admin'` to the enumeration and explain the
pre-#8692 legacy case so an operator reading the command's own
documentation can account for a permanent `resynced 0 / skipped N`.
Also drops the "intentional override" framing for the admin-owned
case, which is not always true (bootstrap-platform-admin.ts already
made this correction for its own log message under the same ruling).

Docblock-only change; no runtime behavior changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

19 hand-written doc(s) reference the affected code — list omitted above 15 rows. Re-derive: node scripts/docs-audit/affected-docs.mjs --json origin/main.

3 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

@os-project-manager os-project-manager added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Aug 16, 2026 — with Claude
@os-project-manager
os-project-manager marked this pull request as ready for review August 16, 2026 23:53
@os-project-manager
os-project-manager added this pull request to the merge queue Aug 16, 2026
Merged via the queue into main with commit 5090047 Aug 17, 2026
29 checks passed
@os-project-manager
os-project-manager deleted the claude/issue-9130-resync-admin-skip-docblock branch August 17, 2026 00:04
os-project-manager pushed a commit that referenced this pull request Aug 17, 2026
…op look

resynced 0 / skipped N is a permanent, by-design outcome on any install
created before #8692's forward-only ruling — the platform's own seeder
wrote the 'admin' stamp those rows still carry, and #8692 deliberately
never migrates it. The docblock half already explains this in source
(#9130 / PR #9183); this adds the runtime-output half so the operator
sees the explanation at the terminal.

- New resyncSkipExplanationLine(resyncSkipped) — a pure, exported helper
  printed as a dim follow-up line under the existing skip-count warning,
  firing on the same resyncSkipped > 0 condition the summary itself uses.
- Names both provenance spellings ('admin' / legacy 'user') and keeps the
  neutral framing PR #9183 established: an admin-owned skip is NOT always
  a deliberate override, while a package-owned skip always is.
- Corrects the skip-count summary's own wording, which read "(admin- or
  package-owned override)" — reintroducing the exact "override" framing
  already removed from the per-row log line for the admin-owned case.
- New unit test pins the trigger condition, the null case, and the
  no-false-"intentional override" framing.

Fixes #9184

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants