@fabrika/builder 0.2.0

package/cli/src/daemon-client.ts

@@ -0,0 +1,280 @@
+import { resolve } from 'path'
+import { BASE_URL, SESSIONS_DIR, TIMEOUT_MS, WS_URL } from './config'
+import type { PhaseState } from './derive'
+import { PHASES } from './phases'
+
+const HEALTH_TIMEOUT_MS = 1000
+
+export interface HealthInfo {
+	ok: boolean
+	version?: string
+	pid?: number
+	dataDir?: string
+	sessionsDir?: string
+	sessions?: number | string[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function optionalString(value: unknown): string | undefined {
+	return typeof value === 'string' ? value : undefined
+}
+
+function optionalNumber(value: unknown): number | undefined {
+	return typeof value === 'number' ? value : undefined
+}
+
+function optionalBoolean(value: unknown): boolean | undefined {
+	return typeof value === 'boolean' ? value : undefined
+}
+
+function stringArray(value: unknown): string[] | null {
+	if (!Array.isArray(value) || !value.every((item: unknown) => typeof item === 'string')) return null
+	return value
+}
+
+function parseHealthInfo(value: unknown): HealthInfo | null {
+	if (!isRecord(value) || value['ok'] !== true) return null
+	const sessions = typeof value['sessions'] === 'number' ? value['sessions'] : stringArray(value['sessions']) ?? undefined
+	return {
+		ok: true,
+		...(optionalString(value['version']) === undefined ? {} : { version: optionalString(value['version']) }),
+		...(optionalNumber(value['pid']) === undefined ? {} : { pid: optionalNumber(value['pid']) }),
+		...(optionalString(value['dataDir']) === undefined ? {} : { dataDir: optionalString(value['dataDir']) }),
+		...(optionalString(value['sessionsDir']) === undefined ? {} : { sessionsDir: optionalString(value['sessionsDir']) }),
+		...(sessions === undefined ? {} : { sessions }),
+	}
+}
+
+function isPhaseId(value: unknown): value is PhaseState['current'] {
+	return typeof value === 'string' && PHASES.some((phase) => phase.id === value)
+}
+
+function parsePhaseState(value: unknown): PhaseState | null {
+	if (!isRecord(value) || !isPhaseId(value['current']) || typeof value['index'] !== 'number') return null
+	const rawCompleted = value['completed']
+	const completed = Array.isArray(rawCompleted) ? rawCompleted.filter(isPhaseId) : null
+	const reads = stringArray(value['reads'])
+	const produces = stringArray(value['produces'])
+	if (completed === null || !Array.isArray(rawCompleted) || completed.length !== rawCompleted.length || reads === null || produces === null) {
+		return null
+	}
+	if (typeof value['gate'] !== 'boolean' || typeof value['satisfied'] !== 'boolean') return null
+	return {
+		current: value['current'],
+		index: value['index'],
+		completed,
+		reads,
+		produces,
+		gate: value['gate'],
+		satisfied: value['satisfied'],
+	}
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+	if (!isRecord(value)) return undefined
+	const result: Record<string, string> = {}
+	for (const [key, entry] of Object.entries(value)) {
+		if (typeof entry !== 'string') return undefined
+		result[key] = entry
+	}
+	return result
+}
+
+function parsePlanResult(value: unknown): PlanResult {
+	if (!isRecord(value) || typeof value['ok'] !== 'boolean') return { ok: false, error: 'Invalid daemon response' }
+	return {
+		ok: value['ok'],
+		...(optionalString(value['browserUrl']) === undefined ? {} : { browserUrl: optionalString(value['browserUrl']) }),
+		...(optionalNumber(value['revision']) === undefined ? {} : { revision: optionalNumber(value['revision']) }),
+		...(optionalBoolean(value['isNew']) === undefined ? {} : { isNew: optionalBoolean(value['isNew']) }),
+		...(stringArray(value['canvasFiles']) === null ? {} : { canvasFiles: stringArray(value['canvasFiles']) ?? [] }),
+		...(optionalString(value['gate']) === undefined ? {} : { gate: optionalString(value['gate']) }),
+		...(optionalString(value['error']) === undefined ? {} : { error: optionalString(value['error']) }),
+		...(stringRecord(value['errors']) === undefined ? {} : { errors: stringRecord(value['errors']) }),
+	}
+}
+
+export async function health(): Promise<HealthInfo | null> {
+	try {
+		const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) })
+		const data: unknown = await res.json()
+		return parseHealthInfo(data)
+	} catch {
+		return null
+	}
+}
+
+export async function isDaemonRunning(): Promise<boolean> {
+	const info = await health()
+	return info !== null && healthMatchesDataRoot(info)
+}
+
+export function healthMatchesDataRoot(
+	info: HealthInfo,
+	expectedSessionsDir: string = SESSIONS_DIR,
+): boolean {
+	if (!info.sessionsDir) return false
+	return comparablePath(info.sessionsDir) === comparablePath(expectedSessionsDir)
+}
+
+function comparablePath(path: string): string {
+	const absolute = resolve(path)
+	return process.platform === 'win32' ? absolute.toLowerCase() : absolute
+}
+
+export async function fetchPhase(fabrikaDir: string, sessionId?: string): Promise<PhaseState | null> {
+	try {
+		let url = `${BASE_URL}/api/phase?root=${encodeURIComponent(fabrikaDir)}`
+		if (sessionId) url += `&session=${encodeURIComponent(sessionId)}`
+		const res = await fetch(url, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) })
+		if (!res.ok) return null
+		const data: unknown = await res.json()
+		return parsePhaseState(data)
+	} catch {
+		return null
+	}
+}
+
+export interface PlanResult {
+	ok: boolean
+	browserUrl?: string
+	revision?: number
+	isNew?: boolean
+	canvasFiles?: string[]
+	gate?: string
+	error?: string
+	errors?: Record<string, string>
+}
+
+export type PlanSource =
+	| { view: string; directory?: never }
+	| { directory: string; view?: never }
+
+export async function pushPlan(
+	sessionId: string,
+	body: PlanSource & { projectRoot: string; label?: string; gate?: string },
+): Promise<PlanResult & { reachable: boolean }> {
+	try {
+		const res = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(body),
+		})
+		const data = parsePlanResult(await res.json())
+		return { ...data, reachable: true }
+	} catch (e) {
+		return { ok: false, reachable: false, error: String(e) }
+	}
+}
+
+export async function peekFeedback(sessionId: string): Promise<string | null> {
+	try {
+		const metaRes = await fetch(`${BASE_URL}/api/session/${sessionId}/meta`, {
+			signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+		})
+		if (!metaRes.ok) return null
+		const meta: unknown = await metaRes.json()
+		if (!isRecord(meta) || !Array.isArray(meta['revisions'])) return null
+		const revisions = meta['revisions']
+		for (let i = revisions.length - 1; i >= 0; i--) {
+			const revision = revisions[i]
+			if (!isRecord(revision) || typeof revision['revision'] !== 'number') continue
+			if (revision['hasFeedback'] === true && revision['feedbackConsumed'] !== true) {
+				const fbRes = await fetch(`${BASE_URL}/api/session/${sessionId}/revision/${revision['revision']}/feedback`, {
+					signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+				})
+				if (!fbRes.ok) return null
+				const data: unknown = await fbRes.json()
+				return isRecord(data) && typeof data['feedback'] === 'string' ? data['feedback'] : ''
+			}
+		}
+		return null
+	} catch {
+		return null
+	}
+}
+
+export async function consumeFeedback(sessionId: string): Promise<string | null> {
+	try {
+		const res = await fetch(`${BASE_URL}/api/session/${sessionId}/feedback/consume`, {
+			method: 'POST',
+			signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+		})
+		const data: unknown = await res.json()
+		if (!isRecord(data) || data['found'] !== true) return null
+		return typeof data['feedback'] === 'string' ? data['feedback'] : ''
+	} catch {
+		return null
+	}
+}
+
+export interface BuildEvent {
+	issue?: string
+	status: string
+	message?: string
+	ts?: number
+}
+
+export async function postBuildEvent(event: BuildEvent): Promise<boolean> {
+	try {
+		const res = await fetch(`${BASE_URL}/api/build/event`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(event),
+			signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+		})
+		return res.ok
+	} catch {
+		return false
+	}
+}
+
+export function waitForFeedback(sessionId: string, timeoutMs: number = TIMEOUT_MS): Promise<string> {
+	return new Promise((resolveP, rejectP) => {
+		let settled = false
+		const ws = new WebSocket(`${WS_URL}/ws/wait/${sessionId}`)
+
+		const timer = setTimeout(() => {
+			if (settled) return
+			settled = true
+			try {
+				ws.close()
+			} catch {}
+			rejectP(new Error('timeout'))
+		}, timeoutMs)
+
+		ws.onmessage = (event: MessageEvent) => {
+			try {
+				const raw = typeof event.data === 'string' ? event.data : ''
+				const data: unknown = JSON.parse(raw)
+				if (isRecord(data) && data['type'] === 'submit') {
+					if (settled) return
+					settled = true
+					clearTimeout(timer)
+					try {
+						ws.close()
+					} catch {}
+					resolveP(typeof data['feedback'] === 'string' ? data['feedback'] : '')
+				}
+			} catch {
+			}
+		}
+
+		ws.onerror = () => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			rejectP(new Error('connection-failed'))
+		}
+
+		ws.onclose = () => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			rejectP(new Error('closed'))
+		}
+	})
+}

