@hiroleague/taskmanager 0.0.1 → 0.0.3

package/src/cli/handlers/search.ts

@@ -1,17 +1,17 @@
-import { runSearch } from "../lib/read/search";
-import type { CliContext } from "./context";
-
-export async function handleSearch(
-  ctx: CliContext,
-  queryParts: string[],
-  options: {
-    board?: string;
-    limit?: string;
-    offset?: string;
-    noPrefix?: boolean;
-    pageAll?: boolean;
-    fields?: string;
-  },
-): Promise<void> {
-  await runSearch(ctx, queryParts, options);
-}
+import { runSearch } from "../lib/read/search";
+import type { CliContext } from "./context";
+
+export async function handleSearch(
+  ctx: CliContext,
+  queryParts: string[],
+  options: {
+    board?: string;
+    limit?: string;
+    offset?: string;
+    noPrefix?: boolean;
+    pageAll?: boolean;
+    fields?: string;
+  },
+): Promise<void> {
+  await runSearch(ctx, queryParts, options);
+}

package/src/cli/handlers/server.test.ts

@@ -4,6 +4,8 @@ import { createTestCliRuntime } from "../lib/runtime";
 import { createDefaultCliContext } from "./context";
 import { handleServerStart, handleServerStatus, handleServerStop } from "./server";
 import type { CliContext } from "./context";
