@hiroleague/taskmanager 0.0.1 → 0.0.3

package/src/cli/lib/command-helpers.ts

@@ -1,154 +1,161 @@
-import { Command } from "commander";
-import { CLI_DEFAULTS } from "./constants";
-import { CLI_ERR } from "../types/errors";
-import { getCliOutputFormat, getCliQuiet } from "./cliFormat";
-import { CliError, exitWithError } from "./output";
-
-/** Shared Commander option helpers — Phase 1 CLI split from monolithic index.ts. */
-
-/** Help text for read/list `--fields` (subset projection; see `jsonFieldProjection.ts` allowlists). */
-export const CLI_FIELDS_OPTION_DESC =
-  "Comma-separated API keys per row (unknown keys exit 2); use with global --format ndjson, not human tables.";
-
-/** `boards describe --entities`: list,group,priority,release,status,meta — order controls CLI stdout (and HTTP when subset). */
-export const CLI_BOARD_DESCRIBE_ENTITIES_DESC =
-  "Comma-separated: list,group,priority,release,status,meta (omit for default five sections, no meta). Board + cliPolicy always in JSON; duplicate or unknown tokens exit 2; board is not a token.";
-
-/** Guarded deletes / structure replaces: paired with `confirmMutableAction` in handlers. */
-export const CLI_YES_OPTION_DESC = "Skip the confirmation prompt";
-
-/** Attach `-y` / `--yes` for commands that call `confirmMutableAction`. */
-export function addYesOption(command: Command): Command {
-  return command.option("-y, --yes", CLI_YES_OPTION_DESC);
-}
-
-/** Human tables cannot apply arbitrary `--fields`; enforce before fetch. */
-export function requireNdjsonWhenUsingFields(
-  fieldKeys: string[] | undefined,
-): void {
-  if (
-    fieldKeys != null &&
-    fieldKeys.length > 0 &&
-    getCliOutputFormat() === "human"
-  ) {
-    throw new CliError("--fields requires global --format ndjson", 2, {
-      code: CLI_ERR.invalidValue,
-    });
-  }
-}
-
-/** Pipe-friendly `--quiet` stdout is not JSON; same constraint as `--fields` vs human tables. */
-export function requireNdjsonWhenQuiet(): void {
-  if (getCliQuiet() && getCliOutputFormat() === "human") {
-    throw new CliError("--quiet requires global --format ndjson", 2, {
-      code: CLI_ERR.invalidValue,
-    });
-  }
-}
-
-/**
- * With global `--quiet`, `--fields` may supply exactly one key (that column per line).
- * Multiple keys are ambiguous for single-column output.
- */
-export function resolveQuietExplicitField(
-  fieldKeys: string[] | undefined,
-): string | undefined {
-  if (!getCliQuiet() || fieldKeys == null || fieldKeys.length === 0) {
-    return undefined;
-  }
-  if (fieldKeys.length > 1) {
-    throw new CliError("--quiet allows at most one --fields key", 2, {
-      code: CLI_ERR.invalidValue,
-    });
-  }
-  return fieldKeys[0];
-}
-
-/** Attach `--client-name` for commands that call the HTTP API (mutations send the label). */
-export function addClientNameOption(command: Command): Command {
-  return command.option(
-    "--client-name <name>",
-    "Human-friendly client label sent with API requests (for notifications)",
-  );
-}
-
-export function addProfileOption(command: Command): Command {
-  return command.option(
-    "--profile <name>",
-    "Runtime profile name for this command",
-  );
-}
-
-export function parsePortOption(port: string | undefined): number | undefined {
-  if (!port?.trim()) return undefined;
-
-  const parsed = Number(port);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new CliError("Invalid port", 2, { code: CLI_ERR.invalidValue, port });
-  }
-
-  return parsed;
-}
-
-export function collectMultiValue(
-  value: string,
-  previous: string[] = [],
-): string[] {
-  return [
-    ...previous,
-    ...value
-      .split(",")
-      .map((entry) => entry.trim())
-      .filter((entry) => entry.length > 0),
-  ];
-}
-
-/** Search: default and cap from `CLI_DEFAULTS` (same max as optional list page-all). */
-export function parseLimitOption(limit: string | undefined): number {
-  if (limit == null || limit === "") return CLI_DEFAULTS.DEFAULT_SEARCH_LIMIT;
-  const n = Number(limit);
-  if (!Number.isInteger(n) || n < 1) {
-    throw new CliError("Invalid limit", 2, { code: CLI_ERR.invalidValue, limit });
-  }
-  return Math.min(CLI_DEFAULTS.MAX_PAGE_LIMIT, n);
-}
-
-/** Optional list limit for tasks/trash/boards/releases; omit = no `limit` param (one full page). */
-export function parseOptionalListLimit(
-  limit: string | undefined,
-): number | null {
-  if (limit == null || limit === "") return null;
-  const n = Number(limit);
-  if (!Number.isInteger(n) || n < 1) {
-    throw new CliError("Invalid limit", 2, { code: CLI_ERR.invalidValue, limit });
-  }
-  return Math.min(CLI_DEFAULTS.MAX_PAGE_LIMIT, n);
-}
-
-export function parseOptionalOffset(offset: string | undefined): number {
-  if (offset == null || offset === "") return 0;
-  const n = Number(offset);
-  if (!Number.isInteger(n) || n < 0) {
-    throw new CliError("Invalid offset", 2, { code: CLI_ERR.invalidValue, offset });
-  }
-  return n;
-}
-
-/** Wrap handler execution so Commander actions share one exit path (Phase 2). */
-export async function withCliErrors(fn: () => Promise<void>): Promise<void> {
-  try {
-    await fn();
-  } catch (error) {
-    exitWithError(error);
-  }
-}
-
-/**
- * Commander `.action()` helper: runs the handler inside {@link withCliErrors} so
- * subcommands cannot forget the shared exit path (see cli-architecture-review item 14).
- */
-export function cliAction<A extends unknown[]>(
-  fn: (...args: A) => Promise<void>,
-): (...args: A) => Promise<void> {
-  return (...args: A) => withCliErrors(() => fn(...args));
-}
+import { Command } from "commander";
+import { CLI_DEFAULTS } from "./constants";
+import { CLI_ERR } from "../types/errors";
+import { getCliOutputFormat, getCliQuiet } from "./cliFormat";
+import { CliError, exitWithError } from "./output";
+
+/** Shared Commander option helpers — Phase 1 CLI split from monolithic index.ts. */
+
+/** Help text for read/list `--fields` (subset projection; see `jsonFieldProjection.ts` allowlists). */
+export const CLI_FIELDS_OPTION_DESC =
+  "Comma-separated API keys per row (unknown keys exit 2); use with global --format ndjson, not human tables.";
+
+/** `boards describe --entities`: list,group,priority,release,status,meta — order controls CLI stdout (and HTTP when subset). */
+export const CLI_BOARD_DESCRIBE_ENTITIES_DESC =
+  "Comma-separated: list,group,priority,release,status,meta (omit for default five sections, no meta). Board + cliPolicy always in JSON; duplicate or unknown tokens exit 2; board is not a token.";
+
+/** Guarded deletes / structure replaces: paired with `confirmMutableAction` in handlers. */
+export const CLI_YES_OPTION_DESC = "Skip the confirmation prompt";
+
+/** Attach `-y` / `--yes` for commands that call `confirmMutableAction`. */
+export function addYesOption(command: Command): Command {
+  return command.option("-y, --yes", CLI_YES_OPTION_DESC);
+}
+
+/** Human tables cannot apply arbitrary `--fields`; enforce before fetch. */
+export function requireNdjsonWhenUsingFields(
+  fieldKeys: string[] | undefined,
+): void {
+  if (
+    fieldKeys != null &&
+    fieldKeys.length > 0 &&
+    getCliOutputFormat() === "human"
+  ) {
+    throw new CliError("--fields requires global --format ndjson", 2, {
+      code: CLI_ERR.invalidValue,
+    });
+  }
+}
+
+/** Pipe-friendly `--quiet` stdout is not JSON; same constraint as `--fields` vs human tables. */
+export function requireNdjsonWhenQuiet(): void {
+  if (getCliQuiet() && getCliOutputFormat() === "human") {
+    throw new CliError("--quiet requires global --format ndjson", 2, {
+      code: CLI_ERR.invalidValue,
+    });
+  }
+}
+
+/**
+ * With global `--quiet`, `--fields` may supply exactly one key (that column per line).
+ * Multiple keys are ambiguous for single-column output.
+ */
+export function resolveQuietExplicitField(
+  fieldKeys: string[] | undefined,
+): string | undefined {
+  if (!getCliQuiet() || fieldKeys == null || fieldKeys.length === 0) {
+    return undefined;
+  }
+  if (fieldKeys.length > 1) {
+    throw new CliError("--quiet allows at most one --fields key", 2, {
+      code: CLI_ERR.invalidValue,
+    });
+  }
+  return fieldKeys[0];
+}
+
+/** Attach `--client-name` for commands that call the HTTP API (mutations send the label). */
+export function addClientNameOption(command: Command): Command {
+  return command.option(
+    "--client-name <name>",
+    "Human-friendly client label sent with API requests (for notifications)",
+  );
+}
+
+export function addProfileOption(command: Command): Command {
+  return command.option(
+    "--profile <name>",
+    "Runtime profile name for this command",
+  );
+}
+
+export function addDevOption(command: Command): Command {
+  return command.option(
+    "--dev",
+    "Run in dev mode (API-only with dev CORS, port 3002 default)",
+  );
+}
+
+export function parsePortOption(port: string | undefined): number | undefined {
+  if (!port?.trim()) return undefined;
+
+  const parsed = Number(port);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new CliError("Invalid port", 2, { code: CLI_ERR.invalidValue, port });
+  }
+
+  return parsed;
+}
+
+export function collectMultiValue(
+  value: string,
+  previous: string[] = [],
+): string[] {
+  return [
+    ...previous,
+    ...value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0),
+  ];
+}
+
+/** Search: default and cap from `CLI_DEFAULTS` (same max as optional list page-all). */
+export function parseLimitOption(limit: string | undefined): number {
+  if (limit == null || limit === "") return CLI_DEFAULTS.DEFAULT_SEARCH_LIMIT;
+  const n = Number(limit);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError("Invalid limit", 2, { code: CLI_ERR.invalidValue, limit });
+  }
+  return Math.min(CLI_DEFAULTS.MAX_PAGE_LIMIT, n);
+}
+
+/** Optional list limit for tasks/trash/boards/releases; omit = no `limit` param (one full page). */
+export function parseOptionalListLimit(
+  limit: string | undefined,
+): number | null {
+  if (limit == null || limit === "") return null;
+  const n = Number(limit);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError("Invalid limit", 2, { code: CLI_ERR.invalidValue, limit });
+  }
+  return Math.min(CLI_DEFAULTS.MAX_PAGE_LIMIT, n);
+}
+
+export function parseOptionalOffset(offset: string | undefined): number {
+  if (offset == null || offset === "") return 0;
+  const n = Number(offset);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new CliError("Invalid offset", 2, { code: CLI_ERR.invalidValue, offset });
+  }
+  return n;
+}
+
+/** Wrap handler execution so Commander actions share one exit path (Phase 2). */
+export async function withCliErrors(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+  } catch (error) {
+    exitWithError(error);
+  }
+}
+
+/**
+ * Commander `.action()` helper: runs the handler inside {@link withCliErrors} so
+ * subcommands cannot forget the shared exit path (see cli-architecture-review item 14).
+ */
+export function cliAction<A extends unknown[]>(
+  fn: (...args: A) => Promise<void>,
+): (...args: A) => Promise<void> {
+  return (...args: A) => withCliErrors(() => fn(...args));
+}

