tailwindcss-patch 9.0.0-alpha.1 → 9.0.0-alpha.3

package/src/cache/types.ts

@@ -0,0 +1,71 @@
+export const CACHE_SCHEMA_VERSION = 2
+export const CACHE_FINGERPRINT_VERSION = 1
+
+export type CacheSchemaVersion = typeof CACHE_SCHEMA_VERSION
+export type CacheFingerprintVersion = typeof CACHE_FINGERPRINT_VERSION
+export type CacheClearScope = 'current' | 'all'
+
+export interface CacheContextMetadata {
+  fingerprintVersion: CacheFingerprintVersion
+  projectRootRealpath: string
+  processCwdRealpath: string
+  cacheCwdRealpath: string
+  tailwindConfigPath?: string
+  tailwindConfigMtimeMs?: number
+  tailwindPackageRootRealpath: string
+  tailwindPackageVersion: string
+  patcherVersion: string
+  majorVersion: 2 | 3 | 4
+  optionsHash: string
+}
+
+export interface CacheContextDescriptor {
+  fingerprint: string
+  metadata: CacheContextMetadata
+}
+
+export interface CacheIndexEntry {
+  context: CacheContextMetadata
+  values: string[]
+  updatedAt: string
+}
+
+export interface CacheIndexFileV2 {
+  schemaVersion: CacheSchemaVersion
+  updatedAt: string
+  contexts: Record<string, CacheIndexEntry>
+}
+
+export type CacheReadReason
+  = 'hit'
+    | 'cache-disabled'
+    | 'noop-driver'
+    | 'file-missing'
+    | 'context-not-found'
+    | 'context-mismatch'
+    | 'legacy-schema'
+    | 'invalid-schema'
+
+export interface CacheReadMeta {
+  hit: boolean
+  reason: CacheReadReason
+  fingerprint?: string
+  schemaVersion?: number
+  details: string[]
+}
+
+export interface CacheReadResult {
+  data: Set<string>
+  meta: CacheReadMeta
+}
+
+export interface CacheClearOptions {
+  scope?: CacheClearScope
+}
+
+export interface CacheClearResult {
+  scope: CacheClearScope
+  filesRemoved: number
+  entriesRemoved: number
+  contextsRemoved: number
+}

package/src/cli.bundle.ts

