feat(push): orphan-YAML gate — halt push when local files lack state entries (#30)

* feat(push): orphan-YAML gate — halt push when local files lack state entries

Catches the duplicate-creation patterns surfaced during the gitops-mudflap
working session 2026-05-13:

- Flow F: user renames a file locally (`mv foo.md bar.md`) then pushes. bar.md
  has no state entry → engine silently POSTed as a new resource, leaving the
  original foo's UUID orphaned on the dashboard.
- Flow G: dashboard rename → pull writes a new <name>-<uuid8>.md file but
  leaves the old YAML on disk. Next push iterates the old YAML, POSTs it,
  creates a duplicate.
- Flow M: `npm run apply` (pull → merge → push) compresses Flow G into one
  click, silently spawning duplicates.

The gate is default-on. When it fires, push exits 1 with a verbose error
that lists every orphan, pairs orphans with possible state-only rename
sources by shared base-slug, and includes an AI-agent-addressed paragraph
explicitly asking agents NOT to auto-pass --allow-new-files without
confirming with the human.

ANSI color when stderr is a TTY; plain text when piped/captured (CI, AI
agent stdout capture).

Override: --allow-new-files flag bypasses the gate with a one-line notice.
Apply propagates the flag through `pushArgs`.

Bootstrap mode (empty state) suppresses the gate — genuine first-time
pushes are all "new".

Selective push (`-- <paths>`) scopes the gate to the selection. Unrelated
orphans elsewhere don't block.

Reuses audit.ts's `checkOrphanYaml` detection via a shared
`findOrphanResourceIds` helper exported from new-file-gate.ts — single
source of truth for "what counts as an orphan YAML".

Suite: 188/188 tests pass (21 new for this gate).

* fix(new-file-gate): respect .vapi-ignore + use real env in paths + dry-run verb

Addresses three code-review findings on the new-file-gate PR:

1. **M1 — .vapi-ignore now suppresses the gate** for files the customer
   has explicitly opted out of gitops tracking. Without this, the gate
   would halt every push for stale dashboard artifacts that customers
   keep around (silenced via .vapi-ignore) — defeating both the
   .vapi-ignore workaround and the gate's intent of catching REAL
   rename / orphan cases. Same `matchesIgnore` helper that audit.ts
   uses; injected via the gate's DI options for filesystem-free tests.

2. **M2 — `<org>` placeholder in relativePath replaced with real
   `VAPI_ENV`**. Previously the gate's message rendered
   `resources/<org>/...` literally. Now renders e.g.
   `resources/mudflap-prod/...`. Tests updated to use `[^/]+` regex
   class so they work regardless of the test env name.

3. **M2 — asymmetric `filter.endsWith(relativePath)` direction
   removed** from `pathMatchesAnyFilter`. The remaining checks
   (exact match, suffix match, resourceId-with-extension tail match)
   cover the real cases without over-matching when relativePath is
   short.

Cleanups:
- Dead UUID-length conditional in formatGateMessage (real UUIDs are
  always 36 chars, slice always fires) → unconditional slice.
- Duplicate `(possible rename SOURCES):` header in both branches of
  the rename-sources block → print header once, then either '(none)'
  or entries.
- Dry-run-aware verb in the bypass notice: "would create" vs
  "creating" based on DRY_RUN flag.

New test: pin .vapi-ignore suppression as a regression guard against
re-introducing the M1 bug. 189/189 tests pass.

Author: dhruva-vapi

src/apply.ts

@@ -33,17 +33,28 @@ export async function runApply(): Promise<void> {
   const pushArgs = allArgs.join(" ");
 
   if (!env || !SLUG_RE.test(env)) {
-    console.error("Usage: npm run apply <org> [--force]");
+    console.error("Usage: npm run apply <org> [--force] [--allow-new-files]");
     console.error("");
     console.error("  Pull → Merge → Push (safe bidirectional sync)");
     console.error("");
     console.error("  Pulls latest platform state (preserving local changes),");
     console.error("  then pushes the result back to the platform.");
     console.error("");
     console.error(
-      "  --force   Enable deletions: resources you deleted locally",
+      "  --force            Enable deletions: resources you deleted locally",
+    );
+    console.error(
+      "                     will also be deleted from the platform.",
+    );
+    console.error(
+      "  --allow-new-files  Bypass the orphan-YAML pre-flight gate (push stage).",
+    );
+    console.error(
+      "                     Use only after confirming every local file without a",
+    );
+    console.error(
+      "                     state entry is genuinely new — see src/new-file-gate.ts.",
     );
-    console.error("            will also be deleted from the platform.");
     process.exit(1);
   }
 

src/audit.ts

@@ -21,6 +21,7 @@
 import { readFile } from "fs/promises";
 import { join } from "path";
 import { matchesIgnore, RESOURCES_DIR } from "./config.ts";
+import { findOrphanResourceIds } from "./new-file-gate.ts";
 import {
   extractBaseSlug,
   fetchAllResources,
@@ -179,21 +180,20 @@ function checkOrphanYaml(
   localIds: string[],
   state: StateFile,
 ): AuditFinding[] {
-  const stateKeys = new Set(Object.keys(state[type]));
-  const findings: AuditFinding[] = [];
-  for (const localId of localIds) {
-    if (stateKeys.has(localId)) continue;
-    findings.push({
-      severity: "warn",
-      type,
-      rule: "orphan-yaml",
-      resourceIds: [localId],
-      message: `local file ${type}/${localId} has no state entry`,
-      suggestedAction:
-        "delete file OR run `npm run pull` to re-key it into state",
-    });
-  }
-  return findings;
+  // Single source of truth for "what counts as an orphan YAML" — shared with
+  // the push-time pre-flight gate in src/new-file-gate.ts. Both surfaces map
+  // the same predicate to different output shapes (here: AuditFinding[];
+  // there: OrphanFile[] + verbose halt message).
+  const orphanIds = findOrphanResourceIds(type, localIds, state);
+  return orphanIds.map((localId) => ({
+    severity: "warn",
+    type,
+    rule: "orphan-yaml",
+    resourceIds: [localId],
+    message: `local file ${type}/${localId} has no state entry`,
+    suggestedAction:
+      "delete file OR run `npm run pull` to re-key it into state",
+  }));
 }
 
 function checkStateGhosts(

src/config.ts

@@ -44,6 +44,9 @@ function parseEnvironment(): Environment {
     console.error(
       "          --type <type> (apply only specific resource type, repeatable)",
     );
+    console.error(
+      "          --allow-new-files (bypass orphan-YAML pre-flight gate)",
+    );
     console.error("          -- <file...> (apply only specific files)");
     process.exit(1);
   }
@@ -88,6 +91,7 @@ function parseFlags(): {
   dryRun: boolean;
   strictValidation: boolean;
   overwriteDrift: boolean;
+  allowNewFiles: boolean;
   applyFilter: ApplyFilter;
 } {
   const args = process.argv.slice(3);
@@ -97,13 +101,15 @@ function parseFlags(): {
     dryRun: boolean;
     strictValidation: boolean;
     overwriteDrift: boolean;
+    allowNewFiles: boolean;
     applyFilter: ApplyFilter;
   } = {
     forceDelete: args.includes("--force"),
     bootstrapSync: args.includes("--bootstrap"),
     dryRun: args.includes("--dry-run"),
     strictValidation: args.includes("--strict"),
     overwriteDrift: args.includes("--overwrite"),
+    allowNewFiles: args.includes("--allow-new-files"),
     applyFilter: {},
   };
 
@@ -119,7 +125,8 @@ function parseFlags(): {
       arg === "--bootstrap" ||
       arg === "--dry-run" ||
       arg === "--strict" ||
-      arg === "--overwrite"
+      arg === "--overwrite" ||
+      arg === "--allow-new-files"
     )
       continue;
 
@@ -184,7 +191,7 @@ function parseFlags(): {
     console.error(
       `   Expected a resource type (e.g. assistants, tools), a folder path ` +
         `(e.g. assistants/foo.yml or resources/<org>/assistants/foo.yml), or ` +
-        `a flag (--force, --bootstrap, --type, --id).`,
+        `a flag (--force, --bootstrap, --type, --id, --allow-new-files).`,
     );
     process.exit(1);
   }
@@ -257,6 +264,7 @@ export const {
   dryRun: DRY_RUN,
   strictValidation: STRICT_VALIDATION,
   overwriteDrift: OVERWRITE_DRIFT,
+  allowNewFiles: ALLOW_NEW_FILES,
   applyFilter: APPLY_FILTER,
 } = parseFlags();