@cat-factory/app 0.248.0 → 0.250.0

package/app/composables/useDocumentSourceConnect.ts

@@ -0,0 +1,88 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+import { isDesignSource } from '@cat-factory/contracts'
+import type {
+  DocumentConnection,
+  DocumentSourceDescriptor,
+  DocumentSourceKind,
+} from '~/types/domain'
+
+/**
+ * How this workspace CONNECTS to a document source, and what it may connect with.
+ *
+ * Split out of `stores/documents.ts` when the OAuth half landed, because "which credential can
+ * this board offer for this source" turned into a question with several parts: a source declares
+ * an OAuth half in code, the deployment may or may not have registered an app for it, and the
+ * typed-credential form is the fallback either way. The store's other concerns (the imported
+ * documents, their freshness, the doc-kind role links) never read any of it.
+ *
+ * It takes bound accessors rather than the store, so it stays testable on its own and cannot
+ * reach for state it has no business in.
+ */
+export interface DocumentSourceConnectDeps {
+  workspaceId: () => string
+  /**
+   * The sources this DEPLOYMENT can OAuth, as the backend reports them beside the descriptors.
+   *
+   * Owned by the caller (the probe writes it) rather than fetched here, because it arrives on the
+   * same response as the descriptors and a second read would be a second round trip that could
+   * disagree with the first.
+   */
+  oauthSources: Ref<DocumentSourceKind[]>
+  /** The connected subset of the descriptors, in registry order. */
+  connectedSources: ComputedRef<DocumentSourceDescriptor[]>
+  /** Fold a new/updated connection into the caller's list. */
+  onConnected: (connection: DocumentConnection) => void
+  /** Drop a source's connection from the caller's list. */
+  onDisconnected: (source: DocumentSourceKind) => void
+}
+
+export function useDocumentSourceConnect(deps: DocumentSourceConnectDeps) {
+  const api = useApi()
+
+  /**
+   * Whether this deployment can run the OAuth connect for a source RIGHT NOW.
+   *
+   * Deliberately not `descriptor.oauth !== undefined`: that says the source supports the flow,
+   * which is true of Figma on every deployment, including the ones that have registered no app.
+   * A button rendered off the descriptor alone could only 503.
+   */
+  function canConnectWithOAuth(source: DocumentSourceKind): boolean {
+    return deps.oauthSources.value.includes(source)
+  }
+
+  /**
+   * Every CONNECTED design source, in the order the backend registered them.
+   *
+   * `isDesignSource` comes from contracts rather than a local list, for the reason the backend
+   * reads it there: whether a source describes a design is a fact both sides have to agree about,
+   * and a second copy here would drift the moment a source is added.
+   */
+  const connectedDesignSources = computed(() =>
+    deps.connectedSources.value.map((s) => s.source).filter(isDesignSource),
+  )
+
+  /** Connect the workspace to a source with its credential bag. */
+  async function connect(source: DocumentSourceKind, credentials: Record<string, string>) {
+    deps.onConnected(await api.connectDocumentSource(deps.workspaceId(), source, credentials))
+  }
+
+  /** Disconnect the workspace from a source. */
+  async function disconnect(source: DocumentSourceKind) {
+    await api.disconnectDocumentSource(deps.workspaceId(), source)
+    deps.onDisconnected(source)
+  }
+
+  /**
+   * Send the browser to a source's vendor consent screen.
+   *
+   * A full navigation rather than a popup: the vendor lands back on the app's own OAuth callback,
+   * which stores the grant and redirects here, so the returning page re-probes and sees the
+   * connection. A popup would leave the opener holding stale state with nothing to tell it.
+   */
+  async function beginOAuthConnect(source: DocumentSourceKind) {
+    const { url } = await api.documentSourceOAuthUrl(deps.workspaceId(), source)
+    window.location.assign(url)
+  }
+
+  return { canConnectWithOAuth, connectedDesignSources, connect, disconnect, beginOAuthConnect }
+}

package/app/composables/usePipelineErrorToast.ts

@@ -333,6 +333,8 @@ const UNAVAILABLE_DESCRIPTION_KEYS: Record<UnavailableReason, string> = {
   binary_generators_unreachable: 'errors.unavailable.description.binary_generators_unreachable',
   foundational_builtins_unreachable:
     'errors.unavailable.description.foundational_builtins_unreachable',
+  connection_credentials_unreadable:
+    'errors.unavailable.description.connection_credentials_unreadable',
 }
 
 /**

package/app/modular/external-tools.spec.ts

@@ -33,6 +33,7 @@ const GATES: NavGates = {
   canManageSettings: true,
   githubAvailable: true,
   libraryAvailable: true,
+  designSourceConnected: true,
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,

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

@@ -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/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/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/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/github/vcsConnect.ts

@@ -15,6 +15,7 @@ export interface VcsProviderViews {
   canConnectGitLabPat: ComputedRef<boolean>
   soleConnectProvider: ComputedRef<VcsProvider | null>
   surfaceProvider: ComputedRef<VcsProvider | null>
+  surfaceWebUrl: ComputedRef<string | null>
 }
 
 /** The derived provider questions above, off the probed connection + capability state. */
@@ -53,12 +54,30 @@ export function createVcsProviderViews(ctx: GitHubStoreContext): VcsProviderView
     connection.value !== null ? provider.value : soleConnectProvider.value,
   )
 
+  /**
+   * The browser-facing host of the instance {@link surfaceProvider} names: the connected one's,
+   * or (with nothing bound) the host the deployment advertises for the provider it could
+   * connect. Null when neither is known, which is what a link builder needs to WITHHOLD rather
+   * than fall back to the provider's public instance.
+   *
+   * It has to come off the connect OPTION before a connection exists, because the two surfaces
+   * that need a host that early (the PAT box's token link, bootstrap's create-repository button)
+   * render while the connect box is still on screen.
+   */
+  const surfaceWebUrl = computed<string | null>(() => {
+    if (connection.value !== null) return connection.value.webUrl
+    const sole = soleConnectProvider.value
+    if (!sole) return null
+    return connectOptions.value.find((o) => o.provider === sole)?.webUrl ?? null
+  })
+
   return {
     provider,
     canConnectGitHubApp,
     canConnectGitLabPat,
     soleConnectProvider,
     surfaceProvider,
+    surfaceWebUrl,
   }
 }