chore: coupling

.changeset/coupling-sv-and-sv-utils.md

@@ -0,0 +1,22 @@
+---
+'sv': minor
+'@sveltejs/sv-utils': minor
+---
+
+feat: sv / sv-utils coupling, pnpm helpers, experimental add-ons, and API snapshots
+
+**Highlights**
+
+- Replace `sv.pnpmBuildDependency` with `sv.file` plus `pnpm.onlyBuiltDependencies` from `@sveltejs/sv-utils` and `file.findUp`.
+
+**`@sveltejs/sv-utils`**
+
+- Add `pnpm.onlyBuiltDependencies` to append packages to `onlyBuiltDependencies` in pnpm YAML via `transforms.yaml`.
+- Type `YamlDocument` (`parse.yaml`) with `get` / `set` using `unknown` so consumers narrow explicitly; align YAML transforms with that contract.
+
+**`sv`**
+
+- Refactor workspace / engine / package-manager flows around file IO and package JSON loading (`loadFile`, `saveFile`, `loadPackageJson`), and trim workspace addon path handling; update addons accordingly.
+- Reorganize the public `testing` entry for Vitest helpers and document the surface.
+- Add generated `api-surface` markdown snapshots and a `scripts/generate-api-surface.js` helper (wired through the build) to track the public API.
+- Remove deprecated `pnpmBuildDependency` usage and stop exporting internal pnpm-only-built helpers from the public `sv` surface.

documentation/docs/50-api/10-sv.md

@@ -48,7 +48,7 @@ export default defineAddon({
 });
 ```
 
-The `sv` object in `run` provides `file`, `dependency`, `devDependency`, `execute`, and `pnpmBuildDependency`. For file transforms (AST-based editing of scripts, Svelte components, CSS, JSON, etc.), see [`@sveltejs/sv-utils`](sv-utils).
+The `sv` object in `run` provides `file`, `dependency`, `devDependency`, and `execute`. For file transforms (AST-based editing of scripts, Svelte components, CSS, JSON, etc.) and package manager helpers, see [`@sveltejs/sv-utils`](sv-utils).
 
 ## `defineAddonOptions`
 

documentation/docs/50-api/20-sv-utils.md

@@ -137,7 +137,7 @@ Return `false` from any transform callback to abort - the original content is re
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	file.eslintConfig,
+	'eslint.config.js',
 	transforms.script(({ ast, js }) => {
 		const { value: existing } = js.exports.createDefault(ast, { fallback: myConfig });
 		if (existing !== myConfig) {
@@ -229,3 +229,18 @@ Namespaced helpers for AST manipulation:
 - **`json.*`** - arrayUpsert, packageScriptsUpsert
 - **`html.*`** - attribute manipulation
 - **`text.*`** - upsert lines in flat files (.env, .gitignore)
+
+## Package manager helpers
+
+### `pnpm.onlyBuiltDependencies`
+
+Returns a transform for `pnpm-workspace.yaml` that adds packages to the `onlyBuiltDependencies` list. Use with `sv.file` when the project uses pnpm.
+
+```js
+// @noErrors
+import { pnpm } from '@sveltejs/sv-utils';
+
+if (packageManager === 'pnpm') {
+	sv.file(file.findUp('pnpm-workspace.yaml'), pnpm.onlyBuiltDependencies('my-native-dep'));
+}
+```

package.json

@@ -9,6 +9,7 @@
 	},
 	"scripts": {
 		"build": "tsdown",
+		"postbuild": "node scripts/generate-api-surface.js",
 		"changeset:publish": "changeset publish",
 		"check": "pnpm --parallel check",
 		"dev": "tsdown -w & pnpm --parallel check -w & wait",