refactor(push): extract reconcileStateKeyForResource — fold two ensure-fns into one generic helper (#34)

* refactor(engine): extract shared slug + folder helpers into slug-utils (#35)

Consolidates 4+ duplicated helpers that had accumulated across the
gitops engine as symptom-fixes piled up. Pure factoring, zero
behavior change at every reachable call site.

Duplications collapsed:
  - `slugify` — 4 byte-identical copies (pull.ts, dep-dedup.ts,
    audit.ts, setup.ts) → 1 in src/slug-utils.ts
  - `extractBaseSlug` — 2 byte-identical copies → 1
  - `FOLDER_MAP` — 2 byte-identical copies (pull.ts, resources.ts) → 1
  - `UUID_SUFFIX_RE` — open-coded in 3 places → 1 constant
  - recanonicalize's inlined precondition-2 check (UUID prefix match)
    → extracted as `isEngineSuffixedSlug`

src/slug-utils.ts is config-free by design (no `./config.ts` import,
no side effects at load) so it's safely importable from any test
without priming process.argv / VAPI_TOKEN. This is the testability
property the prior dep-dedup.ts comment claimed for its local
duplicates but didn't actually enforce.

Regex tightening: shared `UUID_SUFFIX_RE` uses `^(.+)-([0-9a-f]{8})$`
(non-empty base) where the prior pull/dep-dedup copies used
`^(.*)-...` (allowed empty base). Strict improvement — engine-
generated keys always have a non-empty base, and the only input
class affected is the synthetic `-<8hex>` shape which is never
produced by `generateResourceId`. Pinned by a regression test in
tests/slug-utils.test.ts.

Back-compat: dep-dedup.ts re-exports slugify/extractBaseSlug so
existing tests importing them via that path keep working.

Tests: 228/228 pass (208 prior + 20 new slug-utils cases covering
slugify behavior, UUID_SUFFIX_RE boundaries, extractBaseSlug loose
form, isEngineSuffixedSlug strict form).

* refactor(push): extract reconcileStateKeyForResource — fold two 94-line ensure-fns into one generic helper

`ensureToolExists` and `ensureStructuredOutputExists` were structurally
identical 94-line functions differing only in: resource type label,
apply function, state section, remote-list cache, and the per-type
bookkeeping array. Both implemented the same dedup-then-apply flow:
look up existing dashboard/state match by canonical name, adopt with
orphan-deletion guard, mark `touched` for `mergeScoped`, call apply.

Behavioral contract preserved exactly:
  - Log strings byte-identical (verified path-by-path against
    pre-refactor)
  - `autoApplied.add` BEFORE the `if (!uuid) return` early-exit
  - `applied[type]++`, `pushToAutoAppliedList`, `touched.add` AFTER
    the null check — preserves dry-run / drift-halt semantics
  - Orphan-deletion guard scope unchanged: deletes state keys
    pointing at the adopted UUID, leaves `duplicateUuids` alone for
    `npm run cleanup` to handle
  - try/catch boundary identical
  - All 228 prior tests pass unchanged, including the integration
    test in tests/push-dry-run.test.ts

push.ts shrunk -129 net LOC (two 94-line functions collapsed to
~14-line wrappers). Helper is `tools | structuredOutputs` narrow
today; adding a future type requires a deliberate union widening
+ LABELS map entry, not a config flag.

`vapiEnv` and `formatError` parameters are required (not optional
with placeholder defaults) so a future caller can't accidentally
emit a degraded warning or error message.

Tests: 244/244 pass (228 prior + 16 new — 8 scenarios × 2 resource
types covering happy path, ambiguous match, null applyFn ordering
contract, orphan-deletion guard scope, run-scoped idempotency,
state-hit/dashboard-hit/no-match branches).

Closes the symptom-fix pattern documented in improvements.md #10
(now handled by the generic helper instead of the two hardcoded
functions).

Author: dhruva-reddy

src/push.ts

@@ -26,6 +26,7 @@ import {
   formatRecanonicalizeReport,
   recanonicalizeStateKeys,
 } from "./recanonicalize.ts";
+import { reconcileStateKeyForResource } from "./reconcile-state-key.ts";
 import { writeSnapshot } from "./snapshot.ts";
 import { mergeScoped } from "./state-merge.ts";
 import {
@@ -947,85 +948,19 @@ async function ensureToolExists(
   const tool = ctx.allTools.find((t) => t.resourceId === toolId);
   if (!tool) return;
 
-  // Before creating, check whether an existing state entry (under a
-  // different key — e.g., bootstrap-generated `end-call-<uuid8>`) or a
-  // live dashboard tool already represents this same logical tool. Adopt
-  // instead of minting a duplicate.
-  const remoteList = await getExistingRemoteTools(ctx);
-  const match = findExistingResourceByName({
-    localResourceId: toolId,
-    localPayload: tool.data,
-    stateSection: ctx.state.tools,
-    remoteList,
+  await reconcileStateKeyForResource({
+    resourceType: "tools",
+    resource: tool,
+    state: ctx.state,
+    touched: ctx.touched,
+    applied: ctx.applied,
+    autoApplied: ctx.autoApplied,
+    pushToAutoAppliedList: (r) => ctx.autoAppliedTools.push(r),
+    getRemoteList: () => getExistingRemoteTools(ctx),
+    applyFn: applyTool,
+    vapiEnv: VAPI_ENV,
+    formatError: formatApiError,
   });
-  if (match) {
-    if (match.ambiguous) {
-      const displayName = extractResourceName(tool.data) ?? toolId;
-      console.warn(
-        `  ⚠️  Multiple dashboard tools share the name "${displayName}" — adopting ${match.uuid} (lex-smallest). Other UUIDs: ${match.duplicateUuids.join(", ")}. Run \`npm run cleanup -- ${VAPI_ENV}\` to prune duplicates.`,
-      );
-    }
-    console.log(
-      `  🔁 Reusing existing tool: ${toolId} → ${match.uuid} (matched via ${match.source})`,
-    );
-
-    // Re-key state to point at the adopted UUID under the local resourceId.
-    // No hash yet — applyTool below will PATCH with the local payload and
-    // record the post-PATCH hash, exercising the standard drift-check flow.
-    upsertState(ctx.state.tools, tool.resourceId, { uuid: match.uuid });
-
-    // Orphan-deletion guard — drop other state keys pointing at the SAME
-    // uuid so a subsequent full push doesn't see them as "tracked but no
-    // local file" and DELETE the dashboard resource we just adopted. Mark
-    // them touched so the scoped state-merge on save flushes the deletion.
-    // Entries pointing at `match.duplicateUuids` are SEPARATE dashboard
-    // duplicates — leave them alone; `npm run cleanup` handles those.
-    for (const [staleKey, entry] of Object.entries(ctx.state.tools)) {
-      if (staleKey !== tool.resourceId && entry.uuid === match.uuid) {
-        delete ctx.state.tools[staleKey];
-        ctx.touched.tools.add(staleKey);
-      }
-    }
-
-    // PATCH the dashboard with the local payload. `applyTool`'s
-    // `upsertResourceWithStateRecovery` branch picks PATCH because
-    // `state.tools` now has `existingUuid` set. Drift check fires
-    // (no-baseline → log + proceed when `lastPulledHash` is undefined;
-    // full check when it isn't).
-    try {
-      const uuid = await applyTool(tool, ctx.state);
-      ctx.autoApplied.add(`tools:${toolId}`);
-      if (!uuid) return;
-      upsertState(ctx.state.tools, tool.resourceId, {
-        uuid,
-        lastPushedHash: hashPayload(tool.data),
-      });
-      ctx.applied.tools++;
-      ctx.autoAppliedTools.push(tool);
-      ctx.touched.tools.add(tool.resourceId);
-    } catch (error) {
-      console.error(formatApiError(toolId, error));
-      throw error;
-    }
-    return;
-  }
-
-  console.log(`  📦 Auto-applying dependency → tool: ${toolId}`);
-  try {
-    const uuid = await applyTool(tool, ctx.state);
-    ctx.autoApplied.add(`tools:${toolId}`);
-    if (!uuid) return;
-    upsertState(ctx.state.tools, tool.resourceId, {
-      uuid,
-      lastPushedHash: hashPayload(tool.data),
-    });
-    ctx.applied.tools++;
-    ctx.autoAppliedTools.push(tool);
-    ctx.touched.tools.add(tool.resourceId);
-  } catch (error) {
-    console.error(formatApiError(toolId, error));
-    throw error;
-  }
 }
 
 async function ensureStructuredOutputExists(
@@ -1044,83 +979,19 @@ async function ensureStructuredOutputExists(
   );
   if (!output) return;
 
-  // Same dedup pattern as `ensureToolExists`, against the SO state section
-  // and live dashboard SO list.
-  const remoteList = await getExistingRemoteStructuredOutputs(ctx);
-  const match = findExistingResourceByName({
-    localResourceId: outputId,
-    localPayload: output.data,
-    stateSection: ctx.state.structuredOutputs,
-    remoteList,
+  await reconcileStateKeyForResource({
+    resourceType: "structuredOutputs",
+    resource: output,
+    state: ctx.state,
+    touched: ctx.touched,
+    applied: ctx.applied,
+    autoApplied: ctx.autoApplied,
+    pushToAutoAppliedList: (r) => ctx.autoAppliedStructuredOutputs.push(r),
+    getRemoteList: () => getExistingRemoteStructuredOutputs(ctx),
+    applyFn: applyStructuredOutput,
+    vapiEnv: VAPI_ENV,
+    formatError: formatApiError,
   });
-  if (match) {
-    if (match.ambiguous) {
-      const displayName = extractResourceName(output.data) ?? outputId;
-      console.warn(
-        `  ⚠️  Multiple dashboard structured outputs share the name "${displayName}" — adopting ${match.uuid} (lex-smallest). Other UUIDs: ${match.duplicateUuids.join(", ")}. Run \`npm run cleanup -- ${VAPI_ENV}\` to prune duplicates.`,
-      );
-    }
-    console.log(
-      `  🔁 Reusing existing structured output: ${outputId} → ${match.uuid} (matched via ${match.source})`,
-    );
-
-    // Re-key state to point at the adopted UUID under the local resourceId.
-    // No hash yet — applyStructuredOutput below will PATCH with the local
-    // payload and record the post-PATCH hash, exercising the standard
-    // drift-check flow.
-    upsertState(ctx.state.structuredOutputs, output.resourceId, {
-      uuid: match.uuid,
-    });
-
-    // Orphan-deletion guard — drop other state keys pointing at the SAME
-    // uuid so a subsequent full push doesn't see them as "tracked but no
-    // local file" and DELETE the dashboard resource we just adopted. Mark
-    // them touched so the scoped state-merge on save flushes the deletion.
-    for (const [staleKey, entry] of Object.entries(
-      ctx.state.structuredOutputs,
-    )) {
-      if (staleKey !== output.resourceId && entry.uuid === match.uuid) {
-        delete ctx.state.structuredOutputs[staleKey];
-        ctx.touched.structuredOutputs.add(staleKey);
-      }
-    }
-
-    // PATCH via the standard apply path so drift detection fires and any
-    // local edits land on the dashboard.
-    try {
-      const uuid = await applyStructuredOutput(output, ctx.state);
-      ctx.autoApplied.add(`structuredOutputs:${outputId}`);
-      if (!uuid) return;
-      upsertState(ctx.state.structuredOutputs, output.resourceId, {
-        uuid,
-        lastPushedHash: hashPayload(output.data),
-      });
-      ctx.applied.structuredOutputs++;
-      ctx.autoAppliedStructuredOutputs.push(output);
-      ctx.touched.structuredOutputs.add(output.resourceId);
-    } catch (error) {
-      console.error(formatApiError(outputId, error));
-      throw error;
-    }
-    return;
-  }
-
-  console.log(`  📦 Auto-applying dependency → structured output: ${outputId}`);
-  try {
-    const uuid = await applyStructuredOutput(output, ctx.state);
-    ctx.autoApplied.add(`structuredOutputs:${outputId}`);
-    if (!uuid) return;
-    upsertState(ctx.state.structuredOutputs, output.resourceId, {
-      uuid,
-      lastPushedHash: hashPayload(output.data),
-    });
-    ctx.applied.structuredOutputs++;
-    ctx.autoAppliedStructuredOutputs.push(output);
-    ctx.touched.structuredOutputs.add(output.resourceId);
-  } catch (error) {
-    console.error(formatApiError(outputId, error));
-    throw error;
-  }
 }
 
 async function ensureAssistantDepsExist(