axconfig 1.0.0

package/dist/commands/create.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Create command - generates agent-specific configuration.
+ */
+interface CreateOptions {
+    agent: string;
+    output: string;
+    allow?: string;
+    deny?: string;
+    format: string;
+    withCredentials?: string;
+}
+/** Handle create command */
+declare function handleCreate(options: CreateOptions): Promise<void>;
+export { handleCreate };

package/dist/commands/create.js

@@ -0,0 +1,101 @@
+/**
+ * Create command - generates agent-specific configuration.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import promptPassword from "@inquirer/password";
+import { credentialsToEnvironment } from "../auth/get-access-token.js";
+import { buildAgentConfig, formatPermissionErrors, formatPermissionWarnings, } from "../build-agent-config.js";
+import { fromBase64, tryDecrypt } from "../crypto.js";
+import { AGENT_IDS } from "../types.js";
+/** Handle create command */
+async function handleCreate(options) {
+    const { agent } = options;
+    // Validate agent
+    if (!AGENT_IDS.includes(agent)) {
+        console.error(`Error: Unknown agent '${agent}'`);
+        console.error(`Supported agents: ${AGENT_IDS.join(", ")}`);
+        process.exitCode = 2;
+        return;
+    }
+    // Handle credentials file
+    let credentialEnvironment = {};
+    if (options.withCredentials) {
+        const result = await loadCredentials(options.withCredentials, agent);
+        if (!result.ok) {
+            process.exitCode = result.exitCode;
+            return;
+        }
+        credentialEnvironment = result.environment;
+    }
+    const result = buildAgentConfig({
+        agentId: agent,
+        allow: options.allow,
+        deny: options.deny,
+        output: options.output,
+    });
+    if (!result.ok) {
+        if ("errors" in result) {
+            console.error(formatPermissionErrors(result.errors));
+        }
+        else {
+            console.error(`Error: ${result.message}`);
+        }
+        process.exitCode = result.exitCode;
+        return;
+    }
+    // Merge credential env vars with config env vars
+    const environment = { ...credentialEnvironment, ...result.env };
+    // Show warnings
+    if (result.warnings.length > 0) {
+        console.error(formatPermissionWarnings(result.warnings));
+    }
+    // Output based on format
+    if (options.format === "json") {
+        console.log(JSON.stringify({ env: environment }, undefined, 2));
+    }
+    else {
+        // env format (default)
+        for (const [key, value] of Object.entries(environment)) {
+            console.log(`export ${key}="${value}"`);
+        }
+    }
+}
+/** Load and decrypt credentials file */
+async function loadCredentials(filePath, expectedAgent) {
+    if (!existsSync(filePath)) {
+        console.error(`Error: Credentials file not found: ${filePath}`);
+        return { ok: false, exitCode: 1 };
+    }
+    try {
+        const fileContent = JSON.parse(readFileSync(filePath, "utf8"));
+        // Verify agent matches
+        if (fileContent.agent !== expectedAgent) {
+            console.error(`Error: Credentials file is for '${fileContent.agent}', not '${expectedAgent}'`);
+            return { ok: false, exitCode: 1 };
+        }
+        // Decrypt credentials (tries default password first)
+        const decrypted = await tryDecrypt(fromBase64(fileContent), () => promptPassword({ message: "Decryption password" }));
+        const creds = JSON.parse(decrypted);
+        // Convert credentials to env vars
+        const environment = credentialsToEnvironment(creds);
+        // Warn if credentials couldn't be converted to env vars
+        if (Object.keys(environment).length === 0) {
+            const warnings = {
+                codex: "Codex OAuth tokens require auth.json; use API key instead",
+                gemini: "Gemini OAuth requires oauth_creds.json; use API key instead",
+                opencode: "OpenCode credentials require auth.json file",
+            };
+            const warning = warnings[creds.agent];
+            if (warning) {
+                console.error(`Warning: ${warning}`);
+            }
+        }
+        return { ok: true, environment };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: Failed to decrypt credentials: ${message}`);
+        return { ok: false, exitCode: 1 };
+    }
+}
+export { handleCreate };

package/dist/crypto.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Encryption utilities for credential export/import.
+ *
+ * Uses AES-256-GCM with PBKDF2 key derivation.
+ */
+/**
+ * Derive default password from predictable seed.
+ * Provides obfuscation, not security - attacker would need to understand derivation logic.
+ */
+declare const DEFAULT_PASSWORD: string;
+/** Encrypted data structure */
+interface EncryptedData {
+    ciphertext: Buffer;
+    salt: Buffer;
+    iv: Buffer;
+    tag: Buffer;
+}
+/** Serialized encrypted file format */
+interface EncryptedFile {
+    version: 1;
+    agent: string;
+    ciphertext: string;
+    salt: string;
+    iv: string;
+    tag: string;
+}
+/** Encrypt data with password */
+declare function encrypt(data: string, password: string): EncryptedData;
+/** Convert encrypted data to base64 for JSON serialization */
+declare function toBase64(encrypted: EncryptedData): Omit<EncryptedFile, "version" | "agent">;
+/** Convert base64 strings back to buffers */
+declare function fromBase64(file: Omit<EncryptedFile, "version" | "agent">): EncryptedData;
+/**
+ * Try decrypting with default password first, then prompt for custom.
+ * Returns decrypted string on success.
+ */
+declare function tryDecrypt(encrypted: EncryptedData, promptFunction: () => Promise<string>): Promise<string>;
+export { DEFAULT_PASSWORD, encrypt, fromBase64, toBase64, tryDecrypt };
+export type { EncryptedFile };

package/dist/crypto.js

@@ -0,0 +1,78 @@
+/**
+ * Encryption utilities for credential export/import.
+ *
+ * Uses AES-256-GCM with PBKDF2 key derivation.
+ */
+import { createCipheriv, createDecipheriv, createHash, pbkdf2Sync, randomBytes, } from "node:crypto";
+const ALGORITHM = "aes-256-gcm";
+const ITERATIONS = 100_000;
+const KEY_LENGTH = 32;
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+/**
+ * Derive default password from predictable seed.
+ * Provides obfuscation, not security - attacker would need to understand derivation logic.
+ */
+const DEFAULT_PASSWORD = createHash("sha256")
+    .update(["axconfig", "credentials", "default", "v1"].join("."))
+    .digest("base64")
+    .slice(0, 32);
+/** Encrypt data with password */
+function encrypt(data, password) {
+    const salt = randomBytes(SALT_LENGTH);
+    const key = pbkdf2Sync(password, salt, ITERATIONS, KEY_LENGTH, "sha256");
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv, {
+        authTagLength: TAG_LENGTH,
+    });
+    const ciphertext = Buffer.concat([
+        cipher.update(data, "utf8"),
+        cipher.final(),
+    ]);
+    return { ciphertext, salt, iv, tag: cipher.getAuthTag() };
+}
+/** Decrypt data with password. Throws on wrong password. */
+function decrypt(encrypted, password) {
+    const key = pbkdf2Sync(password, encrypted.salt, ITERATIONS, KEY_LENGTH, "sha256");
+    const decipher = createDecipheriv(ALGORITHM, key, encrypted.iv, {
+        authTagLength: TAG_LENGTH,
+    });
+    decipher.setAuthTag(encrypted.tag);
+    return (decipher.update(encrypted.ciphertext).toString("utf8") +
+        decipher.final("utf8"));
+}
+/** Convert encrypted data to base64 for JSON serialization */
+function toBase64(encrypted) {
+    return {
+        ciphertext: encrypted.ciphertext.toString("base64"),
+        salt: encrypted.salt.toString("base64"),
+        iv: encrypted.iv.toString("base64"),
+        tag: encrypted.tag.toString("base64"),
+    };
+}
+/** Convert base64 strings back to buffers */
+function fromBase64(file) {
+    return {
+        ciphertext: Buffer.from(file.ciphertext, "base64"),
+        salt: Buffer.from(file.salt, "base64"),
+        iv: Buffer.from(file.iv, "base64"),
+        tag: Buffer.from(file.tag, "base64"),
+    };
+}
+/**
+ * Try decrypting with default password first, then prompt for custom.
+ * Returns decrypted string on success.
+ */
+async function tryDecrypt(encrypted, promptFunction) {
+    // Try default password first
+    try {
+        return decrypt(encrypted, DEFAULT_PASSWORD);
+    }
+    catch {
+        // Default password failed, prompt user
+        const password = await promptFunction();
+        return decrypt(encrypted, password);
+    }
+}
+export { DEFAULT_PASSWORD, encrypt, fromBase64, toBase64, tryDecrypt };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * axconfig - Configuration management library for AI coding agents.
+ *
+ * @example
+ * // Build agent-specific config
+ * import { buildAgentConfig } from "axconfig";
+ *
+ * const result = buildAgentConfig({
+ *   agentId: "claude-code",
+ *   allow: "read,glob",
+ *   deny: "bash:rm *",
+ *   output: "/tmp/axconfig",
+ * });
+ *
+ * if (result.ok) {
+ *   // Use result.env for agent environment
+ * }
+ *
+ * @example
+ * // Get access token for an agent
+ * import { getAgentAccessToken, checkAuth } from "axconfig";
+ *
+ * const token = getAgentAccessToken("claude-code");
+ * if (token) {
+ *   // Use token for API calls
+ * }
+ *
+ * // Or check auth status first
+ * const status = checkAuth("claude-code");
+ * if (status.authenticated) {
+ *   console.log(`Authenticated via ${status.method}`);
+ * }
+ */
+export type { AgentCapabilities, AgentId, AxrunConfig, BuildResult, CanonicalTool, ConfigBuilder, PermissionConfig, PermissionIssue, PermissionRule, } from "./types.js";
+export { AGENT_IDS } from "./types.js";
+export type { AuthStatus } from "./auth/check-auth.js";
+export { checkAuth, checkAllAuth } from "./auth/check-auth.js";
+export type { Credentials } from "./auth/extract-credentials.js";
+export { extractCredentials } from "./auth/extract-credentials.js";
+export { credentialsToEnvironment, getAccessToken, getAgentAccessToken, } from "./auth/get-access-token.js";
+export { formatRule, parsePermissions, parseRule, parseRuleList, } from "./parse-permissions.js";
+export { getConfigBuilder, registerConfigBuilder } from "./builder.js";
+export { buildAgentConfig, formatPermissionErrors, formatPermissionWarnings, } from "./build-agent-config.js";
+import "./agents/claude-code.js";
+import "./agents/codex.js";
+import "./agents/gemini.js";
+import "./agents/opencode.js";
+export { claudeCodeConfigBuilder } from "./agents/claude-code.js";
+export { codexConfigBuilder } from "./agents/codex.js";
+export { geminiConfigBuilder } from "./agents/gemini.js";
+export { openCodeConfigBuilder } from "./agents/opencode.js";

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * axconfig - Configuration management library for AI coding agents.
+ *
+ * @example
+ * // Build agent-specific config
+ * import { buildAgentConfig } from "axconfig";
+ *
+ * const result = buildAgentConfig({
+ *   agentId: "claude-code",
+ *   allow: "read,glob",
+ *   deny: "bash:rm *",
+ *   output: "/tmp/axconfig",
+ * });
+ *
+ * if (result.ok) {
+ *   // Use result.env for agent environment
+ * }
+ *
+ * @example
+ * // Get access token for an agent
+ * import { getAgentAccessToken, checkAuth } from "axconfig";
+ *
+ * const token = getAgentAccessToken("claude-code");
+ * if (token) {
+ *   // Use token for API calls
+ * }
+ *
+ * // Or check auth status first
+ * const status = checkAuth("claude-code");
+ * if (status.authenticated) {
+ *   console.log(`Authenticated via ${status.method}`);
+ * }
+ */
+export { AGENT_IDS } from "./types.js";
+export { checkAuth, checkAllAuth } from "./auth/check-auth.js";
+export { extractCredentials } from "./auth/extract-credentials.js";
+export { credentialsToEnvironment, getAccessToken, getAgentAccessToken, } from "./auth/get-access-token.js";
+// Permission parsing
+export { formatRule, parsePermissions, parseRule, parseRuleList, } from "./parse-permissions.js";
+// Config builder registry
+export { getConfigBuilder, registerConfigBuilder } from "./builder.js";
+// High-level API
+export { buildAgentConfig, formatPermissionErrors, formatPermissionWarnings, } from "./build-agent-config.js";
+// Import agent modules to trigger self-registration
+import "./agents/claude-code.js";
+import "./agents/codex.js";
+import "./agents/gemini.js";
+import "./agents/opencode.js";
+// Export agent builders for direct access
+export { claudeCodeConfigBuilder } from "./agents/claude-code.js";
+export { codexConfigBuilder } from "./agents/codex.js";
+export { geminiConfigBuilder } from "./agents/gemini.js";
+export { openCodeConfigBuilder } from "./agents/opencode.js";

package/dist/parse-permissions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Permission syntax parser.
+ *
+ * Parses --allow and --deny CLI arguments into PermissionConfig.
+ *
+ * @example
+ * parsePermissions(
+ *   ["read,glob,bash:git *"],
+ *   ["bash:rm *"]
+ * )
+ * // Returns:
+ * // {
+ * //   allow: [
+ * //     { type: "tool", name: "read" },
+ * //     { type: "tool", name: "glob" },
+ * //     { type: "bash", pattern: "git *" }
+ * //   ],
+ * //   deny: [
+ * //     { type: "bash", pattern: "rm *" }
+ * //   ]
+ * // }
+ */
+import type { PermissionConfig, PermissionRule } from "./types.js";
+/**
+ * Parse a single permission rule string.
+ *
+ * Supported formats:
+ * - "read" → { type: "tool", name: "read" }
+ * - "bash:git *" → { type: "bash", pattern: "git *" }
+ * - "read:src/**" → { type: "path", tool: "read", pattern: "src/**" }
+ */
+declare function parseRule(rule: string): PermissionRule;
+/**
+ * Parse a comma-separated list of permission rules.
+ */
+declare function parseRuleList(input: string): PermissionRule[];
+/**
+ * Parse --allow and --deny arguments into PermissionConfig.
+ *
+ * @param allow - Array of comma-separated allow rules
+ * @param deny - Array of comma-separated deny rules
+ * @returns Parsed permission configuration
+ * @throws Error if any rule is invalid
+ */
+declare function parsePermissions(allow?: string[], deny?: string[]): PermissionConfig;
+/**
+ * Format a permission rule for display.
+ */
+declare function formatRule(rule: PermissionRule): string;
+export { formatRule, parsePermissions, parseRule, parseRuleList };

package/dist/parse-permissions.js

@@ -0,0 +1,125 @@
+/**
+ * Permission syntax parser.
+ *
+ * Parses --allow and --deny CLI arguments into PermissionConfig.
+ *
+ * @example
+ * parsePermissions(
+ *   ["read,glob,bash:git *"],
+ *   ["bash:rm *"]
+ * )
+ * // Returns:
+ * // {
+ * //   allow: [
+ * //     { type: "tool", name: "read" },
+ * //     { type: "tool", name: "glob" },
+ * //     { type: "bash", pattern: "git *" }
+ * //   ],
+ * //   deny: [
+ * //     { type: "bash", pattern: "rm *" }
+ * //   ]
+ * // }
+ */
+/** Valid canonical tool names */
+const CANONICAL_TOOLS = new Set([
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "glob",
+    "grep",
+    "web",
+]);
+/** Tools that support path restrictions */
+const PATH_TOOLS = new Set(["read", "write", "edit"]);
+/**
+ * Parse a single permission rule string.
+ *
+ * Supported formats:
+ * - "read" → { type: "tool", name: "read" }
+ * - "bash:git *" → { type: "bash", pattern: "git *" }
+ * - "read:src/**" → { type: "path", tool: "read", pattern: "src/**" }
+ */
+function parseRule(rule) {
+    const trimmed = rule.trim();
+    if (trimmed === "") {
+        throw new Error("Empty permission rule");
+    }
+    // Check for bash pattern: "bash:git *"
+    if (trimmed.startsWith("bash:")) {
+        const pattern = trimmed.slice(5);
+        if (pattern === "") {
+            throw new Error('Invalid bash pattern: "bash:" requires a command pattern');
+        }
+        return { type: "bash", pattern };
+    }
+    // Check for path restriction: "read:src/**"
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex > 0) {
+        const tool = trimmed.slice(0, colonIndex);
+        const pattern = trimmed.slice(colonIndex + 1);
+        if (PATH_TOOLS.has(tool)) {
+            if (pattern === "") {
+                throw new Error(`Invalid path pattern: "${tool}:" requires a path pattern`);
+            }
+            return {
+                type: "path",
+                tool: tool,
+                pattern,
+            };
+        }
+        // Unknown tool with colon - might be a typo
+        if (!CANONICAL_TOOLS.has(tool)) {
+            throw new Error(`Unknown tool "${tool}" in "${trimmed}". ` +
+                `Valid tools: ${[...CANONICAL_TOOLS].join(", ")}`);
+        }
+        // Tool doesn't support path restrictions
+        throw new Error(`Tool "${tool}" does not support path restrictions. ` +
+            `Only ${[...PATH_TOOLS].join(", ")} support patterns like "${tool}:path/**"`);
+    }
+    // Simple tool name: "read", "glob", etc.
+    if (!CANONICAL_TOOLS.has(trimmed)) {
+        throw new Error(`Unknown tool "${trimmed}". Valid tools: ${[...CANONICAL_TOOLS].join(", ")}`);
+    }
+    return { type: "tool", name: trimmed };
+}
+/**
+ * Parse a comma-separated list of permission rules.
+ */
+function parseRuleList(input) {
+    if (input.trim() === "") {
+        return [];
+    }
+    return input.split(",").map((part) => parseRule(part));
+}
+/**
+ * Parse --allow and --deny arguments into PermissionConfig.
+ *
+ * @param allow - Array of comma-separated allow rules
+ * @param deny - Array of comma-separated deny rules
+ * @returns Parsed permission configuration
+ * @throws Error if any rule is invalid
+ */
+function parsePermissions(allow = [], deny = []) {
+    return {
+        allow: allow.flatMap((input) => parseRuleList(input)),
+        deny: deny.flatMap((input) => parseRuleList(input)),
+    };
+}
+/**
+ * Format a permission rule for display.
+ */
+function formatRule(rule) {
+    switch (rule.type) {
+        case "tool": {
+            return rule.name;
+        }
+        case "bash": {
+            return `bash:${rule.pattern}`;
+        }
+        case "path": {
+            return `${rule.tool}:${rule.pattern}`;
+        }
+    }
+}
+export { formatRule, parsePermissions, parseRule, parseRuleList };

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Core types for axconfig.
+ *
+ * Defines the unified permission model and config builder interfaces.
+ */
+/** Supported agent identifiers */
+declare const AGENT_IDS: readonly ["claude-code", "codex", "gemini", "opencode"];
+type AgentId = (typeof AGENT_IDS)[number];
+/** Canonical tool names used in axrun permissions */
+type CanonicalTool = "read" | "write" | "edit" | "bash" | "glob" | "grep" | "web";
+/** Tools that support path restrictions */
+type PathRestrictedTool = "read" | "write" | "edit";
+/** Permission rule for a tool (e.g., "read", "bash") */
+interface ToolPermissionRule {
+    type: "tool";
+    name: CanonicalTool;
+}
+/** Permission rule for a bash command pattern (e.g., "git *") */
+interface BashPatternRule {
+    type: "bash";
+    pattern: string;
+}
+/** Permission rule for a path pattern (e.g., "src/**") */
+interface PathPatternRule {
+    type: "path";
+    tool: PathRestrictedTool;
+    pattern: string;
+}
+/** Union of all permission rule types */
+type PermissionRule = ToolPermissionRule | BashPatternRule | PathPatternRule;
+/** Parsed permission configuration */
+interface PermissionConfig {
+    allow: PermissionRule[];
+    deny: PermissionRule[];
+}
+/** Full axrun configuration */
+interface AxrunConfig {
+    permissions?: PermissionConfig;
+}
+/** Describes what permission features an agent supports */
+interface AgentCapabilities {
+    /** Whether the agent supports per-tool permissions (read, write, etc.) */
+    toolPermissions: boolean;
+    /** Whether the agent supports bash command patterns */
+    bashPatterns: boolean;
+    /** Whether the agent supports path restrictions (read:src/**) */
+    pathRestrictions: boolean;
+    /** Whether the agent can deny read access (some use sandboxes that always allow reads) */
+    canDenyRead: boolean;
+}
+/** Issue with a permission rule (warning or error) */
+interface PermissionIssue {
+    rule: PermissionRule;
+    reason: string;
+    suggestions: string[];
+}
+/** Successful build result */
+interface BuildSuccess {
+    ok: true;
+    /** Environment variables to pass to the agent */
+    env: Record<string, string>;
+    /** CLI arguments to pass to the agent */
+    args?: string[];
+    /** Warnings about dropped rules (for --allow) */
+    warnings: PermissionIssue[];
+}
+/** Failed build result */
+interface BuildFailure {
+    ok: false;
+    /** Errors that prevent running (for --deny) */
+    errors: PermissionIssue[];
+}
+/** Result of building agent-specific config */
+type BuildResult = BuildSuccess | BuildFailure;
+/** Interface for agent-specific config builders */
+interface ConfigBuilder {
+    /** Agent this builder is for */
+    agentId: AgentId;
+    /** What this agent supports */
+    capabilities: AgentCapabilities;
+    /** Build agent-specific config from axrun config */
+    build: (config: AxrunConfig, output: string) => BuildResult;
+}
+export { AGENT_IDS };
+export type { AgentCapabilities, AgentId, AxrunConfig, BuildResult, CanonicalTool, ConfigBuilder, PermissionConfig, PermissionIssue, PermissionRule, };

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core types for axconfig.
+ *
+ * Defines the unified permission model and config builder interfaces.
+ */
+/** Supported agent identifiers */
+const AGENT_IDS = ["claude-code", "codex", "gemini", "opencode"];
+export { AGENT_IDS };