ai-agent-helper 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# ai-agent-helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+使用 TypeScript 和 Zod 开发的 AI agent CLI 管理工具。首版 `0.1.0` 仅实现列出本机 PATH 中可找到的 agent，不安装、更新或启动 agent。
+
+需要 Node.js **22.13 或更高版本**。
+
+## 安装与使用
+
+```sh
+npm install -g ai-agent-helper --registry=https://registry.npmjs.org/
+agent-helper --help
+agent-helper list
+```
+
+## 从源码运行
+
+```sh
+npm install
+npm run build
+node dist/cli.js --help
+node dist/cli.js list
+```
+
+需要使用本地源码提供的 `agent-helper` 命令时，可在构建后于项目目录执行 `npm link`。
+
+## 命令
+
+```sh
+agent-helper --help
+agent-helper -h
+agent-helper --version
+agent-helper list
+agent-helper list --help
+agent-helper list --all
+agent-helper list --json
+agent-helper list --all --json
+```
+
+- 无参数时显示帮助。
+- `list` 默认只列出检测到的 agent，输出名称、命令、状态和路径。
+- `--all` / `-a` 同时列出未检测到的 agent。
+- `--json` 输出纯 JSON 数组；没有检测到时返回 `[]`。
+- 正常查询（包括没有检测到）退出码为 `0`；无效参数或检测异常为 `1`，错误写入 stderr。
+
+JSON 示例：
+
+```json
+[
+  {
+    "id": "claude-code",
+    "name": "Claude Code",
+    "command": "claude",
+    "installed": true,
+    "path": "/usr/local/bin/claude"
+  }
+]
+```
+
+`--all` 中未检测到的条目使用 `installed: false` 和 `path: null`。
+
+## 首版检测范围
+
+| Agent | 命令 | 独立检测模块 |
+| --- | --- | --- |
+| Claude Code | `claude` | `src/agents/claude-code.ts` |
+| Codex | `codex` | `src/agents/codex.ts` |
+| Gemini CLI | `gemini` | `src/agents/gemini.ts` |
+| OpenCode | `opencode` | `src/agents/opencode.ts` |
+| Aider | `aider` | `src/agents/aider.ts` |
+| GitHub Copilot | `copilot` | `src/agents/github-copilot.ts` |
+
+按当前进程的 PATH 顺序查找，只返回首个匹配的可执行入口。Windows 使用 PATHEXT（未设置时使用 `.COM;.EXE;.BAT;.CMD`），支持 npm 的 `.cmd` 入口、大小写不敏感的环境变量名称和带引号的 PATH 目录。macOS/Linux 要求文件有执行权限，支持符号链接。
+
+`installed` 表示找到了对应名称的可执行文件，不保证文件身份、运行正常、版本或登录状态。不会执行 `--version`、读取密钥、联网或加载 shell 配置。PATH 之外的安装、桌面应用、shell alias/function、旧版 `gh copilot` 扩展和未知 agent 不在首版检测范围内。空 PATH 项会跳过；显式的相对 PATH 项相对于当前工作目录解析。
+
+## TypeScript API
+
+```ts
+import { listAgents, agentListSchema, type AgentResult } from "ai-agent-helper";
+
+const installed: AgentResult[] = await listAgents();
+const all = await listAgents({ includeMissing: true });
+agentListSchema.parse(all);
+```
+
+包提供 ESM 导出和类型声明。Zod 校验 CLI 选项及检测结果，并约束已检测到条目必须包含路径、未检测到条目的路径必须为 `null`。
+
+## 开发与扩展
+
+```sh
+npm run dev -- list --all
+npm run check
+npm pack
+```
+
+每种 agent 在 `src/agents/` 中独立实现 `AgentProvider.detect()`，在 `src/agents/index.ts` 注册。当前共用 `src/detection/find-executable.ts` 的 PATH 查找能力；以后可在各自模块内添加专用安装路径或其他识别逻辑，不必修改 CLI。
+
+`src/list-agents.ts` 负责汇总和 Zod 校验，`src/cli.ts` 负责参数解析与展示。测试使用临时目录和伪可执行入口，不启动本机 agent；包含 CLI 帮助、错误参数、JSON、PATH 优先级、Windows PATHEXT、POSIX 执行权限等用例。平台专属用例只在对应平台执行。

package/dist/agents/aider.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const aider: AgentProvider;

package/dist/agents/aider.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const aider = {
+    definition: { id: "aider", name: "Aider", command: "aider" },
+    async detect(context) {
+        return findExecutable("aider", context);
+    },
+};

