@fjall/eslint-plugin 21.0.0 → 21.1.0

package/index.js

@@ -31,6 +31,8 @@ import noReplacementStringExpansion from "./no-replacement-string-expansion.js";
 import noSilentResultDiscard from "./no-silent-result-discard.js";
 import noOptionalWarningEmission from "./no-optional-warning-emission.js";
 import noUnguardedChmodInTests from "./no-unguarded-chmod-in-tests.js";
+import noAdhocFjallHome from "./no-adhoc-fjall-home.js";
+import requireAgentModeDecision from "./require-agent-mode-decision.js";
 
 export default {
   rules: {
@@ -68,6 +70,8 @@ export default {
     "no-replacement-string-expansion": noReplacementStringExpansion,
     "no-silent-result-discard": noSilentResultDiscard,
     "no-optional-warning-emission": noOptionalWarningEmission,
-    "no-unguarded-chmod-in-tests": noUnguardedChmodInTests
+    "no-unguarded-chmod-in-tests": noUnguardedChmodInTests,
+    "no-adhoc-fjall-home": noAdhocFjallHome,
+    "require-agent-mode-decision": requireAgentModeDecision
   }
 };

package/no-adhoc-fjall-home.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview ESLint rule: no-adhoc-fjall-home.
+ *
+ * Fjall's per-user state root — credentials, caches, journals, logs — is
+ * `fjallHomeDir()` / `fjallStatePath(...)` from `@fjall/util`, honouring
+ * `FJALL_CONFIG_DIR`. A hand-rolled `join(homedir(), ".fjall", …)` is
+ * unreachable by that override, so a site that re-derives the path silently
+ * opts itself out of the one mechanism that lets an operator hold two
+ * organisations at once.
+ *
+ * There is no typecheck signal for this: every re-derivation is a correct
+ * `string` and agrees with the seam for the default case. It diverges only
+ * once someone sets the env var, which is exactly when they need it not to.
+ *
+ * Authored after the census that introduced the seam found ELEVEN independent
+ * derivations across four packages — `Credentials.directoryPath`, the
+ * connection / org-config / app-id caches, the agent session hooks, the CLI
+ * log dir, deploy-core's drift, forensics, remediation and cfn-registry
+ * journals, and the MCP server's credential reader. Three of them captured
+ * the path in a module-level `const`, so they could not have honoured an
+ * override even if one had existed. The MCP server and the CLI agreed about
+ * where the live production API key lives only by coincidence: two packages,
+ * same two string literals, nothing linking them.
+ *
+ * The rule flags a `join`/`resolve` call whose arguments contain a `homedir()`
+ * call and a `.fjall` string literal. It deliberately does NOT flag
+ * `homedir()` alone (`~/.aws`, `~/.npmrc` and `~/.claude` are other tools'
+ * state and correctly derived from the real home), nor a `.fjall` literal
+ * alone (project-local `.fjall/` beside a checkout is a different thing, and
+ * `configPaths.ts` owns those names).
+ */
+
+const STATE_ROOT_SEGMENT = ".fjall";
+const PATH_JOINERS = new Set(["join", "resolve"]);
+
+/** `homedir()` / `os.homedir()` — the call, however it was imported. */
+function isHomedirCall(node) {
+  if (node.type !== "CallExpression") return false;
+  const { callee } = node;
+  if (callee.type === "Identifier") return callee.name === "homedir";
+  return (
+    callee.type === "MemberExpression" &&
+    callee.property.type === "Identifier" &&
+    callee.property.name === "homedir"
+  );
+}
+
+/** A literal naming the state root, whole (".fjall") or led (".fjall/x"). */
+function isStateRootLiteral(node) {
+  if (node.type !== "Literal" || typeof node.value !== "string") return false;
+  return (
+    node.value === STATE_ROOT_SEGMENT ||
+    node.value.startsWith(`${STATE_ROOT_SEGMENT}/`)
+  );
+}
+
+/** `join(...)` / `path.join(...)` / `resolve(...)`. */
+function isPathJoiner(node) {
+  const { callee } = node;
+  if (callee.type === "Identifier") return PATH_JOINERS.has(callee.name);
+  return (
+    callee.type === "MemberExpression" &&
+    callee.property.type === "Identifier" &&
+    PATH_JOINERS.has(callee.property.name)
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noAdhocFjallHome = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Fjall's per-user state root must come from fjallHomeDir()/fjallStatePath() in @fjall/util, not a hand-rolled join(homedir(), '.fjall')."
+    },
+    messages: {
+      adhocFjallHome:
+        'Use `fjallStatePath(...)` (or `fjallHomeDir()`) from `@fjall/util` instead of joining `homedir()` with ".fjall". A hand-rolled path cannot honour `FJALL_CONFIG_DIR`, so this state stays in ~/.fjall while the rest of the CLI follows the override — which is how one organisation\'s cache ends up answering for another. For the credential file specifically, use `fjallCredentialsPath()`.'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isPathJoiner(node)) return;
+        const args = node.arguments;
+        if (!args.some(isHomedirCall)) return;
+        if (!args.some(isStateRootLiteral)) return;
+        context.report({ node, messageId: "adhocFjallHome" });
+      }
+    };
+  }
+};
+
+export default noAdhocFjallHome;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/eslint-plugin",
-  "version": "21.0.0",
+  "version": "21.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",

