@aperant/framework 0.6.2

package/src/cli/output-style/ansi.mjs

@@ -0,0 +1,89 @@
+/**
+ * output-style/ansi.mjs — C22 primitive layer.
+ *
+ * Pure-Node ANSI escape helpers. No external dependencies. All rendering is
+ * gated through `supportsColor({ stream, env })` so callers can pass explicit
+ * streams/env stubs in tests — we never mutate process globals.
+ *
+ * See docs/frameworks/spec-gaps.md#c22 and packages/framework/docs/output-style.md.
+ */
+
+const RESET = '\x1b[0m'
+
+/**
+ * SGR codes used by the helper set. Exported so the test suite can assert on
+ * the exact escape sequences without hard-coding magic numbers.
+ */
+export const SGR = Object.freeze({
+	bold: '\x1b[1m',
+	dim: '\x1b[2m',
+	italic: '\x1b[3m',
+	underline: '\x1b[4m',
+	reset: RESET,
+	// 8-color palette — 30-37 foreground. 256-color / truecolor would give us
+	// nicer accents but breaks in plain xterms and stack-traces harder to read.
+	red: '\x1b[31m',
+	green: '\x1b[32m',
+	yellow: '\x1b[33m',
+	blue: '\x1b[34m',
+	magenta: '\x1b[35m',
+	cyan: '\x1b[36m',
+	gray: '\x1b[90m',
+})
+
+/**
+ * Does the runtime support ANSI color on this stream?
+ *
+ *   - NO_COLOR (any non-empty value) → always false (https://no-color.org/).
+ *   - FORCE_COLOR (any non-empty value other than "0") → always true.
+ *   - Otherwise: true iff `stream.isTTY`.
+ *
+ * Pure function; takes explicit stream + env so tests can stub without
+ * touching process globals.
+ */
+export function supportsColor({ stream, env } = {}) {
+	const e = env || process.env
+	const noColor = e.NO_COLOR
+	if (noColor !== undefined && noColor !== '') return false
+	const force = e.FORCE_COLOR
+	if (force !== undefined && force !== '' && force !== '0') return true
+	const s = stream || process.stdout
+	return Boolean(s && s.isTTY)
+}
+
+/**
+ * Wrap `text` in one or more SGR codes. When `color` is false, returns `text`
+ * unchanged — this keeps snapshot tests deterministic and lets consumers pipe
+ * into `jq` without stripping escapes.
+ *
+ * Accepts either a single code string or an array of codes (concatenated).
+ */
+export function style(text, codes, { color = true } = {}) {
+	if (!color) return String(text)
+	const open = Array.isArray(codes) ? codes.join('') : String(codes || '')
+	if (!open) return String(text)
+	return `${open}${text}${RESET}`
+}
+
+/** Convenience wrappers — all take `(text, { color })`. */
+export function bold(text, opts) {
+	return style(text, SGR.bold, opts)
+}
+export function dim(text, opts) {
+	return style(text, SGR.dim, opts)
+}
+export function red(text, opts) {
+	return style(text, SGR.red, opts)
+}
+export function green(text, opts) {
+	return style(text, SGR.green, opts)
+}
+export function yellow(text, opts) {
+	return style(text, SGR.yellow, opts)
+}
+export function cyan(text, opts) {
+	return style(text, SGR.cyan, opts)
+}
+export function gray(text, opts) {
+	return style(text, SGR.gray, opts)
+}

package/src/cli/output-style/helpers.mjs

