@fabrika/builder 0.2.0 → 0.3.2

package/BUILD-CONTRACT.md

@@ -26,6 +26,14 @@ The phase is always derived from application files and gate state. No mutable ph
 
 The stable session ID identifies dashboard revisions. Persistent daemon state defaults to `~/.fabrika` and can be moved with `FABRIKA_DATA_DIR`.
 
+Project registration is independent of canvas revisions. Optional connection and preview fields are non-secret. Credentials are stored separately outside registered projects, and approved installation origins are pinned independently of project JSON.
+
+## Platform operations
+
+Shared parsed DTOs live in `shared/`. CLI and UI use `/api/project/:id/register`, `/platform`, `/connect`, `/disconnect`, `/deploy` and `/preview`. The daemon owns pairing, credential custody, isolated local compilation, Control RPC calls and run observation. No key enters browser state or compiler environment.
+
+The installed console owns human application creation/selection and initial placement approval. The daemon updates environments and triggers exact remotely available commits; it does not create repositories, commit, push or deploy directly to the provider. Disconnect is local deletion, not remote revocation.
+
 ## Gate protocol
 
 1. `gate open` sends one view or a directory of views to `POST /api/session/:id/plan`.

package/README.md

@@ -38,6 +38,13 @@ All commands:
 
 ```text
 fabrika builder init [dir] [--profile <stack>] [--agent all|claude|codex]
+fabrika builder init [dir] --url=<control-origin>
+fabrika builder connect --url=<control-origin> [--no-open] [--json]
+fabrika builder status [--json]
+fabrika builder disconnect [--json]
+fabrika builder deploy [--wait] [--timeout=<seconds>] [--json]
+fabrika builder preview --url=<preview-url>
+fabrika builder preview --clear
 fabrika builder next [--json]
 fabrika builder advance [--force]
 fabrika builder gate open <name> --view <file.jsx>
@@ -49,6 +56,8 @@ fabrika builder build [--issue <ID>] [--assisted]
 
 Use `--profile cf-internal-app` for the full Buzola, Propustka, and Vozka internal-app stack. The default is `cf-lightweight`.
 
+Connected initialization uses `zerops-app` for a new project. A person approves the application and environment in the installed console; the local daemon receives a thirty-day app-scoped credential. The agent and application stay local. Deployment requires a clean, remotely available Git revision and runs through Control. `disconnect` removes the local key only; revoke server access in the console. See [the connected workflow](../../docs/reference/local-builder.md) for prerequisites, custody and recovery.
+
 ## Generated application state
 
 ```text

package/cli/src/bin.ts

@@ -7,13 +7,27 @@ import { cmdGate } from './commands/gate'
 import { cmdInduce } from './commands/induce'
 import { cmdInit } from './commands/init'
 import { cmdNext } from './commands/next'
