@fabrika/builder 0.2.0

package/cli/src/induce.ts

@@ -0,0 +1,151 @@
+import type { StackPointer } from './catalog'
+import type { Skeleton } from './skeletons'
+
+export interface InducedIssue {
+	id: string
+	goal: string
+	satisfies: string[]
+	dependsOn: string[]
+	touches: string[]
+	body: string
+	kind: 'foundation' | 'feature'
+}
+
+const FOUNDATION_SCAFFOLD = 'ISSUE-001'
+const FOUNDATION_DATA = 'ISSUE-002'
+const FOUNDATION_AUTH = 'ISSUE-003'
+
+export interface InduceOpts {
+	stack?: StackPointer
+}
+
+export function induceIssues(skeletons: Skeleton[], opts: InduceOpts = {}): InducedIssue[] {
+	if (skeletons.length === 0) return []
+	const issues: InducedIssue[] = []
+
+	const allSeeds = uniq(skeletons.flatMap((s) => s.seeds))
+	const allRoles = uniq(skeletons.flatMap((s) => s.roles))
+	const allUrls = uniq(skeletons.map((s) => s.url).filter((u): u is string => !!u))
+
+	const stackRef = opts.stack && opts.stack.stackFileExists
+		? [
+			`Stack preset: ${opts.stack.stackFile}`,
+			`Decisions:    ${opts.stack.decisionsDir}/  (resolve the preset's \`decisions:\` ids; read their live \`sources\`)`,
+			'',
+		]
+		: []
+
+	issues.push({
+		id: FOUNDATION_SCAFFOLD,
+		kind: 'foundation',
+		goal: 'Stand up the running app + the routes every scenario navigates to.',
+		satisfies: [],
+		dependsOn: [],
+		touches: ['app scaffold', 'routing', ...allUrls.map((u) => `route: ${u}`)],
+		body: [
+			...stackRef,
+			'Foundation. Scaffold the running app per the active stack preset — read its',
+			'decisions + the live sources they point to, and scaffold from current APIs (do',
+			'NOT copy templates). Register a route for every URL a scenario targets so the',
+			'dev server serves them.',
+			'',
+			'Routes that must exist (from skeleton `url` metadata). The URL is the contract;',
+			'the file location is your call per the stack conventions:',
+			...(allUrls.length ? allUrls.map((u) => `- \`${u}\``) : ['- (none declared)']),
+		].join('\n'),
+	})
+
+	if (allSeeds.length) {
+		issues.push({
+			id: FOUNDATION_DATA,
+			kind: 'foundation',
+			goal: 'Data layer: schema migrations + the named idempotent seeds scenarios rely on.',
+			satisfies: [],
+			dependsOn: [FOUNDATION_SCAFFOLD],
+			touches: ['schema/migrations', ...allSeeds.map((s) => `seed: ${s}`)],
+			body: [
+				'Foundation. Define the schema (idempotent migrations) and one named',
+				'idempotent seed per `seeds:` value, keyed on stable ids.',
+				'',
+				'Named seeds to provide (union of skeleton `seeds`):',
+				...allSeeds.map((s) => `- \`${s}\``),
+			].join('\n'),
+		})
+	}
+
+	if (allRoles.length) {
+		issues.push({
+			id: FOUNDATION_AUTH,
+			kind: 'foundation',
+			goal: 'Auth: the roles scenarios act as, and the means to act as each.',
+			satisfies: [],
+			dependsOn: [FOUNDATION_SCAFFOLD],
+			touches: ['auth', 'identities'],
+			body: [
+				'Foundation. Provide auth for every acting identity in the skeletons.',
+				'',
+				'Roles to support (union of skeleton `roles`):',
+				...allRoles.map((r) => `- \`${r}\``),
+			].join('\n'),
+		})
+	}
+
+	let n = 101
+	for (const s of skeletons) {
+		const deps = [FOUNDATION_SCAFFOLD]
+		if (s.seeds.length && allSeeds.length) deps.push(FOUNDATION_DATA)
+		if (s.roles.length && allRoles.length) deps.push(FOUNDATION_AUTH)
+
+		const satisfies = [s.feature ?? s.name, ...s.invariants]
+
+		issues.push({
+			id: `ISSUE-${n}`,
+			kind: 'feature',
+			goal: `Implement the vertical slice for "${s.name}"${s.url ? ` at ${s.url}` : ''}.`,
+			satisfies: uniq(satisfies),
+			dependsOn: deps,
+			touches: uniq([s.url ? `route: ${s.url}` : 'feature route/UI', ...s.seeds.map((sd) => `seed: ${sd}`)]),
+			body: [
+				`Feature slice satisfying the scenario **${s.name}**` + (s.feature ? ` (\`${s.feature}\`)` : '') + '.',
+				'',
+				`- Route + data: serve URL \`${
+					s.url ?? '(unspecified)'
+				}\` — the URL is a contract (must match the skeleton); choose the file per the stack conventions.`,
+				s.seeds.length ? `- Seeds: ${s.seeds.map((x) => `\`${x}\``).join(', ')}.` : '- Seeds: none.',
+				s.roles.length ? `- Roles: ${s.roles.map((x) => `\`${x}\``).join(', ')}.` : '- Roles: none.',
+				'- Semantic, accessible markup so opice-author finds stable selectors.',
+				s.invariants.length ? '\nInvariants to satisfy (frozen — do not weaken):' : '',
+				...s.invariants.map((iv) => `- ${iv}`),
+				`\nAcceptance: \`${relTest(s.file)}\` goes green (\`bun test\`).`,
+			].filter((x) => x !== '').join('\n'),
+		})
+		n++
+	}
+
+	return issues
+}
+
+export function renderIssue(issue: InducedIssue): string {
+	const fm = [
+		'---',
+		`goal: ${issue.goal}`,
+		`satisfies: [${issue.satisfies.map(q).join(', ')}]`,
+		`depends_on: [${issue.dependsOn.map(q).join(', ')}]`,
+		`touches: [${issue.touches.map(q).join(', ')}]`,
+		'---',
+	].join('\n')
+	return `${fm}\n\n# ${issue.id} — ${issue.goal}\n\n${issue.body}\n`
+}
+
+function relTest(file: string): string {
+	const i = file.indexOf('tests/browser/')
+	return i !== -1 ? file.slice(i) : file
+}
+
+function uniq<T>(xs: T[]): T[] {
+	return [...new Set(xs)]
+}
+
+function q(s: string): string {
+	return `"${s.replace(/"/g, '\\"')}"`
+}

