tailwindcss-patch 8.6.0 → 8.7.0

package/dist/cli.js

@@ -1,8 +1,23 @@
-"use strict";
+"use strict"; function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-var _chunkJ27TPXH5js = require('./chunk-J27TPXH5.js');
+
+
+var _chunkATKR3J24js = require('./chunk-ATKR3J24.js');
 
 // src/cli.ts
-var cli = _chunkJ27TPXH5js.createTailwindcssPatchCli.call(void 0, );
-cli.help();
-cli.parse();
+var _process = require('process'); var _process2 = _interopRequireDefault(_process);
+async function main() {
+  const cli = _chunkATKR3J24js.createTailwindcssPatchCli.call(void 0, );
+  cli.help();
+  cli.parse(_process2.default.argv, { run: false });
+  await cli.runMatchedCommand();
+}
+main().catch((error) => {
+  if (error instanceof _chunkATKR3J24js.ValidateCommandError) {
+    _process2.default.exitCode = error.exitCode;
+    return;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  _chunkATKR3J24js.logger_default.error(message);
+  _process2.default.exitCode = 1;
+});

package/dist/cli.mjs

@@ -1,8 +1,23 @@
 import {
-  createTailwindcssPatchCli
-} from "./chunk-RVSD53YX.mjs";
+  ValidateCommandError,
+  createTailwindcssPatchCli,
+  logger_default
+} from "./chunk-2YHCFHVA.mjs";
 
 // src/cli.ts
-var cli = createTailwindcssPatchCli();
-cli.help();
-cli.parse();
+import process from "process";
+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_default.error(message);
+  process.exitCode = 1;
+});

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { SourceEntry } from '@tailwindcss/oxide';
-import postcss, { Node, Rule } from 'postcss';
+import postcss, { Rule, Node } from 'postcss';
 import { Config } from 'tailwindcss';
 import { PackageResolvingOptions, PackageInfo } from 'local-pkg';
 import { TailwindLocatorOptions, TailwindNextOptions, getConfig } from '@tailwindcss-mangle/config';
@@ -30,11 +30,11 @@ interface CacheUserOptions {
     driver?: CacheDriver;
 }
 /**
- * Controls how extracted class lists are written to disk.
+ * Preferred options for extraction output behavior.
  */
