@aperant/framework 0.6.2

package/src/cli/commands/design-scan.mjs

@@ -0,0 +1,112 @@
+/**
+ * commands/design-scan.mjs — `apt-tools design-scan <project-dir>` (C27).
+ *
+ * Walks the project for UI source files, extracts design tokens (colors,
+ * spacing, typography, radii, shadows) via regex, and writes the result to
+ * `.aperant/design/tokens.json` through `atomicWriteJson`.
+ *
+ * Usage:
+ *
+ *   apt-tools design-scan <project-dir> [--out <path>] [--root <subdir>]
+ *
+ * `--out` overrides the default output location (useful for tests). `--root`
+ * limits the walker to a subdirectory of the project (e.g. `packages/ui`).
+ *
+ * Output envelope (stdout):
+ *
+ *   {
+ *     status: 'ok',
+ *     command: 'design-scan',
+ *     written: '<abs path to tokens.json>',
+ *     summary: { files_scanned, files_skipped, colors, spacing, typography,
+ *                radii, shadows }  // counts per slice
+ *   }
+ *
+ * The command intentionally skips schema validation on the output — if the
+ * scanner produces an invalid shape that's a bug in scan.mjs, not a user
+ * error. Tests cover the schema round-trip.
+ */
+
+import { join, resolve as resolvePath } from 'node:path'
+import { scanDesignTokens } from '../design/scan.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+import { err, ok } from '../util/result.mjs'
+
+export function cmdDesignScan(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err('Usage: apt-tools design-scan <project-dir> [--out <path>] [--root <subdir>]')
+	}
+	const flags = parseFlags(extraArgs ?? [])
+	const outFlag = flags.get('out')
+	const rootFlag = flags.get('root')
+	const absProject = resolvePath(projectDir)
+
+	// Default output: <project>/.aperant/design/tokens.json. Explicit --out
+	// wins (used by tests + ad-hoc scans that don't want to touch .aperant/).
+	const outPath =
+		typeof outFlag === 'string'
+			? resolvePath(outFlag)
+			: join(absProject, '.aperant', 'design', 'tokens.json')
+
+	const tokens = scanDesignTokens(absProject, {
+		root: typeof rootFlag === 'string' ? rootFlag : undefined,
+	})
+
+	// Attach the timestamp here, not in scan.mjs, so scan.mjs stays pure
+	// (important for snapshot tests that compare deterministic outputs).
+	const payload = {
+		...tokens,
+		generated_at: new Date().toISOString(),
+	}
+	// Re-key so the JSON output is in a human-readable field order:
+	// version, generated_at, project_root, scan, then token groups.
+	const ordered = {
+		version: payload.version,
+		generated_at: payload.generated_at,
+		project_root: payload.project_root,
+		scan: payload.scan,
+		colors: payload.colors,
+		spacing: payload.spacing,
+		typography: payload.typography,
+		radii: payload.radii,
+		shadows: payload.shadows,
+	}
+
+	atomicWriteJson(outPath, ordered)
+
+	return ok({
+		status: 'ok',
+		command: 'design-scan',
+		written: outPath,
+		summary: {
+			files_scanned: ordered.scan.files_scanned,
+			files_skipped: ordered.scan.files_skipped,
+			colors: {
+				hex: ordered.colors.hex.length,
+				rgb: ordered.colors.rgb.length,
+				hsl: ordered.colors.hsl.length,
+				tailwind: ordered.colors.tailwind.length,
+				css_vars: ordered.colors.css_vars.length,
+			},
+			spacing: {
+				raw: ordered.spacing.raw.length,
+				tailwind_scale: ordered.spacing.tailwind_scale.length,
+			},
+			typography: {
+				font_families: ordered.typography.font_families.length,
+				font_sizes_raw: ordered.typography.font_sizes_raw.length,
+				tailwind_sizes: ordered.typography.tailwind_sizes.length,
+				line_heights: ordered.typography.line_heights.length,
+			},
+			radii: {
+				raw: ordered.radii.raw.length,
+				tailwind: ordered.radii.tailwind.length,
+			},
+			shadows: {
+				raw: ordered.shadows.raw.length,
+				tailwind: ordered.shadows.tailwind.length,
+			},
+		},
+	})
+}

