@fugood/bricks-ctor 2.25.0-beta.60 → 2.25.0-beta.61

package/skills/bricks-ux/references/ux-critique.md

@@ -1,256 +0,0 @@
-# UX Critique
-
-Verification proves the flow *runs*. UX critique proves the flow is *usable*. Both are required before declaring done; neither substitutes for the other.
-
-UX critique runs in parallel with visual-design critique (`bricks-design/design-critique.md`). A Canvas can fail one and pass the other; both block ship.
-
-This file is tiered. The same UX problem (e.g., closure missing) is **CRITICAL** on a payment kiosk and **MEDIUM** on a museum signage loop. Critique fails ship when CRITICAL or HIGH items go unaddressed in their applicable tiers.
-
-## How to run the pass
-
-1. **Open the journey.** Walk every interaction step-by-step using `user-journey.md` as the spine.
-2. **For each Canvas / Brick group, classify by deployment risk** (table below). The classification determines which tier of checks apply.
-3. **Run the checks in the applicable tier(s).** CRITICAL items always run; HIGH applies broadly; MEDIUM and LOW depend on classification.
-4. **Fix every CRITICAL miss and every HIGH miss.** Surface MEDIUM and LOW misses in the trade-off note if not addressed.
-5. **Re-verify after fixes.** Don't accumulate fix debt.
-
-## Risk classification by deployment shape
-
-| Deployment shape | Risk profile | Tier weighting |
-|---|---|---|
-| Payment / identity capture / safety-critical | CRITICAL-dense — every transact discipline must pass | CRITICAL + HIGH + MEDIUM all apply |
-| Self-service interactive (ordering, check-in, configuration) | HIGH-dense — journey completeness, idle reset, recovery paths | CRITICAL + HIGH apply; MEDIUM where relevant |
-| Monitoring / dashboard / control room | HIGH-dense — alarm hierarchy, stale-data trust, calm/detect/demand | CRITICAL + HIGH apply for alarm states |
-| Browse / wayfinding / menu board | MEDIUM-dense — legibility, comparison clarity, sparse states | HIGH legibility, MEDIUM elsewhere |
-| Glanceable signage / dwell / ambient loop | LOW-dense — main checks are legibility and rhythm | HIGH legibility, LOW elsewhere |
-
-## CRITICAL — blocks ship
-
-Failure on any of these is sufficient grounds to declare the work mid-iteration.
-
-### CR-1. The user-journey spine is whole
-
-Every interaction must have all seven steps present (or deliberately compressed; see `user-journey.md` § "When the seven steps compress"). Most-common holes:
-
-- **Immediate feedback missing** (step 3). User taps, nothing visible, taps again.
-- **In-flight visibility missing** (step 4). Action triggered, screen frozen, user re-triggers.
-- **Recovery as dead-end** (step 6). Error Canvas with no path forward.
-- **Closure ambiguous or missing** (step 7). Success state transient or unclear.
-
-**Must Have:** every interaction has a designed and verified affordance, instruction, feedback, in-flight state, continuation, recovery, closure — or deliberate documented collapse.
-**Anti-Pattern:** journey skipping any step on the assumption "it's fast enough not to need".
-
-### CR-2. Transact has its intensification
-
-For payment / identity / safety-critical flows, the seven steps must be tightened (`user-journey.md` § "When the seven steps intensify"):
-
-- Confirmation step before commit.
-- In-flight visibility non-skippable.
-- Recovery categorised (declined / network / cancelled / timeout).
-- Closure with weight and hold time.
-
-**Must Have:** transact closure holds ≥ 5 seconds, success unmistakable, peripheral state visible.
-**Anti-Pattern:** "Process payment in one tap" with no confirmation; closure that auto-advances in < 2s.
-
-### CR-3. Monitoring has demand discipline
-
-For dashboards / monitor screens with alarm capability:
-
-- Calm / detect / demand are three distinct designed states.
-- Demand state stands out unambiguously; not a slight colour change.
-- Multiple concurrent demand states have priority ordering already designed.
-- Stale-data is visibly declared per source.
-- Color is never the only encoding of severity.
-
-**Must Have:** alarm-state preview captured and reviewed; squint-test passes (alarm visible from peripheral vision); monochrome preview still distinguishes severity tiers.
-**Anti-Pattern:** alarm styled identically to detect-state; "stale" indicator at 8pt in corner; severity by colour alone.
-
-### CR-4. Accessibility floors met for the audience
-
-The seven accessibility disciplines (`accessibility.md`) apply at deployment-relative floors. CRITICAL when the audience includes:
-
-- Reduced-vision users (contrast, scale, color-not-only).
-- Reduced-motor users (touch targets, no precise gestures, no time-pressure auto-cancels).
-- Sensitive-to-motion users (reduced-motion path available).
-- Multilingual audience (strings via Data; type scale accommodates longest translation).
-
-**Must Have:** contrast verified under deployment-actual lighting; touch targets verified with real-finger / real-hardware testing; severity / status encoded by shape + color + label.
-**Anti-Pattern:** WCAG-compliance-on-desktop-monitor as the audit (deployment is sunlit signage at 4m); time-pressure UI on a venue that includes slow / hesitant users.
-
-### CR-5. Idle reset is clean
-
-For self-service interactive deployments:
-
-- Idle timeout exists and is calibrated to the use pattern.
-- Idle reset clears flow state — no half-built order persists; no name on screen; no half-confirmed action.
-- Reset returns to a designed idle / attractor state, not to "whatever Canvas was loaded".
-
-**Must Have:** verified idle reset behaviour via Automation or live test; verified that no leaked state persists to next session.
-**Anti-Pattern:** idle = last interact Canvas; idle that requires operator to manually reset.
-
-## HIGH — must fix before launch
-
-### H-1. Affordance is unambiguous
-
-Every pressable Brick declares "press me" visually — contrast, weight, motion, or icon. Affordance vocabulary is consistent across the deployment.
-
-**Must Have:** pressable tiles visually distinct from non-pressable; squint test confirms which Bricks are interactive.
-**Anti-Pattern:** identical-looking tiles where some are pressable and some aren't; pressable Bricks with no visual distinction from background.
-
-### H-2. Press feedback at registration
-
-Every `on_press` produces a visible state change at the moment of registration — scale, opacity, color, or new Brick entry via Standby Transition. Not a fade-in.
-
-**Must Have:** Brick under press visibly responds within 100ms (effectively snap, not fade).
-**Anti-Pattern:** press registers, no visible change; press relies on Canvas-change-only feedback (user perceives lag).
-
-### H-3. Flow states designed, not skipped
-
-Idle / loading / empty / error / boot / maintenance (as applicable to the deployment) are designed states, each with verified preview.
-
-**Must Have:** every applicable state's preview captured and reviewed; failure modes per state checked against `flow-states.md`.
-**Anti-Pattern:** "empty state is fine, the list is always populated" without testing the empty case; error state in 8pt corner text; boot = loading spinner.
-
-### H-4. Hero continuity across journey Canvases
-
-For multi-Canvas flows, hero Bricks share ids across Canvases — chrome (logo, progress indicator, time, back action) carries via Truth #3 auto-tween.
-
-**Must Have:** primary chrome elements identifiable in the same screen positions across the flow's Canvases.
-**Anti-Pattern:** every Canvas remounts its full Brick set; user loses spatial mental model between steps.
-
-### H-5. Error recovery has a path
-
-Every error state offers retry, alternate method, abandon, or help — never a dead-end. Different error categories get distinguishable recovery treatments.
-
-**Must Have:** each error path verified end-to-end via Automation or live test.
-**Anti-Pattern:** "Error. Please try again." with no retry mechanism; generic recovery for all error types.
-
-### H-6. Stale-data trust
-
-For monitoring / live-data screens, every dynamic source has a visibly declared staleness state or a visible "last update" relative-time indicator.
-
-**Must Have:** staleness visible in peripheral vision; stale value distinguishable from current value.
-**Anti-Pattern:** dynamic value with no age indication; "last update" in 8pt absolute timestamp.
-
-### H-7. Predictable navigation
-
-Navigation affordances (back, next, home) sit consistently across Canvases. Idle returns to the same idle Canvas every time.
-
-**Must Have:** back / next affordance positions verified across Canvases; idle reset produces identical idle Canvas every time.
-**Anti-Pattern:** back button at top-left on Canvas 2, bottom-right on Canvas 3; idle rotates such that the "anchor" element moves.
-
-## MEDIUM — impacts polish; prioritize by user impact
-
-### M-1. Instruction matches user mental model
-
-Action instructions ("Scan your code", "Tap to start", "Pay now") match the user's likely understanding; jargon avoided; language locale-matched.
-
-**Must Have:** wording reviewed for the actual audience; jargon removed.
-**Anti-Pattern:** "Initiate authentication sequence" on a public kiosk; English-only instruction on a multilingual venue.
-
-### M-2. Continuation is non-surprising
-
-The Canvas the user lands on after an action matches their expectation. Big jumps in journey context happen only with explicit transition.
-
-**Must Have:** continuation Canvas reviewed for context preservation; hero continuity in place.
-**Anti-Pattern:** success on Canvas A jumps to Canvas D mid-flow; user loses context.
-
-### M-3. Closure proportional to stakes
-
-Success closure hold time and visual weight match the action's stakes. Routine completions get brief acknowledgement; transact completions get held visible.
-
-**Must Have:** closure hold time tuned to action stakes; auto-advance only after enough time for the user to read.
-**Anti-Pattern:** 1.5s closure for a transact flow; 8s closure for a "saved to favorites" toast.
-
-### M-4. Density rhythm in browse / dwell
-
-For browse / dwell deployments, content rotation has variation in density / framing / colour rhythm across Canvases or slides. Three identical-rhythm Canvases in a row is a tell. (Cross-reference: `bricks-design/design-critique.md` density-rhythm collapse.)
-
-**Must Have:** rhythm variation across the sequence; no three identical-archetype Canvases in a row.
-**Anti-Pattern:** ten Canvases that all read as "headline + bullet list".
-
-### M-5. Audio cues calibrated (when hardware allows)
-
-If the deployment uses audio, volume / timing / time-of-day awareness is intentional.
-
-**Must Have:** audio volume / scheduling reviewed; success / alarm cues distinguishable from ambient.
-**Anti-Pattern:** constant-volume cues regardless of time; audio-only confirmation (no visual pair).
-
-### M-6. Reduced-motion path available (if relevant)
-
-For deployments in clinical / safety / motion-sensitive contexts, a reduced-motion path exists.
-
-**Must Have:** `reduceMotion` Data flag wired where applicable; verified reduced-motion preview.
-**Anti-Pattern:** continuous-motion design with no reduction path for a clinical deployment.
-
-## LOW — context-dependent
-
-### L-1. Polish on idle / attractor presence
-
-For deployments where idle dominates: idle is *inviting*, not just *running*.
-
-**Must Have for high-traffic public deployments:** attractor sequence engages from peripheral vision.
-**Anti-Pattern:** logo-only idle on a deployment whose purpose is to invite interaction.
-
-### L-2. Maintenance state designed
-
-If the deployment has scheduled downtime, a maintenance Canvas exists and distinguishes itself from error.
-
-**Must Have for deployments with maintenance windows:** maintenance Canvas with return path.
-**Anti-Pattern:** maintenance = black screen.
-
-### L-3. Empty-state composition
-
-Empty states explain the absence and suggest what populates.
-
-**Must Have:** empty state designed rather than collapsed-whitespace.
-**Anti-Pattern:** "—" or blank where content would be.
-
-## Tier-by-tier checklist (running order)
-
-Use this when running the pass:
-
-**CRITICAL (always run):**
-
-- [ ] User-journey spine whole (CR-1)
-- [ ] Transact intensified if applicable (CR-2)
-- [ ] Monitoring demand discipline if applicable (CR-3)
-- [ ] Accessibility floors met (CR-4)
-- [ ] Idle reset clean if applicable (CR-5)
-
-**HIGH (always run except for glance / dwell loops):**
-
-- [ ] Affordance unambiguous (H-1)
-- [ ] Press feedback at registration (H-2)
-- [ ] Flow states designed (H-3)
-- [ ] Hero continuity across Canvases (H-4)
-- [ ] Error recovery has a path (H-5)
-- [ ] Stale-data trust if applicable (H-6)
-- [ ] Predictable navigation (H-7)
-
-**MEDIUM (run for interact / transact / browse):**
-
-- [ ] Instruction matches mental model (M-1)
-- [ ] Continuation non-surprising (M-2)
-- [ ] Closure proportional (M-3)
-- [ ] Density rhythm (M-4)
-- [ ] Audio cues calibrated (M-5)
-- [ ] Reduced-motion path (M-6)
-
-**LOW (run for public-facing / high-dwell):**
-
-- [ ] Idle / attractor polish (L-1)
-- [ ] Maintenance state (L-2)
-- [ ] Empty-state composition (L-3)
-
-## Definition of UX done
-
-A flow is UX-done when:
-
-1. The CRITICAL tier passes — zero unaddressed CRITICAL items.
-2. The HIGH tier passes — zero unaddressed HIGH items (or surfaced as accepted trade-off with rationale).
-3. Applicable MEDIUM / LOW items either pass or are surfaced.
-4. Every state (golden path + error categories + idle + empty if relevant) has been verified via preview screenshot or Automation, and reviewed.
-5. Accessibility floors are met at the deployment-relative threshold, not at a desktop default.
-
-If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

