@runtimestudio/tailwind-sort-php 0.1.1 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Runtime Studio
+Copyright (c) 2026 The Trustee for G&J Sevastos Family Trust t/a Runtime Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,10 @@
-# @runtimestudio/tailwind-sort-php
+# Tailwind CSS Class Sorter for PHP
 
-Tailwind CSS class sorting for **mixed PHP/HTML templates** — the WordPress template-partial case that
-`@prettier/plugin-php` + `prettier-plugin-tailwindcss` can't handle.
+[![npm version](https://img.shields.io/npm/v/@runtimestudio/tailwind-sort-php)](https://www.npmjs.com/package/@runtimestudio/tailwind-sort-php)
+[![License: MIT](https://img.shields.io/npm/l/@runtimestudio/tailwind-sort-php)](LICENSE)
+
+`@runtimestudio/tailwind-sort-php` sorts Tailwind CSS classes in **plain PHP files, WordPress themes and plugins, and
+mixed PHP/HTML templates** — the case `prettier-plugin-tailwindcss` can't parse and `@prettier/plugin-php` mangles.
 
 `prettier-plugin-tailwindcss` sorts classes beautifully, but it can't parse files that interleave PHP with HTML, and
 `@prettier/plugin-php` reformats the entire PHP file as a side effect. This tool sorts **only** the class attribute
@@ -17,17 +20,17 @@ values, using a real PHP-aware lexer, and leaves everything else byte-identical.
 
 ## Requirements
 
-- **Bun**, or **Node ≥ 22.18** (native TypeScript type-stripping) — both run the CLI and the programmatic API.
+- **Node ≥ 22.18**, or **Bun** — both run the CLI and the programmatic API.
 - `prettier` ≥ 3 and `prettier-plugin-tailwindcss` ≥ 0.8 (peer dependencies).
 
 ## Install
 
 ```sh
-# Bun
-bun add -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
-
 # npm
 npm install -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
+
+# Bun
+bun add -D @runtimestudio/tailwind-sort-php prettier prettier-plugin-tailwindcss
 ```
 
 pnpm and yarn work the same (`pnpm add -D …` / `yarn add -D …`).
@@ -35,7 +38,9 @@ pnpm and yarn work the same (`pnpm add -D …` / `yarn add -D …`).
 ## Setup
 
 Point Prettier at your Tailwind v4 entry stylesheet so both `prettier-plugin-tailwindcss` and this tool share one
-vocabulary. In `prettier.config.mjs`:
+vocabulary. Any config format Prettier supports works (`.prettierrc`, `prettier.config.js`, a `package.json`
+`"prettier"` key, …) — the tool reads the resolved config, exactly like the plugin does. For example, in
+`prettier.config.mjs`:
 
 ```js
 export default {
@@ -49,20 +54,23 @@ this in place, the CLI needs no flags.
 
 ## Usage
 
-Run with `bunx` (Bun) or `npx` (Node ≥ 22.18):
+Run with `npx` (Node ≥ 22.18) or `bunx` (Bun):
 
 ```sh
 # sort every .php file under the cwd (stylesheet read from your Prettier config)
-bunx tailwind-sort-php
+npx tailwind-sort-php
 
 # specific globs
-bunx tailwind-sort-php "template-parts/**/*.php" "*.php"
+npx tailwind-sort-php "template-parts/**/*.php" "*.php"
 
 # CI / pre-commit — write nothing, exit 1 if anything is unsorted
-bunx tailwind-sort-php --check
+npx tailwind-sort-php --check
 
 # explicit stylesheet (overrides the Prettier config)
-bunx tailwind-sort-php --stylesheet ./resources/css/main.css
+npx tailwind-sort-php --stylesheet ./resources/css/main.css
+
+# one-time: install the pre-commit hook (see "Pre-commit gate" below)
+npx tailwind-sort-php init
 ```
 
 ### Options
@@ -76,6 +84,68 @@ bunx tailwind-sort-php --stylesheet ./resources/css/main.css
 
 Default globs are all `.php` files under the cwd; `node_modules`, `vendor`, `dist`, and `.git` are always skipped.
 
+## Editor integration
+
+No IDE plugin is needed — two small setups cover the common workflows.
+
+### Sort on save (PhpStorm / IntelliJ)
+
+Add a File Watcher (Settings → Tools → File Watchers → `+` → Custom):
+
+- **File type:** PHP
+- **Program:** `$ProjectFileDir$/node_modules/.bin/tailwind-sort-php`
+- **Arguments:** `$FilePathRelativeToProjectRoot$`
+- **Working directory:** `$ProjectFileDir$`
+
+Untick "Auto-save edited files to trigger the watcher" so it runs on explicit save (~130 ms per file). The definition
+lives in `.idea/watcherTasks.xml`, which you can commit to share it with your team.
+
+### Sort on save (VS Code)
+
+Install the [Run on Save](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) extension, then add
+to `.vscode/settings.json`:
+
+```json
+{
+  "emeraldwalk.runonsave": {
+    "commands": [
+      {
+        "match": "\\.php$",
+        "cmd": "${workspaceFolder}/node_modules/.bin/tailwind-sort-php ${relativeFile}"
+      }
+    ]
+  }
+}
+```
+
+### Pre-commit gate
+
+Keep unsorted classes from landing regardless of the editor. One command installs a dependency-free Git hook at
+`.githooks/pre-commit` and points `core.hooksPath` at it:
+
+```sh
+# check-and-fail (default): names the unsorted files and blocks the commit
+npx tailwind-sort-php init
+
+# auto-fix: sorts the staged files in place, then blocks the commit for review and re-staging
+npx tailwind-sort-php init --fix
+```
+
+`init` is no-clobber by default: it refuses to overwrite a differing hook, repoint a `core.hooksPath` that's set
+elsewhere (husky etc.), or disable hooks already living in `.git/hooks` — pass `--force` to override, `--dry-run` to
+preview. Run it once per clone; commit the `.githooks/` directory to share the hook with your team.
+
+Both variants check working-tree file contents, so with partial staging (`git add -p`) the hook can mis-report — and
+under `--fix`, re-staging a fixed file can pull in unrelated unstaged hunks.
+
+Wiring the gate into your own hook manager (husky, lefthook) instead? The staged-PHP check is this one-liner:
+
+```sh
+git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 ./node_modules/.bin/tailwind-sort-php --check
+```
+
+In CI there's no staged diff — just sweep the whole project with `npx tailwind-sort-php --check`.
+
 ## How it handles mixed templates
 
 PHP islands inside a class attribute are treated as opaque atoms that never move. Static text between islands is sorted
@@ -130,14 +200,15 @@ const out = transform(source, sortFn);
 ## Development
 
 ```sh
-bun test                       # or: node --test "test/*.test.ts"
-bun run build                  # compile src → dist (tsc); the published artifact
+bun test      # or: node --test "test/*.test.ts"
+bun run build # compile src → dist (tsc); the published artifact
 ```
 
-46 tests: 41 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`), plus 5
+54 tests: 41 core tests that are dependency-free (the sorter is injected, so they run against a mock `SortFn`), 5
 integration tests that exercise the real `prettier-plugin-tailwindcss` sorter and skip automatically when the Tailwind
-toolchain isn't installed.
+toolchain isn't installed, and 8 `init` tests that run against throwaway git repositories and skip when `git` is
+unavailable.
 
 ## License
 
-MIT © Runtime Studio
+[MIT](LICENSE) © Runtime Studio

package/dist/cli.d.ts

@@ -4,6 +4,7 @@
  *
  * Usage:
  *   tailwind-sort-php [options] [glob ...]
+ *   tailwind-sort-php init [--fix] [--force] [--dry-run]
  *
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
@@ -11,7 +12,7 @@
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *
- * Defaults to all `.php` files under `cwd` (`"**" + "/*.php"`) when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`.
+ * Defaults to all `.php` files under `cwd` when no globs are given.
+ * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 export {};

package/dist/cli.js

@@ -4,6 +4,7 @@
  *
  * Usage:
  *   tailwind-sort-php [options] [glob ...]
+ *   tailwind-sort-php init [--fix] [--force] [--dry-run]
  *
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
@@ -11,12 +12,13 @@
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *
- * Defaults to all `.php` files under `cwd` (`"**" + "/*.php"`) when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`.
+ * Defaults to all `.php` files under `cwd` when no globs are given.
+ * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 import { readFile, writeFile } from 'node:fs/promises';
 import { transform } from "./transform.js";
 import { createTailwindSortFn } from "./sorter.js";
+import { runInit } from "./init.js";
 const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
 /**
  * Parse command-line arguments.
@@ -58,7 +60,6 @@ function parseArgs(argv) {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs) {
-    // Use `Bun.Glob` when available, fall back to `node:fs` glob (Node 22+).
     if (typeof globalThis.Bun !== 'undefined') {
         const { Glob } = await import('bun');
         for (const pattern of globs) {
@@ -112,7 +113,10 @@ async function fromPrettierConfig() {
     }
 }
 async function main() {
-    const cli = parseArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'init')
+        return runInit(argv.slice(1));
+    const cli = parseArgs(argv);
     const pc = await fromPrettierConfig();
     const stylesheet = cli.stylesheet ?? pc.stylesheet;
     if (!stylesheet) {

package/dist/html.d.ts

@@ -8,7 +8,7 @@
  *   - islands inside a quoted attribute value read as opaque atoms
  *
  * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
- * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */

package/dist/html.js

@@ -8,7 +8,7 @@
  *   - islands inside a quoted attribute value read as opaque atoms
  *
  * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
- * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */

package/dist/init.d.ts

@@ -0,0 +1,12 @@
+/**
+ * tailwind-sort-php init
+ *
+ * Installs the pre-commit hook: writes `.githooks/pre-commit` and points `core.hooksPath` at it.
+ * No-clobber unless `--force`; `--fix` installs the auto-fixing variant; `--dry-run` previews.
+ */
+/**
+ * Run the `init` subcommand: install the pre-commit hook and point `core.hooksPath` at it.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ */
+export declare function runInit(argv: string[]): Promise<void>;

package/dist/init.js

@@ -0,0 +1,169 @@
+/**
+ * tailwind-sort-php init
+ *
+ * Installs the pre-commit hook: writes `.githooks/pre-commit` and points `core.hooksPath` at it.
+ * No-clobber unless `--force`; `--fix` installs the auto-fixing variant; `--dry-run` previews.
+ */
+import { execFileSync } from 'node:child_process';
+import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const HOOKS_DIR = '.githooks';
+const HOOK_PATH = `${HOOKS_DIR}/pre-commit`;
+/**
+ * Check-and-fail hook (default): names the unsorted files and blocks the commit; never writes.
+ */
+const HOOK_CHECK = `#!/bin/sh
+# Block commits with unsorted Tailwind classes in staged PHP files. Installed by \`tailwind-sort-php init\`.
+# Note: checks working-tree file contents, so partial staging (\`git add -p\`) can mis-report; see README.
+sorter=./node_modules/.bin/tailwind-sort-php
+[ -x "$sorter" ] || exit 0
+git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
+if git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter" --check; then
+  exit 0
+fi
+echo >&2
+echo "Unsorted Tailwind classes in staged PHP (see above)." >&2
+echo "Fix with: npx tailwind-sort-php (or: bunx tailwind-sort-php), then re-stage." >&2
+exit 1
+`;
+/**
+ * Auto-fix hook (--fix): sorts the staged files in place, then blocks the commit for review.
+ */
+const HOOK_FIX = `#!/bin/sh
+# Sort Tailwind classes in staged PHP files, then abort the commit so the changes can be reviewed and re-staged.
+# Rewrites working-tree files. Installed by \`tailwind-sort-php init --fix\`.
+# Note: with partial staging (\`git add -p\`), re-staging can pull in unrelated unstaged hunks; see README.
+sorter=./node_modules/.bin/tailwind-sort-php
+[ -x "$sorter" ] || exit 0
+git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
+if git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter" --check >/dev/null 2>&1; then
+  exit 0
+fi
+git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter"
+echo >&2
+echo "Sorted Tailwind classes in staged PHP (see above)." >&2
+echo "Review the changes, re-stage, and commit again." >&2
+exit 1
+`;
+/**
+ * Parse `init` subcommand arguments.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ * @returns Parsed flags with defaults applied.
+ */
+function parseArgs(argv) {
+    const cli = { fix: false, force: false, dryRun: false };
+    for (const a of argv) {
+        if (a === '--fix')
+            cli.fix = true;
+        else if (a === '--force')
+            cli.force = true;
+        else if (a === '--dry-run')
+            cli.dryRun = true;
+        else {
+            console.error(`Unknown init option: ${a}`);
+            process.exit(2);
+        }
+    }
+    return cli;
+}
+/**
+ * Run a git command and capture its output.
+ *
+ * @param args Arguments passed to `git`.
+ * @returns Trimmed stdout, or `null` when git exits non-zero (unset config, not a repo, …).
+ */
+function git(args) {
+    try {
+        return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Print an error to stderr and exit with status 1.
+ *
+ * @param message Error text explaining why init refused to proceed.
+ */
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+/**
+ * Run the `init` subcommand: install the pre-commit hook and point `core.hooksPath` at it.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ */
+export async function runInit(argv) {
+    const cli = parseArgs(argv);
+    const hookBody = cli.fix ? HOOK_FIX : HOOK_CHECK;
+    const variant = cli.fix ? 'fix' : 'check';
+    // Anchor everything at the repository root: a relative `core.hooksPath` resolves there,
+    // and the hook's `./node_modules/...` path assumes hooks run from it (they do, for pre-commit).
+    const top = git(['rev-parse', '--show-toplevel']);
+    if (top === null)
+        fail('Not a git repository (or a bare one) — run init from inside a working tree.');
+    const gitDir = git(['rev-parse', '--absolute-git-dir']);
+    const hookAbs = join(top, HOOK_PATH);
+    // Decide whether `core.hooksPath` needs to change. Repointing it makes git ignore `.git/hooks` entirely,
+    // so refuse to silently disable hooks that already live there.
+    const hooksPath = git(['config', '--get', 'core.hooksPath']);
+    let setConfig = false;
+    if (hooksPath === null) {
+        const live = (await readdir(join(gitDir, 'hooks')).catch(() => [])).filter((f) => !f.endsWith('.sample'));
+        if (live.length > 0 && !cli.force) {
+            fail(`Found existing hook(s) in .git/hooks: ${live.join(', ')}.\n` +
+                `Setting core.hooksPath would disable them. Move them into ${HOOKS_DIR}/ first, ` +
+                'or re-run with --force to proceed anyway.');
+        }
+        setConfig = true;
+    }
+    else if (hooksPath !== HOOKS_DIR) {
+        if (!cli.force) {
+            fail(`core.hooksPath is already set to "${hooksPath}" — add the hook there yourself, or re-run ` +
+                `with --force to repoint it to ${HOOKS_DIR}. Hook body:\n\n${hookBody}`);
+        }
+        setConfig = true;
+    }
+    // Decide whether the hook file needs writing; overwriting a differing hook needs --force.
+    const current = await readFile(hookAbs, 'utf8').catch(() => null);
+    let writeHook = current === null;
+    let repairMode = false;
+    if (current !== null && current !== hookBody) {
+        if (!cli.force) {
+            const installed = current === HOOK_CHECK ? 'the check variant' : current === HOOK_FIX ? 'the --fix variant' : 'a custom hook';
+            fail(`${HOOK_PATH} already exists and differs (${installed} is installed). Re-run with --force to overwrite.`);
+        }
+        writeHook = true;
+    }
+    if (current === hookBody) {
+        // Content is already right; still repair a missing executable bit, or git silently skips the hook.
+        repairMode = ((await stat(hookAbs)).mode & 0o111) === 0;
+    }
+    const done = [];
+    if (writeHook) {
+        if (!cli.dryRun) {
+            await mkdir(join(top, HOOKS_DIR), { recursive: true });
+            await writeFile(hookAbs, hookBody);
+            await chmod(hookAbs, 0o755);
+        }
+        done.push(cli.dryRun ? `would install ${HOOK_PATH} (${variant} variant)` : `installed ${HOOK_PATH} (${variant} variant)`);
+    }
+    if (repairMode) {
+        if (!cli.dryRun)
+            await chmod(hookAbs, 0o755);
+        done.push(cli.dryRun ? `would make ${HOOK_PATH} executable` : `made ${HOOK_PATH} executable`);
+    }
+    if (setConfig) {
+        if (!cli.dryRun)
+            git(['config', 'core.hooksPath', HOOKS_DIR]);
+        done.push(cli.dryRun ? `would set core.hooksPath = ${HOOKS_DIR}` : `set core.hooksPath = ${HOOKS_DIR}`);
+    }
+    if (done.length === 0) {
+        console.log(`Nothing to do — ${HOOK_PATH} (${variant} variant) is already installed.`);
+        return;
+    }
+    for (const line of done)
+        console.log(line);
+}

package/dist/islands.js

@@ -73,7 +73,7 @@ function scanPhpBody(src, i) {
             continue;
         }
         // Double-quoted string.
-        // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer (documented).
+        // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
         if (c === '"') {
             i = scanQuoted(src, i + 1, '"');
             continue;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@runtimestudio/tailwind-sort-php",
-  "version": "0.1.1",
-  "description": "Tailwind CSS class sorting for mixed PHP/HTML templates (WordPress-friendly)",
+  "version": "0.2.1",
+  "description": "Tailwind CSS Class Sorter for PHP",
   "keywords": [
     "class-sorting",
     "formatter",

package/src/cli.ts

@@ -4,6 +4,7 @@
  *
  * Usage:
  *   tailwind-sort-php [options] [glob ...]
+ *   tailwind-sort-php init [--fix] [--force] [--dry-run]
  *
  * Options:
  *   --stylesheet <path> Tailwind v4 CSS entry
@@ -11,13 +12,14 @@
  *   --check Don't write; exit 1 if any file needs sorting
  *   --no-short-tags Don't treat bare `<?` as a PHP open tag
  *
- * Defaults to all `.php` files under `cwd` (`"**" + "/*.php"`) when no globs are given.
- * Skips `node_modules`, `vendor`, `dist` and `.git`.
+ * Defaults to all `.php` files under `cwd` when no globs are given.
+ * Skips `node_modules`, `vendor`, `dist` and `.git`. The `init` subcommand installs the pre-commit hook; see `init.ts`.
  */
 
 import { readFile, writeFile } from 'node:fs/promises';
 import { transform, type TransformOptions } from './transform.ts';
 import { createTailwindSortFn } from './sorter.ts';
+import { runInit } from './init.ts';
 
 const IGNORE = ['node_modules', 'vendor', 'dist', '.git'];
 
@@ -63,7 +65,6 @@ function parseArgs(argv: string[]): Cli {
  * @param globs Glob patterns relative to `cwd`.
  */
 async function* scanFiles(globs: string[]): AsyncGenerator<string> {
-  // Use `Bun.Glob` when available, fall back to `node:fs` glob (Node 22+).
   if (typeof (globalThis as any).Bun !== 'undefined') {
     const { Glob } = await import('bun');
     for (const pattern of globs) {
@@ -117,7 +118,10 @@ async function fromPrettierConfig(): Promise<{
 }
 
 async function main() {
-  const cli = parseArgs(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  if (argv[0] === 'init') return runInit(argv.slice(1));
+
+  const cli = parseArgs(argv);
 
   const pc = await fromPrettierConfig();
   const stylesheet = cli.stylesheet ?? pc.stylesheet;

package/src/html.ts

@@ -8,7 +8,7 @@
  *   - islands inside a quoted attribute value read as opaque atoms
  *
  * Skips HTML comments, doctype/CDATA, and the raw-text content of `script`/`style`/`textarea`/`title` elements —
- * their `script`/`style` content may contain strings like `class="..."` that must not be touched.
+ * their content may contain strings like `class="..."` that must not be touched.
  *
  * @see islands.ts - first pass; produces the islands consumed here.
  */

package/src/init.ts

@@ -0,0 +1,186 @@
+/**
+ * tailwind-sort-php init
+ *
+ * Installs the pre-commit hook: writes `.githooks/pre-commit` and points `core.hooksPath` at it.
+ * No-clobber unless `--force`; `--fix` installs the auto-fixing variant; `--dry-run` previews.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const HOOKS_DIR = '.githooks';
+const HOOK_PATH = `${HOOKS_DIR}/pre-commit`;
+
+/**
+ * Check-and-fail hook (default): names the unsorted files and blocks the commit; never writes.
+ */
+const HOOK_CHECK = `#!/bin/sh
+# Block commits with unsorted Tailwind classes in staged PHP files. Installed by \`tailwind-sort-php init\`.
+# Note: checks working-tree file contents, so partial staging (\`git add -p\`) can mis-report; see README.
+sorter=./node_modules/.bin/tailwind-sort-php
+[ -x "$sorter" ] || exit 0
+git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
+if git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter" --check; then
+  exit 0
+fi
+echo >&2
+echo "Unsorted Tailwind classes in staged PHP (see above)." >&2
+echo "Fix with: npx tailwind-sort-php (or: bunx tailwind-sort-php), then re-stage." >&2
+exit 1
+`;
+
+/**
+ * Auto-fix hook (--fix): sorts the staged files in place, then blocks the commit for review.
+ */
+const HOOK_FIX = `#!/bin/sh
+# Sort Tailwind classes in staged PHP files, then abort the commit so the changes can be reviewed and re-staged.
+# Rewrites working-tree files. Installed by \`tailwind-sort-php init --fix\`.
+# Note: with partial staging (\`git add -p\`), re-staging can pull in unrelated unstaged hunks; see README.
+sorter=./node_modules/.bin/tailwind-sort-php
+[ -x "$sorter" ] || exit 0
+git diff --cached --name-only --diff-filter=ACMR -- '*.php' | grep -q . || exit 0
+if git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter" --check >/dev/null 2>&1; then
+  exit 0
+fi
+git diff --cached --name-only -z --diff-filter=ACMR -- '*.php' | xargs -0 "$sorter"
+echo >&2
+echo "Sorted Tailwind classes in staged PHP (see above)." >&2
+echo "Review the changes, re-stage, and commit again." >&2
+exit 1
+`;
+
+interface InitCli {
+  fix: boolean;
+  force: boolean;
+  dryRun: boolean;
+}
+
+/**
+ * Parse `init` subcommand arguments.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ * @returns Parsed flags with defaults applied.
+ */
+function parseArgs(argv: string[]): InitCli {
+  const cli: InitCli = { fix: false, force: false, dryRun: false };
+  for (const a of argv) {
+    if (a === '--fix') cli.fix = true;
+    else if (a === '--force') cli.force = true;
+    else if (a === '--dry-run') cli.dryRun = true;
+    else {
+      console.error(`Unknown init option: ${a}`);
+      process.exit(2);
+    }
+  }
+  return cli;
+}
+
+/**
+ * Run a git command and capture its output.
+ *
+ * @param args Arguments passed to `git`.
+ * @returns Trimmed stdout, or `null` when git exits non-zero (unset config, not a repo, …).
+ */
+function git(args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Print an error to stderr and exit with status 1.
+ *
+ * @param message Error text explaining why init refused to proceed.
+ */
+function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+/**
+ * Run the `init` subcommand: install the pre-commit hook and point `core.hooksPath` at it.
+ *
+ * @param argv Arguments after the `init` subcommand name.
+ */
+export async function runInit(argv: string[]): Promise<void> {
+  const cli = parseArgs(argv);
+  const hookBody = cli.fix ? HOOK_FIX : HOOK_CHECK;
+  const variant = cli.fix ? 'fix' : 'check';
+
+  // Anchor everything at the repository root: a relative `core.hooksPath` resolves there,
+  // and the hook's `./node_modules/...` path assumes hooks run from it (they do, for pre-commit).
+  const top = git(['rev-parse', '--show-toplevel']);
+  if (top === null) fail('Not a git repository (or a bare one) — run init from inside a working tree.');
+  const gitDir = git(['rev-parse', '--absolute-git-dir'])!;
+  const hookAbs = join(top, HOOK_PATH);
+
+  // Decide whether `core.hooksPath` needs to change. Repointing it makes git ignore `.git/hooks` entirely,
+  // so refuse to silently disable hooks that already live there.
+  const hooksPath = git(['config', '--get', 'core.hooksPath']);
+  let setConfig = false;
+  if (hooksPath === null) {
+    const live = (await readdir(join(gitDir, 'hooks')).catch(() => [])).filter((f) => !f.endsWith('.sample'));
+    if (live.length > 0 && !cli.force) {
+      fail(
+        `Found existing hook(s) in .git/hooks: ${live.join(', ')}.\n` +
+          `Setting core.hooksPath would disable them. Move them into ${HOOKS_DIR}/ first, ` +
+          'or re-run with --force to proceed anyway.',
+      );
+    }
+    setConfig = true;
+  } else if (hooksPath !== HOOKS_DIR) {
+    if (!cli.force) {
+      fail(
+        `core.hooksPath is already set to "${hooksPath}" — add the hook there yourself, or re-run ` +
+          `with --force to repoint it to ${HOOKS_DIR}. Hook body:\n\n${hookBody}`,
+      );
+    }
+    setConfig = true;
+  }
+
+  // Decide whether the hook file needs writing; overwriting a differing hook needs --force.
+  const current = await readFile(hookAbs, 'utf8').catch(() => null);
+  let writeHook = current === null;
+  let repairMode = false;
+  if (current !== null && current !== hookBody) {
+    if (!cli.force) {
+      const installed =
+        current === HOOK_CHECK ? 'the check variant' : current === HOOK_FIX ? 'the --fix variant' : 'a custom hook';
+      fail(`${HOOK_PATH} already exists and differs (${installed} is installed). Re-run with --force to overwrite.`);
+    }
+    writeHook = true;
+  }
+  if (current === hookBody) {
+    // Content is already right; still repair a missing executable bit, or git silently skips the hook.
+    repairMode = ((await stat(hookAbs)).mode & 0o111) === 0;
+  }
+
+  const done: string[] = [];
+  if (writeHook) {
+    if (!cli.dryRun) {
+      await mkdir(join(top, HOOKS_DIR), { recursive: true });
+      await writeFile(hookAbs, hookBody);
+      await chmod(hookAbs, 0o755);
+    }
+    done.push(
+      cli.dryRun ? `would install ${HOOK_PATH} (${variant} variant)` : `installed ${HOOK_PATH} (${variant} variant)`,
+    );
+  }
+  if (repairMode) {
+    if (!cli.dryRun) await chmod(hookAbs, 0o755);
+    done.push(cli.dryRun ? `would make ${HOOK_PATH} executable` : `made ${HOOK_PATH} executable`);
+  }
+  if (setConfig) {
+    if (!cli.dryRun) git(['config', 'core.hooksPath', HOOKS_DIR]);
+    done.push(cli.dryRun ? `would set core.hooksPath = ${HOOKS_DIR}` : `set core.hooksPath = ${HOOKS_DIR}`);
+  }
+
+  if (done.length === 0) {
+    console.log(`Nothing to do — ${HOOK_PATH} (${variant} variant) is already installed.`);
+    return;
+  }
+  for (const line of done) console.log(line);
+}

package/src/islands.ts

@@ -104,7 +104,7 @@ function scanPhpBody(src: string, i: number): number {
     }
 
     // Double-quoted string.
-    // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer (documented).
+    // Limitation: nested double quotes in complex `{$a["k"]}` interpolation can desync the lexer; see README.
     if (c === '"') {
       i = scanQuoted(src, i + 1, '"');
       continue;