package/dist/agents/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const claudeCode: AgentProvider;

package/dist/agents/claude-code.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const claudeCode = {
+    definition: { id: "claude-code", name: "Claude Code", command: "claude" },
+    async detect(context) {
+        return findExecutable("claude", context);
+    },
+};

package/dist/agents/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const codex: AgentProvider;

package/dist/agents/codex.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const codex = {
+    definition: { id: "codex", name: "Codex", command: "codex" },
+    async detect(context) {
+        return findExecutable("codex", context);
+    },
+};

package/dist/agents/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const gemini: AgentProvider;

package/dist/agents/gemini.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const gemini = {
+    definition: { id: "gemini", name: "Gemini CLI", command: "gemini" },
+    async detect(context) {
+        return findExecutable("gemini", context);
+    },
+};

package/dist/agents/github-copilot.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const githubCopilot: AgentProvider;

package/dist/agents/github-copilot.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const githubCopilot = {
+    definition: { id: "github-copilot", name: "GitHub Copilot", command: "copilot" },
+    async detect(context) {
+        return findExecutable("copilot", context);
+    },
+};

package/dist/agents/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const builtInAgents: readonly AgentProvider[];

package/dist/agents/index.js

@@ -0,0 +1,7 @@
+import { aider } from "./aider.js";
+import { claudeCode } from "./claude-code.js";
+import { codex } from "./codex.js";
+import { gemini } from "./gemini.js";
+import { githubCopilot } from "./github-copilot.js";
+import { opencode } from "./opencode.js";
+export const builtInAgents = [claudeCode, codex, gemini, opencode, aider, githubCopilot];

package/dist/agents/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const opencode: AgentProvider;

