--- name: tetherto/sdk-bare-sdk-sync source: https://app.decimal.ai/s/tetherto-sdk-bare-sdk-sync@1/SKILL.md source_sha256: 0b7a90a0dd3d --- # SDK ↔ bare-SDK Sync Mirror `@qvac/sdk` → `@qvac/bare-sdk` package metadata so the two lockstep-released packages can't drift. ## When to use this skill **Applies to the `sdk` ↔ `bare-sdk` pair only.** Not relevant for other SDK pod packages. **Use when:** - User runs `/qv-sdk-bare-sdk-sync` directly. - Auto-invoked by `/qv-sdk-changelog` when `--package=sdk`. - Auto-invoked by `/qv-sdk-pr-create` when the PR diff touches `packages/sdk/package.json` version or dependency blocks. - Manually, anytime `@qvac/sdk`'s `version`, `dependencies`, `optionalDependencies`, or `peerDependencies` change and you want to keep `@qvac/bare-sdk` in lockstep before opening a PR. ## What it does **Scope:** this skill mirrors `packages/sdk/package.json` → `packages/bare-sdk/package.json` only. NOTICE regeneration is a **separate downstream step** the caller runs after sync (see Step 3 below) via `qv-notice-generate bare-sdk`. The two steps are tightly related (every sync run should be followed by a NOTICE refresh) but the script itself never touches NOTICE. Mirrors the following from sdk's `package.json` into bare-sdk's: - `version` - `dependencies` entries (except `PLUGIN_ADDONS` and `SDK_ONLY_PACKAGES`) - `optionalDependencies` entries that already exist in bare-sdk (version range only) - `peerDependencies` entries that already exist in bare-sdk (version range only) Also **prunes** `dependencies` entries that sdk no longer declares. Without this, dropping a dep from sdk leaves bare-sdk with an "extra dep" that fails `check:deps-vs-sdk` and forces a manual cleanup. Prune is scoped to `dependencies` only — `optionalDependencies` / `peerDependencies` extras are by design (bare-sdk omits Expo/Pear/RN/MCP). ## What it does NOT do - Does not touch `packages/bare-sdk/NOTICE`. Regenerating NOTICE is a separate `qv-notice-generate` invocation (Step 3 below). The script will not silently re-attribute the package — that requires intent and the right env tokens. - Does not mirror `keywords`, `description`, `repository`, `exports`, `imports`, `files`, `scripts`, `devDependencies`, or `peerDependenciesMeta`. These intentionally diverge between the two packages. - Does not add new `optionalDependencies` or `peerDependencies` to bare-sdk. bare-sdk's opt/peer shape is intentionally a subset (no Expo/Pear/RN/MCP). The script only updates ranges for entries that already exist. - Does not add `PLUGIN_ADDONS` (the 10 `@qvac/*` addon packages bare-sdk excludes by design). The exclusion list lives in `packages/bare-sdk/scripts/plugin-addons.mjs` — single source of truth, shared with `check-deps-vs-sdk.mjs`. - Does not auto-commit. The dev reviews staged changes and commits. - Does not run in CI. CI's job is detection (`check:deps-vs-sdk`); the skill's job is the fix. ## Workflow ### Step 1: Run the sync script From the monorepo root: ```bash node .cursor/skills/qv-sdk-bare-sdk-sync/scripts/sync.mjs ``` The script prints a summary of every change it makes to `packages/bare-sdk/package.json`. If nothing is out of sync, it exits cleanly with `OK: no drift`. Useful flags: | Flag | Behavior | | ----------- | -------------------------------------------------------------------------- | | `--dry-run` | Print the change summary without writing the file. | | `--check` | Exit 1 if drift is detected. Useful for ad-hoc validation (not for CI). | ### Step 2: Verify with the existing drift check ```bash cd packages/bare-sdk && bun run check:deps-vs-sdk ``` This is bare-sdk's own CI guard (`packages/bare-sdk/scripts/check-deps-vs-sdk.mjs`). It must pass after sync. If it fails, the sync logic and the check have drifted from each other — file an issue. ### Step 3: Regenerate bare-sdk's NOTICE ```bash source .env node .cursor/skills/qv-notice-generate/scripts/generate-notice.js bare-sdk ``` `bare-sdk` is included in `FULL_MODEL_LIST_PACKAGES` (see `.cursor/skills/qv-notice-generate/scripts/lib/config.js`) so the generated NOTICE carries the same model attributions (Gemma terms, etc.) as `@qvac/sdk`'s NOTICE. Required because bare-sdk re-exports sdk's compiled output. See `.cursor/skills/qv-notice-generate/SKILL.md` for prerequisites (`GH_TOKEN`, `HF_TOKEN`, `NPM_TOKEN`). ### Step 4: Review and commit `git status` should show modifications to: - `packages/bare-sdk/package.json` - `packages/bare-sdk/NOTICE` Inspect the diffs, then commit alongside the originating sdk change. When invoked from `/qv-sdk-changelog`, this is part of the release commit; when invoked from `/qv-sdk-pr-create`, this is part of the PR's last commit. ## When this skill is invoked from another skill ### From `/qv-sdk-changelog` `/qv-sdk-changelog --package=sdk` calls this skill as its final step (after NOTICE generation for sdk). This ensures every sdk release run leaves bare-sdk in sync. If the user passes `--package=`, this skill is skipped (it only applies to the sdk ↔ bare-sdk pair). ### From `/qv-sdk-pr-create` `/qv-sdk-pr-create` checks the PR diff before opening. If it touches `packages/sdk/package.json` and changes `version`, `dependencies`, `optionalDependencies`, or `peerDependencies`, the parent skill prompts the user to run this skill first. Opt out with `--no-sync` on the parent skill. ## Quality Checklist Before completing: - [ ] Script reports `OK: no drift` OR prints an apply summary with all expected changes. - [ ] `bun run check:deps-vs-sdk` passes in `packages/bare-sdk/`. - [ ] `packages/bare-sdk/NOTICE` regenerated and reviewed (heading reads `@qvac/bare-sdk`, not `@qvac/sdk`). - [ ] Staged changes contain only `packages/bare-sdk/package.json` and `packages/bare-sdk/NOTICE`. - [ ] No CI auto-commits or auto-runs of this skill (skill is local-only). ## References - Existing drift check: `packages/bare-sdk/scripts/check-deps-vs-sdk.mjs` - Plugin addon exclusion list: `packages/bare-sdk/scripts/plugin-addons.mjs` - Notice generator: `.cursor/skills/qv-notice-generate/SKILL.md` - SDK changelog skill: `.cursor/skills/qv-sdk-changelog/SKILL.md` - SDK PR-create skill: `.cursor/skills/qv-sdk-pr-create/SKILL.md` - SDK pod packages: `.cursor/rules/sdk/sdk-pod-packages.mdc`