package/cli/src/daemon-lifecycle.ts

@@ -0,0 +1,171 @@
+import { spawn } from 'child_process'
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync } from 'fs'
+import { dirname, join, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { DATA_DIR, PID_FILE, SESSIONS_DIR, TEMP_DIR } from './config'
+import { health, type HealthInfo, healthMatchesDataRoot, isDaemonRunning } from './daemon-client'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+export function resolveDaemonServer(): string | null {
+	const candidates = [
+		resolve(HERE, '../../daemon/src/bin.ts'),
+	]
+	for (const c of candidates) {
+		if (existsSync(c)) return c
+	}
+	return null
+}
+
+export class DaemonUnavailableError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'DaemonUnavailableError'
+	}
+}
+
+export async function startDaemon(): Promise<void> {
+	const server = resolveDaemonServer()
+	if (!server) {
+		throw new DaemonUnavailableError(
+			'fabrika builder daemon not found. '
+				+ 'Build/start it manually, or run the CLI in offline mode.',
+		)
+	}
+
+	mkdirSync(TEMP_DIR, { recursive: true })
+	const startupLog = join(TEMP_DIR, 'daemon-startup.log')
+	const fd = openSync(startupLog, 'w')
+
+	const child = spawn('bun', ['run', server], {
+		detached: true,
+		stdio: ['ignore', 'ignore', fd],
+		cwd: dirname(dirname(server)),
+		env: daemonSpawnEnvironment(),
+	})
+	child.unref()
+	closeSync(fd)
+
+	for (let i = 0; i < 30; i++) {
+		await new Promise((r) => setTimeout(r, 100))
+		if (await isDaemonRunning()) return
+	}
+
+	let detail = ''
+	if (existsSync(startupLog)) {
+		const log = readFileSync(startupLog, 'utf-8').trim()
+		if (log) detail = '\nDaemon stderr:\n' + log
+	}
+	throw new DaemonUnavailableError('Daemon failed to start within 3 seconds.' + detail)
+}
+
+export function daemonSpawnEnvironment(
+	base: NodeJS.ProcessEnv = process.env,
+	dataDir: string = DATA_DIR,
+): NodeJS.ProcessEnv {
+	return { ...base, FABRIKA_DATA_DIR: resolve(dataDir) }
+}
+
+export async function ensureDaemon(opts: { quiet?: boolean } = {}): Promise<boolean> {
+	const active = await health()
+	if (active && healthMatchesDataRoot(active)) return true
+
+	if (active) {
+		const stopped = await stopMismatchedManagedDaemon(active, opts.quiet ?? false)
+		if (!stopped) return false
+	}
+
+	if (existsSync(PID_FILE)) {
+		const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10)
+		if (!isAlive(pid)) {
+			try {
+				unlinkSync(PID_FILE)
+			} catch {}
+		}
+	}
+
+	try {
+		await startDaemon()
+		return true
+	} catch (error: unknown) {
+		if (!opts.quiet) {
+			console.error(`[fabrika] ${error instanceof Error ? error.message : String(error)}`)
+		}
+		return false
+	}
+}
+
+async function stopMismatchedManagedDaemon(info: HealthInfo, quiet: boolean): Promise<boolean> {
+	const actual = info.sessionsDir ?? '<not reported by legacy daemon>'
+	const mismatch = `daemon data-root mismatch: active ${actual}, requested ${SESSIONS_DIR}`
+	if (!existsSync(PID_FILE)) {
+		if (!quiet) console.error(`[fabrika] ${mismatch}; no managed PID file, refusing to stop it.`)
+		return false
+	}
+
+	const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10)
+	if (!isAlive(pid) || info.pid === undefined || info.pid !== pid) {
+		if (!quiet) console.error(`[fabrika] ${mismatch}; daemon PID ownership could not be verified.`)
+		return false
+	}
+
+	if (!quiet) console.error(`[fabrika] ${mismatch}; restarting managed daemon ${pid}.`)
+	try {
+		process.kill(pid, 'SIGTERM')
+	} catch {
+		return false
+	}
+
+	for (let attempt = 0; attempt < 30; attempt++) {
+		await new Promise((resolveP) => setTimeout(resolveP, 100))
+		if ((await health()) === null) {
+			try {
+				unlinkSync(PID_FILE)
+			} catch {}
+			return true
+		}
+	}
+	if (!quiet) console.error(`[fabrika] mismatched daemon did not stop within 3 seconds.`)
+	return false
+}
+
+export function stopDaemon(): boolean {
+	if (!existsSync(PID_FILE)) return false
+	const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10)
+	try {
+		process.kill(pid, 'SIGTERM')
+		try {
+			unlinkSync(PID_FILE)
+		} catch {}
+		return true
+	} catch {
+		try {
+			unlinkSync(PID_FILE)
+		} catch {}
+		return false
+	}
+}
+
+function isAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch {
+		return false
+	}
+}
+
+export function openBrowser(url: string): void {
+	const candidates = process.platform === 'darwin'
+		? ['open']
+		: ['xdg-open', 'wslview', 'sensible-browser']
+	for (const cmd of candidates) {
+		const which = Bun.spawnSync(['which', cmd])
+		if (which.exitCode === 0) {
+			spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref()
+			return
+		}
+	}
+	console.error(`Open this URL in your browser: ${url}`)
+}

