axconfig 3.6.2 → 3.6.4

package/README.md

@@ -8,7 +8,7 @@ Different AI coding agents each have their own config formats, permission syntax
 
 axconfig solves this by providing:
 
-1. **Unified permission syntax** — One way to express permissions (`--allow read,bash:git *`) that works across all agents
+1. **Unified permission syntax** — One way to express permissions (`--allow "read,bash:git *"`) that works across all agents
 2. **Common config access** — Get and set configuration properties using a consistent API, regardless of agent
 3. **Translation to agent-specific formats** — Converts unified config into whatever format each agent expects
 4. **Capability validation** — Knows what each agent supports and warns/errors appropriately
@@ -18,6 +18,28 @@ It can be used:
 - **As a library** — integrate into your own tools and scripts
 - **As a CLI** — standalone tool for managing agent configs
 
+## Prerequisites
+
+- Node.js 22.14+
+- pnpm (install/build) or npx (run without install)
+- jq (for `--format json` examples)
+- Bash or Zsh for the examples; adjust for PowerShell/fish
+
+## Installation
+
+```bash
+# CLI (global)
+npm install -g axconfig
+# or
+pnpm add -g axconfig
+
+# Library usage (non-global)
+npm install axconfig
+
+# Run without install
+npx -y axconfig --help
+```
+
 ## Core Functionality
 
 ### Permission Parsing
@@ -30,13 +52,20 @@ read, write, bash, glob, grep, webfetch
 
 # Bash command patterns
 bash:git *
-bash:npm run build*
+bash:npm run build *
 
 # Path restrictions (agent-dependent)
 read:src/**
 write:.env
 ```
 
+Quote permission strings so your shell does not expand globs or split on spaces:
+
+```bash
+axconfig set --agent claude allow "read,glob,bash:git *"
+axconfig set --agent claude deny "bash:rm *"
+```
+
 ### Config Translation
 
 Translates unified permissions to agent-specific formats:
@@ -117,6 +146,8 @@ reader.writeRaw(configDir, "customSetting", { foo: "bar" });
 
 ## CLI Commands
 
+Output formats: `--format env` (default) or `--format json`. Examples use long flags (`--agent`, `--format`) for clarity.
+
 ### Create Config
 
 ```bash
@@ -125,13 +156,18 @@ axconfig create --agent claude --output /tmp/config \
   --allow "read,glob,bash:git *" \
   --deny "bash:rm *"
 
-# Export for shell usage
-eval $(axconfig create --agent claude --output /tmp/config --allow read)
+# Export for shell usage (trusted input only)
+tmpfile="$(mktemp "${TMPDIR:-/tmp}/axconfig.XXXXXX")"
+axconfig create --agent claude --output /tmp/config --allow read > "$tmpfile"
+. "$tmpfile"
+rm -f "$tmpfile"
 
 # Export as JSON for parsing
 axconfig create --agent claude --output /tmp/cfg --allow read --format json | jq '.env'
 ```
 
+Note: `axconfig create` outputs shell code (`export ...`) and values are not shell-escaped. Sourcing will execute `$(...)`/backticks if present, so only source trusted values; for untrusted input, prefer `--format json` and parse with `jq`.
+
 ### Get/Set Unified Settings
 
 ```bash
@@ -195,7 +231,7 @@ axconfig get --agent claude allow \
   | cut -d: -f2 | cut -d' ' -f1 | sort | uniq -c | sort -rn
 
 # Compare permissions between agents
-diff <(axconfig get -a claude allow) <(axconfig get -a gemini allow)
+diff <(axconfig get --agent claude allow) <(axconfig get --agent gemini allow)
 
 # Check if a specific permission exists
 axconfig get --agent claude allow | grep -q 'bash:git' && echo "git allowed"

package/dist/agents/claude.js

@@ -76,7 +76,7 @@ function readExistingSettings(settingsPath) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to parse existing settings at ${settingsPath}: ${message}`);
+        throw new Error(`Failed to parse existing settings at ${settingsPath}: ${message}`, { cause: error });
     }
 }
 /**

package/dist/agents/codex.js

@@ -130,7 +130,7 @@ function build(config, output) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to parse existing config at ${configPath}: ${message}`);
+            throw new Error(`Failed to parse existing config at ${configPath}: ${message}`, { cause: error });
         }
     }
     // Infer sandbox mode

package/dist/agents/gemini-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Gemini TOML rule generation helpers.
+ */
+/**
+ * Generate TOML rule for tool permissions.
+ *
+ * For allow rules that include run_shell_command, adds `allow_redirection = true`
+ * to permit heredocs, pipes, and redirects.
+ */
+export declare function generateToolRule(toolNames: string[], decision: "allow" | "deny", priority: number): string;
+/**
+ * Generate TOML rule for bash command patterns.
+ *
+ * For allow rules, includes `allow_redirection = true` to permit
+ * heredocs, pipes, and redirects. Gemini CLI normally downgrades
+ * ALLOW to ASK_USER (DENY in --yolo mode) when redirections detected.
+ */
+export declare function generateBashRule(patterns: string[], decision: "allow" | "deny", priority: number): string;

