Build a Nano app with a coding agent

// A guard for the work of a coding agent on a Nano app: it reads a project and says what must not be in it.
// From the nano133.com guide "Build a Nano app with a coding agent". MIT license.
// Node.js 18 or newer, no packages. It only reads files: it changes nothing and it asks no network.
//
//   node agent-guard.mjs <project folder>
//       scans the project and prints one line for each finding: path:line  rule  what is wrong.
//       It ends with exit code 0 when there is no finding, 1 when there is one, and 2 when it cannot read the folder.
//
//   node agent-guard.mjs <project folder> --changed <file>
//       also reads a list of changed paths, one on each line (for example the output of `git diff --name-only`), and
//       refuses each path that an agent must not change.
//
// What it looks for:
//   seed-in-file       a 64-character hex value written next to a name like seed, secret or private key
//   secret-file        a file that holds secrets: .env, .dev.vars, *.pem, *.key, a service account key
//   float-money        an amount made with parseFloat or Number(amount), or with 1e30, instead of whole numbers of raw
//   real-money-test    a test that can send: the `process` action, or work_generate, next to a node that is not on this computer
//   log-secret         a log line that names a seed, a secret or a private key
//   changed-path       a changed path that an agent must not change (the list below, and the patterns in .agent-never)
//
// It only reads. It writes no file, it runs no program and it makes no network call: its imports are the read functions of node:fs,
// node:path and node:url, and the test script of the guide checks that.
//
// It is not a proof. It finds the mistakes that are easy to find, by patterns, so it misses some and it raises some false alarms:
// a seed in another form (a word list, base64, a value built in code, a value cut in two) is not found, and a 64-character hash that
// sits next to a name such as secret or key is reported as a seed. A person still reads the money code.

import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative, sep } from "node:path";
import { pathToFileURL } from "node:url";

const SKIP_DIRS = new Set([".git", "node_modules", ".wrangler", ".next", "dist", "build", "coverage"]);
const MAX_BYTES = 1_000_000; // a file larger than this is not code

/** Paths that an agent must not change, as patterns. `*` is any text without a slash, `**` is any text. A pattern that ends in `/` is a folder. */
export const NEVER_CHANGE = [".env", ".env.*", ".dev.vars", "*.pem", "*.key", "*.p12", ".github/", "infra/", "terraform/", "*.tf", "secrets/", "firestore.rules", "iam*", ".agent-never", "agent-guard.mjs"];
/** Files that hold secrets, by name. The examples that carry no value are fine. */
const SECRET_FILE = /^(\.env(\.[\w-]+)?|\.dev\.vars|id_rsa[\w.-]*|credentials\.json|service-?account[\w.-]*\.json|[\w.-]+\.(pem|key|p12))$/i;
const EXAMPLE_FILE = /\.(example|sample|template)$/i;

const SEED_NAME = /(seed|secret|private[_-]?key|priv[_-]?key)\w*/i;
const SEED_VALUE = new RegExp(`${SEED_NAME.source}["']?\\s*[:=]\\s*["'\`]?[0-9a-fA-F]{64}(?![0-9a-fA-F])`, "i");
const FLOAT_MONEY = /parseFloat\s*\([^)]*\b(raw|xno|amount|balance|price)\b|Number\s*\(\s*[\w.]*(raw|xno|amount|balance|price)[\w.]*\s*\)/i;
const FLOAT_EXPONENT = /(?<![\w.])1e\+?30\b|Math\.pow\(\s*10\s*,\s*30\s*\)|(?<!\d)10\s*\*\*\s*30(?!n)/;
const LOG_SECRET = /console\.(log|error|info|warn|debug)\s*\([^)]*\b(seed|secret|privateKey|private_key|mnemonic)\b/;
const SENDS = /["'`]process["'`]|work_generate/;
const REMOTE_NODE = /https?:\/\/(?!(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)\b)[\w.-]+/;
const IS_TEST = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)test\.mjs$/;
const CODE = /\.(m?[jt]sx?|cjs|json|env|vars|ya?ml|toml|jsonc|sh|md|txt)$|^\.env|^\.dev\.vars/i;

