apotheke 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Raffaello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,9 @@
 # apotheke
 
-Import organizer for JavaScript and TypeScript projects. Groups, sorts, and deduplicates imports based on a simple config file.
+**Prettier for imports.** Deterministic, configurable import organization for
+JavaScript and TypeScript — as a Prettier plugin or a standalone CLI.
+
+📖 **[Documentation](https://marcoraffaello.com/apotheke)**
 
 ```ts
 // Before
@@ -25,224 +28,85 @@ import { useQuery } from '@tanstack/react-query';
 import { createRoute } from '@tanstack/react-router';
 ```
 
-## Requirements
-
-- Node.js ≥ 18
+apotheke is not a replacement for Prettier — it runs _inside_ Prettier as a
+`preprocess` plugin, so one `prettier --write` organises imports and formats
+code in a single pass.
 
 ## Installation
 
 ```sh
-npm install -D apotheke
-# or
 pnpm add -D apotheke
 ```
 
-## Usage
+Requires Node.js ≥ 18, and Prettier ≥ 3 if you use the plugin.
 
-```sh
-apotheke --write src/**/*.{ts,tsx}     # format in place
-apotheke --check src/**/*.{ts,tsx}     # CI — exit 1 if anything would change
-apotheke --diff  src/**/*.{ts,tsx}     # print diff without writing
-apotheke --stdin-filepath src/app.tsx  # read from stdin, write to stdout
-```
-
-## Config
+## Usage
 
-Create `apotheke.config.mjs` at your project root:
+Describe the groups you want in `apotheke.config.mjs`:
 
 ```js
-// apotheke.config.mjs
 export default {
     groups: [
-        { name: 'React', match: ['react', 'react-dom', 'react-*'] },
+        { name: 'React', match: ['react', 'react-dom'] },
         { name: 'Hooks', match: ['**/hooks/**'] },
         { name: 'Api', match: ['**/api/**', '@tanstack/react-query'] },
-        { name: 'Navigation', match: ['@tanstack/react-router'] },
-        { name: 'Assets', match: ['lucide-react'] }
-    ],
-    aliases: {
-        '@': './src' // mirrors tsconfig paths — auto-read if omitted
-    },
-    groupSeparator: true, // blank line between groups
-    groupComments: true   // // GroupName header above each group
-};
-```
-
-Apotheke also reads `tsconfig.json` (or `jsconfig.json`) automatically to pick up `paths` aliases and `baseUrl`, so you often don't need to set `aliases` manually.
-
-Unmatched imports collect in an **Others** group at the end. Side-effect imports (`import './styles.css'`) always go first.
-
-### Monorepo
-
-Place a root config and extend it per-package:
-
-```js
-// apps/web/apotheke.config.mjs
-export default {
-    extends: '../../apotheke.config.mjs',
-    groups: [{ name: 'Shared', match: ['@acme/*'] }]
-};
-```
-
----
-
-## Prettier plugin
-
-Apotheke ships as a prettier plugin. When loaded, it runs as a `preprocess` step — apotheke organises imports first, then prettier formats the result. One pass, correct order, no conflicts.
-
-**Requirements:** Prettier v3 or later (v3 supports async `preprocess`; v2 does not).
-
-### Permanent setup
-
-**1. Install apotheke**
-
-```sh
-pnpm add -D apotheke
-```
-
-**2. Add the plugin to your prettier config**
-
-```js
-// .prettierrc.js
-module.exports = {
-    plugins: ['apotheke'],
+        { name: 'Navigation', match: ['@tanstack/react-router'] }
+    ]
 };
 ```
 
-That's it — `prettier --write` will now organise imports automatically.
-
-### Quick test (without installing)
-
-```sh
-cd /path/to/your-project
-npx prettier@3 \
-  --plugin /path/to/apotheke/dist/index.js \
-  --write 'src/App.tsx'
-```
-
-### VS Code on-save
-
-Install the [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension. Because `prettier.format()` calls our plugin's `preprocess` hook directly, no extra config is needed:
+Then either add the Prettier plugin — apotheke must be **last** in the array:
 
 ```json
-{
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true
-}
-```
-
-### Pre-commit with Husky + lint-staged
-
-```json
-{
-    "lint-staged": {
-        "*.{ts,tsx,js,jsx}": ["prettier --write"]
-    }
-}
-```
-
-### Prettier v2 fallback
-
-If you can't upgrade to prettier v3, use the CLI sequentially via lint-staged:
-
-```json
-{
-    "lint-staged": {
-        "*.{ts,tsx,js,jsx}": [
-            "apotheke --write",
-            "prettier --write"
-        ]
-    }
-}
-```
-
----
-
-## Testing locally without publishing
-
-### Option 1 — Direct invocation (no setup)
-
-```sh
-node /path/to/apotheke/dist/cli.js --write 'src/**/*.{ts,tsx}'
+{ "plugins": ["apotheke"] }
 ```
 
-Build first if needed: `cd /path/to/apotheke && pnpm build`
-
-### Option 2 — `pnpm link` (recommended)
-
-**In the apotheke repo:**
+or use the CLI:
 
 ```sh
-pnpm build
-pnpm link --global
+apotheke --write 'src/**/*.{ts,tsx}'   # rewrite in place
+apotheke --check 'src/**/*.{ts,tsx}'   # CI — exit 1 if anything would change
+apotheke --diff  'src/**/*.{ts,tsx}'   # preview without writing
 ```
 
-**In your target repo:**
+Groups are matched in order and the first match wins. Unmatched imports collect
+in a trailing `Others` group; side-effect imports always come first. Imports are
+sorted and deduplicated within each group, and `tsconfig.json` path aliases are
+read automatically.
 
-```sh
-pnpm link --global apotheke
-```
+## Documentation
 
-Now `apotheke --write src/**/*.tsx` works as if it were installed normally. You'll need to re-run `pnpm build` in the apotheke repo after making source changes.
+Full guides and reference at
+**[marcoraffaello.com/apotheke](https://marcoraffaello.com/apotheke)**:
 
-**To unlink when done:**
+- [Configuring groups](https://marcoraffaello.com/apotheke/docs/guides/groups)
+- [Aliases and tsconfig paths](https://marcoraffaello.com/apotheke/docs/guides/aliases)
+- [Monorepos](https://marcoraffaello.com/apotheke/docs/guides/monorepos)
+- [Prettier plugin](https://marcoraffaello.com/apotheke/docs/guides/prettier-plugin)
+- [Config reference](https://marcoraffaello.com/apotheke/docs/reference/config)
 
-```sh
-# In your target repo
-pnpm unlink --global apotheke
-
-# In the apotheke repo
-pnpm unlink --global
-```
+## Agent skill
 
-### Option 3 — Path dependency in `package.json`
+This package ships a `SKILL.md` that teaches a coding agent to scan your
+codebase, propose a group config and wire everything up:
 
 ```sh
-pnpm add /path/to/apotheke
+mkdir -p .claude/skills/setup-apotheke
+cp node_modules/apotheke/SKILL.md .claude/skills/setup-apotheke/SKILL.md
 ```
 
----
-
 ## Development
 
+This repository is a pnpm workspace. The published package lives in
+`packages/apotheke`, the documentation site in `apps/docs`.
+
 ```sh
 pnpm install
-
-# Build (required before running locally or testing the plugin)
-pnpm build
-
-# Run all tests (unit + e2e)
-pnpm test
-
-# Unit tests only
-pnpm test:unit
-
-# E2E tests against real repos (cloned automatically on first run)
-pnpm test:e2e
-
-# Type check
-pnpm typecheck
+pnpm build            # build the package (required before format and dogfooding)
+pnpm test             # unit + e2e
+pnpm docs:dev         # run the documentation site locally
 ```
 
-### Project structure
+## License
 
-```
-src/
-  parser.ts        OXC-based import extractor
-  grouper.ts       Glob-based group assignment
-  sorter.ts        Alphabetical sort, type imports float to top
-  deduplicator.ts  Merge named/default imports from same specifier
-  printer.ts       Reconstruct import block with group headers
-  config.ts        Load apotheke.config.mjs, merge tsconfig aliases
-  format.ts        Top-level formatImports(source, config)
-  types.ts         Shared types
-cli.ts             CLI source (Node.js)
-index.ts           Prettier plugin + programmatic API
-dist/
-  cli.js           Compiled CLI — run with node or via the apotheke bin
-  index.js         Compiled prettier plugin
-  index.d.ts       Types for programmatic use
-tests/
-  unit/            76 unit tests
-  e2e/             20 e2e tests against sonner and tremor
-```
+MIT © Marco Raffaello

package/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: setup-apotheke
+description: Set up apotheke import organizer in any JS/TS project. Scans existing imports, proposes group config, writes apotheke.config.mjs, and wires up prettier plugin. Use when user wants to organize imports, set up apotheke, or add import formatting to a project.
+---
+
+# Setup Apotheke
+
+Apotheke is **Prettier for imports** — deterministic, configurable import organization for JavaScript and TypeScript. It is not a replacement for prettier: it runs *inside* prettier as a `preprocess` plugin, so imports get organized and code gets formatted in a single `prettier --write` pass. It also ships a standalone CLI for projects that do not use prettier.
+
+This skill installs and configures it by analyzing the project's actual imports, then wiring it up as a prettier plugin.
+
+Full documentation: <https://marcoraffaello.com/apotheke>
+
+## Step 1 — Detect project structure (monorepo vs single package)
+
+Before doing anything else, determine whether this is a monorepo. Check for these signals at the working directory root:
+
+| File / field                             | Tool                    |
+| ---------------------------------------- | ----------------------- |
+| `pnpm-workspace.yaml`                    | pnpm workspaces         |
+| `turbo.json`                             | Turborepo               |
+| `nx.json`                                | Nx                      |
+| `lerna.json`                             | Lerna                   |
+| `rush.json`                              | Rush                    |
+| `package.json` with `"workspaces"` field | npm/yarn/bun workspaces |
+
+If any of these are present, it's a **monorepo**. Follow the monorepo path below. Otherwise follow the single-package path.
+
+### Single-package path
+
+Proceed to Step 2 with the repo root as the single package root.
+
+### Monorepo path
+
+1. Identify all package roots by reading the workspaces glob (e.g. `packages/*`, `apps/*`) from whichever workspace config is present. List them to the user.
+2. Ask: "Should I set up a shared root config that all packages inherit from, or configure each package independently?"
+    - **Shared root** (recommended): write a root `apotheke.config.mjs` with groups common across all packages; each package gets its own config with `extends: "../../apotheke.config.mjs"` that overrides or adds package-specific groups.
+    - **Independent**: each package gets its own self-contained config with no inheritance.
+3. Scan each package separately (Step 2 runs once per package root). Combine the findings to build the shared group set before writing configs.
+4. In Step 6, add scripts to each package's `package.json` scoped to that package's source folder. Optionally add a root-level script that runs prettier across all packages.
+
+## Step 2 — Scan the project
+
+For each package root (or just the single root), search for all `.ts`, `.tsx`, `.js`, `.jsx` files (excluding `node_modules`, `dist`, `.next`, `build`, `out`). Read a sample of files (up to 20 per package, spread across the directory tree) and extract the unique import specifiers.
+
+Pay attention to:
+
+- **Package imports**: `react`, `@tanstack/react-query`, `lucide-react`, etc.
+- **Path alias imports**: `@/components/...`, `~/lib/...`, `#utils/...`
+- **Relative path patterns**: which folders appear most — `hooks/`, `api/`, `components/`, `views/`, `pages/`, `utils/`, `lib/`, `stores/`, etc.
+- **tsconfig.json / jsconfig.json**: read `compilerOptions.paths` and `compilerOptions.baseUrl` to understand existing aliases. In a monorepo, check both the root tsconfig and each package's tsconfig.
+
+## Step 3 — Check for existing config
+
+Look for `apotheke.config.mjs`, `apotheke.config.js`, or `apotheke.config.ts` at each relevant root. If one already exists, read it, tell the user, and ask whether to update it or abort.
+
+## Step 4 — Propose groups
+
+Based on what you found, propose a `groups` array. Use your judgment to create meaningful groups. Common patterns:
+
+- If the project uses React → group `react`, `react-dom`, `react-*`
+    > **Warning — `react-*` is greedy**: it will also match `react-hook-form`, `react-i18next`, `react-day-picker`, etc. Groups are matched in order and the first match wins. If you want those libraries in their own groups (Forms, i18n, Date), either list them in those groups _before_ the React group in the array, or narrow the React match to just `['react', 'react-dom']` without the wildcard.
+- If the project has `hooks/` folder → group `**/hooks/**`
+- If the project has `api/`, `services/`, `queries/` → group those paths + data-fetching libraries (react-query, swr, etc.)
+- If the project has `components/`, `ui/` → group those
+- If the project uses a router (react-router, tanstack-router, next/navigation) → group it
+- If the project uses icon libraries (lucide-react, @heroicons, react-icons) → group as Assets
+- If the project has a `store/`, `context/` folder → group it
+- If the project uses a UI kit (@mui, @radix-ui, shadcn) → group it
+- In a monorepo, internal workspace packages (e.g. `@acme/*`) deserve their own group
+
+Always propose a sensible **alias map** based on tsconfig `paths`.
+
+In a monorepo with a shared root config: put universal groups (React, external libraries) in the root config, and package-specific groups (internal paths, local components) in each package config.
+
+Present the proposed config clearly and ask the user:
+
+1. Are these groups right? Any to add, remove, or rename?
+2. Is the order right? Groups are matched top-to-bottom and the first match wins.
+3. Should there be blank lines between groups? (`groupSeparator`, default: yes)
+4. Should group comments (`// React`) be added? (`groupComments`, default: yes)
+
+Do **not** offer to toggle sorting or deduplication. Imports are always sorted
+alphabetically within a group, named imports are always sorted within the
+braces, and duplicate specifiers are always merged. There are no options for
+these.
+
+Wait for confirmation before proceeding.
+
+## Step 5 — Write apotheke.config.mjs
+
+**Always use `.mjs`** — it works with both the CLI and the Node.js prettier plugin. Never write `.ts` configs: Node.js (where prettier runs) cannot `import()` TypeScript files. Only `apotheke.config.mjs` and `apotheke.config.js` are discovered.
+
+```js
+// apotheke.config.mjs
+export default {
+    groups: [
+        // ... confirmed groups
+    ],
+    aliases: {
+        // ... from tsconfig paths
+    },
+    groupSeparator: true,
+    groupComments: true
+};
+```
+
+For a monorepo with a shared root:
+
+```js
+// apps/web/apotheke.config.mjs
+export default {
+    extends: '../../apotheke.config.mjs',
+    groups: [
+        // package-specific groups only — root groups are inherited
+        { name: 'Local Components', match: ['**/components/**'] }
+    ]
+};
+```
+
+## Step 6 — Install apotheke and wire up prettier
+
+### 6a. Install apotheke
+
+Check if apotheke is already in `package.json` dependencies. If not, install it:
+
+- Bun project (`bun.lock` present) → `bun add -D apotheke`
+- pnpm (`pnpm-lock.yaml`) → `pnpm add -D apotheke`
+- yarn (`yarn.lock`) → `yarn add -D apotheke`
+- npm (`package-lock.json`) → `npm install -D apotheke`
+
+In a monorepo, install at the root unless the workspace requires per-package installs.
+
+### 6b. Add apotheke to the prettier config
+
+Check for `.prettierrc`, `.prettierrc.js`, `.prettierrc.json`, or `prettier.config.js`. Add `"apotheke"` to the `plugins` array (create the file if none exists):
+
+```js
+// prettier.config.js  (or .prettierrc.js)
+module.exports = {
+    // ...existing options unchanged...
+    plugins: ['apotheke']
+};
+```
+
+For JSON prettier configs (`.prettierrc` or `.prettierrc.json`):
+
+```json
+{
+    "plugins": ["apotheke"]
+}
+```
+
+> **Ordering is critical**: apotheke must be the **last** entry in `plugins`. It chains to the previous plugin's `preprocess` hook via `getBase()?.preprocess`, so any plugin listed after it will completely override apotheke's preprocess and imports will not be organized. If another prettier plugin (e.g. `prettier-plugin-tailwindcss`) is already present, place `"apotheke"` after it:
+>
+> ```json
+> { "plugins": ["prettier-plugin-tailwindcss", "apotheke"] }
+> ```
+
+### 6c. Verify prettier version
+
+Check that prettier v3 is installed (`"prettier": "^3"` in devDependencies). If v2 is found, tell the user:
+
+> "Apotheke's prettier plugin requires prettier v3 (async `preprocess`). I can upgrade it, or set up the v2 fallback (CLI + prettier in sequence). Which do you prefer?"
+
+**v2 fallback** (lint-staged only):
+
+```json
+{
+    "lint-staged": {
+        "*.{ts,tsx,js,jsx}": ["apotheke --write", "prettier --write"]
+    }
+}
+```
+
+## Step 7 — Add scripts to package.json
+
+With the prettier plugin wired up, a single `prettier --write` does everything. Add:
+
+```json
+{
+    "scripts": {
+        "format": "prettier --write 'src/**/*.{ts,tsx,js,jsx}'",
+        "format:check": "prettier --check 'src/**/*.{ts,tsx,js,jsx}'"
+    }
+}
+```
+
+Adjust the glob to match the project's source folder. In a monorepo, also add a root script:
+
+```json
+{
+    "scripts": {
+        "format": "prettier --write 'packages/*/src/**/*.{ts,tsx}' 'apps/*/src/**/*.{ts,tsx}'",
+        "format:check": "prettier --check 'packages/*/src/**/*.{ts,tsx}' 'apps/*/src/**/*.{ts,tsx}'"
+    }
+}
+```
+
+## Step 8 — VS Code on-save (optional)
+
+Ask the user: "Do you want imports organized automatically on save in VS Code?"
+
+If yes, the prettier VS Code extension handles this automatically once the plugin is in the prettier config — no extra config needed. Confirm that the extension is installed and `editor.formatOnSave` is enabled:
+
+```json
+// .vscode/settings.json
+{
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+        "source.organizeImports": false
+    }
+}
+```
+
+Disable `source.organizeImports` to prevent VS Code's built-in import sorter from conflicting with apotheke.
+
+## Step 9 — Run a dry-run
+
+Run a true dry-run (no writes) on a small sample (3–5 files, one per package in a monorepo) and show the user what would change:
+
+```sh
+prettier --list-different 'src/App.tsx' 'src/main.tsx'
+```
+
+> `--write --list-different` together would actually write the files; use `--list-different` alone for a real dry-run.
+
+Show the before/after for imports to confirm the groups look right.
+
+Ask: "Does this look right? Shall I run `format` on the whole project?"
+
+If yes, run the `format` script using the package manager detected in Step 6a
+(`pnpm run format`, `bun run format`, `yarn format` or `npm run format`).
+
+## Final summary
+
+Report:
+
+- Project type: single-package or monorepo (list package roots if monorepo)
+- Config(s) written to: paths
+- Groups configured: list them
+- Prettier plugin: wired up in `prettier.config.js` (or equivalent)
+- Script added: `format` / `format:check`
+- Files that would be changed: N files
+- Whether `--write` was run
+
+Point the user at the documentation for anything beyond this setup:
+<https://marcoraffaello.com/apotheke>

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // cli.ts
-import path3 from "path";
-import fs from "fs";
 import { execFileSync } from "child_process";
+import fs from "fs";
+import path3 from "path";
 import fg from "fast-glob";
 
 // src/config.ts
-import path from "path";
 import { existsSync, readFileSync } from "fs";
+import path from "path";
 function mergeConfigs(parent, child) {
   const mergedGroups = [...parent.groups];
   for (const childGroup of child.groups ?? []) {
@@ -74,65 +74,6 @@ function loadTsConfig(dir) {
   }
 }
 
-// src/parser.ts
-import { parseSync } from "oxc-parser";
-function parseImports(source) {
-  const result = parseSync("file.tsx", source);
-  const comments = result.comments;
-  const nodes = [];
-  for (const node of result.program.body) {
-    if (node.type !== "ImportDeclaration") continue;
-    const specifier = node.source.value;
-    let defaultImport;
-    const namedImports = [];
-    let namespaceImport;
-    for (const s of node.specifiers) {
-      if (s.type === "ImportDefaultSpecifier") {
-        defaultImport = s.local.name;
-      } else if (s.type === "ImportNamespaceSpecifier") {
-        namespaceImport = s.local.name;
-      } else if (s.type === "ImportSpecifier") {
-        const imported = s.imported;
-        const name = imported.type === "Identifier" ? imported.name : imported.value;
-        const localName = s.local.name;
-        const kind = s.importKind === "type" ? "type" : "value";
-        const named = { name, kind };
-        if (localName !== name) named.alias = localName;
-        namedImports.push(named);
-      }
-    }
-    const importKind = node.importKind === "type" ? "type" : "value";
-    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
-    const importNode = {
-      specifier,
-      namedImports,
-      isSideEffect,
-      importKind,
-      start: node.start,
-      end: node.end
-    };
-    if (defaultImport) importNode.defaultImport = defaultImport;
-    if (namespaceImport) importNode.namespaceImport = namespaceImport;
-    const attached = findAttachedComment(source, node.start, comments);
-    if (attached) importNode.attachedComment = attached;
-    nodes.push(importNode);
-  }
-  return nodes;
-}
-function findAttachedComment(source, importStart, comments) {
-  const linesBefore = source.slice(0, importStart).split("\n");
-  const importLine = linesBefore.length - 1;
-  for (const comment of comments) {
-    if (comment.type !== "Line") continue;
-    const commentLines = source.slice(0, comment.end).split("\n");
-    const commentLine = commentLines.length - 1;
-    if (commentLine === importLine - 1) {
-      return `//${comment.value}`;
-    }
-  }
-  return void 0;
-}
-
 // src/deduplicator.ts
 function deduplicateImports(imports) {
   const map = /* @__PURE__ */ new Map();
@@ -241,21 +182,63 @@ function globToRegex(pattern) {
   return new RegExp(re + "$");
 }
 
-// src/sorter.ts
-function sortGroup(imports) {
-  return [...imports].sort((a, b) => {
-    if (a.importKind === "type" && b.importKind !== "type") return -1;
-    if (a.importKind !== "type" && b.importKind === "type") return 1;
-    return a.specifier.localeCompare(b.specifier);
-  });
+// src/parser.ts
+import { parseSync } from "oxc-parser";
+function parseImports(source) {
+  const result = parseSync("file.tsx", source);
+  const comments = result.comments;
+  const nodes = [];
+  for (const node of result.program.body) {
+    if (node.type !== "ImportDeclaration") continue;
+    const specifier = node.source.value;
+    let defaultImport;
+    const namedImports = [];
+    let namespaceImport;
+    for (const s of node.specifiers) {
+      if (s.type === "ImportDefaultSpecifier") {
+        defaultImport = s.local.name;
+      } else if (s.type === "ImportNamespaceSpecifier") {
+        namespaceImport = s.local.name;
+      } else if (s.type === "ImportSpecifier") {
+        const imported = s.imported;
+        const name = imported.type === "Identifier" ? imported.name : imported.value;
+        const localName = s.local.name;
+        const kind = s.importKind === "type" ? "type" : "value";
+        const named = { name, kind };
+        if (localName !== name) named.alias = localName;
+        namedImports.push(named);
+      }
+    }
+    const importKind = node.importKind === "type" ? "type" : "value";
+    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
+    const importNode = {
+      specifier,
+      namedImports,
+      isSideEffect,
+      importKind,
+      start: node.start,
+      end: node.end
+    };
+    if (defaultImport) importNode.defaultImport = defaultImport;
+    if (namespaceImport) importNode.namespaceImport = namespaceImport;
+    const attached = findAttachedComment(source, node.start, comments);
+    if (attached) importNode.attachedComment = attached;
+    nodes.push(importNode);
+  }
+  return nodes;
 }
-function sortNamedImports(node) {
-  const sorted = [...node.namedImports].sort((a, b) => {
-    if (a.kind === "type" && b.kind !== "type") return -1;
-    if (a.kind !== "type" && b.kind === "type") return 1;
-    return a.name.localeCompare(b.name);
-  });
-  return { ...node, namedImports: sorted };
+function findAttachedComment(source, importStart, comments) {
+  const linesBefore = source.slice(0, importStart).split("\n");
+  const importLine = linesBefore.length - 1;
+  for (const comment of comments) {
+    if (comment.type !== "Line") continue;
+    const commentLines = source.slice(0, comment.end).split("\n");
+    const commentLine = commentLines.length - 1;
+    if (commentLine === importLine - 1) {
+      return `//${comment.value}`;
+    }
+  }
+  return void 0;
 }
 
 // src/printer.ts
@@ -307,6 +290,23 @@ function buildImportStatement(node, q) {
   return `import ${typePrefix}${parts.join(", ")} from ${q}${node.specifier}${q};`;
 }
 
+// src/sorter.ts
+function sortGroup(imports) {
+  return [...imports].sort((a, b) => {
+    if (a.importKind === "type" && b.importKind !== "type") return -1;
+    if (a.importKind !== "type" && b.importKind === "type") return 1;
+    return a.specifier.localeCompare(b.specifier);
+  });
+}
+function sortNamedImports(node) {
+  const sorted = [...node.namedImports].sort((a, b) => {
+    if (a.kind === "type" && b.kind !== "type") return -1;
+    if (a.kind !== "type" && b.kind === "type") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { ...node, namedImports: sorted };
+}
+
 // src/format.ts
 function collectOrphanSegments(source, imports) {
   const orphans = [];
@@ -497,19 +497,21 @@ async function expandGlobs(patterns) {
 }
 function getSubmoduleDirs(cwd) {
   try {
-    const output = execFileSync("git", ["-C", cwd, "submodule", "foreach", "--recursive", "--quiet", "pwd"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"]
-    });
+    const output = execFileSync(
+      "git",
+      ["-C", cwd, "submodule", "foreach", "--recursive", "--quiet", "pwd"],
+      {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }
+    );
     return output.trim().split("\n").filter(Boolean);
   } catch {
     return [];
   }
 }
 function isUnderSubmodule(filePath, submoduleDirs) {
-  return submoduleDirs.some(
-    (dir) => filePath === dir || filePath.startsWith(dir + path3.sep)
-  );
+  return submoduleDirs.some((dir) => filePath === dir || filePath.startsWith(dir + path3.sep));
 }
 function printDiff(file, original, updated) {
   const origLines = original.split("\n");

package/dist/index.d.ts

@@ -7,7 +7,6 @@ interface ApothekeConfig {
     groups: GroupConfig[];
     aliases?: Record<string, string>;
     baseUrl?: string;
-    normalizeImports?: 'alias' | 'relative' | 'absolute' | false;
     groupSeparator?: boolean;
     groupComments?: boolean;
 }
@@ -24,7 +23,7 @@ declare function formatImports(source: string, config: ApothekeConfig, options?:
  * Prettier plugin usage (.prettierrc):
  *   { "plugins": ["apotheke"] }
  *
- * Requirements: prettier v3+, Bun runtime
+ * Requirements: prettier v3+, Node.js >= 18
  *
  * The plugin runs as a `preprocess` step, so apotheke organises imports
  * first and prettier formats the result — correct order, one pass.
@@ -32,9 +31,11 @@ declare function formatImports(source: string, config: ApothekeConfig, options?:
  * Pre-commit (lint-staged, prettier v2):
  *   { "*.{ts,tsx}": ["apotheke --write", "prettier --write"] }
  */
+declare function isDocumentSnippet(parentParser: unknown): boolean;
 type PrettierParser = {
     preprocess?: (text: string, opts: {
         filepath?: string;
+        parentParser?: string;
     }) => string | Promise<string>;
     parse?: (text: string, options: unknown) => unknown;
     astFormat?: string;
@@ -45,8 +46,8 @@ type PrettierParser = {
 declare const parsers: {
     typescript: PrettierParser;
     babel: PrettierParser;
-    "babel-ts": PrettierParser;
-    "babel-flow": PrettierParser;
+    'babel-ts': PrettierParser;
+    'babel-flow': PrettierParser;
 };
 
-export { type ApothekeConfig, formatImports, parsers };
+export { type ApothekeConfig, formatImports, isDocumentSnippet, parsers };

package/dist/index.js

@@ -1,64 +1,74 @@
 // index.ts
-import path3 from "path";
 import { existsSync as existsSync2 } from "fs";
+import { createRequire } from "module";
+import path3 from "path";
 
-// src/parser.ts
-import { parseSync } from "oxc-parser";
-function parseImports(source) {
-  const result = parseSync("file.tsx", source);
-  const comments = result.comments;
-  const nodes = [];
-  for (const node of result.program.body) {
-    if (node.type !== "ImportDeclaration") continue;
-    const specifier = node.source.value;
-    let defaultImport;
-    const namedImports = [];
-    let namespaceImport;
-    for (const s of node.specifiers) {
-      if (s.type === "ImportDefaultSpecifier") {
-        defaultImport = s.local.name;
-      } else if (s.type === "ImportNamespaceSpecifier") {
-        namespaceImport = s.local.name;
-      } else if (s.type === "ImportSpecifier") {
-        const imported = s.imported;
-        const name = imported.type === "Identifier" ? imported.name : imported.value;
-        const localName = s.local.name;
-        const kind = s.importKind === "type" ? "type" : "value";
-        const named = { name, kind };
-        if (localName !== name) named.alias = localName;
-        namedImports.push(named);
-      }
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+function mergeConfigs(parent, child) {
+  const mergedGroups = [...parent.groups];
+  for (const childGroup of child.groups ?? []) {
+    const existingIdx = mergedGroups.findIndex((g) => g.name === childGroup.name);
+    if (existingIdx >= 0) {
+      mergedGroups[existingIdx] = childGroup;
+    } else {
+      mergedGroups.push(childGroup);
     }
-    const importKind = node.importKind === "type" ? "type" : "value";
-    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
-    const importNode = {
-      specifier,
-      namedImports,
-      isSideEffect,
-      importKind,
-      start: node.start,
-      end: node.end
-    };
-    if (defaultImport) importNode.defaultImport = defaultImport;
-    if (namespaceImport) importNode.namespaceImport = namespaceImport;
-    const attached = findAttachedComment(source, node.start, comments);
-    if (attached) importNode.attachedComment = attached;
-    nodes.push(importNode);
   }
-  return nodes;
+  return {
+    ...parent,
+    ...child,
+    groups: mergedGroups,
+    aliases: { ...parent.aliases ?? {}, ...child.aliases ?? {} }
+  };
 }
-function findAttachedComment(source, importStart, comments) {
-  const linesBefore = source.slice(0, importStart).split("\n");
-  const importLine = linesBefore.length - 1;
-  for (const comment of comments) {
-    if (comment.type !== "Line") continue;
-    const commentLines = source.slice(0, comment.end).split("\n");
-    const commentLine = commentLines.length - 1;
-    if (commentLine === importLine - 1) {
-      return `//${comment.value}`;
+async function loadConfig(configPath) {
+  const mod = await import(configPath);
+  const userConfig = mod.default ?? mod;
+  const configDir = path.dirname(configPath);
+  const config = { ...userConfig };
+  const tsconfig = loadTsConfig(configDir);
+  if (tsconfig) {
+    const opts = tsconfig.compilerOptions ?? {};
+    if (opts.baseUrl && !config.baseUrl) {
+      config.baseUrl = opts.baseUrl;
+    }
+    if (opts.paths) {
+      const aliases = { ...config.aliases ?? {} };
+      for (const [aliasPattern, targets] of Object.entries(
+        opts.paths
+      )) {
+        const alias = aliasPattern.replace(/\/\*$/, "");
+        const target = (targets[0] ?? "").replace(/\/\*$/, "");
+        if (!aliases[alias]) aliases[alias] = target;
+      }
+      config.aliases = aliases;
     }
   }
-  return void 0;
+  if (userConfig.extends) {
+    const parentPath = path.resolve(configDir, userConfig.extends);
+    if (!existsSync(parentPath)) {
+      throw new Error(
+        `apotheke: extended config not found: ${parentPath}
+  (referenced from ${configPath} via "extends": "${userConfig.extends}")`
+      );
+    }
+    const parent = await loadConfig(parentPath);
+    return mergeConfigs(parent, config);
+  }
+  return config;
+}
+function loadTsConfig(dir) {
+  const tsconfigPath = path.join(dir, "tsconfig.json");
+  if (!existsSync(tsconfigPath)) return null;
+  try {
+    const text = readFileSync(tsconfigPath, "utf8");
+    const cleaned = text.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    return JSON.parse(cleaned);
+  } catch {
+    return null;
+  }
 }
 
 // src/deduplicator.ts
@@ -88,7 +98,7 @@ function deduplicateImports(imports) {
 }
 
 // src/grouper.ts
-import path from "path";
+import path2 from "path";
 function groupImports(imports, config, options = {}) {
   const buckets = /* @__PURE__ */ new Map();
   for (const node of imports) {
@@ -124,7 +134,7 @@ function assignGroup(node, config, options) {
 function resolveCanonicalPath(specifier, config, options) {
   if (specifier.startsWith(".") || specifier.startsWith("/")) {
     const base = options.fileDir ?? process.cwd();
-    return path.resolve(base, specifier);
+    return path2.resolve(base, specifier);
   }
   const aliases = config.aliases ?? {};
   for (const [alias, target] of Object.entries(aliases)) {
@@ -132,7 +142,7 @@ function resolveCanonicalPath(specifier, config, options) {
     if (specifier === alias || specifier.startsWith(prefix)) {
       const rest = specifier.slice(prefix.length);
       const root = options.rootDir ?? process.cwd();
-      const resolved = path.resolve(root, target, rest);
+      const resolved = path2.resolve(root, target, rest);
       return resolved;
     }
   }
@@ -169,21 +179,63 @@ function globToRegex(pattern) {
   return new RegExp(re + "$");
 }
 
-// src/sorter.ts
-function sortGroup(imports) {
-  return [...imports].sort((a, b) => {
-    if (a.importKind === "type" && b.importKind !== "type") return -1;
-    if (a.importKind !== "type" && b.importKind === "type") return 1;
-    return a.specifier.localeCompare(b.specifier);
-  });
+// src/parser.ts
+import { parseSync } from "oxc-parser";
+function parseImports(source) {
+  const result = parseSync("file.tsx", source);
+  const comments = result.comments;
+  const nodes = [];
+  for (const node of result.program.body) {
+    if (node.type !== "ImportDeclaration") continue;
+    const specifier = node.source.value;
+    let defaultImport;
+    const namedImports = [];
+    let namespaceImport;
+    for (const s of node.specifiers) {
+      if (s.type === "ImportDefaultSpecifier") {
+        defaultImport = s.local.name;
+      } else if (s.type === "ImportNamespaceSpecifier") {
+        namespaceImport = s.local.name;
+      } else if (s.type === "ImportSpecifier") {
+        const imported = s.imported;
+        const name = imported.type === "Identifier" ? imported.name : imported.value;
+        const localName = s.local.name;
+        const kind = s.importKind === "type" ? "type" : "value";
+        const named = { name, kind };
+        if (localName !== name) named.alias = localName;
+        namedImports.push(named);
+      }
+    }
+    const importKind = node.importKind === "type" ? "type" : "value";
+    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
+    const importNode = {
+      specifier,
+      namedImports,
+      isSideEffect,
+      importKind,
+      start: node.start,
+      end: node.end
+    };
+    if (defaultImport) importNode.defaultImport = defaultImport;
+    if (namespaceImport) importNode.namespaceImport = namespaceImport;
+    const attached = findAttachedComment(source, node.start, comments);
+    if (attached) importNode.attachedComment = attached;
+    nodes.push(importNode);
+  }
+  return nodes;
 }
-function sortNamedImports(node) {
-  const sorted = [...node.namedImports].sort((a, b) => {
-    if (a.kind === "type" && b.kind !== "type") return -1;
-    if (a.kind !== "type" && b.kind === "type") return 1;
-    return a.name.localeCompare(b.name);
-  });
-  return { ...node, namedImports: sorted };
+function findAttachedComment(source, importStart, comments) {
+  const linesBefore = source.slice(0, importStart).split("\n");
+  const importLine = linesBefore.length - 1;
+  for (const comment of comments) {
+    if (comment.type !== "Line") continue;
+    const commentLines = source.slice(0, comment.end).split("\n");
+    const commentLine = commentLines.length - 1;
+    if (commentLine === importLine - 1) {
+      return `//${comment.value}`;
+    }
+  }
+  return void 0;
 }
 
 // src/printer.ts
@@ -235,6 +287,23 @@ function buildImportStatement(node, q) {
   return `import ${typePrefix}${parts.join(", ")} from ${q}${node.specifier}${q};`;
 }
 
+// src/sorter.ts
+function sortGroup(imports) {
+  return [...imports].sort((a, b) => {
+    if (a.importKind === "type" && b.importKind !== "type") return -1;
+    if (a.importKind !== "type" && b.importKind === "type") return 1;
+    return a.specifier.localeCompare(b.specifier);
+  });
+}
+function sortNamedImports(node) {
+  const sorted = [...node.namedImports].sort((a, b) => {
+    if (a.kind === "type" && b.kind !== "type") return -1;
+    if (a.kind !== "type" && b.kind === "type") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { ...node, namedImports: sorted };
+}
+
 // src/format.ts
 function collectOrphanSegments(source, imports) {
   const orphans = [];
@@ -282,76 +351,7 @@ function formatImports(source, config, options = {}) {
   return before + newImportBlock + "\n" + orphanSuffix + after;
 }
 
-// src/config.ts
-import path2 from "path";
-import { existsSync, readFileSync } from "fs";
-function mergeConfigs(parent, child) {
-  const mergedGroups = [...parent.groups];
-  for (const childGroup of child.groups ?? []) {
-    const existingIdx = mergedGroups.findIndex((g) => g.name === childGroup.name);
-    if (existingIdx >= 0) {
-      mergedGroups[existingIdx] = childGroup;
-    } else {
-      mergedGroups.push(childGroup);
-    }
-  }
-  return {
-    ...parent,
-    ...child,
-    groups: mergedGroups,
-    aliases: { ...parent.aliases ?? {}, ...child.aliases ?? {} }
-  };
-}
-async function loadConfig(configPath) {
-  const mod = await import(configPath);
-  const userConfig = mod.default ?? mod;
-  const configDir = path2.dirname(configPath);
-  const config = { ...userConfig };
-  const tsconfig = loadTsConfig(configDir);
-  if (tsconfig) {
-    const opts = tsconfig.compilerOptions ?? {};
-    if (opts.baseUrl && !config.baseUrl) {
-      config.baseUrl = opts.baseUrl;
-    }
-    if (opts.paths) {
-      const aliases = { ...config.aliases ?? {} };
-      for (const [aliasPattern, targets] of Object.entries(
-        opts.paths
-      )) {
-        const alias = aliasPattern.replace(/\/\*$/, "");
-        const target = (targets[0] ?? "").replace(/\/\*$/, "");
-        if (!aliases[alias]) aliases[alias] = target;
-      }
-      config.aliases = aliases;
-    }
-  }
-  if (userConfig.extends) {
-    const parentPath = path2.resolve(configDir, userConfig.extends);
-    if (!existsSync(parentPath)) {
-      throw new Error(
-        `apotheke: extended config not found: ${parentPath}
-  (referenced from ${configPath} via "extends": "${userConfig.extends}")`
-      );
-    }
-    const parent = await loadConfig(parentPath);
-    return mergeConfigs(parent, config);
-  }
-  return config;
-}
-function loadTsConfig(dir) {
-  const tsconfigPath = path2.join(dir, "tsconfig.json");
-  if (!existsSync(tsconfigPath)) return null;
-  try {
-    const text = readFileSync(tsconfigPath, "utf8");
-    const cleaned = text.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
-    return JSON.parse(cleaned);
-  } catch {
-    return null;
-  }
-}
-
 // index.ts
-import { createRequire } from "module";
 async function resolveConfig(filePath) {
   const candidates = ["apotheke.config.mjs", "apotheke.config.js"];
   let dir = path3.dirname(path3.resolve(filePath));
@@ -368,7 +368,12 @@ async function resolveConfig(filePath) {
     `apotheke: no config found for ${filePath}. Create an apotheke.config.mjs in your project root.`
   );
 }
+var DOCUMENT_PARSERS = /* @__PURE__ */ new Set(["markdown", "mdx"]);
+function isDocumentSnippet(parentParser) {
+  return typeof parentParser === "string" && DOCUMENT_PARSERS.has(parentParser);
+}
 async function preprocess(text, options) {
+  if (isDocumentSnippet(options.parentParser)) return text;
   try {
     const config = await resolveConfig(options.filepath ?? process.cwd());
     const fileDir = options.filepath ? path3.dirname(path3.resolve(options.filepath)) : void 0;
@@ -436,7 +441,10 @@ function makeParser(pluginPath, parserName) {
     async preprocess(text, opts) {
       const base = getBase(opts?.filepath);
       const basePreprocess = base?.preprocess;
-      const after = basePreprocess ? await basePreprocess(text, opts) : text;
+      const after = basePreprocess ? await basePreprocess(
+        text,
+        opts
+      ) : text;
       return preprocess(after, opts);
     }
   };
@@ -449,5 +457,6 @@ var parsers = {
 };
 export {
   formatImports,
+  isDocumentSnippet,
   parsers
 };

package/package.json

@@ -1,48 +1,67 @@
 {
-  "name": "apotheke",
-  "version": "0.0.1",
-  "description": "JavaScript/TypeScript import organizer — prettier plugin + CLI",
-  "type": "module",
-  "repository": {
-    "url": "https://github.com/mRaffaello/apotheke"
-  },
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "apotheke": "./dist/cli.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "devDependencies": {
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
-    "@types/node": "^25.6.0",
-    "husky": "^9.1.7",
-    "prettier": "^3.8.3",
-    "tsup": "^8.5.1",
-    "vitest": "^4.1.5"
-  },
-  "peerDependencies": {
-    "prettier": ">=3"
-  },
-  "peerDependenciesMeta": {
-    "prettier": {
-      "optional": true
+    "name": "apotheke",
+    "version": "0.1.0",
+    "description": "Prettier for imports — deterministic import organization as a Prettier plugin or CLI",
+    "type": "module",
+    "license": "MIT",
+    "author": "Marco Raffaello",
+    "homepage": "https://marcoraffaello.com/apotheke",
+    "keywords": [
+        "imports",
+        "import-sorter",
+        "organize-imports",
+        "prettier",
+        "prettier-plugin",
+        "typescript",
+        "javascript",
+        "codemod",
+        "monorepo"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mRaffaello/apotheke",
+        "directory": "packages/apotheke"
+    },
+    "bugs": {
+        "url": "https://github.com/mRaffaello/apotheke/issues"
+    },
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "bin": {
+        "apotheke": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "SKILL.md"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:unit": "vitest run tests/unit",
+        "test:e2e": "vitest run tests/e2e/e2e.test.ts"
+    },
+    "devDependencies": {
+        "@types/node": "^25.6.0",
+        "tsup": "^8.5.1",
+        "typescript": "~5.9.3",
+        "vitest": "^4.1.5"
+    },
+    "peerDependencies": {
+        "prettier": ">=3"
+    },
+    "peerDependenciesMeta": {
+        "prettier": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "fast-glob": "^3.3.3",
+        "oxc-parser": "^0.129.0"
     }
-  },
-  "dependencies": {
-    "fast-glob": "^3.3.3",
-    "oxc-parser": "^0.129.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:unit": "vitest run tests/unit",
-    "test:e2e": "vitest run tests/e2e/e2e.test.ts"
-  }
-}
+}