agentkit-dsh-plugin 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# agentkit-dsh-plugin
 
-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.
+> DeepSeek Harness 插件：**项目自包含**的 lifecycle hooks —— 配置随仓库走，
+> 按会话 cwd 发现，不需要为每个项目改宿主目录。
+
+## 它做什么
+
+在 DSH 的两个执行缝（`tools/pre-execute` / `tools/post-execute`）上跑命令钩子：
+
+- **配置按会话 cwd 发现**：`<项目>/.agent/hooks/hooks.json`（CC 方言），
+  其次 `.claude/settings.json`、`.claude/hooks.json`；无配置 = 静默跳过
+- **退出码语义**：`PreToolUse` 任何非零 → **阻断**（deny）；`PostToolUse` → 只记录
+- 配置坏掉**报错**，不会伪装成"没有配置"（否则等于静默放行）
+- payload 走 stdin（`{event, hookId, toolName, args, sessionId, cwd}`），
+  env 含 `CLAUDE_PROJECT_DIR` / `DSH_HOOK_ID` / `DSH_SESSION_ID`
+
+## 安装（宿主侧，显式部署动作）
+
+```bash
+# 装进某个 profile（会写 ~/.dsh/profiles/<p>/package.json + node_modules）
+pnpm add agentkit-dsh-plugin --dir ~/.dsh/profiles/web
+# 或用 agentkit 的落地命令（幂等、带备份与审计）
+dsh-landing install --home ~/.dsh --profile web
+```
+
+条目本身由 bundle 自带的 `cordis.patch.yml` 插入；`dsh-landing rollback` 可撤销。
+
+## 项目侧
+
+项目里**零改动**：agentkit 的 `dsh` 适配器会生成 `.agent/hooks/hooks.json`。
+想手写也可以，CC 方言即可。
+
+## 版本跟随
+
+```
+0.0.x  ↔  DeepSeek Harness 0.2.x
+seam：tools/pre-execute · tools/post-execute · ctx.shell
+```
+
+设计与论证见 agentkit 仓的 `docs/design/0001`（为什么自己做）与 `0002`（Target 模型）。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# DSH profile bundle patch:把本插件的 loader 行插进 profile。
+# 目标 id 由我们自己定,便于 profile patch 定向覆盖(如 configFile)。
+- insert:
+    - id: project-hooks
+      name: "agentkit-dsh-plugin"

