@cat-factory/app 0.247.0 → 0.249.0

package/app/modular/journeys/environmentSetup.ts

@@ -18,7 +18,7 @@ import {
 
 /**
  * The environment-setup journey — the slice-3 pilot of the modular-vue adoption
- * (docs/initiatives/modular-vue-adoption.md). It replaces the wizard's hand-rolled
+ * (backend/docs/adr/0049-modular-vue-adoption.md). It replaces the wizard's hand-rolled
  * `STEP_ORDER` + `step` ref + `goToStep` navigation (in `stores/environmentWizard.ts`)
  * with a typed, back/rewind-capable, resumable journey; the per-step data + async
  * actions stay in that Pinia store, driven by the step components below.

package/app/modular/journeys/persistence.ts

@@ -5,7 +5,7 @@ import { createPiniaJourneyPersistence } from '@modular-vue/journeys'
 
 /**
  * Pinia-backed journey persistence (slice 3 of the modular-vue adoption —
- * docs/initiatives/modular-vue-adoption.md).
+ * backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * A journey's `persistence` adapter is what makes `runtime.start()` mean
  * RESUME: it probes `keyFor(input)` for an in-flight serialized instance and

package/app/modular/nav-contributions.spec.ts

@@ -21,6 +21,7 @@ const NO_GATES: NavGates = {
   canManageSettings: false,
   githubAvailable: false,
   libraryAvailable: false,
+  designSourceConnected: false,
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,
@@ -42,6 +43,7 @@ const ALL_GATES: NavGates = {
   canManageSettings: true,
   githubAvailable: true,
   libraryAvailable: true,
+  designSourceConnected: true,
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,

package/app/modular/nav-contributions.ts

@@ -10,7 +10,7 @@ export type { AppSlots } from './slots'
 
 /**
  * The single nav/command catalog for the layer (slice 1 of the modular-vue
- * adoption — docs/initiatives/modular-vue-adoption.md).
+ * adoption — backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * Every destination is declared ONCE here as data and rendered three ways —
  * `SideBar`, `CommandBar`, `BoardToolbar` — instead of each shell hand-rolling
@@ -89,6 +89,16 @@ export interface NavGates {
   githubAvailable: boolean
   /** The prompt-fragment library integration is enabled. */
   libraryAvailable: boolean
+  /**
+   * The board has a CONNECTED design source (Figma, Zeplin).
+   *
+   * Availability, not permission, like `githubAvailable`: the start-from-design affordance and
+   * the tour that walks it both point at a frame-header button that only exists once a design
+   * source is connected, so a board without one is offered a walkthrough that hunts for a
+   * control nobody can see. Connecting is `integrations.manage`, but STARTING from a design is
+   * member-tier, so the gate is the connection rather than the permission to make one.
+   */
+  designSourceConnected: boolean
   /** An execution/test-env backend is reported (runner pool / environment / local). */
   infrastructureAvailable: boolean
   /** Accounts (auth) are enabled on the deployment. */

package/app/modular/nav-gates.ts

@@ -22,6 +22,7 @@ export function createNavGates(): NavGates {
   const access = useWorkspaceAccess()
   const github = useGitHubStore()
   const library = useFragmentLibraryStore()
+  const documents = useDocumentsStore()
   const accounts = useAccountsStore()
   const auth = useAuthStore()
   const providerConnections = useProviderConnectionsStore()
@@ -90,6 +91,9 @@ export function createNavGates(): NavGates {
     get libraryAvailable() {
       return library.available === true
     },
+    get designSourceConnected() {
+      return documents.connectedDesignSources.length > 0
+    },
     get infrastructureAvailable() {
       // `integrations.manage` is required to provision/manage infrastructure, so
       // gate the whole section on it too (a member/viewer would only 403 inside).

package/app/modular/panels/inspector.logic.ts

@@ -3,7 +3,7 @@ import type { Block } from '~/types/domain'
 
 /**
  * Pure definition of the block-inspector panel group (slice 4 of the modular-vue
- * adoption — docs/initiatives/modular-vue-adoption.md).
+ * adoption — backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * The inspector used to be a 631-line `v-if` fan in `InspectorPanel.vue` that
  * switched its body on the selected block's `level` (frame/module/task/epic/

package/app/modular/registry.spec.ts

@@ -9,6 +9,7 @@ const NO_GATES: NavGates = {
   canManageSettings: false,
   githubAvailable: false,
   libraryAvailable: false,
+  designSourceConnected: false,
   infrastructureAvailable: false,
   accountsEnabled: false,
   isAccountAdmin: false,

package/app/modular/registry.ts

@@ -8,7 +8,7 @@ import type { AppSlots } from '~/modular/slots'
 
 /**
  * modular-vue registry for the `@cat-factory/app` layer (slice 0 of the
- * modular-vue adoption — docs/initiatives/modular-vue-adoption.md).
+ * modular-vue adoption — backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * This is the frontend analogue of the backend's public registries
  * (`registerAgentKind`, `registerGate`): a single registry into which the layer

package/app/modular/result-views.ts

@@ -25,7 +25,7 @@ import type { ResultViewContribution } from './slots'
 
 /**
  * The first-party result-view registry (slice 2 of the modular-vue adoption —
- * docs/initiatives/modular-vue-adoption.md).
+ * backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * Every built-in dedicated result window is contributed as a `ComponentEntry`
  * to the `resultViews` slot instead of living in a hardcoded `Record` in

package/app/modular/slots.ts

@@ -10,7 +10,7 @@ import type { WorkspaceMetadataFieldDefinition } from './workspace-metadata'
  * The layer's aggregated slot map — the single home for every slot key the
  * first-party modules (and consumer deployments) contribute to. Grows one key
  * per converted seam as the modular-vue adoption proceeds
- * (docs/initiatives/modular-vue-adoption.md):
+ * (backend/docs/adr/0049-modular-vue-adoption.md):
  *
  *  - `nav` (slice 1) — the nav/command catalog, rendered by the three shells.
  *  - `resultViews` (slice 2) — the id → dedicated result-window registry

package/app/modular/tutorial-tours.spec.ts

@@ -19,6 +19,7 @@ const ALL_GATES: NavGates = {
   canManageSettings: true,
   githubAvailable: true,
   libraryAvailable: true,
+  designSourceConnected: true,
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,
@@ -392,6 +393,10 @@ describe('tour availability across the catalog', () => {
       // this is the tour the contextual offer raises when one does.
       'diagnose-failure',
       'review-merge',
+      // The same loop as a DESIGNER enters it. Offered rather than catalogue-only because on a
+      // board with a design source connected it IS the everyday loop, and its own requirement
+      // keeps it off every board without one.
+      'start-from-design',
     ]
     const CATALOGUE_ONLY = [
       'wire-models',

package/app/modular/tutorial-tours.ts

@@ -152,6 +152,15 @@ export const TUTORIAL_REQUIREMENTS = {
     labelKey: 'tutorial.requirements.library',
     met: (gates) => gates.libraryAvailable,
   },
+  // The CONNECTION rather than the permission to make one: starting from a design is
+  // member-tier, and the frame-header button the tour clicks exists only once some admin has
+  // connected a design source. A tour gated on `integrations.manage` would be withheld from
+  // exactly the persona it is written for.
+  designSource: {
+    id: 'design-source',
+    labelKey: 'tutorial.requirements.designSource',
+    met: (gates) => gates.designSourceConnected,
+  },
 } as const satisfies Record<string, TutorialRequirement>
 
 export const TUTORIAL_TOURS: readonly TutorialTour[] = [
@@ -575,6 +584,74 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
       },
     ],
   },
+  {
+    id: 'start-from-design',
+    order: 55,
+    icon: 'i-lucide-frame',
+    titleKey: 'tutorial.tours.startFromDesign.title',
+    descriptionKey: 'tutorial.tours.startFromDesign.description',
+    // The delivery loop as a DESIGNER enters it, which is a different first step from
+    // `first-task`: the work starts from a frame in Figma, not from a title someone types. It
+    // rides the loop's order (after the run tours, before the platform half) rather than
+    // replacing `first-task`, because it ends in the same add-task form and everything after
+    // that point is the arc those tours already cover.
+    //
+    // Offered at launch, unlike the platform tours, and gated on the design source being
+    // CONNECTED: on a board with one, this is the everyday loop rather than reference material.
+    requires: [
+      TUTORIAL_REQUIREMENTS.boardWrite,
+      TUTORIAL_REQUIREMENTS.service,
+      TUTORIAL_REQUIREMENTS.designSource,
+    ],
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.startFromDesign.steps.intro.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.intro.body',
+      },
+      {
+        id: 'open',
+        target: 'frame-start-from-design',
+        advanceOn: 'target-click',
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.startFromDesign.steps.open.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.open.body',
+      },
+      {
+        id: 'paste',
+        target: 'start-from-design-link',
+        // Inside the modal the previous click opens.
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.startFromDesign.steps.paste.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.paste.body',
+      },
+      {
+        // Left to the anchor-skip rather than given a `when`: the resolved card appears only
+        // once a link has actually been pasted, and someone walking the tour without one in
+        // hand should reach the finish card rather than stall on an input they cannot fill.
+        id: 'resolved',
+        target: 'start-from-design-resolved',
+        waitForTargetMs: 8000,
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.startFromDesign.steps.resolved.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.resolved.body',
+      },
+      {
+        id: 'continue',
+        target: 'start-from-design-continue',
+        advanceOn: 'target-click',
+        placement: 'top',
+        titleKey: 'tutorial.tours.startFromDesign.steps.continue.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.continue.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.startFromDesign.steps.finish.title',
+        bodyKey: 'tutorial.tours.startFromDesign.steps.finish.body',
+      },
+    ],
+  },
   // ---------------------------------------------------------------------------------------
   // The platform half. Ordered after the whole delivery loop so the catalogue reads in the
   // order someone meets these things: learn the loop, then the machinery under it.

package/app/pages/index.vue

@@ -55,6 +55,9 @@ const DocumentTemplatesModal = defineAsyncComponent(
 const SpawnPreviewModal = defineAsyncComponent(
   () => import('~/components/documents/SpawnPreviewModal.vue'),
 )
+const StartFromDesignModal = defineAsyncComponent(
+  () => import('~/components/documents/StartFromDesignModal.vue'),
+)
 const BootstrapModal = defineAsyncComponent(
   () => import('~/components/bootstrap/BootstrapModal.vue'),
 )
@@ -472,6 +475,7 @@ watch(
         <DocumentImportModal v-if="ui.documentImport" />
         <DocumentTemplatesModal v-if="ui.documentTemplates" />
         <SpawnPreviewModal v-if="ui.spawnPreview" />
+        <StartFromDesignModal v-if="ui.startFromDesign" />
         <BootstrapModal v-if="ui.bootstrapOpen" />
         <AddServiceFromRepoModal v-if="ui.addServiceOpen" />
         <GitHubPanel v-if="ui.githubOpen" />

package/app/plugins/modular.client.ts

@@ -20,7 +20,7 @@ import type { Block, CustomAgentKind, CustomTaskType } from '~/types/domain'
 
 /**
  * Wire the modular-vue registry into the Nuxt app (slice 0 of the modular-vue
- * adoption — docs/initiatives/modular-vue-adoption.md).
+ * adoption — backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * `enforce: 'post'` is load-bearing for the consumer-contribution seam. Nuxt
  * loads layer plugins before the consuming app's plugins within the same enforce

package/app/stores/agents.ts

@@ -16,7 +16,7 @@ import type { AgentArchetype, AgentKind, AgentKindVariant, CustomAgentKind } fro
 
 /**
  * The agent palette catalog (slice 2 of the modular-vue adoption —
- * docs/initiatives/modular-vue-adoption.md).
+ * backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * Reactive union of three sources, none of which mutates the frozen built-in
  * {@link AGENT_BY_KIND} const any more:

package/app/stores/documents.spec.ts

@@ -154,3 +154,63 @@ describe('documents store: manual refresh', () => {
     expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
   })
 })
+
+describe('documents store: the OAuth and design halves of the source list', () => {
+  /** The source listing the probe reads: descriptors PLUS what this deployment can OAuth. */
+  function stubSources(oauthSources: string[]) {
+    stubApi({
+      listDocumentSources: () =>
+        Promise.resolve({
+          sources: [
+            {
+              source: 'figma',
+              label: 'Figma',
+              icon: 'i',
+              credentialFields: [],
+              refLabel: '',
+              refPlaceholder: '',
+              oauth: { scopes: ['file_content:read'] },
+            },
+            {
+              source: 'notion',
+              label: 'Notion',
+              icon: 'i',
+              credentialFields: [],
+              refLabel: '',
+              refPlaceholder: '',
+            },
+          ],
+          oauthSources,
+        }),
+      listDocumentConnections: () =>
+        Promise.resolve({ connections: [{ source: 'figma', label: 'Figma', connectedAt: 1 }] }),
+    })
+  }
+
+  it('offers OAuth where the deployment has a registered app', async () => {
+    stubSources(['figma'])
+    const store = useDocumentsStore()
+    await store.probe()
+    expect(store.canConnectWithOAuth('figma')).toBe(true)
+  })
+
+  it('withholds it where the SOURCE declares an OAuth half but the deployment registered nothing', async () => {
+    // Figma declares the half in both cases; only the registered app decides whether the button
+    // is offered. Folded onto the descriptor, this case would render a "Connect with Figma" that
+    // can only 503.
+    stubSources([])
+    const store = useDocumentsStore()
+    await store.probe()
+    expect(store.descriptorFor('figma')?.oauth).toBeDefined()
+    expect(store.canConnectWithOAuth('figma')).toBe(false)
+  })
+
+  it('lists only CONNECTED design sources, so no affordance opens onto a dead end', async () => {
+    stubSources(['figma'])
+    const store = useDocumentsStore()
+    await store.probe()
+    // Notion is connectable and not a design source; Figma is both connected and a design one.
+    // The classification comes from contracts, so adding a source cannot leave it unclassified.
+    expect(store.connectedDesignSources).toEqual(['figma'])
+  })
+})

package/app/stores/documents.ts

@@ -14,6 +14,7 @@ import type {
 } from '~/types/domain'
 import { isConnectableSource } from '@cat-factory/contracts'
 import { useDocumentFreshness } from '~/composables/useDocumentFreshness'
+import { useDocumentSourceConnect } from '~/composables/useDocumentSourceConnect'
 import { useSourceIntegration } from '~/composables/useSourceIntegration'
 import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -32,6 +33,10 @@ export const useDocumentsStore = defineStore('documents', () => {
   const api = useApi()
   const workspace = useWorkspaceStore()
 
+  // What this DEPLOYMENT can OAuth, reported beside the descriptors and read through
+  // `useDocumentSourceConnect`, which owns why that is a separate fact from the descriptor's own.
+  const oauthSources = ref<DocumentSourceKind[]>([])
+
   // Shared opt-in / probe / connections lifecycle (see `useSourceIntegration`).
   const integration = useSourceIntegration<
     DocumentSourceKind,
@@ -41,16 +46,32 @@ export const useDocumentsStore = defineStore('documents', () => {
     enabled: () => !!workspace.workspaceId,
     workspaceId: () => workspace.workspaceId,
     fetch: async () => {
-      const [{ sources }, { connections }] = await Promise.all([
+      const [{ sources, oauthSources: oauth }, { connections }] = await Promise.all([
         api.listDocumentSources(workspace.requireId()),
         api.listDocumentConnections(workspace.requireId()),
       ])
+      oauthSources.value = oauth
       return { sources, connections }
     },
   })
   const { available, sources, connections, connectedSources, anyConnected } = integration
   const { descriptorFor, connectionFor, isConnected, probe, ensureProbed } = integration
 
+  // Connecting a source, and what this board may connect it WITH, in its own collaborator: the
+  // question grew several parts when OAuth landed, and none of the store's other concerns (the
+  // imported documents, their freshness, the doc-kind role links) read any of them.
+  const { canConnectWithOAuth, connectedDesignSources, connect, disconnect, beginOAuthConnect } =
+    useDocumentSourceConnect({
+      workspaceId: () => workspace.requireId(),
+      oauthSources,
+      connectedSources,
+      onConnected: (conn) => {
+        integration.upsertConnection(conn)
+        available.value = true
+      },
+      onDisconnected: (source) => integration.removeConnection(source),
+    })
+
   const { items: documents, upsert: upsertDoc } = useUpsertList<SourceDocument>({
     key: (d) => `${d.source}:${d.externalId}`,
     prepend: true,
@@ -76,19 +97,6 @@ export const useDocumentsStore = defineStore('documents', () => {
     return documents.value.filter((d) => d.linkedBlockId === blockId)
   }
 
-  /** Connect the workspace to a source with its credential bag. */
-  async function connect(source: DocumentSourceKind, credentials: Record<string, string>) {
-    const conn = await api.connectDocumentSource(workspace.requireId(), source, credentials)
-    integration.upsertConnection(conn)
-    available.value = true
-  }
-
-  /** Disconnect the workspace from a source. */
-  async function disconnect(source: DocumentSourceKind) {
-    await api.disconnectDocumentSource(workspace.requireId(), source)
-    integration.removeConnection(source)
-  }
-
   /** Load the imported documents for the workspace (across sources). */
   async function loadDocuments() {
     documents.value = await api.listDocuments(workspace.requireId())
@@ -125,20 +133,36 @@ export const useDocumentsStore = defineStore('documents', () => {
     return results
   }
 
-  /** Preview the board structure a page would expand into (no writes). */
-  function plan(source: DocumentSourceKind, externalId: string): Promise<DocumentBoardPlan> {
-    return api.planDocument(workspace.requireId(), source, externalId)
+  /**
+   * Preview the board structure a page would expand into (no writes).
+   *
+   * With `frameId` the preview is TARGET-AWARE: the planner is told which service the work goes
+   * inside and proposes its modules and tasks instead of an architecture.
+   */
+  function plan(
+    source: DocumentSourceKind,
+    externalId: string,
+    frameId?: string,
+  ): Promise<DocumentBoardPlan> {
+    return api.planDocument(workspace.requireId(), source, {
+      externalId,
+      ...(frameId ? { frameId } : {}),
+    })
   }
 
   /**
-   * Apply a page's structure to the board as new top-level frames, then refresh the
-   * board snapshot. The endpoint also accepts a `frameId` that flattens the planned
-   * frames into an existing service; the SPA deliberately never sends one, because the
-   * planner is target-blind and that path discards the frame titles/types the preview
-   * shows. Scoping a spawn to a service needs a target-aware plan first.
+   * Apply a page's structure to the board, then refresh the board snapshot.
+   *
+   * `frameId` must be the SAME frame the preview was planned for. The endpoint re-plans against
+   * it, so a targeted preview and its write agree; sending a frame the preview did not use would
+   * flatten a board-wide plan into it and discard the frame titles and types the user approved,
+   * which is why this was board-level only until target-aware planning existed.
    */
-  async function spawn(source: DocumentSourceKind, externalId: string) {
-    const { result } = await api.spawnDocument(workspace.requireId(), source, { externalId })
+  async function spawn(source: DocumentSourceKind, externalId: string, frameId?: string) {
+    const { result } = await api.spawnDocument(workspace.requireId(), source, {
+      externalId,
+      ...(frameId ? { frameId } : {}),
+    })
     await workspace.refresh()
     return result
   }
@@ -218,6 +242,10 @@ export const useDocumentsStore = defineStore('documents', () => {
   return {
     available,
     sources,
+    oauthSources,
+    canConnectWithOAuth,
+    connectedDesignSources,
+    beginOAuthConnect,
     connections,
     documents,
     loading,

package/app/stores/environmentWizard.ts

@@ -33,7 +33,7 @@ import { createSaveActions } from '~/stores/environmentWizard/save'
 // compose provider keys purely on the saved recipe (the build-flag rule). Mirrors the other infra
 // stores' idiom; the flow state is a singleton so the wizard's step children share it.
 //
-// Since slice 3 of the modular-vue adoption (docs/initiatives/modular-vue-adoption.md) the wizard's
+// Since slice 3 of the modular-vue adoption (backend/docs/adr/0049-modular-vue-adoption.md) the wizard's
 // step NAVIGATION lives in a modular-vue journey (`app/modular/journeys/environmentSetup.ts`), NOT
 // here — this store no longer holds a `step` / `STEP_ORDER` / `goToStep`. It is purely the per-frame
 // data+action layer the journey's step components drive; `beginForFrame` seeds it when a step first

package/app/stores/publicApiKeys.spec.ts

@@ -13,6 +13,7 @@ function key(over: Partial<PublicApiKey> = {}): PublicApiKey {
     scope: 'write',
     createdByUserId: null,
     createdByKeyId: null,
+    externalIdentity: null,
     createdAt: 1,
     lastUsedAt: null,
     revokedAt: null,

package/app/stores/ui/modals.ts

@@ -192,6 +192,11 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   // opened standalone, and the modal offers every container on the board.
   const bugHunt = ref<{ source: TaskSourceKind | null; containerId: string | null } | null>(null)
 
+  // Start-from-design: paste a design link, and the resolved reference is staged onto a new task
+  // in `frameId`. `frameId` is always present — the affordance lives on a frame header, and the
+  // flow ends in the add-task form, which needs a container to create in.
+  const startFromDesign = ref<{ frameId: string } | null>(null)
+
   // Add-task modal: the container (service frame or module) a new task is being
   // added to, or null when closed. The user types the title + description; nothing
   // is launched until they explicitly start the created task.
@@ -266,6 +271,13 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   function closeBugHunt() {
     bugHunt.value = null
   }
+  function openStartFromDesign(frameId: string) {
+    resetHubReturn()
+    startFromDesign.value = { frameId }
+  }
+  function closeStartFromDesign() {
+    startFromDesign.value = null
+  }
   function openAddTask(containerId: string, prefill: AddTaskPrefill | null = null) {
     addTaskPrefill.value = prefill
     addTaskContainerId.value = containerId
@@ -301,6 +313,7 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     taskConnect,
     taskImport,
     bugHunt,
+    startFromDesign,
     addTaskContainerId,
     addTaskPrefill,
     reviewFrictionContext,
@@ -320,6 +333,8 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     closeTaskImport,
     openBugHunt,
     closeBugHunt,
+    openStartFromDesign,
+    closeStartFromDesign,
     openAddTask,
     closeAddTask,
     openReviewFriction,

package/app/utils/modular.ts

@@ -6,6 +6,6 @@
  * ergonomics as the layer's auto-imported stores and composables.
  *
  * See `app/modular/registry.ts` for the seam itself and
- * docs/initiatives/modular-vue-adoption.md for the adoption plan.
+ * backend/docs/adr/0049-modular-vue-adoption.md for the adoption plan.
  */
 export { registerAppModule } from '~/modular/registry'