opencode-supertask 0.1.23 → 0.1.25

package/README.md

@@ -13,7 +13,13 @@ Documentation: [current architecture](docs/architecture.md) · [operations and t
 
 ### Quick Install
 
-Add the plugin to `~/.config/opencode/opencode.json`:
+Install the CLI globally:
+
+```bash
+npm install -g opencode-supertask
+```
+
+Then add the plugin to `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -36,13 +42,14 @@ The plugin never installs global dependencies by itself. Without a running Gatew
 2. Remove `"opencode-supertask"` from `~/.config/opencode/opencode.json`
 3. Restart OpenCode
 
-To clear all task data safely, stop the Gateway and use the backup-first database command:
+To clear all task data safely, use the backup-first database command:
 
 ```bash
-pm2 stop supertask-gateway
 supertask db clear --confirm CLEAR
 ```
 
+If the matching Gateway is managed by PM2, the CLI stops it first and restarts it after maintenance.
+
 ### CLI Install / Uninstall
 
 ```bash
@@ -114,11 +121,11 @@ supertask template enable --id 1
 # Database maintenance
 supertask db check
 supertask db backup [--output /path/to/tasks-backup.db]
-supertask db clear --confirm CLEAR
-supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE
+supertask db clear --confirm CLEAR [--keep-stopped]
+supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE [--keep-stopped]
 ```
 
-`db backup` creates and validates a standalone SQLite snapshot. `db clear` and `db restore` refuse to run while another Gateway or task is active; both create a safety backup before changing data. Stop the PM2 Gateway before using the destructive CLI commands.
+`db backup` creates and validates a standalone SQLite snapshot. For `db clear` and `db restore`, the CLI automatically stops a PM2 Gateway whose PID matches the current database's fresh ready lock, then restores its previous running state. Both commands create a safety backup before changing data and still refuse active tasks or an unverified/foreground Gateway. Use `--keep-stopped` to leave a previously running PM2 Gateway stopped.
 
 ### Duration Format
 
@@ -214,7 +221,13 @@ SuperTask 是一个基于 SQLite 的 AI Agent 任务调度系统，专为 [OpenC
 
 ### 安装
 
-在 `~/.config/opencode/opencode.json` 中添加：
+先安装全局 CLI：
+
+```bash
+npm install -g opencode-supertask
+```
+
+然后在 `~/.config/opencode/opencode.json` 中添加：
 
 ```json
 {
@@ -240,10 +253,11 @@ supertask gateway   # 前台运行：不需要 pm2
 安全清理所有任务数据：
 
 ```bash
-pm2 stop supertask-gateway
 supertask db clear --confirm CLEAR
 ```
 
+若当前数据库对应的 Gateway 由 PM2 管理，CLI 会自动停止并在维护结束后恢复运行。
+
 ### 定时任务
 
 支持友好的时间格式：
@@ -274,11 +288,11 @@ supertask template add --type cron --cron "0 9 * * *" ...
 ```bash
 supertask db check
 supertask db backup [--output /path/to/tasks-backup.db]
-supertask db clear --confirm CLEAR
-supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE
+supertask db clear --confirm CLEAR [--keep-stopped]
+supertask db restore --from /path/to/tasks-backup.db --confirm RESTORE [--keep-stopped]
 ```
 
-`db backup` 会生成并校验可独立恢复的 SQLite 快照。CLI 清空和恢复会拒绝活跃 Gateway 或运行中任务，并在修改数据前自动保留安全备份；执行这两个危险命令前应先停止 PM2 Gateway。
+`db backup` 会生成并校验可独立恢复的 SQLite 快照。CLI 清空和恢复会先确认 PM2 PID 与当前数据库的新鲜 ready 锁一致，再自动停止并按原状态重启 Gateway；操作失败时也会尝试恢复 Gateway。它们仍会拒绝运行中任务、前台 Gateway 或无法确认归属的进程，并在修改数据前自动保留安全备份。传入 `--keep-stopped` 可让原本运行的 PM2 Gateway 保持停止。
 
 ### 数据位置
 

package/dist/cli/index.js

@@ -19562,7 +19562,7 @@ var init_database_maintenance_service = __esm({
         if (!lock || !isProcessAlive(lock.pid)) return;
         if (allowCurrentGateway && lock.pid === process.pid) return;
         throw new DatabaseMaintenanceConflictError(
-          `Gateway PID ${lock.pid} \u4ECD\u5728\u8FD0\u884C\uFF0C\u8BF7\u5148\u6267\u884C pm2 stop supertask-gateway`
+          `Gateway PID ${lock.pid} \u4ECD\u5728\u8FD0\u884C\uFF0C\u4F46\u672A\u786E\u8BA4\u7531\u5F53\u524D\u6570\u636E\u5E93\u5BF9\u5E94\u7684 PM2 \u8FDB\u7A0B\u7BA1\u7406\uFF1B\u8BF7\u5148\u505C\u6B62\u8BE5 Gateway\uFF08PM2 \u53EF\u6267\u884C pm2 stop supertask-gateway\uFF09`
         );
       }
       static assertNoRunningWork(sqlite2) {
@@ -19718,6 +19718,8 @@ __export(pm2_exports, {
   isGatewayRunning: () => isGatewayRunning,
   isPm2Installed: () => isPm2Installed,
   resolveGatewayEntry: () => resolveGatewayEntry,
+  restartGatewayAfterMaintenance: () => restartGatewayAfterMaintenance,
+  stopGatewayForMaintenance: () => stopGatewayForMaintenance,
   uninstall: () => uninstall,
   upgrade: () => upgrade
 });
@@ -19937,6 +19939,28 @@ function waitForGatewayReady(pid) {
   }
   return isGatewayReady(pid);
 }
+function stopGatewayForMaintenance() {
+  if (!isPm2Installed()) return { wasRunning: false };
+  const proc = pm2JsonList().find((item) => item.name === PROCESS_NAME);
+  const managedCurrentDatabase = proc?.pm2_env?.status === "online" && typeof proc.pid === "number" && isGatewayReady(proc.pid);
+  if (!managedCurrentDatabase) return { wasRunning: false };
+  requirePm2(["stop", PROCESS_NAME], "pm2 stop Gateway for database maintenance");
+  return { wasRunning: true };
+}
+function restartGatewayAfterMaintenance(state2) {
+  if (!state2.wasRunning) return false;
+  requirePm2(["start", PROCESS_NAME], "pm2 restart Gateway after database maintenance");
+  const started = pm2JsonList().find((item) => item.name === PROCESS_NAME);
+  if (started?.pm2_env?.status !== "online") {
+    throw new Error(
+      `[supertask] Gateway \u6570\u636E\u5E93\u7EF4\u62A4\u540E\u672A\u6062\u590D online\uFF08\u72B6\u6001\uFF1A${started?.pm2_env?.status ?? "missing"}\uFF09`
+    );
+  }
+  if (typeof started.pid !== "number" || !waitForGatewayReady(started.pid)) {
+    throw new Error("[supertask] Gateway \u6570\u636E\u5E93\u7EF4\u62A4\u540E\u5DF2 online\uFF0C\u4F46\u672A\u5728\u9650\u5B9A\u65F6\u95F4\u5185\u5C31\u7EEA\uFF1B\u8BF7\u67E5\u770B pm2 logs supertask-gateway");
+  }
+  return true;
+}
 function findBunPath() {
   const override = process.env.SUPERTASK_BUN_BIN;
   if (override) return override;
@@ -24128,6 +24152,11 @@ function compareVersions(left, right) {
 function cacheRoot() {
   return process.env.SUPERTASK_OPENCODE_CACHE_DIR ?? join4(homedir4(), ".cache/opencode/packages");
 }
+function installedPlugins() {
+  const root = cacheRoot();
+  const packageDirs = existsSync6(root) ? readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && (entry.name === PACKAGE_NAME || entry.name.startsWith(`${PACKAGE_NAME}@`))).map((entry) => join4(root, entry.name, "node_modules", PACKAGE_NAME)) : [];
+  return packageDirs.map(pluginAt).filter((plugin) => plugin !== null);
+}
 function resolveInstalledPlugin() {
   const override = process.env.SUPERTASK_PLUGIN_PACKAGE_DIR;
   if (override) {
@@ -24135,9 +24164,7 @@ function resolveInstalledPlugin() {
     if (!plugin) throw new Error(`[supertask] \u5B89\u88C5\u5305\u65E0\u6548\u6216\u7F3A\u5C11 Gateway \u6784\u5EFA\u4EA7\u7269: ${override}`);
     return plugin;
   }
-  const root = cacheRoot();
-  const packageDirs = existsSync6(root) ? readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && (entry.name === PACKAGE_NAME || entry.name.startsWith(`${PACKAGE_NAME}@`))).map((entry) => join4(root, entry.name, "node_modules", PACKAGE_NAME)) : [];
-  const installed = packageDirs.map(pluginAt).filter((plugin) => plugin !== null).sort((left, right) => compareVersions(right.version, left.version));
+  const installed = installedPlugins().sort((left, right) => compareVersions(right.version, left.version));
   if (!installed[0]) {
     throw new Error(`[supertask] OpenCode \u63D2\u4EF6\u7F13\u5B58\u4E2D\u627E\u4E0D\u5230\u53EF\u8FD0\u884C\u7684 ${PACKAGE_NAME}`);
   }
@@ -24146,10 +24173,52 @@ function resolveInstalledPlugin() {
 function opencodeBin() {
   return process.env.SUPERTASK_OPENCODE_BIN ?? "opencode";
 }
+function npmBin() {
+  return process.env.SUPERTASK_NPM_BIN ?? "npm";
+}
+function latestVersion() {
+  const result = spawnSync3(npmBin(), [
+    "view",
+    PACKAGE_NAME,
+    "dist-tags.latest",
+    "--json"
+  ], {
+    encoding: "utf8",
+    env: process.env,
+    timeout: 3e4
+  });
+  const output = `${result.stdout ?? ""}`.trim();
+  if (result.error) {
+    throw new Error(`[supertask] \u67E5\u8BE2 npm latest \u5931\u8D25: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const detail = `${result.stderr ?? ""}`.trim();
+    throw new Error(`[supertask] \u67E5\u8BE2 npm latest \u5931\u8D25: ${detail || `\u9000\u51FA\u7801 ${result.status}`}`);
+  }
+  let version2;
+  try {
+    version2 = JSON.parse(output);
+  } catch {
+    throw new Error(`[supertask] npm latest \u8FD4\u56DE\u65E0\u6CD5\u89E3\u6790: ${output || "(empty)"}`);
+  }
+  if (typeof version2 !== "string" || versionParts(version2) === null) {
+    throw new Error(`[supertask] npm latest \u7248\u672C\u65E0\u6548: ${String(version2)}`);
+  }
+  return version2;
+}
+function resolveInstalledVersion(expectedVersion) {
+  const override = process.env.SUPERTASK_PLUGIN_PACKAGE_DIR;
+  const installed = override ? [pluginAt(override)].filter((plugin) => plugin !== null) : installedPlugins();
+  const matched = installed.find((plugin) => plugin.version === expectedVersion);
+  if (matched) return matched;
+  const actual = installed.length > 0 ? installed.map((plugin) => plugin.version).join(", ") : "\u672A\u627E\u5230\u53EF\u8FD0\u884C\u7F13\u5B58";
+  throw new Error(`[supertask] OpenCode \u63D2\u4EF6\u7F13\u5B58\u7248\u672C\u4E0D\u5339\u914D\uFF1A\u671F\u671B ${expectedVersion}\uFF0C\u5B9E\u9645 ${actual}`);
+}
 function installLatestPlugin() {
+  const version2 = latestVersion();
   const result = spawnSync3(opencodeBin(), [
     "plugin",
-    `${PACKAGE_NAME}@latest`,
+    `${PACKAGE_NAME}@${version2}`,
     "--global",
     "--force"
   ], {
@@ -24164,7 +24233,7 @@ function installLatestPlugin() {
   if (result.status !== 0) {
     throw new Error(`[supertask] OpenCode \u63D2\u4EF6\u66F4\u65B0\u5931\u8D25: ${output || `\u9000\u51FA\u7801 ${result.status}`}`);
   }
-  return resolveInstalledPlugin();
+  return resolveInstalledVersion(version2);
 }
 var PACKAGE_NAME;
 var init_update2 = __esm({
@@ -24239,6 +24308,43 @@ async function withDb(fn) {
     closeDb();
   }
 }
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function runDestructiveDatabaseMaintenance(keepStopped, operation) {
+  const gatewayState = stopGatewayForMaintenance();
+  let result;
+  try {
+    result = operation();
+  } catch (error) {
+    if (gatewayState.wasRunning && !keepStopped) {
+      try {
+        restartGatewayAfterMaintenance(gatewayState);
+      } catch (restartError) {
+        throw new Error(
+          `${messageOf(error)}\uFF1BGateway \u81EA\u52A8\u6062\u590D\u4E5F\u5931\u8D25\uFF1A${messageOf(restartError)}`
+        );
+      }
+    }
+    throw error;
+  }
+  let restarted = false;
+  if (gatewayState.wasRunning && !keepStopped) {
+    try {
+      restarted = restartGatewayAfterMaintenance(gatewayState);
+    } catch (error) {
+      throw new Error(`\u6570\u636E\u5E93\u7EF4\u62A4\u5DF2\u5B8C\u6210\uFF0C\u4F46 Gateway \u81EA\u52A8\u91CD\u542F\u5931\u8D25\uFF1A${messageOf(error)}`);
+    }
+  }
+  return {
+    ...result,
+    gateway: {
+      wasRunning: gatewayState.wasRunning,
+      restarted,
+      keptStopped: gatewayState.wasRunning && keepStopped
+    }
+  };
+}
 var program2 = new Command();
 program2.name("supertask").description("\u901A\u7528\u4EFB\u52A1\u7BA1\u7406\u7CFB\u7EDF - AI Agent \u4EFB\u52A1\u8C03\u5EA6\u5668").version(getPackageVersion());
 program2.command("add").description("\u521B\u5EFA\u65B0\u4EFB\u52A1").requiredOption("-n, --name <name>", "\u4EFB\u52A1\u540D\u79F0").requiredOption("-a, --agent <agent>", "\u4E3B Agent \u540D\u79F0").requiredOption("-p, --prompt <prompt>", "\u63D0\u793A\u8BCD").option("-m, --model <model>", "\u6A21\u578B").option("-c, --category <category>", "\u5206\u7C7B", "general").option("-i, --importance <number>", "\u91CD\u8981\u7A0B\u5EA6 (1-5)", "3").option("-u, --urgency <number>", "\u7D27\u6025\u7A0B\u5EA6 (1-5)", "3").option("-b, --batch <batchId>", "\u6279\u6B21 ID").option("-d, --depends <taskId>", "\u4F9D\u8D56\u7684\u4EFB\u52A1 ID").option("--max-retries <number>", "\u9996\u6B21\u6267\u884C\u4E4B\u5916\u5141\u8BB8\u7684\u91CD\u8BD5\u6B21\u6570", "3").option("--retry-backoff <duration>", "\u91CD\u8BD5\u9000\u907F\u57FA\u7840\u95F4\u9694\uFF0C\u5982 30s / 5min", "30s").option("--timeout <duration>", "\u4EFB\u52A1\u786C\u8D85\u65F6\uFF0C\u5982 30min / 2h").option("-w, --cwd <path>", "(\u5DF2\u5E9F\u5F03) \u5DE5\u4F5C\u76EE\u5F55\u3002\u7CFB\u7EDF\u4F1A\u81EA\u52A8\u8BB0\u5F55\u63D0\u4EA4\u4EFB\u52A1\u65F6\u7684\u5F53\u524D\u76EE\u5F55").action(async (options) => withDb(async () => {
@@ -24450,17 +24556,25 @@ databaseCommand.command("check").description("\u68C0\u67E5\u6570\u636E\u5E93\u5B
 databaseCommand.command("backup").description("\u521B\u5EFA\u7ECF\u8FC7\u5B8C\u6574\u6027\u6821\u9A8C\u7684\u4E00\u81F4\u6027\u5907\u4EFD").option("-o, --output <path>", "\u5907\u4EFD\u6587\u4EF6\u8DEF\u5F84\uFF08\u9ED8\u8BA4\u5199\u5165\u6570\u636E\u5E93\u76EE\u5F55\uFF09").action(async (options) => withDb(async () => {
   console.log(JSON.stringify(DatabaseMaintenanceService.backup(options.output), null, 2));
 }));
-databaseCommand.command("clear").description("\u5907\u4EFD\u540E\u4E8B\u52A1\u6027\u6E05\u7A7A\u4EFB\u52A1\u3001\u6267\u884C\u8BB0\u5F55\u548C\u8C03\u5EA6\u6A21\u677F").option("--confirm <word>", "\u5371\u9669\u64CD\u4F5C\u786E\u8BA4\uFF0C\u5FC5\u987B\u586B\u5199 CLEAR").action(async (options) => withDb(async () => {
+databaseCommand.command("clear").description("\u5907\u4EFD\u540E\u4E8B\u52A1\u6027\u6E05\u7A7A\u4EFB\u52A1\u3001\u6267\u884C\u8BB0\u5F55\u548C\u8C03\u5EA6\u6A21\u677F").option("--confirm <word>", "\u5371\u9669\u64CD\u4F5C\u786E\u8BA4\uFF0C\u5FC5\u987B\u586B\u5199 CLEAR").option("--keep-stopped", "\u7EF4\u62A4\u7ED3\u675F\u540E\u4E0D\u91CD\u542F\u539F\u672C\u7531 PM2 \u7BA1\u7406\u7684 Gateway").action(async (options) => withDb(async () => {
   if (options.confirm !== "CLEAR") {
     throw new Error("\u6E05\u7A7A\u6570\u636E\u5E93\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 --confirm CLEAR");
   }
-  console.log(JSON.stringify(DatabaseMaintenanceService.clear(), null, 2));
+  const result = runDestructiveDatabaseMaintenance(
+    options.keepStopped ?? false,
+    () => DatabaseMaintenanceService.clear()
+  );
+  console.log(JSON.stringify(result, null, 2));
 }));
-databaseCommand.command("restore").description("\u81EA\u52A8\u5907\u4EFD\u5F53\u524D\u5E93\u540E\uFF0C\u4ECE\u6307\u5B9A\u5907\u4EFD\u6062\u590D\u6570\u636E\u5E93").requiredOption("--from <path>", "\u8981\u6062\u590D\u7684 SQLite \u5907\u4EFD\u6587\u4EF6").option("--confirm <word>", "\u5371\u9669\u64CD\u4F5C\u786E\u8BA4\uFF0C\u5FC5\u987B\u586B\u5199 RESTORE").action(async (options) => withDb(async () => {
+databaseCommand.command("restore").description("\u81EA\u52A8\u5907\u4EFD\u5F53\u524D\u5E93\u540E\uFF0C\u4ECE\u6307\u5B9A\u5907\u4EFD\u6062\u590D\u6570\u636E\u5E93").requiredOption("--from <path>", "\u8981\u6062\u590D\u7684 SQLite \u5907\u4EFD\u6587\u4EF6").option("--confirm <word>", "\u5371\u9669\u64CD\u4F5C\u786E\u8BA4\uFF0C\u5FC5\u987B\u586B\u5199 RESTORE").option("--keep-stopped", "\u7EF4\u62A4\u7ED3\u675F\u540E\u4E0D\u91CD\u542F\u539F\u672C\u7531 PM2 \u7BA1\u7406\u7684 Gateway").action(async (options) => withDb(async () => {
   if (options.confirm !== "RESTORE") {
     throw new Error("\u6062\u590D\u6570\u636E\u5E93\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 --confirm RESTORE");
   }
-  console.log(JSON.stringify(DatabaseMaintenanceService.restore(options.from), null, 2));
+  const result = runDestructiveDatabaseMaintenance(
+    options.keepStopped ?? false,
+    () => DatabaseMaintenanceService.restore(options.from)
+  );
+  console.log(JSON.stringify(result, null, 2));
 }));
 program2.addCommand(databaseCommand);
 program2.command("init").description("Initialize SuperTask (create config + run migrations)").action(async () => withDb(async () => {
@@ -24536,7 +24650,7 @@ program2.command("upgrade").description("Update OpenCode plugin cache and restar
     installed = installLatestPlugin2();
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));
-    console.error("Try manually: opencode plugin opencode-supertask@latest --global --force");
+    console.error("Try manually: query npm dist-tags.latest, then install that exact version with opencode plugin.");
     process.exit(1);
   }
   try {