package/dist/agents/gemini-rules.js

@@ -0,0 +1,40 @@
+/**
+ * Gemini TOML rule generation helpers.
+ */
+/**
+ * Generate TOML rule for tool permissions.
+ *
+ * For allow rules that include run_shell_command, adds `allow_redirection = true`
+ * to permit heredocs, pipes, and redirects.
+ */
+export function generateToolRule(toolNames, decision, priority) {
+    if (toolNames.length === 0)
+        return "";
+    const toolNameValue = toolNames.length === 1 ? `"${toolNames[0]}"` : JSON.stringify(toolNames);
+    // Allow redirections for shell commands (heredocs, pipes, >)
+    const includesShell = toolNames.includes("run_shell_command");
+    const allowRedirection = decision === "allow" && includesShell ? "\nallow_redirection = true" : "";
+    return `[[rule]]
+toolName = ${toolNameValue}
+decision = "${decision}"
+priority = ${priority}${allowRedirection}`;
+}
+/**
+ * Generate TOML rule for bash command patterns.
+ *
+ * For allow rules, includes `allow_redirection = true` to permit
+ * heredocs, pipes, and redirects. Gemini CLI normally downgrades
+ * ALLOW to ASK_USER (DENY in --yolo mode) when redirections detected.
+ */
+export function generateBashRule(patterns, decision, priority) {
+    if (patterns.length === 0)
+        return "";
+    const prefixValue = patterns.length === 1 ? `"${patterns[0]}"` : JSON.stringify(patterns);
+    // Allow redirections (heredocs, pipes, >) for allowed commands
+    const allowRedirection = decision === "allow" ? "\nallow_redirection = true" : "";
+    return `[[rule]]
+toolName = "run_shell_command"
+commandPrefix = ${prefixValue}
+decision = "${decision}"
+priority = ${priority}${allowRedirection}`;
+}

package/dist/agents/gemini-settings.d.ts

@@ -6,3 +6,10 @@
  * Throws if file exists but contains invalid JSON to prevent data loss.
  */
 export declare function readExistingSettings(settingsPath: string): Record<string, unknown>;
+/**
+ * Build settings with /tmp workspace added.
+ *
+ * Adds /tmp to workspaces array to allow temporary file writes.
+ * Safe for CI/CD environments (ephemeral containers).
+ */
+export declare function buildSettingsWithTemporaryWorkspace(existingSettings: Record<string, unknown>): Record<string, unknown>;

package/dist/agents/gemini-settings.js

@@ -16,6 +16,25 @@ export function readExistingSettings(settingsPath) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to parse existing settings at ${settingsPath}: ${message}`);
+        throw new Error(`Failed to parse existing settings at ${settingsPath}: ${message}`, { cause: error });
     }
 }
+/**
+ * Build settings with /tmp workspace added.
+ *
+ * Adds /tmp to workspaces array to allow temporary file writes.
+ * Safe for CI/CD environments (ephemeral containers).
+ */
+export function buildSettingsWithTemporaryWorkspace(existingSettings) {
+    const existingWorkspaces = Array.isArray(existingSettings.workspaces)
+        ? existingSettings.workspaces
+        : [];
+    // Avoid duplicate /tmp entries
+    if (existingWorkspaces.includes("/tmp")) {
+        return existingSettings;
+    }
+    return {
+        ...existingSettings,
+        workspaces: [...existingWorkspaces, "/tmp"],
+    };
+}

package/dist/agents/gemini.js

@@ -14,7 +14,8 @@ import { atomicWriteFileSync } from "../atomic-write.js";
 import { registerConfigBuilder } from "../builder.js";
 // Re-export reader
 export { geminiConfigReader } from "./gemini-reader.js";
-import { readExistingSettings } from "./gemini-settings.js";
+import { generateBashRule, generateToolRule } from "./gemini-rules.js";
+import { buildSettingsWithTemporaryWorkspace, readExistingSettings, } from "./gemini-settings.js";
 /** Gemini CLI tool name mapping */
 const TOOL_MAP = {
     read: "read_file",
@@ -31,31 +32,6 @@ const CAPABILITIES = {
     pathRestrictions: false, // Gemini doesn't support path patterns
     canDenyRead: true,
 };
-/**
- * Generate TOML rule for tool permissions.
- */
-function generateToolRule(toolNames, decision, priority) {
-    if (toolNames.length === 0)
-        return "";
-    const toolNameValue = toolNames.length === 1 ? `"${toolNames[0]}"` : JSON.stringify(toolNames);
-    return `[[rule]]
-toolName = ${toolNameValue}
-decision = "${decision}"
-priority = ${priority}`;
-}
-/**
- * Generate TOML rule for bash command patterns.
- */
-function generateBashRule(patterns, decision, priority) {
-    if (patterns.length === 0)
-        return "";
-    const prefixValue = patterns.length === 1 ? `"${patterns[0]}"` : JSON.stringify(patterns);
-    return `[[rule]]
-toolName = "run_shell_command"
-commandPrefix = ${prefixValue}
-decision = "${decision}"
-priority = ${priority}`;
-}
 /**
  * Build Gemini CLI configuration.
  *
@@ -162,7 +138,8 @@ function build(config, output) {
     // Write settings.json, preserving existing settings (e.g., model)
     const settingsPath = path.join(output, "settings.json");
     const existingSettings = readExistingSettings(settingsPath);
-    atomicWriteFileSync(settingsPath, JSON.stringify(existingSettings, undefined, 2));
+    const settings = buildSettingsWithTemporaryWorkspace(existingSettings);
+    atomicWriteFileSync(settingsPath, JSON.stringify(settings, undefined, 2));
     return {
         ok: true,
         env: { GEMINI_DIR: output },

package/dist/agents/opencode.js

@@ -75,7 +75,7 @@ function build(config, output) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to parse existing config at ${configPath}: ${message}`);
+            throw new Error(`Failed to parse existing config at ${configPath}: ${message}`, { cause: error });
         }
     }
     // Write config file, preserving existing settings

