@evanbobo/colco 0.0.0-stage → 0.18.0

package/src/cli.mjs

@@ -0,0 +1,301 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { AGENTS, agentByName, currentAgent } from "./agents/index.mjs";
+import { callTool, ColcoError, VERSION } from "./api.mjs";
+import { configPath, normaliseServer, readConfig, resolveConnection, TOKEN_ENV, writeConfig } from "./config.mjs";
+import { homeDir } from "./home.mjs";
+import { applyInstall, applyRemove, inspect, planInstall } from "./install.mjs";
+import { project, runGit } from "./project.mjs";
+import { cliConfirmation, readMarkers, recordMarker, TASK_STATUSES } from "./usage/markers.mjs";
+import { buildReports, sendReports, totalTokens } from "./usage/report.mjs";
+import { ask, askSecret, choose, multiSelect } from "./prompt.mjs";
+
+/*
+ * The colco command. `add`, `list` and `remove` manage the skill for the chosen agents; `task start|done`
+ * move a task, record where it starts or ends in Colco's marker file and, on done, report the session's
+ * usage; `report` reports (or previews) without moving anything; `call` runs any Colco tool with the saved
+ * API key; `project` finds the projects that use this directory's git repository.
+ */
+
+const HELP = `colco ${VERSION} — Colco（叩叩）协作的 Agent Skill 与用量上报
+
+用法:
+  colco add [-a <agent>]... [-p] [--copy] [--server <url>] [-y] [--force]
+                                安装 Skill；不带 -a 时列出可选 Agent 供勾选
+  colco list [-p]               查看各 Agent 的安装情况
+  colco remove [-a <agent>]... [-p]
+                                卸载 Skill
+  colco task start <id>         把任务改为进行中，开始记录用量
+  colco task done <id> [--status review|blocked|todo|done]
+                                结束任务（默认 done），并上报本会话的模型与 Token
+  colco report [--task <id>] [--dry-run] [--agent <name> --session <id>]
+                                重新统计本会话并上报；--dry-run 只预览
+  colco call <tool> ['<json>']  用已保存的 API Key 调用任意 Colco 工具
+  colco project [--json]        按当前目录的 git 远程地址和分支找到对应的 Colco 项目
+  colco whoami                  检查连接
+
+选项:
+  -a, --agent <name>   ${AGENTS.map((agent) => agent.name).join("、")}（可重复）
+  -p, --project        安装到当前项目（默认全局，对所有项目生效）
+  --copy               复制文件而不是创建链接
+  -y, --yes            不提问，使用默认值
+  --server <url>       Colco 服务地址（也可设置 COLCO_SERVER）
+  --json               colco project 以 JSON 输出
+  API Key 读取 ${TOKEN_ENV}，或 colco add 时保存在 ~/.colco/config.json（仅本人可读）。`;
+
+/** Splits argv into positionals and flags; repeated flags collect into arrays. */
+export function parseArgs(argv) {
+  const positionals = [];
+  const flags = { agent: [] };
+  const valued = new Map([["-a", "agent"], ["--agent", "agent"], ["--server", "server"], ["--task", "task"], ["--session", "session"], ["--status", "status"]]);
+  const booleans = new Map([["-p", "project"], ["--project", "project"], ["-g", "global"], ["--global", "global"], ["--copy", "copy"], ["-y", "yes"], ["--yes", "yes"], ["--force", "force"], ["--dry-run", "dryRun"], ["--json", "json"], ["-h", "help"], ["--help", "help"], ["-v", "version"], ["--version", "version"]]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const [name, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+    if (valued.has(name)) {
+      const value = inline ?? argv[(index += 1)];
+      if (value === undefined) throw new ColcoError(`${name} 需要一个值`);
+      const key = valued.get(name);
+      if (key === "agent") flags.agent.push(...value.split(",").filter(Boolean));
+      else flags[key] = value;
+    } else if (booleans.has(name)) {
+      flags[booleans.get(name)] = true;
+    } else if (arg.startsWith("-") && arg !== "-") {
+      throw new ColcoError(`未知选项：${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+/** A positive task id from text. */
+function taskIdOf(value) {
+  const id = Number(value);
+  if (!/^\d+$/.test(String(value ?? "")) || !Number.isSafeInteger(id) || id < 1) throw new ColcoError("任务 id 必须是正整数");
+  return id;
+}
+
+/** Short token count: 6.4M, 78.2K. */
+function short(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return String(n);
+}
+
+/** The agents named on the command line, validated. */
+function namedAgents(names) {
+  return names.map((name) => {
+    const agent = agentByName(name);
+    if (!agent) throw new ColcoError(`不支持的 Agent：${name}（可选 ${AGENTS.map((candidate) => candidate.name).join("、")}）`);
+    return agent;
+  });
+}
+
+/** `colco add`: choose agents, scope and method, connect, then install. */
+async function add(flags, io) {
+  const interactive = !flags.yes && process.stdin.isTTY;
+  let agents = namedAgents(flags.agent);
+  if (agents.length === 0) {
+    const detected = AGENTS.filter((agent) => agent.detect());
+    if (interactive) {
+      const picked = await multiSelect("为哪些 Agent 安装 Colco Skill？", AGENTS.map((agent) => ({
+        value: agent.name, label: agent.displayName, hint: agent.detect() ? "已检测到" : "未检测到", selected: agent.detect(),
+      })));
+      agents = namedAgents(picked);
+    } else {
+      agents = detected;
+    }
+  }
+  if (agents.length === 0) throw new ColcoError("没有选择 Agent：用 -a claude-code 或 -a codex 指定");
+
+  let scope = flags.project ? "project" : "global";
+  if (interactive && !flags.project && !flags.global) {
+    scope = await choose("安装范围", [{ value: "global", label: "全局：所有项目都能用（推荐）" }, { value: "project", label: "仅当前项目" }]);
+  }
+  let method = flags.copy ? "copy" : "symlink";
+  if (interactive && !flags.copy) {
+    method = await choose("安装方式", [{ value: "symlink", label: "链接到同一份副本，更新一次全部生效（推荐）" }, { value: "copy", label: "每个 Agent 各复制一份" }]);
+  }
+
+  const saved = readConfig();
+  let server = normaliseServer(flags.server) ?? resolveConnection().server;
+  if (!server && interactive) server = normaliseServer(await ask("Colco 服务地址，例如 https://colco.example.com"));
+  if (!server) throw new ColcoError("缺少 Colco 服务地址：加 --server <url>");
+  let token = process.env[TOKEN_ENV] || saved.token || null;
+  let tokenEntered = false;
+  if (!token && interactive) {
+    token = await askSecret("API Key（在 Colco 侧边栏「协作 → Agent」页创建，以 colco_ 开头）");
+    tokenEntered = true;
+  }
+  if (!token) throw new ColcoError(`缺少 API Key：设置 ${TOKEN_ENV}，或在终端中运行 colco add`);
+  const me = await callTool({ server, token }, "whoami", {}, io.fetch);
+  writeConfig({ ...saved, server, ...(tokenEntered ? { token } : {}) });
+  io.out(`已连接：${me.displayName || me.username}`);
+
+  const response = await io.fetch(`${server}/api/agent/skill.md`).catch((error) => {
+    throw new ColcoError(`下载 Skill 失败：${error.message}`);
+  });
+  if (!response.ok) throw new ColcoError(`下载 Skill 失败：HTTP ${response.status}`);
+  const plan = planInstall({ agents, scope, method });
+  const { results, canonicalBackup } = applyInstall(plan, await response.text(), { force: flags.force === true });
+  io.out(`Skill 副本：${plan.canonical}`);
+  if (canonicalBackup) io.out(`原有的 ${plan.canonical} 已移到 ${canonicalBackup}`);
+  for (const result of results) {
+    const how = result.action === "canonical" ? "直接使用该副本" : result.action === "symlink" ? `链接 ${result.dir}` : `复制到 ${result.dir}`;
+    io.out(`${result.ok ? "✓" : "✗"} ${result.displayName}：${result.ok ? how : `${result.dir} ${result.message}`}`);
+    if (result.backup) io.out(`  原有的 ${result.dir} 已移到 ${result.backup}`);
+  }
+  const legacy = join(homeDir(), ".claude", "skills", "analytics-collab");
+  if (existsSync(legacy)) io.out(`提示：发现改名前的旧 Skill ${legacy}，确认不再需要后可删除。`);
+  io.out(`配置：${configPath()}（${tokenEntered ? "已保存 API Key，仅本人可读" : `API Key 读取 ${TOKEN_ENV}`}）`);
+  io.out("重启 Agent 后生效。完成任务时运行 colco task done <id> 会自动上报用了哪些模型、多少 Token。");
+  return results.every((result) => result.ok) ? 0 : 1;
+}
+
+/** `colco list` and `colco remove`. */
+function listOrRemove(command, flags, io) {
+  const scope = flags.project ? "project" : "global";
+  const agents = flags.agent.length > 0 ? namedAgents(flags.agent) : AGENTS;
+  const plan = planInstall({ agents, scope });
+  if (command === "list") {
+    io.out(`范围：${scope === "project" ? "当前项目" : "全局"}；副本：${plan.canonical}`);
+    const labels = { linked: "已安装（链接）", installed: "已安装", missing: "未安装", other: "有同名的其他 Skill" };
+    for (const target of inspect(plan)) {
+      const agent = agentByName(target.agent);
+      io.out(`${target.displayName.padEnd(12)} ${labels[target.state]}${agent.detect() ? "" : "（未检测到该 Agent）"}`);
+    }
+    return 0;
+  }
+  const removed = applyRemove(plan, { keepCanonical: flags.agent.length > 0 && flags.agent.length < AGENTS.length });
+  io.out(removed.length > 0 ? removed.map((path) => `已删除 ${path}`).join("\n") : "没有需要删除的内容");
+  return 0;
+}
+
+/**
+ * The agent, session log and session id this command belongs to, from flags or from the environment the agent
+ * gave this shell; null outside a recognisable agent session.
+ */
+function resolveSession(flags) {
+  if (flags.agent.length > 0) {
+    const [agent] = namedAgents(flags.agent.slice(0, 1));
+    const path = flags.session ? agent.findSession(flags.session) : agent.currentSession();
+    if (!path) throw new ColcoError(`找不到 ${agent.displayName} 的会话${flags.session ? ` ${flags.session}` : ""}`);
+    return { agent, path, sessionId: agent.sessionId(path) };
+  }
+  const agent = currentAgent();
+  const path = agent?.currentSession();
+  return agent && path ? { agent, path, sessionId: agent.sessionId(path) } : null;
+}
+
+/** Prints the reports of a session. */
+function printReports(built, io) {
+  for (const report of built.reports) {
+    const calls = report.models.reduce((sum, entry) => sum + entry.calls, 0);
+    io.out(`任务 ${report.taskId}：${short(totalTokens(report.models))} Token，${calls} 次调用`);
+    for (const entry of report.models) {
+      io.out(`  ${entry.model}  调用 ${entry.calls}  输入 ${short(entry.input_tokens)}  输出 ${short(entry.output_tokens)}  缓存读 ${short(entry.cache_read_tokens)}  缓存写 ${short(entry.cache_write_tokens)}`);
+    }
+  }
+  if (built.unassigned.length > 0) io.out(`不属于任何任务：${short(totalTokens(built.unassigned))} Token`);
+}
+
+/** Reads the session and its markers, builds the reports and sends them unless this is a dry run. */
+async function report(flags, io, { onlyTask = null, found = resolveSession(flags) } = {}) {
+  if (!found) {
+    io.out("colco: 未上报用量：当前不在可识别的 Agent 会话中（用 --agent 和 --session 指定）");
+    return flags.dryRun ? 1 : 0;
+  }
+  const session = found.agent.read(found.path);
+  const markers = readMarkers({ agent: found.agent.name, session: found.sessionId });
+  const built = buildReports({ ...session, sessionId: found.sessionId }, markers, { onlyTask });
+  io.out(`colco: ${found.agent.name} 会话 ${built.sessionId}`);
+  if (built.reports.length === 0) {
+    io.out("这个会话还没有开始过任务（colco task start <id>）");
+    return 0;
+  }
+  printReports(built, io);
+  if (flags.dryRun) return 0;
+  const results = await sendReports(resolveConnection(), found.agent.name, built, io.fetch);
+  for (const result of results) io.out(result.ok ? `已上报任务 ${result.taskId}` : `任务 ${result.taskId} 上报失败：${result.message}`);
+  return results.every((result) => result.ok) ? 0 : 1;
+}
+
+/** `colco task start|done <id>`. */
+async function task(positionals, flags, io) {
+  const [action, rawId] = positionals;
+  if (action !== "start" && action !== "done") throw new ColcoError("用法：colco task start <id> 或 colco task done <id>");
+  const taskId = taskIdOf(rawId);
+  const status = action === "start" ? "in_progress" : flags.status ?? "done";
+  if (action === "done" && (!TASK_STATUSES.has(status) || status === "in_progress")) throw new ColcoError("--status 只能是 done、review、blocked、todo 或 backlog");
+  const found = resolveSession(flags);
+  const data = await callTool(resolveConnection(), "update_task", { task_id: taskId, status }, io.fetch);
+  const marker = found ? recordMarker({ agent: found.agent.name, session: found.sessionId, taskId, status: data.task.status }) : null;
+  io.out(cliConfirmation(taskId, data.task.status, marker?.id));
+  io.out(`「${data.task.title}」`);
+  if (!marker) io.out("colco: 未记录用量：当前不在可识别的 Agent 会话中（用 --agent 和 --session 指定）");
+  if (action === "start" || !marker) return 0;
+  return report(flags, io, { found });
+}
+
+/** Runs the CLI; returns the exit code. `io` carries output, the fetch used for every request and the git runner. */
+export async function main(argv, output = {}) {
+  const io = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+    fetch: (...args) => fetch(...args),
+    git: runGit,
+    ...output,
+  };
+  try {
+    const { positionals, flags } = parseArgs(argv);
+    const [command, ...rest] = positionals;
+    if (flags.version) {
+      io.out(VERSION);
+      return 0;
+    }
+    if (!command || flags.help || command === "help") {
+      io.out(HELP);
+      return 0;
+    }
+    switch (command) {
+      case "add":
+      case "install":
+        return await add(flags, io);
+      case "list":
+      case "ls":
+      case "remove":
+      case "rm":
+        return listOrRemove(command === "ls" ? "list" : command === "rm" ? "remove" : command, flags, io);
+      case "task":
+        return await task(rest, flags, io);
+      case "report":
+        return await report(flags, io, { onlyTask: flags.task === undefined ? null : taskIdOf(flags.task) });
+      case "project":
+        return await project(flags, io, resolveConnection());
+      case "whoami": {
+        const me = await callTool(resolveConnection(), "whoami", {}, io.fetch);
+        io.out(`${me.displayName || me.username}（${me.username}）`);
+        return 0;
+      }
+      case "call": {
+        const [tool, json = "{}"] = rest;
+        if (!tool) throw new ColcoError("用法：colco call <tool> '<json>'");
+        let args;
+        try {
+          args = JSON.parse(json);
+        } catch {
+          throw new ColcoError("参数必须是 JSON");
+        }
+        io.out(JSON.stringify(await callTool(resolveConnection(), tool, args, io.fetch), null, 2));
+        return 0;
+      }
+      default:
+        throw new ColcoError(`未知命令：${command}（运行 colco help 查看用法）`);
+    }
+  } catch (error) {
+    io.err(`colco: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,59 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homeDir } from "./home.mjs";
+
+/*
+ * Where to reach Colco and with which API key. The environment wins over the saved file, so a key can be
+ * kept out of the file entirely. The file is created readable by its owner only. The key is never printed.
+ */
+
+export const TOKEN_ENV = "COLCO_AGENT_TOKEN";
+export const SERVER_ENV = "COLCO_SERVER";
+
+/** Colco's own folder: the configuration and installer backups. */
+export function colcoHome(env = process.env) {
+  return env.COLCO_HOME || join(homeDir(env), ".colco");
+}
+
+/** Path of the saved configuration. */
+export function configPath(env = process.env) {
+  return join(colcoHome(env), "config.json");
+}
+
+/** The saved configuration, or an empty one. */
+export function readConfig(env = process.env) {
+  const path = configPath(env);
+  if (!existsSync(path)) return {};
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Saves the configuration with owner-only permissions. */
+export function writeConfig(config, env = process.env) {
+  const path = configPath(env);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** Normalises a server address to an origin without a trailing slash, or null when it is not http(s). */
+export function normaliseServer(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return null;
+  }
+}
+
+/** The effective server and API key. */
+export function resolveConnection(env = process.env) {
+  const saved = readConfig(env);
+  return { server: normaliseServer(env[SERVER_ENV]) ?? normaliseServer(saved.server), token: env[TOKEN_ENV] || saved.token || null };
+}

package/src/home.mjs

@@ -0,0 +1,6 @@
+import { homedir } from "node:os";
+
+/** The user's home folder from `env` (HOME, then USERPROFILE), so callers and tests can point it elsewhere. */
+export function homeDir(env = process.env) {
+  return env.HOME || env.USERPROFILE || homedir();
+}

package/src/install.mjs

@@ -0,0 +1,164 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { colcoHome } from "./config.mjs";
+import { homeDir } from "./home.mjs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/*
+ * Installs the Colco skill the way the skills CLI does: one canonical copy in `.agents/skills/colco`
+ * (global under the home directory, or inside the project), and each selected agent's skills folder linked
+ * to it, or given its own copy. The canonical copy holds SKILL.md and this package under scripts/, so the
+ * skill runs `colco` locally without downloading anything. Only folders that are ours are replaced.
+ */
+
+export const SKILL_NAME = "colco";
+/** The command the server's SKILL.md uses; the installed copy runs the bundled script instead. */
+export const NPX_COMMAND = "npx -y @evanbobo/colco";
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The canonical skill folder for a scope. */
+export function canonicalDir(scope, cwd = process.cwd(), env = process.env) {
+  return scope === "project" ? join(cwd, ".agents", "skills", SKILL_NAME) : join(homeDir(env), ".agents", "skills", SKILL_NAME);
+}
+
+/** The skill folder of one agent for a scope. */
+export function agentSkillDir(agent, scope, cwd = process.cwd(), env = process.env) {
+  return scope === "project" ? join(cwd, agent.projectSkillsDir, SKILL_NAME) : join(agent.globalSkillsDir(env), SKILL_NAME);
+}
+
+/** Where everything goes; agents whose folder is the canonical one need no link. */
+export function planInstall({ agents, scope = "global", method = "symlink", cwd = process.cwd(), env = process.env }) {
+  const canonical = canonicalDir(scope, cwd, env);
+  return {
+    canonical,
+    scope,
+    targets: agents.map((agent) => {
+      const dir = agentSkillDir(agent, scope, cwd, env);
+      return { agent: agent.name, displayName: agent.displayName, dir, action: resolve(dir) === resolve(canonical) ? "canonical" : method };
+    }),
+  };
+}
+
+/** Points the skill's commands at the bundled script. */
+export function localizeSkill(markdown, scriptPath) {
+  return markdown.split(NPX_COMMAND).join(`node "${scriptPath}"`);
+}
+
+/**
+ * Whether a path is a Colco skill folder (its SKILL.md is named colco) or a link to the canonical copy or to
+ * another Colco folder, so replacing it loses nothing of the user's. Other links, broken or looping ones
+ * included, are not ours.
+ */
+function isOurs(path, canonical, depth = 0) {
+  try {
+    if (lstatSync(path).isSymbolicLink()) {
+      const target = resolve(dirname(path), readlinkSync(path));
+      if (target === resolve(canonical)) return true;
+      return depth < 8 && existsSync(target) && isOurs(target, canonical, depth + 1);
+    }
+    const skill = join(path, "SKILL.md");
+    return existsSync(skill) && /^name:\s*colco\s*$/m.test(readFileSync(skill, "utf8").slice(0, 600));
+  } catch {
+    return false;
+  }
+}
+
+/** Whether anything exists at a path, including a broken link. */
+function present(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Moves a folder that is not ours into ~/.colco/backups and returns where it went. */
+function moveAside(path, env) {
+  const backups = join(colcoHome(env), "backups");
+  mkdirSync(backups, { recursive: true });
+  const name = relative(homeDir(env), path).replace(/[\\/:]+/g, "_").replace(/^_+/, "") || "colco";
+  let target = join(backups, `${name}-${Date.now()}`);
+  for (let n = 1; present(target); n += 1) target = join(backups, `${name}-${Date.now()}-${n}`);
+  try {
+    renameSync(path, target);
+  } catch {
+    cpSync(path, target, { recursive: true, verbatimSymlinks: true });
+    rmSync(path, { recursive: true, force: true });
+  }
+  return target;
+}
+
+/**
+ * Writes the canonical copy and links or copies it into each agent's folder. Returns one result per
+ * target; a folder that is not ours is left alone, or with `force` moved to ~/.colco/backups (never deleted).
+ */
+export function applyInstall(plan, skillMarkdown, { force = false, env = process.env } = {}) {
+  const scriptPath = join(plan.canonical, "scripts", "bin", "colco.mjs");
+  let canonicalBackup = null;
+  if (present(plan.canonical) && !isOurs(plan.canonical, plan.canonical)) {
+    if (!force) throw new Error(`${plan.canonical} 已存在且不是 Colco 的 Skill；确认后加 --force（原目录会移到 ~/.colco/backups）`);
+    canonicalBackup = moveAside(plan.canonical, env);
+  }
+  rmSync(plan.canonical, { recursive: true, force: true });
+  mkdirSync(join(plan.canonical, "scripts"), { recursive: true });
+  for (const part of ["bin", "src", "package.json", "LICENSE", "NOTICE"]) {
+    const from = join(PACKAGE_ROOT, part);
+    if (existsSync(from)) cpSync(from, join(plan.canonical, "scripts", part), { recursive: true });
+  }
+  writeFileSync(join(plan.canonical, "SKILL.md"), localizeSkill(skillMarkdown, scriptPath));
+
+  const results = [];
+  for (const target of plan.targets) {
+    if (target.action === "canonical") {
+      results.push({ ...target, ok: true });
+      continue;
+    }
+    let backup = null;
+    if (present(target.dir) && !isOurs(target.dir, plan.canonical)) {
+      if (!force) {
+        results.push({ ...target, ok: false, message: "已存在且不是 Colco 的 Skill，未覆盖（加 --force 会把它移到 ~/.colco/backups）" });
+        continue;
+      }
+      backup = moveAside(target.dir, env);
+    }
+    rmSync(target.dir, { recursive: true, force: true });
+    mkdirSync(dirname(target.dir), { recursive: true });
+    let action = target.action;
+    if (action === "symlink") {
+      try {
+        symlinkSync(relative(dirname(target.dir), plan.canonical), target.dir, "dir");
+      } catch {
+        action = "copy";
+      }
+    }
+    if (action === "copy") cpSync(plan.canonical, target.dir, { recursive: true });
+    results.push({ ...target, action, ok: true, backup });
+  }
+  return { scriptPath, results, canonicalBackup };
+}
+
+/** Removes the agents' links or copies, and the canonical copy when no agent is left using it. */
+export function applyRemove(plan, { keepCanonical = false } = {}) {
+  const removed = [];
+  for (const target of plan.targets) {
+    if (target.action === "canonical" || !present(target.dir) || !isOurs(target.dir, plan.canonical)) continue;
+    rmSync(target.dir, { recursive: true, force: true });
+    removed.push(target.dir);
+  }
+  if (!keepCanonical && present(plan.canonical) && isOurs(plan.canonical, plan.canonical)) {
+    rmSync(plan.canonical, { recursive: true, force: true });
+    removed.push(plan.canonical);
+  }
+  return removed;
+}
+
+/** Install state of each target: linked, copied, missing, or someone else's folder. */
+export function inspect(plan) {
+  return plan.targets.map((target) => {
+    const dir = target.action === "canonical" ? plan.canonical : target.dir;
+    if (!present(dir)) return { ...target, state: "missing" };
+    if (!isOurs(dir, plan.canonical)) return { ...target, state: "other" };
+    return { ...target, state: lstatSync(dir).isSymbolicLink() ? "linked" : "installed" };
+  });
+}

package/src/project.mjs

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { callTool, ColcoError } from "./api.mjs";
+
+/*
+ * `colco project`: which Colco projects use the code in this directory. It reads the git remote (origin,
+ * else the first remote) and the current branch, and asks Colco's find_projects_by_repository. Git runs
+ * through execFile with an argument list, never a shell, so nothing in a remote or branch name is executed.
+ */
+
+const NOT_A_REPOSITORY = "当前目录不是 git 仓库：请在代码目录中运行 colco project";
+
+/** Runs git with `args` in the current directory; resolves trimmed stdout, rejects with git's error. */
+export function runGit(args) {
+  return new Promise((resolve, reject) => {
+    execFile("git", args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(String(stdout).trim());
+    });
+  });
+}
+
+/**
+ * Removes `user:password@`, query and fragment from a URL-style remote, so no credential leaves the machine or
+ * reaches the screen. scp-style remotes (`git@host:path`) are left as they are; their user is not a secret.
+ */
+export function stripCredentials(remote) {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(remote)) return remote;
+  return remote.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/]*@/i, "$1").replace(/[?#].*$/, "");
+}
+
+/** The directory's remote URL and current branch (null when HEAD is detached or has no commit yet). */
+export async function readGitContext(git) {
+  let inside;
+  try {
+    inside = await git(["rev-parse", "--is-inside-work-tree"]);
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new ColcoError("没有找到 git 命令：请先安装 git");
+    throw new ColcoError(NOT_A_REPOSITORY);
+  }
+  if (inside !== "true") throw new ColcoError(NOT_A_REPOSITORY);
+  let remote = await git(["remote", "get-url", "origin"]).catch(() => "");
+  if (!remote) {
+    const [first] = (await git(["remote"]).catch(() => "")).split("\n").map((name) => name.trim()).filter(Boolean);
+    if (first) remote = await git(["remote", "get-url", "--", first]).catch(() => "");
+  }
+  if (!remote) throw new ColcoError("这个 git 仓库还没有远程地址（git remote），Colco 无法据此找到项目");
+  const head = await git(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "");
+  return { remote: stripCredentials(remote), branch: head && head !== "HEAD" ? head : null };
+}
+
+/** Prints the projects that use this directory's repository, or why there are none; `--json` prints the data. */
+export async function project(flags, io, connection) {
+  const { remote, branch } = await readGitContext(io.git);
+  const data = await callTool(connection, "find_projects_by_repository", { url: remote, ...(branch ? { branch } : {}) }, io.fetch);
+  if (flags.json) {
+    io.out(JSON.stringify({ remote, branch, ...data }, null, 2));
+    return 0;
+  }
+  io.out(`仓库：${data.repository?.url ?? remote}${branch ? `（当前分支 ${branch}）` : ""}`);
+  if (!data.repository) {
+    io.out("这个仓库还没有登记到 Colco，没有项目使用它。");
+    io.out("用 colco call list_projects 查看你的项目；项目负责人可以用 link_repository 把仓库关联到项目。");
+    return 0;
+  }
+  if (data.projects.length === 0) {
+    io.out(`仓库「${data.repository.name}」已登记，但你能访问的项目都没有使用它。`);
+    io.out("用 colco call list_projects 查看你的项目。");
+    return 0;
+  }
+  const idWidth = Math.max(...data.projects.map((item) => String(item.projectId).length));
+  const nameWidth = Math.max(...data.projects.map((item) => item.projectName.length));
+  for (const item of data.projects) {
+    const archived = item.projectStatus === "archived" ? "（已归档）" : "";
+    io.out(`${item.branchMatched ? "*" : " "} ${String(item.projectId).padStart(idWidth)}  ${item.projectName.padEnd(nameWidth)}  ${item.branch}${archived}`);
+  }
+  if (data.projects.some((item) => item.branchMatched)) io.out("* 项目使用的就是当前分支");
+  return 0;
+}