feat: community add-ons - the revenge of the rebase

Simplify transforms API (flat args + TransformContext), move file helpers
back to sv, enforce scoped addon names, sv as peerDep, zero dependencies.

Author: jycouet

documentation/docs/20-commands/20-sv-add.md

@@ -71,7 +71,7 @@ Prevents installing dependencies
 > [!NOTE]
 > Svelte maintainers have not reviewed community add-ons for malicious code!
 
-You can find [community add-ons on npm](https://www.npmjs.com/search?q=keywords%3Asv-add) by searching for `keywords:sv-add`.
+You can find [community add-ons](https://npmx.dev/search?q=keyword:sv-add) by searching for the keyword `sv-add`.
 
 ### How to install a community add-on
 
@@ -99,9 +99,6 @@ npx sv create --add eslint "@supacool"
 # Scoped package: @org (preferred), we will look for @org/sv
 npx sv add "@supacool"
 
-# Regular npm package (with or without scope)
-npx sv add my-cool-addon
-
 # Local add-on
 npx sv add file:../path/to/my-addon
 ```

documentation/docs/40-api/10-add-on.md

@@ -13,6 +13,7 @@ The easiest way to create an add-on is using the addon template:
 
 ```sh
 npx sv create --template addon my-addon
+cd my-addon
 ```
 
 ## Add-on structure
@@ -22,8 +23,7 @@ Typically, an add-on looks like this:
 _hover keywords in the code to have some more context_
 
 ```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, svelte } from '@sveltejs/sv-utils';
 import { defineAddon, defineAddonOptions } from 'sv';
 
 // Define options that will be prompted to the user (or passed as arguments)
@@ -52,15 +52,18 @@ export default defineAddon({
 		if (!isKit) return cancel('SvelteKit is required');
 
 		// Add "Hello [who]!" to the root page
-		sv.file(directory.routes + '/+page.svelte', transforms.svelte(({ ast, svelte }) => {
-			svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
-		}));
+		sv.file(
+			directory.routes + '/+page.svelte',
+			transforms.svelte((ast) => {
+				svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
+			})
+		);
 	}
 });
 ```
 
-> `sv` owns the file system - `sv.file()` resolves the path, reads the file, applies the edit function, and writes the result.
-> `@sveltejs/sv-utils` owns the content - `transforms.svelte()` returns a curried function that handles parsing, gives you the AST and utils, and serializes back. See [sv-utils](/docs/cli/sv-utils) for the full API.
+> `sv` owns the file system — `sv.file()` resolves the path, reads the file, applies the transform, and writes the result.
+> `@sveltejs/sv-utils` owns the content — `transforms.svelte()` handles parsing, gives you the AST, and serializes back. See [sv-utils](/docs/cli/sv-utils) for the full API.
 
 ## Development with `file:` protocol
 
@@ -176,7 +179,7 @@ npm publish
 You can optionally display guidance after your add-on runs:
 
 ```js