package/skills/rive-marketplace/SKILL.md

@@ -1,99 +0,0 @@
----
-name: rive-marketplace
-description: Search and download assets from Rive Marketplace. Use when searching for Rive animations, downloading .riv files, or exploring Rive community assets. Supports keyword search, tag browsing, and direct file downloads via public API. Requires browser tool for searching; API calls work without browser.
----
-
-# Rive Marketplace
-
-Download animated assets (.riv files) from Rive's community marketplace.
-
-## URL Structure
-
-- **Featured**: `https://rive.app/marketplace/featured/`
-- **Latest**: `https://rive.app/marketplace/latest/`
-- **Search**: `https://rive.app/marketplace/search/{query}/`
-- **Tags**: `https://rive.app/marketplace/tag/{TagName}/`
-- **Item**: `https://rive.app/marketplace/{post_id}-{revision_id}-{slug}/`
-
-## API (Public, No Auth)
-
-### Get Post Details
-```bash
-curl -s "https://api.rive.app/api/community-posts/{post_id}" | jq '.'
-```
-
-**Response contains:**
-- `community_post_id` — Post ID
-- `owner.username` — Creator name
-- `community_revisions[0].title` — Asset title
-- `community_revisions[0].description` — Description
-- `community_revisions[0].tags` — Tags array
-- `community_revisions[0].community_files[0].file_url` — **Download URL**
-
-### Download .riv File
-```bash
-# Extract file_url from API response
-curl -s "https://api.rive.app/api/community-posts/{post_id}" | jq -r '.community_revisions[0].community_files[0].file_url'
-
-# Download directly
-curl -O "https://public.rive.app/community/runtime-files/{post_id}-{revision_id}-{slug}.riv"
-```
-
-## Workflow: Search → Download
-
-### 1. Browse via Browser (profile=clawd)
-```
-Open: https://rive.app/marketplace/search/{keyword}/
-```
-
-### 2. Get Post ID from URL
-Item URL format: `/marketplace/{post_id}-{revision_id}-{slug}/`
-Example: `/marketplace/1683-3324-like-button/` → post_id = **1683**
-
-### 3. Fetch Download URL via API
-```bash
-curl -s "https://api.rive.app/api/community-posts/1683" | jq -r '.community_revisions[0].community_files[0].file_url'
-# Output: https://public.rive.app/community/runtime-files/1683-3324-like-button.riv
-```
-
-### 4. Download File
-```bash
-curl -O "https://public.rive.app/community/runtime-files/1683-3324-like-button.riv"
-```
-
-## Example: Full Flow
-
-```bash
-# Search for "button" assets, pick one, get post_id from URL
-POST_ID=1683
-
-# Get file URL
-FILE_URL=$(curl -s "https://api.rive.app/api/community-posts/$POST_ID" | jq -r '.community_revisions[0].community_files[0].file_url')
-
-# Download
-curl -o "my-button.riv" "$FILE_URL"
-```
-
-## Batch Download Script
-
-```bash
-#!/bin/bash
-# Download multiple Rive assets by post IDs
-for POST_ID in 1683 3548 3703; do
-  FILE_URL=$(curl -s "https://api.rive.app/api/community-posts/$POST_ID" | jq -r '.community_revisions[0].community_files[0].file_url')
-  FILENAME=$(basename "$FILE_URL")
-  echo "Downloading $FILENAME..."
-  curl -sO "$FILE_URL"
-done
-```
-
-## License
-
-All Marketplace files are shared under **CC BY** (Creative Commons Attribution 4.0).
-Attribution required when using assets.
-
-## Notes
-
-- No official search API; browse via browser or scrape search results
-- API is public but undocumented; may change without notice
-- Remix/Like/Comment requires authentication