@@ -0,0 +1,20 @@
+import process from 'node:process'
+import { createTailwindcssPatchCli, ValidateCommandError } from './index.bundle'
+import logger from './logger'
+
+async function main() {
+  const cli = createTailwindcssPatchCli()
+  cli.help()
+  cli.parse(process.argv, { run: false })
+  await cli.runMatchedCommand()
+}
+
+main().catch((error) => {
+  if (error instanceof ValidateCommandError) {
+    process.exitCode = error.exitCode
+    return
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  logger.error(message)
+  process.exitCode = 1
+})

package/src/cli.ts

@@ -0,0 +1,20 @@
+import process from 'node:process'
+import { createTailwindcssPatchCli, ValidateCommandError } from './commands/cli'
+import logger from './logger'
+
+async function main() {
+  const cli = createTailwindcssPatchCli()
+  cli.help()
+  cli.parse(process.argv, { run: false })
+  await cli.runMatchedCommand()
+}
+
+main().catch((error) => {
+  if (error instanceof ValidateCommandError) {
+    process.exitCode = error.exitCode
+    return
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  logger.error(message)
+  process.exitCode = 1
+})

package/src/commands/basic-handlers.ts

@@ -0,0 +1,145 @@
+import type { TailwindCssPatchOptions } from '../types'
+import type { TokenGroupKey, TokenOutputFormat } from './token-output'
+import type { TailwindcssPatchCommandContext } from './types'
+
+import process from 'node:process'
+import fs from 'fs-extra'
+import path from 'pathe'
+import { TailwindcssPatcher } from '../api/tailwindcss-patcher'
+import { loadWorkspaceConfigModule } from '../config/workspace'
+import { groupTokensByFile } from '../extraction/candidate-extractor'
+import logger from '../logger'
+import {
+  DEFAULT_TOKEN_REPORT,
+  formatGroupedPreview,
+  formatTokenLine,
+  TOKEN_FORMATS,
+} from './token-output'
+
+const DEFAULT_CONFIG_NAME = 'tailwindcss-mangle'
+
+export async function installCommandDefaultHandler(_ctx: TailwindcssPatchCommandContext<'install'>) {
+  const patcher = await _ctx.createPatcher()
+  await patcher.patch()
+  logger.success('Tailwind CSS runtime patched successfully.')
+}
+
+export async function extractCommandDefaultHandler(ctx: TailwindcssPatchCommandContext<'extract'>) {
+  const { args } = ctx
+  const overrides: TailwindCssPatchOptions = {}
+  let hasOverrides = false
+
+  if (args.output || args.format) {
+    overrides.extract = {
+      ...(args.output === undefined ? {} : { file: args.output }),
+      ...(args.format === undefined ? {} : { format: args.format }),
+    }
+    hasOverrides = true
+  }
+
+  if (args.css) {
+    overrides.tailwindcss = {
+      v4: {
+        cssEntries: [args.css],
+      },
+    }
+    hasOverrides = true
+  }
+
+  const patcher = await ctx.createPatcher(hasOverrides ? overrides : undefined)
+  const extractOptions = args.write === undefined ? {} : { write: args.write }
+  const result = await patcher.extract(extractOptions)
+
+  if (result.filename) {
+    logger.success(`Collected ${result.classList.length} classes → ${result.filename}`)
+  }
+  else {
+    logger.success(`Collected ${result.classList.length} classes.`)
+  }
+
+  return result
+}
+
+export async function tokensCommandDefaultHandler(ctx: TailwindcssPatchCommandContext<'tokens'>) {
+  const { args } = ctx
+  const patcher = await ctx.createPatcher()
+  const report = await patcher.collectContentTokens()
+
+  const shouldWrite = args.write ?? true
+  let format: TokenOutputFormat = args.format ?? 'json'
+  if (!TOKEN_FORMATS.includes(format)) {
+    format = 'json'
+  }
+  const targetFile = args.output ?? DEFAULT_TOKEN_REPORT
+  const groupKey: TokenGroupKey = args.groupKey === 'absolute' ? 'absolute' : 'relative'
+  const buildGrouped = () =>
+    groupTokensByFile(report, {
+      key: groupKey,
+      stripAbsolutePaths: groupKey !== 'absolute',
+    })
+  const grouped = format === 'grouped-json' ? buildGrouped() : null
+  const resolveGrouped = () => grouped ?? buildGrouped()
+
+  if (shouldWrite) {
+    const target = path.resolve(targetFile)
+    await fs.ensureDir(path.dirname(target))
+    if (format === 'json') {
+      await fs.writeJSON(target, report, { spaces: 2 })
+    }
+    else if (format === 'grouped-json') {
+      await fs.writeJSON(target, resolveGrouped(), { spaces: 2 })
+    }
+    else {
+      const lines = report.entries.map(formatTokenLine)
+      await fs.writeFile(target, `${lines.join('\n')}\n`, 'utf8')
+    }
+    logger.success(`Collected ${report.entries.length} tokens (${format}) → ${target.replace(process.cwd(), '.')}`)
+  }
+  else {
+    logger.success(`Collected ${report.entries.length} tokens from ${report.filesScanned} files.`)
+    if (format === 'lines') {
+      const preview = report.entries.slice(0, 5).map(formatTokenLine).join('\n')
+      if (preview) {
+        logger.log('')
+        logger.info(preview)
+        if (report.entries.length > 5) {
+          logger.info(`…and ${report.entries.length - 5} more.`)
+        }
+      }
+    }
+    else if (format === 'grouped-json') {
+      const map = resolveGrouped()
+      const { preview, moreFiles } = formatGroupedPreview(map)
+      if (preview) {
+        logger.log('')
+        logger.info(preview)
+        if (moreFiles > 0) {
+          logger.info(`…and ${moreFiles} more files.`)
+        }
+      }
+    }
+    else {
+      const previewEntries = report.entries.slice(0, 3)
+      if (previewEntries.length) {
+        logger.log('')
+        logger.info(JSON.stringify(previewEntries, null, 2))
+      }
+    }
+  }
+
+  if (report.skippedFiles.length) {
+    logger.warn('Skipped files:')
+    for (const skipped of report.skippedFiles) {
+      logger.warn(`  • ${skipped.file} (${skipped.reason})`)
+    }
+  }
+
+  return report
+}
+
+export async function initCommandDefaultHandler(ctx: TailwindcssPatchCommandContext<'init'>) {
+  const configModule = await loadWorkspaceConfigModule()
+  await configModule.initConfig(ctx.cwd)
+  const configName = configModule.CONFIG_NAME || DEFAULT_CONFIG_NAME
+  logger.success(`✨ ${configName}.config.ts initialized!`)
+}

package/src/commands/cli.ts

@@ -0,0 +1,56 @@
+import type { CAC } from 'cac'
+import type {
+  TailwindcssPatchCliMountOptions,
+  TailwindcssPatchCliOptions,
+} from './types'
+
+import cac from 'cac'
+import { buildDefaultCommandDefinitions } from './command-definitions'
+import { registerTailwindcssPatchCommand } from './command-registrar'
+import { tailwindcssPatchCommands } from './types'
+import {
+  VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
+  ValidateCommandError,
+} from './validate'
+
+export {
+  tailwindcssPatchCommands,
+  VALIDATE_EXIT_CODES,
+  VALIDATE_FAILURE_REASONS,
+  ValidateCommandError,
+}
+export type {
+  TailwindcssPatchCliMountOptions,
+  TailwindcssPatchCliOptions,
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandContext,
+  TailwindcssPatchCommandHandler,
+  TailwindcssPatchCommandHandlerMap,
+  TailwindcssPatchCommandOptionDefinition,
+  TailwindcssPatchCommandOptions,
+} from './types'
+export type {
+  ValidateFailureReason,
+  ValidateFailureSummary,
+  ValidateJsonFailurePayload,
+  ValidateJsonSuccessPayload,
+} from './validate'
+
+export function mountTailwindcssPatchCommands(cli: CAC, options: TailwindcssPatchCliMountOptions = {}) {
+  const prefix = options.commandPrefix ?? ''
+  const selectedCommands = options.commands ?? tailwindcssPatchCommands
+  const defaultDefinitions = buildDefaultCommandDefinitions()
+
+  for (const name of selectedCommands) {
+    registerTailwindcssPatchCommand(cli, name, options, prefix, defaultDefinitions)
+  }
+
+  return cli
+}
+
+export function createTailwindcssPatchCli(options: TailwindcssPatchCliOptions = {}) {
+  const cli = cac(options.name ?? 'tw-patch')
+  mountTailwindcssPatchCommands(cli, options.mountOptions)
+  return cli
+}

package/src/commands/command-context.ts

@@ -0,0 +1,77 @@
+import type { CAC, Command } from 'cac'
+import type { TailwindcssConfigResult } from '../config/workspace'
+import type { TailwindCssPatchOptions } from '../types'
+import type {
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandArgMap,
+  TailwindcssPatchCommandContext,
+} from './types'
+
+import process from 'node:process'
+import path from 'pathe'
+import { TailwindcssPatcher } from '../api/tailwindcss-patcher'
+import { loadPatchOptionsForWorkspace, loadWorkspaceConfigModule } from '../config/workspace'
+import logger from '../logger'
+
+export function resolveCommandCwd(rawCwd?: string) {
+  if (!rawCwd) {
+    return process.cwd()
+  }
+  return path.resolve(rawCwd)
+}
+
+export function createMemoizedPromiseRunner<TResult>(factory: () => Promise<TResult>) {
+  let promise: Promise<TResult> | undefined
+  return () => {
+    if (!promise) {
+      promise = factory()
+    }
+    return promise
+  }
+}
+
+export function createTailwindcssPatchCommandContext<TCommand extends TailwindcssPatchCommand>(
+  cli: CAC,
+  command: Command,
+  commandName: TCommand,
+  args: TailwindcssPatchCommandArgMap[TCommand],
+  cwd: string,
+): TailwindcssPatchCommandContext<TCommand> {
+  const loadCachedConfig = createMemoizedPromiseRunner<TailwindcssConfigResult>(() =>
+    loadWorkspaceConfigModule().then(mod => mod.getConfig(cwd)),
+  )
+  const loadCachedPatchOptions = createMemoizedPromiseRunner<TailwindCssPatchOptions>(() =>
+    loadPatchOptionsForWorkspace(cwd),
+  )
+  const createCachedPatcher = createMemoizedPromiseRunner<TailwindcssPatcher>(async () => {
+    const patchOptions = await loadCachedPatchOptions()
+    return new TailwindcssPatcher(patchOptions)
+  })
+
+  const loadPatchOptionsForContext = (overrides?: TailwindCssPatchOptions) => {
+    if (overrides) {
+      return loadPatchOptionsForWorkspace(cwd, overrides)
+    }
+    return loadCachedPatchOptions()
+  }
+
+  const createPatcherForContext = async (overrides?: TailwindCssPatchOptions) => {
+    if (overrides) {
+      const patchOptions = await loadPatchOptionsForWorkspace(cwd, overrides)
+      return new TailwindcssPatcher(patchOptions)
+    }
+    return createCachedPatcher()
+  }
+
+  return {
+    cli,
+    command,
+    commandName,
+    args,
+    cwd,
+    logger,
+    loadConfig: loadCachedConfig,
+    loadPatchOptions: loadPatchOptionsForContext,
+    createPatcher: createPatcherForContext,
+  }
+}

package/src/commands/command-definitions.ts

@@ -0,0 +1,102 @@
+import type { TailwindcssPatchCommand, TailwindcssPatchCommandOptionDefinition } from './types'
+
+import process from 'node:process'
+import { DEFAULT_TOKEN_REPORT } from './token-output'
+
+export interface TailwindcssPatchCommandDefinition {
+  description: string
+  optionDefs: TailwindcssPatchCommandOptionDefinition[]
+}
+
+export type TailwindcssPatchCommandDefinitions = Record<TailwindcssPatchCommand, TailwindcssPatchCommandDefinition>
+
+function createCwdOptionDefinition(description: string = 'Working directory'): TailwindcssPatchCommandOptionDefinition {
+  return {
+    flags: '--cwd <dir>',
+    description,
+    config: { default: process.cwd() },
+  }
+}
+
+export function buildDefaultCommandDefinitions(): TailwindcssPatchCommandDefinitions {
+  return {
+    install: {
+      description: 'Apply Tailwind CSS runtime patches',
+      optionDefs: [createCwdOptionDefinition()],
+    },
+    extract: {
+      description: 'Collect generated class names into a cache file',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--output <file>', description: 'Override output file path' },
+        { flags: '--format <format>', description: 'Output format (json|lines)' },
+        { flags: '--css <file>', description: 'Tailwind CSS entry CSS when using v4' },
+        { flags: '--no-write', description: 'Skip writing to disk' },
+      ],
+    },
+    tokens: {
+      description: 'Extract Tailwind tokens with file/position metadata',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--output <file>', description: 'Override output file path', config: { default: DEFAULT_TOKEN_REPORT } },
+        {
+          flags: '--format <format>',
+          description: 'Output format (json|lines|grouped-json)',
+          config: { default: 'json' },
+        },
+        {
+          flags: '--group-key <key>',
+          description: 'Grouping key for grouped-json output (relative|absolute)',
+          config: { default: 'relative' },
+        },
+        { flags: '--no-write', description: 'Skip writing to disk' },
+      ],
+    },
+    init: {
+      description: 'Generate a tailwindcss-patch config file',
+      optionDefs: [createCwdOptionDefinition()],
+    },
+    migrate: {
+      description: 'Migrate deprecated config fields to modern options',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--config <file>', description: 'Migrate a specific config file path' },
+        { flags: '--workspace', description: 'Scan workspace recursively for config files' },
+        { flags: '--max-depth <n>', description: 'Maximum recursion depth for --workspace', config: { default: 6 } },
+        { flags: '--include <glob>', description: 'Only migrate files that match this glob (repeatable)' },
+        { flags: '--exclude <glob>', description: 'Skip files that match this glob (repeatable)' },
+        { flags: '--report-file <file>', description: 'Write migration report JSON to a file' },
+        { flags: '--backup-dir <dir>', description: 'Write pre-migration backups into this directory' },
+        { flags: '--check', description: 'Exit with an error when migration changes are required' },
+        { flags: '--json', description: 'Print the migration report as JSON' },
+        { flags: '--dry-run', description: 'Preview changes without writing files' },
+      ],
+    },
+    restore: {
+      description: 'Restore config files from a previous migration report backup snapshot',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--report-file <file>', description: 'Migration report file generated by migrate' },
+        { flags: '--dry-run', description: 'Preview restore targets without writing files' },
+        { flags: '--strict', description: 'Fail when any backup file is missing' },
+        { flags: '--json', description: 'Print the restore result as JSON' },
+      ],
+    },
+    validate: {
+      description: 'Validate migration report compatibility without modifying files',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--report-file <file>', description: 'Migration report file to validate' },
+        { flags: '--strict', description: 'Fail when any backup file is missing' },
+        { flags: '--json', description: 'Print validation result as JSON' },
+      ],
+    },
+    status: {
+      description: 'Check which Tailwind patches are applied',
+      optionDefs: [
+        createCwdOptionDefinition(),
+        { flags: '--json', description: 'Print a JSON report of patch status' },
+      ],
+    },
+  }
+}