package/cli/src/inject-skills.ts

@@ -0,0 +1,313 @@
+import { createHash } from 'crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { dirname, join, relative, resolve } from 'path'
+import { fileURLToPath } from 'url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const MANIFEST_VERSION = 1
+const MANIFEST_RELATIVE_PATH = join('.fabrika', 'agent-support.json')
+
+export type AgentHost = 'claude' | 'codex'
+
+export interface InjectOptions {
+	hosts?: AgentHost[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isAgentHost(value: string): value is AgentHost {
+	return value === 'claude' || value === 'codex'
+}
+
+export interface InjectResult {
+	sourceDir: string | null
+	hosts: AgentHost[]
+	written: string[]
+	updated: string[]
+	skipped: string[]
+	preserved: string[]
+}
+
+interface ManagedManifest {
+	version: number
+	files: Record<string, { installedHash: string; host: AgentHost }>
+}
+
+interface DesiredFile {
+	relativePath: string
+	content: string
+	host: AgentHost
+}
+
+interface AgentSource {
+	filename: string
+	name: string
+	description: string
+	body: string
+	raw: string
+}
+
+const LEGACY_MANAGED_HASHES: Record<string, Set<string>> = {
+	[join('.claude', 'skills', 'fabrika', 'SKILL.md')]: new Set([
+		'd06c8508d47ab36222bcb33b964fd928e3fbcff383db8c257ef68dfd956dd428',
+	]),
+	[join('.claude', 'agents', 'build-orchestrator.md')]: new Set([
+		'31c436e08ffac217d32c71ec56d1612f565b0b2828df9c067ff1e812768339f1',
+	]),
+	[join('.claude', 'agents', 'flows-author.md')]: new Set([
+		'1e55cce06f0210b65ce6ec2d9cd1d4bb5e0e8bcff11e06eb4f2ee405914dd322',
+	]),
+	[join('.claude', 'agents', 'opice-skeleton-author.md')]: new Set([
+		'8644461c1acdc236a886b648ae97984cbd54bc0d59872f7b310ce2b5783e4378',
+	]),
+}
+
+export function resolveSkillSource(): string | null {
+	const candidates = [resolve(HERE, '../../skill')]
+	for (const candidate of candidates) {
+		if (existsSync(join(candidate, 'SKILL.md'))) return candidate
+	}
+	return null
+}
+
+export function parseAgentHosts(value?: string): AgentHost[] {
+	if (!value || value === 'all') return ['claude', 'codex']
+	const requested = [...new Set(value.split(',').map((item) => item.trim()).filter(Boolean))]
+	if (!requested.every(isAgentHost) || requested.length === 0) {
+		throw new Error(`Invalid --agent value: ${value}. Use claude, codex, or all.`)
+	}
+	return requested
+}
+
+export function injectAgentSupport(repoRoot: string, opts: InjectOptions = {}): InjectResult {
+	const sourceDir = resolveSkillSource()
+	const hosts = normalizeHosts(opts.hosts)
+	const result: InjectResult = {
+		sourceDir,
+		hosts,
+		written: [],
+		updated: [],
+		skipped: [],
+		preserved: [],
+	}
+	if (!sourceDir) return result
+
+	const root = resolve(repoRoot)
+	const desired = renderDesiredFiles(sourceDir, hosts)
+	const manifestPath = join(root, MANIFEST_RELATIVE_PATH)
+	const manifest = readManifest(manifestPath)
+
+	for (const file of desired) {
+		installManagedFile(root, file, manifest, result)
+	}
+	writeManifest(manifestPath, manifest)
+	return result
+}
+
+export function injectSkills(repoRoot: string): InjectResult {
+	return injectAgentSupport(repoRoot, { hosts: ['claude'] })
+}
+
+function normalizeHosts(hosts?: AgentHost[]): AgentHost[] {
+	const selected: AgentHost[] = hosts?.length ? hosts : ['claude', 'codex']
+	return [...new Set(selected)].sort()
+}
+
+function renderDesiredFiles(sourceDir: string, hosts: AgentHost[]): DesiredFile[] {
+	const skill = readFileSync(join(sourceDir, 'SKILL.md'), 'utf-8')
+	const agents = readAgentSources(join(sourceDir, 'agents'))
+	const resources = readSkillResources(sourceDir)
+	const files: DesiredFile[] = []
+
+	for (const host of hosts) {
+		const skillRoot = host === 'claude'
+			? join('.claude', 'skills', 'fabrika')
+			: join('.agents', 'skills', 'fabrika')
+		files.push({
+			relativePath: join(skillRoot, 'SKILL.md'),
+			content: host === 'claude' ? renderClaudeSkill(skill) : skill,
+			host,
+		})
+		for (const resource of resources) {
+			if (host === 'claude' && resource.relativePath === join('agents', 'openai.yaml')) continue
+			files.push({
+				relativePath: join(skillRoot, resource.relativePath),
+				content: resource.content,
+				host,
+			})
+		}
+	}
+
+	if (hosts.includes('claude')) {
+		for (const agent of agents) {
+			files.push({
+				relativePath: join('.claude', 'agents', agent.filename),
+				content: agent.raw,
+				host: 'claude',
+			})
+		}
+	}
+	if (hosts.includes('codex')) {
+		for (const agent of agents) {
+			files.push({
+				relativePath: join('.codex', 'agents', agent.filename.replace(/\.md$/, '.toml')),
+				content: renderCodexAgent(agent),
+				host: 'codex',
+			})
+		}
+	}
+
+	return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
+}
+
+function readSkillResources(sourceDir: string): Array<{ relativePath: string; content: string }> {
+	const resources: Array<{ relativePath: string; content: string }> = []
+	for (const directory of ['agents', 'gates']) {
+		const absoluteDir = join(sourceDir, directory)
+		if (!existsSync(absoluteDir)) continue
+		for (const entry of readdirSync(absoluteDir, { withFileTypes: true })) {
+			if (!entry.isFile()) continue
+			if (directory === 'gates' && !entry.name.endsWith('.jsx')) continue
+			if (directory === 'agents' && !entry.name.endsWith('.md') && entry.name !== 'openai.yaml') continue
+			resources.push({
+				relativePath: join(directory, entry.name),
+				content: readFileSync(join(absoluteDir, entry.name), 'utf-8'),
+			})
+		}
+	}
+	return resources
+}
+
+function readAgentSources(agentsDir: string): AgentSource[] {
+	if (!existsSync(agentsDir)) return []
+	return readdirSync(agentsDir)
+		.filter((entry) => entry.endsWith('.md'))
+		.sort()
+		.map((filename) => parseAgentSource(filename, readFileSync(join(agentsDir, filename), 'utf-8')))
+}
+
+function parseAgentSource(filename: string, raw: string): AgentSource {
+	const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+	if (!match) throw new Error(`Agent source ${filename} has no valid frontmatter.`)
+	const metadata = match[1]!
+	const name = metadata.match(/^name:\s*(.+)$/m)?.[1]?.trim()
+	const metadataLines = metadata.split('\n')
+	const descriptionIndex = metadataLines.findIndex((line) => line.startsWith('description:'))
+	let description: string | undefined
+	if (descriptionIndex >= 0) {
+		const inline = metadataLines[descriptionIndex]!.slice('description:'.length).trim()
+		if (inline === '>' || inline === '|') {
+			const descriptionLines: string[] = []
+			for (let index = descriptionIndex + 1; index < metadataLines.length; index++) {
+				const line = metadataLines[index]!
+				if (line.length > 0 && !/^\s/.test(line)) break
+				descriptionLines.push(line.trim())
+			}
+			description = descriptionLines.filter(Boolean).join(' ')
+		} else {
+			description = inline
+		}
+	}
+	if (!name || !description) throw new Error(`Agent source ${filename} is missing name or description.`)
+	return { filename, name, description, body: match[2]!.trim() + '\n', raw }
+}
+
+function renderClaudeSkill(canonical: string): string {
+	return canonical.replace(
+		/\n---\n/,
+		'\nallowed-tools: Bash(bunx fabrika:*), Bash(bun:*), Read, Write, Edit, Glob, Grep, Skill, Agent\n---\n',
+	)
+}
+
+function renderCodexAgent(agent: AgentSource): string {
+	return [
+		`name = ${tomlString(agent.name)}`,
+		`description = ${tomlString(agent.description)}`,
+		`developer_instructions = ${tomlMultiline(agent.body)}`,
+		'',
+	].join('\n')
+}
+
+function tomlString(value: string): string {
+	return JSON.stringify(value)
+}
+
+function tomlMultiline(value: string): string {
+	const escaped = value.replace(/\\/g, '\\\\').replace(/\"\"\"/g, '\\"\\"\\"')
+	return `\"\"\"\n${escaped}\"\"\"`
+}
+
+function installManagedFile(
+	root: string,
+	desired: DesiredFile,
+	manifest: ManagedManifest,
+	result: InjectResult,
+): void {
+	const destination = join(root, desired.relativePath)
+	const desiredHash = hash(desired.content)
+	const existing = existsSync(destination) ? readFileSync(destination, 'utf-8') : null
+	const existingHash = existing === null ? null : hash(existing)
+	const recorded = manifest.files[desired.relativePath]
+
+	if (existing === null) {
+		writeAtomic(destination, desired.content)
+		result.written.push(destination)
+	} else if (existingHash === desiredHash) {
+		result.skipped.push(destination)
+	} else if (
+		existingHash === recorded?.installedHash
+		|| LEGACY_MANAGED_HASHES[desired.relativePath]?.has(existingHash ?? '')
+	) {
+		writeAtomic(destination, desired.content)
+		result.updated.push(destination)
+	} else {
+		result.preserved.push(destination)
+		return
+	}
+
+	manifest.files[desired.relativePath] = { installedHash: desiredHash, host: desired.host }
+}
+
+function readManifest(path: string): ManagedManifest {
+	if (!existsSync(path)) return { version: MANIFEST_VERSION, files: {} }
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'))
+		if (!isRecord(parsed) || !isRecord(parsed['files'])) return { version: MANIFEST_VERSION, files: {} }
+		const files: ManagedManifest['files'] = {}
+		for (const [relativePath, candidate] of Object.entries(parsed['files'])) {
+			if (!isRecord(candidate)) continue
+			const installedHash = candidate['installedHash']
+			const host = candidate['host']
+			if (typeof installedHash === 'string' && typeof host === 'string' && isAgentHost(host)) {
+				files[relativePath] = { installedHash, host }
+			}
+		}
+		return {
+			version: MANIFEST_VERSION,
+			files,
+		}
+	} catch {
+		return { version: MANIFEST_VERSION, files: {} }
+	}
+}
+
+function writeManifest(path: string, manifest: ManagedManifest): void {
+	writeAtomic(path, JSON.stringify(manifest, null, 2) + '\n')
+}
+
+function writeAtomic(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true })
+	const temp = `${path}.${process.pid}.tmp`
+	writeFileSync(temp, content)
+	renameSync(temp, path)
+}
+
+function hash(content: string): string {
+	return createHash('sha256').update(content).digest('hex')
+}
+
+export function manifestRelativePath(repoRoot: string): string {
+	return relative(resolve(repoRoot), join(resolve(repoRoot), MANIFEST_RELATIVE_PATH))
+}

