@nitra/cfr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @nitra/cfr
+
+Kustomize's `resources:` field is an **explicit list**, not a glob. Add a
+YAML manifest to a directory managed by a [Flux](https://fluxcd.io)
+`Kustomization` without listing it in `resources:`, and
+`kustomize-controller` silently skips it — no error, no warning, the
+object just never reaches the cluster.
+
+This CLI catches that drift before it ships: it compares every
+`*.yaml`/`*.yml` file physically present in a directory against the
+`resources:` list in its `kustomization.yaml`, in both directions.
+
+## Usage
+
+```sh
+npx @nitra/cfr [dir-or-kustomization.yaml ...]
+```
+
+No arguments checks `.`. Point it at one or more directories (or direct
+paths to a `kustomization.yaml`/`kustomization.yml`):
+
+```sh
+npx @nitra/cfr flux/clusters/production
+```
+
+```
+✗ flux/clusters/production/kustomization.yaml
+  on disk but missing from resources: (Flux will not apply them):
+    - new-app.yaml
+```
+
+Exits `0` when every target is consistent, `1` otherwise — wire it into CI
+on any path that touches a Kustomize directory with an explicit
+`resources:` list:
+
+```yaml
+# .github/workflows/cfr.yml
+on:
+  push:
+    paths: ['flux/clusters/production/**']
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: npx @nitra/cfr flux/clusters/production
+```
+
+## What it checks
+
+For each target directory:
+
+- every `*.yaml`/`*.yml` file in the directory (except the
+  `kustomization.yaml` itself) must appear in `resources:`
+- every `resources:` entry that is a plain local filename (no `/`, no URL
+  scheme) must exist on disk
+
+Entries containing `/` (subdirectories, components) or a URL scheme
+(remote bases) are out of scope and skipped — this tool only guards
+against the specific footgun of a loose file sitting next to
+`kustomization.yaml` that nobody remembered to list.
+
+## Why this exists
+
+A real incident: a PR added two manifests to a Flux cluster directory but
+missed adding them to `resources:`. The PR merged clean, CI was green,
+`git log` showed the files — and Flux applied nothing. No error surfaced
+anywhere; the only symptom was the feature silently not existing in the
+cluster. This tool turns that into a CI failure at PR time instead.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Kustomize's `resources:` field is an explicit list, not a glob. Add a
+// YAML file to a Kustomize directory without listing it there and
+// kustomize-controller silently skips it — no error, no warning, the
+// resource just never reaches the cluster. This CLI catches that drift
+// before it ships.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const HELP = `cfr (@nitra/cfr) — verify kustomization.yaml resources: match the directory
+
+Usage:
+  npx @nitra/cfr [dir-or-kustomization.yaml ...]
+
+Each argument is either a directory containing a kustomization.yaml (or
+kustomization.yml), or a direct path to one. Defaults to "." when no
+argument is given.
+
+For each target, compares:
+  - every *.yaml/*.yml file physically present in the directory
+  - every plain-filename entry under the top-level "resources:" list
+
+and reports both directions: files on disk missing from resources: (Flux
+will never apply them), and resources: entries with no matching file
+(dead reference). Entries containing "/" or a URL scheme (subdirectories,
+components, remote bases) are out of scope and skipped.
+
+Exits 0 when every target is consistent, 1 otherwise.
+
+Options:
+  -h, --help    Show this help and exit.
+`;
+
+function findKustomization(target) {
+  const abs = resolve(target);
+  let stat;
+  try {
+    stat = statSync(abs);
+  } catch {
+    return { error: `${target}: no such file or directory` };
+  }
+  if (stat.isFile()) {
+    return { dir: dirname(abs), file: abs };
+  }
+  for (const name of ['kustomization.yaml', 'kustomization.yml']) {
+    const candidate = join(abs, name);
+    try {
+      if (statSync(candidate).isFile()) return { dir: abs, file: candidate };
+    } catch {
+      // try next
+    }
+  }
+  return { error: `${target}: no kustomization.yaml (or .yml) found` };
+}
+
+function extractResources(text) {
+  const lines = text.split('\n');
+  const entries = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock) {
+      if (/^resources:\s*(#.*)?$/.test(line)) inBlock = true;
+      continue;
+    }
+    if (line.trim() === '') continue;
+    const item = line.match(/^\s+-\s*(.+?)\s*(#.*)?$/);
+    if (!item) break; // dedented past the list — block is over
+    let value = item[1].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    entries.push(value);
+  }
+  return entries;
+}
+
+function isLocalYamlFilename(entry) {
+  return /^[^/]+\.ya?ml$/i.test(entry) && !/^[a-z]+:\/\//i.test(entry);
+}
+
+function checkTarget(target) {
+  const found = findKustomization(target);
+  if (found.error) return { target, ok: false, error: found.error };
+
+  const { dir, file } = found;
+  const onDisk = new Set(
+    readdirSync(dir).filter((name) => /\.ya?ml$/i.test(name) && join(dir, name) !== file),
+  );
+
+  const listedAll = extractResources(readFileSync(file, 'utf8'));
+  const listedLocal = new Set(listedAll.filter(isLocalYamlFilename));
+
+  const missing = [...onDisk].filter((name) => !listedLocal.has(name)).sort();
+  const dangling = [...listedLocal].filter((name) => !onDisk.has(name)).sort();
+
+  return { target, ok: missing.length === 0 && dangling.length === 0, file, missing, dangling };
+}
+
+function main(argv) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const targets = argv.length > 0 ? argv : ['.'];
+  let exitCode = 0;
+
+  for (const target of targets) {
+    const result = checkTarget(target);
+    if (result.error) {
+      console.error(`✗ ${result.target}: ${result.error}`);
+      exitCode = 1;
+      continue;
+    }
+    if (result.ok) {
+      console.log(`✓ ${result.file}`);
+      continue;
+    }
+    exitCode = 1;
+    console.error(`✗ ${result.file}`);
+    if (result.missing.length > 0) {
+      console.error('  on disk but missing from resources: (Flux will not apply them):');
+      for (const name of result.missing) console.error(`    - ${name}`);
+    }
+    if (result.dangling.length > 0) {
+      console.error('  listed in resources: but missing on disk:');
+      for (const name of result.dangling) console.error(`    - ${name}`);
+    }
+  }
+
+  return exitCode;
+}
+
+process.exit(main(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nitra/cfr",
+  "version": "0.1.0",
+  "description": "Verify that every YAML file in a Kustomize directory is listed in kustomization.yaml's explicit resources: (and vice versa) — catches files Flux silently ignores.",
+  "keywords": [
+    "kustomize",
+    "flux",
+    "fluxcd",
+    "kubernetes",
+    "gitops",
+    "lint"
+  ],
+  "homepage": "https://github.com/nitra/cfr#readme",
+  "bugs": "https://github.com/nitra/cfr/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/cfr.git"
+  },
+  "license": "MIT",
+  "author": "Nitra <info@nitralabs.com> (https://nitra.ai)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "cfr": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/cli.test.mjs"
+  }
+}