package/tools/__tests__/_cli-error.test.ts

@@ -1,35 +0,0 @@
-import { extractCliErrorMessage } from '../_cli-error'
-
-// bricks-project's tsconfig has no @types/jest, so declare the globals this test
-// uses (mirrors tools/mcp-tools/__tests__/huggingface.test.ts).
-declare const describe: (name: string, fn: () => void) => void
-declare const it: (name: string, fn: () => void) => void
-declare const expect: (actual: unknown) => { toBe: (expected: unknown) => void }
-
-describe('extractCliErrorMessage', () => {
-  // Regression: the tools used to build this message inside the same try that
-  // wrapped JSON.parse, so the throw was caught by its own catch and replaced
-  // with the raw JSON blob. The human-readable message must survive.
-  it('extracts error.message from a JSON error body', () => {
-    const output = JSON.stringify({ error: { message: 'Conflict: config was modified' } })
-    expect(extractCliErrorMessage(output, 'Update failed')).toBe('Conflict: config was modified')
-  })
-
-  it('extracts a string error from a JSON error body', () => {
-    expect(extractCliErrorMessage('{"error":"Boom"}', 'Pull failed')).toBe('Boom')
-  })
-
-  it('returns the raw output when it is not JSON', () => {
-    expect(extractCliErrorMessage('plain text failure', 'Release failed')).toBe(
-      'plain text failure',
-    )
-  })
-
-  it('falls back to the raw output when the JSON has no error field', () => {
-    expect(extractCliErrorMessage('{"ok":true}', 'Update failed')).toBe('{"ok":true}')
-  })
-
-  it('falls back to the generic message when output is empty', () => {
-    expect(extractCliErrorMessage('', 'Update failed')).toBe('Update failed')
-  })
-})