package/src/commands/command-metadata.ts

@@ -0,0 +1,68 @@
+import type { Command } from 'cac'
+import type { TailwindcssPatchCommandDefinitions } from './command-definitions'
+import type {
+  TailwindcssPatchCliMountOptions,
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandOptionDefinition,
+  TailwindcssPatchCommandOptions,
+} from './types'
+
+function addPrefixIfMissing(value: string, prefix: string) {
+  if (!prefix || value.startsWith(prefix)) {
+    return value
+  }
+  return `${prefix}${value}`
+}
+
+function resolveCommandNames(
+  command: TailwindcssPatchCommand,
+  mountOptions: TailwindcssPatchCliMountOptions,
+  prefix: string,
+) {
+  const override = mountOptions.commandOptions?.[command]
+  const baseName = override?.name ?? command
+  const name = addPrefixIfMissing(baseName, prefix)
+  const aliases = (override?.aliases ?? []).map(alias => addPrefixIfMissing(alias, prefix))
+  return { name, aliases }
+}
+
+function resolveOptionDefinitions(
+  defaults: TailwindcssPatchCommandOptionDefinition[],
+  override?: TailwindcssPatchCommandOptions,
+) {
+  if (!override) {
+    return defaults
+  }
+
+  const appendDefaults = override.appendDefaultOptions ?? true
+  const customDefs = override.optionDefs ?? []
+  if (!appendDefaults) {
+    return customDefs
+  }
+
+  if (customDefs.length === 0) {
+    return defaults
+  }
+
+  return [...defaults, ...customDefs]
+}
+
+export function resolveCommandMetadata(
+  command: TailwindcssPatchCommand,
+  mountOptions: TailwindcssPatchCliMountOptions,
+  prefix: string,
+  defaults: TailwindcssPatchCommandDefinitions,
+) {
+  const names = resolveCommandNames(command, mountOptions, prefix)
+  const definition = defaults[command]
+  const override = mountOptions.commandOptions?.[command]
+  const description = override?.description ?? definition.description
+  const optionDefs = resolveOptionDefinitions(definition.optionDefs, override)
+  return { ...names, description, optionDefs }
+}
+
+export function applyCommandOptions(command: Command, optionDefs: TailwindcssPatchCommandOptionDefinition[]) {
+  for (const option of optionDefs) {
+    command.option(option.flags, option.description ?? '', option.config)
+  }
+}

