@fabrika/builder 0.2.0

package/cli/src/commands/ensure-daemon.ts

@@ -0,0 +1,25 @@
+import { BASE_URL } from '../config'
+import { health } from '../daemon-client'
+import { ensureDaemon } from '../daemon-lifecycle'
+
+export async function cmdEnsureDaemon(_argv: string[]): Promise<number> {
+	const up = await ensureDaemon()
+	if (!up) {
+		console.log(JSON.stringify({ ok: false, running: false, baseUrl: BASE_URL }))
+		return 1
+	}
+	const info = await health()
+	console.log(
+		JSON.stringify({
+			ok: true,
+			running: true,
+			baseUrl: BASE_URL,
+			version: info?.version ?? null,
+			pid: info?.pid ?? null,
+			dataDir: info?.dataDir ?? null,
+			sessionsDir: info?.sessionsDir ?? null,
+			sessions: info?.sessions ?? null,
+		}),
+	)
+	return 0
+}

package/cli/src/commands/gate.ts

@@ -0,0 +1,165 @@
+import { existsSync, statSync } from 'fs'
+import { extname, resolve } from 'path'
+import { parseArgs } from 'util'
+import { BASE_URL, TIMEOUT_MS } from '../config'
+import { resolveContext } from '../context'
+import { isDaemonRunning, peekFeedback, pushPlan, waitForFeedback } from '../daemon-client'
+import { ensureDaemon, openBrowser } from '../daemon-lifecycle'
+
+export async function cmdGate(argv: string[]): Promise<number> {
+	const sub = argv[0]
+	const rest = argv.slice(1)
+	if (sub === 'open') return gateOpen(rest)
+	if (sub === 'wait') return gateWait(rest)
+	console.error(`[fabrika] unknown gate subcommand: ${sub ?? '(none)'}. Use \`gate open\` or \`gate wait\`.`)
+	return 1
+}
+
+async function gateOpen(argv: string[]): Promise<number> {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			view: { type: 'string' },
+			dir: { type: 'string' },
+			label: { type: 'string' },
+			session: { type: 'string' },
+			root: { type: 'string' },
+		},
+		allowPositionals: true,
+	})
+
+	const name = positionals[0]
+	if (!name) {
+		console.error('[fabrika] gate open requires a <name>. Usage: fabrika builder gate open <name> --view <file.jsx>')
+		return 1
+	}
+	if (!values.view && !values.dir) {
+		console.error('[fabrika] gate open requires exactly one of --view <file.jsx> or --dir <jsxDir>.')
+		return 1
+	}
+	if (values.view && values.dir) {
+		console.error('[fabrika] gate open accepts either --view or --dir, not both.')
+		return 1
+	}
+
+	const ctx = resolveContext({ dir: values.root, session: values.session })
+
+	let source: { view: string } | { directory: string }
+	if (values.dir) {
+		const directory = resolve(values.dir)
+		if (!existsSync(directory) || !statSync(directory).isDirectory()) {
+			console.error(`[fabrika] --dir not a directory: ${directory}`)
+			return 1
+		}
+		source = { directory }
+	} else {
+		const viewPath = resolve(values.view!)
+		if (!existsSync(viewPath)) {
+			console.error(`[fabrika] --view file not found: ${viewPath}`)
+			return 1
+		}
+		if (!statSync(viewPath).isFile()) {
+			console.error(`[fabrika] --view must be a file; use --dir for a directory: ${viewPath}`)
+			return 1
+		}
+		if (extname(viewPath).toLowerCase() !== '.jsx') {
+			console.error(`[fabrika] --view must point to a .jsx file: ${viewPath}`)
+			return 1
+		}
+		source = { view: viewPath }
+	}
+
+	const label = values.label ?? name
+	const browserUrl = `${BASE_URL}/s/${ctx.sessionId}`
+
+	const up = await ensureDaemon({ quiet: true })
+	if (!up) {
+		console.error(`[fabrika] daemon unavailable; cannot push gate "${name}".`)
+		console.log(
+			JSON.stringify({
+				ok: false,
+				reachable: false,
+				gate: name,
+				...source,
+				browserUrl,
+				hint: 'Start the daemon (fabrika builder ensure-daemon), then re-run gate open.',
+			}),
+		)
+		return 0 // soft-fail so the loop can proceed offline / be tested
+	}
+
+	const result = await pushPlan(ctx.sessionId, {
+		...source,
+		projectRoot: ctx.repoRoot,
+		label,
+		gate: name,
+	})
+
+	if (!result.reachable || !result.ok) {
+		console.error(`[fabrika] gate push failed: ${result.error ?? 'compile error'}`)
+		if (result.errors) {
+			for (const [file, err] of Object.entries(result.errors)) {
+				console.error(`  ${file}: ${err}`)
+			}
+		}
+		return 1
+	}
+
+	if (result.isNew && result.browserUrl) {
+		openBrowser(result.browserUrl)
+	}
+
+	console.log(
+		JSON.stringify({
+			ok: true,
+			browserUrl: result.browserUrl ?? browserUrl,
+			revision: result.revision,
+			gate: name,
+			sessionId: ctx.sessionId,
+			canvasFiles: result.canvasFiles,
+		}),
+	)
+	return 0
+}
+
+async function gateWait(argv: string[]): Promise<number> {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			gate: { type: 'string' },
+			timeout: { type: 'string' },
+			session: { type: 'string' },
+			root: { type: 'string' },
+		},
+		allowPositionals: true,
+	})
+
+	const ctx = resolveContext({ dir: values.root, session: values.session })
+	const timeoutMs = values.timeout ? parseInt(values.timeout, 10) : TIMEOUT_MS
+
+	const up = await ensureDaemon({ quiet: true })
+	if (!up) {
+		console.error('[fabrika] daemon unavailable; cannot wait for gate feedback.')
+		return 1
+	}
+
+	const pending = await peekFeedback(ctx.sessionId)
+	if (pending !== null) {
+		process.stdout.write(pending)
+		return 0
+	}
+
+	try {
+		const feedback = await waitForFeedback(ctx.sessionId, timeoutMs)
+		process.stdout.write(feedback)
+		return 0
+	} catch (error: unknown) {
+		const reason = error instanceof Error ? error.message : String(error)
+		if (reason === 'timeout') {
+			console.error('[fabrika] timeout waiting for gate feedback.')
+		} else {
+			console.error(`[fabrika] gate wait failed: ${reason}`)
+		}
+		return 1
+	}
+}