package/tools/__tests__/_mcp-config.test.ts

@@ -1,67 +0,0 @@
-import { mkdtemp, readFile, writeFile, rm } from 'fs/promises'
-import { tmpdir } from 'os'
-import * as path from 'path'
-import { handleMcpConfigOverride } from '../_mcp-config'
-
-// bricks-project's tsconfig has no @types/jest, so declare the globals this test uses
-// (mirrors tools/__tests__/_cli-error.test.ts).
-declare const describe: (name: string, fn: () => void) => void
-declare const it: (name: string, fn: () => void | Promise<void>) => void
-declare const expect: (actual: unknown) => {
-  toBe: (expected: unknown) => void
-  toEqual: (expected: unknown) => void
-}
-
-const projectMcpServer = { command: 'bun', args: ['mcp-server.ts'] }
-
-const withTempMcp = async (contents: string | null, fn: (p: string) => Promise<void>) => {
-  const dir = await mkdtemp(path.join(tmpdir(), 'bf-mcp-'))
-  const mcpPath = path.join(dir, '.mcp.json')
-  if (contents !== null) await writeFile(mcpPath, contents)
-  try {
-    await fn(mcpPath)
-  } finally {
-    await rm(dir, { recursive: true, force: true })
-  }
-}
-
-describe('handleMcpConfigOverride', () => {
-  it('injects bricks-ctor while preserving the user other servers', async () => {
-    await withTempMcp(
-      JSON.stringify({ mcpServers: { smartbear: { command: 'npx' } } }),
-      async (p) => {
-        await handleMcpConfigOverride(p, projectMcpServer)
-        const result = JSON.parse(await readFile(p, 'utf-8'))
-        expect(result.mcpServers.smartbear).toEqual({ command: 'npx' })
-        expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
-      },
-    )
-  })
-
-  it('does not clobber a malformed .mcp.json (regression: user servers were wiped)', async () => {
-    // trailing comma -> JSON.parse throws; the whole file used to be overwritten with the
-    // default, silently deleting every other configured server.
-    const malformed = '{ "mcpServers": { "smartbear": { "command": "npx" }, } }'
-    await withTempMcp(malformed, async (p) => {
-      await handleMcpConfigOverride(p, projectMcpServer)
-      expect(await readFile(p, 'utf-8')).toBe(malformed)
-    })
-  })
-
-  it('backfills mcpServers when missing without dropping other top-level keys', async () => {
-    await withTempMcp(JSON.stringify({ otherKey: 'keep-me' }), async (p) => {
-      await handleMcpConfigOverride(p, projectMcpServer)
-      const result = JSON.parse(await readFile(p, 'utf-8'))
-      expect(result.otherKey).toBe('keep-me')
-      expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
-    })
-  })
-
-  it('writes a default config when no .mcp.json exists', async () => {
-    await withTempMcp(null, async (p) => {
-      await handleMcpConfigOverride(p, projectMcpServer)
-      const result = JSON.parse(await readFile(p, 'utf-8'))
-      expect(result.mcpServers['bricks-ctor']).toEqual(projectMcpServer)
-    })
-  })
-})