package/src/cli/commands/design-template.mjs

@@ -0,0 +1,196 @@
+/**
+ * commands/design-template.mjs — `apt-tools design-template <sub>` (C42).
+ *
+ * Curated DESIGN.md template library CLI. Four subcommands:
+ *
+ *   apt-tools design-template list [--library-dir <path>]
+ *     → { status, command, count, entries: [{slug,name,description,origin,source}], warnings }
+ *
+ *   apt-tools design-template show <slug> [--library-dir <path>]
+ *     → { status, command, slug, path, design_md, frontmatter, provenance }
+ *
+ *   apt-tools design-template add <slug> [--project-dir <path>] [--force] [--library-dir <path>]
+ *     → { status, command, slug, from, to, overwritten }
+ *
+ *   apt-tools design-template submit <path> [--as <slug>] [--library-dir <path>] [--force]
+ *     → { status, command, slug, copied_to, provenance_path, warnings }
+ *
+ * Error envelope shape matches design-validate:
+ *   { status: 'error', command: 'design-template', error: '<msg>', ... }
+ * with exit code 1 on any error path. Custom shape preserved verbatim via
+ * the local templateErr() helper that returns { envelope, exitCode: 1 }.
+ *
+ * Wiring: `bin/apt-tools.mjs` routes the `design-template` case into
+ * `cmdDesignTemplate(args[1], args[2], args.slice(3))`.
+ */
+
+import {
+	addLibraryEntry,
+	listLibraryEntries,
+	loadLibraryEntry,
+	submitLibraryEntry,
+} from '../design/template.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { exitWith, ok } from '../util/result.mjs'
+
+/**
+ * Build the design-template custom error envelope. Returns the
+ * {envelope, exitCode} tuple wrap() consumes.
+ *
+ * @param {string} sub
+ * @param {string} message
+ * @param {Record<string, unknown>} [extras]
+ */
+function templateErr(sub, message, extras = {}) {
+	return exitWith(
+		{
+			status: 'error',
+			command: 'design-template',
+			subcommand: sub,
+			error: message,
+			...extras,
+		},
+		1,
+	)
+}
+
+function cmdList(extraArgs) {
+	const flags = parseFlags(extraArgs || [])
+	const libraryDir = typeof flags.get('library-dir') === 'string' ? flags.get('library-dir') : null
+	const { entries, warnings } = listLibraryEntries({ libraryDir })
+	return ok({
+		status: 'ok',
+		command: 'design-template',
+		subcommand: 'list',
+		count: entries.length,
+		entries,
+		warnings,
+	})
+}
+
+function cmdShow(slug, extraArgs) {
+	if (!slug || typeof slug !== 'string' || slug.startsWith('--')) {
+		return templateErr(
+			'show',
+			'Usage: apt-tools design-template show <slug> [--library-dir <path>]',
+		)
+	}
+	const flags = parseFlags(extraArgs || [])
+	const libraryDir = typeof flags.get('library-dir') === 'string' ? flags.get('library-dir') : null
+	try {
+		const entry = loadLibraryEntry({ libraryDir, slug })
+		return ok({
+			status: 'ok',
+			command: 'design-template',
+			subcommand: 'show',
+			slug: entry.slug,
+			path: entry.path,
+			design_md: entry.design_md,
+			frontmatter: entry.frontmatter,
+			provenance: entry.provenance,
+		})
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return templateErr('show', msg, { slug })
+	}
+}
+
+function cmdAdd(slug, extraArgs) {
+	if (!slug || typeof slug !== 'string' || slug.startsWith('--')) {
+		return templateErr(
+			'add',
+			'Usage: apt-tools design-template add <slug> [--project-dir <path>] [--force] [--library-dir <path>]',
+		)
+	}
+	const flags = parseFlags(extraArgs || [])
+	const libraryDir = typeof flags.get('library-dir') === 'string' ? flags.get('library-dir') : null
+	const projectDirFlag = flags.get('project-dir')
+	const projectDir = typeof projectDirFlag === 'string' ? projectDirFlag : process.cwd()
+	const force = flags.get('force') === true || flags.get('force') === 'true'
+	try {
+		const result = addLibraryEntry({ libraryDir, slug, projectDir, force })
+		return ok({
+			status: 'ok',
+			command: 'design-template',
+			subcommand: 'add',
+			slug: result.slug,
+			from: result.from,
+			to: result.to,
+			overwritten: result.overwritten,
+		})
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		// @ts-expect-error — code attached by template.mjs
+		const code = e && e.code ? e.code : null
+		return templateErr('add', msg, { slug, code })
+	}
+}
+
+function cmdSubmit(candidatePath, extraArgs) {
+	if (!candidatePath || typeof candidatePath !== 'string' || candidatePath.startsWith('--')) {
+		return templateErr(
+			'submit',
+			'Usage: apt-tools design-template submit <path-to-DESIGN.md> [--as <slug>] [--library-dir <path>] [--force]',
+		)
+	}
+	const flags = parseFlags(extraArgs || [])
+	const libraryDir = typeof flags.get('library-dir') === 'string' ? flags.get('library-dir') : null
+	const asFlag = flags.get('as')
+	const slug = typeof asFlag === 'string' && asFlag.length > 0 ? asFlag : undefined
+	const force = flags.get('force') === true || flags.get('force') === 'true'
+	try {
+		const result = submitLibraryEntry({ libraryDir, slug, candidatePath, force })
+		return ok({
+			status: 'ok',
+			command: 'design-template',
+			subcommand: 'submit',
+			slug: result.slug,
+			copied_to: result.copied_to,
+			provenance_path: result.provenance_path,
+			warnings: result.warnings,
+		})
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		// @ts-expect-error — code attached by template.mjs
+		const code = e && e.code ? e.code : null
+		// @ts-expect-error — validation attached by template.mjs on EINVALID_CANDIDATE
+		const validation = e && e.validation ? e.validation : null
+		const extras = { code }
+		if (validation && Array.isArray(validation.errors)) {
+			extras.validation_errors = validation.errors
+		}
+		if (validation && Array.isArray(validation.warnings)) {
+			extras.validation_warnings = validation.warnings
+		}
+		return templateErr('submit', msg, extras)
+	}
+}
+
+/**
+ * Entry point for the `design-template` CLI dispatch. The parent bin/apt-tools.mjs
+ * always calls into here — no per-subcommand routing in the dispatcher.
+ *
+ * @param {string | undefined} subcommand
+ * @param {string | undefined} arg1
+ * @param {string[] | undefined} extraArgs
+ */
+export function cmdDesignTemplate(subcommand, arg1, extraArgs) {
+	if (!subcommand || typeof subcommand !== 'string') {
+		return templateErr('(none)', 'Usage: apt-tools design-template <list|show|add|submit> [args]')
+	}
+	switch (subcommand) {
+		case 'list':
+			return cmdList([arg1, ...(extraArgs || [])].filter((v) => v !== undefined))
+		case 'show':
+			return cmdShow(arg1, extraArgs)
+		case 'add':
+			return cmdAdd(arg1, extraArgs)
+		case 'submit':
+			return cmdSubmit(arg1, extraArgs)
+		default:
+			return templateErr(
+				subcommand,
+				`Unknown design-template subcommand: ${subcommand}. Expected: list | show | add | submit.`,
+			)
+	}
+}

