nx-kv 0.1.1

package/src/core/prompt.js

@@ -0,0 +1,60 @@
+// 终端交互输入。
+//
+// 只做一件 store 层不该管、但 CLI 必须有的事：**隐藏式读取密码**。
+// 不用第三方库——把 stdin 切到 raw 模式、逐字符读、自己回显掩码即可。
+import { createInterface } from 'node:readline';
+
+// 读取一行可见输入（用于非敏感内容）
+export async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// 读取一行**不回显**的输入（密码）。
+// stdin 不是 TTY（管道 / CI）时无法切 raw 模式，退回普通读取——
+// 此时密码会显示在终端里，但至少流程不中断。
+export async function askHidden(question) {
+  if (!process.stdin.isTTY) return ask(question);
+
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    let buf = '';
+    const onData = (ch) => {
+      switch (ch) {
+        case '\r':
+        case '\n':
+        case '': // Ctrl-D
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          resolve(buf.trim());
+          break;
+        case '': // Ctrl-C
+          stdin.setRawMode(false);
+          stdin.pause();
+          process.stdout.write('\n');
+          process.exit(130);
+          break;
+        case '': // Backspace
+        case '\b':
+          buf = buf.slice(0, -1);
+          break;
+        default:
+          // 忽略其他控制字符，避免方向键之类混进密码
+          if (ch >= ' ') buf += ch;
+      }
+    };
+    stdin.on('data', onData);
+  });
+}

package/src/index.js

@@ -0,0 +1,9 @@
+// 编程入口：供其他工具 / agent 以库方式调用。
+// 导出的是各模块的 service（业务真相源），不是 CLI/HTTP 壳。
+export * as config from './core/config.js';
+export * as kvapi from './core/kvapi.js';
+export * as errors from './core/errors.js';
+export * as todo from './modules/todo/service.js';
+
+export { ACTIONS, MODULES } from './runtime/registry.js';
+export { startServer } from './runtime/server.js';

package/src/modules/auth/index.js

@@ -0,0 +1,98 @@
+// 认证模块：登录 / 登出 / 查看登录态。
+//
+// 登录成功后**只把 token 写进本机配置**，密码不落盘、不进日志。
+// 所有需要 token 的模块都通过 core/config.js 的 requireAuth() 取，不各自读配置。
+import { loadConfig, updateConfig, saveConfig, requireAuth, configPathFromEnv } from '../../core/config.js';
+import { login as apiLogin, userInfo } from '../../core/kvapi.js';
+import { askHidden } from '../../core/prompt.js';
+import { badInput } from '../../core/errors.js';
+
+async function doLogin(ctx) {
+  const email = String(ctx.email || '').trim();
+  if (!email) throw badInput('邮箱不能为空');
+
+  // 密码来源优先级：--password（脚本用）> 交互式隐藏输入
+  let password = ctx.password;
+  if (!password) {
+    password = await askHidden(`请输入 ${email} 的密码: `);
+  }
+  if (!password) throw badInput('密码不能为空');
+
+  const { token, userId } = await apiLogin(email, password, { baseUrl: ctx.baseUrl });
+  await updateConfig({
+    token,
+    userId,
+    email,
+    ...(ctx.baseUrl ? { baseUrl: ctx.baseUrl } : {}),
+  });
+  return { email, userId, tokenSaved: true };
+}
+
+export default {
+  id: 'auth',
+  title: '认证（登录态）',
+  order: 10,
+  view: () => import('./view.jsx'),
+
+  actions: [
+    {
+      id: 'auth.login',
+      cli: ['auth', 'login'],
+      http: ['POST', '/api/auth/login'],
+      summary: '登录并保存 token 到本机配置',
+      args: ['email'],
+      flags: {
+        password: { type: 'string', hint: '密码（省略则交互式隐藏输入）' },
+        baseUrl: { type: 'string', hint: '后端地址，覆盖默认' },
+      },
+      run: doLogin,
+      render: (d) => `已登录: ${d.email}（userId=${d.userId}）\n配置: ${configPathFromEnv()}`,
+    },
+    {
+      id: 'auth.logout',
+      cli: ['auth', 'logout'],
+      http: ['POST', '/api/auth/logout'],
+      summary: '清除本机保存的 token',
+      run: async () => {
+        const before = await loadConfig();
+        // 只清登录态，保留 baseUrl 与当前工作空间选择
+        await saveConfig({ ...before, token: '', email: '', userId: 0 });
+        return { loggedOut: true, was: before.email || '' };
+      },
+      render: (d) => (d.was ? `已登出（原账号 ${d.was}）` : '本就未登录'),
+    },
+    {
+      id: 'auth.status',
+      cli: ['auth', 'status'],
+      http: ['GET', '/api/auth'],
+      summary: '查看本机登录态（不请求后端，离线可用）',
+      run: async () => {
+        const cfg = await loadConfig();
+        return {
+          loggedIn: !!cfg.token,
+          email: cfg.email,
+          userId: cfg.userId,
+          baseUrl: cfg.baseUrl,
+          groupId: cfg.groupId,
+          configPath: configPathFromEnv(),
+        };
+      },
+      render: (d) =>
+        d.loggedIn
+          ? `已登录: ${d.email}（userId=${d.userId}）\n后端: ${d.baseUrl}\n工作空间: ${d.groupId > 0 ? d.groupId : '默认组'}`
+          : `未登录（nx-kv auth login <email>）\n后端: ${d.baseUrl}`,
+    },
+    {
+      id: 'auth.me',
+      cli: ['auth', 'me'],
+      http: ['GET', '/api/auth/me'],
+      summary: '向后端确认身份（验证 token 是否仍有效）',
+      run: async () => {
+        await requireAuth();
+        const info = await userInfo();
+        return info ?? { ok: true };
+      },
+      render: (d) => JSON.stringify(d, null, 2),
+    },
+  ],
+};