package/cli/src/issues.ts

@@ -0,0 +1,75 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { basename, join } from 'path'
+
+export interface Issue {
+	id: string
+	path: string
+	goal: string
+	satisfies: string[]
+	dependsOn: string[]
+	touches: string[]
+	body: string
+}
+
+export function readIssues(fabrikaDir: string): Issue[] {
+	const dir = join(fabrikaDir, 'issues')
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+	const out: Issue[] = []
+	for (const entry of readdirSync(dir)) {
+		if (!/^ISSUE-.*\.md$/i.test(entry)) continue
+		const p = join(dir, entry)
+		if (!statSync(p).isFile() || statSync(p).size === 0) continue
+		out.push(parseIssue(p))
+	}
+	out.sort((a, b) => a.id.localeCompare(b.id))
+	return out
+}
+
+export function parseIssue(path: string): Issue {
+	const raw = readFileSync(path, 'utf-8')
+	const fm = extractFrontMatter(raw)
+	return {
+		id: basename(path).replace(/\.md$/i, ''),
+		path,
+		goal: scalar(fm.body['goal']) ?? '',
+		satisfies: list(fm.body['satisfies']),
+		dependsOn: list(fm.body['depends_on']),
+		touches: list(fm.body['touches']),
+		body: fm.rest,
+	}
+}
+
+export function isReady(issue: Issue, knownIds: Set<string>): boolean {
+	return issue.dependsOn.every((dep) => knownIds.has(dep))
+}
+
+interface FrontMatter {
+	body: Record<string, string>
+	rest: string
+}
+
+function extractFrontMatter(raw: string): FrontMatter {
+	const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+	if (!m) return { body: {}, rest: raw }
+	const body: Record<string, string> = {}
+	for (const line of (m[1] ?? '').split(/\r?\n/)) {
+		const kv = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*)$/)
+		if (kv && kv[1]) body[kv[1]] = (kv[2] ?? '').trim()
+	}
+	return { body, rest: (m[2] ?? '').trim() }
+}
+
+function scalar(v: string | undefined): string | undefined {
+	if (v === undefined) return undefined
+	return v.replace(/^["']|["']$/g, '')
+}
+
+function list(v: string | undefined): string[] {
+	if (!v) return []
+	const inner = v.replace(/^\[/, '').replace(/\]$/, '')
+	if (inner.trim() === '') return []
+	return inner
+		.split(',')
+		.map((s) => s.trim().replace(/^["']|["']$/g, ''))
+		.filter((s) => s.length > 0)
+}

package/cli/src/layout.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs'
+import { join, resolve } from 'path'
+import { FABRIKA_DIRNAME, hashRepoPath } from './config'
+
+export const LAYER_DIRS = [
+	'intent',
+	'principles',
+	'architecture',
+	'architecture/flows',
+	'architecture/spec',
+	'pages',
+	'issues',
+]
+
+export const EXTERNAL_DIRS = ['tests/browser']
+
+export interface FabrikaConfig {
+	profile: string
+	sessionId: string
+	createdAt: string
+}
+
+function parseConfig(value: unknown): FabrikaConfig | null {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+	if (!('profile' in value) || !('sessionId' in value) || !('createdAt' in value)) return null
+	const { profile, sessionId, createdAt } = value
+	if (typeof profile !== 'string' || typeof sessionId !== 'string' || typeof createdAt !== 'string') return null
+	return { profile, sessionId, createdAt }
+}
+
+export function fabrikaDir(repoRoot: string): string {
+	return join(resolve(repoRoot), FABRIKA_DIRNAME)
+}
+
+export function configPath(repoRoot: string): string {
+	return join(fabrikaDir(repoRoot), 'config.json')
+}
+
+export function isInitialized(repoRoot: string): boolean {
+	return existsSync(configPath(repoRoot))
+}
+
+export function readConfig(repoRoot: string): FabrikaConfig | null {
+	const p = configPath(repoRoot)
+	if (!existsSync(p)) return null
+	try {
+		return parseConfig(JSON.parse(readFileSync(p, 'utf-8')))
+	} catch {
+		return null
+	}
+}
+
+export interface InitResult {
+	repoRoot: string
+	fabrikaDir: string
+	config: FabrikaConfig
+	createdDirs: string[]
+	createdConfig: boolean
+	alreadyInitialized: boolean
+}
+
+export function scaffold(
+	repoRoot: string,
+	opts: { profile?: string; sessionId?: string } = {},
+): InitResult {
+	const root = resolve(repoRoot)
+	const fdir = fabrikaDir(root)
+	const profile = opts.profile ?? 'cf-lightweight'
+	const createdDirs: string[] = []
+
+	const alreadyInitialized = isInitialized(root)
+
+	for (const dir of ['.', ...LAYER_DIRS]) {
+		const abs = dir === '.' ? fdir : join(fdir, dir)
+		if (!existsSync(abs)) {
+			mkdirSync(abs, { recursive: true })
+			createdDirs.push(abs)
+		}
+	}
+
+	for (const dir of EXTERNAL_DIRS) {
+		const abs = join(root, dir)
+		if (!existsSync(abs)) {
+			mkdirSync(abs, { recursive: true })
+			createdDirs.push(abs)
+		}
+	}
+
+	let config: FabrikaConfig
+	let createdConfig = false
+	const existing = readConfig(root)
+	if (existing) {
+		config = existing
+	} else {
+		config = {
+			profile,
+			sessionId: opts.sessionId ?? hashRepoPath(root),
+			createdAt: new Date().toISOString(),
+		}
+		writeFileSync(configPath(root), JSON.stringify(config, null, 2) + '\n')
+		createdConfig = true
+	}
+
+	return {
+		repoRoot: root,
+		fabrikaDir: fdir,
+		config,
+		createdDirs,
+		createdConfig,
+		alreadyInitialized,
+	}
+}
+
+export function findRepoRoot(start: string = process.cwd()): string | null {
+	let dir = resolve(start)
+	while (true) {
+		if (existsSync(join(dir, FABRIKA_DIRNAME)) && statSync(join(dir, FABRIKA_DIRNAME)).isDirectory()) {
+			return dir
+		}
+		const parent = resolve(dir, '..')
+		if (parent === dir) return null
+		dir = parent
+	}
+}