package/tools/__tests__/pull.test.ts

@@ -1,108 +0,0 @@
-import { execFile as execFileCallback } from 'node:child_process'
-import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { promisify } from 'node:util'
-
-// bricks-project's tsconfig has no @types/jest, so declare the globals this test uses
-// (mirrors tools/__tests__/_mcp-config.test.ts).
-declare const describe: (name: string, fn: () => void) => void
-declare const it: (name: string, fn: () => void | Promise<void>, timeout?: number) => void
-declare const expect: (actual: unknown) => {
-  toBe: (expected: unknown) => void
-}
-
-const execFile = promisify(execFileCallback)
-
-async function run(cmd: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv) {
-  return execFile(cmd, args, {
-    cwd,
-    env: { ...process.env, ...env },
-    maxBuffer: 1024 * 1024,
-  })
-}
-
-async function initGitProject(projectDir: string) {
-  await run('git', ['init', '--initial-branch=master'], projectDir)
-  await run('git', ['config', 'user.email', 'test@example.com'], projectDir)
-  await run('git', ['config', 'user.name', 'Test User'], projectDir)
-  await writeFile(join(projectDir, 'application.json'), JSON.stringify({ id: 'app-1' }))
-  await run('git', ['add', '.'], projectDir)
-  await run('git', ['commit', '-m', 'init'], projectDir)
-}
-
-async function writeFakeBricks(binDir: string) {
-  const payload = {
-    files: [
-      {
-        name: 'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
-        input: 'export const value = 1\n',
-        formatable: false,
-      },
-    ],
-    lastCommitId: 'server-commit',
-  }
-  const bricksPath = join(binDir, 'bricks')
-  await writeFile(
-    bricksPath,
-    `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(JSON.stringify(payload))})\n`,
-  )
-  await chmod(bricksPath, 0o755)
-}
-
-describe('pull.ts', () => {
-  it('creates parent directories before writing pulled project files', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'bricks-project-pull-'))
-    const projectDir = join(root, 'project')
-    const binDir = join(root, 'bin')
-
-    try {
-      await mkdir(projectDir)
-      await mkdir(binDir)
-      await initGitProject(projectDir)
-      await writeFakeBricks(binDir)
-
-      const pullScript = resolve(__dirname, '../pull.ts')
-      await run('bun', [pullScript, '--force'], projectDir, {
-        PATH: `${binDir}:${process.env.PATH || ''}`,
-      })
-
-      const pulledFile = join(
-        projectDir,
-        'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
-      )
-      expect(await readFile(pulledFile, 'utf8')).toBe('export const value = 1\n')
-    } finally {
-      await rm(root, { recursive: true, force: true })
-    }
-  }, 30000)
-
-  it('merges pulled project files back into the starting branch', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'bricks-project-pull-'))
-    const projectDir = join(root, 'project')
-    const binDir = join(root, 'bin')
-
-    try {
-      await mkdir(projectDir)
-      await mkdir(binDir)
-      await initGitProject(projectDir)
-      await writeFakeBricks(binDir)
-
-      const pullScript = resolve(__dirname, '../pull.ts')
-      await run('bun', [pullScript], projectDir, {
-        PATH: `${binDir}:${process.env.PATH || ''}`,
-      })
-
-      const { stdout: branch } = await run('git', ['branch', '--show-current'], projectDir)
-      const pulledFile = join(
-        projectDir,
-        'subspaces/subspace-13/data-calc/data-calculation-0.sandbox.js',
-      )
-
-      expect(branch.trim()).toBe('master')
-      expect(await readFile(pulledFile, 'utf8')).toBe('export const value = 1\n')
-    } finally {
-      await rm(root, { recursive: true, force: true })
-    }
-  }, 30000)
-})