+import { cmdPlatform } from './commands/platform'
+import { BuilderCliError } from './errors'
 
 export const BUILDER_USAGE = `fabrika builder — guided application builder
 
 Usage:
   fabrika builder init [dir] [--profile <stack>] [--agent all|claude|codex]
+                       [--session=<id>] [--no-open] [--no-daemon] [--json]
                                                Scaffold .fabrika/, install agent support, open dashboard
   fabrika builder next [--json]                      Print the task packet for the current derived phase
+  fabrika builder init [dir] --url=<origin> [--no-open]  Initialize zerops-app and begin human consent
+                         [--no-daemon]               Offline init only; incompatible with --url
+  fabrika builder connect --url=<origin> [--no-open] [--json]
+  fabrika builder status [--json]                    Read connection and deployment status
+  fabrika builder disconnect [--json]                Remove local custody; revoke separately in console
+  fabrika builder deploy [--wait] [--timeout=<seconds>] [--json]
+  fabrika builder preview --url=<url> | --clear [--json]
+                                                    Platform commands also accept --dir=<project>
+                                                    Results are sanitized JSON; wait defaults to 600 seconds
+                                                    --no-open returns the local dashboard URL, never approval proof
+                                                    All commands accept --help and never prompt for input
   fabrika builder advance [--force]                  Validate outputs and gate, then print the next phase
   fabrika builder gate open <name> --view <f.jsx>    Push a canvas gate and open the dashboard
   fabrika builder gate wait [--gate <n>] [--timeout] Wait for submitted gate feedback
@@ -24,19 +38,38 @@ Usage:
 Environment:
   FABRIKA_PORT         Daemon port (default 19410)
   FABRIKA_SESSION_ID   Session id (fallback: stable hash of repo abs path)
-  FABRIKA_DATA_DIR     Persistent daemon/session data (default ~/.fabrika; legacy auto-detected)
+  FABRIKA_DATA_DIR     Persistent daemon/session data (default ~/.fabrika)
   FABRIKA_TIMEOUT      gate wait timeout in ms (default 3600000)`
 
 export async function runBuilderCli(argv: readonly string[]): Promise<number> {
+	try {
+		return await dispatchBuilderCli(argv)
+	} catch (error) {
+		console.error(
+			error instanceof BuilderCliError
+				? error.message
+				: 'Builder command failed. Check arguments, .fabrika/config.json, and the local dashboard; use --help for usage.',
+		)
+		return 1
+	}
+}
+
+async function dispatchBuilderCli(argv: readonly string[]): Promise<number> {
 	const command = argv[0]
 	const rest = argv.slice(1)
 
-	if (!command || command === '--help' || command === '-h' || command === 'help') {
+	if (!command || command === '--help' || command === '-h' || command === 'help' || rest.includes('--help') || rest.includes('-h')) {
 		console.info(BUILDER_USAGE)
 		return command ? 0 : 1
 	}
 
 	switch (command) {
+		case 'connect':
+		case 'status':
+		case 'disconnect':
+		case 'deploy':
+		case 'preview':
+			return cmdPlatform(command, rest)
 		case 'init':
 			return cmdInit(rest)
 		case 'next':

package/cli/src/build-status.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
+import { z } from 'zod'
 import type { Issue } from './issues'
 
 export type IssueStatus = 'done' | 'blocked'
@@ -12,23 +13,14 @@ export interface BuildRecord {
 
 export type BuildBoard = Record<string, BuildRecord>
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
+const buildBoardSchema = z.record(
+	z.object({ status: z.enum(['done', 'blocked']), at: z.string(), reason: z.string().optional() })
+		.transform(({ status, at, reason }) => ({ status, at, ...(reason === undefined ? {} : { reason }) })),
+)
 
 function parseBoard(value: unknown): BuildBoard | null {
-	if (!isRecord(value)) return null
-	const board: BuildBoard = {}
-	for (const [id, candidate] of Object.entries(value)) {
-		if (!isRecord(candidate)) return null
-		const status = candidate['status']
-		const at = candidate['at']
-		const reason = candidate['reason']
-		if ((status !== 'done' && status !== 'blocked') || typeof at !== 'string') return null
-		if (reason !== undefined && typeof reason !== 'string') return null
-		board[id] = { status, at, ...(reason === undefined ? {} : { reason }) }
-	}
-	return board
+	const result = buildBoardSchema.safeParse(value)
+	return result.success ? result.data : null
 }
 
 function boardPath(fabrikaDir: string): string {

package/cli/src/commands/advance.ts

@@ -1,9 +1,10 @@
 import { parseArgs } from 'util'
+import { PHASE_COUNT, phaseById, phaseIndex, PHASES } from '../../../shared/phases'
 import { resolveContext } from '../context'
-import { consumeFeedback, isDaemonRunning } from '../daemon-client'
+import { consumeFeedback } from '../daemon-client'
+import { isDaemonRunning } from '../daemon-lifecycle'
 import { isNonEmptyFile, matchGlob, producesSatisfied } from '../derive'
 import { resolvePhaseState } from '../phase-state'
-import { PHASE_COUNT, phaseById, phaseIndex, PHASES } from '../phases'
 
 export async function cmdAdvance(argv: string[]): Promise<number> {
 	const { values } = parseArgs({

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

@@ -1,6 +1,5 @@
 import { BASE_URL } from '../config'
-import { health } from '../daemon-client'
-import { ensureDaemon } from '../daemon-lifecycle'
+import { daemon, ensureDaemon } from '../daemon-lifecycle'
 
 export async function cmdEnsureDaemon(_argv: string[]): Promise<number> {
 	const up = await ensureDaemon()
@@ -8,7 +7,8 @@ export async function cmdEnsureDaemon(_argv: string[]): Promise<number> {
 		console.log(JSON.stringify({ ok: false, running: false, baseUrl: BASE_URL }))
 		return 1
 	}
-	const info = await health()
+	const health = await daemon.health()
+	const info = health.status === 'up' ? health : null
 	console.log(
 		JSON.stringify({
 			ok: true,

package/cli/src/commands/gate.ts

@@ -1,9 +1,10 @@
+import { WaitError } from '@fabrika/daemon-kit'
 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 { pushPlan, waitForFeedback } from '../daemon-client'
 import { ensureDaemon, openBrowser } from '../daemon-lifecycle'
 
 export async function cmdGate(argv: string[]): Promise<number> {
@@ -143,22 +144,15 @@ async function gateWait(argv: string[]): Promise<number> {
 		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') {
+		if (error instanceof WaitError && error.reason === 'timeout') {
 			console.error('[fabrika] timeout waiting for gate feedback.')
 		} else {
-			console.error(`[fabrika] gate wait failed: ${reason}`)
+			console.error(`[fabrika] gate wait failed: ${error instanceof Error ? error.message : String(error)}`)
 		}
 		return 1
 	}

package/cli/src/commands/init.ts

@@ -1,10 +1,13 @@
-import { rmSync } from 'fs'
-import { join } from 'path'
-import { parseArgs } from 'util'
+import { rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseArgs } from 'node:util'
+import { type BuilderPlatformStatus, parseBuilderOrigin } from '../../../shared'
 import { BASE_URL, SESSIONS_DIR } from '../config'
 import { ensureDaemon, openBrowser } from '../daemon-lifecycle'
+import { BuilderCliError } from '../errors'
 import { type AgentHost, injectAgentSupport, parseAgentHosts } from '../inject-skills'
-import { scaffold } from '../layout'
+import { readConfig, scaffold } from '../layout'
+import { platformRequest, publicPlatformStatus } from '../platform-client'
 
 async function resetStaleSession(sessionId: string): Promise<void> {
 	try {
@@ -21,7 +24,9 @@ export async function cmdInit(argv: string[]): Promise<number> {
 	const { values, positionals } = parseArgs({
 		args: argv,
 		options: {
-			profile: { type: 'string', default: 'cf-lightweight' },
+			profile: { type: 'string' },
+			url: { type: 'string' },
+			json: { type: 'boolean' },
 			session: { type: 'string' },
 			agent: { type: 'string', default: 'all' },
 			'no-daemon': { type: 'boolean', default: false },
@@ -38,7 +43,21 @@ export async function cmdInit(argv: string[]): Promise<number> {
 		return 1
 	}
 	const dir = positionals[0] ?? process.cwd()
-	const result = scaffold(dir, { profile: values.profile, sessionId: values.session })
+	if (positionals.length > 1) throw new Error('Expected at most one project directory.')
+	const origin = values.url === undefined ? undefined : parseBuilderOrigin(values.url, 'control origin')
+	if (origin && values['no-daemon']) throw new BuilderCliError('--url cannot be combined with --no-daemon.')
+	const existing = readConfig(dir)
+	const profile = values.profile ?? existing?.profile ?? (origin ? 'zerops-app' : 'cf-lightweight')
+	if (existing && (profile !== existing.profile || (values.session && values.session !== existing.sessionId))) {
+		throw new BuilderCliError('Existing project profile and session cannot be replaced by init.')
+	}
+	if (origin && (profile !== 'zerops-app' || (existing?.connection && existing.connection.receipt.provider !== 'zerops'))) {
+		throw new BuilderCliError('Connected initialization requires zerops-app.')
+	}
+	if (origin && existing?.connection && existing.connection.controlOrigin !== origin) {
+		throw new BuilderCliError('Disconnect explicitly before changing installations.')
+	}
+	const result = scaffold(dir, { profile, sessionId: values.session })
 	const support = injectAgentSupport(result.repoRoot, { hosts })
 
 	if (result.alreadyInitialized) {
@@ -60,13 +79,29 @@ export async function cmdInit(argv: string[]): Promise<number> {
 	}
 
 	const browserUrl = `${BASE_URL}/s/${result.config.sessionId}`
+	let platform: BuilderPlatformStatus | undefined
 	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']) {
+		if (up) {
+			platform = await platformRequest(result.config.sessionId, 'register', { projectRoot: result.repoRoot })
+			if (origin) {
+				const pinnedOrigin = platform.connection?.controlOrigin
+					?? (platform.pairing?.status === 'pending' ? new URL(platform.pairing.authorizationUrl).origin : undefined)
+				if (pinnedOrigin && pinnedOrigin !== origin) throw new BuilderCliError('Disconnect explicitly before changing installations.')
+				if (!existing?.connection && !platform.connection && platform.pairing?.status !== 'pending' && platform.pairing?.status !== 'approved') {
+					platform = await platformRequest(result.config.sessionId, 'connect', { controlOrigin: origin })
+				}
+			}
+		} else if (origin) {
+			throw new Error('Local builder daemon is unavailable.')
+		}
+		if (up && !values['no-open'] && platform?.pairing?.status === 'pending') {
+			openBrowser(platform.pairing.authorizationUrl, browserUrl)
+		} else if (up && !values['no-open']) {
 			openBrowser(browserUrl)
 		} else if (!up) {
 			console.error(`[fabrika] daemon not started (offline). Dashboard: ${browserUrl}`)
@@ -85,7 +120,9 @@ export async function cmdInit(argv: string[]): Promise<number> {
 			agents: support.hosts,
 			browserUrl,
 			createdConfig: result.createdConfig,
+			...(platform ? { platform: publicPlatformStatus(platform) } : {}),
 		}),
 	)
+	if (origin && platform?.pairing && ['failed', 'expired', 'cancelled', 'recovery_required'].includes(platform.pairing.status)) return 1
 	return 0
 }

package/cli/src/commands/next.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'util'
+import { parseArgs } from 'node:util'
 import { resolveContext } from '../context'
 import { packetJson, renderPacket } from '../packet'
 import { resolvePhaseState } from '../phase-state'
@@ -23,9 +23,9 @@ export async function cmdNext(argv: string[]): Promise<number> {
 	const { state, source } = await resolvePhaseState(ctx.repoRoot, ctx.fabrikaDir, ctx.sessionId)
 
 	if (values.json) {
-		console.log(JSON.stringify({ ...packetJson(state, { profile: ctx.profile }), source }))
+		console.log(JSON.stringify({ ...packetJson(state, { profile: ctx.profile, connection: ctx.connection }), source }))
 	} else {
-		process.stdout.write(renderPacket(state, { profile: ctx.profile }))
+		process.stdout.write(renderPacket(state, { profile: ctx.profile, connection: ctx.connection }))
 	}
 	return 0
 }

package/cli/src/commands/platform.ts

@@ -0,0 +1,81 @@
+import { parseArgs } from 'node:util'
+import { parseBuilderOrigin, parseBuilderPreviewUrl } from '../../../shared'
+import { BASE_URL } from '../config'
+import { resolveContext } from '../context'
+import { ensureDaemon, openBrowser } from '../daemon-lifecycle'
+import { BuilderCliError } from '../errors'
+import { readConfig } from '../layout'
+import { platformRequest, publicPlatformStatus } from '../platform-client'
+
+export type PlatformCommand = 'connect' | 'status' | 'disconnect' | 'deploy' | 'preview'
+const stringOption: { type: 'string' } = { type: 'string' }
+const booleanOption: { type: 'boolean' } = { type: 'boolean' }
+
+export async function cmdPlatform(command: PlatformCommand, argv: string[]): Promise<number> {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			json: { type: 'boolean' },
+			dir: { type: 'string' },
+			...(command === 'connect' || command === 'preview' ? { url: stringOption } : {}),
+			...(command === 'connect' ? { 'no-open': booleanOption } : {}),
+			...(command === 'preview' ? { clear: booleanOption } : {}),
+			...(command === 'deploy' ? { wait: booleanOption, timeout: stringOption } : {}),
+		},
+	})
+	const origin = command === 'connect' ? parseBuilderOrigin(values.url, 'control origin') : undefined
+	if (command === 'preview' && Boolean(values.clear) === (values.url !== undefined)) {
+		throw new BuilderCliError('Use preview --url=<url> or preview --clear.')
+	}
+	const previewUrl = command === 'preview' && !values.clear ? parseBuilderPreviewUrl(values.url) : null
+	const seconds = values.timeout === undefined ? 600 : Number(values.timeout)
+	if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86400) throw new Error('Timeout must be between 0 and 86400 seconds (exclusive of 0).')
+	if (values.timeout !== undefined && !values.wait) throw new Error('--timeout requires --wait.')
+	const ctx = resolveContext({ dir: values.dir })
+	const config = readConfig(ctx.repoRoot)
+	if (!config) throw new BuilderCliError('Run fabrika builder init first.')
+	if (
+		(command === 'connect' || command === 'deploy')
+		&& (config.profile !== 'zerops-app' || (config.connection && config.connection.receipt.provider !== 'zerops'))
+	) {
+		throw new BuilderCliError('Connected deployment requires the zerops-app profile.')
+	}
+	if (!await ensureDaemon({ quiet: true })) throw new BuilderCliError('Local builder daemon is unavailable.')
+	await platformRequest(config.sessionId, 'register', { projectRoot: ctx.repoRoot })
+	const dashboardUrl = `${BASE_URL}/s/${encodeURIComponent(config.sessionId)}`
+	let status = await platformRequest(
+		config.sessionId,
+		command === 'status' ? 'platform' : command,
+		command === 'status' ? undefined : command === 'connect' ? { controlOrigin: origin } : command === 'preview' ? { url: previewUrl } : {},
+	)
+	if (command === 'connect' && status.pairing?.status === 'pending' && !values['no-open']) {
+		openBrowser(status.pairing.authorizationUrl, dashboardUrl)
+	}
+	if (command === 'disconnect') console.error('Local credentials removed. Revoke the authorization in the platform console to revoke server access.')
+	let outcome: string | undefined
+	if (command === 'deploy' && values.wait) {
+		const deadline = Date.now() + seconds * 1000
+		while (status.deployment && ['preparing', 'pending', 'running'].includes(status.deployment.status)) {
+			if (Date.now() >= deadline) {
+				outcome = 'timed_out'
+				break
+			}
+			await Bun.sleep(Math.min(1000, deadline - Date.now()))
+			if (Date.now() >= deadline) {
+				outcome = 'timed_out'
+				break
+			}
+			try {
+				status = await platformRequest(config.sessionId, 'platform', undefined, Math.max(1, Math.ceil(deadline - Date.now())))
+			} catch {
+				outcome = Date.now() >= deadline ? 'timed_out' : 'poll_failed'
+				break
+			}
+		}
+		outcome ??= status.deployment?.status ?? 'missing_run'
+	}
+	console.log(JSON.stringify({ ...publicPlatformStatus(status), dashboardUrl, ...(outcome ? { outcome } : {}) }))
+	if (command === 'connect' && status.pairing && ['failed', 'expired', 'cancelled', 'recovery_required'].includes(status.pairing.status)) return 1
+	if (command === 'deploy' && status.deployment && ['failed', 'cancelled'].includes(status.deployment.status)) return 1
+	return outcome !== undefined && outcome !== 'succeeded' ? 1 : 0
+}

package/cli/src/config.ts

@@ -1,15 +1,14 @@
 import { createHash } from 'crypto'
-import { existsSync } from 'fs'
 import { homedir, tmpdir } from 'os'
 import { join, resolve } from 'path'
+import { builderDaemonUrl } from '../../shared/urls'
 
 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 BASE_URL = builderDaemonUrl(DAEMON_PORT)
+export const WS_URL = builderDaemonUrl(DAEMON_PORT, 'ws')
 
 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')
@@ -21,17 +20,11 @@ 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
+	return join(home, '.fabrika')
 }
 
 export function getSessionId(explicit?: string, recorded?: string, repoRoot?: string): string {

package/cli/src/context.ts

@@ -1,4 +1,5 @@
-import { resolve } from 'path'
+import { resolve } from 'node:path'
+import type { BuilderProjectConnection } from '../../shared'
 import { getSessionId } from './config'
 import { fabrikaDir, findRepoRoot, readConfig } from './layout'
 
@@ -8,6 +9,7 @@ export interface CommandContext {
 	sessionId: string
 	profile: string
 	initialized: boolean
+	connection?: BuilderProjectConnection
 }
 
 export function resolveContext(opts: { dir?: string; session?: string } = {}): CommandContext {
@@ -24,5 +26,6 @@ export function resolveContext(opts: { dir?: string; session?: string } = {}): C
 		sessionId,
 		profile: config?.profile ?? 'cf-lightweight',
 		initialized: config !== null,
+		...(config?.connection ? { connection: config.connection } : {}),
 	}
 }