@kelceyp/caw-server 1.0.286 → 1.0.289

package/dist/claude-config-dir-guard.mjs

@@ -0,0 +1,105 @@
+/**
+ * CLAUDE_CONFIG_DIR refusal guard (story As1065).
+ *
+ * Claude Code does no shell expansion on `CLAUDE_CONFIG_DIR`. Some values
+ * therefore name an unintended directory: the vendor builds a fresh config
+ * tree there (`.claude.json`, `projects/`, `sessions/`, `backups/`), usually
+ * inside the job's working directory, and quietly stops using the real one
+ * (upstream #78988). Probe evidence, Claude Code 2.1.281 (2026-09-25):
+ * `~/x`, `$HOME/x` and `rel-cfg` land under the cwd; `/abs/$USER/cfg` creates
+ * a literal `$USER` directory; `/abs/x/~/y` creates a literal `~` directory;
+ * an empty value makes the cwd itself the config dir.
+ *
+ * This module refuses such a value; it never repairs, expands or rewrites
+ * it. The predicate (ratified 2026-09-25, As1065 scope AC 1):
+ *   - `undefined` is absent: nothing happens.
+ *   - any other non-string (including `null`) throws `TypeError`; env values
+ *     are always `string | undefined`, so this is a programming error.
+ *   - a string is checked against `CLAUDE_CONFIG_DIR_REFUSAL_RULES` in order
+ *     EMPTY, NOT_ABSOLUTE, CONTAINS_DOLLAR, TILDE_SEGMENT; the first match is
+ *     reported. "Absolute" is Node's `path.isAbsolute`, as in
+ *     `pty-non-interactive-setup.mjs`. A `~` counts only at the start of a
+ *     `/`-separated segment, so `/a/b~c` passes.
+ *
+ * Dependency-free by design: the only import is the `path` builtin, there is
+ * no logger (an absent variable must produce no new log line) and nothing
+ * runs at load. `shared/` is not published from `server/dist/`, so this
+ * module carries its own copy of the prefix literal.
+ *
+ * `CLAUDE_CONFIG_DIR_REFUSED_PREFIX` is literal copy 2 of 2; copy 1 is
+ * `CLAUDE_CONFIG_DIR_REFUSED_PREFIX` in `shared/jobErrorPrefixes.js`. The
+ * prefix-drift block of
+ * `server/test/unit/core/agents/claude-config-dir-guard.test.js` asserts the
+ * two are equal.
+ */
+
+import { isAbsolute } from 'path';
+
+export const CLAUDE_CONFIG_DIR_REFUSED_PREFIX = 'CLAUDE_CONFIG_DIR_REFUSED';
+
+export const CLAUDE_CONFIG_DIR_REFUSAL_RULES = Object.freeze({
+    EMPTY: 'EMPTY',
+    NOT_ABSOLUTE: 'NOT_ABSOLUTE',
+    CONTAINS_DOLLAR: 'CONTAINS_DOLLAR',
+    TILDE_SEGMENT: 'TILDE_SEGMENT'
+});
+
+// Per-rule `<rule reason>` and `<rule consequence>` of the message contract.
+const RULE_TEXT = Object.freeze({
+    EMPTY: Object.freeze({
+        reason: 'is set but empty',
+        consequence: "use the job's working directory itself as its config directory"
+    }),
+    NOT_ABSOLUTE: Object.freeze({
+        reason: 'is not an absolute path',
+        consequence: "create a new config tree relative to the job's working directory"
+    }),
+    CONTAINS_DOLLAR: Object.freeze({
+        reason: 'contains "$"',
+        consequence: 'create a directory with a literal "$" in its name'
+    }),
+    TILDE_SEGMENT: Object.freeze({
+        reason: 'has a path segment starting with "~"',
+        consequence: 'create a directory whose name starts with a literal "~"'
+    })
+});
+
+/**
+ * Classify a `CLAUDE_CONFIG_DIR` value.
+ *
+ * @param {string|undefined} value
+ * @returns {string|null} the first matching rule code, or `null` when the
+ *   value is absent or passes
+ * @throws {TypeError} if `value` is neither a string nor `undefined`
+ */
+export const classifyClaudeConfigDir = (value) => {
+    if (value === undefined) return null;
+    if (typeof value !== 'string') {
+        throw new TypeError(`CLAUDE_CONFIG_DIR must be a string or undefined (got ${value === null ? 'null' : typeof value})`);
+    }
+    if (value === '') return CLAUDE_CONFIG_DIR_REFUSAL_RULES.EMPTY;
+    if (!isAbsolute(value)) return CLAUDE_CONFIG_DIR_REFUSAL_RULES.NOT_ABSOLUTE;
+    if (value.includes('$')) return CLAUDE_CONFIG_DIR_REFUSAL_RULES.CONTAINS_DOLLAR;
+    if (value.split('/').some((segment) => segment.startsWith('~'))) return CLAUDE_CONFIG_DIR_REFUSAL_RULES.TILDE_SEGMENT;
+    return null;
+};
+
+/**
+ * Throw if a `CLAUDE_CONFIG_DIR` value must not be forwarded to Claude Code.
+ * The refusal is a plain `Error`; its message prefix is the contract.
+ *
+ * @param {string|undefined} value
+ * @throws {Error} `CLAUDE_CONFIG_DIR_REFUSED (<RULE>): ...` for a refused value
+ * @throws {TypeError} if `value` is neither a string nor `undefined`
+ */
+export const assertClaudeConfigDirForwardable = (value) => {
+    const rule = classifyClaudeConfigDir(value);
+    if (rule === null) return;
+    const { reason, consequence } = RULE_TEXT[rule];
+    throw new Error(
+        `${CLAUDE_CONFIG_DIR_REFUSED_PREFIX} (${rule}): CLAUDE_CONFIG_DIR is ${JSON.stringify(value)}, which ${reason}. ` +
+        `Claude Code does not expand "~" or "$VARIABLES" in this value, so it would ${consequence} and stop using your real config directory (upstream #78988). ` +
+        'Fix: unset CLAUDE_CONFIG_DIR, or set it to an absolute path with no "$" and no path segment starting with "~", ' +
+        "in the environment that launches Claude Code (for direct jobs, the CAW server's environment - restart the server after changing it). Then retry."
+    );
+};