@cat-factory/app 0.259.3 → 0.260.1

package/app/stores/board/placement.ts

@@ -207,10 +207,17 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     }
   }
 
-  /** Patch the user-editable fields of a block (title, features, threshold…). */
-  async function updateBlock(id: string, patch: UpdateBlockInput) {
+  /**
+   * Patch the user-editable fields of a block (title, features, threshold…).
+   *
+   * Returns whether the patch was PERSISTED. Both failure modes are already reported here (an
+   * unknown block is a no-op, a rejected write rolls back and toasts), so an inspector control
+   * firing and forgetting stays correct. A caller that goes on to ASSERT what the patch achieved
+   * must read it, or it announces links the rollback has just undone.
+   */
+  async function updateBlock(id: string, patch: UpdateBlockInput): Promise<boolean> {
     const b = getBlock(id)
-    if (!b) return
+    if (!b) return false
     // Snapshot ONLY the fields this patch touches so a rejected write restores them exactly
     // (a patch may set several at once) rather than leaving a stale optimistic value stuck on
     // screen with no feedback — the same rollback contract the other mutations here follow.
@@ -224,6 +231,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     Object.assign(b, patch) // optimistic
     try {
       upsert(await api.updateBlock(useWorkspaceStore().requireId(), id, patch))
+      return true
     } catch (e) {
       // Re-resolve the block: a live event may have replaced its object reference (`upsert`
       // swaps in a fresh one) while the write was in flight, so `b` can be stale. Only revert
@@ -242,6 +250,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
         icon: 'i-lucide-triangle-alert',
         color: 'error',
       })
+      return false
     }
   }
 

package/app/stores/board.spec.ts

@@ -256,12 +256,22 @@ describe('board store read getters', () => {
     s.hydrate([frame('f1', { title: 'Original', description: 'orig' })])
     // With no active workspace, `requireId()` throws inside updateBlock's try — the same catch
     // that a rejected API write hits — so this exercises the optimistic-rollback + toast path.
-    await s.updateBlock('f1', { title: 'Edited', description: 'changed' })
+    // The outcome is REPORTED to the caller, not only toasted: a caller that goes on to announce
+    // what the patch achieved (the monorepo import's frontend wiring) has to see the rollback.
+    await expect(s.updateBlock('f1', { title: 'Edited', description: 'changed' })).resolves.toBe(
+      false,
+    )
     expect(s.getBlock('f1')?.title).toBe('Original')
     expect(s.getBlock('f1')?.description).toBe('orig')
     expect(addSpy).toHaveBeenCalledWith(expect.objectContaining({ color: 'error' }))
   })
 
+  it('updateBlock reports a no-op for a block that is not on the board', async () => {
+    // Nothing is patched and nothing is toasted, so the return value is the ONLY signal that the
+    // write did not happen.
+    await expect(store.updateBlock('missing', { title: 'Edited' })).resolves.toBe(false)
+  })
+
   it('hydrate replaces and upsert inserts/updates cached blocks', () => {
     store.hydrate([frame('f1')])
     store.upsert(task('t1', 'f1', { title: 'first' }))
@@ -305,11 +315,21 @@ describe('board store optimistic rollback', () => {
     }))
     const store = useBoardStore()
     store.hydrate([frame('f1'), task('t1', 'f1', { title: 'orig', description: 'keep' })])
-    await store.updateBlock('t1', { title: 'renamed' })
+    await expect(store.updateBlock('t1', { title: 'renamed' })).resolves.toBe(false)
     expect(store.getBlock('t1')?.title).toBe('orig')
     expect(store.getBlock('t1')?.description).toBe('keep')
   })
 
