@rokkit/cli 1.3.12 → 1.3.13

package/dist/src/checks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Run all doctor checks against the given filesystem adapter.
+ * @param {{ exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
+ * @returns {Array<{ id: string, label: string, status: 'pass'|'fail', fixable: boolean, fix: string, autoFix?: string }>}
+ */
+export function runChecks(fs: {
+    exists: (p: string) => boolean;
+    read: (p: string) => string;
+    resolve: (p: string) => string;
+}): Array<{
+    id: string;
+    label: string;
+    status: "pass" | "fail";
+    fixable: boolean;
+    fix: string;
+    autoFix?: string;
+}>;

package/dist/src/doctor.d.ts

@@ -1,54 +1,3 @@
-/**
- * Build the default named-token starter config source used by `doctor --fix`.
- * @returns {string}
- */
-export function defaultStarterSource(): string;
-/**
- * Run all doctor checks against the given filesystem adapter.
- * @param {{ exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
- * @returns {Array<{ id: string, label: string, status: 'pass'|'fail', fixable: boolean, fix: string, autoFix?: string }>}
- */
-export function runChecks(fs: {
-    exists: (p: string) => boolean;
-    read: (p: string) => string;
-    resolve: (p: string) => string;
-}): Array<{
-    id: string;
-    label: string;
-    status: "pass" | "fail";
-    fixable: boolean;
-    fix: string;
-    autoFix?: string;
-}>;
-/**
- * Validate a parsed rokkit config for the named-token system. All advisory (warn).
- * @param {Record<string, unknown> | null} config
- * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
- */
-export function validateConfigShape(config: Record<string, unknown> | null): Array<{
-    id: string;
-    label: string;
-    status: "warn";
-    fixable: false;
-    fix: string;
-}>;
-/**
- * Advisory lint: scan src/ for surface/border tokens used as text colour.
- * @param {{ list?: (dir: string) => string[], exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
- * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
- */
-export function checkTextTokenUsage(fs: {
-    list?: (dir: string) => string[];
-    exists: (p: string) => boolean;
-    read: (p: string) => string;
-    resolve: (p: string) => string;
-}): Array<{
-    id: string;
-    label: string;
-    status: "warn";
-    fixable: false;
-    fix: string;
-}>;
 /**
  * Interactive doctor command — validates project setup.
  * @param {{ fix?: boolean }} [opts]
@@ -56,3 +5,6 @@ export function checkTextTokenUsage(fs: {
 export function doctor(opts?: {
     fix?: boolean;
 }): Promise<void>;
+export { runChecks } from "./checks.js";
+export { defaultStarterSource } from "./fix.js";
+export { validateConfigShape, checkTextTokenUsage } from "./validate.js";

package/dist/src/fix.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build the default named-token starter config source used by `doctor --fix`.
+ * @returns {string}
+ */
+export function defaultStarterSource(): string;
+/**
+ * Create a real filesystem adapter rooted at cwd.
+ * @param {string} cwd
+ */
+export function createFsAdapter(cwd: string): {
+    exists: (p: any) => boolean;
+    read: (p: any) => string;
+    resolve: (p: any) => string;
+    list: (dir: any) => string[];
+};
+/**
+ * Auto-fix failed checks that are marked fixable.
+ * @param {Array<{ id: string, status: string, fixable: boolean, autoFix?: string, label: string }>} checks
+ * @param {string} cwd
+ * @returns {number} number of fixed items
+ */
+export function autoFix(checks: Array<{
+    id: string;
+    status: string;
+    fixable: boolean;
+    autoFix?: string;
+    label: string;
+}>, cwd: string): number;

package/dist/src/report.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Count failures and print status for each check.
+ * @param {Array} checks
+ * @returns {number}
+ */
+export function printChecks(checks: any[]): number;
+/**
+ * @param {Array} checks
+ * @param {string} cwd
+ * @param {number} failures
+ * @param {boolean} fix
+ */
+export function handleResults(checks: any[], cwd: string, failures: number, fix: boolean): void;

package/dist/src/validate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Advisory validation run by `doctor`: config shape rules for the named-token
+ * system, and a scan for surface/border tokens misused as text colour.
+ */
+/**
+ * Validate a parsed rokkit config for the named-token system. All advisory (warn).
+ * @param {Record<string, unknown> | null} config
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function validateConfigShape(config: Record<string, unknown> | null): Array<{
+    id: string;
+    label: string;
+    status: "warn";
+    fixable: false;
+    fix: string;
+}>;
+/**
+ * Advisory lint: scan src/ for surface/border tokens used as text colour.
+ * @param {{ list?: (dir: string) => string[], exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function checkTextTokenUsage(fs: {
+    list?: (dir: string) => string[];
+    exists: (p: string) => boolean;
+    read: (p: string) => string;
+    resolve: (p: string) => string;
+}): Array<{
+    id: string;
+    label: string;
+    status: "warn";
+    fixable: false;
+    fix: string;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.3.12",
+  "version": "1.3.13",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@mdi/svg": "^7.4.47",
-    "@rokkit/unocss": "1.3.12",
+    "@rokkit/unocss": "1.3.13",
     "sade": "^1.8.1",
     "@iconify/tools": "5.0.3",
     "@iconify/types": "^2.0.0",

package/src/checks.js

@@ -0,0 +1,146 @@
+/**
+ * The `doctor` checks: one function per project-setup requirement, plus
+ * `runChecks` which runs them all against a filesystem adapter.
+ */
+import { generateUnoConfig } from './init.js'
+
+const KNOWN_THEMES = [
+	'rokkit',
+	'minimal',
+	'material',
+	'frosted',
+	'zen-sumi'
+]
+
+/**
+ * Check config file existence
+ * @param {Object} fs
+ * @returns {{ id: string, label: string, status: string, fixable: boolean, fix: string, autoFix: string }}
+ */
+function checkConfig(fs) {
+	const configExists = fs.exists(fs.resolve('rokkit.config.js'))
+	return {
+		id: 'config-exists',
+		label: 'rokkit.config.js exists',
+		status: configExists ? 'pass' : 'fail',
+		fixable: true,
+		fix: 'Run `rokkit init` to generate config',
+		autoFix: 'generate-config'
+	}
+}
+
+/**
+ * Check uno.config.js uses presetRokkit
+ * @param {Object} fs
+ * @returns {Object}
+ */
+function checkUnoPreset(fs) {
+	const unoPath = fs.resolve('uno.config.js')
+	const unoExists = fs.exists(unoPath)
+	const unoContent = unoExists ? fs.read(unoPath) : ''
+	const unoUsesPreset = unoContent.includes('presetRokkit') && unoContent.includes('rokkit.config')
+	return {
+		id: 'uno-uses-preset',
+		label: 'uno.config.js uses presetRokkit(config)',
+		status: unoUsesPreset ? 'pass' : 'fail',
+		fixable: false,
+		fix: unoExists
+			? `Replace uno.config.js contents with:\n${generateUnoConfig()}`
+			: `Create uno.config.js with:\n${generateUnoConfig()}`
+	}
+}
+
+/**
+ * Check app.css has theme imports
+ * @param {Object} fs
+ * @returns {Object}
+ */
+function checkCssImports(fs) {
+	const cssPath = fs.resolve('src/app.css')
+	const cssExists = fs.exists(cssPath)
+	const cssHasBase = cssExists && fs.read(cssPath).includes('@rokkit/themes/base.css')
+	return {
+		id: 'css-imports',
+		label: 'app.css imports @rokkit/themes/base.css',
+		status: cssHasBase ? 'pass' : 'fail',
+		fixable: true,
+		fix: 'Append base theme import to src/app.css',
+		autoFix: 'patch-css'
+	}
+}
+
+/**
+ * Check app.css has at least one theme style
+ * @param {Object} fs
+ * @returns {Object}
+ */
+function checkCssTheme(fs) {
+	const cssPath = fs.resolve('src/app.css')
+	const cssExists = fs.exists(cssPath)
+	const css = cssExists ? fs.read(cssPath) : ''
+	const hasTheme = KNOWN_THEMES.some((t) => css.includes(`@rokkit/themes/${t}.css`))
+	return {
+		id: 'css-theme',
+		label: 'app.css has a theme style',
+		status: hasTheme ? 'pass' : 'warn',
+		fixable: false,
+		fix: `Add a theme import to src/app.css, e.g. @import '@rokkit/themes/rokkit.css'\n         Available: ${KNOWN_THEMES.join(', ')}, or use a custom theme`
+	}
+}
+
+/**
+ * Check rokkit.config.js has a chart section.
+ * Missing chart config is a warning (not failure) — defaults work without it.
+ * @param {Object} fs
+ * @returns {Object}
+ */
+function checkChartConfig(fs) {
+	const configPath = fs.resolve('rokkit.config.js')
+	const configExists = fs.exists(configPath)
+	const hasChart = configExists && /\bchart\s*:/.test(fs.read(configPath))
+	return {
+		id: 'chart-config',
+		label: 'rokkit.config.js has chart configuration',
+		status: hasChart ? 'pass' : 'warn',
+		fixable: configExists,
+		fix: 'Add a chart section to rokkit.config.js (see docs/design/17-chart-preset.md)',
+		autoFix: 'patch-chart-config'
+	}
+}
+
+/**
+ * Check app.html has init script
+ * @param {Object} fs
+ * @returns {Object}
+ */
+function checkHtmlScript(fs) {
+	const htmlPath = fs.resolve('src/app.html')
+	const htmlExists = fs.exists(htmlPath)
+	const htmlHasScript =
+		htmlExists &&
+		(fs.read(htmlPath).includes('rokkit-theme') || fs.read(htmlPath).includes('data-mode'))
+	return {
+		id: 'html-init-script',
+		label: 'app.html has theme init script',
+		status: htmlHasScript ? 'pass' : 'fail',
+		fixable: true,
+		fix: 'Add flash-prevention script to src/app.html',
+		autoFix: 'patch-html'
+	}
+}
+
+/**
+ * Run all doctor checks against the given filesystem adapter.
+ * @param {{ exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
+ * @returns {Array<{ id: string, label: string, status: 'pass'|'fail', fixable: boolean, fix: string, autoFix?: string }>}
+ */
+export function runChecks(fs) {
+	return [
+		checkConfig(fs),
+		checkUnoPreset(fs),
+		checkCssImports(fs),
+		checkCssTheme(fs),
+		checkHtmlScript(fs),
+		checkChartConfig(fs)
+	]
+}

package/src/doctor.js

@@ -1,477 +1,22 @@
 /* eslint-disable no-console */
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs'
-import { resolve, join } from 'path'
-import { loadConfig as loadParsedConfig } from './config.js'
-import {
-	generateUnoConfig,
-	generateAppCssImports,
-	generateChartConfig,
-	generateConfig,
-	serializeRokkitConfig
-} from './init.js'
-import { themeInitScript } from '@rokkit/unocss/hooks'
-import { checkContrastTokens } from './contrast.js'
-
-const KNOWN_THEMES = [
-	'rokkit',
-	'minimal',
-	'material',
-	'frosted',
-	'zen-sumi'
-]
-
-/**
- * Build the default named-token starter config source used by `doctor --fix`.
- * @returns {string}
- */
-export function defaultStarterSource() {
-	const config = generateConfig({
-		palette: 'default',
-		icons: 'rokkit',
-		themes: ['rokkit'],
-		switcher: 'manual',
-		includeChart: true,
-		chartColors: 'default',
-		chartShades: 'standard'
-	})
-	return serializeRokkitConfig(config)
-}
-
-/**
- * Check config file existence
- * @param {Object} fs
- * @returns {{ id: string, label: string, status: string, fixable: boolean, fix: string, autoFix: string }}
- */
-function checkConfig(fs) {
-	const configExists = fs.exists(fs.resolve('rokkit.config.js'))
-	return {
-		id: 'config-exists',
-		label: 'rokkit.config.js exists',
-		status: configExists ? 'pass' : 'fail',
-		fixable: true,
-		fix: 'Run `rokkit init` to generate config',
-		autoFix: 'generate-config'
-	}
-}
-
-/**
- * Check uno.config.js uses presetRokkit
- * @param {Object} fs
- * @returns {Object}
- */
-function checkUnoPreset(fs) {
-	const unoPath = fs.resolve('uno.config.js')
-	const unoExists = fs.exists(unoPath)
-	const unoContent = unoExists ? fs.read(unoPath) : ''
-	const unoUsesPreset = unoContent.includes('presetRokkit') && unoContent.includes('rokkit.config')
-	return {
-		id: 'uno-uses-preset',
-		label: 'uno.config.js uses presetRokkit(config)',
-		status: unoUsesPreset ? 'pass' : 'fail',
-		fixable: false,
-		fix: unoExists
-			? `Replace uno.config.js contents with:\n${generateUnoConfig()}`
-			: `Create uno.config.js with:\n${generateUnoConfig()}`
-	}
-}
-
-/**
- * Check app.css has theme imports
- * @param {Object} fs
- * @returns {Object}
- */
-function checkCssImports(fs) {
-	const cssPath = fs.resolve('src/app.css')
-	const cssExists = fs.exists(cssPath)
-	const cssHasBase = cssExists && fs.read(cssPath).includes('@rokkit/themes/base.css')
-	return {
-		id: 'css-imports',
-		label: 'app.css imports @rokkit/themes/base.css',
-		status: cssHasBase ? 'pass' : 'fail',
-		fixable: true,
-		fix: 'Append base theme import to src/app.css',
-		autoFix: 'patch-css'
-	}
-}
-
-/**
- * Check app.css has at least one theme style
- * @param {Object} fs
- * @returns {Object}
- */
-function checkCssTheme(fs) {
-	const cssPath = fs.resolve('src/app.css')
-	const cssExists = fs.exists(cssPath)
-	const css = cssExists ? fs.read(cssPath) : ''
-	const hasTheme = KNOWN_THEMES.some((t) => css.includes(`@rokkit/themes/${t}.css`))
-	return {
-		id: 'css-theme',
-		label: 'app.css has a theme style',
-		status: hasTheme ? 'pass' : 'warn',
-		fixable: false,
-		fix: `Add a theme import to src/app.css, e.g. @import '@rokkit/themes/rokkit.css'\n         Available: ${KNOWN_THEMES.join(', ')}, or use a custom theme`
-	}
-}
-
-/**
- * Check rokkit.config.js has a chart section.
- * Missing chart config is a warning (not failure) — defaults work without it.
- * @param {Object} fs
- * @returns {Object}
- */
-function checkChartConfig(fs) {
-	const configPath = fs.resolve('rokkit.config.js')
-	const configExists = fs.exists(configPath)
-	const hasChart = configExists && /\bchart\s*:/.test(fs.read(configPath))
-	return {
-		id: 'chart-config',
-		label: 'rokkit.config.js has chart configuration',
-		status: hasChart ? 'pass' : 'warn',
-		fixable: configExists,
-		fix: 'Add a chart section to rokkit.config.js (see docs/design/17-chart-preset.md)',
-		autoFix: 'patch-chart-config'
-	}
-}
-
-/**
- * Check app.html has init script
- * @param {Object} fs
- * @returns {Object}
- */
-function checkHtmlScript(fs) {
-	const htmlPath = fs.resolve('src/app.html')
-	const htmlExists = fs.exists(htmlPath)
-	const htmlHasScript =
-		htmlExists &&
-		(fs.read(htmlPath).includes('rokkit-theme') || fs.read(htmlPath).includes('data-mode'))
-	return {
-		id: 'html-init-script',
-		label: 'app.html has theme init script',
-		status: htmlHasScript ? 'pass' : 'fail',
-		fixable: true,
-		fix: 'Add flash-prevention script to src/app.html',
-		autoFix: 'patch-html'
-	}
-}
-
-/**
- * Run all doctor checks against the given filesystem adapter.
- * @param {{ exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
- * @returns {Array<{ id: string, label: string, status: 'pass'|'fail', fixable: boolean, fix: string, autoFix?: string }>}
- */
-export function runChecks(fs) {
-	return [
-		checkConfig(fs),
-		checkUnoPreset(fs),
-		checkCssImports(fs),
-		checkCssTheme(fs),
-		checkHtmlScript(fs),
-		checkChartConfig(fs)
-	]
-}
-
-const SKIP_DIRS = new Set(['node_modules', '.svelte-kit', 'dist', '.git', 'coverage'])
-
-/**
- * Recursively list absolute file paths under `dir`, skipping vendored/build dirs.
- * @param {string} dir
- * @returns {string[]}
- */
-function listFiles(dir) {
-	const out = []
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		if (entry.isDirectory()) {
-			if (SKIP_DIRS.has(entry.name)) continue
-			out.push(...listFiles(join(dir, entry.name)))
-		} else {
-			out.push(join(dir, entry.name))
-		}
-	}
-	return out
-}
-
-/**
- * Create a real filesystem adapter rooted at cwd.
- * @param {string} cwd
- */
-function createFsAdapter(cwd) {
-	return {
-		exists: (p) => existsSync(p),
-		read: (p) => readFileSync(p, 'utf-8'),
-		resolve: (p) => resolve(cwd, p),
-		list: (dir) => listFiles(dir)
-	}
-}
-
-/**
- * Apply the generate-config fix
- * @param {string} cwd
- * @param {string} label
- */
-function applyGenerateConfig(cwd, label) {
-	const configPath = resolve(cwd, 'rokkit.config.js')
-	writeFileSync(configPath, defaultStarterSource())
-	console.info(`  Fixed: ${label}`)
-}
-
-/**
- * Apply the patch-css fix
- * @param {string} cwd
- * @param {string} label
- */
-function applyPatchCss(cwd, label) {
-	const cssPath = resolve(cwd, 'src/app.css')
-	const imports = generateAppCssImports([])
-	if (existsSync(cssPath)) {
-		const existing = readFileSync(cssPath, 'utf-8')
-		const missing = imports.filter((line) => !existing.includes(line))
-		if (missing.length > 0) writeFileSync(cssPath, `${missing.join('\n')}\n${existing}`)
-	} else {
-		writeFileSync(cssPath, `${imports.join('\n')}\n`)
-	}
-	console.info(`  Fixed: ${label}`)
-}
-
 /**
- * Apply the patch-html fix
- * @param {string} cwd
- * @param {string} label
- * @returns {boolean} whether fix was applied
+ * The `rokkit doctor` command — validates project setup, then reports and
+ * auto-fixes issues.
+ *
+ * Check definitions live in `checks.js`, the fs adapter + auto-fix handlers in
+ * `fix.js`, console reporting in `report.js`, and advisory shape/lint checks in
+ * `validate.js`. This file is the command orchestration + public surface.
  */
-function applyPatchHtml(cwd, label) {
-	const htmlPath = resolve(cwd, 'src/app.html')
-	if (!existsSync(htmlPath)) return false
-	const html = readFileSync(htmlPath, 'utf-8')
-	// Use the project's configured storageKey so the injected script reads the
-	// same localStorage slot the app persists to — don't hardcode a key.
-	const configPath = resolve(cwd, 'rokkit.config.js')
-	const storageKey = existsSync(configPath)
-		? readFileSync(configPath, 'utf-8').match(/storageKey:\s*['"]([^'"]+)['"]/)?.[1]
-		: undefined
-	const marker = storageKey || 'rokkit-theme'
-	if (html.includes(marker)) return false
-	const script = themeInitScript({ storageKey })
-	const patched = html.replace(/(<body[^>]*>)/, `$1\n${script}`)
-	writeFileSync(htmlPath, patched)
-	console.info(`  Fixed: ${label}`)
-	return true
-}
-
-/**
- * Patch rokkit.config.js to add a default chart section.
- * @param {string} cwd
- * @param {string} label
- */
-/* v8 ignore next 16 -- chart-config check emits 'warn' (not 'fail'); applyCheckFix
-   only processes 'fail' statuses, making this handler unreachable via the normal
-   fix flow. Kept for potential future use if the check severity changes. */
-function applyPatchChartConfig(cwd, label) {
-	const configPath = resolve(cwd, 'rokkit.config.js')
-	if (!existsSync(configPath)) return false
-	const content = readFileSync(configPath, 'utf-8')
-	if (/\bchart\s*:/.test(content)) return false
-	const chartConfig = generateChartConfig({ chartColors: 'default', chartShades: 'standard' })
-	const chartJson = JSON.stringify(chartConfig, null, 2).replace(/\n/g, '\n  ')
-	// Inject before the last closing brace of the export default object
-	const patched = content.replace(/(\n?}\s*\n?)$/, `,\n  chart: ${chartJson}\n}\n`)
-	writeFileSync(configPath, patched)
-	console.info(`  Fixed: ${label}`)
-	return true
-}
-
-/** @type {Record<string, (cwd: string, label: string) => boolean|void>} */
-const FIX_HANDLERS = {
-	'generate-config': (cwd, label) => {
-		applyGenerateConfig(cwd, label)
-		return true
-	},
-	'patch-css': (cwd, label) => {
-		applyPatchCss(cwd, label)
-		return true
-	},
-	'patch-html': (cwd, label) => applyPatchHtml(cwd, label),
-	'patch-chart-config': (cwd, label) => applyPatchChartConfig(cwd, label)
-}
-
-/**
- * @param {number} fixed
- * @param {{ status: string, fixable: boolean, autoFix?: string, label: string }} check
- * @param {string} cwd
- * @returns {number}
- */
-function applyCheckFix(fixed, check, cwd) {
-	if (check.status !== 'fail' || !check.fixable) return fixed
-	const handler = FIX_HANDLERS[check.autoFix]
-	return handler && handler(cwd, check.label) ? fixed + 1 : fixed
-}
-
-/**
- * Auto-fix failed checks that are marked fixable.
- * @param {Array<{ id: string, status: string, fixable: boolean, autoFix?: string, label: string }>} checks
- * @param {string} cwd
- * @returns {number} number of fixed items
- */
-function autoFix(checks, cwd) {
-	return checks.reduce((fixed, check) => applyCheckFix(fixed, check, cwd), 0)
-}
-
-/**
- * Print fix hints for failing checks
- * @param {Array} checks
- */
-function printFixHints(checks) {
-	for (const check of checks) {
-		if (check.status === 'fail' || check.status === 'warn') {
-			console.info(`         ${check.fixable ? '(auto-fixable) ' : ''}${check.fix}`)
-		}
-	}
-}
-
-/**
- * Print remaining manual action items
- * @param {Array} checks
- */
-function printManualItems(checks) {
-	for (const check of checks) {
-		if (check.status === 'fail' && !check.fixable) {
-			console.info(`  - ${check.label}: ${check.fix}`)
-		}
-	}
-}
-
-/**
- * Count failures and print status for each check.
- * @param {Array} checks
- * @returns {number}
- */
-function printChecks(checks) {
-	let failures = 0
-	for (const check of checks) {
-		const icon = check.status === 'pass' ? 'PASS' : check.status === 'warn' ? 'WARN' : 'FAIL'
-		console.info(`  ${icon}  ${check.label}`)
-		if (check.status === 'fail') failures++
-	}
-	return failures
-}
-
-/**
- * Handle auto-fix flow and print results.
- * @param {Array} checks
- * @param {string} cwd
- * @param {number} failures
- */
-function handleAutoFix(checks, cwd, failures) {
-	console.info('\nAuto-fixing...\n')
-	const fixed = autoFix(checks, cwd)
-	const remaining = failures - fixed
-	if (remaining > 0) {
-		console.info(`\n${fixed} fixed, ${remaining} require manual action:`)
-		printManualItems(checks)
-	} else {
-		console.info(`\nAll ${fixed} issues fixed!`)
-	}
-}
-
-/**
- * @param {Array} checks
- * @param {string} cwd
- * @param {number} failures
- * @param {boolean} fix
- */
-function handleResults(checks, cwd, failures, fix) {
-	if (failures === 0) return
-	if (fix) {
-		handleAutoFix(checks, cwd, failures)
-	} else {
-		printFixHints(checks)
-		process.exitCode = 1
-	}
-}
-
-/**
- * Validate a parsed rokkit config for the named-token system. All advisory (warn).
- * @param {Record<string, unknown> | null} config
- * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
- */
-export function validateConfigShape(config) {
-	if (!config) return []
-	const checks = []
-	const usesColorsAlias =
-		typeof config.colors === 'object' && config.colors !== null && !Array.isArray(config.colors) && !config.skin
-	const colormap = config.skins?.default ?? config.skin ?? config.colors ?? {}
-
-	if (!('ink' in colormap)) {
-		checks.push({
-			id: 'skin-ink-role',
-			label: 'skin defines an `ink` role',
-			status: 'warn',
-			fixable: false,
-			fix: "Add `ink: '<palette>'` (reusing the surface palette is fine) — without it, ink-* text tokens fall back to the surface palette."
-		})
-	}
-	if (config.colorSpace === 'oklch' && Object.keys(config.palettes ?? {}).length === 0) {
-		checks.push({
-			id: 'oklch-needs-palettes',
-			label: 'colorSpace `oklch` has a `palettes` block',
-			status: 'warn',
-			fixable: false,
-			fix: 'oklch values need a `palettes` block of bare "L C H" components; Tailwind named colors are rgb.'
-		})
-	}
-	if (usesColorsAlias) {
-		checks.push({
-			id: 'colors-alias',
-			label: 'config uses `skin` (not the legacy `colors` alias)',
-			status: 'warn',
-			fixable: false,
-			fix: 'Rename `colors:` to `skin:` — `colors` is a back-compat alias.'
-		})
-	}
-	return checks
-}
-
-/**
- * Patterns that flag a surface/border token being used as a text colour.
- * paper-edge / paper-mute are border/surface tones — used as text they're faint
- * in light and invisible in dark. paper / paper-soft are legitimate on-colours.
- */
-const TEXT_MISUSE_PATTERNS = [
-	/text-paper-edge\b/,
-	/text-paper-mute\b/,
-	/color:\s*var\(\s*--paper-edge\s*\)/,
-	/color:\s*var\(\s*--paper-mute\s*\)/
-]
-
-/**
- * Advisory lint: scan src/ for surface/border tokens used as text colour.
- * @param {{ list?: (dir: string) => string[], exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
- * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
- */
-export function checkTextTokenUsage(fs) {
-	if (typeof fs.list !== 'function' || !fs.exists(fs.resolve('src'))) return []
-
-	const cwd = process.cwd()
-	const hits = []
-	for (const file of fs.list(fs.resolve('src'))) {
-		if (!file.endsWith('.css') && !file.endsWith('.svelte')) continue
-		const lines = fs.read(file).split('\n')
-		const display = file.startsWith(cwd) ? file.slice(cwd.length).replace(/^\//, '') : file
-		lines.forEach((line, i) => {
-			if (TEXT_MISUSE_PATTERNS.some((re) => re.test(line))) hits.push(`${display}:${i + 1}`)
-		})
-	}
-
-	if (hits.length === 0) return []
-	return [
-		{
-			id: 'surface-token-as-text',
-			label: 'no surface/border token used as text colour',
-			status: 'warn',
-			fixable: false,
-			fix: `paper-edge / paper-mute are border/surface tokens — never use them for text (faint in light, invisible in dark). Use the ink scale (ink-mute for readable secondary text). Found at:\n         ${hits.join('\n         ')}`
-		}
-	]
-}
+import { loadConfig as loadParsedConfig } from './config.js'
+import { checkContrastTokens } from './contrast.js'
+import { runChecks } from './checks.js'
+import { createFsAdapter } from './fix.js'
+import { handleResults, printChecks } from './report.js'
+import { validateConfigShape, checkTextTokenUsage } from './validate.js'
+
+export { runChecks } from './checks.js'
+export { defaultStarterSource } from './fix.js'
+export { validateConfigShape, checkTextTokenUsage } from './validate.js'
 
 /**
  * Interactive doctor command — validates project setup.

package/src/fix.js

@@ -0,0 +1,176 @@
+/* eslint-disable no-console */
+/**
+ * The filesystem adapter and auto-fix machinery behind `doctor --fix`:
+ * apply each fix handler for a failed check and count what was fixed.
+ */
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs'
+import { resolve, join } from 'path'
+import {
+	generateAppCssImports,
+	generateChartConfig,
+	generateConfig,
+	serializeRokkitConfig
+} from './init.js'
+import { themeInitScript } from '@rokkit/unocss/hooks'
+
+/**
+ * Build the default named-token starter config source used by `doctor --fix`.
+ * @returns {string}
+ */
+export function defaultStarterSource() {
+	const config = generateConfig({
+		palette: 'default',
+		icons: 'rokkit',
+		themes: ['rokkit'],
+		switcher: 'manual',
+		includeChart: true,
+		chartColors: 'default',
+		chartShades: 'standard'
+	})
+	return serializeRokkitConfig(config)
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.svelte-kit', 'dist', '.git', 'coverage'])
+
+/**
+ * Recursively list absolute file paths under `dir`, skipping vendored/build dirs.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listFiles(dir) {
+	const out = []
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue
+			out.push(...listFiles(join(dir, entry.name)))
+		} else {
+			out.push(join(dir, entry.name))
+		}
+	}
+	return out
+}
+
+/**
+ * Create a real filesystem adapter rooted at cwd.
+ * @param {string} cwd
+ */
+export function createFsAdapter(cwd) {
+	return {
+		exists: (p) => existsSync(p),
+		read: (p) => readFileSync(p, 'utf-8'),
+		resolve: (p) => resolve(cwd, p),
+		list: (dir) => listFiles(dir)
+	}
+}
+
+/**
+ * Apply the generate-config fix
+ * @param {string} cwd
+ * @param {string} label
+ */
+function applyGenerateConfig(cwd, label) {
+	const configPath = resolve(cwd, 'rokkit.config.js')
+	writeFileSync(configPath, defaultStarterSource())
+	console.info(`  Fixed: ${label}`)
+}
+
+/**
+ * Apply the patch-css fix
+ * @param {string} cwd
+ * @param {string} label
+ */
+function applyPatchCss(cwd, label) {
+	const cssPath = resolve(cwd, 'src/app.css')
+	const imports = generateAppCssImports([])
+	if (existsSync(cssPath)) {
+		const existing = readFileSync(cssPath, 'utf-8')
+		const missing = imports.filter((line) => !existing.includes(line))
+		if (missing.length > 0) writeFileSync(cssPath, `${missing.join('\n')}\n${existing}`)
+	} else {
+		writeFileSync(cssPath, `${imports.join('\n')}\n`)
+	}
+	console.info(`  Fixed: ${label}`)
+}
+
+/**
+ * Apply the patch-html fix
+ * @param {string} cwd
+ * @param {string} label
+ * @returns {boolean} whether fix was applied
+ */
+function applyPatchHtml(cwd, label) {
+	const htmlPath = resolve(cwd, 'src/app.html')
+	if (!existsSync(htmlPath)) return false
+	const html = readFileSync(htmlPath, 'utf-8')
+	// Use the project's configured storageKey so the injected script reads the
+	// same localStorage slot the app persists to — don't hardcode a key.
+	const configPath = resolve(cwd, 'rokkit.config.js')
+	const storageKey = existsSync(configPath)
+		? readFileSync(configPath, 'utf-8').match(/storageKey:\s*['"]([^'"]+)['"]/)?.[1]
+		: undefined
+	const marker = storageKey || 'rokkit-theme'
+	if (html.includes(marker)) return false
+	const script = themeInitScript({ storageKey })
+	const patched = html.replace(/(<body[^>]*>)/, `$1\n${script}`)
+	writeFileSync(htmlPath, patched)
+	console.info(`  Fixed: ${label}`)
+	return true
+}
+
+/**
+ * Patch rokkit.config.js to add a default chart section.
+ * @param {string} cwd
+ * @param {string} label
+ */
+/* v8 ignore next 16 -- chart-config check emits 'warn' (not 'fail'); applyCheckFix
+   only processes 'fail' statuses, making this handler unreachable via the normal
+   fix flow. Kept for potential future use if the check severity changes. */
+function applyPatchChartConfig(cwd, label) {
+	const configPath = resolve(cwd, 'rokkit.config.js')
+	if (!existsSync(configPath)) return false
+	const content = readFileSync(configPath, 'utf-8')
+	if (/\bchart\s*:/.test(content)) return false
+	const chartConfig = generateChartConfig({ chartColors: 'default', chartShades: 'standard' })
+	const chartJson = JSON.stringify(chartConfig, null, 2).replace(/\n/g, '\n  ')
+	// Inject before the last closing brace of the export default object
+	const patched = content.replace(/(\n?}\s*\n?)$/, `,\n  chart: ${chartJson}\n}\n`)
+	writeFileSync(configPath, patched)
+	console.info(`  Fixed: ${label}`)
+	return true
+}
+
+/** @type {Record<string, (cwd: string, label: string) => boolean|void>} */
+const FIX_HANDLERS = {
+	'generate-config': (cwd, label) => {
+		applyGenerateConfig(cwd, label)
+		return true
+	},
+	'patch-css': (cwd, label) => {
+		applyPatchCss(cwd, label)
+		return true
+	},
+	'patch-html': (cwd, label) => applyPatchHtml(cwd, label),
+	'patch-chart-config': (cwd, label) => applyPatchChartConfig(cwd, label)
+}
+
+/**
+ * @param {number} fixed
+ * @param {{ status: string, fixable: boolean, autoFix?: string, label: string }} check
+ * @param {string} cwd
+ * @returns {number}
+ */
+function applyCheckFix(fixed, check, cwd) {
+	if (check.status !== 'fail' || !check.fixable) return fixed
+	const handler = FIX_HANDLERS[check.autoFix]
+	return handler && handler(cwd, check.label) ? fixed + 1 : fixed
+}
+
+/**
+ * Auto-fix failed checks that are marked fixable.
+ * @param {Array<{ id: string, status: string, fixable: boolean, autoFix?: string, label: string }>} checks
+ * @param {string} cwd
+ * @returns {number} number of fixed items
+ */
+export function autoFix(checks, cwd) {
+	return checks.reduce((fixed, check) => applyCheckFix(fixed, check, cwd), 0)
+}

package/src/report.js

@@ -0,0 +1,79 @@
+/* eslint-disable no-console */
+/**
+ * Console reporting for `doctor`: print per-check status lines, fix hints and
+ * manual action items, and orchestrate the auto-fix flow summary.
+ */
+import { autoFix } from './fix.js'
+
+/**
+ * Print fix hints for failing checks
+ * @param {Array} checks
+ */
+function printFixHints(checks) {
+	for (const check of checks) {
+		if (check.status === 'fail' || check.status === 'warn') {
+			console.info(`         ${check.fixable ? '(auto-fixable) ' : ''}${check.fix}`)
+		}
+	}
+}
+
+/**
+ * Print remaining manual action items
+ * @param {Array} checks
+ */
+function printManualItems(checks) {
+	for (const check of checks) {
+		if (check.status === 'fail' && !check.fixable) {
+			console.info(`  - ${check.label}: ${check.fix}`)
+		}
+	}
+}
+
+/**
+ * Count failures and print status for each check.
+ * @param {Array} checks
+ * @returns {number}
+ */
+export function printChecks(checks) {
+	let failures = 0
+	for (const check of checks) {
+		const icon = check.status === 'pass' ? 'PASS' : check.status === 'warn' ? 'WARN' : 'FAIL'
+		console.info(`  ${icon}  ${check.label}`)
+		if (check.status === 'fail') failures++
+	}
+	return failures
+}
+
+/**
+ * Handle auto-fix flow and print results.
+ * @param {Array} checks
+ * @param {string} cwd
+ * @param {number} failures
+ */
+function handleAutoFix(checks, cwd, failures) {
+	console.info('\nAuto-fixing...\n')
+	const fixed = autoFix(checks, cwd)
+	const remaining = failures - fixed
+	if (remaining > 0) {
+		console.info(`\n${fixed} fixed, ${remaining} require manual action:`)
+		printManualItems(checks)
+	} else {
+		console.info(`\nAll ${fixed} issues fixed!`)
+	}
+}
+
+/**
+ * @param {Array} checks
+ * @param {string} cwd
+ * @param {number} failures
+ * @param {boolean} fix
+ */
+export function handleResults(checks, cwd, failures, fix) {
+	if (failures === 0) return
+	if (fix) {
+		handleAutoFix(checks, cwd, failures)
+	} else {
+		printFixHints(checks)
+		process.exitCode = 1
+	}
+}

package/src/validate.js

@@ -0,0 +1,89 @@
+/**
+ * Advisory validation run by `doctor`: config shape rules for the named-token
+ * system, and a scan for surface/border tokens misused as text colour.
+ */
+
+/**
+ * Validate a parsed rokkit config for the named-token system. All advisory (warn).
+ * @param {Record<string, unknown> | null} config
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function validateConfigShape(config) {
+	if (!config) return []
+	const checks = []
+	const usesColorsAlias =
+		typeof config.colors === 'object' && config.colors !== null && !Array.isArray(config.colors) && !config.skin
+	const colormap = config.skins?.default ?? config.skin ?? config.colors ?? {}
+
+	if (!('ink' in colormap)) {
+		checks.push({
+			id: 'skin-ink-role',
+			label: 'skin defines an `ink` role',
+			status: 'warn',
+			fixable: false,
+			fix: "Add `ink: '<palette>'` (reusing the surface palette is fine) — without it, ink-* text tokens fall back to the surface palette."
+		})
+	}
+	if (config.colorSpace === 'oklch' && Object.keys(config.palettes ?? {}).length === 0) {
+		checks.push({
+			id: 'oklch-needs-palettes',
+			label: 'colorSpace `oklch` has a `palettes` block',
+			status: 'warn',
+			fixable: false,
+			fix: 'oklch values need a `palettes` block of bare "L C H" components; Tailwind named colors are rgb.'
+		})
+	}
+	if (usesColorsAlias) {
+		checks.push({
+			id: 'colors-alias',
+			label: 'config uses `skin` (not the legacy `colors` alias)',
+			status: 'warn',
+			fixable: false,
+			fix: 'Rename `colors:` to `skin:` — `colors` is a back-compat alias.'
+		})
+	}
+	return checks
+}
+
+/**
+ * Patterns that flag a surface/border token being used as a text colour.
+ * paper-edge / paper-mute are border/surface tones — used as text they're faint
+ * in light and invisible in dark. paper / paper-soft are legitimate on-colours.
+ */
+const TEXT_MISUSE_PATTERNS = [
+	/text-paper-edge\b/,
+	/text-paper-mute\b/,
+	/color:\s*var\(\s*--paper-edge\s*\)/,
+	/color:\s*var\(\s*--paper-mute\s*\)/
+]
+
+/**
+ * Advisory lint: scan src/ for surface/border tokens used as text colour.
+ * @param {{ list?: (dir: string) => string[], exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function checkTextTokenUsage(fs) {
+	if (typeof fs.list !== 'function' || !fs.exists(fs.resolve('src'))) return []
+
+	const cwd = process.cwd()
+	const hits = []
+	for (const file of fs.list(fs.resolve('src'))) {
+		if (!file.endsWith('.css') && !file.endsWith('.svelte')) continue
+		const lines = fs.read(file).split('\n')
+		const display = file.startsWith(cwd) ? file.slice(cwd.length).replace(/^\//, '') : file
+		lines.forEach((line, i) => {
+			if (TEXT_MISUSE_PATTERNS.some((re) => re.test(line))) hits.push(`${display}:${i + 1}`)
+		})
+	}
+
+	if (hits.length === 0) return []
+	return [
+		{
+			id: 'surface-token-as-text',
+			label: 'no surface/border token used as text colour',
+			status: 'warn',
+			fixable: false,
+			fix: `paper-edge / paper-mute are border/surface tokens — never use them for text (faint in light, invisible in dark). Use the ink scale (ink-mute for readable secondary text). Found at:\n         ${hits.join('\n         ')}`
+		}
+	]
+}