package/src/cli/commands/design-validate.mjs

@@ -0,0 +1,83 @@
+/**
+ * commands/design-validate.mjs — `apt-tools design-validate [path]` (C2).
+ *
+ * Validates a DESIGN.md file against the canonical frontmatter schema
+ * (`design/frontmatter-schema.mjs`). Default path is `./DESIGN.md` in the
+ * current working directory.
+ *
+ * Usage:
+ *
+ *   apt-tools design-validate                  # validates ./DESIGN.md
+ *   apt-tools design-validate path/to/DESIGN.md
+ *   apt-tools design-validate --warnings-as-errors
+ *
+ * Output envelope (stdout):
+ *
+ *   {
+ *     status: 'ok' | 'error',
+ *     command: 'design-validate',
+ *     path: '<abs path>',
+ *     errors: [string, ...],
+ *     warnings: [string, ...]
+ *   }
+ *
+ * Exit code is 1 when `errors.length > 0`, or when `warnings.length > 0` and
+ * `--warnings-as-errors` was passed.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+import { validateDesignMarkdown } from '../design/validate.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+/**
+ * @param {string | undefined} pathArg — positional arg from the CLI, may be a flag
+ * @param {string[] | undefined} extraArgs
+ */
+export function cmdDesignValidate(pathArg, extraArgs) {
+	// The first positional may actually be a flag — parseFlags folds all of
+	// args back together and we take the first non-flag as the path.
+	const all = pathArg === undefined ? [] : [pathArg, ...(extraArgs ?? [])]
+	const flags = parseFlags(all)
+	const positional = all.filter((a) => !a.startsWith('--') && a !== 'true' && a !== 'false')
+	const targetArg = positional[0]
+
+	const warningsAsErrors =
+		flags.get('warnings-as-errors') === true || flags.get('warnings-as-errors') === 'true'
+
+	const resolved = resolvePath(
+		process.cwd(),
+		targetArg && targetArg.length > 0 ? targetArg : 'DESIGN.md',
+	)
+
+	if (!existsSync(resolved)) {
+		return err(
+			`DESIGN.md not found at ${resolved}. Run \`/apt:design --new\` first, or pass an explicit path: apt-tools design-validate path/to/DESIGN.md`,
+		)
+	}
+
+	let text
+	try {
+		text = readFileSync(resolved, 'utf8')
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return err(`failed to read ${resolved}: ${msg}`)
+	}
+
+	const result = validateDesignMarkdown(text)
+
+	const hasErrors = result.errors.length > 0
+	const hasWarnings = result.warnings.length > 0
+	const treatAsFailure = hasErrors || (warningsAsErrors && hasWarnings)
+
+	const envelope = {
+		status: treatAsFailure ? 'error' : 'ok',
+		command: 'design-validate',
+		path: resolved,
+		errors: result.errors,
+		warnings: result.warnings,
+	}
+
+	return treatAsFailure ? exitWith(envelope, 1) : ok(envelope)
+}

