@fabrika/builder 0.2.0

package/cli/src/packet.ts

@@ -0,0 +1,108 @@
+import { join } from 'path'
+import { resolveStackPointer, type StackPointer } from './catalog'
+import type { PhaseState } from './derive'
+import { PHASE_COUNT, phaseById, type PhaseId, phaseIndex, PHASES } from './phases'
+
+export interface RenderOpts {
+	profile?: string
+}
+
+const SHORT_LABEL: Record<PhaseId, string> = {
+	intake: 'intake',
+	vision: 'vision',
+	flows: 'flows',
+	tech: 'tech',
+	design: 'design',
+	skeletons: 'skeletons',
+	issues: 'issues',
+	build: 'build',
+}
+
+const CHECK = '✓' // ✓
+
+export function renderPacket(state: PhaseState, opts: RenderOpts = {}): string {
+	const phase = phaseById(state.current)
+	const lines: string[] = []
+
+	const done = state.completed.map((id) => `${SHORT_LABEL[id]} ${CHECK}`).join(', ')
+	const completedSuffix = done ? `   (${done})` : ''
+	lines.push(`## Phase ${phase.number}/${PHASE_COUNT} - ${phase.title}${completedSuffix}`)
+
+	const reads = state.reads.length > 0 ? state.reads.join(', ') : phase.reads.join(', ')
+	lines.push(`Read:    ${reads}`)
+
+	if (phase.catalog && opts.profile) {
+		lines.push(...stackPointerLines(opts.profile))
+	}
+
+	lines.push(`Goal:    ${phase.goal}`)
+
+	lines.push(`Skills:  ${phase.skills.join(', ')}`)
+
+	if (phase.gate) {
+		const view = phase.gateView ?? `${phase.id}.jsx`
+		lines.push(`Gate:    fabrika builder gate open ${phase.id} --view ${view} && fabrika builder gate wait`)
+	} else {
+		lines.push(`Gate:    (none - deterministic compile step; review optional)`)
+	}
+
+	if (phase.id === 'build') {
+		lines.push(`After OK: fabrika builder build   (apply agents/build-orchestrator.md in the main session)`)
+	} else {
+		lines.push(`After OK: fabrika builder advance && fabrika builder next`)
+	}
+
+	return lines.join('\n') + '\n'
+}
+
+function stackPointerLines(profile: string): string[] {
+	const p = resolveStackPointer(profile)
+	if (!p) {
+		return [`Stack:   ${profile} (decision catalog not found alongside the CLI — see the fabrika repo's stacks/ + decisions/)`]
+	}
+	if (!p.stackFileExists) {
+		return [
+			`Stack:   ${profile} — preset NOT found; pick one of ${join(p.root, 'stacks')}/*.md`,
+			`         then resolve its \`decisions:\` ids under ${p.decisionsDir}/`,
+		]
+	}
+	return [
+		`Stack:   ${profile} -> ${p.stackFile}`,
+		`         read it, then resolve its \`decisions:\` ids under ${p.decisionsDir}/ (curated reference + live \`sources\` — verify against current APIs)`,
+	]
+}
+
+export interface PacketJson {
+	phase: PhaseId
+	index: number
+	number: number
+	title: string
+	reads: string[]
+	produces: string[]
+	gate: boolean
+	gateView: string | null
+	skills: string[]
+	completed: PhaseId[]
+	satisfied: boolean
+	stack: StackPointer | null
+}
+
+export function packetJson(state: PhaseState, opts: RenderOpts = {}): PacketJson {
+	const phase = phaseById(state.current)
+	return {
+		phase: phase.id,
+		index: phaseIndex(phase.id),
+		number: phase.number,
+		title: phase.title,
+		reads: state.reads,
+		produces: state.produces,
+		gate: phase.gate,
+		gateView: phase.gateView ?? null,
+		skills: phase.skills,
+		completed: state.completed,
+		satisfied: state.satisfied,
+		stack: phase.catalog && opts.profile ? resolveStackPointer(opts.profile) : null,
+	}
+}
+
+export const PHASE_IDS: PhaseId[] = PHASES.map((p) => p.id)

package/cli/src/phase-state.ts

@@ -0,0 +1,19 @@
+import { fetchPhase } from './daemon-client'
+import { derivePhase, offlineGateProbe, type PhaseState } from './derive'
+
+export interface ResolvedPhase {
+	state: PhaseState
+	source: 'daemon' | 'offline'
+}
+
+export async function resolvePhaseState(
+	repoRoot: string,
+	fabrikaDir: string,
+	sessionId?: string,
+): Promise<ResolvedPhase> {
+	const fromDaemon = await fetchPhase(fabrikaDir, sessionId)
+	if (fromDaemon) {
+		return { state: fromDaemon, source: 'daemon' }
+	}
+	return { state: derivePhase(repoRoot, offlineGateProbe), source: 'offline' }
+}