package/tools/_cli-error.ts

@@ -1,17 +0,0 @@
-// Extract a human-readable message from a `bricks ... --json` failure payload.
-//
-// On failure the CLI prints `{ "error": { "message": "..." } }` (or the older
-// `{ "error": "..." }`) to stdout/stderr. Earlier call sites built that message
-// inside the same `try` that wrapped `JSON.parse`, so the `throw` was caught by
-// its own `catch` and replaced with the raw JSON blob — the human-readable
-// message never surfaced. Parsing here, outside any throw, avoids that trap.
-export function extractCliErrorMessage(output: string, fallback: string): string {
-  try {
-    const { error } = JSON.parse(output)
-    const message = error?.message ?? error
-    if (typeof message === 'string' && message) return message
-  } catch {
-    // output is not JSON — fall through to the raw output below
-  }
-  return output || fallback
-}

package/tools/_edits-log.ts

@@ -1,41 +0,0 @@
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
-import path from 'node:path'
-
-const auditLogIgnoreEntry = '.bricks/edits.jsonl'
-
-// Ensure the project's .gitignore excludes the audit log. No-op when it is already
-// ignored directly or via a broader `.bricks` rule.
-const ensureAuditLogIgnored = async (projectDir: string) => {
-  const gitignorePath = path.join(projectDir, '.gitignore')
-  const content = await readFile(gitignorePath, 'utf8').catch((err: any) => {
-    if (err?.code === 'ENOENT') return ''
-    throw err
-  })
-  const ignored = content
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .some((line) => line === auditLogIgnoreEntry || line === '.bricks/' || line === '.bricks')
-  if (ignored) return
-
-  const prefix = content && !content.endsWith('\n') ? '\n' : ''
-  await writeFile(
-    gitignorePath,
-    `${content}${prefix}\n# MCP entry-editing audit log\n${auditLogIgnoreEntry}\n`,
-  )
-}
-
-// Append one JSON record to `.bricks/edits.jsonl`, creating the directory and the
-// gitignore entry as needed. Shared by the source-editing tools and `compile()` so
-// every project mutation lands in the same audit log.
-export const appendEditRecord = async (projectDir: string, record: Record<string, unknown>) => {
-  const bricksDir = path.join(projectDir, '.bricks')
-  await mkdir(bricksDir, { recursive: true })
-  await ensureAuditLogIgnored(projectDir)
-  await appendFile(path.join(bricksDir, 'edits.jsonl'), `${JSON.stringify(record)}\n`)
-}
-
-// Provenance stamped on every audit record: which agent/session produced the change.
-export const editProvenance = () => ({
-  session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
-  agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
-})

