apotheke 0.0.1 → 0.1.1

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,22 @@
-# apotheke
-
-Import organizer for JavaScript and TypeScript projects. Groups, sorts, and deduplicates imports based on a simple config file.
+<p align="left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/header/graph.svg?title=apotheke&subtitle=Deterministic%20import%20organization%20for%20JavaScript%20and%20TypeScript&logo=https://raw.githubusercontent.com/mRaffaello/apotheke/main/apps/docs/public/mark-dark.png&align=left&font=geist&mode=dark" />
+    <img alt="apotheke — deterministic import organization for JavaScript and TypeScript" src="https://shieldcn.dev/header/graph.svg?title=apotheke&subtitle=Deterministic%20import%20organization%20for%20JavaScript%20and%20TypeScript&logo=https://raw.githubusercontent.com/mRaffaello/apotheke/main/apps/docs/public/mark.png&align=left&font=geist&mode=light" />
+  </picture>
+</p>
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/apotheke">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/group/npm/apotheke+npm/dm/apotheke+bundlephobia/minzip/apotheke+npm/types/apotheke+github/ci/mRaffaello/apotheke+github/license/mRaffaello/apotheke.svg?variant=secondary&mode=dark" />
+      <img alt="npm version, monthly downloads, minzipped size, TypeScript types, CI status, MIT license" src="https://shieldcn.dev/group/npm/apotheke+npm/dm/apotheke+bundlephobia/minzip/apotheke+npm/types/apotheke+github/ci/mRaffaello/apotheke+github/license/mRaffaello/apotheke.svg?variant=secondary&mode=light" />
+    </picture>
+  </a>
+</p>
+
+**Prettier for imports.** You describe the groups your codebase actually has —
+apotheke sorts every import into them, the same way, in every file. Run it as a
+Prettier plugin or as a standalone CLI.
 
 ```ts
 // Before
@@ -25,224 +41,36 @@ import { useQuery } from '@tanstack/react-query';
 import { createRoute } from '@tanstack/react-router';
 ```
 
-## Requirements
-
-- Node.js ≥ 18
+Note where `../api/tsr` and `@tanstack/react-query` landed: grouping is by
+**role in your app**, not by whether a module is local or comes from
+`node_modules`.
 
-## Installation
+## Getting started
 
 ```sh
-npm install -D apotheke
-# or
 pnpm add -D apotheke
 ```
 
-## Usage
-
-```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
-
-Create `apotheke.config.mjs` at your project root:
-
-```js
-// apotheke.config.mjs
-export default {
-    groups: [
-        { name: 'React', match: ['react', 'react-dom', 'react-*'] },
-        { 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'],
-};
-```
-
-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:
-
-```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
+📖 **[Read the documentation →](https://marcoraffaello.com/apotheke)**
 
-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}'
-```
-
-Build first if needed: `cd /path/to/apotheke && pnpm build`
-
-### Option 2 — `pnpm link` (recommended)
-
-**In the apotheke repo:**
-
-```sh
-pnpm build
-pnpm link --global
-```
-
-**In your target repo:**
-
-```sh
-pnpm link --global apotheke
-```
-
-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.
-
-**To unlink when done:**
-
-```sh
-# In your target repo
-pnpm unlink --global apotheke
-
-# In the apotheke repo
-pnpm unlink --global
-```
-
-### Option 3 — Path dependency in `package.json`
-
-```sh
-pnpm add /path/to/apotheke
-```
-
----
+The [quick start](https://marcoraffaello.com/apotheke/docs/quick-start) goes
+from an empty config to organised imports in about two minutes.
 
 ## 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
+Issues and pull requests are welcome at
+[github.com/mRaffaello/apotheke](https://github.com/mRaffaello/apotheke).
 
-```
-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
-```
+## License
+
+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>