@cat-factory/app 0.94.0 → 0.95.0

package/app/components/github/AddServiceFromRepoModal.vue

@@ -10,9 +10,9 @@
 // pinned to a subdirectory. When the selected repo is a monorepo, the user
 // browses its tree and picks the service's directory before adding (and may add
 // more than one, a subset of the repo's services).
-import { refDebounced } from '@vueuse/core'
 import type { FrameRepoType, GitHubAvailableRepo } from '~/types/domain'
 import GitHubConnect from '~/components/github/GitHubConnect.vue'
+import RepoSearchEmpty from '~/components/github/RepoSearchEmpty.vue'
 import RepoTreeBrowser from '~/components/github/RepoTreeBrowser.vue'
 import ServiceTestConfig from '~/components/panels/inspector/ServiceTestConfig.vue'
 import ServiceFragments from '~/components/panels/inspector/ServiceFragments.vue'
@@ -89,33 +89,27 @@ function toRepoItem(r: GitHubAvailableRepo) {
   return { label: `${r.owner}/${r.name}${suffix}`, value: r.githubId, disabled: onBoard }
 }
 
-const repoItems = computed(() => github.availableRepos.map(toRepoItem))
-
-// A wide App install (or a PAT) can expose hundreds of repos, far too many to prefetch and
-// filter in the browser — so the picker searches SERVER-SIDE. Nothing is fetched on open;
-// once the user types at least MIN_SEARCH_LEN characters the (debounced) query is sent to
-// the backend, which returns only the `owner/name` matches. Below the gate the list stays
-// empty and the field prompts for more characters.
-const MIN_SEARCH_LEN = 3
-const repoSearch = ref('')
-const repoSearchDebounced = refDebounced(repoSearch, 250)
-// Trimmed for display + the min-length gate; the backend matches case-insensitively.
-const repoQueryRaw = computed(() => repoSearchDebounced.value.trim())
-
-// True while the query is too short to search — the picker shows the "type N chars" hint.
-const belowMinChars = computed(() => repoQueryRaw.value.length < MIN_SEARCH_LEN)
+// Server-side, debounced, min-length-gated repo search (a wide App install / PAT can expose
+// hundreds of repos, too many to prefetch and filter in the browser). Shared with the doc-task
+// reference-repo picker via `useRepoSearch`; `repoResults` is this picker's own result list, so
+// the two never clobber each other. Nothing is fetched on open — the field prompts for more
+// characters below the gate; granting the App access needs no manual refresh (the next search
+// hits GitHub live).
+const {
+  search: repoSearch,
+  query: repoQueryRaw,
+  belowMinChars,
+  results: repoResults,
+  loading: repoLoading,
+  reset: resetRepoSearch,
+} = useRepoSearch()
+
+const repoItems = computed(() => repoResults.value.map(toRepoItem))
 
 // The selected repo, captured when picked (below). The loaded list is volatile — a later
-// search replaces it — so the selection can't be derived from `availableRepos` after the fact.
+// search replaces it — so the selection can't be derived from the results after the fact.
 const selectedRepo = ref<GitHubAvailableRepo | undefined>(undefined)
 
-// Fetch matches server-side as the debounced query changes; below the gate clear the list
-// so stale matches don't linger (the hint shows instead). Granting the App access needs no
-// manual refresh — the next search hits GitHub live, with no cached list to invalidate.
-watch(repoQueryRaw, (q) => {
-  void github.loadAvailableRepos(q.length >= MIN_SEARCH_LEN ? q : '')
-})
-
 // The server already filtered, so the matches ARE the loaded repos (empty below the gate).
 const queryMatches = computed(() => (belowMinChars.value ? [] : repoItems.value))
 