@@ -0,0 +1,184 @@
+/**
+ * output-style/helpers.mjs — C22 composable render helpers.
+ *
+ * All helpers accept `{ color }` (default `true`). When `color` is false, the
+ * return value is plain ASCII/Unicode with no ANSI escapes — so pipelines into
+ * `jq`, `tee -a file`, or a log line always look identical.
+ *
+ * The underlying SGR wrapping lives in ansi.mjs. This module is pure string
+ * formatting; no I/O, no process globals, no date `Date.now()` mutation —
+ * relative-time takes an explicit `now` so tests stay deterministic.
+ */
+
+import { bold, cyan, dim, gray, green, red, yellow } from './ansi.mjs'
+
+const BULLET = '·'
+const ICON_OK = '✓'
+const ICON_FAIL = '✗'
+const ICON_PENDING = '⋯'
+const EM_DASH = '—'
+
+/**
+ * @typedef {{ color?: boolean }} ColorOpts
+ */
+
+/**
+ * Bold header line with optional trailing newline suppressed for composition.
+ *
+ * @param {string} title
+ * @param {ColorOpts} [opts]
+ * @returns {string}
+ */
+export function section(title, { color = true } = {}) {
+	return bold(String(title), { color })
+}
+
+/**
+ * `· text` bullet with an optional status icon.
+ *
+ * status:
+ *   'ok'      → green ✓
+ *   'fail'    → red   ✗
+ *   'pending' → yellow ⋯
+ *   undefined → bare   ·
+ *
+ * @param {string} text
+ * @param {'ok'|'fail'|'pending'|string} [status]
+ * @param {ColorOpts} [opts]
+ * @returns {string}
+ */
+export function bullet(text, status, { color = true } = {}) {
+	if (!status) {
+		return `${dim(BULLET, { color })} ${text}`
+	}
+	let icon
+	if (status === 'ok') icon = green(ICON_OK, { color })
+	else if (status === 'fail') icon = red(ICON_FAIL, { color })
+	else if (status === 'pending') icon = yellow(ICON_PENDING, { color })
+	else icon = dim(BULLET, { color })
+	return `${icon} ${text}`
+}
+
+/**
+ * `dim(key): bold(value)` — the canonical "one fact per line" format used in
+ * the TTY-sidecar previews on `state` / `active`.
+ *
+ * @param {string} key
+ * @param {unknown} value
+ * @param {ColorOpts} [opts]
+ * @returns {string}
+ */
+export function kv(key, value, { color = true } = {}) {
+	const k = dim(`${key}:`, { color })
+	const v = bold(value === null || value === undefined ? EM_DASH : String(value), { color })
+	return `${k} ${v}`
+}
+
+/**
+ * Minimal aligned ASCII table. `rows` is an array of objects; `headers`
+ * defaults to the keys of the first row. Returns `''` for an empty rows list
+ * (no blank-table noise on TTY-sidecar output).
+ *
+ * @param {Array<Record<string, unknown>> | null | undefined} rows
+ * @param {string[]} [headers]
+ * @param {ColorOpts} [opts]
+ * @returns {string}
+ */
+export function table(rows, headers, { color = true } = {}) {
+	if (!Array.isArray(rows) || rows.length === 0) return ''
+	const cols = Array.isArray(headers) && headers.length > 0 ? headers : Object.keys(rows[0] || {})
+	if (cols.length === 0) return ''
+
+	// Pre-stringify every cell so we can compute widths without double work.
+	const body = rows.map((row) =>
+		cols.map((c) => {
+			const v = /** @type {Record<string, unknown>} */ (row)[c]
+			return v === undefined || v === null ? '' : String(v)
+		}),
+	)
+	const widths = cols.map((c, i) => Math.max(c.length, ...body.map((r) => r[i].length)))
+
+	const head = cols.map((c, i) => bold(c.padEnd(widths[i]), { color })).join('  ')
+	const sep = widths.map((w) => '-'.repeat(w)).join('  ')
+	const lines = body.map((r) => r.map((cell, i) => cell.padEnd(widths[i])).join('  '))
+	return [head, sep, ...lines].join('\n')
+}
+
+/**
+ * Relative-time formatter — "just now", "5s ago", "12m ago", "3h ago",
+ * "2d ago". Accepts any ISO string or epoch ms. Takes explicit `now` so unit
+ * tests don't need to freeze clocks.
+ *
+ * Returns `'—'` when the input is missing/unparseable so composition always
+ * produces a fixed-width line.
+ *
+ * @param {string | number | null | undefined} when
+ * @param {number} [now]
+ * @returns {string}
+ */
+export function relativeTime(when, now = Date.now()) {
+	if (!when) return EM_DASH
+	const t = typeof when === 'number' ? when : Date.parse(when)
+	if (!Number.isFinite(t)) return EM_DASH
+	const diffMs = now - t
+	if (diffMs < 0) return 'in the future'
+	const s = Math.floor(diffMs / 1000)
+	if (s < 5) return 'just now'
+	if (s < 60) return `${s}s ago`
+	const m = Math.floor(s / 60)
+	if (m < 60) return `${m}m ago`
+	const h = Math.floor(m / 60)
+	if (h < 24) return `${h}h ago`
+	const d = Math.floor(h / 24)
+	return `${d}d ago`
+}
+
+/**
+ * @typedef {Object} StatusLineData
+ * @property {number | Record<string, unknown>} [active_tasks]
+ * @property {string | null} [current_phase]
+ * @property {string | number | null} [last_activity]
+ * @property {number} [team_count]
+ */
+
+/**
+ * @typedef {Object} StatusLineOpts
+ * @property {boolean} [color]
+ * @property {number} [now]
+ */
+
+// C56 B5 — compact phase labels. Keeps the statusline narrow when the
+// underlying lifecycle value is multi-hyphenated (`shipped-pending-merge`).
+// Unknown values render verbatim — additive enum values pass through.
+/** @type {Record<string, string>} */
+const PHASE_LABEL = {
+	'shipped-pending-merge': 'shipped',
+}
+
+/**
+ * Compact single-line status string suitable for embedding in a shell prompt
+ * or external statusline tool. Missing fields render as dim em-dashes so the
+ * line has a consistent shape.
+ *
+ * Shape:
+ *   {icon} aperant {dim(·)} tasks {count} {dim(·)} phase {name} {dim(·)} team {n} {dim(·)} {relative}
+ *
+ * @param {StatusLineData} [data]
+ * @param {StatusLineOpts} [opts]
+ * @returns {string}
+ */
+export function statusLine(
+	{ active_tasks = 0, current_phase = null, last_activity = null, team_count = 0 } = {},
+	{ color = true, now = undefined } = {},
+) {
+	const taskCount =
+		typeof active_tasks === 'number' ? active_tasks : Object.keys(active_tasks || {}).length
+	const icon = taskCount > 0 ? green('●', { color }) : gray('○', { color })
+	const sep = dim(BULLET, { color })
+	const phaseLabel = current_phase ? (PHASE_LABEL[current_phase] ?? String(current_phase)) : null
+	const phase = phaseLabel ? cyan(phaseLabel, { color }) : dim(EM_DASH, { color })
+	const rel = last_activity ? relativeTime(last_activity, now) : EM_DASH
+	const relStyled = last_activity ? dim(rel, { color }) : dim(EM_DASH, { color })
+	const label = bold('aperant', { color })
+	return `${icon} ${label} ${sep} tasks ${bold(String(taskCount), { color })} ${sep} phase ${phase} ${sep} team ${bold(String(team_count), { color })} ${sep} ${relStyled}`
+}

