@cat-factory/app 0.217.1 → 0.218.0

package/README.md

@@ -577,10 +577,12 @@ layer ships the base `en` locale, and a downstream deployment overrides by dropp
 [`docs/localization.md`](../../docs/localization.md).
 
 - `i18n/locales/<locale>.json`: the catalogs (the v9+ `i18n/` convention, NOT `app/locales/`).
-- `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the named
-  `numberFormats`/`datetimeFormats`). Messages are deliberately NOT here so the module can
-  deep-merge across the `extends` chain. Referenced as the BARE filename
+- `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the plural
+  selectors, the named `numberFormats`/`datetimeFormats`). Messages are deliberately NOT here
+  so the module can deep-merge across the `extends` chain. Referenced as the BARE filename
   `vueI18n: 'i18n.config.ts'`, never `layerDir`-anchored.
+- `i18n/plural-rules.ts`: the per-locale plural selectors, kept beside the config as pure
+  logic so they unit-test standalone. See **Plural forms** below.
 - `package.json` `files` MUST include `"i18n"`. Release-blocking.
 
 **Adding a string**: add the key to `en.json` under the feature namespace, resolve with
@@ -605,6 +607,25 @@ so a dynamic lookup is total; **no cross-key concatenation** (a full sentence is
   until runtime.
 - Straight quotes, no em-dashes in new entries.
 
+**Plural forms: how MANY forms an entry carries is part of its contract.** Most locales run on
+vue-i18n's built-in selector, where a 2-form entry is `one | other` and a 3-form entry is
+`zero | one | other` (the leading zero form is a copy nicety, not a CLDR category: "no
+participants" beats "0 participants"). `pl`, `uk` and `he` override that selector in
+`i18n/plural-rules.ts` because the built-in one cannot express their agreement, so their entries
+carry the locale's CLDR categories instead, optionally behind the same zero form:
+
+| Locale      | CLDR forms            | With a zero form              |
+| ----------- | --------------------- | ----------------------------- |
+| `pl` / `uk` | `one \| few \| many`  | `zero \| one \| few \| many`  |
+| `he`        | `one \| two \| other` | `zero \| one \| two \| other` |
+
+Dropping a form does not drop a case, it RE-POINTS every remaining slot onto a different count,
+so `i18n/plural-forms.spec.ts` fails the build on an entry whose form count is neither shape (and
+on a key `en` pluralizes that one of those three renders flat). Neither other i18n gate can see
+this: the key exists and it moved with `en`, which is all they check. `plural-rules.spec.ts`
+separately pins each selector against `Intl.PluralRules`, so a hand-written rule that disagrees
+with the platform's own CLDR data fails a test rather than shipping.
+
 **Translator descriptions (`@<key>` siblings): default to NONE.** They live only in `en.json` and
 are notes to a translator, never runtime data. Add one ONLY when a competent translator seeing
 the English and the key path could plausibly get it wrong: homograph / part-of-speech ambiguity
@@ -633,6 +654,8 @@ rather than being dropped. A new failure-presenting surface copies that split (t
 4. **Locale parity**: `i18n-locale-parity.mjs --since origin/<base>` requires a PR that adds,
    changes, or removes an `en.json` key to make the SAME change in every other locale. It is
    change-coupling against the merge-base, NOT full key parity.
+5. **Plural shape**: `i18n/plural-forms.spec.ts` fails on a `pl`/`uk`/`he` entry carrying the
+   wrong number of forms (see **Plural forms** above), which the other three gates all pass.
 
 **Translate for real: NEVER ship an English string as a non-`en` value.** The parity gate checks
 only that the key exists, so it will pass a verbatim English copy, and that copy is a bug. The

package/app/components/board/BoardCanvas.vue

@@ -20,6 +20,9 @@ const execution = useExecutionStore()
 const ui = useUiStore()
 const github = useGitHubStore()
 const toast = useToast()
+// The drop resolves its target task at the moment of the drop, so the sandbox reading is a
+// function of that id rather than a computed over a bound block.
+const { forcedFor } = useDryRunPolicy()
 const access = useWorkspaceAccess()
 const { t } = useI18n()
 
@@ -184,6 +187,18 @@ async function onDrop(event: DragEvent) {
       })
       return
     }
+    // A dropped pipeline starts live and has nothing to ask for, but a preset that sandboxes the
+    // dropper's role means this run merges nothing. Said HERE, because the drop is the only
+    // moment this surface has: the ordinary start stays silent (it is already visible on the
+    // card it landed on), and only the sandbox, which is not, earns a toast.
+    if (forcedFor(target.id)) {
+      toast.add({
+        title: t('board.dryRunToast.title'),
+        description: t('board.dryRunToast.body', { name: pipeline.name }),
+        color: 'warning',
+        icon: 'i-lucide-shield',
+      })
+    }
     execution.start(target.id, pipeline)
     ui.select(target.id)
   }

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