-// @noErrors
+// @errors: 2304 7031
 export default defineAddon({
 	// ...
 	nextSteps: ({ options }) => [

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

@@ -16,158 +16,128 @@ npm install -D @sveltejs/sv-utils
 The Svelte CLI is split into two packages with a clear boundary:
 
 - **`sv`** = **where and when** to do it. It owns paths, workspace detection, dependency tracking, and file I/O. The engine orchestrates add-on execution.
-- **`@sveltejs/sv-utils`** = **what** to do to content. It provides parsers, language tooling, and typed transforms. Everything here is pure - no file system, no workspace awareness.
+- **`@sveltejs/sv-utils`** = **what** to do to content. It provides parsers, language tooling, and typed transforms. Everything here is pure — no file system, no workspace awareness.
 
 This separation means transforms are testable without a workspace and composable across add-ons.
 
 ## Transforms
 
-Transforms are curried, parser-aware functions that turn `string -> string`. Call a transform with your callback to get a function that plugs directly into `sv.file()`. The parser choice is baked into the transform type - you can't accidentally parse a vite config as Svelte because you never call a parser yourself.
-
-Each transform injects relevant utilities into the callback, so you only need one import:
+Transforms are typed, parser-aware functions that turn `string -> string`. The parser choice is baked into the transform type — you can't accidentally parse a vite config as Svelte because you never call a parser yourself.
 
 ```js
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, js, svelte, css, json } from '@sveltejs/sv-utils';
 ```
 
 ### `transforms.script`
 
-Transform a JavaScript/TypeScript file. The callback receives `{ ast, comments, content, js }`.
+Transform a JavaScript/TypeScript file. The callback receives the AST, comments, and a context with `language`.
 
 ```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, js } from '@sveltejs/sv-utils';
 
-sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
+const addVitePlugin = transforms.script((ast, comments, { language }) => {
 	js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
 	js.vite.addPlugin(ast, { code: 'foo()' });
-}));
+});
 ```
 
 ### `transforms.svelte`
 
-Transform a Svelte component. The callback receives `{ ast, content, svelte, js }`.
+Transform a Svelte component. The engine injects `language` automatically via the context.
 
 ```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
-
-sv.file(layoutPath, transforms.svelte(({ ast, svelte }) => {
-	svelte.addFragment(ast, '<Foo />');
-}));
-```
+import { transforms, js, svelte } from '@sveltejs/sv-utils';
 
-### `transforms.svelteScript`
-
-Transform a Svelte component with a `<script>` block guaranteed. Pass `{ language }` as the first argument. The callback receives `{ ast, content, svelte, js }` where `ast.instance` is always non-null.
-
-```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
-
-sv.file(layoutPath, transforms.svelteScript({ language }, ({ ast, svelte, js }) => {
+const addFooComponent = transforms.svelte((ast, { language }) => {
+	svelte.ensureScript(ast, { language });
 	js.imports.addDefault(ast.instance.content, { as: 'Foo', from: './Foo.svelte' });
 	svelte.addFragment(ast, '<Foo />');
-}));
+});
 ```
 
 ### `transforms.css`
 
-Transform a CSS file. The callback receives `{ ast, content, css }`.
+Transform a CSS file. The callback receives the AST and a context with `language`.
 
 ```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, css } from '@sveltejs/sv-utils';
 
-sv.file(files.stylesheet, transforms.css(({ ast, css }) => {
+const addTailwind = transforms.css((ast, { language }) => {
 	css.addAtRule(ast, { name: 'import', params: "'tailwindcss'" });
-}));
+});
 ```
 
 ### `transforms.json`
 
-Transform a JSON file. Mutate the `data` object directly. The callback receives `{ data, content, json }`.
+Transform a JSON file. Mutate the `data` object directly. The callback also receives a context with `language`.
 
 ```js
-// @noErrors
 import { transforms } from '@sveltejs/sv-utils';
 
-sv.file(files.tsconfig, transforms.json(({ data }) => {
+const enableStrict = transforms.json((data, { language }) => {
 	data.compilerOptions ??= {};
 	data.compilerOptions.strict = true;
-}));
+});
 ```
 
 ### `transforms.yaml` / `transforms.toml`
 
-Same pattern as `transforms.json`, for YAML and TOML files respectively. The callback receives `{ data, content }`.
+Same pattern as `transforms.json`, for YAML and TOML files respectively. All callbacks receive a context with `language`.
 
 ### `transforms.text`
 
-Transform a plain text file (.env, .gitignore, etc.). No parser - string in, string out. The callback receives `{ content, text }`.
+Transform a plain text file (.env, .gitignore, etc.). No parser — string in, string out. The callback also receives a context with `language`.
 
 ```js
-// @noErrors
 import { transforms } from '@sveltejs/sv-utils';
 
-sv.file('.env', transforms.text(({ content }) => {
+const addDbUrl = transforms.text((content, { language }) => {
 	return content + '\nDATABASE_URL="file:local.db"';
-}));
+});
 ```
 
 ### Aborting a transform
 
-Return `false` from any transform callback to abort - the original content is returned unchanged.
+Return `false` from any transform callback to abort — the original content is returned unchanged.
 
 ```js
-// @noErrors
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, js } from '@sveltejs/sv-utils';
 
-sv.file(files.eslintConfig, transforms.script(({ ast, js }) => {
+const myConfig = '{}';
+const setupEslint = transforms.script((ast) => {
 	const { value: existing } = js.exports.createDefault(ast, { fallback: myConfig });
 	if (existing !== myConfig) {
 		// config already exists, don't touch it
 		return false;
 	}
 	// ... continue modifying ast
-}));
+});
 ```
 
 ### Standalone usage & testing
 
-Transforms are curried functions - call them with the callback, then apply to content:
+Transforms are just functions — they work without the `sv` engine. Pass content directly, with an optional context:
 
 ```js
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, js } from '@sveltejs/sv-utils';
 
-const result = transforms.script(({ ast, js }) => {
+const addPlugin = transforms.script((ast) => {
 	js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
-})('export default {}');
+});
+
+// use standalone — pass content and context directly
+const result = addPlugin('export default {}', { language: 'ts' });
 ```
 
 ### Composability
 
-For cases where you need to mix transforms and raw edits, use `sv.file` with a content callback and invoke the curried transform manually:
+Add-ons can export reusable transforms that other add-ons consume:
 
 ```js
-// @noErrors
-sv.file(path, (content) => {
-	content = transforms.script(({ ast, js }) => {
-		js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
-	})(content);
-	content = content.replace('foo', 'bar');
-	return content;
-});
-```
-
-Add-ons can also export reusable transform functions:
-
-```js
-// @errors: 7006
-import { transforms } from '@sveltejs/sv-utils';
+import { transforms, js, svelte } from '@sveltejs/sv-utils';
 
-// reusable - export from your package
-export const addFooImport = transforms.svelte(({ ast, svelte, js }) => {
+// reusable transform — export from your package
+export const addFooImport = transforms.svelte((ast, { language }) => {
 	svelte.ensureScript(ast, { language });
 	js.imports.addDefault(ast.instance.content, { as: 'Foo', from: './Foo.svelte' });
 });
@@ -178,7 +148,6 @@ export const addFooImport = transforms.svelte(({ ast, svelte, js }) => {
 For cases where transforms don't fit (e.g., conditional parsing, error handling around the parser), the `parse` namespace is still available:
 
 ```js
-// @noErrors
 import { parse } from '@sveltejs/sv-utils';
 
 const { ast, generateCode } = parse.script(content);
@@ -194,9 +163,9 @@ const { ast, generateCode } = parse.html(content);
 
 Namespaced helpers for AST manipulation:
 
-- **`js.*`** - imports, exports, objects, arrays, variables, functions, vite config helpers, SvelteKit helpers
-- **`css.*`** - rules, declarations, at-rules, imports
-- **`svelte.*`** - ensureScript, addSlot, addFragment
-- **`json.*`** - arrayUpsert, packageScriptsUpsert
-- **`html.*`** - attribute manipulation
-- **`text.*`** - upsert lines in flat files (.env, .gitignore)
+- **`js.*`** — imports, exports, objects, arrays, variables, functions, vite config helpers, SvelteKit helpers
+- **`css.*`** — rules, declarations, at-rules, imports
+- **`svelte.*`** — ensureScript, addSlot, addFragment
+- **`json.*`** — arrayUpsert, packageScriptsUpsert
+- **`html.*`** — attribute manipulation
+- **`text.*`** — upsert lines in flat files (.env, .gitignore)

packages/sv-utils/package.json

@@ -38,7 +38,6 @@
 	},
 	"keywords": [
 		"sv",
-		"sv-add",
 		"svelte",
 		"sveltekit"
 	]

packages/sv-utils/src/index.ts

@@ -29,7 +29,12 @@ export * as json from './tooling/json.ts';
 export * as svelte from './tooling/svelte/index.ts';
 
 // Transforms — sv-utils = what to do to content, sv = where and when to do it.
-export { transforms } from './tooling/transforms.ts';
+export {
+	transforms,
+	isTransform,
+	type TransformFn,
+	type TransformContext
+} from './tooling/transforms.ts';
 
 /**
  * Low-level parsers. Prefer `transforms` for add-on file edits — it picks the
@@ -66,20 +71,8 @@ export { createPrinter } from './utils.ts';
 export { sanitizeName } from './sanitize.ts';
 export { downloadJson } from './downloadJson.ts';
 
-// File system helpers
-export {
-	commonFilePaths,
-	fileExists,
-	getPackageJson,
-	installPackages,
-	readFile,
-	writeFile,
-	type Package
-} from './files.ts';
-
 // Terminal styling
 export { color } from './color.ts';
 
 // Types
 export type { Comments, AstTypes, SvelteAst } from './tooling/index.ts';
-export type { TransformFn } from './tooling/transforms.ts';