package/src/commands/command-registrar.ts

@@ -0,0 +1,39 @@
+import type { CAC } from 'cac'
+import type { TailwindcssPatchCommandDefinitions } from './command-definitions'
+import type {
+  TailwindcssPatchCliMountOptions,
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandArgMap,
+  TailwindcssPatchCommandDefaultHandlerMap,
+} from './types'
+
+import {
+  applyCommandOptions,
+  resolveCommandMetadata,
+} from './command-metadata'
+import { runWithCommandHandler } from './command-runtime'
+import { defaultCommandHandlers } from './default-handler-map'
+
+export function registerTailwindcssPatchCommand<TCommand extends TailwindcssPatchCommand>(
+  cli: CAC,
+  commandName: TCommand,
+  options: TailwindcssPatchCliMountOptions,
+  prefix: string,
+  defaultDefinitions: TailwindcssPatchCommandDefinitions,
+) {
+  const metadata = resolveCommandMetadata(commandName, options, prefix, defaultDefinitions)
+  const command = cli.command(metadata.name, metadata.description)
+  applyCommandOptions(command, metadata.optionDefs)
+  command.action(async (args: TailwindcssPatchCommandArgMap[TCommand]) => {
+    const defaultHandler = defaultCommandHandlers[commandName] as TailwindcssPatchCommandDefaultHandlerMap[TCommand]
+    return runWithCommandHandler(
+      cli,
+      command,
+      commandName,
+      args,
+      options.commandHandlers?.[commandName],
+      defaultHandler,
+    )
+  })
+  metadata.aliases.forEach(alias => command.alias(alias))
+}

