Sync pipeline: open blockers & process gaps (tracker)

[IgorShevchik]

Purpose

Single durable record of the blockers / process gaps for the nuxt/ui → b24ui per-commit live-sync, surfaced while running the manual ports (#68–#72, and ongoing). Some items already have dedicated issues — linked below; this issue is the umbrella status view so the picture survives context resets.

Context: the manual per-commit cadence is proven (5 upstream commits ported as gated PRs: #68 → #72). These items are what stands between "manual cadence" and "trusted automation".

---

1. Ledger drift — ✅ being closed

.sync/nuxt-ui.json was still cursor: null, sync_enabled: false, processed: {}, with only one .sync/log/ entry, so the manual progress of #68–#72 was not recorded.

Status: resolved as part of the efd7b8ec port PR — cursor set to the last ported upstream SHA, processed backfilled for #68–#72, and the ledger is now maintained per port going forward (one processed entry + a .sync/log/<sha>.md per commit). No separate reconciliation PR needed.

2. Automation not live — blocked on owner action

PR #67 (Phase 1 porter workflow) is not merged: it needs the repo secret CLAUDE_CODE_OAUTH_TOKEN (owner action) plus a live trial run before we trust it. Until then every port is hand-driven.
→ tracked by PR #67.

3. Snapshot regeneration footgun — P3

A targeted vitest run -u <files> intermittently leaves the first component(s) rendering against a stale compiled theme, producing a false-green -u. Mitigation today: always run the full pnpm exec vitest run -u then verify with pnpm exec vitest run (no -u). Worth hardening (cache: false under CI, or a test:update script).
→ tracked by #74.

4. main branch protection + workflow security baseline — owner action

main protection (require PR + the ci check, include admins, CODEOWNERS) and per-workflow least-privilege permissions: / action SHA-pinning. The repo-settings part cannot be done in code and gates trusting the automated sync (Phase 3).
→ tracked by #64 (esp. §4).

5. Environment ephemerality — process note

The remote-execution container wipes the upstream (nuxt/ui) git remote and /tmp between sessions. Each resume must re-add upstream and git fetch nuxt/ui v4 before the queue can be recomputed.

Mitigation (no code fix needed): standard resume preamble —

git remote add upstream https://github.com/nuxt/ui.git 2>/dev/null
git fetch --no-tags upstream v4
# next commit to port = oldest of:  git log --reverse --oneline <cursor>..upstream/v4

where <cursor> is .sync/nuxt-ui.json → cursor. Could be folded into a SessionStart hook later.

---

Priority

• [ERR_PACKAGE_PATH_NOT_EXPORTED] Не удаётся запустить проект с @tailwindcss/vite #2, UI Component for Embedding Bitrix24 Open Line Widget with Custom Data #4 — P1 (owner actions; gate automation).
• installation-nuxt-app #3 — P3 (DX).
• Add Search Functionality to Select Component #1 — done.
• Custom color for Select item #5 — process note (optional hook later).

[IgorShevchik]

6. Prop coverage — a gap the test suite cannot see

Adding an item to this tracker rather than a new issue, because it is the same failure mode item 2 is about: a port that arrives incomplete and passes every gate.

The gap

A prop can exist in the types — so typecheck passes — without being rendered. Snapshots do not catch it either, because nothing in the matrix passes the prop, so no snapshot changes. It then flows into the docs, which are generated from the types. The user reads the page, writes <B24Input no-border />, and nothing happens.

Measured on main while closing #63 (see #529):

Declared props across src/runtime/components/*.vue	1140
Never mentioned in their own spec	242 (21 %)

242 is a floor, not a ceiling — "mentioned anywhere in the spec file" counted as covered, and mentioning is not exercising.

Why it matters here specifically

The uncovered props are disproportionately ours, not upstream's. Checked against nuxt/ui@v4 source:

                Input.vue  Select.vue
noPadding           0          0
noBorder            0          0
underline           0          0
tag                 0          0
tagColor            0          0

An upstream prop arrives with an upstream test attached. A Bitrix24-only prop arrives with nothing, and no future sync will ever bring one. So the sync pipeline's safety net is thinnest exactly where the code is most ours.

What it already caught

Running this once on five components turned up three props that are typed, documented, forwarded to the theme and render nothing — Button.depth, Button.activeDepth, Textarea.fixed. All three are now @deprecated in #529. Button.depth had in fact been noticed before and tagged @depricate, misspelled, so no tooling ever surfaced it.

Deliberately no standing checker

No prop-coverage utility was added, and that is the decision, not an omission: a permanent checker is machinery to maintain forever and a further divergence from upstream — the direction settled in #87. The scan is a one-off script, reproduced below so it does not have to be reinvented.

// node this from the repo root
import fs from 'node:fs'
import path from 'node:path'

const dir = 'src/runtime/components'
let totalProps = 0, totalUncovered = 0
const rows = []

for (const file of fs.readdirSync(dir).filter(f => f.endsWith('.vue'))) {
  const name = path.basename(file, '.vue')
  const spec = `test/components/${name}.spec.ts`
  if (!fs.existsSync(spec)) continue

  const src = fs.readFileSync(path.join(dir, file), 'utf8')
  const m = src.match(/export interface \w+Props[^{]*\{([\s\S]*?)\n\}/)
  if (!m) continue

  const props = [...m[1].matchAll(/^\s{2}(\w+)\??\s*:/gm)].map(x => x[1])
  if (!props.length) continue

  const specSrc = fs.readFileSync(spec, 'utf8')
  const uncovered = props.filter(p => !new RegExp('\\b' + p + '\\b').test(specSrc))
  totalProps += props.length
  totalUncovered += uncovered.length
  if (uncovered.length) rows.push([name, props.length, uncovered])
}

rows.sort((a, b) => b[2].length - a[2].length)
console.log(`${totalProps} props, ${totalUncovered} uncovered (${(100 * totalUncovered / totalProps).toFixed(1)}%)`)
for (const [name, count, uncovered] of rows.slice(0, 15)) {
  console.log(name.padEnd(22), String(count).padStart(3), 'props ->', uncovered.join(', '))
}

It only reads the first export interface *Props block, so inherited props (UseComponentIconsProps, LinkProps) are not counted — another reason the figure is a floor.

A prop that turns up uncovered is not automatically a bug. Mount the component with and without it and diff the HTML first: autofocus, autofocusDelay, autoresizeDelay, maxrows and loadingAuto legitimately render nothing. Only pin the ones that change markup — a snapshot of a no-op reads as certifying it.

When to re-run

Not on a schedule and not in CI. Worth a pass when a release carries several new Bitrix24-only props, and worth it as part of the Phase 3 gate (item 2) before an automated port is trusted — an incomplete port looks exactly like this.

Priority

P3. It is a slow-moving gap: it only widens when new Bitrix24-only props are added.

---

Generated by Claude Code

[IgorShevchik]

Closing. Re-measured all six items against main today rather than reading the body, and the tracker no longer describes the project.

	item	measured today
1	Ledger drift	done. cursor set, 294 processed entries, 294 files in .sync/log/
2	Automation not live	obsolete — see below
3	Snapshot regeneration footgun	done. #74 closed 2026-08-26 via #498
4	Branch protection + workflow security	done except the repository setting, which moved to #97 with #64
5	Environment ephemerality	still true, but a process note
6	Prop coverage	improved: 242 (21 %) → 192 (16.8 %)

Item 2 is not blocked — it was cancelled

The body says PR #67 needs the CLAUDE_CODE_OAUTH_TOKEN secret and a trial run, an owner action gating everything else.

PR #67 was closed unmerged on 2026-08-12, and the automation was removed on purpose the same day. .sync/PORTING.md's changelog carries the decision: the sync is manual, .sync/PLAN.md and .sync/RUNBOOK.md were deleted, and sync_enabled was dropped from the ledger because "a kill-switch for a dispatcher that will not exist reads as the sync is off to anyone who finds it".

No secret is needed. Phase 2 and Phase 3 are not deferred, they are not happening, and the twelve-plus ports since have all run by hand. Worth stating plainly because this line survived three months and was still being quoted as a live blocker — including by me, earlier today, before checking the PR's state instead of the issue's description of it.

Item 4, for the record

#64 is closed and its two remainders live on #97: CODEOWNERS and branch protection on main. §1 (least-privilege permissions: in all five workflows), §2 (every action pinned by SHA, enforced by .github/scripts/assert-actions-pinned.py in CI) and §3 (no pull_request_target) all landed.

What actually survives

Item 5 — the container drops the upstream remote between sessions; confirmed just now, only origin is configured. Three commands of preamble, not a blocker. Folding it into a SessionStart hook is still the obvious home if it ever becomes annoying.

Item 6 — the prop-coverage comment above stands on its own: the script, the decision not to add a standing checker, and when to re-run it. The 21 % → 16.8 % move came from #519, #521 and #522.

Neither is a blocker, and neither needs a tracker to hold it. A status view that reports four dead items as live is worse than no status view — it sends the next reader after work that was cancelled a month ago.

---

Generated by Claude Code