package/dist/agents/opencode.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const opencode = {
+    definition: { id: "opencode", name: "OpenCode", command: "opencode" },
+    async detect(context) {
+        return findExecutable("opencode", context);
+    },
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { listAgents } from "./list-agents.js";
+const help = `agent-helper — 列出本地 AI agent CLI
+
+用法：
+  agent-helper list [--all] [--json]
+  agent-helper [--help | --version]
+
+命令：
+  list             列出 PATH 中检测到的 agent
+
+选项：
+  -a, --all        同时显示未检测到的 agent（仅用于 list）
+      --json       输出 JSON 数组（仅用于 list）
+  -h, --help       显示帮助，支持 list --help
+  -v, --version    显示 agent-helper 版本
+
+示例：
+  agent-helper list
+  agent-helper list --all
+  agent-helper list --json
+  agent-helper list --all --json
+
+检测范围：Claude Code、Codex、Gemini CLI、OpenCode、Aider、GitHub Copilot。
+仅查找 PATH 中的可执行入口，不启动 agent，不检查登录状态或版本。`;
+const cliOptionsSchema = z.object({
+    all: z.boolean().default(false),
+    json: z.boolean().default(false),
+    help: z.boolean().default(false),
+    version: z.boolean().default(false),
+});
+function printTable(agents) {
+    if (agents.length === 0) {
+        console.log("未在 PATH 中检测到支持的 agent。使用 agent-helper list --all 查看检测范围。");
+        return;
+    }
+    const rows = [["AGENT", "COMMAND", "STATUS", "PATH"], ...agents.map((agent) => [
+            agent.name, agent.command, agent.installed ? "found" : "not found", agent.path ?? "-",
+        ])];
+    const widths = [0, 1, 2].map((column) => Math.max(...rows.map((row) => row[column].length)));
+    console.log(rows.map((row) => row.map((value, column) => column < 3 ? value.padEnd(widths[column] + 2) : value).join("")).join("\n"));
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        options: {
+            all: { type: "boolean", short: "a" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const options = cliOptionsSchema.parse(values);
+    if (positionals.length > 1 || (positionals[0] !== undefined && positionals[0] !== "list")) {
+        throw new Error(`未知命令：${positionals.join(" ")}。使用 agent-helper --help 查看帮助。`);
+    }
+    if (options.help) {
+        console.log(help);
+        return;
+    }
+    if (options.version) {
+        const metadata = z.object({ version: z.string().min(1) }).parse(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")));
+        console.log(metadata.version);
+        return;
+    }
+    if (positionals.length === 0) {
+        if (options.all || options.json)
+            throw new Error("--all 和 --json 需要与 list 命令一起使用。");
+        console.log(help);
+        return;
+    }
+    const agents = await listAgents({ includeMissing: options.all });
+    if (options.json)
+        console.log(JSON.stringify(agents, null, 2));
+    else
+        printTable(agents);
+}
+main().catch((error) => {
+    console.error(`agent-helper: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/detection/find-executable.d.ts

@@ -0,0 +1,3 @@
+import type { DetectionContext } from "./types.js";
+/** Search PATH in order without running the executable or loading shell profiles. */
+export declare function findExecutable(command: string, context: DetectionContext): Promise<string | null>;

package/dist/detection/find-executable.js

@@ -0,0 +1,46 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+function getEnv(context, name) {
+    if (context.platform !== "win32")
+        return context.env[name];
+    const key = Object.keys(context.env).find((key) => key.toUpperCase() === name);
+    return key === undefined ? undefined : context.env[key];
+}
+async function isExecutable(file, windows) {
+    try {
+        if (!(await stat(file)).isFile())
+            return false;
+        await access(file, windows ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP"].includes(code ?? ""))
+            return false;
+        throw error;
+    }
+}
+/** Search PATH in order without running the executable or loading shell profiles. */
+export async function findExecutable(command, context) {
+    const windows = context.platform === "win32";
+    const paths = windows ? win32 : posix;
+    const extensions = windows
+        ? (getEnv(context, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD")
+            .split(";")
+            .filter((extension) => /^\.[a-z0-9]+$/i.test(extension))
+        : [""];
+    const directories = (getEnv(context, "PATH") ?? "").split(paths.delimiter);
+    for (const rawDirectory of directories) {
+        // Empty PATH entries do not implicitly opt into scanning the current directory.
+        const directory = windows ? rawDirectory.replace(/^"(.*)"$/, "$1") : rawDirectory;
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = paths.resolve(context.cwd, directory, `${command}${extension}`);
+            if (await isExecutable(candidate, windows))
+                return candidate;
+        }
+    }
+    return null;
+}

package/dist/detection/types.d.ts

@@ -0,0 +1,10 @@
+import type { AgentDefinition } from "../schema.js";
+export interface DetectionContext {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    cwd: string;
+}
+export interface AgentProvider {
+    definition: AgentDefinition;
+    detect(context: DetectionContext): Promise<string | null>;
+}

package/dist/detection/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { listAgents, type ListAgentsOptions } from "./list-agents.js";
+export { agentDefinitionSchema, agentResultSchema, agentListSchema, type AgentDefinition, type AgentResult } from "./schema.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { listAgents } from "./list-agents.js";
+export { agentDefinitionSchema, agentResultSchema, agentListSchema } from "./schema.js";

package/dist/list-agents.d.ts

@@ -0,0 +1,6 @@
+import type { DetectionContext } from "./detection/types.js";
+import { type AgentResult } from "./schema.js";
+export interface ListAgentsOptions extends Partial<DetectionContext> {
+    includeMissing?: boolean;
+}
+export declare function listAgents(options?: ListAgentsOptions): Promise<AgentResult[]>;

package/dist/list-agents.js

@@ -0,0 +1,14 @@
+import { builtInAgents } from "./agents/index.js";
+import { agentListSchema } from "./schema.js";
+export async function listAgents(options = {}) {
+    const context = {
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+        cwd: options.cwd ?? process.cwd(),
+    };
+    const results = await Promise.all(builtInAgents.map(async (provider) => {
+        const path = await provider.detect(context);
+        return { ...provider.definition, installed: path !== null, path };
+    }));
+    return agentListSchema.parse(results).filter((agent) => options.includeMissing || agent.installed);
+}

package/dist/schema.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export declare const agentDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+}, z.core.$strip>;
+export declare const agentResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<true>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<false>;
+    path: z.ZodNull;
+}, z.core.$strip>], "installed">;
+export declare const agentListSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<true>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<false>;
+    path: z.ZodNull;
+}, z.core.$strip>], "installed">>;
+export type AgentDefinition = z.infer<typeof agentDefinitionSchema>;
+export type AgentResult = z.infer<typeof agentResultSchema>;

package/dist/schema.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const agentDefinitionSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    command: z.string().min(1),
+});
+export const agentResultSchema = z.discriminatedUnion("installed", [
+    agentDefinitionSchema.extend({ installed: z.literal(true), path: z.string().min(1) }),
+    agentDefinitionSchema.extend({ installed: z.literal(false), path: z.null() }),
+]);
+export const agentListSchema = z.array(agentResultSchema);

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "ai-agent-helper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "Discover locally installed AI agent CLIs.",
+  "type": "module",
+  "bin": {
+    "agent-helper": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "claude",
+    "codex",
+    "gemini",
+    "typescript"
+  ],
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}