@terminus-ai/cli 0.0.1

package/bin/devlint.mjs

@@ -0,0 +1,112 @@
+/**
+ * Prod-compat lint for local agent dev.
+ *
+ * Local exec is native (real /bin/sh, real python) — a capability SUPERSET
+ * of the hosted isolate (just-bash's ~80 coreutils; stdlib-only
+ * CPython/WASM). These heuristics warn, never block, when a program leans
+ * on something the hosted tier lacks, so the authoring-time mistakes ("use
+ * git…", `import pandas`) surface before publish instead of after. The
+ * guarantee remains `terminus dev --remote`, which runs the real isolate.
+ *
+ * The manifests (bin/lint-manifests/) are read off the engines the platform
+ * runs: just-bash's getCommandNames() and its CPython's
+ * sys.stdlib_module_names, at the just-bash version terminus-backend's bashd
+ * pins. Each file's `source` names that version; regenerate both from the
+ * new version when the pin moves.
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const manifestDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "lint-manifests");
+
+function loadManifest(name, key) {
+  try {
+    return new Set(JSON.parse(readFileSync(path.join(manifestDir, name), "utf8"))[key]);
+  } catch {
+    return null;
+  }
+}
+
+const JUSTBASH_COMMANDS = loadManifest("justbash-commands.json", "commands");
+const PYTHON_STDLIB = loadManifest("python-stdlib.json", "modules");
+
+/**
+ * Drop heredoc bodies before tokenizing: everything between `<<WORD` (or
+ * `<<-WORD` / quoted variants) and the terminator line is data, not
+ * commands. Without this, a `cat > file <<EOF` report body lints every
+ * markdown line as an unknown command.
+ */
+export function stripHeredocBodies(command) {
+  const lines = command.split("\n");
+  const kept = [];
+  let terminator = null;
+  for (const line of lines) {
+    if (terminator !== null) {
+      if (line.trim() === terminator) terminator = null;
+      continue;
+    }
+    const heredoc = /<<-?\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(line);
+    if (heredoc) terminator = heredoc[1] ?? heredoc[2] ?? heredoc[3];
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+/** Shell syntax words and builtins the tokenizer must not flag. */
+const SHELL_BUILTINS = new Set([
+  "cd", "export", "set", "unset", "exit", "return", "true", ":", "[", "[[",
+  "test", "read", "wait", "shift", "local", "source", ".", "eval", "exec",
+  "if", "then", "else", "elif", "fi", "for", "while", "until", "do", "done",
+  "case", "esac", "function", "{", "}", "!", "in", "time", "trap", "printf",
+  "pwd", "type", "command", "kill", "sleep",
+]);
+
+/**
+ * Best-effort first-word extraction across pipeline/list segments. Dynamic
+ * commands, substitutions, and quoting escape this on purpose — the lint is
+ * a hint, not a gate.
+ */
+export function lintBashCommand(command) {
+  if (!JUSTBASH_COMMANDS || typeof command !== "string") return [];
+  const warnings = new Set();
+  const segments = stripHeredocBodies(command)
+    .replace(/\$\([^)]*\)/g, " ")
+    .split(/\||&&|\|\||;|\n|`/);
+  for (const segment of segments) {
+    let words = segment.trim().split(/\s+/).filter(Boolean);
+    // Skip leading VAR=value assignments and redirections.
+    while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || /^[<>&\d]/.test(words[0]))) {
+      words = words.slice(1);
+    }
+    const word = words[0];
+    if (!word) continue;
+    if (word.startsWith("$") || word.startsWith('"') || word.startsWith("'")) continue;
+    if (word.includes("/")) continue; // explicit paths fail loudly on their own
+    const name = word.replace(/^\\/, "");
+    if (SHELL_BUILTINS.has(name) || JUSTBASH_COMMANDS.has(name)) continue;
+    warnings.add(
+      `[prod-compat] '${name}' is not available in the hosted shell tier (just-bash coreutils only)`,
+    );
+  }
+  return [...warnings];
+}
+
+/** Warn on imports outside the CPython stdlib the hosted WASM tier serves. */
+export function lintPythonImports(code) {
+  if (!PYTHON_STDLIB || typeof code !== "string") return [];
+  const warnings = new Set();
+  for (const line of code.split("\n")) {
+    const match = /^\s*(?:import|from)\s+([A-Za-z_][A-Za-z0-9_.]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_.]*)*)/.exec(line);
+    if (!match) continue;
+    for (const raw of match[1].split(",")) {
+      const root = raw.trim().split(".")[0];
+      if (!root || PYTHON_STDLIB.has(root)) continue;
+      warnings.add(
+        `[prod-compat] python module '${root}' is outside the stdlib — the hosted tier has no pip packages`,
+      );
+    }
+  }
+  return [...warnings];
+}