package/src/cli/lib/config.ts

@@ -28,6 +28,10 @@ export function setRuntimeProfile(profile: string | undefined): void {
   setRuntimeConfigSelection({ profile });
 }
 
+export function setRuntimeCliPort(port: number | undefined): void {
+  setRuntimeConfigSelection({ port });
+}
+
 export function setRuntimeKind(kind: RuntimeKind | undefined): void {
   setRuntimeConfigSelection({ kind });
 }

package/src/cli/lib/launcherUi.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { printSetupContinuePrompt, printSetupNextSteps } from "./launcherUi";
+
+async function captureConsoleLog(
+  run: () => Promise<void> | void,
+): Promise<string> {
+  const originalLog = console.log;
+  const lines: string[] = [];
+  console.log = (...args: unknown[]) => {
+    lines.push(args.map(String).join(" "));
+  };
+  try {
+    await run();
+  } finally {
+    console.log = originalLog;
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+describe("printSetupNextSteps", () => {
+  test("prints a prominent table with required repo skills install guidance", async () => {
+    const stdout = await captureConsoleLog(async () => {
+      printSetupNextSteps({
+        profileName: "default",
+        skillsInstalled: false,
+      });
+    });
+
+    expect(stdout).toContain("+-");
+    expect(stdout).toContain("REQUIRED BEFORE USING hirotm");
+    expect(stdout).toContain("Install AI agent skills now. The hirotm CLI depends on these skills.");
+    expect(stdout).toContain("hirotm --help");
+    expect(stdout).toContain("1. Repo skills  : npx skills add hiro-league/hirotaskmanager");
+    expect(stdout).toContain("2. Update later : npx skills update");
+    expect(stdout).toContain("npx skills add hiro-league/hirotaskmanager");
+    expect(stdout).not.toContain("npx skills add \"$HOME/.taskmanager/skills\"");
+  });
+
+  test("prints local skills command when bundled skills were copied", async () => {
+    const stdout = await captureConsoleLog(async () => {
+      printSetupNextSteps({
+        profileName: "default",
+        skillsInstalled: true,
+      });
+    });
+
+    expect(stdout).toContain("npx skills add hiro-league/hirotaskmanager");
+    expect(stdout).toContain("2. Local skills : npx skills add \"$HOME/.taskmanager/skills\"");
+    expect(stdout).toContain("3. Update later : npx skills update");
+    expect(stdout).toContain("npx skills add \"$HOME/.taskmanager/skills\"");
+    expect(stdout).toContain("npx skills update");
+  });
+
+  test("prints profile-specific CLI guidance for named profiles", async () => {
+    const stdout = await captureConsoleLog(async () => {
+      printSetupNextSteps({
+        profileName: "work",
+        skillsInstalled: false,
+      });
+    });
+
+    expect(stdout).toContain("hirotm --profile work --help");
+  });
+});
+
+describe("printSetupContinuePrompt", () => {
+  test("prints a separate enter-to-continue message", async () => {
+    const stdout = await captureConsoleLog(() => {
+      printSetupContinuePrompt();
+    });
+
+    expect(stdout).toContain("Press Enter to continue and start TaskManager...");
+  });
+});

package/src/cli/lib/launcherUi.ts

@@ -0,0 +1,213 @@
+/**
+ * hirotaskmanager interactive setup: compact prompts, inline spinners, and colored values.
+ * Uses ANSI only when stdout is a TTY and NO_COLOR is unset.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { ansi, paint } from "../../shared/terminalColors";
+
+const out = process.stdout;
+const SPINNER_FRAMES = ["-", "\\", "|", "/"] as const;
+const SPINNER_INTERVAL_MS = 100;
+const DEFAULT_SPINNER_MS = 900;
+
+function line(text = ""): void {
+  console.log(text);
+}
+
+function clearInline(): void {
+  if (typeof out.clearLine === "function" && typeof out.cursorTo === "function") {
+    out.clearLine(0);
+    out.cursorTo(0);
+  }
+}
+
+function writeInline(text: string): void {
+  clearInline();
+  out.write(text);
+}
+
+export function paintValue(value: string | number | boolean): string {
+  return paint(out, String(value), ansi.bold + ansi.cyan);
+}
+
+function paintSuccess(text: string): string {
+  return paint(out, text, ansi.bold + ansi.green);
+}
+
+function paintWarning(text: string): string {
+  return paint(out, text, ansi.bold + ansi.yellow);
+}
+
+function printAsciiTable(lines: readonly string[]): void {
+  const innerWidth = Math.max(76, ...lines.map((line) => line.length));
+  const border = `  +-${"-".repeat(innerWidth)}-+`;
+  line();
+  line(border);
+  for (const entry of lines) {
+    line(`  | ${entry.padEnd(innerWidth)} |`);
+  }
+  line(border);
+  line();
+}
+
+export type SpinnerHandle = {
+  stop: (finalText?: string | null) => void;
+};
+
+export function startInlineSpinner(message: string): SpinnerHandle {
+  if (!out.isTTY) {
+    line(message);
+    return {
+      stop(finalText?: string | null): void {
+        if (finalText) line(finalText);
+      },
+    };
+  }
+
+  let frameIndex = 0;
+  let stopped = false;
+  writeInline(`${message} ${paint(out, SPINNER_FRAMES[frameIndex], ansi.dim)}`);
+  const timer = setInterval(() => {
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+    writeInline(`${message} ${paint(out, SPINNER_FRAMES[frameIndex], ansi.dim)}`);
+  }, SPINNER_INTERVAL_MS);
+
+  return {
+    stop(finalText?: string | null): void {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      clearInline();
+      if (finalText) out.write(`${finalText}\n`);
+    },
+  };
+}
+
+export async function spinForMoment(
+  message: string,
+  finalText = message,
+  durationMs = DEFAULT_SPINNER_MS,
+): Promise<void> {
+  const spinner = startInlineSpinner(message);
+  await Bun.sleep(durationMs);
+  spinner.stop(finalText);
+}
+
+export function formatTextPrompt(label: string, defaultValue: string): string {
+  return `${label}: ${paintValue(`[${defaultValue}]`)}`;
+}
+
+export function formatBooleanPrompt(
+  label: string,
+  defaultValue: boolean,
+): string {
+  return `${label} ${paintValue(`[${defaultValue ? "Y/n" : "y/N"}]`)}`;
+}
+
+export function printInteractiveSetupHeader(opts: {
+  profileName: string;
+  firstProfileOnMachine: boolean;
+}): void {
+  // Keep the setup header to one line so first run stays dense and scannable.
+  line(
+    paint(
+      out,
+      opts.firstProfileOnMachine
+        ? "Hiro Task Manager - First-time Setup..."
+        : `Hiro Task Manager - Profile Setup: ${opts.profileName}`,
+      ansi.bold + ansi.cyan,
+    ),
+  );
+}
+
+export function printSavedProfileSummary(opts: {
+  created: boolean;
+  profileName: string;
+  appUrl: string;
+  dataDir: string;
+  openBrowser: boolean;
+}): void {
+  line(
+    `${opts.created ? paintSuccess("Profile Created:") : paintSuccess("Profile Saved:")} ${paintValue(opts.profileName)}`,
+  );
+  line(`  ${paintWarning("App URL:")}      ${paintValue(opts.appUrl)}`);
+  line(`  ${paintWarning("Data Path:")}    ${paintValue(opts.dataDir)}`);
+  line(
+    `  ${paintWarning("Open Browser:")} ${paintValue(opts.openBrowser ? "Yes" : "No")}`,
+  );
+}
+
+export function printSetupNextSteps(opts: {
+  profileName: string;
+  skillsInstalled: boolean;
+}): void {
+  const cliHelpCommand =
+    opts.profileName === "default"
+      ? "hirotm --help"
+      : `hirotm --profile ${opts.profileName} --help`;
+  const skillLines = [
+    "1. Repo skills  : npx skills add hiro-league/hirotaskmanager",
+  ];
+  if (opts.skillsInstalled) {
+    skillLines.push("2. Local skills : npx skills add \"$HOME/.taskmanager/skills\"");
+    skillLines.push("3. Update later : npx skills update");
+  } else {
+    skillLines.push("2. Update later : npx skills update");
+  }
+  const lines = [
+    "REQUIRED BEFORE USING hirotm",
+    "Install AI agent skills now. The hirotm CLI depends on these skills.",
+    "",
+    ...skillLines,
+    "",
+    `After skills install: ${cliHelpCommand}`,
+  ];
+
+  // Package managers may block postinstall hooks, so setup must surface the
+  // exact skills commands in a standalone table before startup continues.
+  printAsciiTable(lines);
+}
+
+export function printSetupContinuePrompt(): void {
+  line("Press Enter to continue and start TaskManager...");
+}
+
+export async function printPassphraseHint(): Promise<void> {
+  // Keep the browser handoff to one line because the recovery key prints later from the server.
+  const text =
+    "Create your passphrase in the browser. Your recovery key prints here once.";
+  await spinForMoment(text, text);
+}
+
+export function printRecoveryKey(recoveryKey: string): void {
+  line();
+  line(paintWarning("Recovery Key:"));
+  line(paintValue(recoveryKey));
+  line(
+    paint(
+      out,
+      "Store it on a separate device. It will never show again.",
+      ansi.dim,
+    ),
+  );
+  line(
+    paint(
+      out,
+      "Use it to recover your passphrase and access your server/data.",
+      ansi.dim,
+    ),
+  );
+  line();
+}
+
+export function printRecoveryKeyExitHint(appUrl: string): void {
+  // Explain why Enter returns to the shell without implying the server is stopping.
+  line(
+    `After you copy the recovery key, press Enter to close this launcher. TaskManager stays running at ${paintValue(appUrl)}.`,
+  );
+}
+
+export function isAuthInitialized(authDir: string): boolean {
+  return existsSync(path.join(authDir, "auth.json"));
+}