package/cli/src/commands/induce.ts

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { parseArgs } from 'util'
+import { resolveStackPointer } from '../catalog'
+import { resolveContext } from '../context'
+import { induceIssues, renderIssue } from '../induce'
+import { readSkeletons } from '../skeletons'
+
+export async function cmdInduce(argv: string[]): Promise<number> {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			dir: { type: 'string' },
+			session: { type: 'string' },
+			force: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	})
+
+	const ctx = resolveContext({ dir: values.dir, session: values.session })
+	if (!ctx.initialized) {
+		console.error(`[fabrika] no .fabrika/ found at or above ${ctx.repoRoot}. Run \`fabrika builder init\` first.`)
+		return 1
+	}
+
+	const testsBrowserDir = join(ctx.repoRoot, 'tests', 'browser')
+	const skeletons = readSkeletons(testsBrowserDir)
+	if (skeletons.length === 0) {
+		console.error(
+			`[fabrika] no opice skeletons in ${testsBrowserDir}. `
+				+ `Author them in phase 6 (skeletons) first.`,
+		)
+		return 1
+	}
+
+	const issues = induceIssues(skeletons, { stack: resolveStackPointer(ctx.profile) ?? undefined })
+	const issuesDir = join(ctx.fabrikaDir, 'issues')
+	mkdirSync(issuesDir, { recursive: true })
+
+	let written = 0
+	let skipped = 0
+	for (const issue of issues) {
+		const path = join(issuesDir, `${issue.id}.md`)
+		if (existsSync(path) && !values.force) {
+			skipped++
+			continue
+		}
+		writeFileSync(path, renderIssue(issue))
+		written++
+	}
+
+	const foundation = issues.filter((i) => i.kind === 'foundation').length
+	const feature = issues.filter((i) => i.kind === 'feature').length
+	console.log(
+		`[fabrika] induced ${issues.length} issue(s) from ${skeletons.length} skeleton(s): `
+			+ `${foundation} foundation + ${feature} feature.`,
+	)
+	console.log(`[fabrika] wrote ${written}, skipped ${skipped} existing (use --force to overwrite).`)
+	console.log(`[fabrika] → .fabrika/issues/  · next: fabrika builder advance && fabrika builder next  (build)`)
+	return 0
+}

