@aperant/framework 0.6.2

package/src/cli/commands/variant-gallery.mjs

@@ -0,0 +1,167 @@
+/**
+ * commands/variant-gallery.mjs — `apt-tools variant-gallery <task-dir>` (C1, Wave 2).
+ *
+ * Scans <task-dir>/mockups/ for `iteration-NNN-variant-<letter>.html` files,
+ * renders a gallery HTML that iframes each variant side-by-side, and writes
+ * it as `iteration-NNN-gallery.html`.  The user opens the gallery via
+ * `file://` and runs `/apt:mockup --pick <letter>` to promote one variant.
+ *
+ * Usage:
+ *
+ *   apt-tools variant-gallery <task-dir>                        # latest iteration
+ *   apt-tools variant-gallery <task-dir> --iteration 001
+ *   apt-tools variant-gallery <task-dir> --iteration 002 --feature "settings page"
+ *   apt-tools variant-gallery <task-dir> --styles a=paper,b=bento,c=clean
+ *
+ * Output envelope (stdout):
+ *
+ *   {
+ *     status: "ok",
+ *     command: "variant-gallery",
+ *     written: "<abs path to gallery html>",
+ *     iteration: "001",
+ *     variants: [{ letter, filename, style, description }, ...],
+ *     skipped: [string, ...]          // files that didn't match the naming contract
+ *   }
+ *
+ * Exit non-zero when the mockups directory has zero matching variants —
+ * the skill is supposed to write them before calling this command, so an
+ * empty pool is almost always an integration bug.
+ */
+
+import { existsSync, readdirSync, writeFileSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+import { renderGallery, variantEntriesFromFilenames } from '../variant/gallery.mjs'
+
+/**
+ * Scan the mockups dir for iteration-NNN-variant-X.html filenames and
+ * return the highest NNN present.  Returns null when nothing matches.
+ *
+ * @param {string[]} filenames
+ * @returns {string | null}
+ */
+function detectLatestIteration(filenames) {
+	const re = /^iteration-(\d{3})-variant-[a-z]\.html$/i
+	const seen = new Set()
+	for (const name of filenames) {
+		const m = name.match(re)
+		if (m) seen.add(m[1])
+	}
+	if (seen.size === 0) return null
+	const sorted = [...seen].sort()
+	return sorted[sorted.length - 1] ?? null
+}
+
+/**
+ * Parse `--styles a=paper,b=bento,c=clean` into a `{ a: { style: "paper" } }` record.
+ * Unknown-format entries are silently skipped (the skill is allowed to pass
+ * partial metadata).
+ *
+ * @param {string | undefined | true} raw
+ * @returns {Record<string, { style?: string, description?: string }>}
+ */
+function parseStylesFlag(raw) {
+	if (typeof raw !== 'string' || raw.length === 0) return {}
+	const out = {}
+	for (const pair of raw.split(',')) {
+		const trimmed = pair.trim()
+		if (!trimmed) continue
+		const eq = trimmed.indexOf('=')
+		if (eq <= 0) continue
+		const letter = trimmed.slice(0, eq).trim().toLowerCase()
+		const style = trimmed.slice(eq + 1).trim()
+		if (!letter || !style) continue
+		out[letter] = { style }
+	}
+	return out
+}
+
+export function cmdVariantGallery(taskDirArg, extraArgs) {
+	if (!taskDirArg || typeof taskDirArg !== 'string' || taskDirArg.startsWith('--')) {
+		return err(
+			'Usage: apt-tools variant-gallery <task-dir> [--iteration NNN] [--feature "<text>"] [--styles a=slug,b=slug,...]',
+		)
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const iterationFlag = flags.get('iteration')
+	const featureFlag = flags.get('feature')
+	const stylesFlag = flags.get('styles')
+
+	const taskDir = resolvePath(process.cwd(), taskDirArg)
+	const mockupsDir = resolvePath(taskDir, 'mockups')
+
+	if (!existsSync(mockupsDir)) {
+		return err(`variant-gallery: mockups directory does not exist at ${mockupsDir}`)
+	}
+
+	let entries
+	try {
+		entries = readdirSync(mockupsDir)
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return err(`variant-gallery: failed to read ${mockupsDir}: ${msg}`)
+	}
+
+	// Resolve iteration — explicit flag wins, else scan for latest.
+	const iteration =
+		typeof iterationFlag === 'string' && /^\d{1,3}$/.test(iterationFlag)
+			? iterationFlag.padStart(3, '0')
+			: detectLatestIteration(entries)
+
+	if (!iteration) {
+		return err(
+			`variant-gallery: no iteration-NNN-variant-X.html files found under ${mockupsDir}. Run \`/apt:mockup --variants N\` first.`,
+		)
+	}
+
+	// Filter to the chosen iteration's variant files.
+	const iterationPrefix = `iteration-${iteration}-variant-`
+	const variantFilenames = entries
+		.filter((n) => n.startsWith(iterationPrefix) && n.endsWith('.html'))
+		.sort()
+
+	const styleByLetter = parseStylesFlag(typeof stylesFlag === 'string' ? stylesFlag : undefined)
+	const { variants, skipped } = variantEntriesFromFilenames(variantFilenames, styleByLetter)
+
+	if (variants.length === 0) {
+		return err(
+			`variant-gallery: no variant files match iteration ${iteration}. Expected e.g. iteration-${iteration}-variant-a.html under ${mockupsDir}.`,
+		)
+	}
+
+	const feature =
+		typeof featureFlag === 'string' && featureFlag.length > 0
+			? featureFlag
+			: '(unspecified feature)'
+	const html = renderGallery({
+		feature,
+		iteration,
+		variants,
+		taskDir,
+	})
+
+	const galleryPath = resolvePath(mockupsDir, `iteration-${iteration}-gallery.html`)
+	try {
+		writeFileSync(galleryPath, html, 'utf8')
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return err(`variant-gallery: failed to write ${galleryPath}: ${msg}`)
+	}
+
+	return ok({
+		status: 'ok',
+		command: 'variant-gallery',
+		written: galleryPath,
+		iteration,
+		variants: variants.map((v) => ({
+			letter: v.letter,
+			filename: v.filename,
+			style: v.style ?? null,
+			description: v.description ?? null,
+		})),
+		skipped,
+	})
+}

package/src/cli/commands/variant-pick.mjs

@@ -0,0 +1,103 @@
+/**
+ * commands/variant-pick.mjs — `apt-tools variant-pick <task-dir> <letter>` (C1, Wave 2).
+ *
+ * Promotes one variant from a `--variants N` run to the canonical
+ * iteration file and archives the others.  Called by `/apt:mockup --pick`
+ * (the skill does the user-facing prompt + next-step messaging; this
+ * command does the deterministic filesystem work).
+ *
+ * Usage:
+ *
+ *   apt-tools variant-pick <task-dir> <letter>                 # latest iteration
+ *   apt-tools variant-pick <task-dir> <letter> --iteration 002
+ *
+ * Output envelope (stdout):
+ *
+ *   {
+ *     status: "ok",
+ *     command: "variant-pick",
+ *     iteration: "001",
+ *     letter: "b",
+ *     promoted: "<abs path to iteration-001.html>",
+ *     source: "<abs path to iteration-001-variant-b.html>",
+ *     archive_dir: "<abs path to iteration-001-archive/>",
+ *     archived: [string, ...]
+ *   }
+ */
+
+import { existsSync, readdirSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+import { promoteVariant } from '../variant/pick.mjs'
+
+function detectLatestIteration(entries) {
+	const re = /^iteration-(\d{3})-variant-[a-z]\.html$/i
+	const seen = new Set()
+	for (const name of entries) {
+		const m = name.match(re)
+		if (m) seen.add(m[1])
+	}
+	if (seen.size === 0) return null
+	const sorted = [...seen].sort()
+	return sorted[sorted.length - 1] ?? null
+}
+
+export function cmdVariantPick(taskDirArg, letterArg, extraArgs) {
+	if (
+		!taskDirArg ||
+		typeof taskDirArg !== 'string' ||
+		taskDirArg.startsWith('--') ||
+		!letterArg ||
+		typeof letterArg !== 'string' ||
+		letterArg.startsWith('--')
+	) {
+		return err('Usage: apt-tools variant-pick <task-dir> <letter> [--iteration NNN]')
+	}
+
+	const letterRaw = letterArg.trim().toLowerCase()
+	if (!/^[a-z]$/.test(letterRaw)) {
+		return err(`variant-pick: <letter> must be a single letter (a-z), got "${letterArg}"`)
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const iterationFlag = flags.get('iteration')
+
+	const taskDir = resolvePath(process.cwd(), taskDirArg)
+	const mockupsDir = resolvePath(taskDir, 'mockups')
+	if (!existsSync(mockupsDir)) {
+		return err(`variant-pick: mockups directory does not exist at ${mockupsDir}`)
+	}
+
+	let iteration
+	if (typeof iterationFlag === 'string' && /^\d{1,3}$/.test(iterationFlag)) {
+		iteration = iterationFlag.padStart(3, '0')
+	} else {
+		const entries = readdirSync(mockupsDir)
+		iteration = detectLatestIteration(entries)
+		if (!iteration) {
+			return err(
+				`variant-pick: no iteration-NNN-variant-X.html files under ${mockupsDir}. Run \`/apt:mockup --variants N\` first.`,
+			)
+		}
+	}
+
+	let result
+	try {
+		result = promoteVariant({ mockupsDir, iteration, letter: letterRaw })
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e)
+		return err(`variant-pick: ${msg}`)
+	}
+
+	return ok({
+		status: 'ok',
+		command: 'variant-pick',
+		iteration: result.iteration,
+		letter: result.letter,
+		promoted: result.promoted,
+		source: result.source,
+		archive_dir: result.archiveDir,
+		archived: result.archived,
+	})
+}

package/src/cli/commands/variant-pool.mjs

@@ -0,0 +1,104 @@
+/**
+ * commands/variant-pool.mjs — `apt-tools variant-pool [opts]` (C1, Wave 2).
+ *
+ * Deterministic resolver that returns N typeui-sh style slugs for the
+ * `apt:mockup --variants N` flow.  The skill invokes this CLI before
+ * spawning N sub-agents in parallel — each sub-agent is handed one
+ * `{ slug, name, description, path }` tuple from the returned list and
+ * seeds its HTML generation with the referenced SKILL.md.
+ *
+ * Usage:
+ *
+ *   apt-tools variant-pool                       # 3 default slugs
+ *   apt-tools variant-pool --n 4                 # 4 slugs
+ *   apt-tools variant-pool --taste ./taste.yaml  # filter by direction
+ *   apt-tools variant-pool --styles-dir <path>   # override typeui-sh path
+ *
+ * Output envelope (stdout):
+ *
+ *   {
+ *     status: "ok",
+ *     command: "variant-pool",
+ *     n: 3,
+ *     styles: [{ slug, name, description, path }, ...],
+ *     warnings: [string, ...]
+ *   }
+ *
+ * `path` is the absolute path to the style's SKILL.md so the orchestrator
+ * can pass it straight to the spawned sub-agent's context.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parse as parseYaml } from 'yaml'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+import { resolveVariantPool } from '../variant/pool.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// commands/variant-pool.mjs → ../../../../docs/frameworks/…/typeui-sh
+// Resolved relative to the shipping package so the CLI works from any cwd.
+const DEFAULT_STYLES_DIR = resolvePath(
+	__dirname,
+	'..',
+	'..',
+	'..',
+	'..',
+	'..',
+	'docs',
+	'frameworks',
+	'Design-system',
+	'examples',
+	'by-source',
+	'typeui-sh',
+)
+
+export function cmdVariantPool(extraArgs) {
+	const flags = parseFlags(extraArgs ?? [])
+	const nFlag = flags.get('n')
+	const tasteFlag = flags.get('taste')
+	const stylesDirFlag = flags.get('styles-dir')
+
+	const n = typeof nFlag === 'string' || typeof nFlag === 'number' ? nFlag : 3
+	const stylesDir =
+		typeof stylesDirFlag === 'string' && stylesDirFlag.length > 0
+			? resolvePath(stylesDirFlag)
+			: DEFAULT_STYLES_DIR
+
+	if (!existsSync(stylesDir)) {
+		return err(
+			`variant-pool: styles directory not found at ${stylesDir}. Pass --styles-dir <path> or re-install the framework.`,
+		)
+	}
+
+	let taste = null
+	if (typeof tasteFlag === 'string' && tasteFlag.length > 0) {
+		const tastePath = resolvePath(tasteFlag)
+		if (!existsSync(tastePath)) {
+			return err(`variant-pool: taste file not found at ${tastePath}`)
+		}
+		try {
+			const text = readFileSync(tastePath, 'utf8')
+			const parsed = parseYaml(text)
+			if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+				taste = /** @type {{ direction?: string }} */ (parsed)
+			}
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e)
+			return err(`variant-pool: failed to parse taste file ${tastePath}: ${msg}`)
+		}
+	}
+
+	const { slugs, warnings } = resolveVariantPool({ n, taste, stylesDir })
+
+	return ok({
+		status: 'ok',
+		command: 'variant-pool',
+		n: slugs.length,
+		styles: slugs,
+		warnings,
+	})
+}