package/require-agent-mode-decision.js

@@ -0,0 +1,131 @@
+/**
+ * ESLint Rule: require-agent-mode-decision
+ *
+ * A command handler that writes MACHINE-READABLE output to stdout must decide,
+ * in code, what agent mode means for it.
+ *
+ * `fjall apps detect` shipped writing `process.stdout.write(JSON.stringify(...))`
+ * and never once consulting `isAgentMode`. It registered the agent flag set, so
+ * `--agent` was accepted; it had no lane, so `--agent` did nothing. Every
+ * structural check in the estate stayed green, because all of them were
+ * DECLARATION checks — the command was declared, and no test asked whether the
+ * declaration was honoured. An agent following the shipped skill hit raw JSON
+ * at the first mandatory step of the app-creation recipe.
+ *
+ * The rule is deliberately not "never write JSON to stdout": the `--output json`
+ * lane is a real contract that the MCP server depends on. What it requires is
+ * that a file emitting structured stdout ALSO references `isAgentMode`, i.e.
+ * that the author made the call rather than never facing it. A genuinely
+ * human-only handler declares itself with a disable comment naming its
+ * `HUMAN_ONLY_LEAVES` entry, which turns an invisible omission into a
+ * reviewable claim.
+ *
+ * Flags:
+ * - `process.stdout.write(...)` containing a `JSON.stringify(...)` call, in a
+ *   file under `src/commands/` that never references `isAgentMode`.
+ *
+ * Allowed:
+ * - the same write in a file that consults `isAgentMode` anywhere;
+ * - human text (`process.stdout.write("...")`) — no structured payload;
+ * - anything outside `src/commands/` (services and renderers are not the
+ *   surface where the mode decision belongs).
+ */
+
+const COMMANDS_PATH_FRAGMENT = "src/commands/";
+const AGENT_MODE_IDENTIFIER = "isAgentMode";
+
+function isProcessStdoutWrite(node) {
+  const callee = node.callee;
+  if (callee === undefined || callee.type !== "MemberExpression") return false;
+  if (
+    callee.property.type !== "Identifier" ||
+    callee.property.name !== "write"
+  ) {
+    return false;
+  }
+  const target = callee.object;
+  return (
+    target.type === "MemberExpression" &&
+    target.object.type === "Identifier" &&
+    target.object.name === "process" &&
+    target.property.type === "Identifier" &&
+    target.property.name === "stdout"
+  );
+}
+
+function isJsonStringifyCall(node) {
+  return (
+    node.type === "CallExpression" &&
+    node.callee.type === "MemberExpression" &&
+    node.callee.object.type === "Identifier" &&
+    node.callee.object.name === "JSON" &&
+    node.callee.property.type === "Identifier" &&
+    node.callee.property.name === "stringify"
+  );
+}
+
+/** Walk an expression tree looking for a JSON.stringify call. */
+function containsJsonStringify(node, depth = 0) {
+  if (node === undefined || node === null || typeof node !== "object") {
+    return false;
+  }
+  // Template literals and concatenations nest, but not deeply in practice.
+  if (depth > 12) return false;
+  if (isJsonStringifyCall(node)) return true;
+  for (const key of Object.keys(node)) {
+    if (key === "parent" || key === "loc" || key === "range") continue;
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (containsJsonStringify(item, depth + 1)) return true;
+      }
+    } else if (value !== null && typeof value === "object" && value.type) {
+      if (containsJsonStringify(value, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Command handlers that write structured stdout must consult isAgentMode, so an agent surface cannot be declared and then silently ignored",
+      category: "Best Practices",
+      recommended: false
+    },
+    messages: {
+      undeclaredJsonStdout:
+        "This handler writes JSON to stdout but never consults `isAgentMode`, so `--agent` would be accepted and ignored (the `apps detect` defect). Add an agent lane, or disable this rule with a comment naming the command's HUMAN_ONLY_LEAVES entry."
+    },
+    schema: []
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    if (!filename.includes(COMMANDS_PATH_FRAGMENT)) return {};
+
+    let referencesAgentMode = false;
+    const offenders = [];
+
+    return {
+      Identifier(node) {
+        if (node.name === AGENT_MODE_IDENTIFIER) referencesAgentMode = true;
+      },
+      CallExpression(node) {
+        if (!isProcessStdoutWrite(node)) return;
+        if (node.arguments.some((arg) => containsJsonStringify(arg))) {
+          offenders.push(node);
+        }
+      },
+      "Program:exit"() {
+        if (referencesAgentMode) return;
+        for (const node of offenders) {
+          context.report({ node, messageId: "undeclaredJsonStdout" });
+        }
+      }
+    };
+  }
+};