@@ -36,6 +36,13 @@ const typeBadge = computed(() => {
 })
 const selected = computed(() => ui.selectedBlockId === props.taskId)
 
+// This card's Start is a ONE-TAP live start, so it has nothing to ask for and offers no dry-run
+// request. What it does owe the reader is the half that is not a choice: a preset that sandboxes
+// their role means this button opens a pull request and merges nothing, and a card that said so
+// only after the fact would leave that to be discovered from a run that stops at the merge.
+const { forcedFor } = useDryRunPolicy()
+const sandboxed = computed(() => forcedFor(props.taskId))
+
 // Drag-to-connect: dragging from this card's handle onto another task makes THAT task
 // depend on this one (this is the prerequisite). The composable tracks the gesture.
 const { start: startConnect } = useDependencyConnect()
@@ -106,12 +113,16 @@ async function run() {
   const started = await execution.start(props.taskId, pipeline)
   if (started) {
     // Confirm the (optimistic) start landed — the button unmounts once the stream pushes
-    // in_progress, so without this the successful action gives no feedback.
+    // in_progress, so without this the successful action gives no feedback. A sandboxed start
+    // says so here rather than borrowing the live wording: this is the moment the reader learns
+    // what they just started, and the two runs differ in what they will end up doing.
     toast.add({
-      title: t('board.task.startedToast.title'),
-      description: t('board.task.startedToast.body', { name: pipeline.name }),
-      color: 'success',
-      icon: 'i-lucide-play',
+      title: sandboxed.value ? t('board.dryRunToast.title') : t('board.task.startedToast.title'),
+      description: sandboxed.value
+        ? t('board.dryRunToast.body', { name: pipeline.name })
+        : t('board.task.startedToast.body', { name: pipeline.name }),
+      color: sandboxed.value ? 'warning' : 'success',
+      icon: sandboxed.value ? 'i-lucide-shield' : 'i-lucide-play',
     })
   } else {
     starting.value = false
@@ -357,15 +368,19 @@ function selectTask() {
           :color="runnable ? 'primary' : 'neutral'"
           variant="soft"
           size="xs"
-          :icon="runnable ? 'i-lucide-play' : 'i-lucide-lock'"
+          :icon="!runnable ? 'i-lucide-lock' : sandboxed ? 'i-lucide-shield' : 'i-lucide-play'"
           :loading="starting"
           :disabled="!runnable || starting"
           :title="
-            runnable
-              ? t('board.task.startPipeline', {
-                  name: defaultPipeline?.name ?? t('board.task.pipelineFallback'),
-                })
-              : t('board.task.waitingOn', { deps: unmet.map((d) => d.title).join(', ') })
+            !runnable
+              ? t('board.task.waitingOn', { deps: unmet.map((d) => d.title).join(', ') })
+              : sandboxed
+                ? t('board.task.startPipelineDryRun', {
+                    name: defaultPipeline?.name ?? t('board.task.pipelineFallback'),
+                  })
+                : t('board.task.startPipeline', {
+                    name: defaultPipeline?.name ?? t('board.task.pipelineFallback'),
+                  })
           "
           @click.stop="run"
         >

package/app/components/focus/BlockFocusView.vue

@@ -47,10 +47,16 @@ const runOptions = computed(() => {
   )
 })
 
+// The run MODE, shared with the inspector's Run menu so the two surfaces offer (and force) the
+// same thing. The toggle sits beside the picker rather than inside it because the picker's rows
+// START a run on click: a modifier reachable only by opening the list would be one the user has
+// to arm and re-open the menu to use.
+const runStart = useRunStart(() => block.value?.id)
+
 /** Start the picked pipeline immediately — the Run menu chooses an ACTION, it stores no default. */
 function runPipeline(id: string) {
   const pipeline = pipelines.getPipeline(id)
-  if (pipeline && block.value) void execution.start(block.value.id, pipeline)
+  if (pipeline && block.value) void runStart.start(pipeline)
 }
 
 /**
@@ -136,6 +142,28 @@ function openApprovalFor(approvalId: string) {
         >
           {{ t('initiative.inspector.runPlanning') }}
         </UButton>
+        <!-- A sandboxed role cannot ask its way out, so the badge REPLACES the toggle rather
+             than sitting beside it as a switch that does nothing. -->
+        <UBadge
+          v-if="!isInitiative && runStart.forced.value"
+          color="warning"
+          variant="subtle"
+          size="sm"
+          icon="i-lucide-shield"
+          :title="t('focus.dryRunForcedHint')"
+          data-testid="focus-dry-run-forced"
+        >
+          {{ t('focus.dryRun') }}
+        </UBadge>
+        <USwitch
+          v-else-if="!isInitiative && runStart.canRequest.value"
+          :model-value="runStart.requested.value"
+          size="sm"
+          :label="t('focus.dryRun')"
+          :title="t('focus.dryRunHint')"
+          data-testid="focus-dry-run"
+          @update:model-value="runStart.setRequested($event)"
+        />
         <!-- The rich picker rather than a list of names: the run starts the moment a row is
              clicked, so the preview is the only chance to see which agents it will run. -->
         <PipelinePicker

package/app/components/panels/InspectorPanel.vue

@@ -178,6 +178,10 @@ const taskBranchUrl = computed(() => {
   return base ? `${base}/tree/${pr.branch}` : null
 })
 
+// The run MODE, shared with the focus view's Run picker so the two surfaces offer (and force)
+// the same thing.
+const runStart = useRunStart(() => block.value?.id)
+
 // Hide UI-testing pipelines when this block's frame has no UI to exercise, `'recurring'`-only
 // pipelines (a manual run of one is refused server-side), and every pipeline whose purpose doesn't
 // match this block's task type or LEVEL — they'd be refused at run start (see utils/pipeline + the
@@ -186,7 +190,7 @@ const taskBranchUrl = computed(() => {
 // frames and modules too, which is why it reads `block.level` rather than assuming a task.
 const runMenu = computed(() => {
   const frame = block.value ? board.serviceOf(block.value) : undefined
-  return pipelines.pipelines
+  const runnable = pipelines.pipelines
     .filter((p) =>
       pipelineAllowedForManualStart(
         p,
@@ -199,8 +203,40 @@ const runMenu = computed(() => {
     .map((p) => ({
       label: p.name,
       icon: 'i-lucide-play',
-      onSelect: () => block.value && execution.start(block.value.id, p),
+      onSelect: () => void runStart.start(p),
     }))
+  // The run MODE leads the menu, because it changes what every row below it does. A policy
+  // sandbox is stated in both interface tiers as a disabled row: there is nothing to choose, and
+  // a menu that said nothing would leave the user to discover it from a run that never merges.
+  if (runStart.forced.value) {
+    return [
+      [
+        {
+          label: t('panels.inspector.dryRunForced'),
+          icon: 'i-lucide-shield',
+          disabled: true,
+          type: 'label' as const,
+        },
+      ],
+      runnable,
+    ]
+  }
+  if (!runStart.canRequest.value) return runnable
+  return [
+    [
+      {
+        label: t('panels.inspector.dryRun'),
+        icon: 'i-lucide-shield',
+        type: 'checkbox' as const,
+        checked: runStart.requested.value,
+        // Keep the menu open: the choice is a modifier on the pipeline row the user is about to
+        // pick, so closing here would make them reopen the menu to act on it.
+        onSelect: (e: Event) => e.preventDefault(),
+        onUpdateChecked: (checked: boolean) => runStart.setRequested(checked),
+      },
+    ],
+    runnable,
+  ]
 })
 
 // Delegate to the shared confirm-gated deletion so the button and the keyboard shortcut
@@ -515,10 +551,19 @@ const showOriginalDescription = ref(false)
             :color="canRun ? 'primary' : 'neutral'"
             variant="soft"
             size="sm"
-            :icon="canRun ? 'i-lucide-play' : 'i-lucide-lock'"
+            :icon="
+              !canRun
+                ? 'i-lucide-lock'
+                : runStart.dryRun.value
+                  ? 'i-lucide-shield'
+                  : 'i-lucide-play'
+            "
             trailing-icon="i-lucide-chevron-down"
             :disabled="!canRun"
-            :title="runBlockedReason ?? undefined"
+            :title="
+              runBlockedReason ??
+              (runStart.dryRun.value ? t('panels.inspector.dryRunHint') : undefined)
+            "
             data-testid="run-start"
           >
             {{ instance ? t('panels.inspector.reRun') : t('panels.inspector.run') }}

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

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import { isDryRun } from '@cat-factory/contracts'
 import type { Block } from '~/types/domain'
 import { agentKindMeta } from '~/utils/catalog'
 import {
@@ -48,6 +49,12 @@ const reviewStageLabel = computed(() =>
 
 const instance = computed(() => execution.getInstance(props.block.executionId))
 
+// Whether this run may land its work at all. Read through the contracts helper rather than an
+// equality here, so a run persisted before the mode existed (absent ⇒ live) is never badged as a
+// sandbox. Both routes into the mode look identical from here on purpose: what the reader needs
+// is that nothing will merge, and WHY is answered by the run's own notes and the merge decision.
+const sandboxed = computed(() => isDryRun(instance.value?.mode))
+
 // Nothing to show yet: no run, no failed run, no PR, and not awaiting a merge — render an
 // empty state instead of a blank gap so the section reads as "no runs yet" rather than broken.
 const isEmpty = computed(
@@ -266,8 +273,23 @@ async function mergePr() {
     <!-- running pipeline -->
     <div v-if="instance">
       <div class="mb-1 flex items-center justify-between">
-        <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
-          {{ instance.pipelineName }}
+        <span class="flex min-w-0 items-center gap-1.5">
+          <span class="truncate text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            {{ instance.pipelineName }}
+          </span>
+          <!-- A sandboxed run looks exactly like one that simply has not reached the merge yet,
+               right up until it stops there, so it says what it is from the start. -->
+          <UBadge
+            v-if="sandboxed"
+            color="warning"
+            variant="subtle"
+            size="sm"
+            icon="i-lucide-shield"
+            :title="t('inspector.execution.dryRunHint')"
+            data-testid="run-dry-run"
+          >
+            {{ t('inspector.execution.dryRun') }}
+          </UBadge>
         </span>
         <div class="flex items-center gap-1">
           <!-- Stop without deleting: halts the run but keeps it readable + retryable. -->

package/app/components/riskPolicy/RiskPolicyPreview.vue

@@ -8,12 +8,29 @@
 // A policy with auto-merge off has no thresholds to explain (the master switch wins before
 // any score is compared), so it says so instead of listing ceilings that never apply.
 import { computed } from 'vue'
-import type { RiskPolicy } from '~/types/merge'
-import { riskPolicyCeilings, type RiskPolicyAxis } from '~/utils/riskPolicy'
+import type { RiskPolicy, WorkspaceRole } from '~/types/merge'
+import { riskPolicyCeilings, rolePolicySummary, type RiskPolicyAxis } from '~/utils/riskPolicy'
 
 const props = defineProps<{ policy: RiskPolicy }>()
 const { t, n } = useI18n()
 
+// The role layer, when the policy has one. Worth a line here rather than only in settings: this
+// preview is what a task's merge-policy picker shows, and "runs started by a member never merge"
+// changes what picking this policy means for whoever is reading it.
+const ROLE_LABEL: Record<WorkspaceRole, () => string> = {
+  admin: () => t('merge.role.admin'),
+  member: () => t('merge.role.member'),
+  viewer: () => t('merge.role.viewer'),
+}
+const roleLayer = computed(() => {
+  const { sandboxed, narrowed } = rolePolicySummary(props.policy)
+  return {
+    sandboxed: sandboxed.map((r) => ROLE_LABEL[r]()).join(', '),
+    narrowed: narrowed.map((r) => ROLE_LABEL[r]()).join(', '),
+    any: sandboxed.length > 0 || narrowed.length > 0,
+  }
+})
+
 // Exhaustive over the axis union with LITERAL keys, so both i18n drift guards apply: the
 // typed-key check catches a renamed key, and the Record catches a new axis.
 const AXIS_LABEL: Record<RiskPolicyAxis, () => string> = {
@@ -68,6 +85,20 @@ const ceilings = computed(() =>
       </p>
     </div>
 
+    <!-- Who started the run changes what may land, on a policy that says so. -->
+    <div v-if="roleLayer.any" data-testid="risk-policy-preview-roles">
+      <div class="mb-1 flex items-center gap-1 text-[10px] uppercase tracking-wide text-slate-500">
+        <UIcon name="i-lucide-users" class="h-3 w-3" />
+        {{ t('riskPolicy.preview.roleHeading') }}
+      </div>
+      <p v-if="roleLayer.sandboxed" class="text-[12px] leading-snug text-slate-400">
+        {{ t('riskPolicy.preview.roleSandboxed', { roles: roleLayer.sandboxed }) }}
+      </p>
+      <p v-if="roleLayer.narrowed" class="text-[12px] leading-snug text-slate-400">
+        {{ t('riskPolicy.preview.roleNarrowed', { roles: roleLayer.narrowed }) }}
+      </p>
+    </div>
+
     <div>
       <div class="mb-1 flex items-center gap-1 text-[10px] uppercase tracking-wide text-slate-500">
         <UIcon name="i-lucide-wrench" class="h-3 w-3" />

package/app/components/settings/MergeRolePolicyEditor.logic.spec.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest'
+import { MERGE_CLASS_RULES } from '@cat-factory/contracts'
+import type { ClassRulesByRole, MergeClassRules } from '~/types/merge'
+import {
+  INHERIT_RULE,
+  narrowingOptionsFor,
+  roleClassRuleRows,
+  roleNarrowedCount,
+  setRoleClassRule,
+  toggleDryRunRole,
+} from '~/components/settings/MergeRolePolicyEditor.logic'
+
+describe('narrowingOptionsFor', () => {
+  it('offers only the rules that would actually narrow the base', () => {
+    expect(narrowingOptionsFor('always')).toEqual(['thresholds', 'never'])
+    expect(narrowingOptionsFor('thresholds')).toEqual(['never'])
+  })
+
+  // Nothing is stricter than "always require review", so the editor has nothing to offer a role
+  // on that class rather than an option that silently does nothing.
+  it('offers nothing on a class the policy already routes to a human', () => {
+    expect(narrowingOptionsFor('never')).toEqual([])
+  })
+})
+
+// The sentinel is a VALUE the select renders as an item, and Reka UI's `SelectItem` throws on an
+// empty-string value (it reserves `''` for "cleared, show the placeholder"). Nothing here can see
+// that widget, so the invariant it imposes is asserted where it is authored: the failure it
+// prevents is not a wrong label, it is the settings panel throwing when a role group is expanded.
+describe('INHERIT_RULE', () => {
+  it('is a non-empty value the select can carry as an item', () => {
+    expect(INHERIT_RULE).not.toBe('')
+    expect(INHERIT_RULE.length).toBeGreaterThan(0)
+  })
+
+  // It is also not one of the rules, or clearing a row would be indistinguishable from setting it.
+  it('cannot collide with a real rule', () => {
+    expect(MERGE_CLASS_RULES).not.toContain(INHERIT_RULE as string)
+  })
+})
+
+describe('roleClassRuleRows', () => {
+  const base: MergeClassRules = { docs: 'always', schema: 'never' }
+
+  // The sentinel is truthy, so anything asking "did this role author a rule" by testing the
+  // SELECTION rather than the stored entry reads inheritance as a stored rule: it would offer
+  // "same as this policy" twice on every untouched row, and flag every one of them redundant.
+  it('never treats inheritance as a stored rule', () => {
+    for (const row of roleClassRuleRows(base, undefined)) {
+      expect(row.options).not.toContain(INHERIT_RULE as string)
+      expect(row.redundant).toBe(false)
+    }
+  })
+
+  it('reads an absent entry as inheritance, never as thresholds', () => {
+    const rows = roleClassRuleRows(base, undefined)
+    expect(rows.map((r) => r.selected)).toEqual([
+      INHERIT_RULE,
+      INHERIT_RULE,
+      INHERIT_RULE,
+      INHERIT_RULE,
+      INHERIT_RULE,
+      INHERIT_RULE,
+    ])
+    expect(rows.find((r) => r.changeClass === 'docs')?.base).toBe('always')
+    expect(rows.find((r) => r.changeClass === 'source')?.base).toBe('thresholds')
+  })
+
+  it('surfaces the role rule and marks it as governing when it narrows', () => {
+    const rows = roleClassRuleRows(base, { docs: 'never' })
+    const docs = rows.find((r) => r.changeClass === 'docs')
+    expect(docs?.selected).toBe('never')
+    expect(docs?.redundant).toBe(false)
+  })
+
+  // A base edit can turn a stored role rule into a no-op. The row keeps it (so it can be read and
+  // cleared) and says it no longer does anything, rather than dropping it and reading as clean.
+  it('keeps a rule the base rule has overtaken, flagged as having no effect', () => {
+    const rows = roleClassRuleRows({ docs: 'never' }, { docs: 'thresholds' })
+    const docs = rows.find((r) => r.changeClass === 'docs')
+    expect(docs?.selected).toBe('thresholds')
+    expect(docs?.redundant).toBe(true)
+    expect(docs?.options).toContain('thresholds')
+  })
+})
+
+describe('setRoleClassRule', () => {
+  it('writes a rule under the role', () => {
+    expect(setRoleClassRule({}, 'member', 'source', 'never')).toEqual({
+      member: { source: 'never' },
+    })
+  })
+
+  it('clears back to an omission, so absent stays absent', () => {
+    const before: ClassRulesByRole = { member: { source: 'never', docs: 'never' } }
+    expect(setRoleClassRule(before, 'member', 'docs', INHERIT_RULE)).toEqual({
+      member: { source: 'never' },
+    })
+  })
+
+  // `{}` is the identity for the whole feature, so emptying a role's last rule must reach it:
+  // a `{ member: {} }` left behind would read as a role that had been given a policy.
+  it('drops the role entirely once its last rule is cleared', () => {
+    const before: ClassRulesByRole = { admin: { docs: 'never' }, member: { source: 'never' } }
+    expect(setRoleClassRule(before, 'member', 'source', INHERIT_RULE)).toEqual({
+      admin: { docs: 'never' },
+    })
+  })
+
+  it('leaves the other roles untouched', () => {
+    const before: ClassRulesByRole = { admin: { docs: 'never' } }
+    expect(setRoleClassRule(before, 'member', 'source', 'thresholds')).toEqual({
+      admin: { docs: 'never' },
+      member: { source: 'thresholds' },
+    })
+  })
+})
+
+describe('toggleDryRunRole', () => {
+  it('adds and removes a role', () => {
+    expect(toggleDryRunRole([], 'member', true)).toEqual(['member'])
+    expect(toggleDryRunRole(['member'], 'member', false)).toEqual([])
+  })
+
+  it('keeps the shared role order whatever order the toggles arrived in', () => {
+    expect(toggleDryRunRole(['viewer'], 'admin', true)).toEqual(['admin', 'viewer'])
+    expect(toggleDryRunRole(['viewer', 'admin'], 'member', true)).toEqual([
+      'admin',
+      'member',
+      'viewer',
+    ])
+  })
+
+  it('is idempotent on a role already in the state asked for', () => {
+    expect(toggleDryRunRole(['member'], 'member', true)).toEqual(['member'])
+    expect(toggleDryRunRole([], 'member', false)).toEqual([])
+  })
+})
+
+describe('roleNarrowedCount', () => {
+  it('counts the classes a role authored, and reads absence as zero', () => {
+    expect(roleNarrowedCount(undefined)).toBe(0)
+    expect(roleNarrowedCount({})).toBe(0)
+    expect(roleNarrowedCount({ docs: 'never', source: 'never' })).toBe(2)
+  })
+})

package/app/components/settings/MergeRolePolicyEditor.logic.ts

@@ -0,0 +1,133 @@
+// Pure state math behind <MergeRolePolicyEditor>: what a preset's ROLE layer currently says, and
+// what each edit turns it into.
+//
+// It lives outside the SFC because the interesting parts are not the happy path. Two of them:
+//
+//  - **Absent is not a rule.** A role that authored nothing on a class is governed by the base
+//    rule, and that silence must survive a round trip through this editor: an edit clears back to
+//    an OMISSION rather than writing `thresholds`, and a role left with nothing drops out of the
+//    map entirely, so `{}` stays the identity the wire contract says it is.
+//  - **Narrow-only.** `narrowMergeClassRule` (contracts, the same implementation the engine
+//    applies) takes the stricter of the base and the role rule, so a role rule that is looser than
+//    the base does nothing at all. Offering one would tell an operator they had written a policy
+//    when they had written a no-op, so the options a row offers are exactly the rules that would
+//    change its outcome, plus whatever is already stored.
+import {
+  MERGE_CLASS_RULES,
+  narrowMergeClassRule,
+  RULEABLE_CHANGE_CLASSES,
+  WORKSPACE_ROLES,
+} from '@cat-factory/contracts'
+import type {
+  ClassRulesByRole,
+  MergeClassRule,
+  MergeClassRules,
+  RuleableChangeClass,
+  WorkspaceRole,
+} from '~/types/merge'
+
+/**
+ * The "this role adds nothing here" selection, stored as an OMISSION.
+ *
+ * It must be a non-empty string, and not because of a style preference: the select this feeds is
+ * Nuxt UI's `USelect` over Reka UI, whose `SelectItem` THROWS on an empty-string value (the empty
+ * string is how that widget spells "cleared, show the placeholder", so an item may not claim it).
+ * A `''` sentinel therefore does not degrade, it takes down the settings panel the moment a role
+ * group is expanded. It is a member of the selection union rather than `undefined` for the same
+ * reason: the row has to be able to OFFER inheriting as a choice, which is a value.
+ */
+export const INHERIT_RULE = 'inherit' as const
+export type RoleRuleSelection = MergeClassRule | typeof INHERIT_RULE
+
+/** One class's row inside one role's group. */
+export interface RoleClassRuleRow {
+  changeClass: RuleableChangeClass
+  /** What the preset's base `classRules` say for this class (what the row inherits). */
+  base: MergeClassRule
+  /** The role's own entry, or {@link INHERIT_RULE} when it authored none. */
+  selected: RoleRuleSelection
+  /**
+   * The rules this row may be set to: the ones strictly stricter than `base` (a looser one is
+   * discarded by the engine), plus the stored value whatever it is, so a rule that a later base
+   * edit turned into a no-op stays visible and clearable instead of vanishing from its own row.
+   */
+  options: MergeClassRule[]
+  /**
+   * The stored rule no longer changes anything, because the base rule is already at least as
+   * strict. Not an error and not silently dropped: the operator wrote it down, and the honest
+   * report is that the base map now covers it.
+   */
+  redundant: boolean
+}
+
+/**
+ * The rules that would actually narrow `base`. Empty for `never`, which is already the strictest
+ * rule there is, so a class the preset always routes to a human offers a role nothing to add.
+ */
+export function narrowingOptionsFor(base: MergeClassRule): MergeClassRule[] {
+  return MERGE_CLASS_RULES.filter((rule) => narrowMergeClassRule(base, rule) !== base)
+}
+
+/** One role's rows, in the shared class order, against the preset's base rules. */
+export function roleClassRuleRows(
+  base: MergeClassRules,
+  entry: MergeClassRules | undefined,
+): RoleClassRuleRow[] {
+  return RULEABLE_CHANGE_CLASSES.map((changeClass) => {
+    const baseRule = base[changeClass] ?? 'thresholds'
+    // The role's own rule, or nothing at all. Held as `undefined` rather than folded into
+    // `selected` up front because "did this role author a rule here" is the question the two
+    // lines below both ask, and an absent entry is the one answer that is not one of the three
+    // rules. Testing the SENTINEL for that would tie them to whatever string it happens to be.
+    const stored = entry?.[changeClass]
+    const narrowing = narrowingOptionsFor(baseRule)
+    return {
+      changeClass,
+      base: baseRule,
+      selected: stored ?? INHERIT_RULE,
+      options: stored && !narrowing.includes(stored) ? [...narrowing, stored] : narrowing,
+      redundant: !!stored && narrowMergeClassRule(baseRule, stored) === baseRule,
+    }
+  })
+}
+
+/**
+ * Set (or clear) one role's rule for one class, pruning back to the identity: clearing the last
+ * rule a role carried removes the role's entry, so a preset an operator has emptied is byte-for-byte
+ * the `{}` a preset that never had a role rule carries.
+ */
+export function setRoleClassRule(
+  byRole: ClassRulesByRole,
+  role: WorkspaceRole,
+  changeClass: RuleableChangeClass,
+  rule: RoleRuleSelection,
+): ClassRulesByRole {
+  const entry: MergeClassRules = { ...byRole[role] }
+  if (rule === INHERIT_RULE) delete entry[changeClass]
+  else entry[changeClass] = rule
+  const next: ClassRulesByRole = { ...byRole }
+  if (Object.keys(entry).length === 0) delete next[role]
+  else next[role] = entry
+  return next
+}
+
+/**
+ * Add or remove a role from the sandboxed list, keeping it in the shared role order so two presets
+ * carrying the same policy carry the same array (and a diff of a preset reads as an edit rather
+ * than a reshuffle).
+ */
+export function toggleDryRunRole(
+  roles: readonly WorkspaceRole[],
+  role: WorkspaceRole,
+  sandboxed: boolean,
+): WorkspaceRole[] {
+  const next = new Set(roles)
+  if (sandboxed) next.add(role)
+  else next.delete(role)
+  return WORKSPACE_ROLES.filter((r) => next.has(r))
+}
+
+/** How many classes a role has authored a rule for (the collapsed group's summary). */
+export function roleNarrowedCount(entry: MergeClassRules | undefined): number {
+  return entry ? Object.keys(entry).length : 0
+}