+import type { ServerStartMode } from "../ports/process";
+import type { RunningServerStatus } from "../../shared/serverStatus";
 
 function baseCtx(overrides: Partial<CliContext> = {}): CliContext {
   return {
@@ -19,7 +21,14 @@ function baseCtx(overrides: Partial<CliContext> = {}): CliContext {
 
 describe("handleServerStatus", () => {
   test("prints status from readServerStatus", async () => {
-    const status = { running: true, pid: 42 };
+    const status = {
+      pid: 42,
+      port: 3020,
+      running: true,
+      runtime: "installed",
+      source: "installed",
+      url: "http://127.0.0.1:3020",
+    } satisfies RunningServerStatus;
     let printed: unknown;
     const ctx = baseCtx({
       printJson: (d) => {
@@ -37,15 +46,22 @@ describe("handleServerStatus", () => {
 describe("handleServerStart / handleServerStop", () => {
   test("background start passes dataDir + port and prints JSON status", async () => {
     let startArgs: ConfigOverrides | undefined;
-    let backgroundFlag: boolean | undefined;
-    const status = { running: true, pid: 99, port: 3040 };
+    let startMode: ServerStartMode | undefined;
+    const status = {
+      pid: 99,
+      port: 3040,
+      running: true,
+      runtime: "installed",
+      source: "installed",
+      url: "http://127.0.0.1:3040",
+    } satisfies RunningServerStatus;
     let printed: unknown;
     const ctx = baseCtx({
       resolveDataDir: () => "/custom/data",
       resolvePort: () => 3040,
-      startServer: async (opts, bg) => {
+      startServer: async (opts, mode) => {
         startArgs = opts;
-        backgroundFlag = bg;
+        startMode = mode;
         return status;
       },
       printJson: (d) => {
@@ -59,26 +75,52 @@ describe("handleServerStart / handleServerStop", () => {
       dataDir: "/custom/data",
       port: 3040,
     } satisfies ConfigOverrides);
-    expect(backgroundFlag).toBe(true);
+    expect(startMode).toBe("background");
     expect(printed).toEqual(status);
   });
 
-  test("foreground start awaits startServer with background false", async () => {
-    let backgroundFlag: boolean | undefined;
+  test("default start uses background mode", async () => {
+    let startMode: ServerStartMode | undefined;
+    let printed: unknown;
     const ctx = baseCtx({
-      startServer: async (_opts, bg) => {
-        backgroundFlag = bg;
-        return { running: false };
+      startServer: async (_opts, mode) => {
+        startMode = mode;
+        return {
+          pid: 88,
+          port: 3020,
+          running: true,
+          runtime: "installed",
+          source: "installed",
+          url: "http://127.0.0.1:3020",
+        } satisfies RunningServerStatus;
+      },
+      printJson: (d) => {
+        printed = d;
       },
     });
 
     await handleServerStart(ctx, {});
 
-    expect(backgroundFlag).toBe(false);
+    expect(startMode).toBe("background");
+    expect(printed).toBeTruthy();
+  });
+
+  test("foreground start awaits startServer with foreground mode", async () => {
+    let startMode: ServerStartMode | undefined;
+    const ctx = baseCtx({
+      startServer: async (_opts, mode) => {
+        startMode = mode;
+        return { running: false as const };
+      },
+    });
+
+    await handleServerStart(ctx, { foreground: true });
+
+    expect(startMode).toBe("foreground");
   });
 
   test("stop prints status from stopServer", async () => {
-    const status = { running: false };
+    const status = { running: false as const };
     let printed: unknown;
     const ctx = baseCtx({
       stopServer: async () => status,

package/src/cli/handlers/server.ts

@@ -1,23 +1,36 @@
+import { CLI_ERR } from "../types/errors";
+import { CliError } from "../lib/output";
 import type { CliContext } from "./context";
 
 export async function handleServerStart(
   ctx: CliContext,
   options: {
     background?: boolean;
+    foreground?: boolean;
     dataDir?: string;
   },
 ): Promise<void> {
   const port = ctx.resolvePort();
   const dataDir = ctx.resolveDataDir({ dataDir: options.dataDir });
 
-  if (options.background) {
-    const status = await ctx.startServer({ dataDir, port }, true);
+  if (options.background && options.foreground) {
+    throw new CliError("Choose either --background or --foreground", 2, {
+      code: CLI_ERR.invalidValue,
+    });
+  }
+
+  // Default to background so `hirotm server start` stays script/agent-friendly
+  // unless the caller explicitly asks to keep logs attached.
+  const startMode = options.foreground ? "foreground" : "background";
+
+  if (startMode === "background") {
+    const status = await ctx.startServer({ dataDir, port }, startMode);
     ctx.printJson(status);
     return;
   }
 
   // Run in production mode so the installed CLI uses a stable home data directory by default.
-  await ctx.startServer({ dataDir, port }, false);
+  await ctx.startServer({ dataDir, port }, startMode);
 }
 
 export async function handleServerStatus(ctx: CliContext): Promise<void> {

package/src/cli/lib/api-client.test.ts

@@ -5,6 +5,7 @@ import {
   fetchApiMutate,
   fetchApiTrashMutate,
   fetchHealth,
+  fetchHealthStatus,
 } from "./api-client";
 import { CliError } from "./output";
 
@@ -200,7 +201,14 @@ describe("api-client (mock fetch)", () => {
 
   test("fetchHealth true when ok JSON", async () => {
     setMockFetch(async () =>
-      new Response(JSON.stringify({ ok: true }), {
+      new Response(JSON.stringify({
+        pid: 4321,
+        port: 20000,
+        running: true,
+        runtime: "installed",
+        source: "installed",
+        url: "http://127.0.0.1:20000",
+      }), {
         status: 200,
         headers: { "content-type": "application/json" },
       }),
@@ -209,9 +217,34 @@ describe("api-client (mock fetch)", () => {
     await expect(fetchHealth({ port: 20000 })).resolves.toBe(true);
   });
 
+  test("fetchHealthStatus returns runtime/source metadata when provided", async () => {
+    setMockFetch(async () =>
+      new Response(JSON.stringify({
+        pid: 12345,
+        port: 20000,
+        running: true,
+        runtime: "installed",
+        source: "repo",
+        url: "http://127.0.0.1:20000",
+      }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    await expect(fetchHealthStatus({ port: 20000 })).resolves.toEqual({
+      pid: 12345,
+      port: 20000,
+      running: true,
+      runtime: "installed",
+      source: "repo",
+      url: "http://127.0.0.1:20000",
+    });
+  });
+
   test("fetchHealth false when not ok", async () => {
     setMockFetch(async () =>
-      new Response(JSON.stringify({ ok: false }), {
+      new Response(JSON.stringify({ running: false }), {
         status: 200,
         headers: { "content-type": "application/json" },
       }),

package/src/cli/lib/api-client.ts

@@ -23,6 +23,7 @@ import { CLI_DEFAULTS } from "./constants";
 import { CLI_ERR } from "../types/errors";
 import { mapHttpStatusToCliFailure } from "./cli-http-errors";
 import { CliError } from "./output";
+import type { RunningServerStatus } from "../../shared/serverStatus";
 
 /** Uses `CLI_DEFAULTS.API_FETCH_TIMEOUT_MS`; health polling uses short waits in `process.ts`. */
 // Aligns with docs/cli-error-handling.md: timeouts surface as exit 7 + code request_timeout.
@@ -54,16 +55,16 @@ function buildBaseUrl(overrides: ConfigOverrides = {}): string {
 }
 
 function buildStartCommand(overrides: ConfigOverrides = {}): string {
-  const command = ["hirotm", "server", "start", "--background"];
+  const command = ["hirotm", "server", "start"];
   const profile = resolveProfileName(overrides);
   const runtime = resolveRuntimeKind(overrides);
 
-  if (runtime === "dev" || profile !== "default") {
+  if (profile !== "default") {
     command.push("--profile", profile);
   }
-
-  // Port is not a CLI flag; it comes from profile config or TASKMANAGER_PORT. The shell
-  // inherits env when copy-pasting this command, so overrides still apply.
+  if (runtime === "dev") {
+    command.push("--dev");
+  }
 
   return command.join(" ");
 }
@@ -177,6 +178,8 @@ async function apiRequest<T>(
   return (await response.json()) as T;
 }
 
+export type HealthStatus = RunningServerStatus;
+
 export async function fetchApi<T>(
   endpoint: string,
   overrides: ConfigOverrides = {},
@@ -211,17 +214,47 @@ export async function fetchApiTrashMutate<T>(
   });
 }
 
-export async function fetchHealth(overrides: ConfigOverrides = {}): Promise<boolean> {
+export async function fetchHealthStatus(
+  overrides: ConfigOverrides = {},
+): Promise<HealthStatus | null> {
   const baseUrl = buildBaseUrl(overrides);
 
   try {
     const response = await fetch(`${baseUrl}/api/health`, {
       headers: taskManagerClientHeaders(),
     });
-    if (!response.ok) return false;
-    const body = (await response.json()) as { ok?: unknown };
-    return body.ok === true;
+    if (!response.ok) return null;
+    const body = (await response.json()) as {
+      pid?: unknown;
+      port?: unknown;
+      running?: unknown;
+      runtime?: unknown;
+      source?: unknown;
+      url?: unknown;
+    };
+    if (
+      typeof body.pid !== "number" ||
+      typeof body.port !== "number" ||
+      body.running !== true ||
+      (body.runtime !== "dev" && body.runtime !== "installed") ||
+      (body.source !== "repo" && body.source !== "installed") ||
+      typeof body.url !== "string"
+    ) {
+      return null;
+    }
+    return {
+      pid: body.pid,
+      port: body.port,
+      running: true,
+      runtime: body.runtime,
+      source: body.source,
+      url: body.url,
+    };
   } catch {
-    return false;
+    return null;
   }
 }
+
+export async function fetchHealth(overrides: ConfigOverrides = {}): Promise<boolean> {
+  return (await fetchHealthStatus(overrides))?.running === true;
+}

package/src/cli/lib/cli-http-errors.test.ts

@@ -1,85 +1,85 @@
-import { describe, expect, test } from "bun:test";
-import { CLI_ERR } from "../types/errors";
-import { enrichNotFoundError, mapHttpStatusToCliFailure } from "./cli-http-errors";
-import { CliError } from "./output";
-
-describe("mapHttpStatusToCliFailure", () => {
-  test.each([
-    [400, CLI_ERR.badRequest, 9, undefined],
-    [401, CLI_ERR.unauthenticated, 10, undefined],
-    [403, CLI_ERR.forbidden, 4, undefined],
-    [404, CLI_ERR.notFound, 3, undefined],
-    [408, CLI_ERR.requestTimeout, 7, true],
-    [409, CLI_ERR.conflict, 5, undefined],
-    [422, CLI_ERR.badRequest, 9, undefined],
-    [426, CLI_ERR.versionMismatch, 8, undefined],
-    [429, CLI_ERR.rateLimited, 1, true],
-    [502, CLI_ERR.internalError, 1, true],
-    [418, CLI_ERR.httpError, 1, undefined],
-  ] as const)(
-    "status %i → code %s exit %i retryable %j",
-    (status, code, exit, retryable) => {
-      const { exitCode, details } = mapHttpStatusToCliFailure(status, {
-        status,
-        url: "http://127.0.0.1:1/api/x",
-      });
-      expect(exitCode).toBe(exit);
-      expect(details.code).toBe(code);
-      if (retryable === undefined) {
-        expect(details.retryable).toBeUndefined();
-      } else {
-        expect(details.retryable).toBe(retryable);
-      }
-    },
-  );
-
-  test("599 maps to internal_error (5xx branch)", () => {
-    const { exitCode, details } = mapHttpStatusToCliFailure(599, { status: 599 });
-    expect(exitCode).toBe(1);
-    expect(details.code).toBe(CLI_ERR.internalError);
-    expect(details.retryable).toBe(true);
-  });
-
-  test("preserves API code as serverCode, not duplicate top-level code", () => {
-    const { details } = mapHttpStatusToCliFailure(400, {
-      code: "CUSTOM",
-      status: 400,
-    });
-    expect(details.code).toBe(CLI_ERR.badRequest);
-    expect(details.serverCode).toBe("CUSTOM");
-    expect((details as Record<string, unknown>).code).toBe(CLI_ERR.badRequest);
-  });
-
-  test("non-string code in body is ignored for serverCode", () => {
-    const { details } = mapHttpStatusToCliFailure(404, {
-      code: 123,
-      status: 404,
-    } as Record<string, unknown>);
-    expect(details.serverCode).toBeUndefined();
-  });
-});
-
-describe("enrichNotFoundError", () => {
-  test("merges context when details.code is not_found", () => {
-    const err = new CliError("Whatever", 3, { code: CLI_ERR.notFound });
-    try {
-      enrichNotFoundError(err, { board: "my-board", taskId: 9 });
-      expect.unreachable();
-    } catch (e) {
-      expect(e).toBeInstanceOf(CliError);
-      const c = e as CliError;
-      expect(c.message).toBe("Whatever");
-      expect(c.exitCode).toBe(3);
-      expect(c.details).toMatchObject({
-        code: CLI_ERR.notFound,
-        board: "my-board",
-        taskId: 9,
-      });
-    }
-  });
-
-  test("rethrows unchanged when code is not not_found", () => {
-    const err = new CliError("Nope", 4, { code: CLI_ERR.forbidden });
-    expect(() => enrichNotFoundError(err, { board: "x" })).toThrow(err);
-  });
-});
+import { describe, expect, test } from "bun:test";
+import { CLI_ERR } from "../types/errors";
+import { enrichNotFoundError, mapHttpStatusToCliFailure } from "./cli-http-errors";
+import { CliError } from "./output";
+
+describe("mapHttpStatusToCliFailure", () => {
+  test.each([
+    [400, CLI_ERR.badRequest, 9, undefined],
+    [401, CLI_ERR.unauthenticated, 10, undefined],
+    [403, CLI_ERR.forbidden, 4, undefined],
+    [404, CLI_ERR.notFound, 3, undefined],
+    [408, CLI_ERR.requestTimeout, 7, true],
+    [409, CLI_ERR.conflict, 5, undefined],
+    [422, CLI_ERR.badRequest, 9, undefined],
+    [426, CLI_ERR.versionMismatch, 8, undefined],
+    [429, CLI_ERR.rateLimited, 1, true],
+    [502, CLI_ERR.internalError, 1, true],
+    [418, CLI_ERR.httpError, 1, undefined],
+  ] as const)(
+    "status %i → code %s exit %i retryable %j",
+    (status, code, exit, retryable) => {
+      const { exitCode, details } = mapHttpStatusToCliFailure(status, {
+        status,
+        url: "http://127.0.0.1:1/api/x",
+      });
+      expect(exitCode).toBe(exit);
+      expect(details.code).toBe(code);
+      if (retryable === undefined) {
+        expect(details.retryable).toBeUndefined();
+      } else {
+        expect(details.retryable).toBe(retryable);
+      }
+    },
+  );
+
+  test("599 maps to internal_error (5xx branch)", () => {
+    const { exitCode, details } = mapHttpStatusToCliFailure(599, { status: 599 });
+    expect(exitCode).toBe(1);
+    expect(details.code).toBe(CLI_ERR.internalError);
+    expect(details.retryable).toBe(true);
+  });
+
+  test("preserves API code as serverCode, not duplicate top-level code", () => {
+    const { details } = mapHttpStatusToCliFailure(400, {
+      code: "CUSTOM",
+      status: 400,
+    });
+    expect(details.code).toBe(CLI_ERR.badRequest);
+    expect(details.serverCode).toBe("CUSTOM");
+    expect((details as Record<string, unknown>).code).toBe(CLI_ERR.badRequest);
+  });
+
+  test("non-string code in body is ignored for serverCode", () => {
+    const { details } = mapHttpStatusToCliFailure(404, {
+      code: 123,
+      status: 404,
+    } as Record<string, unknown>);
+    expect(details.serverCode).toBeUndefined();
+  });
+});
+
+describe("enrichNotFoundError", () => {
+  test("merges context when details.code is not_found", () => {
+    const err = new CliError("Whatever", 3, { code: CLI_ERR.notFound });
+    try {
+      enrichNotFoundError(err, { board: "my-board", taskId: 9 });
+      expect.unreachable();
+    } catch (e) {
+      expect(e).toBeInstanceOf(CliError);
+      const c = e as CliError;
+      expect(c.message).toBe("Whatever");
+      expect(c.exitCode).toBe(3);
+      expect(c.details).toMatchObject({
+        code: CLI_ERR.notFound,
+        board: "my-board",
+        taskId: 9,
+      });
+    }
+  });
+
+  test("rethrows unchanged when code is not not_found", () => {
+    const err = new CliError("Nope", 4, { code: CLI_ERR.forbidden });
+    expect(() => enrichNotFoundError(err, { board: "x" })).toThrow(err);
+  });
+});