+  it('updateBlock reports the patch persisted when the API accepts it', async () => {
+    vi.stubGlobal('useApi', () => ({
+      updateBlock: async () => task('t1', 'f1', { title: 'renamed' }),
+    }))
+    const store = useBoardStore()
+    store.hydrate([frame('f1'), task('t1', 'f1', { title: 'orig' })])
+    await expect(store.updateBlock('t1', { title: 'renamed' })).resolves.toBe(true)
+    expect(store.getBlock('t1')?.title).toBe('renamed')
+  })
+
   it('previewResize translates the children when the drag moves the content origin', () => {
     // A child's position is relative to its container's content origin, so growing the frame
     // 40px west (origin -40) has to move every direct child +40 or the whole content slides with

package/app/utils/edgeSegments.spec.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { shallowRef } from 'vue'
+import { commitSegments, sameSegments, type EdgeSegment } from './edgeSegments'
+
+const line = (over: Partial<EdgeSegment> = {}): EdgeSegment => ({
+  id: 'a__b',
+  x1: 0,
+  y1: 0,
+  x2: 10,
+  y2: 10,
+  ...over,
+})
+
+describe('sameSegments', () => {
+  it('accepts a freshly measured list that resolved to the same overlay', () => {
+    expect(sameSegments([line()], [line()])).toBe(true)
+  })
+
+  it('rejects a moved endpoint, however slightly', () => {
+    expect(sameSegments([line()], [line({ y2: 10.5 })])).toBe(false)
+  })
+
+  it('rejects a changed link set', () => {
+    expect(sameSegments([line()], [])).toBe(false)
+    expect(sameSegments([line()], [line({ id: 'a__c' })])).toBe(false)
+  })
+
+  it('rejects a dependency whose source finished, since it restyles the arrow', () => {
+    expect(sameSegments([line({ done: false })], [line({ done: true })])).toBe(false)
+  })
+})
+
+describe('commitSegments', () => {
+  it('publishes a changed list and reports it', () => {
+    const target = shallowRef<EdgeSegment[]>([line()])
+    const next = [line({ x2: 20 })]
+    expect(commitSegments(target, next)).toBe(true)
+    expect(target.value).toBe(next)
+  })
+
+  it('leaves the published array untouched when nothing moved', () => {
+    const published = [line()]
+    const target = shallowRef<EdgeSegment[]>(published)
+    // Identity has to survive, not just the values: reassigning an equal-but-new array is
+    // what re-rendered the whole overlay on every frame of an idle board.
+    expect(commitSegments(target, [line()])).toBe(false)
+    expect(target.value).toBe(published)
+  })
+})

package/app/utils/edgeSegments.ts

@@ -0,0 +1,49 @@
+import type { Ref } from 'vue'
+
+/**
+ * One drawable link on the board's screen-space overlay: a border-to-border line between two
+ * block cards. `done` rides only on dependency edges, where it picks the stroke and arrowhead.
+ */
+export type EdgeSegment = {
+  id: string
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+  done?: boolean
+}
+
+/** Whether two resolved segment lists would draw exactly the same overlay. */
+export function sameSegments(a: readonly EdgeSegment[], b: readonly EdgeSegment[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    const left = a[i]!
+    const right = b[i]!
+    if (
+      left.id !== right.id ||
+      left.x1 !== right.x1 ||
+      left.y1 !== right.y1 ||
+      left.x2 !== right.x2 ||
+      left.y2 !== right.y2 ||
+      left.done !== right.done
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Publish a freshly measured list, and report whether it moved anything. Writing an
+ * equal-but-new array every frame is what re-rendered the whole overlay 60 times a second on
+ * a board where nothing was moving, and it is also the signal the settling frame loop reads
+ * to decide it can park.
+ *
+ * The target is a `shallowRef`: the lists are replaced wholesale, so deep-proxying every
+ * segment object would be pure overhead.
+ */
+export function commitSegments(target: Ref<EdgeSegment[]>, next: EdgeSegment[]): boolean {
+  if (sameSegments(target.value, next)) return false
+  target.value = next
+  return true
+}

package/app/utils/monorepoImport.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import type { CreatedMonorepoFrame } from './monorepoImport'
+import {
+  canDesignateFrontend,
+  planFrontendConfigPatches,
+  planMonorepoImport,
+} from './monorepoImport'
+
+/** Pair a plan with block ids, the way the modal does as each create call returns. */
+function created(entries: ReturnType<typeof planMonorepoImport>): CreatedMonorepoFrame[] {
+  return entries.map((entry, i) => ({ blockId: `blk_${i}`, entry }))
+}
+
+describe('canDesignateFrontend', () => {
+  it('offers the mark for two or more backend services', () => {
+    expect(canDesignateFrontend('service', 2)).toBe(true)
+    expect(canDesignateFrontend('service', 5)).toBe(true)
+  })
+
+  it('withholds it below two directories: there is no rest to bind to', () => {
+    expect(canDesignateFrontend('service', 1)).toBe(false)
+    expect(canDesignateFrontend('service', 0)).toBe(false)
+  })
+
+  it('withholds it for roles a backend binding cannot point at', () => {
+    // A binding's `service` source names a `service` frame; a library/document frame is not one,
+    // and when everything is already a frontend the mark divides nothing.
+    expect(canDesignateFrontend('library', 3)).toBe(false)
+    expect(canDesignateFrontend('document', 3)).toBe(false)
+    expect(canDesignateFrontend('frontend', 3)).toBe(false)
+  })
+})
+
+describe('planMonorepoImport', () => {
+  it('creates the marked directory as a frontend and the rest with the picked role', () => {
+    expect(
+      planMonorepoImport(['apps/web', 'services/api', 'services/auth'], 'service', 'apps/web'),
+    ).toEqual([
+      { directory: 'apps/web', type: 'frontend', designatedFrontend: true },
+      { directory: 'services/api', type: 'service', designatedFrontend: false },
+      { directory: 'services/auth', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('keeps the picked order, wherever the marked directory sits in it', () => {
+    const plan = planMonorepoImport(['services/api', 'apps/web'], 'service', 'apps/web')
+    expect(plan.map((e) => e.directory)).toEqual(['services/api', 'apps/web'])
+    expect(plan[1]?.type).toBe('frontend')
+  })
+
+  it('gives every directory the picked role when nothing is marked', () => {
+    expect(planMonorepoImport(['a', 'b'], 'service', undefined)).toEqual([
+      { directory: 'a', type: 'service', designatedFrontend: false },
+      { directory: 'b', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('ignores a mark on a directory that is not being created', () => {
+    // The cart entry was removed (or was already on the board and got filtered out) after being
+    // marked. Designating nothing is right; promoting some other frame to frontend would not be.
+    expect(planMonorepoImport(['a', 'b'], 'service', 'apps/web')).toEqual([
+      { directory: 'a', type: 'service', designatedFrontend: false },
+      { directory: 'b', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('designates nobody when the whole cart is imported under the frontend role', () => {
+    // Every entry is `type: 'frontend'` here, so the flag is the ONLY thing that separates
+    // "the app the others talk to" from "a cart of frontends". A mark is never on offer for this
+    // role (`canDesignateFrontend`), and one carried over from a role change must not act.
+    const plan = planMonorepoImport(['apps/web', 'apps/admin'], 'frontend', 'apps/web')
+    expect(plan.every((e) => e.type === 'frontend')).toBe(true)
+    expect(plan.some((e) => e.designatedFrontend)).toBe(false)
+  })
+})
+
+describe('planFrontendConfigPatches', () => {
+  it('binds the designated frontend to every other frame created beside it', () => {
+    const plan = planMonorepoImport(
+      ['apps/web', 'services/api', 'services/auth'],
+      'service',
+      'apps/web',
+    )
+    expect(planFrontendConfigPatches(created(plan))).toEqual([
+      {
+        blockId: 'blk_0',
+        config: {
+          directory: 'apps/web',
+          backendBindings: [
+            { envVar: '', source: { kind: 'service', serviceBlockId: 'blk_1' } },
+            { envVar: '', source: { kind: 'service', serviceBlockId: 'blk_2' } },
+          ],
+        },
+      },
+    ])
+  })
+
+  it('leaves every env var name empty rather than inventing one', () => {
+    const plan = planMonorepoImport(['apps/web', 'services/api'], 'service', 'apps/web')
+    const [patch] = planFrontendConfigPatches(created(plan))
+    expect(patch?.config.backendBindings.every((b) => b.envVar === '')).toBe(true)
+  })
+
+  it('carries the subdirectory to every frontend frame, designated or not', () => {
+    // `frontendConfig.directory` is what the harness's install/build/serve reads; the service-level
+    // directory that scopes an agent's checkout is a different field and does not stand in. A cart
+    // imported under the `frontend` role has no designated frame, and every frame in it would
+    // otherwise build the repo root.
+    const plan = planMonorepoImport(['apps/web', 'apps/admin'], 'frontend', undefined)
+    expect(planFrontendConfigPatches(created(plan))).toEqual([
+      { blockId: 'blk_0', config: { directory: 'apps/web', backendBindings: [] } },
+      { blockId: 'blk_1', config: { directory: 'apps/admin', backendBindings: [] } },
+    ])
+  })
+
+  it('patches nothing when the import creates no frontend frame', () => {
+    const plan = planMonorepoImport(['services/api', 'services/auth'], 'service', undefined)
+    expect(planFrontendConfigPatches(created(plan))).toEqual([])
+  })
+})

package/app/utils/monorepoImport.ts

@@ -0,0 +1,154 @@
+import type { FrameRepoType, FrontendBackendBinding, FrontendConfig } from '~/types/domain'
+
+/**
+ * Planning rules for a monorepo import: turning the picked subdirectories into the frames to
+ * create, and the `frontendConfig` patches those frames owe once they have ids.
+ *
+ * The relationship model already exists: a `frontend` frame's `backendBindings` ARE the
+ * frontend→service board link (`@cat-factory/contracts`'s `frontendBackendBindingSchema`), the
+ * frontend counterpart of a service frame's `serviceConnections`. All this adds is declaring it
+ * at IMPORT time, while the user still has the whole selection in front of them, instead of
+ * making them open the frontend's inspector afterwards and re-pick services one row at a time.
+ *
+ * Pure and frontend-only: the modal is the sole caller, so these rules stay here rather than in
+ * contracts (nothing on the backend has to agree about them, since it sees ordinary frame creates
+ * and ordinary `frontendConfig` patches).
+ */
+
+/**
+ * Whether the import may offer a frontend mark for the directories it is about to create.
+ *
+ * Two conditions, both about the mark meaning something:
+ *
+ * - The picked role is `service`. A backend binding may only point at a `service` frame, so
+ *   marking a frontend among libraries or document repos would wire nothing, and when the role
+ *   already IS `frontend`, every frame is one and singling one out says nothing.
+ * - At least two directories are being CREATED. The mark divides that set into "the frontend" and
+ *   "the backends it talks to"; with one there is no rest to bind to, and the role select above
+ *   already covers importing a lone frontend. The count is of what the add will actually create,
+ *   never of the raw cart: a cart entry whose frame already exists (a retry after a partial
+ *   failure) is filtered out of the import, so counting it would offer a mark that binds nothing.
+ */
+export function canDesignateFrontend(type: FrameRepoType, directoryCount: number): boolean {
+  return type === 'service' && directoryCount >= 2
+}
+
+/** One frame the import will create: its repo subdirectory and the role it takes. */
+export interface MonorepoImportEntry {
+  /** Repo-root-relative subdirectory the frame is pinned to. */
+  directory: string
+  /** The frame's repo role: `frontend` for the marked directory, the picked role for the rest. */
+  type: FrameRepoType
+  /**
+   * Whether this is the ONE directory marked as the frontend for the others, so its config binds
+   * every other frame the import creates.
+   *
+   * Stated here rather than left to be re-derived from `type`, because `type === 'frontend'` does
+   * NOT identify it: when the picked ROLE is `frontend`, every entry carries that type and no mark
+   * was ever on offer (see {@link canDesignateFrontend}), so a type test picks an arbitrary frame
+   * and binds it to a backend set that does not exist.
+   */
+  designatedFrontend: boolean
+}
+
+/**
+ * The frames to create for a monorepo import, in the order the user picked them.
+ *
+ * A `frontendDirectory` is honoured only when the mark would MEAN something, and this is the one
+ * place that decides. Two ways it can be stale, both of which designate nothing rather than
+ * promoting some other frame:
+ *
+ * - The role or the size of the import no longer admits a mark ({@link canDesignateFrontend}), so
+ *   the picker is not even on screen. Enforced here rather than trusted to the caller, because a
+ *   caller that re-derives the condition can drift from it.
+ * - The marked directory is not among the ones being created: it was removed from the cart, or an
+ *   earlier add already created it.
+ */
+export function planMonorepoImport(
+  directories: readonly string[],
+  backendType: FrameRepoType,
+  frontendDirectory: string | undefined,
+): MonorepoImportEntry[] {
+  const marked =
+    canDesignateFrontend(backendType, directories.length) && frontendDirectory !== undefined
+  const frontend = marked && directories.includes(frontendDirectory) ? frontendDirectory : undefined
+  return directories.map((directory) => ({
+    directory,
+    type: directory === frontend ? 'frontend' : backendType,
+    designatedFrontend: directory === frontend,
+  }))
+}
+
+/** A frame the import created, paired with the plan entry it was created from. */
+export interface CreatedMonorepoFrame {
+  /** Id of the block the create call minted. */
+  blockId: string
+  /** The entry that produced it, carrying its role and whether it is the designated frontend. */
+  entry: MonorepoImportEntry
+}
+
+/** One `frontendConfig` write the import owes a frame it created. */
+export interface FrontendConfigPatch {
+  blockId: string
+  config: FrontendConfig
+}
+
+/**
+ * The `frontendConfig` each created `frontend` frame needs, once the create calls have minted
+ * their ids.
+ *
+ * EVERY frontend frame gets one, not only a designated one, because the patch carries two
+ * separable facts:
+ *
+ * - **`directory`, for all of them.** A frame's monorepo subdirectory is a SERVICE-level fact (the
+ *   repo projection's `directory`, which scopes an agent's checkout); the harness's frontend
+ *   install/build/serve reads `frontendConfig.directory` instead, and defaults to the repo root
+ *   when it is absent. So a monorepo frontend whose config does not repeat it builds the wrong
+ *   tree, silently. That is true of every frontend frame an import creates, including a whole cart
+ *   imported under the `frontend` role, where no mark is ever offered. The user picked the
+ *   directory, so it is copied, never guessed.
+ * - **`backendBindings`, for the designated one only.** The mark is what says "these other frames
+ *   are the backends this app talks to"; an undesignated frontend frame is bound to nothing, which
+ *   is the same empty list the inspector would have shown.
+ */
+export function planFrontendConfigPatches(
+  created: readonly CreatedMonorepoFrame[],
+): FrontendConfigPatch[] {
+  const designated = created.find((frame) => frame.entry.designatedFrontend)
+  const backendBlockIds = designated
+    ? created.filter((frame) => frame !== designated).map((frame) => frame.blockId)
+    : []
+  return created
+    .filter((frame) => frame.entry.type === 'frontend')
+    .map((frame) => ({
+      blockId: frame.blockId,
+      config: frontendConfigForImport(
+        frame.entry.directory,
+        frame === designated ? backendBlockIds : [],
+      ),
+    }))
+}
+
+/**
+ * The `frontendConfig` for one created frontend frame: where the app lives in the repo, and one
+ * backend binding per frame it was marked the frontend for.
+ *
+ * **`envVar` is left EMPTY.** The env var a frontend reads for an upstream URL is a fact about the
+ * frontend's own source, which an import that never looks inside the repo cannot know, and
+ * inventing a plausible name (`PUB_API_URL`) would inject a variable nothing reads while looking
+ * configured. Empty is the contract's designed inert state: the job-body builder filters those
+ * bindings out of the injected env, `duplicateBindingEnvVars` ignores them, `frontendOriginsForService`
+ * skips them, and the board still draws the frontend→service edge. What the import DOES know (which
+ * services this frontend talks to) is recorded; the names are left for the inspector's "Detect from
+ * repo" (which reads the repo's dotenv examples) or the user, and the modal says so.
+ */
+function frontendConfigForImport(
+  directory: string,
+  backendBlockIds: readonly string[],
+): FrontendConfig {
+  const backendBindings: FrontendBackendBinding[] = backendBlockIds.map((serviceBlockId) => ({
+    envVar: '',
+    source: { kind: 'service', serviceBlockId },
+  }))
+  return { directory, backendBindings }
+}