@cat-factory/app 0.248.0 → 0.249.0

package/app/components/board/AddTaskModal.vue

@@ -1230,6 +1230,7 @@ function openReviewFrictionDialog(conflict: NonNullable<ReturnType<typeof parseC
             v-if="ui.addTaskContainerId"
             v-model="pendingContext"
             :scope-block-id="ui.addTaskContainerId"
+            :description="description"
             :docs-hint="t('board.addTask.noDocsHint')"
             :issues-hint="t('board.addTask.noIssuesHint')"
           />

package/app/components/board/nodes/BlockNode.vue

@@ -20,6 +20,7 @@ const board = useBoardStore()
 const execution = useExecutionStore()
 const ui = useUiStore()
 const tasks = useTasksStore()
+const documents = useDocumentsStore()
 const agentRuns = useAgentRunsStore()
 const services = useServicesStore()
 const reviews = useReviewStage()
@@ -161,6 +162,18 @@ function addRecurring() {
   ui.openAddRecurring(props.id)
 }
 
+/**
+ * Start a task from a design link, scoped to THIS service.
+ *
+ * BASIC tier, unlike the recurring/initiative buttons beside it: for a design-led team this is
+ * the everyday delivery loop rather than planning about it, which is the tier bar. It is offered
+ * only where a design source is actually connected, so a board that has none carries no control
+ * whose first click is a dead end.
+ */
+function startFromDesign() {
+  ui.openStartFromDesign(props.id)
+}
+
 // Hunt this service's tracker board for a bug worth picking up. Scoped to THIS frame, so
 // an adopted candidate lands here rather than wherever the board's first frame happens to be.
 function huntBugs() {
@@ -410,6 +423,17 @@ const ITEM_ICON: Record<string, string> = {
                   :title="t('board.frame.createTaskFromIssueTitle')"
                   @click.stop="createTaskFromIssue"
                 />
+                <UButton
+                  v-if="documents.connectedDesignSources.length > 0"
+                  class="nodrag"
+                  data-testid="frame-start-from-design"
+                  :size="isTouch ? 'sm' : 'xs'"
+                  variant="ghost"
+                  color="neutral"
+                  icon="i-lucide-frame"
+                  :title="t('board.frame.startFromDesignTitle')"
+                  @click.stop="startFromDesign"
+                />
                 <!-- Recurring pipelines + initiatives are ADVANCED-tier authoring: both plan
                      work rather than do it (a schedule that fires runs on a cadence, an
                      initiative that groups tasks under a goal), and the basic frame header is

package/app/components/context/ContextAttachmentFields.vue

@@ -14,7 +14,10 @@
 // root-mounted with independent open flags), so in-progress form data survives. That upgrade is
 // itself gated on `integrations.manage` for documents, whose ATTACH writes are member-tier while
 // storing the credential is not.
+import { refDebounced } from '@vueuse/core'
+import type { DocumentSourceKind } from '~/types/domain'
 import type { PendingContext } from '~/composables/useContextLinking'
+import { claimCandidates, firstLinkCandidate } from '~/components/context/pastedLinkOffer.logic'
 import { connectableSources } from '~/utils/sourcePicker'
 import ContextDocumentPicker from '~/components/documents/ContextDocumentPicker.vue'
 import ContextIssuePicker from '~/components/tasks/ContextIssuePicker.vue'
@@ -32,6 +35,11 @@ const props = defineProps<{
    * service's linked repo, so there is no unscoped mode to fall back on.
    */
   scopeBlockId: string
+  /**
+   * The description the author is writing, watched for a pasted link worth attaching. Optional:
+   * a host with no description field simply never offers.
+   */
+  description?: string
 }>()
 
 const emit = defineEmits<{ 'update:modelValue': [PendingContext[]] }>()
@@ -89,6 +97,80 @@ const chosenDocKeys = computed(() => pendingDocs.value.map(contextKey))
 const showIssuePicker = ref(false)
 const chosenIssueKeys = computed(() => pendingIssues.value.map(contextKey))
 
+// ---- the pasted-link offer ------------------------------------------------------------------
+// A URL named in a description already reaches the run path, where an UNIMPORTED one is dropped
+// with an info line and the agent gets nothing from it. Offering to attach it here turns that
+// silent drop into a decision the author can still make. Only HOST-PINNED sources are asked
+// (`claimCandidates`), because a host-blind parser claims a shape rather than a reference.
+const offer = ref<{ url: string; source: DocumentSourceKind; externalId: string } | null>(null)
+/** The URL last resolved, so re-typing around an unchanged link costs no further round trips. */
+let judged: string | null = null
+/**
+ * Which link-resolution pass is the current one. A pass that has been superseded neither writes an
+ * offer nor spends another request.
+ *
+ * `judged` alone cannot do this: it is set BEFORE the awaits, so it stops a second pass starting
+ * for the same URL but says nothing about a pass already in flight for a DIFFERENT one. The
+ * description is a text field a person is still typing in, and the debounce releases a new pass
+ * every 500ms, so an earlier URL's resolve routinely settles after a later one. Landing it would
+ * offer to attach a link that is no longer in the description at all, and accepting the offer
+ * attaches that wrong document, silently: the chip it adds names the stale URL, which is the only
+ * place the mismatch is visible and the one part nobody re-reads.
+ */
+let offerPass = 0
+
+// Debounced, because this fires on every keystroke of a description and each miss costs one
+// request per connected host-pinned source.
+const debouncedDescription = refDebounced(
+  computed(() => props.description ?? ''),
+  500,
+)
+
+watch(
+  debouncedDescription,
+  async (text) => {
+    const url = firstLinkCandidate(text)
+    if (url === judged) return
+    const pass = ++offerPass
+    judged = url
+    offer.value = null
+    if (!url || !documents.available) return
+    for (const source of claimCandidates(documents.connectedSources.map((s) => s.source))) {
+      // Checked per source, not just around the write: once superseded, the remaining sources
+      // would be asked about a URL nobody is looking at any more.
+      if (pass !== offerPass) return
+      try {
+        const ref = await documents.resolveRef(source, url)
+        if (pass !== offerPass) return
+        offer.value = { url, source, externalId: ref.externalId }
+        return
+      } catch {
+        // silent-catch-ok: a source that refuses (or cannot be reached) simply makes no offer.
+        // There is nothing to report — the paste stays in the description exactly as typed, and
+        // the attach picker above is the route for anything this could not judge.
+      }
+    }
+  },
+  { immediate: true },
+)
+
+/** Stage the offered link, then withdraw the offer: it is now a chip in the list below. */
+function acceptOffer() {
+  const accepted = offer.value
+  if (!accepted) return
+  const descriptor = documents.descriptorFor(accepted.source)
+  addPending({
+    kind: 'document',
+    source: accepted.source,
+    externalId: accepted.externalId,
+    title: accepted.url,
+    subtitle: descriptor?.label,
+    icon: descriptor?.icon,
+    needsImport: true,
+  })
+  offer.value = null
+}
+
 function addPending(item: PendingContext) {
   if (props.modelValue.some((c) => contextKey(c) === contextKey(item))) return
   emit('update:modelValue', [...props.modelValue, item])
@@ -160,6 +242,26 @@ function removePending(item: PendingContext) {
           {{ t('contextAttachments.attach') }}
         </UButton>
       </div>
+      <!-- Offered, never applied: the author wrote the link into prose, and silently turning
+           that into an attachment would attach pages nobody meant to attach. -->
+      <div
+        v-if="offer && docsConnected"
+        class="flex items-center gap-2 rounded-md border border-indigo-900/60 bg-indigo-950/30 px-2 py-1.5"
+        data-testid="pasted-link-offer"
+      >
+        <UIcon name="i-lucide-link" class="h-3.5 w-3.5 shrink-0 text-indigo-400" />
+        <span class="min-w-0 flex-1 truncate text-xs text-slate-300">
+          {{
+            t('contextAttachments.pastedLink.offer', {
+              source: documents.descriptorFor(offer.source)?.label ?? offer.source,
+            })
+          }}
+        </span>
+        <UButton color="primary" variant="soft" size="xs" @click="acceptOffer">
+          {{ t('contextAttachments.pastedLink.attach') }}
+        </UButton>
+      </div>
+
       <ContextDocumentPicker
         v-if="showDocPicker && docsConnected"
         :chosen-keys="chosenDocKeys"

package/app/components/context/pastedLinkOffer.logic.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { claimCandidates, firstLinkCandidate } from './pastedLinkOffer.logic'
+
+describe('firstLinkCandidate', () => {
+  it('picks a URL out of prose and drops the punctuation the sentence left on it', () => {
+    expect(
+      firstLinkCandidate('Build the screen at https://www.figma.com/design/abc?node-id=1-2.'),
+    ).toBe('https://www.figma.com/design/abc?node-id=1-2')
+    expect(firstLinkCandidate('see [design](https://www.figma.com/design/abc), then ship')).toBe(
+      'https://www.figma.com/design/abc',
+    )
+  })
+
+  it('answers null for text with no link, and takes only the FIRST of several', () => {
+    expect(firstLinkCandidate('make the button green')).toBeNull()
+    // One chip beside a field cannot answer "which of these did you mean", and guessing is
+    // worse than sending the author to the attach picker, which is still right there.
+    expect(firstLinkCandidate('https://a.test/one and https://b.test/two')).toBe(
+      'https://a.test/one',
+    )
+  })
+})
+
+describe('claimCandidates', () => {
+  it('asks only HOST-PINNED sources, whatever else is connected', () => {
+    // Notion's parser claims any UUID-shaped run, so asked about a Figma link whose file key
+    // happens to carry one it answers yes — and the offer would stage a design into Notion's key
+    // space. Registration order is preserved for the ones that remain.
+    expect(claimCandidates(['notion', 'figma', 'confluence', 'zeplin'])).toEqual([
+      'figma',
+      'zeplin',
+    ])
+    expect(claimCandidates(['notion', 'confluence'])).toEqual([])
+  })
+})

package/app/components/context/pastedLinkOffer.logic.ts

@@ -0,0 +1,50 @@
+import { isHostPinnedSource } from '@cat-factory/contracts'
+import type { DocumentSourceKind } from '~/types/domain'
+
+// The pure half of "you pasted a link into the description; want it attached?".
+//
+// A URL named in a task description already reaches the run path, where an UNIMPORTED one is
+// dropped with an info line and the agent gets no context from it. This offer is what turns that
+// drop into an attachment while the author is still on the form. What makes it safe to offer at
+// all is the same rule the canonicaliser and the refusal-claimant search follow: only a
+// HOST-PINNED source may claim a URL, because a host-blind parser claims a SHAPE and will happily
+// claim a dashboard link that has nothing to do with it.
+
+/** How much text is scanned for a link. Bounded: this runs as someone types a description. */
+const MAX_SCANNED_CHARS = 4000
+
+/**
+ * Trailing characters a URL written in prose collects, stripped so the offer resolves the link
+ * rather than the sentence it sits in. Brackets and quotes come in Markdown link syntax.
+ */
+const TRAILING_NOISE = /[)\]}>.,;:!?'"]+$/
+
+/**
+ * The first `http(s)` URL in `text`, or null.
+ *
+ * FIRST rather than all of them: the offer is one chip beside a form field, and a description
+ * naming five links needs the attach picker, not five chips. Someone who pasted the design link
+ * second can still attach it there, so nothing is lost by declining to guess which of many was
+ * meant.
+ */
+export function firstLinkCandidate(text: string): string | null {
+  const match = /https?:\/\/[^\s<>"']+/i.exec(text.slice(0, MAX_SCANNED_CHARS))
+  if (!match) return null
+  const trimmed = match[0].replace(TRAILING_NOISE, '')
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * The sources worth ASKING about a pasted URL: connected, and host-pinned.
+ *
+ * Host-pinned is not an optimisation here, it is the whole safety property. Asking Notion (whose
+ * parser claims any UUID-shaped run) about a Figma link gets a confident yes, and the offer would
+ * then stage a design against Notion's key space — the exact mis-attribution
+ * `orderSourcesByClaimConfidence` exists to prevent on every other surface. Sources arrive in
+ * registry order and stay in it, so two pinned sources are asked in a stable order.
+ */
+export function claimCandidates(
+  connected: readonly DocumentSourceKind[],
+): readonly DocumentSourceKind[] {
+  return connected.filter(isHostPinnedSource)
+}

package/app/components/documents/DocumentSourceConnectModal.vue

@@ -4,6 +4,13 @@
 // same modal serves Confluence, Notion and any future source. Secret credentials
 // are write-only — the backend never returns them, so on reload we show
 // "Connected" with empty fields.
+//
+// A source that declares an OAuth half AND has a registered app on this deployment leads with
+// "Connect with <source>", and the credential form moves BELOW it as the fallback. That order is
+// the point of the slice: minting a personal access token by hand is an unreasonable first step
+// to put in front of a designer, and whichever affordance comes first is the one people use.
+// Where no app is registered the button is absent entirely rather than disabled, because the
+// remedy belongs to an admin in a different surface and a dead control states nothing.
 import IntegrationBackTitle from '~/components/layout/IntegrationBackTitle.vue'
 import SecretInput from '~/components/common/SecretInput.vue'
 
@@ -33,6 +40,33 @@ const back = useIntegrationBack(open)
 /** One value per credential field, reset whenever the modal (re)opens. */
 const values = ref<Record<string, string>>({})
 const saving = ref(false)
+const startingOAuth = ref(false)
+
+/** The OAuth half is offered only when the SOURCE declares one and this deployment registered an app. */
+const oauth = computed(() =>
+  source.value && descriptor.value?.oauth && documents.canConnectWithOAuth(source.value)
+    ? descriptor.value.oauth
+    : null,
+)
+
+async function connectWithOAuth() {
+  if (!source.value) return
+  startingOAuth.value = true
+  try {
+    // Navigates away on success, so nothing after this runs; the `finally` covers the refusal
+    // path (an app un-registered between the probe and the click).
+    await documents.beginOAuthConnect(source.value)
+  } catch (e) {
+    toast.add({
+      title: t('documents.connect.oauth.failed', { source: descriptor.value?.label ?? '' }),
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    startingOAuth.value = false
+  }
+}
 
 watch(open, (isOpen) => {
   if (isOpen) values.value = {}
@@ -97,6 +131,22 @@ async function disconnect() {
           {{ t('documents.connect.intro', { source: descriptor.label }) }}
         </p>
 
+        <div v-if="oauth" class="space-y-2">
+          <UButton
+            color="primary"
+            icon="i-lucide-shield-check"
+            :loading="startingOAuth"
+            data-testid="document-connect-oauth"
+            @click="connectWithOAuth"
+          >
+            {{ t('documents.connect.oauth.action', { source: descriptor.label }) }}
+          </UButton>
+          <p class="text-[11px] text-slate-500">
+            {{ t('documents.connect.oauth.scopes', { scopes: oauth.scopes.join(', ') }) }}
+          </p>
+          <p class="text-[11px] text-slate-500">{{ t('documents.connect.oauth.fallback') }}</p>
+        </div>
+
         <div class="space-y-3">
           <UFormField
             v-for="field in descriptor.credentialFields"

package/app/components/documents/SpawnPreviewModal.vue

@@ -1,21 +1,30 @@
 <script setup lang="ts">
+import { isDesignSource } from '@cat-factory/contracts'
 import type { DocumentBoardPlan } from '~/types/domain'
 
 // Preview the structure an imported document expands into, then spawn it. The
 // plan is fetched fresh on open; a badge makes clear whether an LLM or the
 // deterministic heading parser produced it.
 //
-// A spawn always creates new top-level frames. The planner's job is to decompose a
-// document into services, so spawning into an existing frame could only flatten the
-// planned frames into it — silently discarding the frame titles and types rendered
-// below, i.e. producing something other than what this preview showed. Scoping a
-// spawn to one service needs a target-aware PLAN (a prompt that yields modules and
-// tasks for an existing service), not a target-aware write.
+// A PROSE document spawns new top-level frames: the planner's job there is to decompose a
+// specification into services. A DESIGN document cannot answer that question — it describes
+// screens, and asked for an architecture it produces a service per Figma page — so it is planned
+// INTO a service that already exists, and the frame picker below is required before a plan is
+// even requested. The frame is then sent to the spawn as well, so the write re-plans against the
+// same target and nothing the preview showed is discarded.
 const { t } = useI18n()
 const ui = useUiStore()
+const board = useBoardStore()
 const documents = useDocumentsStore()
 const toast = useToast()
 
+/** Design documents are planned into an existing service; prose documents at the board root. */
+const needsTarget = computed(() => !!ui.spawnPreview && isDesignSource(ui.spawnPreview.source))
+const targetFrameId = ref<string | undefined>()
+const frameOptions = computed(() =>
+  board.frames.map((frame) => ({ label: frame.title, value: frame.id })),
+)
+
 const open = computed({
   get: () => ui.spawnPreview !== null,
   set: (v: boolean) => {
@@ -27,16 +36,50 @@ const plan = ref<DocumentBoardPlan | null>(null)
 const loadingPlan = ref(false)
 const spawning = ref(false)
 
+// Declared BEFORE the planning watcher so it runs first: a target picked for the previous
+// document must not survive into the next one, where it would silently plan a different design
+// into a service nobody chose for it.
 watch(
   () => ui.spawnPreview?.externalId,
-  async (externalId) => {
+  () => {
+    targetFrameId.value = undefined
+  },
+)
+
+/**
+ * Which re-plan is the current one. Each request supersedes the one before it, and a superseded
+ * response is DROPPED rather than rendered.
+ *
+ * Two requests are genuinely in flight whenever the target is switched while a plan is still
+ * loading, and an LLM plan takes long enough for that to be ordinary rather than a stress case.
+ * The responses can land in either order, so without this the OLDER frame's plan can overwrite the
+ * newer one and sit under a selection it was not authored for: the preview then disagrees with the
+ * write, which re-plans against the target the user actually picked. That disagreement is the one
+ * thing the target-aware path exists to prevent, and it is silent, because a plan for the wrong
+ * service looks exactly like a plan.
+ */
+let planRequest = 0
+
+// The preview re-plans whenever the TARGET moves, not only when the document does: a plan
+// authored for one service says nothing about another, and leaving the previous frame's modules
+// on screen under a newly-picked service is the misreading this whole variant exists to prevent.
+watch(
+  [() => ui.spawnPreview?.externalId, targetFrameId],
+  async ([externalId]) => {
+    const request = ++planRequest
     plan.value = null
     const preview = ui.spawnPreview
     if (!externalId || !preview) return
+    if (needsTarget.value && !targetFrameId.value) return
     loadingPlan.value = true
     try {
-      plan.value = await documents.plan(preview.source, externalId)
+      const planned = await documents.plan(preview.source, externalId, targetFrameId.value)
+      if (request !== planRequest) return
+      plan.value = planned
     } catch (e) {
+      // A superseded request's failure is not this selection's failure: toasting it would report an
+      // outage against a target whose own plan may be loading fine.
+      if (request !== planRequest) return
       toast.add({
         title: t('documents.spawn.planFailed'),
         description: e instanceof Error ? e.message : String(e),
@@ -44,7 +87,9 @@ watch(
         color: 'error',
       })
     } finally {
-      loadingPlan.value = false
+      // Only the current request may clear the spinner; an older one settling first would report
+      // "loaded" over a plan still on its way.
+      if (request === planRequest) loadingPlan.value = false
     }
   },
   { immediate: true },
@@ -55,14 +100,20 @@ async function spawn() {
   if (!preview) return
   spawning.value = true
   try {
-    const result = await documents.spawn(preview.source, preview.externalId)
+    const result = await documents.spawn(preview.source, preview.externalId, targetFrameId.value)
+    const summary = t('documents.spawn.summary', {
+      frames: t('documents.spawn.frameCount', { count: result.frames }, result.frames),
+      modules: t('documents.spawn.moduleCount', { count: result.modules }, result.modules),
+      tasks: t('documents.spawn.taskCount', { count: result.tasks }, result.tasks),
+    })
     toast.add({
       title: t('documents.spawn.spawned'),
-      description: t('documents.spawn.summary', {
-        frames: t('documents.spawn.frameCount', { count: result.frames }, result.frames),
-        modules: t('documents.spawn.moduleCount', { count: result.modules }, result.modules),
-        tasks: t('documents.spawn.taskCount', { count: result.tasks }, result.tasks),
-      }),
+      // A reused module is stated only when there was one, and never folded into the created
+      // count: a spawn into a service that already had every planned module otherwise reports
+      // "0 modules" beside its tasks, which reads as the modules having failed.
+      description: result.reusedModules
+        ? `${summary} · ${t('documents.spawn.reusedCount', { count: result.reusedModules }, result.reusedModules)}`
+        : summary,
       icon: 'i-lucide-check',
       color: 'success',
     })
@@ -97,9 +148,34 @@ async function spawn() {
                 : t('documents.spawn.plannerHeadings')
             }}
           </UBadge>
-          <span class="text-xs text-slate-400">{{ t('documents.spawn.asTopLevel') }}</span>
+          <span class="text-xs text-slate-400">{{
+            plan.targetFrameId ? t('documents.spawn.intoService') : t('documents.spawn.asTopLevel')
+          }}</span>
         </div>
 
+        <UFormField
+          v-if="needsTarget"
+          :label="t('documents.spawn.target.label')"
+          :help="t('documents.spawn.target.help')"
+        >
+          <USelectMenu
+            v-model="targetFrameId"
+            :items="frameOptions"
+            value-key="value"
+            :placeholder="t('documents.spawn.target.placeholder')"
+            class="w-full"
+            data-testid="spawn-target-frame"
+          />
+        </UFormField>
+
+        <p
+          v-if="needsTarget && !targetFrameId"
+          class="text-xs text-slate-400"
+          data-testid="spawn-target-required"
+        >
+          {{ t('documents.spawn.target.required') }}
+        </p>
+
         <div v-if="loadingPlan" 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.spawn.buildingPlan') }}