package/src/modules/auth/view.jsx

@@ -0,0 +1,78 @@
+// 登录页：填邮箱密码登录，显示当前登录态与后端地址。
+// 密码只在提交时用一次，不进 localStorage、不写日志。
+import { useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { useStore } from '../../web/frontend/store.jsx';
+import { useToast, useGuard, Copyable } from '../../web/frontend/components/ui.jsx';
+import { CliHints } from '../../web/frontend/components/CliHints.jsx';
+
+export default function AuthView() {
+  const { boot, refreshBoot } = useStore();
+  const toast = useToast();
+  const guard = useGuard();
+  const [email, setEmail] = useState(boot?.email || '');
+  const [password, setPassword] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  const login = () => guard(async () => {
+    if (!email.trim()) { toast('请填邮箱'); return; }
+    if (!password) { toast('请填密码'); return; }
+    setBusy(true);
+    try {
+      const r = await api('/api/auth/login', { method: 'POST', body: { email: email.trim(), password } });
+      setPassword(''); // 用完即清，不留在组件状态里
+      toast(`已登录: ${r.email}`);
+      await refreshBoot();
+    } finally {
+      setBusy(false);
+    }
+  });
+
+  const logout = () => guard(async () => {
+    await api('/api/auth/logout', { method: 'POST' });
+    toast('已登出');
+    await refreshBoot();
+  });
+
+  return (
+    <>
+      <div className="card">
+        <div className="colhead">
+          <h3>登录态</h3>
+          <span className={boot?.loggedIn ? 'tag strong' : 'tag bad'}>
+            {boot?.loggedIn ? '已登录' : '未登录'}
+          </span>
+        </div>
+        <div className="settings">
+          <dt>账号</dt>
+          <dd>{boot?.email || <span className="muted">（未登录）</span>}</dd>
+          <dt>userId</dt>
+          <dd>{boot?.userId || '-'}</dd>
+          <dt>后端</dt>
+          <dd className="mono"><Copyable text={boot?.baseUrl}>{boot?.baseUrl}</Copyable></dd>
+          <dt>本机配置</dt>
+          <dd className="mono"><Copyable text={boot?.configPath}>{boot?.configPath}</Copyable></dd>
+        </div>
+      </div>
+
+      <div className="card">
+        <div className="colhead"><h3>{boot?.loggedIn ? '切换账号' : '登录'}</h3></div>
+        <div className="row-inline" style={{ padding: 12 }}>
+          <input placeholder="邮箱" size="24" spellCheck="false" value={email}
+            onChange={(e) => setEmail(e.target.value)} />
+          <input placeholder="密码" type="password" size="18" value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            onKeyDown={(e) => { if (e.key === 'Enter') login(); }} />
+          <button className="btn" onClick={login} disabled={busy}>{busy ? '登录中…' : '登录'}</button>
+          {boot?.loggedIn ? <button className="btn ghost danger" onClick={logout}>登出</button> : null}
+        </div>
+        <div className="muted" style={{ padding: '0 12px 12px', fontSize: 12 }}>
+          密码只用于本次请求，不写入本机配置；配置里只保存 token。
+          也可以用 CLI：<code>nx-kv auth login &lt;email&gt;</code>（会交互式隐藏输入密码）。
+        </div>
+      </div>
+
+      <CliHints module="auth" />
+    </>
+  );
+}

package/src/modules/bundled/index.js

@@ -0,0 +1,51 @@
+// 内置 skill 包模块：把随包发布的 nx-kv 说明装到用户的 skills 目录。
+// 没有面板视图——安装入口在 Skill 页，列出/安装都通过 action 暴露。
+import * as service from './service.js';
+
+export default {
+  id: 'bundled',
+  title: '内置 skill 包',
+  order: 50,
+  view: null,
+
+  actions: [
+    {
+      id: 'bundled.list',
+      // 第二条是历史别名：`skill install --list` 早于 `bundled list` 存在，
+      // 命令路径里带 flag，因此匹配是按 token 前缀而非「非 flag 前缀」。
+      cli: [['bundled', 'list'], ['skill', 'install', '--list']],
+      http: ['GET', '/api/bundled'],
+      summary: '列出包内自带 skill（含文件数与描述）',
+      // 两端返回结构刻意不同：HTTP 供面板顺带拿到默认安装目录；
+      // CLI 的 --json 保持纯数组的历史形状，不破坏已在消费它的 agent。
+      run: async (_ctx, meta) => {
+        const skills = await service.listBundledSkills();
+        return meta.transport === 'http'
+          ? { defaultDir: service.DEFAULT_SKILLS_DIR, skills }
+          : skills;
+      },
+      render: (l) =>
+        l.length
+          ? l.map((s) => `${s.name.padEnd(14)} ${s.files} 个文件  ${s.description.slice(0, 50)}`).join('\n')
+          : '（包内无内置 skill）',
+    },
+    {
+      id: 'bundled.install',
+      cli: ['skill', 'install'],
+      http: ['POST', '/api/bundled/install'],
+      summary: '安装内置 skill 到 skills 目录（默认 nx-kv → ~/.claude/skills）',
+      args: [{ name: 'name', required: false }],
+      flags: { to: { type: 'string' }, force: { type: 'boolean' } },
+      run: (ctx) =>
+        service.installBundledSkill({ name: ctx.name || 'nx-kv', to: ctx.to, force: ctx.force }),
+      render: (d) => {
+        if (d.status === 'conflict') {
+          const files = d.files.map((f) => `  ${f.file}  ${f.side}`).join('\n');
+          return `目标已存在且内容不同（${d.count} 个文件）: ${d.path}\n${files}\n用 --force 覆盖，或先删除目标目录`;
+        }
+        if (d.skipped) return `已是最新，无需安装: ${d.path}`;
+        return `${d.replaced ? '已更新' : '已安装'} ${d.name}（${d.files} 个文件）-> ${d.path}`;
+      },
+    },
+  ],
+};

package/src/modules/bundled/service.js

@@ -0,0 +1,80 @@
+// 内置 skill 包：随 nx-kv 一起发布的 assets/<name>/（SKILL.md + references/…）
+// 负责列出与安装到用户/项目的 skills 目录，供 agent 一键获得 nx-kv 的使用说明。
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fsp from 'node:fs/promises';
+import { diffTrees } from '../../core/fstree.js';
+import { parseFrontmatter } from '../../core/frontmatter.js';
+import { assertSafeName } from '../../core/paths.js';
+import { notFound } from '../../core/errors.js';
+
+// assets/ 在包根，src/modules/bundled/ 的上三级
+const ASSETS_DIR = fileURLToPath(new URL('../../../assets/', import.meta.url));
+
+// 默认安装到 Claude Code 的用户级 skills 目录
+export const DEFAULT_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+
+async function pathExists(p) {
+  try {
+    await fsp.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function assetsDir() {
+  return ASSETS_DIR;
+}
+
+// 列出包内自带的所有 skill（含文件数与描述）
+export async function listBundledSkills() {
+  const out = [];
+  const entries = await fsp.readdir(ASSETS_DIR, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const dir = join(ASSETS_DIR, e.name);
+    // 用不存在的路径当哨兵，diffTrees 会把包内文件全列为 only-central，等于列出文件清单
+    const files = await diffTrees(dir, join(dir, '__nx_rh_missing__'));
+    if (!files.length) continue;
+
+    // 描述解析复用 core/frontmatter.js —— 这里原本抄了一份简化正则，
+    // 于是 CRLF / 块标量 / 引号的处理与 skills 侧并不一致。
+    const md = await fsp.readFile(join(dir, 'SKILL.md'), 'utf8').catch(() => null);
+    const description = md ? parseFrontmatter(md).description : '';
+    out.push({ name: e.name, dir, files: files.length, description });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// 安装内置 skill 到目标 skills 目录（默认 ~/.claude/skills）
+// 返回 { status: 'ok' | 'conflict', ... }——已存在且内容不同是**业务结果**，
+// 需要用户决定是否覆盖，不是错误。
+export async function installBundledSkill({ name = 'nx-kv', to, force } = {}) {
+  name = assertSafeName(name);
+  const src = join(ASSETS_DIR, name);
+  if (!(await pathExists(join(src, 'SKILL.md')))) {
+    const available = (await listBundledSkills()).map((s) => s.name).join(', ') || '(无)';
+    throw notFound(`未找到内置 skill: ${name}（可用: ${available}）`);
+  }
+
+  const targetRoot = resolve(to || DEFAULT_SKILLS_DIR);
+  const dst = join(targetRoot, name);
+  const files = await diffTrees(src, dst); // side: only-central=新增, both-differ=不同, only-project=多余
+
+  if (!files.length) {
+    return { status: 'ok', skipped: true, name, path: dst, files: 0 };
+  }
+
+  const exists = await pathExists(dst);
+  if (exists && !force) {
+    return { status: 'conflict', name, path: dst, files, count: files.length };
+  }
+
+  if (exists) await fsp.rm(dst, { recursive: true, force: true });
+  await fsp.mkdir(targetRoot, { recursive: true });
+  await fsp.cp(src, dst, { recursive: true, dereference: true, force: true });
+
+  return { status: 'ok', installed: !exists, replaced: exists, name, path: dst, files: files.length };
+}

package/src/modules/group/index.js

@@ -0,0 +1,199 @@
+// 工作空间（group）模块：完整 CRUD + 切换 + 成员查看。
+//
+// 后端实际支持：`POST /groups`（建）、`GET /groups`（列）、`PATCH /groups/:id`（改）、
+// `DELETE /groups/:id`（解散）、`GET /groups/:id/members`（成员）。
+// 所以这是一个**集合资源**，声明 `resource: 'group'` —— 五个 CRUD 操作齐备且两端可达，
+// tests/unit/registry.test.mjs 会据此断言。
+//
+// `current` / `use` / `members` 不是 CRUD，用动作动词命名。
+//
+// 切换是**本机态**：只改 ~/.nx-kv/config.json 的 groupId，不动服务端任何数据。
+// 之后所有 todo 读写都带上它，后端按 groupId 隔离。
+import { loadConfig, updateConfig, requireAuth } from '../../core/config.js';
+import {
+  listGroups,
+  createGroup,
+  updateGroup,
+  deleteGroup,
+  listGroupMembers,
+} from '../../core/kvapi.js';
+import { badInput, notFound } from '../../core/errors.js';
+
+// 纯文本渲染用：把一行的关键信息摆齐
+const renderGroupLine = (g, current) =>
+  `${current ? '*' : ' '} ${String(g.id).padStart(4)}  ${g.name.padEnd(14)}  ${(g.myRole || '').padEnd(6)}  ${g.memberCount} 人  ${g.description || ''}`;
+
+// 按 id 或名字定位。后端没有「取单个组」的接口，所以从列表里找。
+async function findGroup(locator) {
+  const s = String(locator ?? '').trim();
+  if (!s) throw badInput('必须给出工作空间 id 或名称（nx-kv group list 可查看）');
+  const groups = await listGroups();
+  const hit = /^\d+$/.test(s)
+    ? groups.find((g) => g.id === Number(s))
+    : groups.find((g) => g.name.toLowerCase() === s.toLowerCase());
+  if (!hit) {
+    throw notFound(`工作空间不存在或无权访问: ${s}（nx-kv group list 查看可用项）`);
+  }
+  return hit;
+}
+
+export default {
+  id: 'group',
+  title: '工作空间（= Web「工作空间」页）',
+  order: 20,
+  view: () => import('./view.jsx'),
+
+  // 集合资源：建 / 查（列表、单条）/ 改 / 散 都齐备
+  resource: 'group',
+
+  actions: [
+    // ─── CRUD 五操作 ───────────────────────────────────────────
+    {
+      id: 'group.list',
+      cli: ['group', 'list'],
+      http: ['GET', '/api/groups'],
+      summary: '列出我的工作空间（* 为当前）',
+      run: async () => {
+        await requireAuth();
+        const [groups, cfg] = await Promise.all([listGroups(), loadConfig()]);
+        return {
+          current: cfg.groupId,
+          groups: groups.map((g) => ({ ...g, current: g.id === cfg.groupId })),
+        };
+      },
+      render: (d) => {
+        if (!d.groups.length) return '（没有可用工作空间）';
+        return d.groups.map((g) => renderGroupLine(g, g.current)).join('\n');
+      },
+    },
+    {
+      id: 'group.get',
+      cli: ['group', 'get'],
+      http: ['GET', '/api/groups/:id'],
+      summary: '查看单个工作空间',
+      args: ['id'],
+      run: async (ctx) => {
+        await requireAuth();
+        const g = await findGroup(ctx.id);
+        const cfg = await loadConfig();
+        return { ...g, current: g.id === cfg.groupId };
+      },
+      render: (g) =>
+        [
+          `${g.name}${g.current ? '  ← 当前' : ''}`,
+          `  id:     ${g.id}`,
+          `  角色:   ${g.myRole || '-'}`,
+          `  成员:   ${g.memberCount} 人`,
+          `  描述:   ${g.description || '-'}`,
+          `  创建:   ${String(g.createdAt || '').slice(0, 10) || '-'}`,
+        ].join('\n'),
+    },
+    {
+      id: 'group.add',
+      cli: ['group', 'add'],
+      http: ['POST', '/api/groups'],
+      summary: '新建工作空间',
+      args: ['name'],
+      flags: { description: { type: 'string', hint: '描述' } },
+      run: async (ctx) => {
+        await requireAuth();
+        return createGroup({ name: ctx.name, description: ctx.description });
+      },
+      render: (g) => `已新建工作空间: ${g.name}（id=${g.id}）\n用 nx-kv group use ${g.id} 切过去`,
+    },
+    {
+      id: 'group.update',
+      cli: ['group', 'update'],
+      http: ['PATCH', '/api/groups/:id'],
+      summary: '改名 / 改描述（只改传入的字段）',
+      args: ['id'],
+      flags: {
+        name: { type: 'string', hint: '新名称' },
+        description: { type: 'string', hint: '新描述' },
+      },
+      run: async (ctx) => {
+        await requireAuth();
+        const g = await findGroup(ctx.id); // 支持按名字定位，再拿真实 id
+        return updateGroup(g.id, { name: ctx.name, description: ctx.description });
+      },
+      render: (g) => `已更新工作空间: ${g.name}（id=${g.id}）`,
+    },
+    {
+      id: 'group.remove',
+      cli: ['group', 'remove'],
+      http: ['DELETE', '/api/groups/:id'],
+      summary: '解散工作空间（后端要求组内已无 KV）',
+      args: ['id'],
+      run: async (ctx) => {
+        await requireAuth();
+        const g = await findGroup(ctx.id);
+        const cfg = await loadConfig();
+        if (g.id === cfg.groupId) {
+          // 解散当前空间会导致后续所有读写打到一个不存在的组上，先拦住
+          throw badInput(`不能解散当前正在使用的工作空间（${g.name}），先 nx-kv group use default 切走`);
+        }
+        await deleteGroup(g.id);
+        return { id: g.id, name: g.name };
+      },
+      render: (d) => `已解散工作空间: ${d.name}（id=${d.id}）`,
+    },
+
+    // ─── 非 CRUD：切换与成员 ───────────────────────────────────
+    {
+      id: 'group.current',
+      cli: ['group', 'current'],
+      http: ['GET', '/api/group'],
+      summary: '查看当前工作空间',
+      run: async () => {
+        const cfg = await loadConfig();
+        if (!cfg.groupId) return { id: 0, name: '默认组' };
+        // 名字是尽力而为：后端不可达时不该让「看当前是什么」失败
+        const groups = await listGroups().catch(() => []);
+        const hit = groups.find((g) => g.id === cfg.groupId);
+        return { id: cfg.groupId, name: hit ? hit.name : `#${cfg.groupId}` };
+      },
+      render: (d) => `当前工作空间: ${d.name}（${d.id === 0 ? '默认组，不传 groupId' : 'id=' + d.id}）`,
+    },
+    {
+      id: 'group.use',
+      cli: [['group', 'use'], ['group', 'switch']],
+      http: ['POST', '/api/group'],
+      summary: '切换当前工作空间（id 或名称；0 / default 回默认组）',
+      args: ['locator'],
+      run: async (ctx) => {
+        await requireAuth();
+        const s = String(ctx.locator ?? '').trim();
+        if (s === '0' || s.toLowerCase() === 'default') {
+          await updateConfig({ groupId: 0 });
+          return { id: 0, name: '默认组' };
+        }
+        const g = await findGroup(s);
+        await updateConfig({ groupId: g.id });
+        return g;
+      },
+      render: (d) =>
+        d.id === 0
+          ? '已切回默认组（后续读写不传 groupId）'
+          : `已切换到工作空间: ${d.name}（id=${d.id}）`,
+    },
+    {
+      id: 'group.members',
+      cli: ['group', 'members'],
+      http: ['GET', '/api/groups/:id/members'],
+      summary: '查看工作空间成员',
+      args: ['id'],
+      run: async (ctx) => {
+        await requireAuth();
+        const g = await findGroup(ctx.id);
+        return { group: { id: g.id, name: g.name }, members: await listGroupMembers(g.id) };
+      },
+      render: (d) => {
+        if (!d.members.length) return `${d.group.name}: （没有成员）`;
+        const w = Math.max(...d.members.map((m) => m.email.length));
+        return d.members
+          .map((m) => `  ${m.email.padEnd(w)}  ${m.role.padEnd(8)}  ${m.nickname}`)
+          .join('\n');
+      },
+    },
+  ],
+};