-interface OutputUserOptions {
+interface TailwindExtractionUserOptions {
     /** Whether to produce an output file. */
-    enabled?: boolean;
+    write?: boolean;
     /** Optional absolute or relative path to the output file. */
     file?: string;
     /** Output format, defaults to JSON when omitted. */
@@ -44,6 +44,22 @@ interface OutputUserOptions {
     /** Whether to strip the universal selector (`*`) from the final list. */
     removeUniversalSelector?: boolean;
 }
+/**
+ * @deprecated Use `TailwindExtractionUserOptions`.
+ * Legacy output options kept for backward compatibility and will be removed in the next major version.
+ */
+interface OutputUserOptions {
+    /** @deprecated Use `extract.write` instead. */
+    enabled?: boolean;
+    /** @deprecated Use `extract.file` instead. */
+    file?: string;
+    /** @deprecated Use `extract.format` instead. */
+    format?: 'json' | 'lines';
+    /** @deprecated Use `extract.pretty` instead. */
+    pretty?: number | boolean;
+    /** @deprecated Use `extract.removeUniversalSelector` instead. */
+    removeUniversalSelector?: boolean;
+}
 /**
  * Options controlling how Tailwind contexts are exposed during runtime patching.
  */
@@ -59,18 +75,30 @@ interface ExtendLengthUnitsUserOptions extends Partial<ILengthUnitsPatchOptions>
     enabled?: boolean;
 }
 /**
- * Feature switches that toggle optional Tailwind patch capabilities.
+ * Preferred options for runtime patch behavior.
  */
-interface FeatureUserOptions {
+interface PatchApplyUserOptions {
+    /** Whether patched files can be overwritten on disk. */
+    overwrite?: boolean;
     /** Whether to expose runtime Tailwind contexts (or configure how they are exposed). */
     exposeContext?: boolean | ExposeContextUserOptions;
     /** Extends the length-unit patch or disables it entirely. */
     extendLengthUnits?: false | ExtendLengthUnitsUserOptions;
 }
+/**
+ * @deprecated Use `PatchApplyUserOptions`.
+ * Legacy nested feature options kept for backward compatibility and will be removed in the next major version.
+ */
+interface FeatureUserOptions {
+    /** @deprecated Use `apply.exposeContext` instead. */
+    exposeContext?: boolean | ExposeContextUserOptions;
+    /** @deprecated Use `apply.extendLengthUnits` instead. */
+    extendLengthUnits?: false | ExtendLengthUnitsUserOptions;
+}
 /**
  * Shared configuration used for Tailwind v2/v3 patching flows.
  */
-interface TailwindConfigUserOptions {
+interface TailwindRuntimeConfigUserOptions {
     /** Path to a Tailwind config file when auto-detection is insufficient. */
     config?: string;
     /** Custom working directory used when resolving config-relative paths. */
@@ -78,10 +106,16 @@ interface TailwindConfigUserOptions {
     /** Optional PostCSS plugin name to use instead of the default. */
     postcssPlugin?: string;
 }
+/**
+ * @deprecated Use `TailwindRuntimeConfigUserOptions`.
+ * Legacy naming kept for backward compatibility and will be removed in the next major version.
+ */
+interface TailwindConfigUserOptions extends TailwindRuntimeConfigUserOptions {
+}
 /**
  * Additional configuration specific to Tailwind CSS v4 extraction.
  */
-interface TailwindV4UserOptions {
+interface TailwindV4RuntimeUserOptions {
     /** Base directory used when resolving v4 content sources and configs. */
     base?: string;
     /** Raw CSS passed directly to the v4 design system. */
@@ -94,7 +128,7 @@ interface TailwindV4UserOptions {
 /**
  * High-level Tailwind patch configuration shared across versions.
  */
-interface TailwindUserOptions extends TailwindConfigUserOptions {
+interface TailwindcssUserOptions extends TailwindRuntimeConfigUserOptions {
     /**
      * Optional hint for picking the patch strategy.
      * When omitted we infer from the installed Tailwind CSS package version.
@@ -105,11 +139,17 @@ interface TailwindUserOptions extends TailwindConfigUserOptions {
     /** Package resolution options forwarded to `local-pkg`. */
     resolve?: PackageResolvingOptions;
     /** Overrides applied when patching Tailwind CSS v2. */
-    v2?: TailwindConfigUserOptions;
+    v2?: TailwindRuntimeConfigUserOptions;
     /** Overrides applied when patching Tailwind CSS v3. */
-    v3?: TailwindConfigUserOptions;
+    v3?: TailwindRuntimeConfigUserOptions;
     /** Options specific to Tailwind CSS v4 patching. */
-    v4?: TailwindV4UserOptions;
+    v4?: TailwindV4RuntimeUserOptions;
+}
+/**
+ * @deprecated Use `TailwindcssUserOptions`.
+ * Legacy naming kept for backward compatibility and will be removed in the next major version.
+ */
+interface TailwindUserOptions extends TailwindcssUserOptions {
 }
 /**
  * Root configuration consumed by the Tailwind CSS patch runner.
@@ -119,18 +159,33 @@ interface TailwindcssPatchOptions {
      * Base directory used when resolving Tailwind resources.
      * Defaults to `process.cwd()`.
      */
-    cwd?: string;
-    /** Whether to overwrite generated artifacts (e.g., caches, outputs). */
-    overwrite?: boolean;
-    /** Tailwind-specific configuration grouped by major version. */
-    tailwind?: TailwindUserOptions;
-    /** Feature toggles for optional helpers. */
-    features?: FeatureUserOptions;
+    projectRoot?: string;
+    /** Preferred Tailwind runtime configuration. */
+    tailwindcss?: TailwindcssUserOptions;
+    /** Preferred patch toggles. */
+    apply?: PatchApplyUserOptions;
+    /** Preferred extraction output settings. */
+    extract?: TailwindExtractionUserOptions;
     /** Optional function that filters final class names. */
     filter?: (className: string) => boolean;
     /** Cache configuration or boolean to enable/disable quickly. */
     cache?: boolean | CacheUserOptions;
-    /** Output configuration or boolean to inherits defaults. */
+    /**
+     * Base directory used when resolving Tailwind resources.
+     * Defaults to `process.cwd()`.
+     * @deprecated Use `projectRoot` instead.
+     */
+    cwd?: string;
+    /**
+     * Whether to overwrite generated artifacts (e.g., caches, outputs).
+     * @deprecated Use `apply.overwrite` instead.
+     */
+    overwrite?: boolean;
+    /** @deprecated Use `tailwindcss` instead. */
+    tailwind?: TailwindUserOptions;
+    /** @deprecated Use `apply` instead. */
+    features?: FeatureUserOptions;
+    /** @deprecated Use `extract` instead. */
     output?: OutputUserOptions;
 }
 /**
@@ -200,6 +255,60 @@ interface NormalizedTailwindcssPatchOptions {
     filter: (className: string) => boolean;
 }
 
+declare const CACHE_SCHEMA_VERSION = 2;
+declare const CACHE_FINGERPRINT_VERSION = 1;
+type CacheSchemaVersion = typeof CACHE_SCHEMA_VERSION;
+type CacheFingerprintVersion = typeof CACHE_FINGERPRINT_VERSION;
+type CacheClearScope = 'current' | 'all';
+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;
+}
+interface CacheContextDescriptor {
+    fingerprint: string;
+    metadata: CacheContextMetadata;
+}
+interface CacheIndexEntry {
+    context: CacheContextMetadata;
+    values: string[];
+    updatedAt: string;
+}
+interface CacheIndexFileV2 {
+    schemaVersion: CacheSchemaVersion;
+    updatedAt: string;
+    contexts: Record<string, CacheIndexEntry>;
+}
+type CacheReadReason = 'hit' | 'cache-disabled' | 'noop-driver' | 'file-missing' | 'context-not-found' | 'context-mismatch' | 'legacy-schema' | 'invalid-schema';
+interface CacheReadMeta {
+    hit: boolean;
+    reason: CacheReadReason;
+    fingerprint?: string;
+    schemaVersion?: number;
+    details: string[];
+}
+interface CacheReadResult {
+    data: Set<string>;
+    meta: CacheReadMeta;
+}
+interface CacheClearOptions {
+    scope?: CacheClearScope;
+}
+interface CacheClearResult {
+    scope: CacheClearScope;
+    filesRemoved: number;
+    entriesRemoved: number;
+    contextsRemoved: number;
+}
+
 type TailwindcssClassCacheEntry = Rule | {
     layer: string;
     options: Record<string, any>;
@@ -380,6 +489,7 @@ interface LegacyTailwindcssPatcherOptions {
 interface ExtractValidCandidatesOption {
     sources?: SourceEntry[];
     base?: string;
+    baseFallbacks?: string[];
     css?: string;
     cwd?: string;
 }
@@ -406,6 +516,7 @@ declare class TailwindcssPatcher {
     readonly options: NormalizedTailwindcssPatchOptions;
     readonly packageInfo: PackageInfo;
     readonly majorVersion: TailwindMajorVersion;
+    private readonly cacheContext;
     private readonly cacheStore;
     constructor(options?: TailwindcssPatcherInitOptions);
     patch(): Promise<PatchRunnerResult>;
@@ -413,6 +524,7 @@ declare class TailwindcssPatcher {
     getContexts(): TailwindcssRuntimeContext[];
     private runTailwindBuildIfNeeded;
     private collectClassSet;
+    private debugCacheRead;
     private mergeWithCache;
     private mergeWithCacheSync;
     getClassSet(): Promise<Set<string>>;
@@ -420,6 +532,7 @@ declare class TailwindcssPatcher {
     extract(options?: {
         write?: boolean;
     }): Promise<ExtractResult>;
+    clearCache(options?: CacheClearOptions): Promise<CacheClearResult>;
     extractValidCandidates: typeof extractValidCandidates;
     collectContentTokens(options?: {
         cwd?: string;
@@ -435,9 +548,15 @@ declare class TailwindcssPatcher {
 
 declare class CacheStore {
     private readonly options;
+    private readonly context?;
     private readonly driver;
+    private readonly lockPath;
     private memoryCache;
-    constructor(options: NormalizedCacheOptions);
+    private memoryIndex;
+    private lastReadMeta;
+    constructor(options: NormalizedCacheOptions, context?: CacheContextDescriptor | undefined);
+    private isContextAware;
+    private createEmptyIndex;
     private ensureDir;
     private ensureDirSync;
     private createTempPath;
@@ -445,16 +564,128 @@ declare class CacheStore {
     private replaceCacheFileSync;
     private cleanupTempFile;
     private cleanupTempFileSync;
+    private delay;
+    private acquireLock;
+    private releaseLockSyncOrAsync;
+    private acquireLockSync;
+    private withFileLock;
+    private withFileLockSync;
+    private normalizeContextEntry;
+    private normalizeIndexFile;
+    private readParsedCacheFile;
+    private readParsedCacheFileSync;
+    private findProjectMatch;
+    private writeIndexFile;
+    private writeIndexFileSync;
     write(data: Set<string>): Promise<string | undefined>;
     writeSync(data: Set<string>): string | undefined;
+    readWithMeta(): Promise<CacheReadResult>;
+    readWithMetaSync(): CacheReadResult;
     read(): Promise<Set<string>>;
     readSync(): Set<string>;
+    getLastReadMeta(): CacheReadMeta;
+    private countEntriesFromParsed;
+    clear(options?: CacheClearOptions): Promise<CacheClearResult>;
+    clearSync(options?: CacheClearOptions): CacheClearResult;
+    readIndexSnapshot(): CacheIndexFileV2 | undefined;
 }
 
+declare const MIGRATION_REPORT_KIND = "tw-patch-migrate-report";
+declare const MIGRATION_REPORT_SCHEMA_VERSION = 1;
+interface ConfigFileMigrationEntry {
+    file: string;
+    changed: boolean;
+    written: boolean;
+    rolledBack: boolean;
+    backupFile?: string;
+    changes: string[];
+}
+interface ConfigFileMigrationReport {
+    reportKind: typeof MIGRATION_REPORT_KIND;
+    schemaVersion: typeof MIGRATION_REPORT_SCHEMA_VERSION;
+    generatedAt: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+    cwd: string;
+    dryRun: boolean;
+    rollbackOnError: boolean;
+    backupDirectory?: string;
+    scannedFiles: number;
+    changedFiles: number;
+    writtenFiles: number;
+    backupsWritten: number;
+    unchangedFiles: number;
+    missingFiles: number;
+    entries: ConfigFileMigrationEntry[];
+}
+interface MigrateConfigFilesOptions {
+    cwd: string;
+    files?: string[];
+    dryRun?: boolean;
+    workspace?: boolean;
+    maxDepth?: number;
+    rollbackOnError?: boolean;
+    backupDir?: string;
+    include?: string[];
+    exclude?: string[];
+}
+interface RestoreConfigFilesOptions {
+    cwd: string;
+    reportFile: string;
+    dryRun?: boolean;
+    strict?: boolean;
+}
+interface RestoreConfigFilesResult {
+    cwd: string;
+    reportFile: string;
+    reportKind?: string;
+    reportSchemaVersion?: number;
+    dryRun: boolean;
+    strict: boolean;
+    scannedEntries: number;
+    restorableEntries: number;
+    restoredFiles: number;
+    missingBackups: number;
+    skippedEntries: number;
+    restored: string[];
+}
+declare function migrateConfigFiles(options: MigrateConfigFilesOptions): Promise<ConfigFileMigrationReport>;
+declare function restoreConfigFiles(options: RestoreConfigFilesOptions): Promise<RestoreConfigFilesResult>;
+
 declare const logger: consola.ConsolaInstance;
 
-type TailwindcssPatchCommand = 'install' | 'extract' | 'tokens' | 'init' | 'status';
+type TailwindcssPatchCommand = 'install' | 'extract' | 'tokens' | 'init' | 'migrate' | 'restore' | 'validate' | 'status';
 declare const tailwindcssPatchCommands: TailwindcssPatchCommand[];
+declare const VALIDATE_EXIT_CODES: {
+    readonly OK: 0;
+    readonly REPORT_INCOMPATIBLE: 21;
+    readonly MISSING_BACKUPS: 22;
+    readonly IO_ERROR: 23;
+    readonly UNKNOWN_ERROR: 24;
+};
+declare const VALIDATE_FAILURE_REASONS: readonly ["report-incompatible", "missing-backups", "io-error", "unknown-error"];
+type ValidateFailureReason = (typeof VALIDATE_FAILURE_REASONS)[number];
+interface ValidateFailureSummary {
+    reason: ValidateFailureReason;
+    exitCode: number;
+    message: string;
+}
+interface ValidateJsonSuccessPayload extends RestoreConfigFilesResult {
+    ok: true;
+}
+interface ValidateJsonFailurePayload {
+    ok: false;
+    reason: ValidateFailureReason;
+    exitCode: number;
+    message: string;
+}
+declare class ValidateCommandError extends Error {
+    reason: ValidateFailureReason;
+    exitCode: number;
+    constructor(summary: ValidateFailureSummary, options?: ErrorOptions);
+}
 type TokenOutputFormat = 'json' | 'lines' | 'grouped-json';
 type TokenGroupKey = 'relative' | 'absolute';
 type CacOptionConfig = Parameters<Command['option']>[2];
@@ -489,6 +720,29 @@ interface TokensCommandArgs extends BaseCommandArgs {
 }
 interface InitCommandArgs extends BaseCommandArgs {
 }
+interface MigrateCommandArgs extends BaseCommandArgs {
+    config?: string;
+    dryRun?: boolean;
+    workspace?: boolean;
+    maxDepth?: string | number;
+    include?: string | string[];
+    exclude?: string | string[];
+    reportFile?: string;
+    backupDir?: string;
+    check?: boolean;
+    json?: boolean;
+}
+interface RestoreCommandArgs extends BaseCommandArgs {
+    reportFile?: string;
+    dryRun?: boolean;
+    strict?: boolean;
+    json?: boolean;
+}
+interface ValidateCommandArgs extends BaseCommandArgs {
+    reportFile?: string;
+    strict?: boolean;
+    json?: boolean;
+}
 interface StatusCommandArgs extends BaseCommandArgs {
     json?: boolean;
 }
@@ -497,6 +751,9 @@ interface TailwindcssPatchCommandArgMap {
     extract: ExtractCommandArgs;
     tokens: TokensCommandArgs;
     init: InitCommandArgs;
+    migrate: MigrateCommandArgs;
+    restore: RestoreCommandArgs;
+    validate: ValidateCommandArgs;
     status: StatusCommandArgs;
 }
 interface TailwindcssPatchCommandResultMap {
@@ -504,6 +761,9 @@ interface TailwindcssPatchCommandResultMap {
     extract: ExtractResult;
     tokens: TailwindTokenReport;
     init: void;
+    migrate: ConfigFileMigrationReport;
+    restore: RestoreConfigFilesResult;
+    validate: RestoreConfigFilesResult;
     status: PatchStatusReport;
 }
 interface TailwindcssPatchCommandContext<TCommand extends TailwindcssPatchCommand> {
@@ -556,4 +816,4 @@ interface TailwindBuildOptions {
 }
 declare function runTailwindBuild(options: TailwindBuildOptions): Promise<postcss.Result<postcss.Root>>;
 
-export { CacheStore, type CacheStrategy, type ExtractResult, type ILengthUnitsPatchOptions, type NormalizedTailwindcssPatchOptions, type PatchCheckStatus, type PatchName, type PatchStatusEntry, type PatchStatusReport, type TailwindPatchRuntime, type TailwindTokenByFileMap, type TailwindTokenFileKey, type TailwindTokenLocation, type TailwindTokenReport, type TailwindcssClassCache, type TailwindcssPatchCliMountOptions, type TailwindcssPatchCliOptions, type TailwindcssPatchCommand, type TailwindcssPatchCommandContext, type TailwindcssPatchCommandHandler, type TailwindcssPatchCommandHandlerMap, type TailwindcssPatchCommandOptionDefinition, type TailwindcssPatchCommandOptions, type TailwindcssPatchOptions, TailwindcssPatcher, type TailwindcssRuntimeContext, collectClassesFromContexts, collectClassesFromTailwindV4, createTailwindcssPatchCli, extractProjectCandidatesWithPositions, extractRawCandidates, extractRawCandidatesWithPositions, extractValidCandidates, getPatchStatusReport, groupTokensByFile, loadRuntimeContexts, logger, mountTailwindcssPatchCommands, normalizeOptions, runTailwindBuild, tailwindcssPatchCommands };
+export { type CacheClearOptions, type CacheClearResult, type CacheClearScope, type CacheContextMetadata, type CacheReadMeta, CacheStore, type CacheStrategy, type ConfigFileMigrationEntry, type ConfigFileMigrationReport, type ExtractResult, type ILengthUnitsPatchOptions, MIGRATION_REPORT_KIND, MIGRATION_REPORT_SCHEMA_VERSION, type MigrateConfigFilesOptions, type NormalizedTailwindcssPatchOptions, type PatchCheckStatus, type PatchName, type PatchStatusEntry, type PatchStatusReport, type RestoreConfigFilesOptions, type RestoreConfigFilesResult, type TailwindPatchRuntime, type TailwindTokenByFileMap, type TailwindTokenFileKey, type TailwindTokenLocation, type TailwindTokenReport, type TailwindcssClassCache, type TailwindcssPatchCliMountOptions, type TailwindcssPatchCliOptions, type TailwindcssPatchCommand, type TailwindcssPatchCommandContext, type TailwindcssPatchCommandHandler, type TailwindcssPatchCommandHandlerMap, type TailwindcssPatchCommandOptionDefinition, type TailwindcssPatchCommandOptions, type TailwindcssPatchOptions, TailwindcssPatcher, type TailwindcssRuntimeContext, VALIDATE_EXIT_CODES, VALIDATE_FAILURE_REASONS, ValidateCommandError, type ValidateFailureReason, type ValidateFailureSummary, type ValidateJsonFailurePayload, type ValidateJsonSuccessPayload, collectClassesFromContexts, collectClassesFromTailwindV4, createTailwindcssPatchCli, extractProjectCandidatesWithPositions, extractRawCandidates, extractRawCandidatesWithPositions, extractValidCandidates, getPatchStatusReport, groupTokensByFile, loadRuntimeContexts, logger, migrateConfigFiles, mountTailwindcssPatchCommands, normalizeOptions, restoreConfigFiles, runTailwindBuild, tailwindcssPatchCommands };