package/cli/src/commands/init.ts

@@ -0,0 +1,91 @@
+import { rmSync } from 'fs'
+import { join } from 'path'
+import { parseArgs } from 'util'
+import { BASE_URL, SESSIONS_DIR } from '../config'
+import { ensureDaemon, openBrowser } from '../daemon-lifecycle'
+import { type AgentHost, injectAgentSupport, parseAgentHosts } from '../inject-skills'
+import { scaffold } from '../layout'
+
+async function resetStaleSession(sessionId: string): Promise<void> {
+	try {
+		await fetch(`${BASE_URL}/api/session/${encodeURIComponent(sessionId)}/reset`, { method: 'POST' })
+	} catch {
+	}
+	try {
+		rmSync(join(SESSIONS_DIR, sessionId), { recursive: true, force: true })
+	} catch {
+	}
+}
+
+export async function cmdInit(argv: string[]): Promise<number> {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: {
+			profile: { type: 'string', default: 'cf-lightweight' },
+			session: { type: 'string' },
+			agent: { type: 'string', default: 'all' },
+			'no-daemon': { type: 'boolean', default: false },
+			'no-open': { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	})
+
+	let hosts: AgentHost[]
+	try {
+		hosts = parseAgentHosts(values.agent)
+	} catch (error: unknown) {
+		console.error(`[fabrika] ${error instanceof Error ? error.message : String(error)}`)
+		return 1
+	}
+	const dir = positionals[0] ?? process.cwd()
+	const result = scaffold(dir, { profile: values.profile, sessionId: values.session })
+	const support = injectAgentSupport(result.repoRoot, { hosts })
+
+	if (result.alreadyInitialized) {
+		console.error(`[fabrika] .fabrika/ already initialized at ${result.fabrikaDir} (idempotent re-run)`)
+	} else {
+		console.error(`[fabrika] scaffolded .fabrika/ at ${result.fabrikaDir}`)
+	}
+	if (result.createdDirs.length) {
+		console.error(`[fabrika] created ${result.createdDirs.length} dir(s)`)
+	}
+	if (support.sourceDir) {
+		console.error(
+			`[fabrika] agent support (${support.hosts.join('+')}): `
+				+ `${support.written.length} installed, ${support.updated.length} updated, `
+				+ `${support.skipped.length} current, ${support.preserved.length} user-edited preserved`,
+		)
+	} else {
+		console.error(`[fabrika] agent support: source dir not found, skipped installation`)
+	}
+
+	const browserUrl = `${BASE_URL}/s/${result.config.sessionId}`
+	if (!values['no-daemon']) {
+		const up = await ensureDaemon({ quiet: true })
+		if (!result.alreadyInitialized) {
+			await resetStaleSession(result.config.sessionId)
+			console.error(`[fabrika] cleared any stale session for ${result.config.sessionId}`)
+		}
+		if (up && !values['no-open']) {
+			openBrowser(browserUrl)
+		} else if (!up) {
+			console.error(`[fabrika] daemon not started (offline). Dashboard: ${browserUrl}`)
+		}
+	} else if (!result.alreadyInitialized) {
+		await resetStaleSession(result.config.sessionId)
+	}
+
+	console.log(
+		JSON.stringify({
+			ok: true,
+			repoRoot: result.repoRoot,
+			fabrikaDir: result.fabrikaDir,
+			sessionId: result.config.sessionId,
+			profile: result.config.profile,
+			agents: support.hosts,
+			browserUrl,
+			createdConfig: result.createdConfig,
+		}),
+	)
+	return 0
+}

package/cli/src/commands/next.ts

