admin-ui-starter-kit 0.1.1 → 0.1.3

package/scripts/audit-consumer.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * audit-consumer — checks a consuming app for common admin-ui-starter-kit
+ * migration mistakes:
+ *
+ * - stale copied import paths such as @/components/ui/base/buttons
+ * - invalid package imports not listed in package.json exports
+ * - local files that only re-export package components
+ *
+ * Run from a consumer app:
+ *
+ *   npx admin-ui-starter-kit-audit
+ *   npx admin-ui-starter-kit-audit --fix
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = 'admin-ui-starter-kit';
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
+const PACKAGE_JSON = JSON.parse(
+	await fs.readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+);
+const PUBLIC_EXPORTS = new Set(Object.keys(PACKAGE_JSON.exports ?? {}));
+
+const DEFAULT_PATHS = ['src', 'app', 'resources/js', 'components', 'pages'];
+const CODE_EXTENSIONS = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
+const SKIP_DIRS = new Set([
+	'.git',
+	'.next',
+	'.nuxt',
+	'.turbo',
+	'.vercel',
+	'build',
+	'coverage',
+	'dist',
+	'node_modules',
+	'public',
+	'vendor',
+]);
+
+function parseArgs(argv) {
+	const opts = { fix: false, json: false, help: false, paths: [] };
+	for (const arg of argv.slice(2)) {
+		if (arg === '--fix') {
+			opts.fix = true;
+		} else if (arg === '--json') {
+			opts.json = true;
+		} else if (arg === '--help' || arg === '-h') {
+			opts.help = true;
+		} else if (arg.startsWith('--paths=')) {
+			opts.paths.push(...arg.slice('--paths='.length).split(',').filter(Boolean));
+		} else if (arg.startsWith('-')) {
+			throw new Error(`Unknown option: ${arg}`);
+		} else {
+			opts.paths.push(arg);
+		}
+	}
+	return opts;
+}
+
+function printHelp() {
+	console.log(
+		`Usage: npx ${PACKAGE_NAME}-audit [options] [paths...]\n\n` +
+			`Audits a consuming app for stale local UI imports, invalid package subpaths,\n` +
+			`and local files that only mirror ${PACKAGE_NAME} exports.\n\n` +
+			`Options:\n` +
+			`  --fix             Rewrite known copied import paths to package imports\n` +
+			`  --paths=a,b       Comma-separated paths to scan\n` +
+			`  --json            Print machine-readable JSON\n` +
+			`  --help, -h        Show this message\n`,
+	);
+}
+
+async function exists(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function walk(dir, files = []) {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (SKIP_DIRS.has(entry.name)) continue;
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await walk(full, files);
+		} else if (entry.isFile() && CODE_EXTENSIONS.has(path.extname(entry.name))) {
+			files.push(full);
+		}
+	}
+	return files;
+}
+
+async function getScanFiles(cwd, requestedPaths) {
+	const roots = requestedPaths.length > 0 ? requestedPaths : DEFAULT_PATHS;
+	const files = [];
+	for (const relative of roots) {
+		const full = path.resolve(cwd, relative);
+		if (!(await exists(full))) continue;
+		const stat = await fs.stat(full);
+		if (stat.isDirectory()) {
+			await walk(full, files);
+		} else if (stat.isFile() && CODE_EXTENSIONS.has(path.extname(full))) {
+			files.push(full);
+		}
+	}
+	return [...new Set(files)].sort();
+}
+
+function getImportSpecifiers(source) {
+	const specifiers = [];
+	const patterns = [
+		/\bimport\s+(?:type\s+)?(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g,
+		/\bexport\s+(?:type\s+)?[^'"]*?\s+from\s+['"]([^'"]+)['"]/g,
+		/\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+	];
+	for (const pattern of patterns) {
+		for (const match of source.matchAll(pattern)) specifiers.push(match[1]);
+	}
+	return specifiers;
+}
+
+function normalizePackageKey(specifier) {
+	if (specifier === PACKAGE_NAME) return '.';
+	if (!specifier.startsWith(`${PACKAGE_NAME}/`)) return null;
+	return `.${specifier.slice(PACKAGE_NAME.length)}`;
+}
+
+function packageImportIssue(specifier) {
+	const key = normalizePackageKey(specifier);
+	if (key === null) return null;
+	if (PUBLIC_EXPORTS.has(key)) return null;
+	return {
+		kind: 'invalid-package-import',
+		specifier,
+		message: `${specifier} is not a public ${PACKAGE_NAME} export`,
+	};
+}
+
+function mapOldSpecifier(specifier) {
+	const typographyPrefixes = [
+		'@/components/ui/base/typography',
+		'@/components/ui/typography',
+		'@/components/typography',
+	];
+	if (typographyPrefixes.some((prefix) => specifier === prefix || specifier.startsWith(`${prefix}/`))) {
+		return `${PACKAGE_NAME}/typography`;
+	}
+
+	const layerMappings = [
+		{ prefix: '@/components/ui/base/', target: 'base' },
+		{ prefix: '@/components/base/', target: 'base' },
+		{ prefix: '@/components/composed/', target: 'composed' },
+		{ prefix: '@/components/features/', target: 'features' },
+		{ prefix: '@/components/layout/', target: 'layout' },
+	];
+
+	for (const mapping of layerMappings) {
+		if (!specifier.startsWith(mapping.prefix)) continue;
+		const rest = specifier.slice(mapping.prefix.length);
+		const parts = rest.split('/').filter(Boolean);
+		if (parts.length === 0) continue;
+
+		if (mapping.target === 'base' && parts[0] === 'display' && parts[1] === 'metadata') {
+			return `${PACKAGE_NAME}/base/display/metadata`;
+		}
+
+		const candidate = `${PACKAGE_NAME}/${mapping.target}/${parts[0]}`;
+		if (PUBLIC_EXPORTS.has(normalizePackageKey(candidate))) return candidate;
+	}
+
+	if (specifier === '@/components/layout') return `${PACKAGE_NAME}/layout`;
+
+	return null;
+}
+
+function isKnownCopiedImport(specifier) {
+	return mapOldSpecifier(specifier) !== null;
+}
+
+function isMirrorFile(source) {
+	const withoutComments = source
+		.replace(/\/\*[\s\S]*?\*\//g, '')
+		.replace(/^\s*\/\/.*$/gm, '')
+		.trim();
+	if (!withoutComments) return false;
+
+	const statements = withoutComments
+		.split(';')
+		.map((statement) => statement.trim())
+		.filter(Boolean);
+	if (statements.length === 0) return false;
+
+	return statements.every((statement) =>
+		/^export\s+(?:type\s+)?(?:\{[\s\S]*\}|\*)\s+from\s+['"]admin-ui-starter-kit(?:\/[^'"]+)?['"]$/m.test(
+			statement,
+		),
+	);
+}
+
+function replaceSpecifiers(source) {
+	let changed = false;
+	const next = source.replace(
+		/(['"])(@\/components\/(?:ui\/base|ui\/typography|base|typography|composed|features|layout)(?:\/[^'"]*)?)\1/g,
+		(match, quote, specifier) => {
+			const replacement = mapOldSpecifier(specifier);
+			if (!replacement) return match;
+			changed = true;
+			return `${quote}${replacement}${quote}`;
+		},
+	);
+	return { changed, source: next };
+}
+
+async function audit(opts) {
+	const cwd = process.cwd();
+	const files = await getScanFiles(cwd, opts.paths);
+	const issues = [];
+	const fixedFiles = [];
+
+	for (const file of files) {
+		const source = await fs.readFile(file, 'utf8');
+		const relative = path.relative(cwd, file);
+		const specifiers = getImportSpecifiers(source);
+
+		for (const specifier of specifiers) {
+			if (isKnownCopiedImport(specifier)) {
+				issues.push({
+					kind: 'stale-local-import',
+					file: relative,
+					specifier,
+					suggested: mapOldSpecifier(specifier),
+					message: `${specifier} should import directly from ${PACKAGE_NAME}`,
+				});
+			}
+
+			const invalidPackageImport = packageImportIssue(specifier);
+			if (invalidPackageImport) {
+				issues.push({ ...invalidPackageImport, file: relative });
+			}
+		}
+
+		if (isMirrorFile(source)) {
+			issues.push({
+				kind: 'local-package-mirror',
+				file: relative,
+				message: 'local file only re-exports admin-ui-starter-kit; replace call-site imports directly',
+			});
+		}
+
+		if (opts.fix) {
+			const replacement = replaceSpecifiers(source);
+			if (replacement.changed) {
+				await fs.writeFile(file, replacement.source);
+				fixedFiles.push(relative);
+			}
+		}
+	}
+
+	return { filesScanned: files.length, issues, fixedFiles: [...new Set(fixedFiles)].sort() };
+}
+
+function printReport(result, opts) {
+	if (opts.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	if (result.fixedFiles.length > 0) {
+		console.log(`Rewrote imports in ${result.fixedFiles.length} file(s):`);
+		for (const file of result.fixedFiles) console.log(`  - ${file}`);
+		console.log('');
+	}
+
+	if (result.issues.length === 0) {
+		console.log(`Admin UI audit passed (${result.filesScanned} files scanned).`);
+		return;
+	}
+
+	console.error(`Admin UI audit found ${result.issues.length} issue(s):`);
+	for (const issue of result.issues) {
+		const suggestion = issue.suggested ? ` -> ${issue.suggested}` : '';
+		console.error(`- ${issue.file}: ${issue.message}${suggestion}`);
+	}
+
+	if (!opts.fix) {
+		console.error('\nRun with --fix to rewrite known copied import paths.');
+	}
+}
+
+async function main() {
+	const opts = parseArgs(process.argv);
+	if (opts.help) {
+		printHelp();
+		return;
+	}
+
+	const first = await audit(opts);
+	if (!opts.fix || first.fixedFiles.length === 0) {
+		printReport(first, opts);
+		process.exit(first.issues.length > 0 ? 1 : 0);
+	}
+
+	const second = await audit({ ...opts, fix: false });
+	const merged = {
+		filesScanned: second.filesScanned,
+		issues: second.issues,
+		fixedFiles: first.fixedFiles,
+	};
+	printReport(merged, opts);
+	process.exit(second.issues.length > 0 ? 1 : 0);
+}
+
+main().catch((error) => {
+	if (error instanceof Error) {
+		console.error(`admin-ui-starter-kit-audit: ${error.message}`);
+	} else {
+		console.error(error);
+	}
+	process.exit(2);
+});

package/scripts/install-skill.mjs

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 /**
- * install-skill — consumer-facing installer for the
- * `component-library-rules` skill that ships inside the
- * `admin-ui-starter-kit` npm package.
+ * install-skill — consumer-facing installer for the AI skills that ship
+ * inside the `admin-ui-starter-kit` npm package.
  *
  * Run from a consumer project (after `npm install admin-ui-starter-kit`):
  *
- *   npx admin-ui-starter-kit-install-skill [--target=claude|agents|both] [--force]
+ *   npx admin-ui-starter-kit-install-skill [--skill=name|all] [--target=claude|agents|both] [--force]
  *
  * Default behaviour: copies the skill into BOTH
- *   <cwd>/.claude/skills/component-library-rules/
- *   <cwd>/.agents/skills/component-library-rules/
+ *   <cwd>/.claude/skills/<skill-name>/
+ *   <cwd>/.agents/skills/<skill-name>/
  *
  * The script is idempotent. It refuses to run inside the library itself
  * (the maintainer has `scripts/publish-skill.mjs` for that workflow).
@@ -20,18 +19,16 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
-const SKILL_NAME = 'component-library-rules';
+const SKILL_NAMES = ['component-library-rules', 'admin-ui-consumer-migration'];
 const PACKAGE_NAME = 'admin-ui-starter-kit';
 
 const __filename = fileURLToPath(import.meta.url);
 // scripts/install-skill.mjs lives at <pkg>/scripts/, so package root is one up.
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
-const SOURCE = path.join(PACKAGE_ROOT, '.agents', 'skills', SKILL_NAME);
-
 const CWD = process.cwd();
 
 function parseArgs(argv) {
-	const opts = { target: 'both', force: false, help: false };
+	const opts = { target: 'both', skill: 'all', force: false, help: false };
 	for (const arg of argv.slice(2)) {
 		if (arg === '--force' || arg === '-f') {
 			opts.force = true;
@@ -44,6 +41,15 @@ function parseArgs(argv) {
 				process.exit(2);
 			}
 			opts.target = value;
+		} else if (arg.startsWith('--skill=')) {
+			const value = arg.slice('--skill='.length);
+			if (value !== 'all' && !SKILL_NAMES.includes(value)) {
+				console.error(
+					`✖ Invalid --skill=${value}. Expected one of: all, ${SKILL_NAMES.join(', ')}.`,
+				);
+				process.exit(2);
+			}
+			opts.skill = value;
 		} else {
 			console.error(`✖ Unknown argument: ${arg}`);
 			opts.help = true;
@@ -55,8 +61,9 @@ function parseArgs(argv) {
 function printHelp() {
 	console.log(
 		`Usage: npx ${PACKAGE_NAME}-install-skill [options]\n\n` +
-			`Installs the "${SKILL_NAME}" skill into the current project.\n\n` +
+			`Installs ${PACKAGE_NAME} AI skills into the current project.\n\n` +
 			`Options:\n` +
+			`  --skill=all|${SKILL_NAMES.join('|')}   Which skill to install (default: all)\n` +
 			`  --target=claude|agents|both   Where to install (default: both)\n` +
 			`  --force, -f                   Overwrite existing skill dir without prompting\n` +
 			`  --help, -h                    Show this message\n`,
@@ -107,7 +114,7 @@ function confirm(question) {
 	});
 }
 
-async function installInto(targetDir, force) {
+async function installInto(skillName, sourceDir, targetDir, force) {
 	// Safety: the only thing we ever delete is the existing skill dir at the
 	// exact target path. We never touch the parent directory or siblings.
 	if (await exists(targetDir)) {
@@ -120,8 +127,8 @@ async function installInto(targetDir, force) {
 		}
 		await fs.rm(targetDir, { recursive: true, force: true });
 	}
-	const count = await copyDir(SOURCE, targetDir);
-	console.log(`  ✓ Installed ${SKILL_NAME} → ${targetDir} (${count} files)`);
+	const count = await copyDir(sourceDir, targetDir);
+	console.log(`  ✓ Installed ${skillName} → ${targetDir} (${count} files)`);
 	return count;
 }
 
@@ -143,31 +150,38 @@ async function main() {
 		process.exit(2);
 	}
 
-	if (!(await exists(SOURCE))) {
-		console.error(
-			`✖ Source skill not found at ${SOURCE}\n` +
-				`  This usually means the ${PACKAGE_NAME} package is missing the skill files.\n` +
-				`  Try reinstalling: npm install ${PACKAGE_NAME}@latest`,
-		);
-		process.exit(1);
-	}
+	const skillNames = opts.skill === 'all' ? SKILL_NAMES : [opts.skill];
 
-	const targets = [];
-	if (opts.target === 'claude' || opts.target === 'both') {
-		targets.push(path.join(CWD, '.claude', 'skills', SKILL_NAME));
-	}
-	if (opts.target === 'agents' || opts.target === 'both') {
-		targets.push(path.join(CWD, '.agents', 'skills', SKILL_NAME));
-	}
+	console.log(`Installing ${skillNames.length === 1 ? `"${skillNames[0]}"` : 'AI skills'} from ${PACKAGE_NAME}\n`);
 
-	console.log(`Installing "${SKILL_NAME}" from ${PACKAGE_NAME}\n`);
-	for (const target of targets) {
-		try {
-			await installInto(target, opts.force);
-		} catch (err) {
-			console.error(`  ✖ ${target}`);
-			console.error(`    ${err instanceof Error ? err.message : String(err)}`);
+	for (const skillName of skillNames) {
+		const source = path.join(PACKAGE_ROOT, '.agents', 'skills', skillName);
+		if (!(await exists(source))) {
+			console.error(
+				`✖ Source skill not found at ${source}\n` +
+					`  This usually means the ${PACKAGE_NAME} package is missing the skill files.\n` +
+					`  Try reinstalling: npm install ${PACKAGE_NAME}@latest`,
+			);
 			process.exitCode = 1;
+			continue;
+		}
+
+		const targets = [];
+		if (opts.target === 'claude' || opts.target === 'both') {
+			targets.push(path.join(CWD, '.claude', 'skills', skillName));
+		}
+		if (opts.target === 'agents' || opts.target === 'both') {
+			targets.push(path.join(CWD, '.agents', 'skills', skillName));
+		}
+
+		for (const target of targets) {
+			try {
+				await installInto(skillName, source, target, opts.force);
+			} catch (err) {
+				console.error(`  ✖ ${target}`);
+				console.error(`    ${err instanceof Error ? err.message : String(err)}`);
+				process.exitCode = 1;
+			}
 		}
 	}