cofluxd 2.0.2 → 2.1.1

package/account-client.mjs

@@ -3,6 +3,50 @@ import fs from "node:fs";
 import net from "node:net";
 import { join } from "node:path";
 
+/* --------------------------------- 实体标识 -------------------------------- */
+// `coflux:<kind>:<hex>`：设备 / 项目 / 工作区 / 终端 ID 的可粘贴短形式，hex 是 ID 的前几位
+// （生成时固定取前 8 位）。解析大小写不敏感并归一成小写；凡是收 ID 的地方都收标识。
+//
+// 规则是纯拼接，故各端各自本地生成，不上协议：Rust 侧同一份规则在 crates/cli/src/handle.rs 与
+// crates/worker/src/handle.rs——两版 CLI 的输出是逐字对齐的契约，改一边必须改另一边。
+const HANDLE_KINDS = ["device", "project", "workspace", "terminal"];
+
+/** `id` 的标识。空进空出：缺坐标时不能造出 `coflux:x:` 这样的半截标识。 */
+export function entityHandle(kind, id) {
+  const raw = typeof id === "string" ? id : "";
+  return raw ? `coflux:${kind}:${raw.slice(0, 8).toLowerCase()}` : "";
+}
+
+/** 解析标识；不是标识（裸 UUID 也一样）返回 null，调用方按它看起来的那个 ID 处理。 */
+export function parseHandle(raw) {
+  if (typeof raw !== "string") return null;
+  const parts = raw.toLowerCase().split(":");
+  if (parts.length !== 3 || parts[0] !== "coflux") return null;
+  const [, kind, hex] = parts;
+  if (!HANDLE_KINDS.includes(kind) || !/^[0-9a-f]{4,32}$/.test(hex)) return null;
+  return { kind, prefix: hex };
+}
+
+/**
+ * `--device` / `--workspace` 筛选值命中某个 ID 吗？标识按类型 + 前缀比，其余按原样相等比。
+ * 这是**比较**不是解析：不查表，只用同一套语法——也正因为如此，标识绝不能漏到字符串相等那条
+ * 路上去，否则它谁也匹配不上，打印一个空列表还不报错。
+ */
+export function matchesTarget(target, id, kind) {
+  const handle = parseHandle(target);
+  if (!handle) return id === target;
+  return handle.kind === kind && typeof id === "string" && id.toLowerCase().startsWith(handle.prefix);
+}
+
+/** 筛选参数拿到了别的类型的标识：说清楚，不要打印空列表。不是标识的一律放行（那就是个 ID）。 */
+const HANDLE_LABELS = { device: "设备", project: "项目", workspace: "工作区", terminal: "终端" };
+export function checkFilterHandle(flag, expected, target) {
+  const handle = parseHandle(target);
+  if (handle && handle.kind !== expected) {
+    throw new Error(`--${flag} 需要${HANDLE_LABELS[expected]}标识或${HANDLE_LABELS[expected]} ID，给的是${HANDLE_LABELS[handle.kind]}标识 ${target}`);
+  }
+}
+
 function origin(raw) {
   const url = new URL(raw.replace(/^wss:/, "https:").replace(/^ws:/, "http:"));
   if (url.username || url.password) throw new Error("服务器地址不能包含凭据");
@@ -45,6 +89,22 @@ export async function runAccountCommand(positionals, flags, home) {
   const sessionPath = join(home, "cli-session.json");
   const required = (key) => { if (!flags[key]) throw new Error(`缺少 --${key}`); return flags[key]; };
   const target = () => { if (!id) throw new Error("缺少目标 ID"); return id; };
+  // `project import <path>`: the path is resolved on the **target device** (`~` expansion and
+  // `git rev-parse --show-toplevel` both happen there), so the CLI only checks its shape — the same
+  // rule as `device exec --cwd`. Expanding it here would resolve the caller's home on the wrong machine.
+  const importPath = () => {
+    const value = (id ?? "").trim();
+    if (!value) throw new Error('缺少要导入的路径（导入当前目录写 coflux project import "$PWD"）');
+    if (!(value.startsWith("/") || value === "~" || value.startsWith("~/"))) throw new Error('路径要绝对路径或 ~ 开头（它在目标设备上解析）；导入当前目录写 coflux project import "$PWD"');
+    return value;
+  };
+  // `--device` falls back to the daemon-issued COFLUX_DEVICE_ID; empty on both sides is an error,
+  // never a guess — silently importing onto the wrong machine is worse than failing.
+  const deviceTarget = () => {
+    const value = (flags.device || process.env.COFLUX_DEVICE_ID || "").trim();
+    if (!value) throw new Error("缺少设备：请加 --device <id>（coflux device list 可以看到）");
+    return value;
+  };
   const print = (value) => console.log(JSON.stringify(value));
   if (command === "login") {
     const server = origin(flags.server || "https://api.coflux.dev");
@@ -109,6 +169,9 @@ export async function runAccountCommand(positionals, flags, home) {
     process.exit(exitCode);
   }
   let operation;
+  if (command === "project") {
+    if (sub === "import") operation = { op: "project.import", daemonId: deviceTarget(), path: importPath(), ...(flags.name ? { name: flags.name } : {}) };
+  }
   if (command === "workspace") {
     if (sub === "new") operation = { op: "workspace.new", projectId: required("project"), branch: required("branch"), createNew: !flags["existing-branch"], ...(flags.name ? { name: flags.name } : {}) };
     if (sub === "rename") operation = { op: "workspace.rename", workspaceId: target(), name: required("name") };
@@ -124,12 +187,16 @@ export async function runAccountCommand(positionals, flags, home) {
     if (["stop", "remove"].includes(sub)) operation = { op: `terminal.${sub}`, terminalId: target() };
   }
   if (!operation && command !== "whoami" && command !== "ports" && sub !== "list") throw new Error("未知账号命令");
-  if (operation && (flags.device || (flags.workspace && operation.op !== "terminal.new"))) throw new Error("目标 ID 已确定作用范围，请不要附加设备或工作区筛选参数");
+  // `project.import` is addressed by device like `snapshot`, so `--device` is an input to it rather than a filter.
+  if (operation && ((flags.device && operation.op !== "project.import") || (flags.workspace && operation.op !== "terminal.new"))) throw new Error("目标 ID 已确定作用范围，请不要附加设备或工作区筛选参数");
   let value = await call(operation || { op: "snapshot" });
   if (command === "whoami") value = { accountId: value.accountId };
   else if (sub === "list" || command === "ports") {
     const field = { device: "devices", project: "projects", workspace: "workspaces", terminal: "terminals", ports: "ports" }[command];
-    value = value[field].filter((item) => (!flags.device || item.daemonId === flags.device) && (!flags.workspace || item.workspaceId === flags.workspace || (command === "workspace" && item.id === flags.workspace)));
+    // 客户端字符串比较，不经中心解析：标识不在这里认，就会一个都匹配不上（空列表、还不报错）。
+    if (flags.device) checkFilterHandle("device", "device", flags.device);
+    if (flags.workspace) checkFilterHandle("workspace", "workspace", flags.workspace);
+    value = value[field].filter((item) => (!flags.device || matchesTarget(flags.device, item.daemonId, "device")) && (!flags.workspace || matchesTarget(flags.workspace, item.workspaceId, "workspace") || (command === "workspace" && matchesTarget(flags.workspace, item.id, "workspace"))));
   }
   print(value);
 }

package/coflux.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // coflux：账号与本地、跨设备业务操作；不负责宿主生命周期。
-import { handlesAccountCommand, runAccountCommand } from "./account-client.mjs";
+import { entityHandle, handlesAccountCommand, runAccountCommand } from "./account-client.mjs";
 import { randomUUID } from "node:crypto";
 import { parseArgs } from "node:util";
 import { spawnSync } from "node:child_process";
@@ -206,6 +206,15 @@ function tailLines(text, n) {
   return lines.slice(-n).join("\n");
 }
 
+/**
+ * 一行终端的第一列：标识。daemon 已经在载荷里给了 `ref`；它没给（CLI 比 daemon 新）就按同一条
+ * 规则从 `taskId` 现算一个——生成规则是纯拼接，两边算出来的东西一样。
+ * 与 Rust 版 `row_handle`（crates/cli/src/commands.rs）逐字对齐。
+ */
+function rowHandle(t) {
+  return (typeof t.ref === "string" && t.ref) || entityHandle("terminal", t.taskId);
+}
+
 /** ` busy` / ` idle` plus ` last=<code>` for a live, instrumented terminal; nothing otherwise. */
 function commandSuffix(t) {
   if (!t.integrated) return "";
@@ -256,7 +265,7 @@ async function cmdTerminal(values) {
     if (!terminals.length) return void console.log("本工作区暂无终端");
     for (const t of terminals) {
       const exit = t.exitCode === undefined || t.exitCode === null ? "" : ` exit=${t.exitCode}`;
-      console.log(`${t.taskId}  ${t.status}${exit}${commandSuffix(t)}  ${t.title}`);
+      console.log(`${rowHandle(t)}  ${t.status}${exit}${commandSuffix(t)}  ${t.title}`);
     }
   } else if (sub === "read") {
     const taskId = positionals[2];
@@ -330,10 +339,14 @@ async function cmdWorkspace() {
   const sub = positionals[1];
   if (!sub) {
     const result = await agentPost({ action: "workspace.current" });
+    // ref / owningRef 原样透传：daemon 旧到不给就是 undefined，JSON.stringify 直接省掉这两个键
+    // （与 Rust 版 render_workspace_current 同序同省略规则）。
     return void console.log(JSON.stringify({
       workspaceId: result.workspaceId,
+      ref: result.ref,
       path: result.path,
       owningWorkspaceId: result.owningWorkspaceId,
+      owningRef: result.owningRef,
       moved: Boolean(result.moved),
     }));
   }
@@ -522,6 +535,11 @@ const HELP = `coflux —— 账号与终端操作
                           该 worktree 已被删掉：其下所有终端搬回项目主工作区、工作区记录消失
                           （不执行 git worktree remove）
 
+实体标识：设备 / 项目 / 工作区 / 终端的 ID 都可以写成 coflux:<kind>:<ID 前 8 位>，例如
+coflux:workspace:3f2a1b7c。凡是收 ID 的地方都收标识（大小写不敏感），返回实体的地方都带一个
+ref 字段给出它的标识。前缀在范围内撞车时会让你改用完整 ID；标识类型与命令要的不一致会直接报错，
+不会去动旁边那个实体。
+
 agent 命令的环境变量：COFLUX_AGENT_TIMEOUT_MS 收窄单次请求的等待上限（默认 30000，只能调小），
 供有硬超时的 hook 脚本用——到点干净失败，好过被宿主杀在半路。
 
@@ -537,6 +555,14 @@ agent 命令的环境变量：COFLUX_AGENT_TIMEOUT_MS 收窄单次请求的等
                           任何工作区。--cwd 默认 daemon 用户的 HOME，只接受绝对路径或 ~ 开头的路径；
                           --timeout 默认 60 秒、最长 600 秒；没有 stdin。要输密码、驱动 TUI，或想让
                           用户看见过程并能接管的长任务，用 coflux terminal new，不要用它
+  coflux project import <path> [--device <id>] [--name <名称>]
+                          把设备上的一个 git 仓库目录变成项目（路径在仓库里就导入仓库根），并
+                          建好它的主工作区；打印一行 JSON：projectId / name / repoPath /
+                          defaultBranch / workspaceId / path / alreadyImported。<path> 必填，
+                          只接受绝对路径或 ~ 开头的路径（它在目标设备上解析）——导入当前目录写
+                          coflux project import "$PWD"。--device 缺省取 COFLUX_DEVICE_ID。
+                          同一个仓库根导入第二次不会多出一个项目：返回已有的那个，
+                          alreadyImported=true
   coflux workspace new --project <id> --branch <分支> [--existing-branch]
   coflux workspace rename <id> --name <名称> | workspace remove <id>
   coflux terminal new --workspace <id> [--cmd <命令>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Coflux 无界面宿主（cofluxd）与统一操作工具（coflux）",
   "type": "module",
   "bin": {

package/skills/coflux/SKILL.md

@@ -59,6 +59,11 @@ env | grep '^COFLUX_'
   | `COFLUX_TASK_ID` | id of this terminal (the taskId / terminalId used by local commands and `read_terminal`) |
   | `COFLUX_SESSION_ID` | id of this PTY session |
 
+  Under those id lines the `<coflux-session>` block prints a `<Kind> handle:` line for the device,
+  project, workspace and terminal — the same ids in a short, typed, pasteable form (see "Entity
+  handles"). A PTY session has no handle, a coordinate that is empty contributes no line, and the
+  `COFLUX_*` variables themselves are always full UUIDs.
+
 - **Variables empty or absent**: there is no local terminal context. Use `coflux whoami` to check
   account access and the account CLI to discover workspaces. Ask the user to log in when needed;
   never fabricate COFLUX_* coordinates.
@@ -138,9 +143,9 @@ So, after entering or leaving a worktree, owning **and** effective are both the
 its id to account CLI commands and everything local already acts on it. The plugin drops the new id next to the
 tool result, and `coflux workspace` always tells you. Two things stay behind on purpose:
 
-- `COFLUX_WORKSPACE_ID` (and the id in the `<coflux-session>` block from earlier in this session)
-  still names where the terminal was *opened*; it is frozen when the PTY starts and cannot be
-  rewritten. Never reuse it after a move.
+- `COFLUX_WORKSPACE_ID` (and the workspace id and handle in the `<coflux-session>` block from
+  earlier in this session) still names where the terminal was *opened*; it is frozen when the PTY
+  starts and cannot be rewritten. Never reuse either form after a move.
 - The shell inside this terminal keeps its own directory. That is only about the shell; it does not
   affect where your work is attributed.
 
@@ -152,15 +157,75 @@ a daemon that is down or too old — the session just carries on with the owners
 
 ```sh
 coflux workspace
-{"workspaceId":"ws-b","path":"/Users/me/.coflux/worktrees/ws-b","owningWorkspaceId":"ws-a","moved":true}
+{"workspaceId":"3f2a1b7c-9d44-4e1a-8f02-1b6c2d5e7a90","ref":"coflux:workspace:3f2a1b7c","path":"/Users/me/.coflux/worktrees/ws-b","owningWorkspaceId":"7c1d90ab-5e33-4c88-9a71-0d4f8b2e6c15","owningRef":"coflux:workspace:7c1d90ab","moved":true}
 ```
 
 One line of JSON: `workspaceId` (+ `path`) is the **effective** workspace, `owningWorkspaceId` is the
-workspace this terminal belongs to right now, and `moved` says whether they differ. With the plugin
-installed you also get a `<coflux-session-moved>` block at the start of every prompt while the two
-differ — but that block only arrives with the **next** user prompt. **About to call an account command right
-after a `cd`? Run `coflux workspace` first** and use the `workspaceId` it prints; do not reuse
-`COFLUX_WORKSPACE_ID`.
+workspace this terminal belongs to right now, `ref` and `owningRef` are those two workspaces'
+handles (a daemon too old to send them leaves both keys out), and `moved` says whether they differ.
+With the plugin installed you also get a `<coflux-session-moved>` block at the start of every prompt
+while the two differ — but that block only arrives with the **next** user prompt. **About to call an
+account command right after a `cd`? Run `coflux workspace` first** and use the `workspaceId` it
+prints; do not reuse `COFLUX_WORKSPACE_ID`.
+
+## Entity handles: ids you can paste
+
+Every coflux entity also has a **handle**: one short string that says both "this is coflux" and
+"this is a device / project / workspace / terminal".
+
+```
+coflux:device:b6767697
+coflux:project:7a83f21e
+coflux:workspace:3f2a1b7c
+coflux:terminal:9e21c4d0
+```
+
+The grammar is `coflux:<kind>:<short>`. `<kind>` is one of `device`, `project`, `workspace` and
+`terminal`. `<short>` is the first 8 hexadecimal characters of the entity's UUID — its first
+dash-delimited group. Handles are always generated in lowercase and are read case-insensitively.
+There is nothing else encoded in one: no name, no timestamp, no device. UUIDs stay canonical; a
+handle is another way to *write* an id, not a replacement for it.
+
+**Anywhere an id is accepted, a handle is accepted.** That covers every account CLI command taking
+a device, project, workspace or terminal id, the `--device` / `--workspace` filters of the list
+commands, and every local terminal command taking a terminal id. `coflux terminal read
+coflux:terminal:9e21c4d0` and `coflux terminal read <that terminal's full UUID>` are the same call.
+
+**Anywhere an entity is returned, its handle comes back too**, in a `ref` field beside the
+entity's unchanged id field. The ids in JSON — `taskId`, `workspaceId`, `deviceId` — are still full
+UUIDs, and `ref` is the handle next to them; where one payload carries two ids of the same kind it
+gets two keys, as `coflux workspace` does with `ref` and `owningRef`. Local terminal results carry
+both as well, and their `taskId` is always the **resolved** UUID — never the handle you passed in,
+so it is safe to feed onward. The local `coflux terminal list` text rows lead with the handle, so
+the next command can be typed straight from what you just read.
+
+So when the user pastes you a `coflux:` string, you already know what kind of thing it names and
+can use it as-is — no listing, no guessing. Handles are made to be pasted rather than displayed:
+the desktop and iOS clients offer "copy handle" on the entity (right-click in the desktop sidebar
+and terminal tabs, long-press on iOS rows and terminal chips) and show no handle text otherwise.
+
+### When a handle does not resolve
+
+A handle is a prefix, so resolving one can fail in three distinct ways. Each is one readable
+sentence; what matters is which of the three you got:
+
+- **Nothing matches** — no entity of that kind, within the scope that command can see, starts with
+  that short id. The handle belongs to another account, to a workspace you are not in, or to
+  something that no longer exists. List and pick again; re-running the same string cannot help.
+- **More than one matches** — two entities of that kind share the short id, so nothing is acted on.
+  Use the full UUID instead. There is no "first match" fallback, and picking one yourself is
+  exactly what the error exists to prevent.
+- **Wrong kind** — the handle is well-formed but names a different kind than the command expects
+  (a workspace handle where a terminal id goes). The command fails rather than act on an adjacent
+  entity; the fix is a handle of the expected kind, never a retry.
+
+The scopes differ on purpose: account CLI commands resolve a handle among **the requesting
+account's** entities, while local terminal commands resolve it among the terminals of **the
+workspace your cwd is in** — the same boundary that already makes another workspace's terminal
+indistinguishable from one that does not exist.
+
+Handles need a daemon and a CLI new enough to know about them. An older one rejects a handle the
+way it rejects any unrecognised id; there, use the full UUID and tell the user to upgrade.
 
 ## When to open a terminal
 
@@ -266,9 +331,10 @@ coflux terminal read <taskId>             # the last 200 lines of the scrollback
 coflux terminal read <taskId> --lines=50
 ```
 
-`list` rows are `<taskId>  <state>[ exit=<code>][ busy|idle][ last=<code>]  <title>`: `running` /
-`exited` / `idle` is the terminal, `busy` or `idle` says whether a command is running in it right
-now, and `last=<code>` is the exit code of the last command that finished. `read` returns the tail
+`list` rows are `<handle>  <state>[ exit=<code>][ busy|idle][ last=<code>]  <title>`: the first
+column is the terminal's handle (see "Entity handles"), which every other terminal command accepts
+as its id; `running` / `exited` / `idle` is the terminal, `busy` or `idle` says whether a command is
+running in it right now, and `last=<code>` is the exit code of the last command that finished. `read` returns the tail
 of the terminal's **full scrollback** (well beyond one screen, up to the daemon's history limit),
 ANSI stripped, with a `# running` / `# exited exit=<code>` header. A freshly opened terminal can
 read back empty for a moment while the shell starts. Once the shell has exited only the last
@@ -400,7 +466,10 @@ there: the terminal is open all the same, use `read` and `send` with it; "busy"
 still running in that terminal, `wait` for it or `read` first; "unknown action terminal.run" = this
 machine's daemon is older than the CLI, tell the user to run `cofluxd update && cofluxd restart`
 (the terminal was opened as a plain shell, nothing was run); "daemon is not connected to the
-center" only appears on `new`/`list`/`ports`/`notify`, retry once it reconnects.
+center" only appears on `new`/`list`/`ports`/`notify`, retry once it reconnects. A terminal handle
+that names the wrong kind, or whose prefix matches more than one terminal in this workspace, has
+its own sentence each — see "When a handle does not resolve"; an unknown handle shares the
+"not in this workspace or does not exist" sentence above, on purpose.
 
 ## Account CLI: across workspaces and devices
 
@@ -412,6 +481,7 @@ never as a command argument. Account commands return JSON. A workspace ID identi
 coflux device list
 coflux device exec <deviceId> --cmd="<command>" [--cwd=<dir>] [--timeout=<seconds>]
 coflux project list --device <deviceId>
+coflux project import <path> [--device <deviceId>] [--name <name>]
 coflux workspace list --device <deviceId>
 coflux workspace new --project <projectId> --branch <branch>
 coflux terminal new --workspace <workspaceId> --title <title> [--cmd <command>]
@@ -437,6 +507,31 @@ Read before sending; stop immediately when the user takes over. If a write times
 result before retrying. Exiting the CLI does not stop its terminals. Delete workspaces through
 `coflux workspace remove` so the filesystem and workspace records stay consistent.
 
+### Turn a repository into a project
+
+```sh
+coflux project import "$PWD"
+coflux project import /srv/checkouts/api --device <deviceId> --name api
+```
+
+A repository that is not a project yet has no workspaces, so nothing else in this skill can reach
+it: `workspace new` needs a `projectId`. This is the command that creates one, without the user
+having to click Import in the desktop app.
+
+`<path>` is required and must be **absolute or start with `~/`** — it is resolved on the target
+device, so importing the current directory is written explicitly as `"$PWD"`. Any path inside the
+repository imports the repository root. `--device` selects the machine and defaults to
+`COFLUX_DEVICE_ID`; with neither, the command fails rather than guessing. `--name` overrides the
+project name, which otherwise comes from the git remote and falls back to the directory name.
+
+Success is one line of JSON: `projectId`, `name`, `repoPath`, `defaultBranch`, the main workspace's
+`workspaceId` and `path`, and `alreadyImported`. A repository root on a device has exactly one
+project, so importing the same repository twice returns the existing one with
+`alreadyImported: true` and creates nothing — re-running it is safe. Failures are one sentence and a
+non-zero exit: "不是 git 仓库" (the path is not inside a repository), "设备离线，无法执行该操作"
+(that device is not connected), and a submitted-but-unfinished import tells you to check
+`coflux project list`.
+
 ### Run one command on another machine
 
 ```sh