package/src/cli/commands/wave.mjs

@@ -0,0 +1,206 @@
+/**
+ * commands/wave.mjs — wave analyzer (C29).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+export function cmdWave(subcommand, projectDir, extraArgs) {
+	if (!subcommand)
+		return err('Usage: apt-tools wave <analyze> <project-dir> [--plan <path>] [--wave <N>]')
+
+	switch (subcommand) {
+		case 'analyze': {
+			if (!projectDir)
+				return err('Usage: apt-tools wave analyze <project-dir> [--plan <path>] [--wave <N>]')
+			const targetDir = resolve(projectDir)
+
+			// Determine plan path
+			const planIdx = extraArgs.indexOf('--plan')
+			const planPath =
+				planIdx >= 0 && extraArgs[planIdx + 1]
+					? resolve(extraArgs[planIdx + 1])
+					: join(targetDir, 'implementation_plan.json')
+
+			// Parse --wave N filter
+			const waveIdx = extraArgs.indexOf('--wave')
+			const waveFilter =
+				waveIdx >= 0 && extraArgs[waveIdx + 1] ? parseInt(extraArgs[waveIdx + 1], 10) : null
+
+			// Read and validate plan JSON (T-11-05: validate structure)
+			if (!existsSync(planPath)) return err(`Plan file not found: ${planPath}`)
+			let plan
+			try {
+				plan = JSON.parse(readFileSync(planPath, 'utf-8'))
+			} catch (e) {
+				return err(`Invalid JSON in plan file: ${e.message}`)
+			}
+
+			if (!plan.subtasks || !Array.isArray(plan.subtasks)) {
+				return err('Plan must contain a "subtasks" array')
+			}
+
+			// Validate each subtask has required fields
+			for (const st of plan.subtasks) {
+				if (!st.id) return err(`Subtask missing "id" field: ${JSON.stringify(st)}`)
+				if (!Array.isArray(st.dependencies)) {
+					return err(`Subtask "${st.id}" missing "dependencies" array`)
+				}
+			}
+
+			const subtaskMap = new Map()
+			for (const st of plan.subtasks) {
+				subtaskMap.set(st.id, st)
+			}
+
+			// Validate all dependencies reference existing subtasks
+			for (const st of plan.subtasks) {
+				for (const dep of st.dependencies) {
+					if (!subtaskMap.has(dep)) {
+						return err(`Subtask "${st.id}" depends on unknown subtask "${dep}"`)
+					}
+				}
+			}
+
+			// Detect cycles using DFS with coloring (T-11-06: prevents infinite loops)
+			const WHITE = 0,
+				GRAY = 1,
+				BLACK = 2
+			const color = new Map()
+			for (const st of plan.subtasks) color.set(st.id, WHITE)
+			let cycleFound = null
+
+			function dfs(id, path) {
+				if (cycleFound) return
+				color.set(id, GRAY)
+				path.push(id)
+				const st = subtaskMap.get(id)
+				for (const dep of st.dependencies) {
+					if (color.get(dep) === GRAY) {
+						// Found cycle: extract from dep to current position
+						const cycleStart = path.indexOf(dep)
+						cycleFound = path.slice(cycleStart).concat(dep)
+						return
+					}
+					if (color.get(dep) === WHITE) {
+						dfs(dep, path)
+					}
+				}
+				path.pop()
+				color.set(id, BLACK)
+			}
+
+			for (const st of plan.subtasks) {
+				if (color.get(st.id) === WHITE) {
+					dfs(st.id, [])
+				}
+				if (cycleFound) break
+			}
+
+			if (cycleFound) {
+				return exitWith({ error: 'Circular dependency detected', cycle: cycleFound }, 1)
+			}
+
+			// Wave assignment algorithm (D-12, D-13)
+			const waveAssignment = new Map() // subtask id -> wave number
+			const assigned = new Set()
+
+			// Wave 1: subtasks with no dependencies
+			for (const st of plan.subtasks) {
+				if (st.dependencies.length === 0) {
+					waveAssignment.set(st.id, 1)
+					assigned.add(st.id)
+				}
+			}
+
+			// Iteratively assign remaining subtasks
+			let currentWave = 1
+			let progress = true
+			while (assigned.size < plan.subtasks.length && progress) {
+				progress = false
+				currentWave++
+				for (const st of plan.subtasks) {
+					if (assigned.has(st.id)) continue
+					// Check if ALL dependencies are assigned
+					const allDepsAssigned = st.dependencies.every((dep) => assigned.has(dep))
+					if (allDepsAssigned) {
+						const maxDepWave = Math.max(...st.dependencies.map((dep) => waveAssignment.get(dep)))
+						waveAssignment.set(st.id, maxDepWave + 1)
+						assigned.add(st.id)
+						progress = true
+					}
+				}
+			}
+
+			if (assigned.size < plan.subtasks.length) {
+				const unassigned = plan.subtasks.filter((st) => !assigned.has(st.id)).map((st) => st.id)
+				return err(
+					`Could not assign all subtasks to waves. Missing dependency or orphan subtasks: ${unassigned.join(', ')}`,
+				)
+			}
+
+			// Build wave groups
+			const totalWaves = Math.max(...waveAssignment.values())
+			const wavesMap = new Map()
+			for (let w = 1; w <= totalWaves; w++) {
+				wavesMap.set(w, { wave: w, subtasks: [], files: [] })
+			}
+
+			for (const st of plan.subtasks) {
+				const w = waveAssignment.get(st.id)
+				wavesMap.get(w).subtasks.push(st.id)
+				if (Array.isArray(st.files)) {
+					for (const f of st.files) {
+						if (!wavesMap.get(w).files.includes(f)) {
+							wavesMap.get(w).files.push(f)
+						}
+					}
+				}
+			}
+
+			// File conflict check: files appearing in multiple subtasks within same wave
+			const fileConflicts = []
+			for (const [w, group] of wavesMap) {
+				const fileOwners = new Map()
+				for (const stId of group.subtasks) {
+					const st = subtaskMap.get(stId)
+					if (Array.isArray(st.files)) {
+						for (const f of st.files) {
+							if (!fileOwners.has(f)) fileOwners.set(f, [])
+							fileOwners.get(f).push(stId)
+						}
+					}
+				}
+				for (const [file, owners] of fileOwners) {
+					if (owners.length > 1) {
+						fileConflicts.push({ wave: w, file, subtasks: owners })
+					}
+				}
+			}
+
+			// Build subtask_wave_map
+			const subtaskWaveMap = {}
+			for (const [id, w] of waveAssignment) {
+				subtaskWaveMap[id] = w
+			}
+
+			// Apply --wave N filter (D-16)
+			let waves = Array.from(wavesMap.values())
+			if (waveFilter !== null) {
+				waves = waves.filter((w) => w.wave === waveFilter)
+			}
+
+			return ok({
+				status: 'ok',
+				command: 'wave-analyze',
+				total_waves: totalWaves,
+				waves,
+				file_conflicts: fileConflicts,
+				subtask_wave_map: subtaskWaveMap,
+			})
+		}
+		default:
+			return err(`Unknown wave subcommand: ${subcommand}. Available: analyze`)
+	}
+}

package/src/cli/commands/wfrun.mjs

@@ -0,0 +1,72 @@
+/**
+ * commands/wfrun.mjs — C17 declarative-workflow CLI entry.
+ *
+ * Usage:
+ *   apt-tools wfrun validate <workflow.yaml>
+ *   apt-tools wfrun plan <workflow.yaml> [--input k=v] …
+ *   apt-tools wfrun run  <workflow.yaml> [--input k=v] … [--project-dir <path>]
+ *
+ * Shape mirrors cmdWorkflow (C29 phase-enforcement): (subcommand, positional,
+ * extraArgs). The second positional in the dispatch table (bin/apt-tools.mjs)
+ * is the workflow YAML path — not a project dir. The project dir for
+ * .aperant/wfrun/** writes defaults to process.cwd() and can be overridden
+ * via the --project-dir flag.
+ *
+ * This command does NOT overload the existing `workflow` command — see
+ * docs/workflows.md for the naming-collision note.
+ */
+
+import { resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+import { parseInputFlags, runWfrun } from '../wfrun/run.mjs'
+
+export async function cmdWfrun(subcommand, workflowPath, extraArgs = []) {
+	if (!subcommand) {
+		return err('Usage: apt-tools wfrun <validate|plan|run> <workflow.yaml> [--input k=v …]')
+	}
+	if (!['validate', 'plan', 'run'].includes(subcommand)) {
+		return err(`Unknown wfrun subcommand: ${subcommand}. Expected: validate, plan, run`)
+	}
+	if (!workflowPath) {
+		return err(`Usage: apt-tools wfrun ${subcommand} <workflow.yaml> [--input k=v …]`)
+	}
+
+	const inputRes = parseInputFlags(extraArgs)
+	if (!inputRes.ok) {
+		return exitWith(
+			{
+				status: 'error',
+				command: `wfrun-${subcommand}`,
+				errors: inputRes.errors.map((m) => ({ path: '--input', message: m })),
+			},
+			1,
+		)
+	}
+
+	const flags = parseFlags(
+		extraArgs.filter((a, i, arr) => a !== '--input' && arr[i - 1] !== '--input'),
+	)
+	const projectDirFlag = flags.get('project-dir')
+	const projectRoot = typeof projectDirFlag === 'string' ? resolve(projectDirFlag) : process.cwd()
+
+	const res = await runWfrun({
+		subcommand,
+		workflowPath,
+		projectDir: projectRoot,
+		inputs: inputRes.inputs,
+	})
+
+	if (!res.ok) {
+		return exitWith(
+			{
+				status: 'error',
+				command: `wfrun-${subcommand}`,
+				errors: res.errors,
+			},
+			1,
+		)
+	}
+
+	return ok(res.result)
+}