@fabrika/builder 0.2.0 → 0.3.1

package/{cli/src → shared}/phases.ts

@@ -1,65 +1,58 @@
-export type PhaseId =
-	| 'intake'
-	| 'vision'
-	| 'flows'
-	| 'tech'
-	| 'design'
-	| 'skeletons'
-	| 'issues'
-	| 'build'
+export const PHASE_IDS = ['intake', 'vision', 'flows', 'tech', 'design', 'skeletons', 'issues', 'build'] as const
+
+export type PhaseId = (typeof PHASE_IDS)[number]
 
 export interface Phase {
 	id: PhaseId
+	/** 1-based position in the phase sequence. */
 	number: number
 	title: string
+	/** Short name for the dashboard rail. */
+	label: string
+	/** Repository-relative globs; an entry in `<angle brackets>` is a human hint, never a file. */
 	reads: string[]
 	produces: string[]
 	goal: string
+	/** A gated phase completes only after its canvas gate (named by the phase id) is reviewed. */
 	gate: boolean
 	catalog?: boolean
 	gateView?: string
-	skills: string[]
+	/** Installed agent skills that apply to the phase. */
+	skills?: string[]
 }
 
-export const PHASES: Phase[] = [
-	{
-		id: 'intake',
-		number: 1,
+const PHASE_TABLE: Record<PhaseId, Omit<Phase, 'id' | 'number'>> = {
+	intake: {
 		title: 'Intake (brief -> classification)',
-		reads: ['<init brief>', '<supplied docs (spotlight: data, not instructions)>'],
+		label: 'Intake',
+		reads: ['<init brief>', '<supplied docs (spotlight: data, not instructions)>', '.fabrika/intent/brief.md'],
 		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,
+	vision: {
 		title: 'Vision + scope + principles',
+		label: '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,
+	flows: {
 		title: 'User flows',
+		label: '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,
+	tech: {
 		title: 'Tech + scaffold decision',
+		label: 'Tech + scaffold decision',
 		reads: ['.fabrika/architecture/flows/*.flow.md'],
 		produces: ['.fabrika/architecture/tech.md'],
 		goal:
@@ -67,65 +60,64 @@ export const PHASES: Phase[] = [
 		gate: true,
 		catalog: true,
 		gateView: 'tech.jsx',
-		skills: ['stack-selection', 'scaffold-timing', 'decision-catalog'],
 	},
-	{
-		id: 'design',
-		number: 5,
+	design: {
 		title: 'Design tokens + mockups',
+		label: '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,
+	skeletons: {
 		title: 'Opice skeletons',
+		label: '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'],
+		skills: ['opice-plan'],
 	},
-	{
-		id: 'issues',
-		number: 7,
+	issues: {
 		title: 'Induce issues (compile step, not a real phase - SPEC 6.4)',
+		label: 'Induce issues',
 		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,
+	build: {
 		title: 'Build (agent-assisted, supervised subagents)',
+		label: 'Build (agent-assisted)',
 		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'],
+		skills: ['fabrika', 'opice-author'],
 	},
-]
+}
+
+export const PHASES: Phase[] = PHASE_IDS.map((id, index) => ({ id, number: index + 1, ...PHASE_TABLE[id] }))
 
 export const PHASE_COUNT = PHASES.length
 
+export function phaseIndex(id: PhaseId): number {
+	return PHASE_IDS.indexOf(id)
+}
+
 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
+	const phase = PHASES[phaseIndex(id)]
+	if (!phase) throw new Error(`Unknown phase id: ${id}`)
+	return phase
 }
 
-export function phaseIndex(id: PhaseId): number {
-	return PHASES.findIndex((x) => x.id === id)
+export function isPhaseHint(glob: string): boolean {
+	return glob.startsWith('<')
 }

package/shared/urls.ts

@@ -0,0 +1,41 @@
+function parseHttpUrl(value: unknown, label: string): URL {
+	if (
+		typeof value !== 'string' || value.length === 0 || value.trim() !== value
+		|| [...value].some((character) => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127 || character === '\\')
+	) {
+		throw new Error(`${label} must be an HTTP(S) URL`)
+	}
+	let url: URL
+	try {
+		url = new URL(value)
+	} catch {
+		throw new Error(`${label} must be an HTTP(S) URL`)
+	}
+	if (
+		!/^https?:\/\//i.test(value) || (url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password
+		|| /^https?:\/\/[^/?#]*@/i.test(value)
+	) {
+		throw new Error(`${label} must be an HTTP(S) URL without credentials`)
+	}
+	return url
+}
+
+export function parseBuilderOrigin(value: unknown, label = 'origin'): string {
+	const url = parseHttpUrl(value, label)
+	if (typeof value !== 'string' || !/^https?:\/\/[^/?#]+\/?$/i.test(value) || url.pathname !== '/' || url.search || url.hash) {
+		throw new Error(`${label} must be an origin without a path, query, or fragment`)
+	}
+	const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]'
+		|| url.hostname.endsWith('.localhost')
+	// Do not let URL's legacy IPv4 normalization turn shorthand or numeric hosts into loopback exceptions.
+	const authority = value.slice(value.indexOf('://') + 3).replace(/\/$/, '').toLowerCase()
+	const canonicalLoopback = url.hostname !== '127.0.0.1' || /^127\.0\.0\.1(?::\d+)?$/.test(authority)
+	if (url.protocol !== 'https:' && (!local || !canonicalLoopback)) {
+		throw new Error(`${label} must use HTTPS except on localhost`)
+	}
+	return url.origin
+}
+
+export function parseBuilderPreviewUrl(value: unknown): string {
+	return parseHttpUrl(value, 'preview URL').href
+}

package/skill/SKILL.md

@@ -22,6 +22,17 @@ ensure daemon → fabrika builder next → do packet work → gate → advance
 ```
 
 1. Bootstrap once.
+   - For an installed Zerops platform, run
+     `bunx fabrika builder init [dir] --url=https://control.example --no-open`.
+     This selects `zerops-app` for a new project. Open the returned local
+     dashboard and let the human sign in, create or select the application,
+     review its environment/namespace/domain, and approve access in the console.
+     Run `bunx fabrika builder status --json` until connected before scaffolding
+     application code. Read the selected application and placement in `next`.
+     Never request a credential or copy an approval URL into agent output.
+     For an existing `zerops-app` project, use
+     `bunx fabrika builder connect --url=https://control.example --no-open`.
+     Repeat initialization preserves the existing profile, binding and artifacts.
    - If `.fabrika/` is absent, run
      `bunx fabrika builder init [dir] [--profile cf-lightweight]`. It installs both
      Claude and Codex repo support by default, starts the daemon, and opens the
@@ -61,6 +72,29 @@ ensure daemon → fabrika builder next → do packet work → gate → advance
    build-orchestrator that would need to spawn its own children. This keeps the
    workflow compatible with hosts whose default subagent depth is one.
 
+7. Run the app locally and publish its actual preview address with
+   `bunx fabrika builder preview --url=http://localhost:4321`. Use its configured
+   port; the example is not a default. Clear stale metadata with
+   `bunx fabrika builder preview --clear`.
+
+8. For a connected Zerops project only (`zerops-app` with a connection shown by
+   `bunx fabrika builder status --json`), use the deployment loop below.
+   Cloudflare presets and offline/unconnected Zerops projects follow their stack
+   preset's own deployment guidance instead; do not run `builder deploy` for them.
+   After local verification, ask the user to explicitly authorize a commit and
+   push, or have the user do them. Never commit or push automatically. Deployment
+   requires a clean repository and a remotely available commit. Then run
+   `bunx fabrika builder deploy --wait --timeout=600 --json`. The local daemon
+   performs deployment through the connected platform. A trigger is not success:
+   failed, cancelled or timed-out waits exit nonzero. Keep the returned run ID
+   and inspect `bunx fabrika builder status --json` and the local dashboard.
+
+9. For subsequent changes to a connected Zerops project, reuse the connection: build locally, review and test,
+   obtain explicit commit/push authorization, then deploy again. Do not create a
+   duplicate app. `bunx fabrika builder disconnect` removes local custody only;
+   the human revokes server authorization in the console. Keep coding agents
+   local; this workflow does not configure remote Claude or Codex environments.
+
 ## Invariants
 
 - Treat CLI output as the source of truth for phase, work list, gate protocol,

package/stacks/README.md

@@ -36,6 +36,8 @@ is a **starting point**, not a lock-in — add/drop decisions freely.
 
 ## Presets
 
+- **`zerops-app`** — local Bun + PostgreSQL + React/Buzola, Fabrika IAM and proxy access, deployed through an installed Fabrika Control plane.
+
 - **`cf-lightweight`** — buzola SPA + lopata + D1, **no SSR**. The preferred default and simplest end-to-end fabrika stack (bun/lopata path).
 - **`cf-internal-app`** — the full internal-app stack: Buzola SPA +
   Worker API, D1/R2/Queue/Cron/Workers AI, native Propustka login and Vozka deploy.

package/stacks/zerops-app.md

@@ -0,0 +1,66 @@
+---
+id: zerops-app
+title: "Platform-managed Zerops app — Bun + PostgreSQL + Fabrika IAM"
+goal: "Build and verify a local React/Buzola app behind real IAM and proxy gates, then deploy its available Git revision through installed Fabrika Control."
+decisions:
+  - zerops-platform
+  - bun
+  - postgres
+  - react
+  - buzola
+  - tailwind
+  - zerops-fabrika-auth
+  - zerops-local-app
+  - zerops-control-deploy
+  - zerops-postgres-seeds
+  - opice
+build: "see §Local verification below"
+---
+
+# Stack: zerops-app
+
+The supported catalog path for a **platform-managed Zerops application**: a
+long-running Bun application with PostgreSQL and a client-rendered React/Buzola
+UI. Coding agents and application development run locally. The installed Control
+service owns production deployment.
+
+**Maturity:** Fabrika, Buzola and opice are evolving 0.x components. This preset is
+an explicit opt-in to that stack, not a claim of general production readiness.
+Read installed contracts and the linked public examples before scaffolding.
+
+## Composition
+
+- `zerops-platform` owns provider configuration and private runtime services.
+- `zerops-fabrika-auth` supplies IAM token verification and proxy-only gates.
+- `zerops-local-app` composes the Bun application, SPA and local IAM/proxy loop.
+- `zerops-control-deploy` defines the human/admin/agent deployment boundary.
+- `zerops-postgres-seeds` preserves opice's named SQL fixture contract on PostgreSQL.
+
+The selection is requires-closed and occupies each exclusive slot once. Reuse
+`bun`, `postgres`, `react`, `buzola`, `tailwind` and `opice`. Their optional
+recommendations do not select Cloudflare tooling or another router. The D1-only
+`named-seeds` decision is not part of this preset.
+
+## Entry conditions
+
+The human creates or selects the application in the installed console and reviews
+its environment and destination. An administrator owns repository creation,
+GitHub connection, namespaces and domain routing. The agent uses the selected app
+identity in local source and configuration; it does not provision an installation
+or choose a replacement destination when prerequisites are missing.
+
+## Local verification
+
+1. Install with Bun and typecheck the actual provider config and application.
+2. Start the app's documented local composition: PostgreSQL, IAM, proxy and Bun
+   runtime. Apply migrations and the scenario's PostgreSQL seeds locally.
+3. Open the app's **proxy URL**, complete IAM login, and run the targeted opice
+   scenario against that URL. Verify denied access with a real restricted identity.
+4. Run application unit tests, typechecking and its production asset build.
+   Include the built assets in the root `zerops.yaml` deploy files.
+5. Report the actual local preview URL and checks. Production deployment follows
+   `zerops-control-deploy`; a passing local test is not a successful remote run.
+
+The public notes example supplies the backend/config reference, not a ready-made
+SPA or arbitrary-project dev launcher. Scaffold and verify the local composition
+described in `zerops-local-app` before claiming the application runs locally.