package/cli/src/derive.ts

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, statSync } from 'fs'
+import { basename, dirname, join, resolve } from 'path'
+import { type Phase, type PhaseId, PHASES } from './phases'
+
+export interface PhaseState {
+	current: PhaseId
+	index: number
+	completed: PhaseId[]
+	reads: string[]
+	produces: string[]
+	gate: boolean
+	satisfied: boolean
+}
+
+export type GateProbe = (phase: Phase) => boolean
+
+export const offlineGateProbe: GateProbe = () => true
+
+export function matchGlob(repoRoot: string, glob: string): string[] {
+	if (!glob.includes('*')) {
+		const abs = resolve(repoRoot, glob)
+		return existsSync(abs) ? [abs] : []
+	}
+
+	const dirPart = dirname(glob)
+	const filePart = basename(glob)
+	const absDir = resolve(repoRoot, dirPart)
+	if (!existsSync(absDir) || !statSync(absDir).isDirectory()) return []
+
+	const re = globSegmentToRegExp(filePart)
+	const out: string[] = []
+	for (const entry of readdirSync(absDir)) {
+		if (re.test(entry)) out.push(join(absDir, entry))
+	}
+	return out
+}
+
+function globSegmentToRegExp(seg: string): RegExp {
+	const escaped = seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
+	return new RegExp(`^${escaped}$`)
+}
+
+export function isNonEmptyFile(p: string): boolean {
+	try {
+		const st = statSync(p)
+		return st.isFile() && st.size > 0
+	} catch {
+		return false
+	}
+}
+
+export function producesSatisfied(repoRoot: string, phase: Phase): boolean {
+	for (const glob of phase.produces) {
+		if (isPlaceholder(glob)) return false
+		const matches = matchGlob(repoRoot, glob).filter(isNonEmptyFile)
+		if (matches.length === 0) return false
+	}
+	return true
+}
+
+export function resolveReads(repoRoot: string, phase: Phase): string[] {
+	const out: string[] = []
+	for (const glob of phase.reads) {
+		if (isPlaceholder(glob)) {
+			out.push(glob) // keep the human hint, e.g. "<init brief>"
+			continue
+		}
+		const matches = matchGlob(repoRoot, glob)
+		if (matches.length > 0) {
+			out.push(glob)
+		}
+	}
+	return out
+}
+
+function isPlaceholder(glob: string): boolean {
+	return glob.startsWith('<')
+}
+
+export function derivePhase(repoRoot: string, gateProbe: GateProbe = offlineGateProbe): PhaseState {
+	const completed: PhaseId[] = []
+
+	for (const phase of PHASES) {
+		const produced = producesSatisfied(repoRoot, phase)
+		const gateOk = !produced ? false : phase.gate ? gateProbe(phase) : true
+
+		if (produced && gateOk) {
+			completed.push(phase.id)
+			continue
+		}
+		return toState(repoRoot, phase, completed, produced)
+	}
+
+	const build = PHASES.at(-1)
+	if (build === undefined) throw new Error('The builder has no phases')
+	return toState(repoRoot, build, completed.filter((id) => id !== build.id), true)
+}
+
+function toState(repoRoot: string, phase: Phase, completed: PhaseId[], satisfied: boolean): PhaseState {
+	return {
+		current: phase.id,
+		index: PHASES.findIndex((p) => p.id === phase.id),
+		completed,
+		reads: resolveReads(repoRoot, phase),
+		produces: phase.produces,
+		gate: phase.gate,
+		satisfied,
+	}
+}

