@cat-factory/app 0.238.0 → 0.241.0

package/app/components/documents/DocumentImportModal.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { DocumentSourceKind } from '~/types/domain'
+import DocumentSyncState from '~/components/documents/DocumentSyncState.vue'
 import IntegrationBackTitle from '~/components/layout/IntegrationBackTitle.vue'
 
 // Import pages from a connected document source and pick one to expand into
@@ -147,6 +148,7 @@ function preview(externalId: string) {
                   {{ doc.title }}
                 </a>
                 <p class="mt-0.5 line-clamp-2 text-xs text-slate-500">{{ doc.excerpt }}</p>
+                <DocumentSyncState :doc="doc" class="mt-1" />
               </div>
               <UButton
                 color="primary"

package/app/components/documents/DocumentSyncState.logic.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { documentFreshnessChangeSchema, documentFreshnessGapSchema } from '@cat-factory/contracts'
+import { missingI18nKeys } from '../../../test/i18nKeys'
+import { CHANGE_KEYS, GAP_KEYS } from './DocumentSyncState.logic'
+
+/**
+ * The half of these tables' correctness that no guard can see.
+ *
+ * `satisfies Record<TheEnum, string>` already proves every MEMBER has an entry, and CI's locale
+ * parity plus `i18n:check` cover keys written literally as a translate call. A key held in a lookup
+ * table is invisible to both, so deleting it from the catalog passes every check and renders its own
+ * dotted path to the user (see `test/i18nKeys.ts`).
+ *
+ * The member lists are DERIVED from the picklists the component's types come from rather than
+ * re-listed here: a re-listed copy would pass while the code under test had drifted, which is the
+ * one failure mode a table test exists to catch.
+ */
+describe('DocumentSyncState freshness tables', () => {
+  it('names a key the base catalog holds for every gap', () => {
+    expect(missingI18nKeys(Object.values(GAP_KEYS))).toEqual([])
+  })
+
+  it('names a key the base catalog holds for every change outcome', () => {
+    expect(missingI18nKeys(Object.values(CHANGE_KEYS))).toEqual([])
+  })
+
+  it('covers exactly the contracts vocabularies, with no entry for a member that is gone', () => {
+    expect(Object.keys(GAP_KEYS).sort()).toEqual([...documentFreshnessGapSchema.options].sort())
+    expect(Object.keys(CHANGE_KEYS).sort()).toEqual(
+      [...documentFreshnessChangeSchema.options].sort(),
+    )
+  })
+})

package/app/components/documents/DocumentSyncState.logic.ts

@@ -0,0 +1,38 @@
+import type { DocumentFreshnessChange, DocumentFreshnessGap } from '~/types/domain'
+
+/**
+ * The i18n keys `DocumentSyncState` renders a freshness verdict through, in their own module so a
+ * spec can prove they still resolve.
+ *
+ * Both are exhaustive `Record`s over a contracts vocabulary, which buys half the guarantee: adding a
+ * member fails the build here rather than rendering an empty line. The other half is what the
+ * `satisfies` cannot see: that each VALUE still names a key the catalog holds. Typed message keys
+ * and `i18n:check` only find keys written literally as a translate call, so a key held in a lookup
+ * table is invisible to both, and deleting it reads as a clean removal that renders its own key path
+ * at runtime. `DocumentSyncState.logic.spec.ts` closes that (see `test/i18nKeys.ts`).
+ *
+ * ONE FULL SENTENCE per member rather than a shared "not confirmed: {reason}" frame, because each
+ * asks for a different fix and a clause spliced into a sentence is what breaks first in a language
+ * whose word order is not English's.
+ */
+export const GAP_KEYS = {
+  not_connected: 'documents.freshness.gap.not_connected',
+  credentials_unreadable: 'documents.freshness.gap.credentials_unreadable',
+  unversioned: 'documents.freshness.gap.unversioned',
+  source_unreachable: 'documents.freshness.gap.source_unreachable',
+} as const satisfies Record<DocumentFreshnessGap, string>
+
+/**
+ * What a CONFIRMED check found, which is a different question from why one failed.
+ *
+ * Three outcomes rather than a "did it change" boolean, because the middle one is the common case
+ * for a whole-file source and is exactly what a boolean gets wrong: a Figma file's revision moves on
+ * any edit anywhere in it, so a check legitimately finds a newer revision with not one byte of THIS
+ * document's content different. Rendering that as "pulled the newer version" would tell a person
+ * their own edit had landed when it may be in a frame this document does not cover.
+ */
+export const CHANGE_KEYS = {
+  unchanged: 'documents.freshness.change.unchanged',
+  reimported: 'documents.freshness.change.reimported',
+  revision_only: 'documents.freshness.change.revision_only',
+} as const satisfies Record<DocumentFreshnessChange, string>

package/app/components/documents/DocumentSyncState.vue

@@ -0,0 +1,181 @@
+<script setup lang="ts">
+import { isConnectableSource } from '@cat-factory/contracts'
+import type { SourceDocument } from '~/types/domain'
+import { CHANGE_KEYS, GAP_KEYS } from '~/components/documents/DocumentSyncState.logic'
+
+// When a stored document was last written, and a way to ask its source whether that is still the
+// current revision.
+//
+// A source-backed document is a PROJECTION of a page someone else keeps editing, and until the
+// dispatch-time refresh landed nothing ever looked at the source again. Runs now re-confirm on
+// every dispatch, but the person deciding whether to START one still had no way to see it: the
+// board showed a title and an excerpt frozen at import, so "is the frame I just edited the one the
+// agents will read" was unanswerable without opening Figma and comparing by eye.
+//
+// TWO facts, deliberately rendered as two, because they answer different questions and one is not
+// the other's proxy:
+//
+//   - `syncedAt` is when the BODY was last written. It is on every row, costs nothing, and moves
+//     only when a fetch actually changed something.
+//   - the freshness verdict is what the source said when someone last ASKED. It exists only after
+//     a click, because confirming costs a round trip per document and listing a board's imported
+//     pages must not spend one each.
+//
+// So an absent verdict means "nobody has asked", never "unknown", and a row that was refreshed and
+// found UNCHANGED still shows its old `syncedAt` beside a confirmation: the body genuinely was not
+// rewritten, and moving the stamp would claim a write that never happened.
+//
+// BOTH are rendered WITH THEIR TIME, and that is not decoration. Each is a claim about a moment in
+// the history of a page someone else is still editing, and a moment stated without its time is read
+// as "now": a confirmation reached an hour ago would otherwise keep showing a green check under
+// copy that says the copy is current, which is the precise false confidence this whole surface
+// exists to remove. Hence the `long` datetime format (`short` is date-only, so two writes on the
+// same day are indistinguishable) on the one side and the verdict's own `checkedAt` on the other.
+const props = defineProps<{ doc: SourceDocument }>()
+
+const { t, d } = useI18n()
+const documents = useDocumentsStore()
+const toast = useToast()
+
+/**
+ * The source to ask, or null for an origin with nobody to ask. An `upload` was handed to the
+ * platform through the API and has no page behind it, so it gets the stamp and no action; the
+ * backend refuses the call for the same reason, and narrowing here keeps the SPA from making it.
+ */
+const askable = computed(() => (isConnectableSource(props.doc.source) ? props.doc.source : null))
+
+const verdict = computed(() => documents.freshnessFor(props.doc.source, props.doc.externalId))
+const busy = computed(() => documents.isRefreshing(props.doc.source, props.doc.externalId))
+
+interface Stated {
+  tone: 'ok' | 'warn' | 'muted'
+  icon: string
+  text: string
+  /** The revision token, shown only when there IS one to paste back into the source. */
+  revision: string
+}
+
+/** What the last check concluded, or null when nobody has asked yet. */
+const stated = computed<Stated | null>(() => {
+  const value = verdict.value?.verdict
+  if (!value) return null
+  switch (value.status) {
+    case 'confirmed':
+      // None of the three is a degradation, but they are the whole answer to "did my edit land",
+      // and each answers it differently.
+      return {
+        tone: 'ok',
+        icon: 'i-lucide-check',
+        text: t(CHANGE_KEYS[value.change]),
+        revision: value.version,
+      }
+    case 'unconfirmed':
+      return {
+        tone: 'warn',
+        icon: 'i-lucide-triangle-alert',
+        text: t(GAP_KEYS[value.reason]),
+        revision: '',
+      }
+    case 'not-applicable':
+      // Reachable for a connectable source this deployment wired no provider for. Stating it beats
+      // rendering nothing after a click, which reads as an action that silently failed.
+      return {
+        tone: 'muted',
+        icon: 'i-lucide-minus',
+        text: t('documents.freshness.notApplicable'),
+        revision: '',
+      }
+    default:
+      return unstatable(value)
+  }
+})
+
+/** Compile-time totality over the verdict union: adding a status fails the build here. */
+function unstatable(_value: never): null {
+  return null
+}
+
+/**
+ * The verdict's own moment, always rendered beside it.
+ *
+ * A verdict does not expire and is deliberately not made to: expiring it would invent an "unknown"
+ * where the rule is that only "nobody has asked" exists. What makes that safe is stating WHEN, so a
+ * check reached an hour ago reads as an hour-old check instead of as the current state of a page
+ * that has had an hour to move.
+ */
+const checkedAt = computed(() => {
+  const at = verdict.value?.checkedAt
+  if (at === undefined) return ''
+  return t('documents.freshness.checkedAt', { when: d(new Date(at), 'long') })
+})
+
+/**
+ * The verdict's detail line: which revision was confirmed, and when it was confirmed.
+ *
+ * In the hover title rather than the row, which is an 11px line already carrying a stamp, a
+ * sentence and a button. That placement is only safe because the visible sentences state what the
+ * check FOUND and never when it ran ("Matches the source", not "current as of just now"): a claim
+ * about the present tense would still be a claim about the present tense with the timestamp hidden
+ * one layer down.
+ */
+const detail = computed(() =>
+  [
+    stated.value?.revision
+      ? t('documents.freshness.revision', { version: stated.value.revision })
+      : '',
+    checkedAt.value,
+  ]
+    .filter(Boolean)
+    .join(' · '),
+)
+
+const TONE_CLASS: Record<Stated['tone'], string> = {
+  ok: 'text-emerald-400',
+  warn: 'text-amber-400',
+  muted: 'text-slate-500',
+}
+
+async function refresh() {
+  const source = askable.value
+  if (!source || busy.value) return
+  try {
+    await documents.refresh(source, props.doc.externalId)
+  } catch (e) {
+    toast.add({
+      title: t('documents.freshness.refreshFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  }
+}
+</script>
+
+<template>
+  <div class="flex items-center gap-1.5 text-[11px] text-slate-500">
+    <span class="truncate">
+      {{ t('documents.freshness.updated', { when: d(new Date(props.doc.syncedAt), 'long') }) }}
+    </span>
+    <span
+      v-if="stated"
+      class="flex min-w-0 items-center gap-1"
+      :class="TONE_CLASS[stated.tone]"
+      :title="detail || undefined"
+    >
+      <UIcon :name="stated.icon" class="h-3 w-3 shrink-0" />
+      <span class="truncate">{{ stated.text }}</span>
+    </span>
+    <UButton
+      v-if="askable"
+      color="neutral"
+      variant="ghost"
+      size="xs"
+      icon="i-lucide-refresh-cw"
+      :loading="busy"
+      :aria-label="t('documents.freshness.refresh')"
+      :title="t('documents.freshness.refresh')"
+      class="ml-auto shrink-0"
+      @click="refresh"
+    />
+  </div>
+</template>

package/app/components/documents/TaskContextDocs.vue

@@ -4,6 +4,7 @@ import type { Block } from '~/types/domain'
 import { connectableSources } from '~/utils/sourcePicker'
 import ContextDocumentPicker from '~/components/documents/ContextDocumentPicker.vue'
 import DocumentOriginLink from '~/components/documents/DocumentOriginLink.vue'
+import DocumentSyncState from '~/components/documents/DocumentSyncState.vue'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
 
 // Documents (from any source) attached to a task OR an initiative as agent
@@ -140,19 +141,29 @@ async function attach(item: PendingContext) {
     />
 
     <div v-if="linked.length" class="space-y-1">
-      <DocumentOriginLink
+      <!--
+        The sync state sits BESIDE the origin link, never inside it: the refresh action is a
+        button, and a button nested in an anchor both breaks the markup and navigates away on the
+        click it was meant to handle.
+      -->
+      <div
         v-for="doc in linked"
         :key="`${doc.source}:${doc.externalId}`"
-        :url="doc.url"
-        class="flex items-center gap-1.5 rounded-md border border-slate-800 bg-slate-900/60 px-2 py-1.5 text-xs text-slate-300"
-        hover-class="hover:bg-slate-800/60"
+        class="rounded-md border border-slate-800 bg-slate-900/60 px-2 py-1.5"
       >
-        <UIcon
-          :name="documents.descriptorForOrigin(doc.source)?.icon ?? 'i-lucide-file-text'"
-          class="h-3.5 w-3.5 shrink-0 text-indigo-400"
-        />
-        <span class="truncate">{{ doc.title }}</span>
-      </DocumentOriginLink>
+        <DocumentOriginLink
+          :url="doc.url"
+          class="flex items-center gap-1.5 text-xs text-slate-300"
+          hover-class="hover:text-white"
+        >
+          <UIcon
+            :name="documents.descriptorForOrigin(doc.source)?.icon ?? 'i-lucide-file-text'"
+            class="h-3.5 w-3.5 shrink-0 text-indigo-400"
+          />
+          <span class="truncate">{{ doc.title }}</span>
+        </DocumentOriginLink>
+        <DocumentSyncState :doc="doc" class="mt-1" />
+      </div>
     </div>
     <p v-else class="text-[11px] text-slate-500">
       {{ emptyHint }}

package/app/components/layout/AccountAuditLog.logic.spec.ts

@@ -0,0 +1,107 @@
+import { AUDIT_ACTION_DETAIL_KEYS, auditActionSchema } from '@cat-factory/contracts'
+import type { AuditEventWire } from '@cat-factory/contracts'
+import { describe, expect, it } from 'vitest'
+import { ACTION_KEYS, actorLabel, describeEvent } from './AccountAuditLog.logic'
+
+/**
+ * The audit viewer's sentence composition. What is worth pinning is the set of rows a happy-path
+ * render never produces, because those are the rows an audit log is kept FOR: an action this build
+ * has retired, a `details` blob that would not parse, a person who is no longer here.
+ */
+
+/** A fake `t` that renders `key(param=value, …)`, so an unresolved slot is visible as itself. */
+function fakeT(key: string, params?: Record<string, string>): string {
+  const rendered = Object.entries(params ?? {})
+    .map(([k, v]) => `${k}=${v}`)
+    .sort()
+    .join(',')
+  return rendered ? `${key}(${rendered})` : key
+}
+
+function event(overrides: Partial<AuditEventWire> = {}): AuditEventWire {
+  return {
+    id: 'aud_1',
+    at: 1_700_000_000_000,
+    workspaceId: null,
+    actor: { kind: 'user', userId: 'usr_actor' },
+    action: 'account.member_roles_changed',
+    targetType: 'user',
+    targetId: 'usr_target',
+    details: { previousRoles: 'developer', roles: 'admin' },
+    actorName: 'Ada',
+    targetName: 'Grace',
+    ...overrides,
+  } as AuditEventWire
+}
+
+describe('audit sentence composition', () => {
+  it('gives every action in the wire vocabulary its own copy', () => {
+    // Derived from the picklist the backend writes against, not a list retyped here: an action
+    // added on the backend fails THIS assertion rather than rendering its raw code at an operator.
+    expect(Object.keys(ACTION_KEYS).sort()).toEqual([...auditActionSchema.options].sort())
+  })
+
+  it('interpolates the row’s own values', () => {
+    expect(describeEvent(event(), fakeT)).toBe(
+      'layout.auditLog.actions.accountMemberRolesChanged(previousRoles=developer,roles=admin,target=Grace)',
+    )
+  })
+
+  it('defaults every slot the ACTION declares when the details blob was unreadable', () => {
+    // The regression: `decodeAuditDetails` deliberately returns `{}` for a blob that will not
+    // parse, keeping a row that states less over losing the row entirely. Defaulting by iterating
+    // the row cannot reach that case — there are no keys to iterate — so the sentence rendered the
+    // literal `{previousRoles}` at an operator. The seed comes from the contract, so the two
+    // declared slots are known even when the row carries neither.
+    expect(describeEvent(event({ details: {} }), fakeT)).toBe(
+      'layout.auditLog.actions.accountMemberRolesChanged(previousRoles=layout.auditLog.values.none,' +
+        'roles=layout.auditLog.values.none,target=Grace)',
+    )
+  })
+
+  it('defaults a slot the row carries as null or empty, without dropping it', () => {
+    expect(describeEvent(event({ details: { previousRoles: null, roles: '' } }), fakeT)).toBe(
+      'layout.auditLog.actions.accountMemberRolesChanged(previousRoles=layout.auditLog.values.none,' +
+        'roles=layout.auditLog.values.none,target=Grace)',
+    )
+  })
+
+  it('leaves no declared slot of any action unfilled on an empty details blob', () => {
+    // The structural form of the case above, across the whole vocabulary rather than one action:
+    // whatever an action declares it carries, a row carrying none of it still renders every slot.
+    for (const action of auditActionSchema.options) {
+      const sentence = describeEvent(event({ action, details: {} }), fakeT)
+      for (const slot of AUDIT_ACTION_DETAIL_KEYS[action]) {
+        expect(sentence).toContain(`${slot}=layout.auditLog.values.none`)
+      }
+    }
+  })
+
+  it('names a RETIRED action as itself rather than dropping or guessing it', () => {
+    // Nothing here can know what a retired member meant, and a missing row is the one failure an
+    // audit log must not have.
+    expect(describeEvent(event({ action: { retired: 'account.something_gone' } }), fakeT)).toBe(
+      'layout.auditLog.retiredAction(action=account.something_gone)',
+    )
+  })
+
+  it('falls back to the raw id for a person who is no longer here', () => {
+    // Which is precisely the kind of thing the log is kept to record, so it renders rather than
+    // becoming a placeholder.
+    expect(actorLabel(event({ actorName: null }), fakeT)).toBe('usr_actor')
+    expect(describeEvent(event({ targetName: null }), fakeT)).toContain('target=usr_target')
+  })
+
+  it('shows an API key as the key, never the person who minted it', () => {
+    // A leaked key has to stay distinguishable from the human it was minted by.
+    expect(actorLabel(event({ actor: { kind: 'apiKey', apiKeyId: 'key_9' } }), fakeT)).toBe(
+      'layout.auditLog.actors.apiKey(id=key_9)',
+    )
+  })
+
+  it('says the SYSTEM acted, which is not the same as a user we failed to resolve', () => {
+    expect(actorLabel(event({ actor: { kind: 'system' } }), fakeT)).toBe(
+      'layout.auditLog.actors.system',
+    )
+  })
+})

package/app/components/layout/AccountAuditLog.logic.ts

@@ -0,0 +1,101 @@
+import { AUDIT_ACTION_DETAIL_KEYS, isRetiredAuditValue } from '@cat-factory/contracts'
+import type { AuditAction, AuditEventWire } from '@cat-factory/contracts'
+
+// How one audit row becomes one sentence. Kept out of the SFC on the same seam as
+// `StepToolServers.logic.ts`, because the two rules worth asserting here are both about rows a
+// happy-path render never produces: an action this build has retired, and a row whose `details`
+// blob would not parse.
+//
+// The design this serves: the backend records machine-readable FIELDS and never prose, since a
+// row is persisted and English written today could not be re-rendered for a reader in another
+// locale years later. So every sentence is a translated key plus the row's own values.
+
+/**
+ * Action → message key. EXHAUSTIVE over the contract union on purpose: the alternative is a lookup
+ * returning `undefined` for an action somebody added on the backend, which renders a raw
+ * `account.member_roles_changed` at an operator instead of failing the build.
+ */
+export const ACTION_KEYS: Record<AuditAction, string> = {
+  'account.member_added': 'layout.auditLog.actions.accountMemberAdded',
+  'account.member_roles_changed': 'layout.auditLog.actions.accountMemberRolesChanged',
+  'account.budget_changed': 'layout.auditLog.actions.accountBudgetChanged',
+  'account.settings_changed': 'layout.auditLog.actions.accountSettingsChanged',
+  'account.invitation_created': 'layout.auditLog.actions.accountInvitationCreated',
+  'account.invitation_revoked': 'layout.auditLog.actions.accountInvitationRevoked',
+  'account.invitation_accepted': 'layout.auditLog.actions.accountInvitationAccepted',
+  'account.member_sessions_revoked': 'layout.auditLog.actions.accountMemberSessionsRevoked',
+  'workspace.member_added': 'layout.auditLog.actions.workspaceMemberAdded',
+  'workspace.member_role_changed': 'layout.auditLog.actions.workspaceMemberRoleChanged',
+  'workspace.member_removed': 'layout.auditLog.actions.workspaceMemberRemoved',
+  'workspace.access_mode_changed': 'layout.auditLog.actions.workspaceAccessModeChanged',
+}
+
+/** Translate a key with interpolation params. The component owns the i18n instance; this is pure. */
+export type Translate = (key: string, params?: Record<string, string>) => string
+
+/**
+ * The row's detail fields as interpolation params.
+ *
+ * Seeded from what the ACTION declares it carries (`AUDIT_ACTION_DETAIL_KEYS`, the same contract
+ * the backend writers are held to), then overlaid with what the row actually holds. Both halves
+ * are needed, and the seed is the one easy to leave out: iterating the row alone defaults
+ * nothing, because a row whose `details` blob was unreadable has NO keys to iterate — and that is
+ * precisely the row the defaulting exists for. `decodeAuditDetails` returns an empty set there by
+ * design, keeping a row that states less over losing the row entirely, so without the seed the
+ * sentence renders the literal `{previousRoles}` at an operator.
+ *
+ * Derived from the contract rather than re-listed, so an action whose fields change cannot leave
+ * this behind: the `Record` it reads is exhaustive over the same picklist `ACTION_KEYS` is.
+ */
+export function detailParams(
+  action: AuditAction,
+  details: AuditEventWire['details'],
+  none: string,
+): Record<string, string> {
+  const params: Record<string, string> = {}
+  for (const key of AUDIT_ACTION_DETAIL_KEYS[action]) params[key] = none
+  for (const [key, value] of Object.entries(details)) {
+    params[key] = value === null || value === '' ? none : String(value)
+  }
+  return params
+}
+
+/** Who the action was performed ON: the resolved name, else the raw id. */
+export function targetLabel(event: AuditEventWire): string {
+  return event.targetName ?? event.targetId
+}
+
+/**
+ * Who performed it.
+ *
+ * The three principal kinds render differently on purpose. A user shows their name (or their id,
+ * when the person is gone — which is precisely the kind of thing the log is kept to record); an
+ * API key shows the key, never the person who minted it, so a leaked key is distinguishable from
+ * them; and `system` says the engine acted, which is a different fact from a user we failed to
+ * resolve and must never look the same.
+ */
+export function actorLabel(event: AuditEventWire, t: Translate): string {
+  if (event.actor.kind === 'system') return t('layout.auditLog.actors.system')
+  if (event.actor.kind === 'apiKey') {
+    return t('layout.auditLog.actors.apiKey', { id: event.actor.apiKeyId })
+  }
+  return event.actorName ?? event.actor.userId
+}
+
+/**
+ * The sentence for one row.
+ *
+ * A RETIRED action (one this build no longer declares, in a row written before it was retired) is
+ * named as itself rather than dropped or guessed onto a current member. Nothing here can know what
+ * it meant, and a missing row is the one failure an audit log must not have — so it renders as
+ * "unrecognised action: <value>" and keeps its actor, target and timestamp.
+ */
+export function describeEvent(event: AuditEventWire, t: Translate): string {
+  if (isRetiredAuditValue(event.action)) {
+    return t('layout.auditLog.retiredAction', { action: event.action.retired })
+  }
+  return t(ACTION_KEYS[event.action], {
+    target: targetLabel(event),
+    ...detailParams(event.action, event.details, t('layout.auditLog.values.none')),
+  })
+}