axconfig 3.6.3 → 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-settings.js

@@ -16,7 +16,7 @@ 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 });
     }
 }
 /**

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.3",
+  "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"
   }
 }