package/tools/_git-author.ts

@@ -1,37 +0,0 @@
-import { sh } from './_shell'
-
-const CTOR_NAME = 'CTOR'
-const CTOR_EMAIL = 'ctor@bricks.tools'
-const CTOR_COAUTHOR_TRAILER = `Co-authored-by: ${CTOR_NAME} <${CTOR_EMAIL}>`
-
-async function hasGitIdentity(cwd: string): Promise<boolean> {
-  const out = (await sh`cd ${cwd} && git config user.email`.quiet().nothrow().text()).trim()
-  return !!out
-}
-
-// Build `git ...` args for a commit attributed to CTOR.
-// If the machine has a git identity configured (any config level), the user
-// remains the main author and CTOR is added via a Co-authored-by trailer.
-// If no identity is configured (typical for non-tech users), CTOR becomes the
-// main author via per-command `-c user.name/-c user.email` overrides so the
-// user's git config is left untouched.
-//
-// `extraFlags` are inserted between `commit` and the `-m` args (e.g.
-// `['--no-verify']` to bypass pre-commit hooks for controlled cases like
-// committing merge-conflict markers).
-export async function buildCommitArgs(
-  cwd: string,
-  messages: string[],
-  extraFlags: string[] = [],
-): Promise<string[]> {
-  const hasIdentity = await hasGitIdentity(cwd)
-  const prefix = hasIdentity
-    ? []
-    : ['-c', `user.name=${CTOR_NAME}`, '-c', `user.email=${CTOR_EMAIL}`]
-  const msgArgs: string[] = []
-  for (const m of messages) msgArgs.push('-m', m)
-  if (hasIdentity) msgArgs.push('-m', CTOR_COAUTHOR_TRAILER)
-  return [...prefix, 'commit', ...extraFlags, ...msgArgs]
-}
-
-export { CTOR_NAME, CTOR_EMAIL, CTOR_COAUTHOR_TRAILER }