feat(tailwindcss-patch): expose restore report metadata in json

Author: sonofmagic

.changeset/tender-houses-fly.md

@@ -0,0 +1,9 @@
+---
+"tailwindcss-patch": patch
+---
+
+Improve restore JSON observability for migration reports.
+
+- expose `reportKind` and `reportSchemaVersion` in `tw-patch restore --json` output when report metadata is present
+- keep compatibility with legacy reports that do not contain schema metadata
+- add unit tests for metadata and legacy restore report behavior

packages/tailwindcss-patch/MIGRATION.md

@@ -91,6 +91,7 @@ Migration mapping:
 - `tw-patch restore` can restore config files from a migration report (`backupFile` entries) with optional `--dry-run`, `--strict`, and `--json`.
 - Migration reports now include envelope metadata: `reportKind`, `schemaVersion`, `generatedAt`, and `tool` (`name` / `version`).
 - `tw-patch restore` validates report metadata when present, rejects unknown kinds/newer schema versions, and keeps legacy metadata-free reports backward compatible.
+- `tw-patch restore --json` now exposes report metadata fields (`reportKind`, `reportSchemaVersion`) when available for easier diagnostics.
 - Commands resolve configuration from `tailwindcss-patch.config.ts` via `@tailwindcss-mangle/config`. Existing configuration files continue to work without changes.
 
 ## 4. Cache handling

packages/tailwindcss-patch/README-cn.md

@@ -90,6 +90,7 @@ CLI 会通过 `@tailwindcss-mangle/config` 加载 `tailwindcss-patch.config.ts`
 | `--json`               | 输出 JSON 格式的恢复结果。                                   |
 
 `tw-patch restore` 在报告包含元数据时会执行 schema 校验。若 `reportKind` 不匹配或 `schemaVersion` 高于当前支持版本，会拒绝恢复；不包含该元数据的历史报告仍保持兼容。
+使用 `--json` 时，恢复结果会在报告含元数据时附带 `reportKind` / `reportSchemaVersion` 字段。
 
 ### `tokens` 常用参数
 

packages/tailwindcss-patch/README.md

@@ -147,6 +147,7 @@ Migration reports now include envelope metadata: `reportKind`, `schemaVersion`,
 | `--json`              | Print restore summary as JSON.                                    |
 
 `tw-patch restore` validates report schema metadata when available. Reports with unsupported `reportKind` or newer `schemaVersion` are rejected to avoid unsafe restores. Legacy reports without metadata are still supported.
+With `--json`, restore output includes `reportKind` / `reportSchemaVersion` when report metadata is present.
 
 ### Token report options
 

packages/tailwindcss-patch/src/cli/migrate-config.ts

@@ -96,6 +96,7 @@ export interface RestoreConfigFilesOptions {
 export interface RestoreConfigFilesResult {
   cwd: string
   reportFile: string
+  reportKind?: string
   reportSchemaVersion?: number
   dryRun: boolean
   strict: boolean
@@ -718,6 +719,7 @@ export async function restoreConfigFiles(options: RestoreConfigFilesOptions): Pr
   return {
     cwd,
     reportFile,
+    ...(report.reportKind === undefined ? {} : { reportKind: report.reportKind }),
     ...(report.schemaVersion === undefined ? {} : { reportSchemaVersion: report.schemaVersion }),
     dryRun,
     strict,

packages/tailwindcss-patch/test/cli.migrate-config.test.ts

@@ -296,6 +296,8 @@ describe('restoreConfigFiles', () => {
       await fs.outputFile(target, `export default { registry: { extract: { file: 'x.json' } } }\n`, 'utf8')
       await fs.outputFile(backup, `export default { registry: { output: { file: 'x.json' } } }\n`, 'utf8')
       await fs.outputJSON(reportPath, {
+        reportKind: 'tw-patch-migrate-report',
+        schemaVersion: 1,
         entries: [{ file: target, backupFile: backup }],
       }, { spaces: 2 })
 
@@ -304,7 +306,8 @@ describe('restoreConfigFiles', () => {
         reportFile: '.tw-patch/migrate-report.json',
       })
 
-      expect(result.reportSchemaVersion).toBeUndefined()
+      expect(result.reportKind).toBe('tw-patch-migrate-report')
+      expect(result.reportSchemaVersion).toBe(1)
       expect(result.restoredFiles).toBe(1)
       expect(result.missingBackups).toBe(0)
       const restored = await fs.readFile(target, 'utf8')
@@ -344,6 +347,32 @@ describe('restoreConfigFiles', () => {
     }
   })
 
+  it('supports legacy restore report without schema metadata', async () => {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'tw-patch-restore-legacy-'))
+    const target = path.resolve(cwd, 'tailwindcss-patch.config.ts')
+    const backup = path.resolve(cwd, '.tw-patch/migrate-backups/tailwindcss-patch.config.ts.bak')
+    const reportPath = path.resolve(cwd, '.tw-patch/migrate-report.json')
+    try {
+      await fs.outputFile(target, `export default { registry: { extract: { file: 'x.json' } } }\n`, 'utf8')
+      await fs.outputFile(backup, `export default { registry: { output: { file: 'x.json' } } }\n`, 'utf8')
+      await fs.outputJSON(reportPath, {
+        entries: [{ file: target, backupFile: backup }],
+      }, { spaces: 2 })
+
+      const result = await restoreConfigFiles({
+        cwd,
+        reportFile: '.tw-patch/migrate-report.json',
+      })
+
+      expect(result.reportKind).toBeUndefined()
+      expect(result.reportSchemaVersion).toBeUndefined()
+      expect(result.restoredFiles).toBe(1)
+    }
+    finally {
+      await fs.remove(cwd)
+    }
+  })
+
   it('throws in strict mode when backup files are missing', async () => {
     const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'tw-patch-restore-strict-'))
     const target = path.resolve(cwd, 'tailwindcss-patch.config.ts')

packages/tailwindcss-patch/test/cli.mount.test.ts

@@ -32,6 +32,8 @@ const { migrateConfigFilesMock, restoreConfigFilesMock } = vi.hoisted(() => {
     restoreConfigFilesMock: vi.fn(async () => ({
       cwd: '/tmp/project',
       reportFile: '/tmp/project/.tw-patch/migrate-report.json',
+      reportKind: 'tw-patch-migrate-report',
+      reportSchemaVersion: 1,
       dryRun: false,
       strict: false,
       scannedEntries: 1,
@@ -464,6 +466,8 @@ describe('mountTailwindcssPatchCommands', () => {
     expect(logger.log).toHaveBeenCalledWith(JSON.stringify({
       cwd: '/tmp/project',
       reportFile: '/tmp/project/.tw-patch/migrate-report.json',
+      reportKind: 'tw-patch-migrate-report',
+      reportSchemaVersion: 1,
       dryRun: false,
       strict: false,
       scannedEntries: 1,