@fugood/bricks-ctor 2.25.0-beta.23 → 2.25.0-beta.24

package/compile/__tests__/util.test.js

@@ -243,14 +243,14 @@ describe('generateCalulationMap', () => {
     expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBeUndefined()
   })
 
-  test('snapshotMode forwards to makeId so generated ids are sequential', () => {
+  test('snapshotMode forwards to makeId so generated ids are deterministic v4 uuids', () => {
     const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo' } }), {
       snapshotMode: true,
     })
     const sandboxIds = sandboxNodeIds(result.map).map((s) => s.id)
-    // Snapshot-mode ids embed a 12-digit counter — stable suffix lets us assert order.
+    const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}'
     sandboxIds.forEach((id) => {
-      expect(id).toMatch(/^PROPERTY_BANK_COMMAND_NODE_00000000-0000-0000-0000-\d{12}$/)
+      expect(id).toMatch(new RegExp(`^PROPERTY_BANK_COMMAND_NODE_${uuid}$`))
     })
   })
 

package/compile/index.ts

@@ -1460,5 +1460,7 @@ export const compile = async (app: Application) => {
 
 export const checkConfig = async (configPath: string) => {
   const { sh } = await import('../tools/_shell')
-  await sh`bricks app check-config ${configPath}`
+  // --validate-automation surfaces broken automation_map / test_map refs early,
+  // which catches agent-authored automations that reference deleted bricks.
+  await sh`bricks app check-config --validate-automation ${configPath}`
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.23",
+  "version": "2.25.0-beta.24",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.25.0-beta.21",
+    "@fugood/bricks-cli": "^2.25.0-beta.24",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -25,5 +25,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "8b167250b57c5e9973e60de8266b880d15adcce6"
+  "gitHead": "529cad1e3d46ef2fbff4c8aaf759eec3d8ca289e"
 }

package/skills/bricks-ctor/rules/automations.md

@@ -118,6 +118,16 @@ const testLoginFlow: AutomationTest = {
 | `match_screenshot`           | `[name, threshold?, maxRetry?]`                  | Screenshot compare   |
 | `delay`                      | `[subspace?, property?, defaultValue?]`          | Delay execution      |
 
+In project TypeScript source, pass entity getters for BRICKS entities:
+
+```typescript
+run: ['brick_press', () => mainSubspace, () => bricks.bSubmitButton]
+run: ['wait_until_canvas_change', () => mainSubspace, () => canvases.cDone, 5000]
+run: ['assert_property', () => mainSubspace, () => data.dStep, 'done']
+```
+
+The compiler resolves these getters to the current generated IDs.
+
 ### execute_action Params
 
 The `params` object in `execute_action` uses **runtime event property keys** from `event-props.ts`, NOT the action config `input` names from type definitions.
@@ -208,6 +218,7 @@ Automations work with Modules. Use Manual Run in Preview mode for module testing
 
 - **Automation map key**: Always use `'AUTOMATION_MAP_DEFAULT'` as the automation map ID (not `makeId()`). The preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
 - **Valid makeId types**: Use `'test'` for AutomationTest, `'test_case'` for TestCase, `'test_var'` for TestVariable. Do NOT use `'automation_test'` or `'automation_test_map'`.
+- **Entity references in run arrays**: Use getter references (`() => subspace`, `() => bricks.bButton`, `() => data.dValue`) in TypeScript source so compile resolves fresh IDs.
 - **handler in execute_action**: Pass the entity's `.id` string (e.g., `bricks.bInput.id`), not a getter function.
 
 ## Best Practices

package/utils/__tests__/id.test.js

@@ -1,8 +1,24 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { makeId } from '../id'
 
-const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}'
 const UUID_ONLY_RE = new RegExp(`^${UUID}$`)
 
+const withProjectDir = (app, fn) => {
+  const previousCwd = process.cwd()
+  const dir = mkdtempSync(join(tmpdir(), 'make-id-'))
+  try {
+    if (app) writeFileSync(join(dir, 'application.json'), JSON.stringify(app))
+    process.chdir(dir)
+    return fn()
+  } finally {
+    process.chdir(previousCwd)
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
 describe('makeId', () => {
   describe('type prefixes', () => {
     const cases = [
@@ -25,8 +41,23 @@ describe('makeId', () => {
       expect(makeId(type)).toMatch(new RegExp(`^${prefix}${UUID}$`))
     })
 
-    test('returns unique random uuids across calls', () => {
-      expect(makeId('brick')).not.toBe(makeId('brick'))
+    test('uses generated count fallback when no alias is provided', () => {
+      const first = withProjectDir({ id: 'count-fallback-app' }, () => {
+        jest.resetModules()
+        const { makeId: makeFreshId } = require('../id')
+        return [makeFreshId('brick'), makeFreshId('brick')]
+      })
+      const second = withProjectDir({ id: 'count-fallback-app' }, () => {
+        jest.resetModules()
+        const { makeId: makeFreshId } = require('../id')
+        return [makeFreshId('brick'), makeFreshId('brick')]
+      })
+
+      expect(first[0]).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      expect(first[1]).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      expect(first[0]).not.toBe(first[1])
+      expect(second).toEqual(first)
+      jest.resetModules()
     })
 
     test('unknown type falls through to an unprefixed uuid', () => {
@@ -41,18 +72,83 @@ describe('makeId', () => {
   })
 
   describe('snapshotMode', () => {
-    test('produces sequential, deterministic uuids', () => {
-      const a = makeId('brick', { snapshotMode: true })
-      const b = makeId('brick', { snapshotMode: true })
-      expect(a).toMatch(/^BRICK_00000000-0000-0000-0000-\d{12}$/)
-      expect(b).toMatch(/^BRICK_00000000-0000-0000-0000-\d{12}$/)
-      expect(Number(b.slice(-12))).toBe(Number(a.slice(-12)) + 1)
+    test('produces deterministic v4 uuids from the generated count', () => {
+      const previousCwd = process.cwd()
+      const dir = mkdtempSync(join(tmpdir(), 'make-id-snapshot-'))
+      writeFileSync(join(dir, 'application.json'), JSON.stringify({ id: 'snapshot-app' }))
+      try {
+        process.chdir(dir)
+        jest.resetModules()
+        const { makeId: makeFreshId } = require('../id')
+        const a = makeFreshId('brick', { snapshotMode: true })
+        const b = makeFreshId('brick', { snapshotMode: true })
+
+        jest.resetModules()
+        const { makeId: makeFreshIdAgain } = require('../id')
+        expect(makeFreshIdAgain('brick', { snapshotMode: true })).toBe(a)
+        expect(makeFreshIdAgain('brick', { snapshotMode: true })).toBe(b)
+        expect(a).not.toBe(b)
+        expect(a).toMatch(new RegExp(`^BRICK_${UUID}$`))
+        expect(b).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      } finally {
+        process.chdir(previousCwd)
+        rmSync(dir, { recursive: true, force: true })
+        jest.resetModules()
+      }
     })
 
     test('snapshotMode false falls back to random uuid', () => {
       const id = makeId('canvas', { snapshotMode: false })
       expect(id).toMatch(new RegExp(`^CANVAS_${UUID}$`))
-      expect(id).not.toMatch(/CANVAS_00000000-0000-0000-0000-/)
+    })
+  })
+
+  describe('stable aliases', () => {
+    test('produces the same id for the same application id, type, and alias', () => {
+      const first = withProjectDir({ id: 'stable-app' }, () => {
+        jest.resetModules()
+        return require('../id').makeId('brick', 'stable-hero')
+      })
+      const second = withProjectDir({ id: 'stable-app' }, () => {
+        jest.resetModules()
+        return require('../id').makeId('brick', 'stable-hero')
+      })
+
+      expect(second).toBe(first)
+      expect(first).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      jest.resetModules()
+    })
+
+    test('uses the application id when hashing stable aliases', () => {
+      const idA = withProjectDir({ id: 'app-a' }, () => makeId('brick', 'hero'))
+      const idB = withProjectDir({ id: 'app-b' }, () => makeId('brick', 'hero'))
+
+      expect(idA).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      expect(idB).toMatch(new RegExp(`^BRICK_${UUID}$`))
+      expect(idA).not.toBe(idB)
+    })
+
+    test('rejects duplicate aliases for the same application id and entry type', () => {
+      withProjectDir({ id: 'duplicate-app' }, () => {
+        expect(makeId('brick', 'shared')).toMatch(new RegExp(`^BRICK_${UUID}$`))
+        expect(() => makeId('brick', 'shared')).toThrow(/Duplicate makeId alias 'shared'/)
+      })
+    })
+
+    test('allows the same alias for different entry types', () => {
+      withProjectDir({ id: 'shared-alias-app' }, () => {
+        const brick = makeId('brick', 'shared')
+        const canvas = makeId('canvas', 'shared')
+
+        expect(brick).toMatch(new RegExp(`^BRICK_${UUID}$`))
+        expect(canvas).toMatch(new RegExp(`^CANVAS_${UUID}$`))
+        expect(brick).not.toBe(canvas)
+      })
+    })
+
+    test('falls back when application.json is not present', () => {
+      const id = withProjectDir(null, () => makeId('brick', 'fallback-app-id'))
+      expect(id).toMatch(new RegExp(`^BRICK_${UUID}$`))
     })
   })
 })

package/utils/id.ts

@@ -1,38 +1,83 @@
 import { v4 as uuid } from 'uuid'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 let count = 0
 
-// Used for snapshot mode
-const countUUID = () => {
-  const current = count
-  count += 1
-  return `00000000-0000-0000-0000-${current.toString().padStart(12, '0')}`
+type IdType =
+  | 'animation'
+  | 'brick'
+  | 'canvas'
+  | 'generator'
+  | 'data'
+  | 'switch'
+  | 'property_bank_command'
+  | 'property_bank_calc'
+  | 'dynamic-brick'
+  | 'automation_map'
+  | 'test'
+  | 'test_case'
+  | 'test_var'
+  | 'subspace'
+
+type IdOptions = {
+  snapshotMode?: boolean
+}
+
+const APPLICATION_ID_FALLBACK = 'unknown-application'
+
+const usedStableAliases = new Set<string>()
+let applicationIdCache: { cwd: string; id: string } | null = null
+
+const readApplicationId = () => {
+  const cwd = process.cwd()
+  if (applicationIdCache?.cwd === cwd) return applicationIdCache.id
+
+  let id = APPLICATION_ID_FALLBACK
+  try {
+    const app = JSON.parse(readFileSync(join(cwd, 'application.json'), 'utf8'))
+    if (typeof app.id === 'string' && app.id) id = app.id
+  } catch {
+    // `makeId` is also used from tests and utilities outside project roots.
+  }
+
+  applicationIdCache = { cwd, id }
+  return id
+}
+
+const hashToRandomBytes = (parts: string[]) => {
+  const hash = createHash('sha256').update(JSON.stringify(parts)).digest()
+  return new Uint8Array(hash.subarray(0, 16))
 }
 
-// Make a random id if not want to use fixed id
-export const makeId = (
-  type:
-    | 'animation'
-    | 'brick'
-    | 'canvas'
-    | 'generator'
-    | 'data'
-    | 'switch'
-    | 'property_bank_command'
-    | 'property_bank_calc'
-    | 'dynamic-brick'
-    | 'automation_map'
-    | 'test'
-    | 'test_case'
-    | 'test_var'
-    | 'subspace',
-  opts?: {
-    snapshotMode?: boolean
-  },
-) => {
+const makeStableUuid = (type: string, alias?: string) => {
+  const applicationId = readApplicationId()
+  const seed = alias ?? String(count)
+  if (alias === undefined) count += 1
+
+  if (alias !== undefined) {
+    const aliasKey = JSON.stringify([applicationId, type, alias])
+    if (usedStableAliases.has(aliasKey)) {
+      throw new Error(`Duplicate makeId alias '${alias}' for type '${type}'`)
+    }
+    usedStableAliases.add(aliasKey)
+  }
+
+  return uuid({
+    random: hashToRandomBytes([applicationId, type, seed]),
+  })
+}
+
+// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
+export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
   if (type === 'subspace') {
     throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
   }
+
+  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
+  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
+
   let prefix = ''
   switch (type) {
     case 'animation':
@@ -76,5 +121,11 @@ export const makeId = (
       break
     default:
   }
-  return `${prefix}${opts?.snapshotMode ? countUUID() : uuid()}`
+
+  const useCountFallback = aliasOrOpts === undefined && opts === undefined
+  const id =
+    alias !== undefined || options?.snapshotMode || useCountFallback
+      ? makeStableUuid(type, alias)
+      : uuid()
+  return `${prefix}${id}`
 }