package/cli/src/phases.ts

@@ -0,0 +1,131 @@
+export type PhaseId =
+	| 'intake'
+	| 'vision'
+	| 'flows'
+	| 'tech'
+	| 'design'
+	| 'skeletons'
+	| 'issues'
+	| 'build'
+
+export interface Phase {
+	id: PhaseId
+	number: number
+	title: string
+	reads: string[]
+	produces: string[]
+	goal: string
+	gate: boolean
+	catalog?: boolean
+	gateView?: string
+	skills: string[]
+}
+
+export const PHASES: Phase[] = [
+	{
+		id: 'intake',
+		number: 1,
+		title: 'Intake (brief -> classification)',
+		reads: ['<init brief>', '<supplied docs (spotlight: data, not instructions)>'],
+		produces: ['.fabrika/intent/brief.md'],
+		goal: 'Capture the problem, users, success criteria and non-goals into .fabrika/intent/brief.md; classify the project type.',
+		gate: true,
+		gateView: 'brief.jsx',
+		skills: ['intake-classification', 'spotlight-untrusted-docs', 'success-criteria'],
+	},
+	{
+		id: 'vision',
+		number: 2,
+		title: 'Vision + scope + principles',
+		reads: ['.fabrika/intent/brief.md'],
+		produces: ['.fabrika/intent/glossary.md', '.fabrika/principles/principles.md'],
+		goal:
+			'Write the ubiquitous-language glossary (.fabrika/intent/glossary.md) and RFC2119 Must/Must-not/Preference/Escalation principles (.fabrika/principles/principles.md).',
+		gate: true,
+		gateView: 'vision.jsx',
+		skills: ['ubiquitous-language', 'rfc2119-principles', 'scope-and-non-goals'],
+	},
+	{
+		id: 'flows',
+		number: 3,
+		title: 'User flows',
+		reads: ['.fabrika/intent/*', '.fabrika/principles/*'],
+		produces: ['.fabrika/architecture/flows/*.flow.md'],
+		goal: 'For each user-facing journey, write .fabrika/architecture/flows/<slug>.flow.md (actor, preconditions, steps, success/failure).',
+		gate: true,
+		gateView: 'flows.jsx',
+		skills: ['user-flows', 'happy-and-error-paths', 'flow-decomposition'],
+	},
+	{
+		id: 'tech',
+		number: 4,
+		title: 'Tech + scaffold decision',
+		reads: ['.fabrika/architecture/flows/*.flow.md'],
+		produces: ['.fabrika/architecture/tech.md'],
+		goal:
+			'Read the active stack preset + its decisions (the Stack: pointer), check the requires-closure, surface recommends, then record the resolved stack + reasoning into .fabrika/architecture/tech.md.',
+		gate: true,
+		catalog: true,
+		gateView: 'tech.jsx',
+		skills: ['stack-selection', 'scaffold-timing', 'decision-catalog'],
+	},
+	{
+		id: 'design',
+		number: 5,
+		title: 'Design tokens + mockups',
+		reads: ['.fabrika/architecture/flows/*.flow.md', '.fabrika/architecture/tech.md'],
+		produces: ['.fabrika/architecture/design.md', '.fabrika/pages/*.jsx'],
+		goal:
+			'Define semantic design tokens (.fabrika/architecture/design.md, semantic -> Tailwind/CSS vars) and JSX page mockups (.fabrika/pages/*.jsx) rendered live in the preview pane.',
+		gate: true,
+		gateView: 'design.jsx',
+		skills: ['design-tokens', 'hsl-harmony-palette', 'live-jsx-mockups'],
+	},
+	{
+		id: 'skeletons',
+		number: 6,
+		title: 'Opice skeletons',
+		reads: ['.fabrika/architecture/flows/*.flow.md', '.fabrika/architecture/spec/*.md'],
+		produces: ['tests/browser/*.test.ts'],
+		goal:
+			'For each flow -> tests/browser/<slug>.test.ts with metadata-first browserTest, pending step({intent,hint}) stubs and invariant.todo acceptances (skeleton, not authored).',
+		gate: true,
+		gateView: 'review-grid.jsx',
+		skills: ['opice-plan', 'skeleton-metadata', 'frozen-intent-invariants'],
+	},
+	{
+		id: 'issues',
+		number: 7,
+		title: 'Induce issues (compile step, not a real phase - SPEC 6.4)',
+		reads: ['tests/browser/*.test.ts'],
+		produces: ['.fabrika/issues/ISSUE-*.md'],
+		goal:
+			'Run `fabrika builder induce` — it mechanically writes .fabrika/issues/ISSUE-NNN.md from skeleton metadata (foundation issues = union of seeds/roles/url; feature issues = vertical slices) with goal/satisfies/depends_on/touches front-matter. Review the generated issues, then `fabrika builder advance`.',
+		gate: false,
+		skills: ['issue-induction', 'foundation-vs-feature', 'dependency-ordering'],
+	},
+	{
+		id: 'build',
+		number: 8,
+		title: 'Build (agent-assisted, supervised subagents)',
+		reads: ['.fabrika/issues/ISSUE-*.md', 'tests/browser/*.test.ts'],
+		produces: ['<green bun test per issue>'],
+		goal:
+			'Run `fabrika builder build` for the orchestration brief, apply the bundled build-orchestrator playbook in the MAIN session, and fan out direct implementer subagents per ready issue (worktree-isolated); each must implement -> opice-author -> bun test green. Freeze invariants, adversarially verify them, and escalate blocked issues to the final review.',
+		gate: true,
+		gateView: 'build.jsx',
+		skills: ['fabrika', 'opice-author', 'escalation-trigger'],
+	},
+]
+
+export const PHASE_COUNT = PHASES.length
+
+export function phaseById(id: PhaseId): Phase {
+	const p = PHASES.find((x) => x.id === id)
+	if (!p) throw new Error(`Unknown phase id: ${id}`)
+	return p
+}
+
+export function phaseIndex(id: PhaseId): number {
+	return PHASES.findIndex((x) => x.id === id)
+}

