@downcity/city 1.1.1 → 1.1.5

package/src/cli/service/ServiceCommandSupport.ts

@@ -0,0 +1,275 @@
+/**
+ * `city service` 命令共享辅助 + Agent 预检。
+ *
+ * 关键点（中文）
+ * - 统一承载 service 命令的参数解析、目标 agent 路径解析与项目目录校验。
+ * - 提供 `checkAgentPreflight` 供 start/restart/status 等命令统一使用。
+ * - 保持 command 注册层只关注命令树，不再直接承载路径解析细节。
+ */
+
+import path from "node:path";
+import fs from "node:fs";
+import type { Command } from "commander";
+import { getProfileMdPath, getDowncityJsonPath } from "@/config/Paths.js";
+import { listManagedAgentEntries } from "@/process/registry/CityRegistry.js";
+import { isCityRunning } from "@/process/registry/CityRuntime.js";
+import { ensureRuntimeExecutionBindingReady } from "@downcity/agent";
+import type { JsonValue } from "@downcity/agent";
+import { parsePort, resolveAgentName } from "../shared/IndexSupport.js";
+import { CliError } from "../shared/CliError.js";
+import type { ScheduledJobStatus } from "@downcity/agent";
+import type { ServiceCliBaseOptions } from "@downcity/agent";
+import { parseBoolean } from "../shared/IndexSupport.js";
+
+export function isRegistryEntryRunning(
+  entry: { status?: "running" | "stopped" },
+): boolean {
+  return entry.status !== "stopped";
+}
+
+/**
+ * Agent 启动前预检选项。
+ */
+export interface AgentPreflightOptions {
+  /** 是否要求 city runtime 已运行。 */
+  requireCityRunning?: boolean;
+}
+
+/**
+ * Agent 启动前统一预检。
+ *
+ * 关键点（中文）
+ * - 收敛 start/restart/status 等命令的前置校验逻辑。
+ * - 按顺序检查，首个失败即抛 CliError（city running → PROFILE.md → downcity.json → binding）。
+ *
+ * @throws {CliError} 任一校验失败时抛出。
+ */
+export async function checkAgentPreflight(
+  projectRoot: string,
+  options?: AgentPreflightOptions,
+): Promise<void> {
+  if (options?.requireCityRunning !== false) {
+    if (!(await isCityRunning())) {
+      throw new CliError({
+        title: "city runtime is not running",
+        fix: "city start",
+      });
+    }
+  }
+
+  const profilePath = getProfileMdPath(projectRoot);
+  if (!fs.existsSync(profilePath)) {
+    throw new CliError({
+      title: "Project not initialized",
+      note: `PROFILE.md not found at ${projectRoot}`,
+      fix: "city agent create",
+    });
+  }
+
+  const downcityJsonPath = getDowncityJsonPath(projectRoot);
+  if (!fs.existsSync(downcityJsonPath)) {
+    throw new CliError({
+      title: "downcity.json not found",
+      note: `project: ${projectRoot}`,
+      fix: "city agent create",
+    });
+  }
+
+  // 关键点（中文）：提前校验 execution binding，避免"启动成功后秒退"。
+  ensureRuntimeExecutionBindingReady(projectRoot);
+}
+
+/**
+ * 解析正整数参数。
+ */
+export function parsePositiveIntOption(value: string, fieldName: string): number {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 归一化 schedule 状态过滤参数。
+ */
+export function normalizeScheduledJobStatus(
+  value: string | undefined,
+): ScheduledJobStatus | undefined {
+  const text = String(value || "").trim().toLowerCase();
+  if (!text) return undefined;
+  if (
+    text === "pending" ||
+    text === "running" ||
+    text === "succeeded" ||
+    text === "failed" ||
+    text === "cancelled"
+  ) {
+    return text;
+  }
+  throw new Error(
+    `Invalid schedule status: ${value}. Use pending|running|succeeded|failed|cancelled.`,
+  );
+}
+
+/**
+ * 解析项目根目录。
+ */
+export function resolveProjectRoot(pathInput?: string): string {
+  const raw = String(pathInput || ".").trim() || ".";
+  // 关键点（中文）：在 agent shell 中，默认 path="." 时优先使用注入的 DC_AGENT_PATH。
+  if (raw === ".") {
+    const envAgentPath = String(process.env.DC_AGENT_PATH || "").trim();
+    if (envAgentPath) return path.resolve(envAgentPath);
+  }
+  return path.resolve(raw);
+}
+
+/**
+ * 通过 agent 名称解析 projectRoot。
+ */
+export async function resolveProjectRootByAgentName(agentName: string): Promise<{
+  projectRoot?: string;
+  error?: string;
+}> {
+  const target = String(agentName || "").trim().toLowerCase();
+  if (!target) {
+    return { error: "--agent requires a non-empty value" };
+  }
+
+  const entries = await listManagedAgentEntries();
+  const matchedRoots = entries
+    .filter((entry) => isRegistryEntryRunning(entry))
+    .map((entry) => path.resolve(String(entry.projectRoot || "").trim() || "."))
+    .filter((root, index, all) => all.indexOf(root) === index)
+    .filter((root) => {
+      const byDirName = path.basename(root).toLowerCase() === target;
+      const byShipName = resolveAgentName(root).toLowerCase() === target;
+      return byDirName || byShipName;
+    });
+
+  if (matchedRoots.length === 0) {
+    return {
+      error: `Agent not found in managed agent registry: ${agentName}. Run "city agent list" to inspect names.`,
+    };
+  }
+  if (matchedRoots.length > 1) {
+    return {
+      error: `Agent name is ambiguous: ${agentName}. Matched paths: ${matchedRoots.join(", ")}`,
+    };
+  }
+
+  return { projectRoot: matchedRoots[0] };
+}
+
+/**
+ * 统一解析 service 命令目标路径（agent 优先于 path）。
+ */
+export async function resolveServiceProjectRoot(options: ServiceCliBaseOptions): Promise<{
+  projectRoot?: string;
+  error?: string;
+}> {
+  const explicitAgent = String(options.agent || "").trim();
+  if (explicitAgent) {
+    return resolveProjectRootByAgentName(explicitAgent);
+  }
+
+  const rawPath = String(options.path || ".").trim() || ".";
+  // 关键点（中文）：在 agent shell 中，未显式传 --agent 且 path 走默认值时，
+  // 优先使用注入的 DC_AGENT_NAME 走 registry 解析，确保多 agent 下目标稳定。
+  if (rawPath === ".") {
+    const envAgentName = String(process.env.DC_AGENT_NAME || "").trim();
+    if (envAgentName) {
+      const byName = await resolveProjectRootByAgentName(envAgentName);
+      if (byName.projectRoot) {
+        return byName;
+      }
+    }
+  }
+
+  const projectRoot = resolveProjectRoot(options.path);
+  const entries = await listManagedAgentEntries();
+  const registered = entries.some(
+    (entry) =>
+      isRegistryEntryRunning(entry) &&
+      path.resolve(String(entry.projectRoot || "").trim() || ".") === projectRoot,
+  );
+  if (!registered) {
+    return {
+      error:
+        `Agent is not registered in managed agent registry: ${projectRoot}. ` +
+        `Run "city agent list" to inspect registered agents.`,
+    };
+  }
+  return { projectRoot };
+}
+
+/**
+ * 解析 schedule 管理命令目标路径。
+ */
+export async function resolveScheduleProjectRoot(options: ServiceCliBaseOptions): Promise<{
+  projectRoot?: string;
+  error?: string;
+}> {
+  const explicitAgent = String(options.agent || "").trim();
+  if (explicitAgent) {
+    return resolveProjectRootByAgentName(explicitAgent);
+  }
+  return {
+    projectRoot: resolveProjectRoot(options.path),
+  };
+}
+
+/**
+ * 校验路径是否为有效 agent 项目目录。
+ */
+export function validateAgentProjectRoot(projectRoot: string): string | null {
+  const missing: string[] = [];
+  if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
+    missing.push("downcity.json");
+  }
+  if (!fs.existsSync(getProfileMdPath(projectRoot))) {
+    missing.push("PROFILE.md");
+  }
+
+  if (missing.length === 0) return null;
+  return `Invalid agent path: ${projectRoot}. Missing: ${missing.join(", ")}`;
+}
+
+/**
+ * 解析 service command payload。
+ */
+export function parseCommandPayload(raw?: string): JsonValue | undefined {
+  if (typeof raw !== "string") return undefined;
+  const text = raw.trim();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as JsonValue;
+  } catch {
+    // 关键点（中文）：payload 不是 JSON 时按字符串透传，避免强制格式。
+    return text;
+  }
+}
+
+/**
+ * 注入 service 目标解析通用选项。
+ */
+export function addServiceTargetOptions(command: Command): Command {
+  return command
+    .option("--path <path>", "项目根目录（默认当前目录）", ".")
+    .option("--agent <name>", "agent 名称（从 managed agent registry 解析）")
+    .option("--host <host>", "Server host（覆盖自动解析）")
+    .option("--port <port>", "Server port（覆盖自动解析）", parsePort)
+    .option("--token <token>", "覆盖 Bearer Token（仅远程 HTTP 调用需要；默认本地走 IPC）")
+    .option("--json [enabled]", "以 JSON 输出", parseBoolean, true);
+}
+
+/**
+ * 注入 schedule 管理命令通用选项。
+ */
+export function addServiceScheduleOptions(command: Command): Command {
+  return command
+    .option("--path <path>", "项目根目录（默认当前目录）", ".")
+    .option("--agent <name>", "agent 名称（从 managed agent registry 解析）")
+    .option("--json [enabled]", "以 JSON 输出", parseBoolean, true);
+}