@@ -0,0 +1,31 @@
+import { parseArgs } from 'util'
+import { resolveContext } from '../context'
+import { packetJson, renderPacket } from '../packet'
+import { resolvePhaseState } from '../phase-state'
+
+export async function cmdNext(argv: string[]): Promise<number> {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			json: { type: 'boolean', default: false },
+			dir: { type: 'string' },
+			session: { type: 'string' },
+		},
+		allowPositionals: true,
+	})
+
+	const ctx = resolveContext({ dir: values.dir, session: values.session })
+	if (!ctx.initialized) {
+		console.error(`[fabrika] no .fabrika/ found at or above ${ctx.repoRoot}. Run \`fabrika builder init\` first.`)
+		return 1
+	}
+
+	const { state, source } = await resolvePhaseState(ctx.repoRoot, ctx.fabrikaDir, ctx.sessionId)
+
+	if (values.json) {
+		console.log(JSON.stringify({ ...packetJson(state, { profile: ctx.profile }), source }))
+	} else {
+		process.stdout.write(renderPacket(state, { profile: ctx.profile }))
+	}
+	return 0
+}

package/cli/src/config.ts

@@ -0,0 +1,47 @@
+import { createHash } from 'crypto'
+import { existsSync } from 'fs'
+import { homedir, tmpdir } from 'os'
+import { join, resolve } from 'path'
+
+export const DAEMON_PORT = parseInt(process.env['FABRIKA_PORT'] || '19410', 10)
+export const BASE_URL = `http://localhost:${DAEMON_PORT}`
+export const WS_URL = `ws://localhost:${DAEMON_PORT}`
+
+export const TIMEOUT_MS = parseInt(process.env['FABRIKA_TIMEOUT'] || String(60 * 60 * 1000), 10)
+
+export const LEGACY_DATA_DIR = join(homedir(), '.claude', 'fabrika')
+export const NEUTRAL_DATA_DIR = join(homedir(), '.fabrika')
+export const DATA_DIR = resolveDataDir()
+export const SESSIONS_DIR = join(DATA_DIR, 'sessions')
+export const TEMP_DIR = join(tmpdir(), 'fabrika')
+export const PID_FILE = join(TEMP_DIR, 'daemon.pid')
+
+export const FABRIKA_DIRNAME = '.fabrika'
+
+export function resolveDataDir(opts: {
+	home?: string
+	explicit?: string
+	exists?: (path: string) => boolean
+} = {}): string {
+	const home = opts.home ?? homedir()
+	const explicit = opts.explicit ?? process.env['FABRIKA_DATA_DIR']
+	if (explicit) return resolve(explicit)
+	const neutral = join(home, '.fabrika')
+	const legacy = join(home, '.claude', 'fabrika')
+	const exists = opts.exists ?? existsSync
+	if (exists(neutral)) return neutral
+	if (exists(legacy)) return legacy
+	return neutral
+}
+
+export function getSessionId(explicit?: string, recorded?: string, repoRoot?: string): string {
+	if (explicit) return explicit
+	if (process.env['FABRIKA_SESSION_ID']) return process.env['FABRIKA_SESSION_ID']
+	if (recorded) return recorded
+	return hashRepoPath(repoRoot ?? process.cwd())
+}
+
+export function hashRepoPath(repoRoot: string): string {
+	const abs = resolve(repoRoot)
+	return 's_' + createHash('sha256').update(abs).digest('hex').slice(0, 16)
+}

package/cli/src/context.ts

@@ -0,0 +1,28 @@
+import { resolve } from 'path'
+import { getSessionId } from './config'
+import { fabrikaDir, findRepoRoot, readConfig } from './layout'
+
+export interface CommandContext {
+	repoRoot: string
+	fabrikaDir: string
+	sessionId: string
+	profile: string
+	initialized: boolean
+}
+
+export function resolveContext(opts: { dir?: string; session?: string } = {}): CommandContext {
+	const repoRoot = opts.dir
+		? resolve(opts.dir)
+		: findRepoRoot(process.cwd()) ?? process.cwd()
+
+	const config = readConfig(repoRoot)
+	const sessionId = getSessionId(opts.session, config?.sessionId, repoRoot)
+
+	return {
+		repoRoot,
+		fabrikaDir: fabrikaDir(repoRoot),
+		sessionId,
+		profile: config?.profile ?? 'cf-lightweight',
+		initialized: config !== null,
+	}
+}