package/src/commands/command-runtime.ts

@@ -0,0 +1,33 @@
+import type { CAC, Command } from 'cac'
+import type {
+  TailwindcssPatchCommand,
+  TailwindcssPatchCommandArgMap,
+  TailwindcssPatchCommandContext,
+  TailwindcssPatchCommandHandler,
+  TailwindcssPatchCommandResultMap,
+} from './types'
+
+import {
+  createMemoizedPromiseRunner,
+  createTailwindcssPatchCommandContext,
+  resolveCommandCwd,
+} from './command-context'
+
+export function runWithCommandHandler<TCommand extends TailwindcssPatchCommand>(
+  cli: CAC,
+  command: Command,
+  commandName: TCommand,
+  args: TailwindcssPatchCommandArgMap[TCommand],
+  handler: TailwindcssPatchCommandHandler<TCommand> | undefined,
+  defaultHandler: (
+    context: TailwindcssPatchCommandContext<TCommand>,
+  ) => Promise<TailwindcssPatchCommandResultMap[TCommand]>,
+) {
+  const cwd = resolveCommandCwd(args.cwd)
+  const context = createTailwindcssPatchCommandContext(cli, command, commandName, args, cwd)
+  const runDefault = createMemoizedPromiseRunner(() => defaultHandler(context))
+  if (!handler) {
+    return runDefault()
+  }
+  return handler(context, runDefault)
+}

package/src/commands/default-handler-map.ts

@@ -0,0 +1,25 @@
+import type { TailwindcssPatchCommandDefaultHandlerMap } from './types'
+
+import {
+  extractCommandDefaultHandler,
+  initCommandDefaultHandler,
+  installCommandDefaultHandler,
+  tokensCommandDefaultHandler,
+} from './basic-handlers'
+import {
+  migrateCommandDefaultHandler,
+} from './migrate-handler'
+import { restoreCommandDefaultHandler } from './restore-handler'
+import { statusCommandDefaultHandler } from './status-handler'
+import { validateCommandDefaultHandler } from './validate-handler'
+
+export const defaultCommandHandlers = {
+  install: installCommandDefaultHandler,
+  extract: extractCommandDefaultHandler,
+  tokens: tokensCommandDefaultHandler,
+  init: initCommandDefaultHandler,
+  migrate: migrateCommandDefaultHandler,
+  restore: restoreCommandDefaultHandler,
+  validate: validateCommandDefaultHandler,
+  status: statusCommandDefaultHandler,
+} satisfies TailwindcssPatchCommandDefaultHandlerMap