/** `*` is any text without a slash, `**` is any text, and a pattern that ends in `/` matches a folder and all that is in it. */
export function globToRegExp(pattern) {
  const folder = pattern.endsWith("/");
  const body = (folder ? pattern.slice(0, -1) : pattern)
    .split("**")
    .map((part) => part.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*"))
    .join(".*");
  return new RegExp(`^(?:.*/)?${body}${folder ? "(?:/.*)?" : ""}$`);
}

function walk(root) {
  const out = [];
  const visit = (dir) => {
    for (const name of readdirSync(dir).sort()) {
      const full = join(dir, name);
      const stat = statSync(full);
      if (stat.isDirectory()) {
        if (!SKIP_DIRS.has(name)) visit(full);
      } else if (stat.isFile()) out.push(full);
    }
  };
  visit(root);
  return out;
}

/** The names that .gitignore lists on a line of their own, with no slash and no wildcard: files that the project keeps out of its repository. */
function ignoredNames(root) {
  const file = join(root, ".gitignore");
  if (!existsSync(file)) return new Set();
  return new Set(
    readFileSync(file, "utf8")
      .split(/\r?\n/)
      .map((l) => l.trim())
      .filter((l) => l && !l.startsWith("#") && !/[*/!]/.test(l)),
  );
}

/** What is wrong in a project. Answers [{ path, line, rule, message }]. */
export function guard(root, { changed = [] } = {}) {
  const findings = [];
  const add = (path, line, rule, message) => findings.push({ path, line, rule, message });
  const ignored = ignoredNames(root);
  for (const full of walk(root)) {
    const path = relative(root, full).split(sep).join("/");
    const name = path.split("/").at(-1);
    if (SECRET_FILE.test(name) && !EXAMPLE_FILE.test(name) && !ignored.has(name)) add(path, 0, "secret-file", "this file holds secrets: keep it out of the repository (list it in .gitignore)");
    if (statSync(full).size > MAX_BYTES || !CODE.test(name)) continue;
    const lines = readFileSync(full, "utf8").split(/\r?\n/);
    const testFile = IS_TEST.test(path);
    const text = lines.join("\n");
    lines.forEach((line, i) => {
      const n = i + 1;
      if (SEED_VALUE.test(line)) add(path, n, "seed-in-file", "a seed, a secret or a key is written in this file: make a throwaway one with randomBytes(32), or read it from the environment");
      if (FLOAT_MONEY.test(line) || FLOAT_EXPONENT.test(line)) add(path, n, "float-money", "an amount made with floating point: use whole numbers of raw (BigInt)");
      if (LOG_SECRET.test(line)) add(path, n, "log-secret", "a log line names a seed, a secret or a key: never log one");
    });
    if (testFile && SENDS.test(text)) {
      const at = lines.findIndex((l) => REMOTE_NODE.test(l) && /rpc|node/i.test(l));
      if (at >= 0) add(path, at + 1, "real-money-test", "a test that can send (process or work_generate) names a node that is not on this computer: tests use a mock node");
    }
  }
  const never = [...NEVER_CHANGE];
  const extra = join(root, ".agent-never");
  if (existsSync(extra))
    never.push(
      ...readFileSync(extra, "utf8")
        .split(/\r?\n/)
        .map((l) => l.trim())
        .filter((l) => l && !l.startsWith("#")),
    );
  const patterns = never.map((p) => [p, globToRegExp(p)]);
  for (const raw of changed) {
    const path = raw.trim().replace(/^\.\//, "");
    if (!path) continue;
    const hit = patterns.find(([, re]) => re.test(path));
    if (hit) add(path, 0, "changed-path", `an agent must not change this path (it matches ${hit[0]}): the owner changes it`);
  }
  return findings;
}

function main(args) {
  const [folder, ...rest] = args;
  if (!folder || !existsSync(folder) || !statSync(folder).isDirectory()) {
    console.error("Usage: node agent-guard.mjs <project folder> [--changed <file with one path on each line>]");
    process.exit(2);
  }
  const at = rest.indexOf("--changed");
  let changed = [];
  if (at >= 0) {
    if (!rest[at + 1] || !existsSync(rest[at + 1])) {
      console.error("--changed needs a file with one path on each line.");
      process.exit(2);
    }
    changed = readFileSync(rest[at + 1], "utf8").split(/\r?\n/);
  }
  const findings = guard(folder, { changed });
  for (const f of findings) console.log(`${f.path}${f.line ? `:${f.line}` : ""}  ${f.rule}  ${f.message}`);
  console.log(findings.length ? `${findings.length} finding${findings.length === 1 ? "" : "s"}` : "no findings");
  process.exit(findings.length ? 1 : 0);
}

// Run the command line only when this file is started by itself, not when you import it.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv.slice(2));