package/src/cli/output-style/index.mjs

@@ -0,0 +1,9 @@
+/**
+ * output-style/index.mjs — barrel re-export for C22 helpers.
+ *
+ * Import surface:
+ *   import { section, bullet, kv, table, statusLine, supportsColor } from '../output-style/index.mjs'
+ */
+
+export { bold, cyan, dim, gray, green, red, SGR, style, supportsColor, yellow } from './ansi.mjs'
+export { bullet, kv, relativeTime, section, statusLine, table } from './helpers.mjs'

package/src/cli/personas/role-scan.mjs

@@ -0,0 +1,323 @@
+/**
+ * personas/role-scan.mjs — C48 deterministic role-signal detector.
+ *
+ * Scans the target project for role-ish signals that let the apt:personas
+ * SKILL.md body (LLM) ground its persona drafts in real code — NOT invent
+ * personas from prose alone.
+ *
+ * Design principle: no LLM call, no network, no heavy AST. This helper
+ * returns a structured `findings[]` list. The SKILL.md body reads that list
+ * AND the PROJECT.md target-audience prose AND .aperant/product-context.json
+ * and produces the final persona JSON. If this file ever starts talking to
+ * an LLM, the split is broken — move the LLM call up to the skill body
+ * and keep this helper deterministic.
+ *
+ * Signals (ordered by discriminating power):
+ *
+ *   1. `role` / `userRole` / `isAdmin` / `isStaff` / `isOwner` identifier
+ *      references — string constants, boolean checks, enum shapes. High
+ *      confidence when the identifier is used in conditionals.
+ *   2. `/api/<role>/` or `/<role>/` route prefixes in Next.js `app/` or
+ *      Express-style path strings. Medium-high confidence.
+ *   3. RBAC-shaped patterns: `Role`, `Permission`, `can*`, `hasRole`,
+ *      `requireAuth`, `policy` naming. Medium confidence.
+ *   4. Schema / validator enums: `v.union(v.literal('admin'), ...)` or
+ *      `z.enum(['admin',...])`. High confidence — these are usually the
+ *      canonical role list for the product.
+ *
+ * We cap scan to a bounded sample (fileCap=400 source files, lineCap=2000
+ * lines per file) so the helper stays fast even on large monorepos. The
+ * SKILL.md body reads the raw `findings[]` + decides what to escalate —
+ * this is signal extraction, not classification.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { extname, join, resolve } from 'node:path'
+
+const SOURCE_EXTENSIONS = new Set([
+	'.ts',
+	'.tsx',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.py',
+	'.rs',
+	'.go',
+	'.java',
+	'.rb',
+])
+
+const IGNORE_DIRS = new Set([
+	'node_modules',
+	'.git',
+	'.aperant',
+	'dist',
+	'build',
+	'.next',
+	'.turbo',
+	'.vercel',
+	'.cache',
+	'target',
+	'vendor',
+	'__pycache__',
+	'coverage',
+	'out',
+])
+
+/**
+ * @typedef {Object} RoleFinding
+ * @property {string} file            Repo-relative path.
+ * @property {number} line            1-indexed line number where the signal appears.
+ * @property {string} matched         The substring that matched.
+ * @property {'identifier' | 'route-prefix' | 'rbac-pattern' | 'validator-enum'} kind
+ * @property {'low' | 'medium' | 'high'} confidence
+ */
+
+/**
+ * @typedef {Object} RoleScanResult
+ * @property {string} projectDir
+ * @property {number} files_scanned
+ * @property {number} files_with_signal
+ * @property {RoleFinding[]} findings
+ * @property {string[]} unique_role_strings  De-duped role names seen in enums / literals
+ * @property {{ truncated: boolean, reason: string | null }} limits
+ */
+
+const IDENTIFIER_RE =
+	/\b(isAdmin|isStaff|isOwner|userRole|currentRole|roleName|user\.role|session\.user\.role)\b/
+const ROUTE_PREFIX_RE =
+	/['"`](?:\/api)?\/(admin|owner|staff|user|member|student|teacher|coach|parent|guest|customer|buyer|seller|manager|doctor|patient|driver|rider|host|viewer|creator|artist|editor|reviewer|approver|superadmin|client|worker|vendor|contractor|employee|agent|operator)(?:\/|['"` ])/i
+const RBAC_RE =
+	/\b(Role|Permission|canEdit|canView|canManage|hasRole|hasPermission|requireRole|requireAuth|authorize|policy(?:Id|Name)?)\b/
+const VALIDATOR_LITERAL_RE =
+	/v\.literal\(\s*['"]([a-z][a-z_-]*)['"]\s*\)|z\.literal\(\s*['"]([a-z][a-z_-]*)['"]\s*\)/gi
+const VALIDATOR_ENUM_RE = /z\.enum\s*\(\s*\[([^\]]+)\]/gi
+
+/**
+ * Walk a directory tree, yielding paths with interesting extensions. Bounded.
+ *
+ * @param {string} root
+ * @param {number} fileCap
+ * @returns {{ files: string[], truncated: boolean }}
+ */
+function collectSourceFiles(root, fileCap) {
+	/** @type {string[]} */
+	const out = []
+	/** @type {string[]} */
+	const stack = [root]
+	let truncated = false
+	while (stack.length > 0 && out.length < fileCap) {
+		const dir = /** @type {string} */ (stack.pop())
+		let entries
+		try {
+			entries = readdirSync(dir, { withFileTypes: true })
+		} catch {
+			continue
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith('.') && IGNORE_DIRS.has(entry.name)) continue
+			const full = join(dir, entry.name)
+			if (entry.isDirectory()) {
+				if (IGNORE_DIRS.has(entry.name)) continue
+				stack.push(full)
+				continue
+			}
+			if (!entry.isFile()) continue
+			const ext = extname(entry.name)
+			if (!SOURCE_EXTENSIONS.has(ext)) continue
+			out.push(full)
+			if (out.length >= fileCap) {
+				truncated = true
+				break
+			}
+		}
+	}
+	return { files: out, truncated }
+}
+
+/**
+ * Turn an absolute path into a repo-relative one.
+ *
+ * @param {string} abs
+ * @param {string} root
+ */
+function rel(abs, root) {
+	if (abs.startsWith(root + '/')) return abs.slice(root.length + 1)
+	if (abs === root) return ''
+	return abs
+}
+
+/**
+ * Scan a single file and return role-signal findings. Bounded to the first
+ * `lineCap` lines.
+ *
+ * @param {string} path
+ * @param {string} repoRoot
+ * @param {number} lineCap
+ * @returns {RoleFinding[]}
+ */
+function scanFile(path, repoRoot, lineCap) {
+	let text
+	try {
+		text = readFileSync(path, 'utf-8')
+	} catch {
+		return []
+	}
+	const lines = text.split(/\r?\n/).slice(0, lineCap)
+	/** @type {RoleFinding[]} */
+	const findings = []
+	const relPath = rel(path, repoRoot)
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		if (line.length === 0) continue
+
+		const idMatch = IDENTIFIER_RE.exec(line)
+		if (idMatch) {
+			findings.push({
+				file: relPath,
+				line: i + 1,
+				matched: idMatch[0],
+				kind: 'identifier',
+				confidence: 'high',
+			})
+		}
+
+		const routeMatch = ROUTE_PREFIX_RE.exec(line)
+		if (routeMatch) {
+			findings.push({
+				file: relPath,
+				line: i + 1,
+				matched: routeMatch[0],
+				kind: 'route-prefix',
+				confidence: 'medium',
+			})
+		}
+
+		// RBAC pattern matches are noisy; require the path to look policy-ish
+		// or the identifier to be more than a bare `Role` word in a comment.
+		const rbacMatch = RBAC_RE.exec(line)
+		if (rbacMatch && !/^\s*(\/\/|#|\*|\/\*)/.test(line)) {
+			findings.push({
+				file: relPath,
+				line: i + 1,
+				matched: rbacMatch[0],
+				kind: 'rbac-pattern',
+				confidence: 'medium',
+			})
+		}
+
+		// Validator literals are very high signal — every match IS a named role.
+		VALIDATOR_LITERAL_RE.lastIndex = 0
+		let lit
+		lit = VALIDATOR_LITERAL_RE.exec(line)
+		while (lit !== null) {
+			const role = lit[1] ?? lit[2]
+			if (role) {
+				findings.push({
+					file: relPath,
+					line: i + 1,
+					matched: role,
+					kind: 'validator-enum',
+					confidence: 'high',
+				})
+			}
+			lit = VALIDATOR_LITERAL_RE.exec(line)
+		}
+
+		VALIDATOR_ENUM_RE.lastIndex = 0
+		let enumMatch
+		enumMatch = VALIDATOR_ENUM_RE.exec(line)
+		while (enumMatch !== null) {
+			const body = enumMatch[1]
+			const items = body
+				.split(',')
+				.map((x) => x.trim().replace(/^['"`]|['"`]$/g, ''))
+				.filter((x) => /^[a-z][a-z_-]*$/.test(x))
+			for (const item of items) {
+				findings.push({
+					file: relPath,
+					line: i + 1,
+					matched: item,
+					kind: 'validator-enum',
+					confidence: 'high',
+				})
+			}
+			enumMatch = VALIDATOR_ENUM_RE.exec(line)
+		}
+	}
+	return findings
+}
+
+/**
+ * Run a bounded role-signal scan over a project directory.
+ *
+ * @param {string} projectDir
+ * @param {{ fileCap?: number, lineCap?: number }} [opts]
+ * @returns {RoleScanResult}
+ */
+export function runRoleScan(projectDir, opts = {}) {
+	const abs = resolve(projectDir)
+	const fileCap = opts.fileCap ?? 400
+	const lineCap = opts.lineCap ?? 2000
+
+	let stats
+	try {
+		stats = statSync(abs)
+	} catch {
+		return {
+			projectDir: abs,
+			files_scanned: 0,
+			files_with_signal: 0,
+			findings: [],
+			unique_role_strings: [],
+			limits: { truncated: false, reason: 'project dir missing' },
+		}
+	}
+	if (!stats.isDirectory()) {
+		return {
+			projectDir: abs,
+			files_scanned: 0,
+			files_with_signal: 0,
+			findings: [],
+			unique_role_strings: [],
+			limits: { truncated: false, reason: 'project path is not a directory' },
+		}
+	}
+
+	const { files, truncated } = collectSourceFiles(abs, fileCap)
+	/** @type {RoleFinding[]} */
+	const all = []
+	const withSignal = new Set()
+	for (const f of files) {
+		const findings = scanFile(f, abs, lineCap)
+		if (findings.length > 0) {
+			withSignal.add(f)
+			all.push(...findings)
+		}
+	}
+
+	// De-duped role strings seen in high-confidence signals — the SKILL.md body
+	// uses this as the shortlist of candidate role names.
+	const uniq = new Set()
+	for (const f of all) {
+		if (f.kind !== 'validator-enum' && f.kind !== 'route-prefix') continue
+		const clean = f.matched
+			.toLowerCase()
+			.replace(/^['"`/]+|['"` ]+$/g, '')
+			.replace(/^api\//, '')
+		if (/^[a-z][a-z_-]{1,30}$/.test(clean)) uniq.add(clean)
+	}
+
+	return {
+		projectDir: abs,
+		files_scanned: files.length,
+		files_with_signal: withSignal.size,
+		findings: all,
+		unique_role_strings: [...uniq].sort(),
+		limits: {
+			truncated,
+			reason: truncated ? `scan capped at ${fileCap} source files` : null,
+		},
+	}
+}