package/cli/src/index.ts

@@ -0,0 +1,38 @@
+export { resolveCatalogRoot, resolveStackPointer, type StackPointer } from './catalog'
+export {
+	BASE_URL,
+	DAEMON_PORT,
+	DATA_DIR,
+	FABRIKA_DIRNAME,
+	getSessionId,
+	hashRepoPath,
+	LEGACY_DATA_DIR,
+	NEUTRAL_DATA_DIR,
+	resolveDataDir,
+	TEMP_DIR,
+	WS_URL,
+} from './config'
+export { derivePhase, type GateProbe, isNonEmptyFile, matchGlob, offlineGateProbe, type PhaseState, producesSatisfied, resolveReads } from './derive'
+export {
+	type AgentHost,
+	injectAgentSupport,
+	type InjectOptions,
+	type InjectResult,
+	injectSkills,
+	parseAgentHosts,
+	resolveSkillSource,
+} from './inject-skills'
+export {
+	configPath,
+	EXTERNAL_DIRS,
+	type FabrikaConfig,
+	fabrikaDir,
+	findRepoRoot,
+	type InitResult,
+	isInitialized,
+	LAYER_DIRS,
+	readConfig,
+	scaffold,
+} from './layout'
+export { type PacketJson, packetJson, PHASE_IDS, type RenderOpts, renderPacket } from './packet'
+export { type Phase, PHASE_COUNT, phaseById, type PhaseId, phaseIndex, PHASES } from './phases'