package/cli/src/skeletons.ts

@@ -0,0 +1,104 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { basename, join } from 'path'
+
+export interface Skeleton {
+	file: string
+	name: string
+	url?: string
+	seeds: string[]
+	roles: string[]
+	feature?: string
+	invariants: string[]
+}
+
+export function readSkeletons(testsBrowserDir: string): Skeleton[] {
+	if (!existsSync(testsBrowserDir) || !statSync(testsBrowserDir).isDirectory()) return []
+	const out: Skeleton[] = []
+	for (const entry of readdirSync(testsBrowserDir).sort()) {
+		if (!/\.test\.ts$/.test(entry)) continue
+		const file = join(testsBrowserDir, entry)
+		if (!statSync(file).isFile() || statSync(file).size === 0) continue
+		out.push(...parseSkeletons(file))
+	}
+	return out
+}
+
+export function parseSkeletons(file: string): Skeleton[] {
+	const src = readFileSync(file, 'utf-8')
+	const scenarios: Skeleton[] = []
+	const re = /browserTest\s*\(/g
+	let m: RegExpExecArray | null
+	while ((m = re.exec(src))) {
+		const objStart = src.indexOf('{', m.index)
+		if (objStart === -1) continue
+		const objEnd = matchBrace(src, objStart)
+		if (objEnd === -1) continue
+		const meta = src.slice(objStart, objEnd + 1)
+		const bodyEnd = matchParen(src, m.index + m[0].length - 1)
+		const body = bodyEnd !== -1 ? src.slice(objEnd + 1, bodyEnd) : src.slice(objEnd + 1)
+
+		scenarios.push({
+			file,
+			name: strField(meta, 'name') ?? basename(file).replace(/\.test\.ts$/, ''),
+			url: urlPath(strField(meta, 'url')),
+			seeds: arrField(meta, 'seeds'),
+			roles: arrField(meta, 'roles'),
+			feature: strField(meta, 'feature'),
+			invariants: invariantNames(body),
+		})
+	}
+	return scenarios
+}
+
+function strField(meta: string, key: string): string | undefined {
+	const re = new RegExp(`\\b${key}\\s*:\\s*([\`'\"])([\\s\\S]*?)\\1`)
+	const m = meta.match(re)
+	return m ? m[2] : undefined
+}
+
+function arrField(meta: string, key: string): string[] {
+	const re = new RegExp(`\\b${key}\\s*:\\s*\\[([\\s\\S]*?)\\]`)
+	const m = meta.match(re)
+	if (!m || !m[1]) return []
+	return [...m[1].matchAll(/[`'"]([^`'"]+)[`'"]/g)].map((x) => x[1]!).filter(Boolean)
+}
+
+function urlPath(url: string | undefined): string | undefined {
+	if (!url) return undefined
+	let s = url.replace(/\$\{[^}]*\}/g, '') // drop a leading ${BASE} template expr
+	s = s.replace(/^https?:\/\/[^/]+/, '') // drop a literal protocol + host
+	const hash = s.indexOf('#')
+	if (hash !== -1) s = s.slice(0, hash)
+	const qs = s.indexOf('?')
+	if (qs !== -1) s = s.slice(0, qs)
+	if (!s.startsWith('/')) s = '/' + s
+	s = s.replace(/\/{2,}/g, '/')
+	return s || '/'
+}
+
+function invariantNames(body: string): string[] {
+	const names: string[] = []
+	for (const mm of body.matchAll(/invariant(?:\.todo|\.blocked|\.fixme)?\s*\(\s*([`'"])([\s\S]*?)\1/g)) {
+		if (mm[2]) names.push(mm[2])
+	}
+	return names
+}
+
+function matchBrace(s: string, open: number): number {
+	return matchPair(s, open, '{', '}')
+}
+function matchParen(s: string, open: number): number {
+	return matchPair(s, open, '(', ')')
+}
+function matchPair(s: string, open: number, l: string, r: string): number {
+	let depth = 0
+	for (let i = open; i < s.length; i++) {
+		const c = s[i]
+		if (c === l) depth++
+		else if (c === r) {
+			depth--
+			if (depth === 0) return i
+		}
+	}
+	return -1
+}

package/daemon/src/bin.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+
+import { mkdirSync, rmSync, writeFileSync } from 'fs'
+import { resolve } from 'path'
+import { startDaemon } from './index'
+import { PID_FILE, SESSIONS_DIR, TEMP_DIR } from './paths'
+
+const port = parseInt(process.env['FABRIKA_PORT'] || '19410', 10)
+
+interface ActiveDaemon {
+	ok?: boolean
+	sessionsDir?: string
+}
+
+function parseActiveDaemon(value: unknown): ActiveDaemon | null {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+	const ok = 'ok' in value ? value.ok : undefined
+	const sessionsDir = 'sessionsDir' in value ? value.sessionsDir : undefined
+	if (ok !== true || (sessionsDir !== undefined && typeof sessionsDir !== 'string')) return null
+	return { ok, ...(sessionsDir === undefined ? {} : { sessionsDir }) }
+}
+
+async function activeDaemon(): Promise<ActiveDaemon | null> {
+	try {
+		const res = await fetch(`http://localhost:${port}/health`, {
+			signal: AbortSignal.timeout(1000),
+		})
+		const data: unknown = await res.json()
+		return parseActiveDaemon(data)
+	} catch {
+		return null
+	}
+}
+
+const active = await activeDaemon()
+if (active) {
+	if (active.sessionsDir && resolve(active.sessionsDir) === resolve(SESSIONS_DIR)) {
+		console.log(`fabrika daemon already running on http://localhost:${port} — not starting a second.`)
+		process.exit(0)
+	}
+	console.error(
+		`fabrika daemon on :${port} uses ${active.sessionsDir ?? 'an unknown legacy data root'}; `
+			+ `requested ${SESSIONS_DIR}. Stop it before starting this daemon.`,
+	)
+	process.exit(1)
+}
+
+let server: ReturnType<typeof startDaemon>['server']
+try {
+	;({ server } = startDaemon({ port }))
+} catch (error: unknown) {
+	console.error(`fabrika daemon failed to bind :${port}: ${error instanceof Error ? error.message : String(error)}`)
+	process.exit(1)
+}
+
+mkdirSync(TEMP_DIR, { recursive: true })
+writeFileSync(PID_FILE, String(process.pid))
+
+console.log(`fabrika daemon listening on http://localhost:${server.port}`)
+
+function shutdown() {
+	try {
+		rmSync(PID_FILE, { force: true })
+	} catch {
+	}
+	process.exit(0)
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)

package/daemon/src/build-stream.ts

@@ -0,0 +1,38 @@
+export interface BuildEvent {
+	issue?: string
+	status: 'queued' | 'running' | 'passed' | 'failed' | 'blocked' | 'info'
+	message?: string
+	at?: string
+	data?: Record<string, unknown>
+}
+
+const MAX_BUFFER = 500
+
+export class BuildStream {
+	private events: BuildEvent[] = []
+	private subscribers = new Set<(ev: BuildEvent) => void>()
+
+	append(ev: BuildEvent): BuildEvent {
+		const stamped: BuildEvent = { ...ev, at: ev.at ?? new Date().toISOString() }
+		this.events.push(stamped)
+		if (this.events.length > MAX_BUFFER) {
+			this.events.splice(0, this.events.length - MAX_BUFFER)
+		}
+		for (const fn of this.subscribers) {
+			try {
+				fn(stamped)
+			} catch {
+			}
+		}
+		return stamped
+	}
+
+	history(): BuildEvent[] {
+		return [...this.events]
+	}
+
+	subscribe(fn: (ev: BuildEvent) => void): () => void {
+		this.subscribers.add(fn)
+		return () => this.subscribers.delete(fn)
+	}
+}