package/dist/cli.js

@@ -32,8 +32,14 @@ const program = new Command()
     .helpCommand(false)
     .addHelpText("after", String.raw `
 Examples:
-  # Create config and source it in current shell
-  eval $(axconfig create --agent claude --output /tmp/cfg --allow read)
+  # Create config and source it in current shell (trusted input only; output is not shell-escaped)
+  tmpfile="$(mktemp "${"$"}{TMPDIR:-/tmp}/axconfig.XXXXXX")"
+  axconfig create --agent claude --output /tmp/cfg --allow read > "$tmpfile"
+  . "$tmpfile"
+  rm -f "$tmpfile"
+
+  # For untrusted input, use JSON output instead
+  axconfig create --agent claude --output /tmp/cfg --allow read --format json | jq '.env'
 
   # Get current settings
   axconfig get --agent claude allow

package/dist/object-path.js

@@ -49,9 +49,9 @@ function setByPath(object, keyPath, value) {
     for (let index = 0; index < keys.length - 1; index++) {
         const key = keys[index];
         if (key === undefined)
-            continue;
+            return;
         if (UNSAFE_KEYS.has(key))
-            continue;
+            return;
         if (!(key in current) ||
             typeof current[key] !== "object" ||
             current[key] === null) {

package/dist/read-write-json-config.js

@@ -22,7 +22,9 @@ function readJsonConfig(configPath) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            throw new Error(`Invalid JSON in ${configPath}: ${error.message}`);
+            throw new Error(`Invalid JSON in ${configPath}: ${error.message}`, {
+                cause: error,
+            });
         }
         throw error;
     }

package/dist/read-write-toml-config.js

@@ -23,7 +23,9 @@ function readTomlConfig(configPath) {
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Invalid TOML in ${configPath}: ${error.message}`);
+            throw new Error(`Invalid TOML in ${configPath}: ${error.message}`, {
+                cause: error,
+            });
         }
         throw error;
     }

package/package.json

@@ -2,7 +2,7 @@
   "name": "axconfig",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Unified configuration management for AI coding agents - common API for permissions, settings, and config across Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, and OpenCode",
   "repository": {
     "type": "git",
@@ -62,29 +62,29 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.28.0",
+  "packageManager": "pnpm@10.30.1",
   "engines": {
     "node": ">=22.14.0"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
     "@iarna/toml": "^2.2.5",
-    "axshared": "^4.0.0",
-    "commander": "^14.0.2"
+    "axshared": "^5.0.0",
+    "commander": "^14.0.3"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
     "@types/iarna__toml": "^2.0.5",
-    "@types/node": "^25.0.9",
-    "@vitest/coverage-v8": "^4.0.17",
-    "eslint": "^9.39.2",
-    "eslint-config-axkit": "^1.1.0",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.1",
+    "eslint-config-axkit": "^1.2.1",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.82.0",
-    "prettier": "3.8.0",
-    "semantic-release": "^25.0.2",
+    "knip": "^5.85.0",
+    "prettier": "3.8.1",
+    "semantic-release": "^25.0.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   }
 }