@fugood/bricks-ctor 2.25.0-beta.47 → 2.25.0-beta.49

package/compile/__tests__/index.test.js

@@ -1,7 +1,14 @@
 jest.mock('../../tools/_shell', () => ({
-  sh: jest.fn(() => Promise.resolve({})),
+  sh: jest.fn(),
 }))
 
+// Mirrors the chainable `sh` result (supports `.nothrow()` like the real helper).
+const shResult = (over = {}) => {
+  const result = Promise.resolve({ exitCode: 0, stdout: '', stderr: '', ...over })
+  result.nothrow = () => result
+  return result
+}
+
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
@@ -57,7 +64,8 @@ const commandOf = ([strings, ...values]) =>
 
 describe('checkConfig', () => {
   beforeEach(() => {
-    sh.mockClear()
+    sh.mockReset()
+    sh.mockImplementation(() => shResult())
   })
 
   test('runs doctor after check-config', async () => {
@@ -68,6 +76,20 @@ describe('checkConfig', () => {
       'bricks app doctor --validate-automation .bricks/build/application-config.json',
     ])
   })
+
+  test('skips doctor when the CLI lacks the command', async () => {
+    sh.mockReturnValueOnce(shResult()) // check-config
+    sh.mockReturnValueOnce(shResult({ exitCode: 1, stderr: "error: unknown command 'doctor'" }))
+
+    await expect(checkConfig('config.json')).resolves.toBeUndefined()
+  })
+
+  test('throws when doctor reports config errors', async () => {
+    sh.mockReturnValueOnce(shResult()) // check-config
+    sh.mockReturnValueOnce(shResult({ exitCode: 1, stderr: 'DATA_RACE: conflicting writes' }))
+
+    await expect(checkConfig('config.json')).rejects.toThrow()
+  })
 })
 
 describe('compile animations', () => {

package/compile/index.ts

@@ -1494,6 +1494,11 @@ export const checkConfig = async (configPath: string) => {
   // which catches agent-authored automations that reference deleted bricks.
   await sh`bricks app check-config --validate-automation ${configPath}`
   // Doctor adds semantic lint checks after structural validation. Warnings are
-  // surfaced in the compile log, but only errors fail by default.
-  await sh`bricks app doctor --validate-automation ${configPath}`
+  // surfaced in the compile log, but only errors fail by default. Older published
+  // bricks-cli builds lack `app doctor` — skip rather than fail the compile.
+  const doctor = await sh`bricks app doctor --validate-automation ${configPath}`.nothrow()
+  if (doctor.exitCode !== 0) {
+    if (/unknown command/i.test(doctor.stderr?.toString() ?? '')) return
+    throw new Error(`bricks app doctor failed with exit ${doctor.exitCode}`)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.47",
+  "version": "2.25.0-beta.49",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -11,7 +11,7 @@
     "@babel/parser": "7.28.5",
     "@babel/traverse": "7.28.5",
     "@babel/types": "7.28.5",
-    "@fugood/bricks-cli": "^2.25.0-beta.46",
+    "@fugood/bricks-cli": "^2.25.0-beta.49",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -29,5 +29,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "95f194a3fb6331c0f25a879e55675e3ff331a412"
+  "gitHead": "e7da261fd97feda0ee059ff04070f0068cad9d29"
 }

package/skills/bricks-ctor/references/verification-toolchain.md

@@ -122,6 +122,25 @@ Once DevTools is on, ask the user how they want to drive the verification — Ch
 
 For agent-driven CDP/MCP work against the device (`bricks devtools …` with `-a <ip> --passcode <pc>`, plus bridging the device MCP endpoint into an MCP client), the same `bricks-cli` skill referenced in Path 1 covers the on-device case — read it if installed. If not installed, run `bricks --help` and `bricks devtools --help` for the authoritative command listing.
 
+### Running real-device Automations from an agent
+
+There is no `bricks devtools automation` subcommand. Use the DevTools runtime helpers exposed inside the app:
+
+```bash
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "Object.getOwnPropertyNames(automation).sort()" -j
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "automation.list()" -j
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "automation.run('<TEST_id>', { updateScreenshot: false })" --await -j
+```
+
+`automation.run()` starts the device-side run and may return `null`; treat that as accepted, not as a pass/fail result. Wait for the run timeout/window, then verify completion through the app's own state and a screenshot. For app state, use live runtime reads such as:
+
+```bash
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "JSON.stringify({ result: system.data.property('<S_xxxx>', '<resultAlias>')?.value })" -j
+bricks devtools screenshot -a <ip> -p 19851 --passcode <pc> -o /tmp/device-automation.png
+```
+
+In CTOR Desktop sandboxed sessions, keep these as separate simple commands. Avoid multi-line shell scripts, `for` loops, brace expansion, and command substitution around `bricks devtools`; those can stay sandboxed and lose LAN/device access. After `bun update-app` or a device refresh, the DevTools socket may briefly drop, so wait and probe with one screenshot or one `runtime eval` before running the automation.
+
 ### Real-device side-effects warning
 
 Real devices fire real peripherals. Payment terminals charge. MQTT broadcasts on shared topics. BLE advertises to bystanders. Use a **staging** device for verification cycles; never iterate on a production-deployed device unless the user explicitly approves.

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

@@ -0,0 +1,35 @@
+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/_cli-error.ts

@@ -0,0 +1,17 @@
+// 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/deploy.ts

@@ -1,6 +1,7 @@
 import { access, readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -162,12 +163,7 @@ const result = await sh`${args}`.quiet().nothrow()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error || 'Release failed')
-  } catch {
-    throw new Error(output || 'Release failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Release failed'))
 }
 
 const output = JSON.parse(result.stdout.toString())

package/tools/mcp-tools/_editing-helpers.ts

@@ -0,0 +1,58 @@
+import * as t from '@babel/types'
+import path from 'node:path'
+
+export const oxfmtOptions = {
+  trailingComma: 'all',
+  tabWidth: 2,
+  semi: false,
+  singleQuote: true,
+  printWidth: 100,
+} as const
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+export const isIdentifierName = (value: string) => /^[$A-Z_a-z][$\w]*$/.test(value)
+
+export const normalizeRelPath = (file: string) => file.replace(/\\/g, '/').replace(/^\.\/+/, '')
+
+export const projectRelativePath = (projectDir: string, absPath: string) =>
+  normalizeRelPath(path.relative(projectDir, absPath))
+
+export const getPropertyKeyName = (key: t.Expression | t.PrivateName) => {
+  if (t.isIdentifier(key)) return key.name
+  if (t.isStringLiteral(key) || t.isNumericLiteral(key)) return String(key.value)
+  return null
+}
+
+export const makeObjectKey = (key: string) =>
+  isIdentifierName(key) ? t.identifier(key) : t.stringLiteral(key)
+
+export const getObjectProperty = (object: t.ObjectExpression, key: string) =>
+  object.properties.find((property): property is t.ObjectProperty => {
+    if (!t.isObjectProperty(property)) return false
+    return getPropertyKeyName(property.key) === key
+  })
+
+export const getStringProperty = (object: t.ObjectExpression, key: string) => {
+  const property = getObjectProperty(object, key)
+  if (!property || !t.isStringLiteral(property.value)) return undefined
+  return property.value.value
+}
+
+export const setObjectProperty = (object: t.ObjectExpression, key: string, value: t.Expression) => {
+  const existing = getObjectProperty(object, key)
+  if (existing) {
+    existing.value = value
+    return
+  }
+  object.properties.push(t.objectProperty(makeObjectKey(key), value))
+}
+
+export const removeObjectProperty = (object: t.ObjectExpression, key: string) => {
+  const index = object.properties.findIndex((property) => {
+    if (!t.isObjectProperty(property)) return false
+    return getPropertyKeyName(property.key) === key
+  })
+  if (index >= 0) object.properties.splice(index, 1)
+}

package/tools/mcp-tools/data-calc-editing.ts

@@ -9,18 +9,20 @@ import path from 'node:path'
 import { z } from 'zod'
 
 import { verifyProject } from './_verify'
+import {
+  getObjectProperty,
+  getStringProperty,
+  isRecord,
+  makeObjectKey,
+  oxfmtOptions,
+  projectRelativePath,
+  removeObjectProperty,
+  setObjectProperty,
+} from './_editing-helpers'
 import { appendEditRecord, editProvenance } from '../_edits-log'
 
 const generate = (generateModule as any).default || generateModule
 
-const oxfmtOptions = {
-  trailingComma: 'all',
-  tabWidth: 2,
-  semi: false,
-  singleQuote: true,
-  printWidth: 100,
-} as const
-
 type ParsedFile = {
   ast: t.File
   source: string
@@ -79,16 +81,6 @@ class DataCalcEditingError extends Error {
   }
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-
-const isIdentifierName = (value: string) => /^[$A-Z_a-z][$\w]*$/.test(value)
-
-const normalizeRelPath = (file: string) => file.replace(/\\/g, '/').replace(/^\.\/+/, '')
-
-const projectRelativePath = (projectDir: string, absPath: string) =>
-  normalizeRelPath(path.relative(projectDir, absPath))
-
 const resolveProjectPath = (projectDir: string, file: string) => {
   if (path.isAbsolute(file)) {
     throw new DataCalcEditingError('invalid_file', 'File must be project-relative', { file })
@@ -132,44 +124,6 @@ const readParsedFile = async (projectDir: string, absPath: string): Promise<Pars
   }
 }
 
-const getPropertyKeyName = (key: t.Expression | t.PrivateName) => {
-  if (t.isIdentifier(key)) return key.name
-  if (t.isStringLiteral(key) || t.isNumericLiteral(key)) return String(key.value)
-  return null
-}
-
-const makeObjectKey = (key: string) =>
-  isIdentifierName(key) ? t.identifier(key) : t.stringLiteral(key)
-
-const getObjectProperty = (object: t.ObjectExpression, key: string) =>
-  object.properties.find((property): property is t.ObjectProperty => {
-    if (!t.isObjectProperty(property)) return false
-    return getPropertyKeyName(property.key) === key
-  })
-
-const getStringProperty = (object: t.ObjectExpression, key: string) => {
-  const property = getObjectProperty(object, key)
-  if (!property || !t.isStringLiteral(property.value)) return undefined
-  return property.value.value
-}
-
-const setObjectProperty = (object: t.ObjectExpression, key: string, value: t.Expression) => {
-  const existing = getObjectProperty(object, key)
-  if (existing) {
-    existing.value = value
-    return
-  }
-  object.properties.push(t.objectProperty(makeObjectKey(key), value))
-}
-
-const removeObjectProperty = (object: t.ObjectExpression, key: string) => {
-  const index = object.properties.findIndex((property) => {
-    if (!t.isObjectProperty(property)) return false
-    return getPropertyKeyName(property.key) === key
-  })
-  if (index >= 0) object.properties.splice(index, 1)
-}
-
 const getExportEntries = (ast: t.File): ExportEntry[] =>
   ast.program.body.flatMap((statement) => {
     if (!t.isExportNamedDeclaration(statement)) return []

package/tools/mcp-tools/entry-editing.ts

@@ -10,19 +10,22 @@ import path from 'node:path'
 import { z } from 'zod'
 
 import { verifyProject } from './_verify'
+import {
+  getObjectProperty,
+  getPropertyKeyName,
+  getStringProperty,
+  isRecord,
+  makeObjectKey,
+  oxfmtOptions,
+  projectRelativePath,
+  removeObjectProperty,
+  setObjectProperty,
+} from './_editing-helpers'
 import { appendEditRecord, editProvenance } from '../_edits-log'
 
 const generate = (generateModule as any).default || generateModule
 const traverse = (traverseModule as any).default || traverseModule
 
-const oxfmtOptions = {
-  trailingComma: 'all',
-  tabWidth: 2,
-  semi: false,
-  singleQuote: true,
-  printWidth: 100,
-} as const
-
 const entryKinds = {
   'bricks.ts': {
     kind: 'brick',
@@ -129,16 +132,6 @@ class EntryEditingError extends Error {
   }
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-
-const isIdentifierName = (value: string) => /^[$A-Z_a-z][$\w]*$/.test(value)
-
-const normalizeRelPath = (file: string) => file.replace(/\\/g, '/').replace(/^\.\/+/, '')
-
-const projectRelativePath = (projectDir: string, absPath: string) =>
-  normalizeRelPath(path.relative(projectDir, absPath))
-
 const resolveProjectPath = (projectDir: string, file: string) => {
   if (path.isAbsolute(file)) {
     throw new EntryEditingError('invalid_file', 'File must be project-relative', { file })
@@ -195,44 +188,6 @@ const readParsedFile = async (projectDir: string, absPath: string): Promise<Pars
   }
 }
 
-const getPropertyKeyName = (key: t.Expression | t.PrivateName) => {
-  if (t.isIdentifier(key)) return key.name
-  if (t.isStringLiteral(key) || t.isNumericLiteral(key)) return String(key.value)
-  return null
-}
-
-const makeObjectKey = (key: string) =>
-  isIdentifierName(key) ? t.identifier(key) : t.stringLiteral(key)
-
-const getObjectProperty = (object: t.ObjectExpression, key: string) =>
-  object.properties.find((property): property is t.ObjectProperty => {
-    if (!t.isObjectProperty(property)) return false
-    return getPropertyKeyName(property.key) === key
-  })
-
-const getStringProperty = (object: t.ObjectExpression, key: string) => {
-  const property = getObjectProperty(object, key)
-  if (!property || !t.isStringLiteral(property.value)) return undefined
-  return property.value.value
-}
-
-const setObjectProperty = (object: t.ObjectExpression, key: string, value: t.Expression) => {
-  const existing = getObjectProperty(object, key)
-  if (existing) {
-    existing.value = value
-    return
-  }
-  object.properties.push(t.objectProperty(makeObjectKey(key), value))
-}
-
-const removeObjectProperty = (object: t.ObjectExpression, key: string) => {
-  const index = object.properties.findIndex((property) => {
-    if (!t.isObjectProperty(property)) return false
-    return getPropertyKeyName(property.key) === key
-  })
-  if (index >= 0) object.properties.splice(index, 1)
-}
-
 const getExportEntries = (ast: t.File): ExportEntry[] =>
   ast.program.body.flatMap((statement) => {
     if (!t.isExportNamedDeclaration(statement)) return []

package/tools/pull.ts

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { format } from 'oxfmt'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { readLastPushedCommit, writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -68,12 +69,7 @@ const result = await sh`bricks ${command} project-pull ${app.id} --json`.quiet()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error || 'Pull failed')
-  } catch {
-    throw new Error(output || 'Pull failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Pull failed'))
 }
 
 const { files, lastCommitId: serverLastCommitId } = JSON.parse(result.stdout.toString())

package/tools/push-config.ts

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -99,12 +100,7 @@ const result = await sh`${args}`.quiet().nothrow()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error?.message || json.error || 'Update failed')
-  } catch {
-    throw new Error(output || 'Update failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Update failed'))
 }
 
 const output = JSON.parse(result.stdout.toString())