package/dist/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/install.ts
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+var ROW_ID = "project-hooks";
+var ROW_NAME = "agentkit-dsh-plugin";
+var STATE_DIR = ".agentkit-landing";
+function landingPaths(home2, profile2) {
+  const patch = join(home2, "profiles", profile2, "cordis.patch.yml");
+  return { home: home2, profile: profile2, patch, stateDir: join(home2, "profiles", profile2, STATE_DIR) };
+}
+function rowPresent(patchText) {
+  return patchText.includes(`id: ${ROW_ID}`) || patchText.includes(ROW_NAME);
+}
+function renderRow(configFile2) {
+  const lines = [`- id: ${ROW_ID}`, `  name: ${ROW_NAME}`];
+  if (configFile2 !== void 0) {
+    lines.push("  config:", `    configFile: ${configFile2}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function audit(paths, action, detail) {
+  mkdirSync(paths.stateDir, { recursive: true });
+  const rec = { at: (/* @__PURE__ */ new Date()).toISOString(), action, profile: paths.profile, ...detail };
+  appendFileSync(join(paths.stateDir, "ledger.jsonl"), `${JSON.stringify(rec)}
+`, "utf8");
+}
+function install(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(join(opts.home, "profiles", opts.profile))) {
+    return { ok: false, changed: false, path: paths.patch, reason: `profile not found: ${opts.home}/profiles/${opts.profile}` };
+  }
+  if (!existsSync(paths.patch)) {
+    mkdirSync(paths.stateDir, { recursive: true });
+    writeFileSync(paths.patch, `${renderRow(opts.configFile)}`, "utf8");
+    audit(paths, "install", { backup: null, configFile: opts.configFile ?? null, created: true });
+    return { ok: true, changed: true, path: paths.patch, reason: "created" };
+  }
+  const before = readFileSync(paths.patch, "utf8");
+  if (rowPresent(before)) {
+    audit(paths, "install-noop", { reason: "already present" });
+    return { ok: true, changed: false, path: paths.patch, reason: "already present" };
+  }
+  mkdirSync(paths.stateDir, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backup = join(paths.stateDir, `backup-${stamp}.yml`);
+  copyFileSync(paths.patch, backup);
+  const next = before.endsWith("\n") || before === "" ? `${before}${renderRow(opts.configFile)}` : `${before}
+${renderRow(opts.configFile)}`;
+  writeFileSync(paths.patch, next, "utf8");
+  audit(paths, "install", { backup, configFile: opts.configFile ?? null });
+  return { ok: true, changed: true, path: paths.patch, backup };
+}
+function rollback(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(paths.stateDir)) {
+    return { ok: false, changed: false, path: paths.patch, reason: "no state directory \u2014 nothing to roll back" };
+  }
+  const backups = readdirSync(paths.stateDir).filter((f) => f.startsWith("backup-") && f.endsWith(".yml")).sort();
+  const last = backups.at(-1);
+  if (last === void 0) {
+    return { ok: false, changed: false, path: paths.patch, reason: "no backup recorded" };
+  }
+  copyFileSync(join(paths.stateDir, last), paths.patch);
+  audit(paths, "rollback", { restoredFrom: last });
+  return { ok: true, changed: true, path: paths.patch, backup: join(paths.stateDir, last) };
+}
+function status(opts) {
+  const paths = landingPaths(opts.home, opts.profile);
+  if (!existsSync(paths.patch)) {
+    return { ok: true, installed: false, path: paths.patch, backups: [] };
+  }
+  const text = readFileSync(paths.patch, "utf8");
+  const m = new RegExp(`configFile:\\s*(\\S+)`).exec(text);
+  const backups = existsSync(paths.stateDir) ? readdirSync(paths.stateDir).filter((f) => f.startsWith("backup-")).sort() : [];
+  return { ok: true, installed: rowPresent(text), path: paths.patch, backups, ...m?.[1] !== void 0 ? { configFile: m[1] } : {} };
+}
+function readProfileJson(home2, profile2) {
+  const p = join(home2, "profiles", profile2, "package.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function installBundle(opts) {
+  const profileDir = join(opts.home, "profiles", opts.profile);
+  if (!existsSync(join(opts.home, "profiles", opts.profile))) {
+    return { ok: false, added: false, alreadyInstalled: false, error: `profile not found: ${profileDir}` };
+  }
+  const pkg = readProfileJson(opts.home, opts.profile);
+  if (pkg === null) return { ok: false, added: false, alreadyInstalled: false, error: `cannot read ${join(profileDir, "package.json")}` };
+  const deps = pkg.dependencies ?? {};
+  const dsh = pkg.dsh ?? {};
+  const bundles = dsh.profile?.bundles ?? [];
+  const installed = Object.keys(deps).some((k) => k === ROW_NAME) || bundles.includes(ROW_NAME);
+  if (installed) return { ok: true, added: false, alreadyInstalled: true };
+  if (opts.skipPackageManager !== true) {
+    const pm = resolvePnpm();
+    if (pm === null) {
+      return {
+        ok: false,
+        added: false,
+        alreadyInstalled: false,
+        error: "pnpm not found (tried PATH, ~/.local/share/pnpm/pnpm, npx). Install pnpm, or rerun with --skip-pnpm and install the package into the profile by hand."
+      };
+    }
+    const r = spawnSync(pm, ["add", opts.from], { cwd: profileDir, encoding: "utf8", timeout: 18e4 });
+    if (r.status !== 0) {
+      const detail = [r.error?.message, r.stdout, r.stderr].filter((x) => typeof x === "string").join("\n").trim();
+      return { ok: false, added: false, alreadyInstalled: false, error: `${pm} add failed (exit ${String(r.status)})
+${detail.slice(-600)}` };
+    }
+  }
+  const next = {
+    ...pkg,
+    dependencies: { ...deps, [ROW_NAME]: opts.skipPackageManager === true ? "file:." : opts.from },
+    dsh: { ...dsh, profile: { ...dsh.profile ?? {}, bundles: [...bundles, ROW_NAME] } }
+  };
+  writeFileSync(join(profileDir, "package.json"), `${JSON.stringify(next, null, 2)}
+`, "utf8");
+  audit(landingPaths(opts.home, opts.profile), "install-bundle", { from: opts.from });
+  return { ok: true, added: true, alreadyInstalled: false };
+}
+function resolvePnpm() {
+  const candidates = ["pnpm", join(homedirPath(), ".local/share/pnpm/pnpm")];
+  for (const c of candidates) {
+    const probe = spawnSync(c, ["--version"], { encoding: "utf8", timeout: 15e3 });
+    if (probe.status === 0) return c;
+  }
+  const viaNpx = spawnSync("npx", ["--no-install", "pnpm", "--version"], { encoding: "utf8", timeout: 2e4 });
+  if (viaNpx.status === 0) return "npx pnpm";
+  return null;
+}
+function homedirPath() {
+  try {
+    return homedir();
+  } catch {
+    return process.env.HOME ?? "";
+  }
+}
+
+// src/cli.ts
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (err) => {
+    if (err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
+}
+var USAGE = `dsh-landing <install|rollback|status> [--profile <name>] [--home <path>] [--configFile <abs>]
+
+  install    \u628A\u63D2\u4EF6\u6761\u76EE\u8FFD\u52A0\u8FDB <home>/profiles/<profile>/cordis.patch.yml\uFF08\u5E42\u7B49\uFF1B\u5199\u524D\u5907\u4EFD\uFF09
+  rollback   \u6062\u590D\u6700\u8FD1\u4E00\u6B21\u5907\u4EFD\uFF08\u64A4\u9500\u6211\u4EEC\u8FFD\u52A0\u7684\u6761\u76EE\uFF0C\u4E0D\u52A8\u522B\u4EBA\u7684\u5185\u5BB9\uFF09
+  status     \u62A5\u544A\u662F\u5426\u5DF2\u5B89\u88C5\u3001\u5907\u4EFD\u6570\u3001configFile
+
+\u5BBF\u4E3B\u6539\u52A8\u662F**\u663E\u5F0F\u90E8\u7F72\u52A8\u4F5C**\uFF1A\u6BCF\u6B21\u52A8\u4F5C\u5199\u5BA1\u8BA1\u5230 <profile>/.agentkit-landing/ledger.jsonl\u3002`;
+function flag(args2, name) {
+  const i = args2.indexOf(`--${name}`);
+  return i >= 0 ? args2[i + 1] : void 0;
+}
+var args = process.argv.slice(2);
+var cmd = args[0];
+if (cmd === void 0 || cmd === "--help" || cmd === "-h") {
+  process.stdout.write(`${USAGE}
+`);
+  process.exit(cmd === void 0 ? 1 : 0);
+}
+var home = flag(args, "home") ?? process.env.DSH_HOME ?? join2(homedir2(), ".dsh");
+var profile = flag(args, "profile") ?? "web";
+var configFile = flag(args, "configFile");
+if (cmd === "install") {
+  const from = flag(args, "from");
+  if (from !== void 0) {
+    const b = installBundle({
+      home,
+      profile,
+      from,
+      ...args.includes("--skip-pnpm") ? { skipPackageManager: true } : {}
+    });
+    if (!b.ok) {
+      process.stderr.write(`dsh-landing: bundle install failed \u2014 ${b.error}
+`);
+      process.exit(1);
+    }
+    process.stdout.write(
+      b.alreadyInstalled ? `dsh-landing: plugin already installed in profile ${profile}
+` : `dsh-landing: plugin installed into ${home}/profiles/${profile}/node_modules and registered in dsh.profile.bundles
+`
+    );
+  }
+  if (from !== void 0 && configFile === void 0) {
+    process.stdout.write("  row:      provided by the bundle's own cordis.patch.yml (no override needed)\n");
+    process.exit(0);
+  }
+  const r = install({ home, profile, ...configFile !== void 0 ? { configFile } : {} });
+  if (!r.ok) {
+    process.stderr.write(`dsh-landing: install failed \u2014 ${r.reason}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`dsh-landing: ${r.changed ? "installed" : "already present"} \u2192 ${r.path}
+`);
+  if (r.backup !== void 0) process.stdout.write(`  backup: ${r.backup}
+`);
+  if (r.changed) {
+    process.stdout.write("  next: restart DSH (or /hooks-reload) \u2014 \u63D2\u4EF6\u6761\u76EE\u9700\u8981 profile \u91CD\u65B0\u5408\u6210\u624D\u751F\u6548\n");
+    process.stdout.write("  undo: dsh-landing rollback\n");
+  }
+} else if (cmd === "rollback") {
+  const r = rollback({ home, profile });
+  if (!r.ok) {
+    process.stderr.write(`dsh-landing: rollback failed \u2014 ${r.reason}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`dsh-landing: rolled back ${r.path} from ${r.backup}
+`);
+} else if (cmd === "status") {
+  const s = status({ home, profile });
+  const p = landingPaths(home, profile);
+  process.stdout.write(`dsh-landing: profile ${profile} (${home}/profiles/${profile})
+`);
+  process.stdout.write(`  installed: ${s.installed ? "yes" : "no"}
+`);
+  process.stdout.write(`  patch:     ${s.path}
+`);
+  process.stdout.write(`  configFile:${s.configFile ?? " (project-discovered default)"}
+`);
+  process.stdout.write(`  backups:   ${s.backups.length}
+`);
+  process.stdout.write(`  audit:     ${join2(p.stateDir, "ledger.jsonl")}
+`);
+} else {
+  process.stderr.write(`dsh-landing: unknown command ${cmd}
+
+${USAGE}
+`);
+  process.exit(1);
+}

package/dist/index.js

@@ -0,0 +1,170 @@
+// ../core/dist/config.js
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var CONFIG_CANDIDATES = [".agent/hooks/hooks.json", ".claude/settings.json", ".claude/hooks.json"];
+var DEFAULT_TIMEOUT_MS = 6e5;
+function loadHooks(projectRoot) {
+  const errors = [];
+  for (const rel of CONFIG_CANDIDATES) {
+    const abs = join(projectRoot, rel);
+    if (!existsSync(abs))
+      continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(abs, "utf8"));
+    } catch (err) {
+      errors.push(`${abs}: \u4E0D\u662F\u5408\u6CD5 JSON \u2014 ${err.message}`);
+      return { hooks: [], source: abs, errors };
+    }
+    return { ...parseEntries(parsed, rel), source: abs };
+  }
+  return { hooks: [], source: null, errors };
+}
+function parseEntries(doc, where) {
+  const errors = [];
+  const hooks = [];
+  const raw = doc?.hooks;
+  if (!Array.isArray(raw)) {
+    errors.push(`${where}: \u9876\u5C42\u7F3A\u5C11 hooks \u6570\u7EC4`);
+    return { hooks, errors };
+  }
+  for (const [i, entry] of raw.entries()) {
+    const e = entry;
+    const command = typeof e?.command === "string" ? e.command : "";
+    if (command === "") {
+      errors.push(`${where}: \u7B2C ${i + 1} \u6761\u7F3A command \u2014\u2014 \u8DF3\u8FC7`);
+      continue;
+    }
+    const event = e?.event === "PostToolUse" ? "PostToolUse" : "PreToolUse";
+    const matcher = e?.matcher?.tool;
+    hooks.push({
+      id: typeof e?.id === "string" ? e.id : `hook-${i + 1}`,
+      event,
+      ...typeof matcher === "string" ? { tool: matcher } : {},
+      command,
+      timeoutMs: typeof e?.timeoutMs === "number" ? e.timeoutMs : DEFAULT_TIMEOUT_MS
+    });
+  }
+  return { hooks, errors };
+}
+function matches(hook, toolName) {
+  if (hook.tool === void 0)
+    return true;
+  try {
+    return new RegExp(hook.tool).test(toolName);
+  } catch {
+    return false;
+  }
+}
+function exitCodeBlocks(hook, exitCode) {
+  return hook.event === "PreToolUse" && exitCode !== 0;
+}
+
+// src/payload.ts
+function buildPayload(input) {
+  return {
+    event: input.event,
+    hookId: input.hookId,
+    toolName: input.toolName,
+    args: input.args,
+    sessionId: input.sessionId,
+    cwd: input.cwd ?? null
+  };
+}
+function payloadStdin(payload) {
+  return `${JSON.stringify(payload)}
+`;
+}
+function hookEnv(cwd, hookId, sessionId) {
+  return {
+    CLAUDE_PROJECT_DIR: cwd,
+    DSH_HOOK_ID: hookId,
+    DSH_SESSION_ID: sessionId ?? ""
+  };
+}
+
+// src/execute.ts
+import { spawnSync } from "node:child_process";
+async function runHookCommand(req, shell) {
+  if (shell !== void 0 && typeof shell.run === "function" && typeof shell.resolve === "function") {
+    try {
+      const resolved = shell.resolve({
+        command: req.command,
+        workdir: req.cwd,
+        timeoutMs: req.timeoutMs,
+        stdin: req.stdin,
+        env: req.env
+      });
+      const r2 = await shell.run(resolved);
+      return { exitCode: r2.exitCode };
+    } catch (err) {
+      return { exitCode: 1, error: `ctx.shell failure: ${err.message}` };
+    }
+  }
+  const r = spawnSync("sh", ["-c", req.command], {
+    cwd: req.cwd,
+    timeout: req.timeoutMs,
+    input: req.stdin,
+    env: { ...process.env, ...req.env },
+    encoding: "utf8"
+  });
+  return { exitCode: r.status ?? 1, ...r.status === null ? { error: `signal: ${String(r.signal)}` } : {} };
+}
+
+// src/index.ts
+var RECENT_CAP = 20;
+function createProjectHooksPlugin(ctx) {
+  const state = { runs: [] };
+  const note = (text) => {
+    ctx.write?.(text);
+  };
+  const record = (run) => {
+    state.runs = [run, ...state.runs].slice(0, RECENT_CAP);
+  };
+  const handle = async (event, exec) => {
+    const cwd = exec.agent?.session?.header?.cwd ?? process.cwd();
+    const sessionId = exec.agent?.session?.id ?? null;
+    const toolName = String(exec.toolName ?? "");
+    const args = exec.args ?? {};
+    const { hooks, source, errors } = loadHooks(cwd);
+    for (const e of errors) note(`project-hooks: ${e}
+`);
+    if (source === null) return void 0;
+    const applicable = hooks.filter((h) => h.event === event && matches(h, toolName));
+    if (applicable.length === 0) return void 0;
+    let decision;
+    for (const hook of applicable) {
+      const payload = buildPayload({ event, hookId: hook.id, toolName, args, sessionId, cwd });
+      const { exitCode, error } = await runHookCommand(
+        {
+          command: hook.command,
+          cwd,
+          timeoutMs: hook.timeoutMs,
+          stdin: payloadStdin(payload),
+          env: hookEnv(cwd, hook.id, sessionId)
+        },
+        ctx.shell
+      );
+      record({ hookId: hook.id, event, toolName, exitCode, at: Date.now(), ...error !== void 0 ? { error } : {} });
+      if (error !== void 0) note(`project-hooks: ${hook.id}: ${error}
+`);
+      if (exitCodeBlocks(hook, exitCode)) {
+        decision = {
+          kind: "deny",
+          reason: `project-hooks: ${hook.id} exited ${exitCode}${error === void 0 ? "" : ` (${error})`}`
+        };
+      }
+    }
+    return decision;
+  };
+  ctx.on("tools/pre-execute", (exec) => handle("PreToolUse", exec));
+  ctx.on("tools/post-execute", (exec) => handle("PostToolUse", exec));
+  return state;
+}
+function apply(ctx) {
+  return createProjectHooksPlugin(ctx);
+}
+export {
+  apply,
+  createProjectHooksPlugin
+};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "agentkit-dsh-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "DeepSeek Harness 插件：项目自包含的 lifecycle hooks（配置随仓库走，per-session 发现）",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts src/cli.ts --bundle --platform=node --format=esm --outdir=dist --target=node20",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "agentkit-plugin-core": "workspace:*"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "bin": {
+    "dsh-landing": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentkit/agentkit.git",
+    "directory": "packages/plugins/dsh"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "agent",
+    "hooks",
+    "agentkit"
+  ]
+}