@cat-factory/app 0.248.0 → 0.249.0

package/app/components/documents/StartFromDesignModal.vue

@@ -0,0 +1,237 @@
+<script setup lang="ts">
+// Start a task from a design link: paste a Figma/Zeplin URL on a service frame, and the resolved
+// reference is staged onto the add-task form as context. One affordance, three steps that used to
+// be four separate surfaces (Integrations hub → import modal → board → add task → attach).
+//
+// Three rules this surface exists to hold, each of which the obvious version gets wrong.
+//
+//  - It resolves the reference BEFORE anything is created, through the same
+//    `POST /document-sources/:source/resolve-ref` the attach picker uses, so a share link's title
+//    segment and tracking params are trimmed where the person who pasted them can still see it,
+//    and a link the source cannot read is a correction rather than a toast over a task that
+//    already exists without its design.
+//  - It only asks the CONNECTED DESIGN sources, and it asks them in claim-confidence order
+//    (host-pinned first), because a host-blind prose parser will happily claim a Figma URL whose
+//    file key carries a UUID-shaped run. `connectedDesignSources` is already in registry order
+//    and every design source is host-pinned, so the order is the store's.
+//  - A WIDENED reference is stated separately from a trimmed one. Figma's own Copy link emits a
+//    complex instance id for any component instance, which the parser cannot read, so it falls
+//    back to the whole file: "I attached this frame" and "I attached the entire design" otherwise
+//    render identically. For a designer that widening IS the defect, not a detail.
+import { refRowFor, classifyRefFailure, type RefState } from './ContextDocumentPicker.logic'
+import type { DocumentSourceKind, ResolvedDocumentRef } from '~/types/domain'
+
+const { t } = useI18n()
+const ui = useUiStore()
+const documents = useDocumentsStore()
+
+const open = computed({
+  get: () => ui.startFromDesign !== null,
+  set: (v: boolean) => {
+    if (!v) ui.closeStartFromDesign()
+  },
+})
+
+const pasted = ref('')
+const state = ref<RefState>({ status: 'none' })
+/** The source that claimed the paste, held beside the verdict so the staged item names it. */
+const claimant = ref<DocumentSourceKind | null>(null)
+/**
+ * The exact text {@link state} is the verdict FOR, so the same text is never re-resolved.
+ *
+ * This is what keeps Continue clickable. The input resolves on blur, and clicking Continue blurs
+ * it, so a person who resolved with Enter and then reached for the button re-entered `resolve()`
+ * on mousedown: the state fell back to `checking`, `row` went null, and Vue disabled the button
+ * before mouseup, so the click was never dispatched. The button came back enabled a moment later
+ * having done nothing, which reads as a dead button rather than as a race. (The `start-from-design`
+ * tour hit the same edge, its `advanceOn: 'target-click'` step waiting on a click that never fired.)
+ *
+ * Guarding on the TEXT rather than suppressing the blur is what makes it a fix instead of a
+ * workaround: re-resolving input that already has a verdict spends one HTTP call per connected
+ * design source to arrive back where it started, whoever caused it.
+ */
+const resolvedFor = ref<string | null>(null)
+
+watch(open, (isOpen) => {
+  if (!isOpen) return
+  pasted.value = ''
+  state.value = { status: 'none' }
+  claimant.value = null
+  resolvedFor.value = null
+})
+
+const row = computed(() => refRowFor(state.value, pasted.value))
+const sources = computed(() => documents.connectedDesignSources)
+
+/**
+ * The source the staged reference will be attached to.
+ *
+ * An UNCHECKED paste (the pre-flight itself failed: offline, a 502, a proxy's error page) is not
+ * a refusal, so it stays stageable with the import as the backstop it always was — but only when
+ * ONE design source is connected, because that is the only case where nothing has to be guessed.
+ * With two, the source is exactly what the resolve was going to tell us, and picking the
+ * first-registered one would attach a Zeplin screen to Figma's key space. Then the honest answer
+ * is to say the check could not be made and let the person retry.
+ */
+const target = computed<DocumentSourceKind | null>(() => {
+  if (claimant.value) return claimant.value
+  if (state.value.status !== 'unchecked') return null
+  return sources.value.length === 1 ? (sources.value[0] ?? null) : null
+})
+
+/**
+ * Ask each connected design source in turn and keep the FIRST that claims the paste.
+ *
+ * Sequential rather than parallel: the sources are ordered by how much a claim over a URL is
+ * worth, and running them together would make the winner whichever answered first. A refusal from
+ * one source is not a refusal of the paste, so only the LAST one is surfaced when nobody claims
+ * it — that is the state where the person genuinely has to change something.
+ */
+async function resolve() {
+  const text = pasted.value.trim()
+  // Already judged, so there is nothing to learn and a verdict to lose (see `resolvedFor`).
+  if (text === resolvedFor.value) return
+  claimant.value = null
+  if (!text) {
+    state.value = { status: 'none' }
+    resolvedFor.value = null
+    return
+  }
+  state.value = { status: 'checking' }
+  let last: RefState = { status: 'rejected', reason: 'document_ref_unrecognized' }
+  for (const source of sources.value) {
+    try {
+      const ref: ResolvedDocumentRef = await documents.resolveRef(source, text)
+      claimant.value = source
+      state.value = { status: 'ok', ref }
+      resolvedFor.value = text
+      return
+    } catch (e) {
+      last = classifyRefFailure(e)
+      // An outage leaves the paste UNJUDGED rather than refused, and asking the next source
+      // would turn one source being down into a different source's verdict.
+      if (last.status === 'unchecked') break
+    }
+  }
+  state.value = last
+  // A refusal and an outage are verdicts too: re-running on the same text would reach the same
+  // one, and an `unchecked` paste is stageable, so it must survive the blur Continue causes.
+  resolvedFor.value = text
+}
+
+/**
+ * Hand the resolved reference to the add-task form as a staged attachment.
+ *
+ * `needsImport` is true because nothing has been fetched yet: the form's own pre-create resolve
+ * (`useContextLinking().resolvePending`) performs the import, which is where an unreachable page
+ * becomes a correction the author can still make. Importing here as well would spend the fetch
+ * twice and move the failure back before the form exists.
+ */
+function stage() {
+  const frame = ui.startFromDesign
+  const resolved = row.value
+  const source = target.value
+  if (!frame || !resolved || !source) return
+  const descriptor = documents.descriptorFor(source)
+  ui.closeStartFromDesign()
+  ui.openAddTask(frame.frameId, {
+    context: [
+      {
+        kind: 'document',
+        source,
+        externalId: resolved.externalId,
+        title: resolved.label,
+        subtitle: descriptor?.label,
+        icon: descriptor?.icon,
+        needsImport: true,
+      },
+    ],
+  })
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('documents.startFromDesign.title')">
+    <template #body>
+      <div class="space-y-4">
+        <p class="text-sm text-slate-400">{{ t('documents.startFromDesign.intro') }}</p>
+
+        <!-- No connected design source: the flow cannot run, and saying which step is missing
+             beats an input that refuses every paste. The connect route is withheld from a member
+             for the same reason the picker's add tier is: connecting stores a credential. -->
+        <p v-if="sources.length === 0" class="text-sm text-amber-300">
+          {{ t('documents.startFromDesign.noSource') }}
+        </p>
+
+        <template v-else>
+          <UFormField :label="t('documents.startFromDesign.linkLabel')">
+            <UInput
+              v-model="pasted"
+              :placeholder="t('documents.startFromDesign.linkPlaceholder')"
+              class="w-full"
+              data-testid="start-from-design-link"
+              @blur="resolve"
+              @keyup.enter="resolve"
+            />
+          </UFormField>
+
+          <div
+            v-if="state.status === 'checking'"
+            class="flex items-center gap-2 text-sm text-slate-400"
+          >
+            <UIcon name="i-lucide-loader" class="h-4 w-4 animate-spin" />
+            {{ t('documents.startFromDesign.checking') }}
+          </div>
+
+          <div
+            v-else-if="row"
+            class="space-y-1 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            data-testid="start-from-design-resolved"
+          >
+            <div class="flex items-center gap-2 text-sm text-white">
+              <UIcon name="i-lucide-frame" class="h-4 w-4 text-indigo-400" />
+              <span class="truncate">{{ row.label }}</span>
+            </div>
+            <p v-if="row.trimmed" class="text-[11px] text-slate-400">
+              {{ t('documents.startFromDesign.trimmed') }}
+            </p>
+            <!-- Its own line, in amber: a trim resolves the same page, a drop widens ONE frame to
+                 the whole design file, and the second is what a designer needs to see. -->
+            <p v-if="row.droppedScope" class="text-[11px] text-amber-300">
+              {{ t('documents.startFromDesign.widened', { scope: row.droppedScope }) }}
+            </p>
+            <p v-if="row.unchecked && target" class="text-[11px] text-slate-400">
+              {{ t('documents.startFromDesign.unchecked') }}
+            </p>
+            <p v-else-if="row.unchecked" class="text-[11px] text-amber-300">
+              {{ t('documents.startFromDesign.uncheckedAmbiguous') }}
+            </p>
+          </div>
+
+          <p
+            v-else-if="state.status === 'rejected'"
+            class="text-sm text-amber-300"
+            data-testid="start-from-design-rejected"
+          >
+            {{ t('documents.startFromDesign.rejected') }}
+          </p>
+        </template>
+
+        <div class="flex justify-end gap-2 pt-1">
+          <UButton color="neutral" variant="ghost" @click="ui.closeStartFromDesign()">
+            {{ t('common.cancel') }}
+          </UButton>
+          <UButton
+            color="primary"
+            icon="i-lucide-arrow-right"
+            :disabled="!row || !target"
+            data-testid="start-from-design-continue"
+            @click="stage"
+          >
+            {{ t('documents.startFromDesign.continue') }}
+          </UButton>
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/layout/AccountDeploymentSettings.vue

@@ -39,9 +39,14 @@ watch(
 
 const slack = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
 const linear = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
+// The deployment's registered Figma app, which is what turns "Connect with Figma" on for every
+// board in the account. Without it the Figma document source still connects, by personal access
+// token — which is the step this exists to spare a designer.
+const figma = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
 const web = reactive({ braveApiKey: '', searxngUrl: '', searxngApiKey: '' })
 const savingSlack = ref(false)
 const savingLinear = ref(false)
+const savingFigma = ref(false)
 const savingWeb = ref(false)
 
 const summary = computed(() => store.view?.summary ?? null)
@@ -289,6 +294,62 @@ async function clearLinear() {
   }
 }
 
+async function saveFigma() {
+  if (!figma.clientId.trim() || !figma.clientSecret.trim() || !figma.redirectUrl.trim()) {
+    toast.add({ title: t('layout.accountDeployment.figma.validation'), color: 'error' })
+    return
+  }
+  savingFigma.value = true
+  try {
+    await store.save(props.accountId, {
+      secrets: {
+        figmaOAuth: {
+          clientId: figma.clientId.trim(),
+          clientSecret: figma.clientSecret.trim(),
+          redirectUrl: figma.redirectUrl.trim(),
+        },
+      },
+    })
+    figma.clientId = ''
+    figma.clientSecret = ''
+    figma.redirectUrl = ''
+    toast.add({
+      title: t('layout.accountDeployment.figma.saved'),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
+  } catch (e) {
+    toast.add({
+      title: t('layout.accountDeployment.figma.saveFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    savingFigma.value = false
+  }
+}
+
+async function clearFigma() {
+  if (!(await confirmAction('clear', 'Figma'))) return
+  savingFigma.value = true
+  try {
+    await store.save(props.accountId, { secrets: { figmaOAuth: null } })
+    toast.add({
+      title: t('layout.accountDeployment.figma.cleared'),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
+  } catch (e) {
+    toast.add({
+      title: t('layout.accountDeployment.figma.clearFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    savingFigma.value = false
+  }
+}
+
 async function saveWeb() {
   const brave = web.braveApiKey.trim()
   const searxng = web.searxngUrl.trim()
@@ -479,6 +540,67 @@ async function clearWeb() {
       </div>
     </section>
 
+    <!-- Figma app OAuth (the document source's designer-doable connect) -->
+    <section class="space-y-2 border-t border-slate-800 pt-6">
+      <div class="flex items-center gap-2">
+        <h4 class="text-sm font-semibold text-slate-200">
+          {{ t('layout.accountDeployment.figma.title') }}
+        </h4>
+        <UBadge
+          :color="summary?.figmaOAuthConfigured ? 'success' : 'neutral'"
+          variant="subtle"
+          size="xs"
+        >
+          {{
+            summary?.figmaOAuthConfigured
+              ? t('layout.accountDeployment.configured')
+              : t('layout.accountDeployment.notSet')
+          }}
+        </UBadge>
+      </div>
+      <p class="text-[11px] text-slate-400">
+        {{ t('layout.accountDeployment.figma.description') }}
+      </p>
+      <div class="grid grid-cols-1 gap-2 sm:grid-cols-3">
+        <UInput
+          v-model="figma.clientId"
+          :placeholder="t('layout.accountDeployment.figma.clientId')"
+          size="sm"
+        />
+        <SecretInput
+          v-model="figma.clientSecret"
+          :placeholder="t('layout.accountDeployment.figma.clientSecret')"
+          size="sm"
+        />
+        <UInput
+          v-model="figma.redirectUrl"
+          :placeholder="t('layout.accountDeployment.figma.redirectUrl')"
+          size="sm"
+        />
+      </div>
+      <div class="flex gap-2">
+        <UButton
+          color="primary"
+          size="xs"
+          icon="i-lucide-save"
+          :loading="savingFigma"
+          @click="saveFigma"
+        >
+          {{ t('common.save') }}
+        </UButton>
+        <UButton
+          v-if="summary?.figmaOAuthConfigured"
+          color="neutral"
+          variant="ghost"
+          size="xs"
+          :loading="savingFigma"
+          @click="clearFigma"
+        >
+          {{ t('layout.accountDeployment.clear') }}
+        </UButton>
+      </div>
+    </section>
+
     <!-- Web search keys -->
     <section class="space-y-2 border-t border-slate-800 pt-6">
       <div class="flex items-center gap-2">

package/app/composables/api/documents.ts

@@ -1,6 +1,7 @@
 import {
   connectDocumentSourceContract,
   disconnectDocumentSourceContract,
+  documentSourceOAuthUrlContract,
   importDocumentContract,
   linkDocumentContract,
   linkDocumentForKindContract,
@@ -41,6 +42,14 @@ export function documentsApi({ send, ws }: ApiContext) {
         body: { credentials },
       }),
 
+    // The vendor authorization URL for a source's OAuth connect. Admin-tier: what it hands back
+    // is the first half of a credential write, completed by the public callback.
+    documentSourceOAuthUrl: (workspaceId: string, source: DocumentSourceKind) =>
+      send(documentSourceOAuthUrlContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
+      }),
+
     disconnectDocumentSource: (workspaceId: string, source: DocumentSourceKind) =>
       send(disconnectDocumentSourceContract, {
         pathPrefix: ws(workspaceId),
@@ -77,12 +86,14 @@ export function documentsApi({ send, ws }: ApiContext) {
         body: { query },
       }),
 
-    planDocument: (workspaceId: string, source: DocumentSourceKind, externalId: string) =>
-      send(planDocumentContract, {
-        pathPrefix: ws(workspaceId),
-        pathParams: { source },
-        body: { externalId },
-      }),
+    // `frameId` makes the plan TARGET-AWARE: modules and tasks for a service that already exists
+    // rather than an architecture. The same frame is sent to the spawn, so the preview and the
+    // write agree about the target.
+    planDocument: (
+      workspaceId: string,
+      source: DocumentSourceKind,
+      body: { externalId: string; frameId?: string },
+    ) => send(planDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
     spawnDocument: (
       workspaceId: string,

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/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',