code-agent-auto-commit 1.3.0 → 1.3.2

package/README.md

@@ -45,9 +45,9 @@ cac --help
 cac init
 
 # 2. Configure AI API key for commit messages
-#    Edit .code-agent-auto-commit.json — set your provider, model, and API key env var.
-#    Or export the key in your shell:
-export MINIMAX_API_KEY='your-api-key'   # or OPENAI_API_KEY, etc.
+#    Edit .cac/.code-agent-auto-commit.json — set your model and defaultProvider.
+#    Fill keys in .cac/.env and load them:
+source .cac/.env
 
 # 3. Install hooks
 cac install --tool all --scope project
@@ -79,22 +79,31 @@ cac uninstall [--tool all|opencode|codex|claude] [--scope project|global] [--wor
 cac status [--scope project|global] [--worktree <path>] [--config <path>]
 cac run [--tool opencode|codex|claude|manual] [--worktree <path>] [--config <path>] [--event-json <json>] [--event-stdin]
 cac set-worktree <path> [--config <path>]
+cac ai <message> [--config <path>]
+cac ai set-key <provider|ENV_VAR> <api-key> [--config <path>]
+cac ai get-key <provider|ENV_VAR> [--config <path>]
 ```
 
 ### Command Details
 
-- `cac init`: creates a config file for a worktree. It resolves the target path from `--config` or defaults to `<worktree>/.code-agent-auto-commit.json`.
+- `cac init`: creates `.cac/.code-agent-auto-commit.json` under the worktree (unless `--config` is provided), and also writes `.cac/.env.example` and `.cac/.env` with default provider API key env vars.
 - `cac install`: installs adapters/hooks for selected tools (`opencode`, `codex`, `claude`) in `project` or `global` scope. If no config exists at the resolved path, it creates one first.
 - `cac uninstall`: removes previously installed adapters/hooks for selected tools and scope.
 - `cac status`: prints resolved config path, worktree, commit mode, AI/push toggles, and install status of each adapter.
-- `cac run`: executes one auto-commit pass (manual or hook-triggered). It reads config, filters changed files, stages/commits by configured mode, and optionally pushes.
+- `cac run`: executes one auto-commit pass (manual or hook-triggered). It reads config, filters changed files, stages/commits by configured mode, and optionally pushes. Hook-triggered runs also write logs to `.cac/run-<timestamp>.log`.
 - `cac set-worktree`: updates only the `worktree` field in the resolved config file.
+- `cac ai`: tests AI request (`cac ai "hi"`) or manages global keys (`set-key` / `get-key`).
 
 ## Config File
 
 Default project config file:
 
-`.code-agent-auto-commit.json`
+`.cac/.code-agent-auto-commit.json`
+
+Generated env templates:
+
+- `.cac/.env.example`
+- `.cac/.env`
 
 You can copy from:
 

package/dist/cli.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const claude_1 = require("./adapters/claude");
 const codex_1 = require("./adapters/codex");
@@ -73,6 +74,87 @@ function parseTools(value) {
     }
     return tools;
 }
+const ENV_NAME_REGEX = /^[A-Z_][A-Z0-9_]*$/;
+function resolveAiEnvName(target, aiConfig) {
+    if (ENV_NAME_REGEX.test(target)) {
+        return target;
+    }
+    const providerConfig = aiConfig.providers[target];
+    const envName = providerConfig?.apiKeyEnv?.trim();
+    if (envName && ENV_NAME_REGEX.test(envName)) {
+        return envName;
+    }
+    throw new Error(`Unknown provider or env var: ${target}`);
+}
+function shellQuoteSingle(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function parseExportValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/'"'"'/g, "'");
+    }
+    if (trimmed.startsWith("\"") && trimmed.endsWith("\"")) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function readKeyFromEnvFile(filePath, envName) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return undefined;
+    }
+    const lines = node_fs_1.default.readFileSync(filePath, "utf8").split(/\r?\n/);
+    for (const line of lines) {
+        const match = line.match(/^\s*export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!match) {
+            continue;
+        }
+        if (match[1] !== envName) {
+            continue;
+        }
+        return parseExportValue(match[2]);
+    }
+    return undefined;
+}
+function detectShellRcPath() {
+    const shell = node_path_1.default.basename(process.env.SHELL ?? "");
+    const home = node_os_1.default.homedir();
+    if (shell === "zsh") {
+        return node_path_1.default.join(home, ".zshrc");
+    }
+    if (shell === "bash") {
+        return node_path_1.default.join(home, ".bashrc");
+    }
+    if (shell === "fish") {
+        return node_path_1.default.join(home, ".config", "fish", "config.fish");
+    }
+    return node_path_1.default.join(home, ".profile");
+}
+function ensureGlobalKeysSource(shellRcPath, keysPath) {
+    const isFish = node_path_1.default.basename(shellRcPath) === "config.fish";
+    const sourceLine = isFish
+        ? `if test -f ${JSON.stringify(keysPath)}; source ${JSON.stringify(keysPath)}; end`
+        : `[ -f ${JSON.stringify(keysPath)} ] && source ${JSON.stringify(keysPath)}`;
+    const existing = node_fs_1.default.existsSync(shellRcPath) ? node_fs_1.default.readFileSync(shellRcPath, "utf8") : "";
+    if (existing.includes(keysPath)) {
+        return false;
+    }
+    const next = existing.trimEnd().length > 0
+        ? `${existing.trimEnd()}\n\n# code-agent-auto-commit global AI keys\n${sourceLine}\n`
+        : `# code-agent-auto-commit global AI keys\n${sourceLine}\n`;
+    (0, fs_1.writeTextFile)(shellRcPath, next);
+    return true;
+}
+function writeRunLog(worktree, lines) {
+    const logPath = (0, fs_1.getProjectRunLogPath)(worktree);
+    const content = [
+        `time=${new Date().toISOString()}`,
+        ...lines,
+        "",
+    ].join("\n");
+    (0, fs_1.writeTextFile)(logPath, content);
+    return logPath;
+}
 async function readStdinText() {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -91,6 +173,8 @@ Usage:
   cac run [--tool opencode|codex|claude|manual] [--worktree <path>] [--config <path>] [--event-json <json>] [--event-stdin]
   cac set-worktree <path> [--config <path>]
   cac ai <message> [--config <path>]
+  cac ai set-key <provider|ENV_VAR> <api-key> [--config <path>]
+  cac ai get-key <provider|ENV_VAR> [--config <path>]
   cac version
 `);
 }
@@ -100,6 +184,8 @@ async function commandInit(flags) {
     const configPath = explicit ? node_path_1.default.resolve(explicit) : (0, fs_1.getProjectConfigPath)(worktree);
     (0, config_1.initConfigFile)(configPath, worktree);
     console.log(`Initialized config: ${configPath}`);
+    console.log(`Generated env template: ${(0, fs_1.getProjectEnvExamplePath)(worktree)}`);
+    console.log(`Generated local env: ${(0, fs_1.getProjectEnvPath)(worktree)}`);
 }
 async function commandInstall(flags) {
     const worktree = node_path_1.default.resolve(getStringFlag(flags, "worktree") ?? process.cwd());
@@ -198,6 +284,23 @@ async function commandRun(flags, positionals) {
     const tool = (getStringFlag(flags, "tool") ?? "manual");
     const worktree = getStringFlag(flags, "worktree");
     const configPath = getStringFlag(flags, "config");
+    const shouldLogRun = tool !== "manual";
+    const runLogLines = [];
+    const logInfo = (message) => {
+        console.log(message);
+        runLogLines.push(message);
+    };
+    const logWarn = (message) => {
+        console.warn(message);
+        runLogLines.push(message);
+    };
+    const flushRunLog = (resolvedWorktree) => {
+        if (!shouldLogRun) {
+            return;
+        }
+        const logPath = writeRunLog(resolvedWorktree, runLogLines);
+        logInfo(`Run log: ${logPath}`);
+    };
     let event;
     const eventJson = getStringFlag(flags, "event-json");
     if (eventJson) {
@@ -220,37 +323,119 @@ async function commandRun(flags, positionals) {
     if (tool === "codex" && event && typeof event === "object") {
         const eventType = event.type;
         if (eventType && eventType !== "agent-turn-complete") {
-            console.log(`Skipped: codex event ${eventType}`);
+            logInfo(`Skipped: codex event ${eventType}`);
             return;
         }
     }
-    const result = await (0, run_1.runAutoCommit)({
-        tool,
-        worktree,
-        event,
-        sessionID: getStringFlag(flags, "session-id"),
-    }, {
-        explicitPath: configPath,
-        worktree,
-    });
+    let result;
+    try {
+        result = await (0, run_1.runAutoCommit)({
+            tool,
+            worktree,
+            event,
+            sessionID: getStringFlag(flags, "session-id"),
+        }, {
+            explicitPath: configPath,
+            worktree,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logWarn(`Error: ${message}`);
+        flushRunLog(node_path_1.default.resolve(worktree ?? process.cwd()));
+        throw error;
+    }
     if (result.skipped) {
-        console.log(`Skipped: ${result.reason ?? "unknown"}`);
+        logInfo(`Skipped: ${result.reason ?? "unknown"}`);
+        flushRunLog(result.worktree);
         return;
     }
-    console.log(`Committed: ${result.committed.length}`);
+    logInfo(`Committed: ${result.committed.length}`);
     for (const item of result.committed) {
-        console.log(`- ${item.hash.slice(0, 12)} ${item.message}`);
+        logInfo(`- ${item.hash.slice(0, 12)} ${item.message}`);
     }
-    console.log(`Pushed: ${result.pushed ? "yes" : "no"}`);
+    logInfo(`Pushed: ${result.pushed ? "yes" : "no"}`);
     if (result.tokenUsage) {
-        console.log(`AI tokens: ${result.tokenUsage.totalTokens} (prompt: ${result.tokenUsage.promptTokens}, completion: ${result.tokenUsage.completionTokens})`);
+        logInfo(`AI tokens: ${result.tokenUsage.totalTokens} (prompt: ${result.tokenUsage.promptTokens}, completion: ${result.tokenUsage.completionTokens})`);
     }
     if (result.aiWarning) {
-        console.warn(`\nWarning: AI commit message failed — ${result.aiWarning}`);
-        console.warn(`Using fallback prefix instead. Run "cac ai hello" to test your AI config.`);
+        logWarn("");
+        logWarn(`Warning: AI commit message failed — ${result.aiWarning}`);
+        logWarn(`Using fallback prefix instead. Run "cac ai hello" to test your AI config.`);
     }
+    flushRunLog(result.worktree);
 }
 async function commandAI(flags, positionals) {
+    const worktree = node_path_1.default.resolve(getStringFlag(flags, "worktree") ?? process.cwd());
+    const explicitConfig = getStringFlag(flags, "config");
+    const loaded = (0, config_1.loadConfig)({ explicitPath: explicitConfig, worktree });
+    const subcommand = positionals[0];
+    if (subcommand === "set-key") {
+        const target = positionals[1];
+        const key = positionals.slice(2).join(" ").trim();
+        if (!target || !key) {
+            console.error("Usage: cac ai set-key <provider|ENV_VAR> <api-key>");
+            process.exitCode = 1;
+            return;
+        }
+        const envName = resolveAiEnvName(target, loaded.config.ai);
+        const keysPath = (0, fs_1.getGlobalKeysEnvPath)();
+        const line = `export ${envName}=${shellQuoteSingle(key)}`;
+        const existing = node_fs_1.default.existsSync(keysPath) ? node_fs_1.default.readFileSync(keysPath, "utf8") : "";
+        const lines = existing.split(/\r?\n/);
+        let found = false;
+        const updated = lines.map((entry) => {
+            const match = entry.match(/^\s*export\s+([A-Za-z_][A-Za-z0-9_]*)=/);
+            if (match && match[1] === envName) {
+                found = true;
+                return line;
+            }
+            return entry;
+        });
+        if (!found) {
+            if (updated.length === 1 && updated[0] === "") {
+                updated.splice(0, 1);
+            }
+            if (updated.length === 0) {
+                updated.push("# code-agent-auto-commit global AI keys");
+            }
+            updated.push(line);
+        }
+        (0, fs_1.writeTextFile)(keysPath, `${updated.filter((entry, idx, arr) => !(idx === arr.length - 1 && entry === "")).join("\n")}\n`);
+        process.env[envName] = key;
+        const shellRcPath = detectShellRcPath();
+        const inserted = ensureGlobalKeysSource(shellRcPath, keysPath);
+        console.log(`Set ${envName} in ${keysPath}`);
+        if (inserted) {
+            console.log(`Added source line to ${shellRcPath}`);
+        }
+        console.log(`Global key configured. Open a new shell or run: source ${shellRcPath}`);
+        return;
+    }
+    if (subcommand === "get-key") {
+        const target = positionals[1];
+        if (!target) {
+            console.error("Usage: cac ai get-key <provider|ENV_VAR>");
+            process.exitCode = 1;
+            return;
+        }
+        const envName = resolveAiEnvName(target, loaded.config.ai);
+        const fromProcess = process.env[envName]?.trim();
+        const fromFile = readKeyFromEnvFile((0, fs_1.getGlobalKeysEnvPath)(), envName);
+        const value = fromProcess || fromFile;
+        if (!value) {
+            console.log(`${envName} is not set`);
+            process.exitCode = 1;
+            return;
+        }
+        const masked = value.length <= 8
+            ? `${value.slice(0, 2)}***`
+            : `${value.slice(0, 4)}***${value.slice(-4)}`;
+        console.log(`Env: ${envName}`);
+        console.log(`Value: ${masked}`);
+        console.log(`Source: ${fromProcess ? "process env" : (0, fs_1.getGlobalKeysEnvPath)()}`);
+        return;
+    }
     const message = positionals.join(" ").trim();
     if (!message) {
         console.error(`Usage: cac ai <message>`);
@@ -258,9 +443,6 @@ async function commandAI(flags, positionals) {
         process.exitCode = 1;
         return;
     }
-    const worktree = node_path_1.default.resolve(getStringFlag(flags, "worktree") ?? process.cwd());
-    const explicitConfig = getStringFlag(flags, "config");
-    const loaded = (0, config_1.loadConfig)({ explicitPath: explicitConfig, worktree });
     console.log(`Provider: ${loaded.config.ai.defaultProvider}`);
     console.log(`Model: ${loaded.config.ai.model}`);
     console.log(`Sending: "${message}"`);

package/dist/core/ai.js

@@ -13,6 +13,32 @@ const TYPE_ALIASES = {
     refactoring: "refactor",
     refector: "refactor",
 };
+const MINIMAX_MODEL_ALIASES = {
+    "minimax-m2.5": "MiniMax-M2.5",
+    "minimax-m2.5-highspeed": "MiniMax-M2.5-highspeed",
+    "minimax-m2.1": "MiniMax-M2.1",
+    "minimax-m2.1-highspeed": "MiniMax-M2.1-highspeed",
+    "minimax-m2": "MiniMax-M2",
+    "minimax-text-01": "MiniMax-Text-01",
+    "text-01": "MiniMax-Text-01",
+};
+function normalizeProviderModel(provider, model) {
+    const trimmed = model.trim();
+    const raw = trimmed.includes("/") ? trimmed.slice(trimmed.lastIndexOf("/") + 1) : trimmed;
+    if (provider !== "minimax") {
+        return raw;
+    }
+    return MINIMAX_MODEL_ALIASES[raw.toLowerCase()] ?? raw;
+}
+function minimaxFallbackModel(model) {
+    return model === "MiniMax-Text-01" ? undefined : "MiniMax-Text-01";
+}
+function isUnknownModelError(status, body) {
+    if (status < 400 || status >= 500) {
+        return false;
+    }
+    return /unknown\s+model|invalid\s+model|model.*not\s+found|does\s+not\s+exist|not\s+supported/i.test(body);
+}
 function normalizeCommitType(raw) {
     const value = raw.trim().toLowerCase();
     if (VALID_TYPES.has(value)) {
@@ -134,7 +160,7 @@ function validateAIConfig(ai) {
     }
     return undefined;
 }
-async function generateOpenAiStyleMessage(provider, model, summary, maxLength, signal) {
+async function generateOpenAiStyleMessage(providerName, provider, model, summary, maxLength, signal) {
     const apiKey = getApiKey(provider);
     const headers = {
         "Content-Type": "application/json",
@@ -143,38 +169,59 @@ async function generateOpenAiStyleMessage(provider, model, summary, maxLength, s
     if (apiKey) {
         headers.Authorization = `Bearer ${apiKey}`;
     }
-    const response = await fetch(`${provider.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-            model,
-            temperature: 0.2,
-            messages: [
-                {
-                    role: "system",
-                    content: "You generate exactly one conventional commit message. Format: '<type>(<scope>): <description>'. Scope is optional. Allowed types: feat, fix, refactor, docs, style, test, chore, perf, ci, build. Description must be imperative, lowercase, no period. Describe the actual change, not just 'update <file>'. No quotes. No code block.",
-                },
-                {
-                    role: "user",
-                    content: buildUserPrompt(summary, maxLength),
-                },
-            ],
-        }),
-        signal,
-    });
-    if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        return { content: undefined, usage: undefined, error: `HTTP ${response.status}: ${body.slice(0, 200)}` };
+    async function requestModel(modelName) {
+        const response = await fetch(`${provider.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                model: modelName,
+                temperature: 0.2,
+                messages: [
+                    {
+                        role: "system",
+                        content: "You generate exactly one conventional commit message. Format: '<type>(<scope>): <description>'. Scope is optional. Allowed types: feat, fix, refactor, docs, style, test, chore, perf, ci, build. Description must be imperative, lowercase, no period. Describe the actual change, not just 'update <file>'. No quotes. No code block.",
+                    },
+                    {
+                        role: "user",
+                        content: buildUserPrompt(summary, maxLength),
+                    },
+                ],
+            }),
+            signal,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            return { ok: false, status: response.status, body };
+        }
+        const payload = (await response.json());
+        const usage = payload.usage
+            ? {
+                promptTokens: payload.usage.prompt_tokens ?? 0,
+                completionTokens: payload.usage.completion_tokens ?? 0,
+                totalTokens: payload.usage.total_tokens ?? 0,
+            }
+            : undefined;
+        return { ok: true, content: payload.choices?.[0]?.message?.content, usage };
     }
-    const payload = (await response.json());
-    const usage = payload.usage
-        ? {
-            promptTokens: payload.usage.prompt_tokens ?? 0,
-            completionTokens: payload.usage.completion_tokens ?? 0,
-            totalTokens: payload.usage.total_tokens ?? 0,
+    const first = await requestModel(model);
+    if (first.ok) {
+        return { content: first.content, usage: first.usage };
+    }
+    if (providerName === "minimax" && isUnknownModelError(first.status, first.body)) {
+        const fallback = minimaxFallbackModel(model);
+        if (fallback) {
+            const retry = await requestModel(fallback);
+            if (retry.ok) {
+                return { content: retry.content, usage: retry.usage };
+            }
+            return {
+                content: undefined,
+                usage: undefined,
+                error: `HTTP ${first.status}: ${first.body.slice(0, 200)} | retry(${fallback}) HTTP ${retry.status}: ${retry.body.slice(0, 120)}`,
+            };
         }
-        : undefined;
-    return { content: payload.choices?.[0]?.message?.content, usage };
+    }
+    return { content: undefined, usage: undefined, error: `HTTP ${first.status}: ${first.body.slice(0, 200)}` };
 }
 async function generateAnthropicStyleMessage(provider, model, summary, maxLength, signal) {
     const apiKey = getApiKey(provider);
@@ -220,21 +267,25 @@ async function generateAnthropicStyleMessage(provider, model, summary, maxLength
     return { content: firstText, usage };
 }
 async function generateCommitMessage(ai, summary, maxLength) {
+    if (!ai.enabled) {
+        return { message: undefined, usage: undefined };
+    }
     const configError = validateAIConfig(ai);
     if (configError) {
         return { message: undefined, usage: undefined, warning: configError };
     }
     const { provider, model } = splitModelRef(ai.model, ai.defaultProvider);
+    const resolvedModel = normalizeProviderModel(provider, model);
     const providerConfig = ai.providers[provider];
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ai.timeoutMs);
     try {
         let result;
         if (providerConfig.api === "openai-completions") {
-            result = await generateOpenAiStyleMessage(providerConfig, model, summary, maxLength, controller.signal);
+            result = await generateOpenAiStyleMessage(provider, providerConfig, resolvedModel, summary, maxLength, controller.signal);
         }
         else {
-            result = await generateAnthropicStyleMessage(providerConfig, model, summary, maxLength, controller.signal);
+            result = await generateAnthropicStyleMessage(providerConfig, resolvedModel, summary, maxLength, controller.signal);
         }
         if (result.error) {
             return { message: undefined, usage: result.usage, warning: result.error };
@@ -258,6 +309,7 @@ async function testAI(ai, userMessage) {
         return { ok: false, error: configError };
     }
     const { provider, model } = splitModelRef(ai.model, ai.defaultProvider);
+    const resolvedModel = normalizeProviderModel(provider, model);
     const providerConfig = ai.providers[provider];
     const apiKey = getApiKey(providerConfig);
     const controller = new AbortController();
@@ -269,26 +321,49 @@ async function testAI(ai, userMessage) {
                 Authorization: `Bearer ${apiKey}`,
                 ...(providerConfig.headers ?? {}),
             };
-            const response = await fetch(`${providerConfig.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-                method: "POST",
-                headers,
-                body: JSON.stringify({
-                    model,
-                    temperature: 0.2,
-                    messages: [{ role: "user", content: userMessage }],
-                }),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                const body = await response.text().catch(() => "");
-                return { ok: false, error: `HTTP ${response.status}: ${body.slice(0, 300)}` };
+            async function requestModel(modelName) {
+                const response = await fetch(`${providerConfig.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify({
+                        model: modelName,
+                        temperature: 0.2,
+                        messages: [{ role: "user", content: userMessage }],
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const body = await response.text().catch(() => "");
+                    return { ok: false, status: response.status, body };
+                }
+                const payload = (await response.json());
+                const usage = payload.usage
+                    ? {
+                        promptTokens: payload.usage.prompt_tokens ?? 0,
+                        completionTokens: payload.usage.completion_tokens ?? 0,
+                        totalTokens: payload.usage.total_tokens ?? 0,
+                    }
+                    : undefined;
+                return { ok: true, reply: payload.choices?.[0]?.message?.content ?? "", usage };
             }
-            const payload = (await response.json());
-            const reply = payload.choices?.[0]?.message?.content ?? "";
-            const usage = payload.usage
-                ? { promptTokens: payload.usage.prompt_tokens ?? 0, completionTokens: payload.usage.completion_tokens ?? 0, totalTokens: payload.usage.total_tokens ?? 0 }
-                : undefined;
-            return { ok: true, reply, usage };
+            const first = await requestModel(resolvedModel);
+            if (first.ok) {
+                return { ok: true, reply: first.reply, usage: first.usage };
+            }
+            if (provider === "minimax" && isUnknownModelError(first.status, first.body)) {
+                const fallback = minimaxFallbackModel(resolvedModel);
+                if (fallback) {
+                    const retry = await requestModel(fallback);
+                    if (retry.ok) {
+                        return { ok: true, reply: retry.reply, usage: retry.usage };
+                    }
+                    return {
+                        ok: false,
+                        error: `HTTP ${first.status}: ${first.body.slice(0, 300)} | retry(${fallback}) HTTP ${retry.status}: ${retry.body.slice(0, 200)}`,
+                    };
+                }
+            }
+            return { ok: false, error: `HTTP ${first.status}: ${first.body.slice(0, 300)}` };
         }
         else {
             const headers = {
@@ -301,7 +376,7 @@ async function testAI(ai, userMessage) {
                 method: "POST",
                 headers,
                 body: JSON.stringify({
-                    model,
+                    model: resolvedModel,
                     max_tokens: 256,
                     messages: [{ role: "user", content: userMessage }],
                 }),

package/dist/core/config.js

@@ -141,6 +141,21 @@ function normalizeConfig(config) {
     }
     return config;
 }
+function buildProjectEnvContent(config) {
+    const envNames = Array.from(new Set(Object.values(config.ai.providers)
+        .map((provider) => provider.apiKeyEnv?.trim())
+        .filter((name) => Boolean(name)))).sort();
+    const lines = [
+        "# code-agent-auto-commit local AI keys",
+        "# Fill values and run: source .cac/.env",
+        "",
+    ];
+    for (const envName of envNames) {
+        lines.push(`${envName}=`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
 function resolveConfigPath(options) {
     if (options.explicitPath) {
         return node_path_1.default.resolve(options.explicitPath);
@@ -150,6 +165,10 @@ function resolveConfigPath(options) {
     if (node_fs_1.default.existsSync(projectPath)) {
         return projectPath;
     }
+    const legacyProjectPath = (0, fs_1.getLegacyProjectConfigPath)(cwd);
+    if (node_fs_1.default.existsSync(legacyProjectPath)) {
+        return legacyProjectPath;
+    }
     return (0, fs_1.getGlobalConfigPath)();
 }
 function loadConfig(options) {
@@ -166,8 +185,15 @@ function loadConfig(options) {
     };
 }
 function initConfigFile(targetPath, worktree) {
-    const config = DEFAULT_CONFIG(node_path_1.default.resolve(worktree));
+    const resolvedWorktree = node_path_1.default.resolve(worktree);
+    const config = DEFAULT_CONFIG(resolvedWorktree);
     (0, fs_1.writeJsonFile)(targetPath, config);
+    const envExamplePath = (0, fs_1.getProjectEnvExamplePath)(resolvedWorktree);
+    (0, fs_1.writeTextFile)(envExamplePath, buildProjectEnvContent(config));
+    const envPath = (0, fs_1.getProjectEnvPath)(resolvedWorktree);
+    if (!node_fs_1.default.existsSync(envPath)) {
+        (0, fs_1.writeTextFile)(envPath, buildProjectEnvContent(config));
+    }
     return config;
 }
 function updateConfigWorktree(configPath, worktree) {

package/dist/core/fs.d.ts

@@ -1,6 +1,11 @@
 export declare function getUserConfigHome(): string;
 export declare function getProjectConfigPath(worktree: string): string;
+export declare function getLegacyProjectConfigPath(worktree: string): string;
+export declare function getProjectEnvExamplePath(worktree: string): string;
+export declare function getProjectEnvPath(worktree: string): string;
+export declare function getProjectRunLogPath(worktree: string, date?: Date): string;
 export declare function getGlobalConfigPath(): string;
+export declare function getGlobalKeysEnvPath(): string;
 export declare function ensureDirForFile(filePath: string): void;
 export declare function readJsonFile<T>(filePath: string): T | undefined;
 export declare function writeJsonFile(filePath: string, value: unknown): void;

package/dist/core/fs.js

@@ -5,7 +5,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUserConfigHome = getUserConfigHome;
 exports.getProjectConfigPath = getProjectConfigPath;
+exports.getLegacyProjectConfigPath = getLegacyProjectConfigPath;
+exports.getProjectEnvExamplePath = getProjectEnvExamplePath;
+exports.getProjectEnvPath = getProjectEnvPath;
+exports.getProjectRunLogPath = getProjectRunLogPath;
 exports.getGlobalConfigPath = getGlobalConfigPath;
+exports.getGlobalKeysEnvPath = getGlobalKeysEnvPath;
 exports.ensureDirForFile = ensureDirForFile;
 exports.readJsonFile = readJsonFile;
 exports.writeJsonFile = writeJsonFile;
@@ -13,6 +18,20 @@ exports.writeTextFile = writeTextFile;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
+function formatTimestamp(date) {
+    const pad = (value, size = 2) => String(value).padStart(size, "0");
+    return [
+        date.getFullYear(),
+        pad(date.getMonth() + 1),
+        pad(date.getDate()),
+        "-",
+        pad(date.getHours()),
+        pad(date.getMinutes()),
+        pad(date.getSeconds()),
+        "-",
+        pad(date.getMilliseconds(), 3),
+    ].join("");
+}
 function getUserConfigHome() {
     const xdg = process.env.XDG_CONFIG_HOME;
     if (xdg && xdg.trim().length > 0) {
@@ -21,11 +40,26 @@ function getUserConfigHome() {
     return node_path_1.default.join(node_os_1.default.homedir(), ".config");
 }
 function getProjectConfigPath(worktree) {
+    return node_path_1.default.join(worktree, ".cac", ".code-agent-auto-commit.json");
+}
+function getLegacyProjectConfigPath(worktree) {
     return node_path_1.default.join(worktree, ".code-agent-auto-commit.json");
 }
+function getProjectEnvExamplePath(worktree) {
+    return node_path_1.default.join(worktree, ".cac", ".env.example");
+}
+function getProjectEnvPath(worktree) {
+    return node_path_1.default.join(worktree, ".cac", ".env");
+}
+function getProjectRunLogPath(worktree, date = new Date()) {
+    return node_path_1.default.join(worktree, ".cac", `run-${formatTimestamp(date)}.log`);
+}
 function getGlobalConfigPath() {
     return node_path_1.default.join(getUserConfigHome(), "code-agent-auto-commit", "config.json");
 }
+function getGlobalKeysEnvPath() {
+    return node_path_1.default.join(getUserConfigHome(), "code-agent-auto-commit", "keys.env");
+}
 function ensureDirForFile(filePath) {
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
 }

package/dist/test/config.test.js

@@ -9,15 +9,30 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_test_1 = __importDefault(require("node:test"));
 const strict_1 = __importDefault(require("node:assert/strict"));
 const config_1 = require("../core/config");
+const fs_1 = require("../core/fs");
 (0, node_test_1.default)("init and update config file", () => {
     const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "code-agent-auto-commit-"));
-    const configPath = node_path_1.default.join(tempDir, ".code-agent-auto-commit.json");
+    const configPath = (0, fs_1.getProjectConfigPath)(tempDir);
     const created = (0, config_1.initConfigFile)(configPath, tempDir);
     strict_1.default.equal(created.version, 1);
     strict_1.default.equal(created.worktree, tempDir);
+    strict_1.default.equal(node_fs_1.default.existsSync(node_path_1.default.join(tempDir, ".cac", ".env.example")), true);
+    strict_1.default.equal(node_fs_1.default.existsSync(node_path_1.default.join(tempDir, ".cac", ".env")), true);
     const loaded = (0, config_1.loadConfig)({ explicitPath: configPath, worktree: tempDir });
     strict_1.default.equal(loaded.config.worktree, tempDir);
     const nextDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "code-agent-auto-commit-next-"));
     const updated = (0, config_1.updateConfigWorktree)(configPath, nextDir);
     strict_1.default.equal(updated.worktree, nextDir);
 });
+(0, node_test_1.default)("loadConfig resolves new and legacy project paths", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "code-agent-auto-commit-resolve-"));
+    const newConfigPath = (0, fs_1.getProjectConfigPath)(tempDir);
+    (0, config_1.initConfigFile)(newConfigPath, tempDir);
+    const loadedNew = (0, config_1.loadConfig)({ worktree: tempDir });
+    strict_1.default.equal(loadedNew.path, newConfigPath);
+    node_fs_1.default.rmSync(node_path_1.default.join(tempDir, ".cac"), { recursive: true, force: true });
+    const legacyPath = node_path_1.default.join(tempDir, ".code-agent-auto-commit.json");
+    node_fs_1.default.writeFileSync(legacyPath, JSON.stringify({ version: 1, enabled: true }, null, 2), "utf8");
+    const loadedLegacy = (0, config_1.loadConfig)({ worktree: tempDir });
+    strict_1.default.equal(loadedLegacy.path, legacyPath);
+});

package/docs/CONFIG.md

@@ -3,8 +3,9 @@
 `cac` reads JSON config from:
 
 1. `--config <path>` if provided
-2. `<worktree>/.code-agent-auto-commit.json` if it exists
-3. `~/.config/code-agent-auto-commit/config.json`
+2. `<worktree>/.cac/.code-agent-auto-commit.json` if it exists
+3. `<worktree>/.code-agent-auto-commit.json` if it exists (legacy path)
+4. `~/.config/code-agent-auto-commit/config.json`
 
 ## Schema
 
@@ -70,3 +71,5 @@
   - `gitlab`: remote URL must contain `gitlab`
   - `generic`: no provider URL validation
 - Keep API keys in environment variables when possible.
+- `cac init` also creates `.cac/.env.example` and `.cac/.env` with provider key variables.
+- Hook-triggered `cac run` writes output logs to `.cac/run-<timestamp>.log`.

package/docs/zh-CN.md

@@ -15,9 +15,9 @@ It runs commits automatically when a chat/agent turn ends.
 cac init
 
 # 2. 配置 AI API Key（必须，否则无法生成 AI commit message）
-#    编辑 .code-agent-auto-commit.json，设置 provider、model 和 apiKeyEnv。
-#    或者在 shell 中导出对应的环境变量：
-export MINIMAX_API_KEY='your-api-key'   # 或 OPENAI_API_KEY 等
+#    编辑 .cac/.code-agent-auto-commit.json，设置 model 和 defaultProvider。
+#    在 .cac/.env 中填入 API Key 后加载：
+source .cac/.env
 
 # 3. 安装钩子
 cac install --tool all --scope project
@@ -37,7 +37,8 @@ cac status --scope project
 
 - `cac init [--worktree <path>] [--config <path>]`
   - Initializes a config file.
-  - Writes to `<worktree>/.code-agent-auto-commit.json` by default; use `--config` for a custom path.
+  - 默认写入 `<worktree>/.cac/.code-agent-auto-commit.json`；也会生成 `.cac/.env.example` 和 `.cac/.env`。
+  - 可通过 `--config` 指定自定义路径。
 
 - `cac install [--tool all|opencode|codex|claude] [--scope project|global] [--worktree <path>] [--config <path>]`
   - Installs auto-commit adapters for selected tools (OpenCode/Codex/Claude).
@@ -54,6 +55,16 @@ cac status --scope project
 - `cac run [--tool opencode|codex|claude|manual] [--worktree <path>] [--config <path>] [--event-json <json>] [--event-stdin]`
   - Executes one auto-commit pass (manual trigger or hook trigger).
   - Runs the configured pipeline: filter files -> stage -> commit -> optional push.
+  - 由聊天结束自动触发时，会把本次输出写到 `.cac/run-<timestamp>.log`。
+
+- `cac ai <message> [--config <path>]`
+  - 发送一条测试消息到当前 AI 配置并打印回复。
+
+- `cac ai set-key <provider|ENV_VAR> <api-key> [--config <path>]`
+  - 全局设置 API Key（写入 `~/.config/code-agent-auto-commit/keys.env`），并自动尝试把 source 语句加入 shell rc。
+
+- `cac ai get-key <provider|ENV_VAR> [--config <path>]`
+  - 查看当前 key 是否已配置（以脱敏形式显示）。
 
 - `cac set-worktree <path> [--config <path>]`
   - Updates only the `worktree` field in config and leaves other settings unchanged.
@@ -68,7 +79,7 @@ cac status --scope project
 
 ## Config File
 
-Default location in repository root: `.code-agent-auto-commit.json`
+Default location in repository root: `.cac/.code-agent-auto-commit.json`
 
 For full field details, see `docs/CONFIG.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-agent-auto-commit",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "CAC provides configurable AI auto-commit(using your git account) for OpenCode, Claude Code, Codex, and other AI code agents",
   "license": "MIT",
   "type": "commonjs",