@@ -148,7 +142,7 @@ function toggleMonorepo(value: boolean) {
 watch(selectedRepoId, (id) => {
   if (id === undefined) selectedRepo.value = undefined
   else {
-    const found = github.availableRepos.find((r) => r.githubId === id)
+    const found = repoResults.value.find((r) => r.githubId === id)
     if (found) selectedRepo.value = found
   }
   isMonorepo.value = selectedRepo.value?.isMonorepo === true
@@ -161,7 +155,7 @@ function resetSelection() {
   selectedDirectory.value = undefined
   isMonorepo.value = false
   configuredBlockId.value = undefined
-  repoSearch.value = ''
+  resetRepoSearch()
   selectedType.value = 'service'
 }
 
@@ -296,7 +290,7 @@ function done() {
                 :items="repoMenuItems"
                 :ignore-filter="true"
                 value-key="value"
-                :loading="github.loadingAvailable"
+                :loading="repoLoading"
                 icon="i-lucide-search"
                 :placeholder="t('github.addService.searchPlaceholder')"
                 class="w-full"
@@ -312,14 +306,11 @@ function done() {
                   />
                 </template>
                 <template #empty>
-                  <span v-if="belowMinChars">
-                    {{
-                      t('github.addService.searchMinChars', { min: MIN_SEARCH_LEN }, MIN_SEARCH_LEN)
-                    }}
-                  </span>
-                  <span v-else-if="!github.loadingAvailable">{{
-                    t('github.addService.noMatches', { query: repoQueryRaw })
-                  }}</span>
+                  <RepoSearchEmpty
+                    :below-min-chars="belowMinChars"
+                    :loading="repoLoading"
+                    :query="repoQueryRaw"
+                  />
                 </template>
               </UInputMenu>
             </div>

package/app/components/github/RepoSearchEmpty.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// The empty-state body shared by the GitHub repo pickers (the add-service modal and the doc-task
+// reference-repo picker), both driven by `useRepoSearch`: below the min-length gate it prompts for
+// more characters; otherwise (once a search has settled) it reports no matches. Kept as one
+// component so the two pickers can't drift on the empty-state copy or behaviour.
+import { REPO_SEARCH_MIN_LEN } from '~/composables/useRepoSearch'
+
+defineProps<{ belowMinChars: boolean; loading: boolean; query: string }>()
+
+const { t } = useI18n()
+</script>
+
+<template>
+  <span v-if="belowMinChars">
+    {{ t('github.addService.searchMinChars', { min: REPO_SEARCH_MIN_LEN }, REPO_SEARCH_MIN_LEN) }}
+  </span>
+  <span v-else-if="!loading">{{ t('github.addService.noMatches', { query }) }}</span>
+</template>

package/app/components/panels/inspector/DocReferenceRepos.vue

@@ -0,0 +1,144 @@
+<script setup lang="ts">
+// Reference repositories for a document-authoring task. The doc-writer agent clones each attached
+// repo READ-ONLY as a sibling checkout it may read (to reuse existing solutions as a reference)
+// while drafting — it never writes to them. Any repo the workspace's GitHub App (or the signed-in
+// user's PAT) can reach may be attached, so this reuses the SAME server-side, debounced repo
+// search as the add-service picker (`useRepoSearch`), not a filter over the synced projection.
+import type { Block, GitHubAvailableRepo, ReferenceRepo } from '~/types/domain'
+import RepoSearchEmpty from '~/components/github/RepoSearchEmpty.vue'
+
+const props = defineProps<{ block: Block }>()
+
+const { t } = useI18n()
+const github = useGitHubStore()
+const board = useBoardStore()
+
+const {
+  search: repoSearch,
+  query: repoQuery,
+  belowMinChars,
+  results: repoResults,
+  loading: repoLoading,
+  reset: resetRepoSearch,
+} = useRepoSearch()
+
+const attached = computed<ReferenceRepo[]>(() => props.block.referenceRepos ?? [])
+// Keyed by the provider-neutral repo id. The search results are `GitHubAvailableRepo`s (whose id
+// field is `githubId`), so a menu item's `githubId` is compared against this set of `repoId`s —
+// the same numeric id space on every provider.
+const attachedIds = computed(() => new Set(attached.value.map((r) => r.repoId)))
+
+// Menu items: the searched repos, an already-attached one disabled so it can't be added twice.
+const repoItems = computed(() =>
+  belowMinChars.value
+    ? []
+    : repoResults.value.map((r) => ({
+        label: `${r.owner}/${r.name}${r.personal ? t('github.addService.repoLabel.personal') : ''}`,
+        value: r.githubId,
+        disabled: attachedIds.value.has(r.githubId),
+      })),
+)
+
+// The picked repo id; watched to attach then clear (the combobox has no "add" affordance of its
+// own, so selecting a repo IS the attach action).
+const pickedId = ref<number | undefined>(undefined)
+
+watch(pickedId, (id) => {
+  if (id === undefined) return
+  const repo = repoResults.value.find((r) => r.githubId === id)
+  pickedId.value = undefined
+  if (!repo || attachedIds.value.has(id)) return
+  attach(repo)
+})
+
+function toReference(repo: GitHubAvailableRepo): ReferenceRepo {
+  return {
+    repoId: repo.githubId,
+    owner: repo.owner,
+    name: repo.name,
+    // A repo with no reported default branch is rare; fall back to `main` so the clone has a ref.
+    defaultBranch: repo.defaultBranch ?? 'main',
+    // A repo the workspace connection reaches carries that connection; a PAT-only (`personal`) repo
+    // has none, so the run clones it with the initiator's own token instead.
+    ...(repo.personal || !github.connection
+      ? {}
+      : { connectionId: github.connection.installationId }),
+  }
+}
+
+function attach(repo: GitHubAvailableRepo) {
+  board.updateBlock(props.block.id, {
+    referenceRepos: [...attached.value, toReference(repo)],
+  })
+  resetRepoSearch()
+}
+
+function detach(repoId: number) {
+  board.updateBlock(props.block.id, {
+    referenceRepos: attached.value.filter((r) => r.repoId !== repoId),
+  })
+}
+</script>
+
+<template>
+  <div data-testid="doc-reference-repos">
+    <div class="mb-1 flex items-center justify-between">
+      <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+        {{ t('inspector.referenceRepos.title') }}
+      </span>
+    </div>
+
+    <!-- Attached reference repos: chips with a remove control. -->
+    <div v-if="attached.length" class="mb-1.5 flex flex-wrap gap-1">
+      <UBadge
+        v-for="r in attached"
+        :key="r.repoId"
+        size="sm"
+        variant="soft"
+        color="neutral"
+        data-testid="reference-repo-chip"
+      >
+        {{ r.owner }}/{{ r.name }}
+        <UButton
+          color="neutral"
+          variant="link"
+          size="xs"
+          icon="i-lucide-x"
+          :aria-label="t('inspector.referenceRepos.remove', { repo: `${r.owner}/${r.name}` })"
+          data-testid="reference-repo-remove"
+          @click="detach(r.repoId)"
+        />
+      </UBadge>
+    </div>
+
+    <!-- The picker: only usable once the workspace's GitHub App is connected. -->
+    <UInputMenu
+      v-if="github.connected"
+      v-model="pickedId"
+      v-model:search-term="repoSearch"
+      :items="repoItems"
+      :ignore-filter="true"
+      value-key="value"
+      :loading="repoLoading"
+      icon="i-lucide-search"
+      :placeholder="t('github.addService.searchPlaceholder')"
+      class="w-full"
+      data-testid="reference-repo-search"
+    >
+      <template #empty>
+        <RepoSearchEmpty
+          :below-min-chars="belowMinChars"
+          :loading="repoLoading"
+          :query="repoQuery"
+        />
+      </template>
+    </UInputMenu>
+    <div v-else class="text-[11px] text-slate-500">
+      {{ t('inspector.referenceRepos.connectFirst') }}
+    </div>
+
+    <div class="mt-1 text-[11px] text-slate-500">
+      {{ t('inspector.referenceRepos.hint') }}
+    </div>
+  </div>
+</template>

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -480,6 +480,9 @@ const technicalLabel = computed(() => {
       </div>
     </div>
 
+    <!-- reference repositories: read-only repos the doc-writer reads while drafting (doc tasks) -->
+    <DocReferenceRepos v-if="block.taskType === 'document'" :block="block" />
+
     <!-- issue-tracker writeback overrides -->
     <div>
       <div class="mb-1 flex items-center justify-between">

package/app/composables/useRepoSearch.ts

@@ -0,0 +1,66 @@
+import { computed, ref, watch } from 'vue'
+import { refDebounced } from '@vueuse/core'
+import type { GitHubAvailableRepo } from '~/types/domain'
+
+/** Minimum characters before a search fires — a wide install has too many repos to prefetch. */
+export const REPO_SEARCH_MIN_LEN = 3
+
+/** How the picker searches: a debounced, min-length-gated, server-side repo search. */
+export type RepoFetcher = (query: string) => Promise<GitHubAvailableRepo[]>
+
+/**
+ * Shared repo-lookup behaviour for the GitHub repo pickers (the add-service modal and the
+ * doc-task reference-repo picker). A wide App install / PAT can expose hundreds of repos, so the
+ * pickers search SERVER-SIDE rather than prefetching and filtering in the browser: once the user
+ * types at least {@link REPO_SEARCH_MIN_LEN} characters the (debounced) query is sent to the
+ * backend, which returns only the matches. Below the gate the list stays empty and the caller
+ * shows a "type N chars" hint.
+ *
+ * The fetcher defaults to the github store's NON-mutating `searchAvailableRepos`, so each picker
+ * keeps its OWN result list — two pickers never clobber each other through the shared
+ * `availableRepos` singleton. A stale-response guard drops an out-of-order fetch so fast typing
+ * can't leave older matches showing.
+ */
+export function useRepoSearch(fetcher?: RepoFetcher) {
+  const github = useGitHubStore()
+  const doFetch: RepoFetcher = fetcher ?? ((q) => github.searchAvailableRepos(q))
+
+  const search = ref('')
+  const debounced = refDebounced(search, 250)
+  // Trimmed for the min-length gate; the backend matches case-insensitively.
+  const query = computed(() => debounced.value.trim())
+  const belowMinChars = computed(() => query.value.length < REPO_SEARCH_MIN_LEN)
+
+  const results = ref<GitHubAvailableRepo[]>([])
+  const loading = ref(false)
+  // Monotonic token so a slow earlier fetch can't overwrite a faster later one.
+  let seq = 0
+
+  watch(query, async (q) => {
+    if (q.length < REPO_SEARCH_MIN_LEN) {
+      results.value = []
+      return
+    }
+    const mine = ++seq
+    loading.value = true
+    try {
+      const found = await doFetch(q)
+      if (mine === seq) results.value = found
+    } finally {
+      if (mine === seq) loading.value = false
+    }
+  })
+
+  /** Clear the search term and results (e.g. after a pick, or when the host closes). */
+  function reset() {
+    search.value = ''
+    results.value = []
+    // Bump the token so an in-flight fetch's result/finally is ignored — and clear `loading`
+    // ourselves, since that same in-flight `finally` will now skip its `mine === seq` guard and
+    // would otherwise leave the spinner stuck on until the next search completes.
+    seq++
+    loading.value = false
+  }
+
+  return { search, query, belowMinChars, results, loading, reset }
+}

package/app/stores/github.ts

@@ -157,6 +157,18 @@ export const useGitHubStore = defineStore('github', () => {
     }
   }
 
+  /**
+   * Search the installation/PAT-accessible repos server-side WITHOUT touching the shared
+   * `availableRepos`/`loadingAvailable` singleton — it returns the matches to the caller instead.
+   * This is the reusable form behind {@link useRepoSearch}: two independent pickers (the
+   * add-service modal and the doc-task reference-repo picker) can search concurrently without
+   * clobbering each other's results. A blank/short `q` (or no connection) returns `[]`.
+   */
+  async function searchAvailableRepos(q: string): Promise<GitHubAvailableRepo[]> {
+    if (!connected.value || q.trim() === '') return []
+    return api.listGitHubAvailableRepos(workspace.requireId(), q)
+  }
+
   /** Set the exact set of repos this workspace links, then refresh projections. */
   async function setLinkedRepos(repoGithubIds: number[]) {
     savingRepos.value = true
@@ -318,6 +330,7 @@ export const useGitHubStore = defineStore('github', () => {
     load,
     ensureLoaded,
     loadAvailableRepos,
+    searchAvailableRepos,
     setLinkedRepos,
     loadRepoTree,
     loadBranches,

package/app/types/domain.ts

@@ -28,6 +28,7 @@ export type {
   DocKindFieldSpec,
   Block,
   PullRequestRef,
+  ReferenceRepo,
   CloudProvider,
   InstanceSize,
   ProvisionType,

package/i18n/locales/en.json

@@ -876,6 +876,12 @@
       "involvedServicesHint": "Connected services directly involved in this task: each spins up as an ephemeral environment alongside this task's own service, and the coding agent may change their repositories too.",
       "involvedServicesEmpty": "No connected services. Connect services on the service frame to select them here.",
       "involvedServiceStale": "No longer connected to this task's service; it is dropped on the next change."
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/i18n/locales/es.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "Servicios conectados directamente involucrados en esta tarea: cada uno se levanta como un entorno efímero junto al servicio propio de la tarea, y el agente de código puede modificar también sus repositorios.",
       "involvedServicesEmpty": "No hay servicios conectados. Conecta servicios en el marco del servicio para seleccionarlos aquí.",
       "involvedServiceStale": "Ya no está conectado al servicio de esta tarea; se eliminará con el próximo cambio."
+    },
+    "referenceRepos": {
+      "title": "Repositorios de referencia",
+      "remove": "Quitar {repo}",
+      "connectFirst": "Conecta GitHub para adjuntar repositorios de referencia.",
+      "hint": "El escritor de documentos los clona en modo de solo lectura para reutilizar soluciones existentes como referencia al redactar. Nunca los modifica."
     }
   },
   "panels": {

package/i18n/locales/fr.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "Services connectés directement impliqués dans cette tâche : chacun démarre comme environnement éphémère aux côtés du service propre de la tâche, et l'agent de code peut aussi modifier leurs dépôts.",
       "involvedServicesEmpty": "Aucun service connecté. Connectez des services sur le cadre du service pour les sélectionner ici.",
       "involvedServiceStale": "N'est plus connecté au service de cette tâche ; il sera retiré au prochain changement."
+    },
+    "referenceRepos": {
+      "title": "Dépôts de référence",
+      "remove": "Retirer {repo}",
+      "connectFirst": "Connectez GitHub pour joindre des dépôts de référence.",
+      "hint": "Le rédacteur de documents les clone en lecture seule pour réutiliser des solutions existantes comme référence lors de la rédaction. Il ne les modifie jamais."
     }
   },
   "panels": {

package/i18n/locales/he.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "שירותים מחוברים המעורבים ישירות במשימה זו: כל אחד מהם מוקם כסביבה זמנית לצד השירות של המשימה, וסוכן הקוד עשוי לשנות גם את המאגרים שלהם.",
       "involvedServicesEmpty": "אין שירותים מחוברים. חברו שירותים במסגרת השירות כדי לבחור אותם כאן.",
       "involvedServiceStale": "כבר לא מחובר לשירות של משימה זו; הוא יוסר בשינוי הבא."
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/i18n/locales/ja.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "このタスクに直接関与する接続済みサービス。各サービスはタスク自身のサービスと並んで一時的な環境として起動され、コーディングエージェントがそのリポジトリを変更することもあります。",
       "involvedServicesEmpty": "接続済みのサービスはありません。ここで選択するには、サービスフレームでサービスを接続してください。",
       "involvedServiceStale": "このタスクのサービスとの接続が解除されています。次回の変更時に削除されます。"
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/i18n/locales/pl.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "Połączone usługi bezpośrednio zaangażowane w to zadanie: każda z nich uruchamiana jest jako środowisko tymczasowe obok własnej usługi zadania, a agent kodujący może też zmieniać ich repozytoria.",
       "involvedServicesEmpty": "Brak połączonych usług. Połącz usługi na ramce usługi, aby móc je tutaj wybrać.",
       "involvedServiceStale": "Nie jest już połączona z usługą tego zadania; zostanie usunięta przy następnej zmianie."
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/i18n/locales/tr.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "Bu göreve doğrudan dahil olan bağlı servisler: her biri görevin kendi servisiyle birlikte geçici bir ortam olarak ayağa kaldırılır ve kodlama ajanı onların depolarında da değişiklik yapabilir.",
       "involvedServicesEmpty": "Bağlı servis yok. Burada seçebilmek için servis çerçevesinde servisleri bağlayın.",
       "involvedServiceStale": "Artık bu görevin servisine bağlı değil; bir sonraki değişiklikte kaldırılacak."
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/i18n/locales/uk.json

@@ -833,6 +833,12 @@
       "involvedServicesHint": "З'єднані сервіси, безпосередньо залучені до цього завдання: кожен розгортається як тимчасове середовище поряд із власним сервісом завдання, і агент кодування може змінювати також їхні репозиторії.",
       "involvedServicesEmpty": "Немає з'єднаних сервісів. З'єднайте сервіси на рамці сервісу, щоб вибрати їх тут.",
       "involvedServiceStale": "Більше не з'єднаний із сервісом цього завдання; буде видалений під час наступної зміни."
+    },
+    "referenceRepos": {
+      "title": "Reference repositories",
+      "remove": "Remove {repo}",
+      "connectFirst": "Connect GitHub to attach reference repositories.",
+      "hint": "The document writer clones these read-only to reuse existing solutions as a reference while drafting. It never changes them."
     }
   },
   "panels": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.39",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.103.0"
+    "@cat-factory/contracts": "0.104.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",