package/src/cli/commands/detect-project.mjs

@@ -0,0 +1,223 @@
+/**
+ * commands/detect-project.mjs — detect-project command (C29).
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { extname, join, resolve } from 'node:path'
+import { detectWorktree } from '../git/worktree-detect.mjs'
+import { err, ok } from '../util/result.mjs'
+
+export function cmdDetectProject(projectDir) {
+	if (!projectDir) return err('Usage: apt-tools detect-project <project-dir>')
+	const targetDir = resolve(projectDir)
+
+	// Check if already initialized
+	const configPath = join(targetDir, '.aperant', 'config.json')
+	if (existsSync(configPath)) {
+		let existingConfig = null
+		try {
+			existingConfig = JSON.parse(readFileSync(configPath, 'utf-8'))
+		} catch {
+			/* malformed */
+		}
+		return ok({
+			status: 'already-initialized',
+			command: 'detect-project',
+			projectDir: targetDir,
+			project_type: existingConfig?.project_type ?? 'unknown',
+		})
+	}
+
+	// Count source files (common languages — NOT in node_modules, .git, dist, build)
+	const sourceExts = new Set([
+		'.js',
+		'.ts',
+		'.jsx',
+		'.tsx',
+		'.py',
+		'.rs',
+		'.go',
+		'.java',
+		'.rb',
+		'.vue',
+		'.svelte',
+	])
+	const ignoreDirs = new Set([
+		'node_modules',
+		'.git',
+		'dist',
+		'build',
+		'.next',
+		'__pycache__',
+		'target',
+		'vendor',
+	])
+	let sourceFileCount = 0
+	const MAX_SCAN = 500
+
+	function countSources(dir, depth) {
+		if (depth > 5 || sourceFileCount > MAX_SCAN) return
+		try {
+			for (const entry of readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isDirectory() && !ignoreDirs.has(entry.name) && !entry.name.startsWith('.')) {
+					countSources(join(dir, entry.name), depth + 1)
+				} else if (entry.isFile()) {
+					const ext = extname(entry.name)
+					if (sourceExts.has(ext)) sourceFileCount++
+				}
+				if (sourceFileCount > MAX_SCAN) return
+			}
+		} catch {
+			/* permission errors, etc */
+		}
+	}
+	countSources(targetDir, 0)
+
+	// Detect project signals
+	const hasSrcDir = existsSync(join(targetDir, 'src'))
+	const hasPackageJson = existsSync(join(targetDir, 'package.json'))
+	const hasCargoToml = existsSync(join(targetDir, 'Cargo.toml'))
+	const hasPyproject = existsSync(join(targetDir, 'pyproject.toml'))
+	const hasGoMod = existsSync(join(targetDir, 'go.mod'))
+	const hasTsconfig = existsSync(join(targetDir, 'tsconfig.json'))
+	const hasGit = existsSync(join(targetDir, '.git'))
+
+	// Detect existing framework
+	const hasClaudeMd = existsSync(join(targetDir, 'CLAUDE.md'))
+	const hasAgentsMd = existsSync(join(targetDir, 'AGENTS.md'))
+	const hasBmad = existsSync(join(targetDir, '_bmad-output'))
+	const hasPlanning = existsSync(join(targetDir, '.planning'))
+
+	// Read package.json for stack detection
+	let packageJson = null
+	if (hasPackageJson) {
+		try {
+			packageJson = JSON.parse(readFileSync(join(targetDir, 'package.json'), 'utf-8'))
+		} catch {
+			/* malformed */
+		}
+	}
+
+	const deps = { ...packageJson?.dependencies, ...packageJson?.devDependencies }
+	const detectedStack = []
+	if (deps) {
+		if (deps['react']) detectedStack.push('React ' + (deps['react'].replace(/[\^~]/, '') || ''))
+		if (deps['next']) detectedStack.push('Next.js')
+		if (deps['vue']) detectedStack.push('Vue')
+		if (deps['svelte'] || deps['@sveltejs/kit']) detectedStack.push('Svelte')
+		if (deps['express']) detectedStack.push('Express')
+		if (deps['fastify']) detectedStack.push('Fastify')
+		if (deps['convex']) detectedStack.push('Convex')
+		if (deps['prisma'] || deps['@prisma/client']) detectedStack.push('Prisma')
+		if (deps['drizzle-orm']) detectedStack.push('Drizzle')
+		if (deps['tailwindcss']) detectedStack.push('Tailwind CSS')
+		if (deps['typescript']) detectedStack.push('TypeScript')
+		if (deps['vitest']) detectedStack.push('Vitest')
+		if (deps['jest']) detectedStack.push('Jest')
+		if (deps['electron']) detectedStack.push('Electron')
+	}
+
+	// Git commit count (cheap heuristic for fresh init)
+	let commitCount = 0
+	if (hasGit) {
+		try {
+			const count = execSync('git rev-list --count HEAD 2>/dev/null', {
+				cwd: targetDir,
+				encoding: 'utf-8',
+			}).trim()
+			commitCount = parseInt(count, 10) || 0
+		} catch {
+			commitCount = 0
+		}
+	}
+
+	// Greenfield vs brownfield (per spec 4.2, addressing G10: scaffold-aware)
+	const isScaffolded = hasPackageJson && sourceFileCount > 15 && commitCount <= 3
+	const isGreenfield =
+		!isScaffolded && (!hasSrcDir || sourceFileCount < 5 || (hasGit && commitCount <= 1))
+
+	// Detect project type (addressing G2)
+	let projectType = 'unknown'
+	if (hasPackageJson) {
+		const pkg = packageJson
+		if (pkg?.workspaces || existsSync(join(targetDir, 'pnpm-workspace.yaml'))) {
+			projectType = 'monorepo'
+		} else if (pkg?.bin) {
+			projectType = 'cli-tool'
+		} else if (
+			deps?.['next'] ||
+			deps?.['react'] ||
+			deps?.['vue'] ||
+			deps?.['svelte'] ||
+			deps?.['@sveltejs/kit']
+		) {
+			projectType = 'web-app'
+		} else if (deps?.['express'] || deps?.['fastify'] || deps?.['hono'] || deps?.['koa']) {
+			projectType = 'api-service'
+		} else if (pkg?.main || pkg?.module || pkg?.exports) {
+			projectType = 'library'
+		}
+	} else if (hasCargoToml || hasGoMod || hasPyproject) {
+		projectType = 'cli-tool'
+	}
+
+	// Framework-aware risk map defaults (addressing G11)
+	const riskMapDefaults = {
+		critical_paths: [
+			'**/auth/**',
+			'**/middleware/auth*',
+			'**/*.env*',
+			'**/migration*/**',
+			'**/schema*',
+		],
+		elevated_paths: ['**/api/**', '**/routes/**', '**/store/**', '**/hooks/use*'],
+		safe_paths: ['**/*.css', '**/*.md', '**/*.test.*', '**/*.spec.*'],
+	}
+	if (deps?.['next']) {
+		riskMapDefaults.critical_paths.push('**/middleware.ts', '**/middleware.js')
+		riskMapDefaults.elevated_paths.push('**/app/api/**', '**/pages/api/**')
+	}
+	if (deps?.['convex']) {
+		riskMapDefaults.critical_paths.push('**/convex/schema.*', '**/convex/auth.*')
+		riskMapDefaults.elevated_paths.push('**/convex/**')
+	}
+	if (deps?.['prisma'] || deps?.['@prisma/client']) {
+		riskMapDefaults.critical_paths.push('**/prisma/schema.prisma', '**/prisma/migrations/**')
+	}
+	if (deps?.['drizzle-orm']) {
+		riskMapDefaults.critical_paths.push('**/drizzle/**', '**/db/schema.*')
+	}
+
+	// Check for test infrastructure
+	const hasTests =
+		existsSync(join(targetDir, '__tests__')) ||
+		existsSync(join(targetDir, 'tests')) ||
+		existsSync(join(targetDir, 'test')) ||
+		(deps && (deps['vitest'] || deps['jest'] || deps['mocha']))
+
+	return ok({
+		status: 'ok',
+		command: 'detect-project',
+		projectDir: targetDir,
+		classification: isGreenfield ? 'greenfield' : 'brownfield',
+		is_scaffolded: isScaffolded,
+		project_type: projectType,
+		source_file_count: Math.min(sourceFileCount, MAX_SCAN),
+		has_src_dir: hasSrcDir,
+		has_git: hasGit,
+		commit_count: commitCount,
+		has_tests: hasTests,
+		detected_stack: detectedStack,
+		risk_map_defaults: riskMapDefaults,
+		existing_framework: {
+			claude_md: hasClaudeMd,
+			agents_md: hasAgentsMd,
+			bmad: hasBmad,
+			planning: hasPlanning,
+		},
+		package_name: packageJson?.name ?? null,
+		package_description: packageJson?.description ?? null,
+		worktree: detectWorktree(targetDir),
+	})
+}