package/src/cli/service/ServiceScheduleCommand.ts

@@ -0,0 +1,305 @@
+/**
+ * `city service schedule` 命令。
+ *
+ * 关键点（中文）
+ * - schedule 管理命令只依赖项目本地 schedule SQLite，不要求 runtime 在线。
+ * - 这里同时承载 schedule 子命令注册与本地存储读写流程。
+ */
+
+import type { Command } from "commander";
+import { ServiceScheduleStore } from "@downcity/agent";
+import { printResult } from "@/utils/cli/CliOutput.js";
+import type { ServiceCliBaseOptions } from "@downcity/agent";
+import {
+  addServiceScheduleOptions,
+  normalizeScheduledJobStatus,
+  parsePositiveIntOption,
+  resolveScheduleProjectRoot,
+  validateAgentProjectRoot,
+} from "./ServiceCommandSupport.js";
+
+/**
+ * 执行 `service schedule list`。
+ */
+export async function runServiceScheduleListCommand(params: {
+  options: ServiceCliBaseOptions;
+  statusRaw?: string;
+  limitRaw?: string;
+}): Promise<void> {
+  const resolved = await resolveScheduleProjectRoot(params.options);
+  if (!resolved.projectRoot) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule list failed",
+      payload: {
+        error: resolved.error || "Failed to resolve agent project path",
+      },
+    });
+    return;
+  }
+  const projectRoot = resolved.projectRoot;
+  const pathError = validateAgentProjectRoot(projectRoot);
+  if (pathError) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule list failed",
+      payload: {
+        error: pathError,
+      },
+    });
+    return;
+  }
+
+  try {
+    const status = normalizeScheduledJobStatus(params.statusRaw);
+    const limit = params.limitRaw
+      ? parsePositiveIntOption(params.limitRaw, "limit")
+      : 100;
+    const store = new ServiceScheduleStore(projectRoot);
+    try {
+      const jobs = store.listJobs({ status, limit });
+      printResult({
+        asJson: params.options.json,
+        success: true,
+        title: "service schedule listed",
+        payload: {
+          ...(status ? { status } : {}),
+          limit,
+          count: jobs.length,
+          jobs,
+        },
+      });
+    } finally {
+      store.close();
+    }
+  } catch (error) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule list failed",
+      payload: {
+        error: String(error),
+      },
+    });
+  }
+}
+
+/**
+ * 执行 `service schedule info`。
+ */
+export async function runServiceScheduleInfoCommand(params: {
+  jobId: string;
+  options: ServiceCliBaseOptions;
+}): Promise<void> {
+  const resolved = await resolveScheduleProjectRoot(params.options);
+  if (!resolved.projectRoot) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule info failed",
+      payload: {
+        error: resolved.error || "Failed to resolve agent project path",
+      },
+    });
+    return;
+  }
+  const projectRoot = resolved.projectRoot;
+  const pathError = validateAgentProjectRoot(projectRoot);
+  if (pathError) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule info failed",
+      payload: {
+        error: pathError,
+      },
+    });
+    return;
+  }
+
+  const jobId = String(params.jobId || "").trim();
+  if (!jobId) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule info failed",
+      payload: {
+        error: "jobId is required",
+      },
+    });
+    return;
+  }
+
+  const store = new ServiceScheduleStore(projectRoot);
+  try {
+    const job = store.getJobById(jobId);
+    if (!job) {
+      printResult({
+        asJson: params.options.json,
+        success: false,
+        title: "service schedule info failed",
+        payload: {
+          error: `Scheduled job not found: ${jobId}`,
+        },
+      });
+      return;
+    }
+    printResult({
+      asJson: params.options.json,
+      success: true,
+      title: "service schedule info ok",
+      payload: {
+        job,
+      },
+    });
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 执行 `service schedule cancel`。
+ */
+export async function runServiceScheduleCancelCommand(params: {
+  jobId: string;
+  options: ServiceCliBaseOptions;
+}): Promise<void> {
+  const resolved = await resolveScheduleProjectRoot(params.options);
+  if (!resolved.projectRoot) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule cancel failed",
+      payload: {
+        error: resolved.error || "Failed to resolve agent project path",
+      },
+    });
+    return;
+  }
+  const projectRoot = resolved.projectRoot;
+  const pathError = validateAgentProjectRoot(projectRoot);
+  if (pathError) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule cancel failed",
+      payload: {
+        error: pathError,
+      },
+    });
+    return;
+  }
+
+  const jobId = String(params.jobId || "").trim();
+  if (!jobId) {
+    printResult({
+      asJson: params.options.json,
+      success: false,
+      title: "service schedule cancel failed",
+      payload: {
+        error: "jobId is required",
+      },
+    });
+    return;
+  }
+
+  const store = new ServiceScheduleStore(projectRoot);
+  try {
+    const current = store.getJobById(jobId);
+    if (!current) {
+      printResult({
+        asJson: params.options.json,
+        success: false,
+        title: "service schedule cancel failed",
+        payload: {
+          error: `Scheduled job not found: ${jobId}`,
+        },
+      });
+      return;
+    }
+    if (current.status !== "pending") {
+      printResult({
+        asJson: params.options.json,
+        success: false,
+        title: "service schedule cancel failed",
+        payload: {
+          error: `Only pending jobs can be cancelled. Current status: ${current.status}`,
+          job: current,
+        },
+      });
+      return;
+    }
+
+    const cancelled = store.cancelPendingJob(jobId);
+    if (!cancelled) {
+      printResult({
+        asJson: params.options.json,
+        success: false,
+        title: "service schedule cancel failed",
+        payload: {
+          error: `Failed to cancel scheduled job: ${jobId}`,
+        },
+      });
+      return;
+    }
+
+    printResult({
+      asJson: params.options.json,
+      success: true,
+      title: "service schedule cancelled",
+      payload: {
+        job: store.getJobById(jobId),
+      },
+    });
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 注册 `service schedule` 子命令组。
+ */
+export function registerServiceScheduleCommands(service: Command): void {
+  const schedule = service
+    .command("schedule")
+    .description("查看和管理持久化 schedule 任务")
+    .helpOption("--help", "display help for command");
+
+  addServiceScheduleOptions(
+    schedule
+      .command("list")
+      .description("列出当前 agent 的调度任务")
+      .option("--status <status>", "状态过滤（pending|running|succeeded|failed|cancelled）")
+      .option("--limit <n>", "返回条数（默认 100）"),
+  ).action(async (opts: ServiceCliBaseOptions & { status?: string; limit?: string }) => {
+    await runServiceScheduleListCommand({
+      options: opts,
+      statusRaw: opts.status,
+      limitRaw: opts.limit,
+    });
+  });
+
+  addServiceScheduleOptions(
+    schedule
+      .command("info <jobId>")
+      .description("查看单个调度任务详情"),
+  ).action(async (jobId: string, opts: ServiceCliBaseOptions) => {
+    await runServiceScheduleInfoCommand({
+      jobId,
+      options: opts,
+    });
+  });
+
+  addServiceScheduleOptions(
+    schedule
+      .command("cancel <jobId>")
+      .description("取消一个尚未执行的调度任务"),
+  ).action(async (jobId: string, opts: ServiceCliBaseOptions) => {
+    await runServiceScheduleCancelCommand({
+      jobId,
+      options: opts,
+    });
+  });
+}