@hiroleague/taskmanager 0.0.1 → 0.0.3

package/src/cli/bootstrap/launcher.ts

@@ -1,8 +1,13 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { Command } from "commander";
-import { ensureRuntimeDirectories } from "../../shared/runtimeConfig";
+import {
+  ensureRuntimeDirectories,
+  hasAnyProfileConfigOnDisk,
+} from "../../shared/runtimeConfig";
+import { ensureBundledSkills } from "../../shared/skillsInstall";
 import {
   getDefaultInstalledAuthDir,
   getDefaultInstalledDataDir,
@@ -16,8 +21,24 @@ import { parsePortOption } from "../lib/command-helpers";
 import { CLI_ERR } from "../types/errors";
 import { CLI_DEFAULTS } from "../lib/constants";
 import { CliError, exitWithError } from "../lib/output";
-import { startServer } from "../lib/process";
+import { readServerStatus, startServer, stopServer } from "../lib/process";
 import { canPromptInteractively } from "../lib/tty";
+import type { ServerStartMode } from "../ports/process";
+import {
+  formatBooleanPrompt,
+  formatTextPrompt,
+  isAuthInitialized,
+  paintValue,
+  printSetupContinuePrompt,
+  printSetupNextSteps,
+  printPassphraseHint,
+  printRecoveryKey,
+  printRecoveryKeyExitHint,
+  printInteractiveSetupHeader,
+  printSavedProfileSummary,
+  spinForMoment,
+  startInlineSpinner,
+} from "../lib/launcherUi";
 
 /** Phase 3: installed-app launcher logic (formerly all of app.ts). */
 
@@ -28,6 +49,50 @@ interface LauncherOptions {
   profile?: string;
 }
 
+interface LauncherServerOptions {
+  profile?: string;
+}
+
+interface LauncherServerStartOptions extends LauncherServerOptions {
+  dataDir?: string;
+  foreground?: boolean;
+}
+
+export interface LauncherSetupResult {
+  config: CliConfigFile;
+  setupMeta: {
+    /** User went through interactive prompts (not bunx / non-TTY defaults). */
+    justFinishedInteractiveSetup: boolean;
+    /** No profile had config.json on disk before this run’s save. */
+    firstProfileOnMachine: boolean;
+  };
+}
+
+export function resolveLauncherStartPlan(options: {
+  shouldRunSetup: boolean;
+  needsRecoveryKeyExitFlow: boolean;
+  alreadyRunning: boolean;
+  shouldOpenBrowser: boolean;
+  preferForegroundWhenNotSetup?: boolean;
+}): {
+  startMode: ServerStartMode;
+  readyLabel: "Started" | "Already started";
+  shouldOpenBrowserOnReady: boolean;
+} {
+  return {
+    startMode: options.shouldRunSetup
+      ? options.needsRecoveryKeyExitFlow
+        ? "background-attached"
+        : "foreground"
+      : options.preferForegroundWhenNotSetup
+        ? "foreground"
+        : "background",
+    readyLabel: options.alreadyRunning ? "Already started" : "Started",
+    shouldOpenBrowserOnReady:
+      options.shouldOpenBrowser && !options.alreadyRunning,
+  };
+}
+
 function parseBrowserMode(browser: string | undefined): boolean | undefined {
   if (!browser?.trim()) return undefined;
 
@@ -83,7 +148,7 @@ async function promptWithDefault(
     output: process.stdout,
   });
   try {
-    const answer = await rl.question(`${question} [${defaultValue}]: `);
+    const answer = await rl.question(`${question} `);
     return answer.trim() || defaultValue;
   } finally {
     rl.close();
@@ -94,14 +159,13 @@ async function promptBoolean(
   question: string,
   defaultValue: boolean,
 ): Promise<boolean> {
-  const label = defaultValue ? "Y/n" : "y/N";
   const rl = createInterface({
     input: process.stdin,
     output: process.stdout,
   });
   try {
     for (;;) {
-      const answer = (await rl.question(`${question} [${label}]: `))
+      const answer = (await rl.question(`${question}: `))
         .trim()
         .toLowerCase();
       if (!answer) return defaultValue;
@@ -119,10 +183,11 @@ async function runLauncherSetup(overrides: {
   port?: number;
   dataDir?: string;
   openBrowser?: boolean;
-}): Promise<CliConfigFile> {
+}): Promise<LauncherSetupResult> {
   const defaults = resolveLauncherDefaults(overrides);
   const configScope = { profile: overrides.profile, kind: "installed" as const };
   const existing = readConfigFile(configScope);
+  const machineHadNoProfilesBefore = !hasAnyProfileConfigOnDisk();
 
   // Keep the first-run path working for bunx and other non-interactive entry
   // points by saving sane defaults instead of failing on missing prompts.
@@ -134,18 +199,47 @@ async function runLauncherSetup(overrides: {
       dataDir: config.data_dir,
       authDir: config.auth_dir,
     });
-    return config;
+    return {
+      config,
+      setupMeta: {
+        justFinishedInteractiveSetup: false,
+        firstProfileOnMachine: machineHadNoProfilesBefore,
+      },
+    };
   }
 
-  console.log("TaskManager first-run setup");
+  printInteractiveSetupHeader({
+    profileName: resolveProfileName(configScope),
+    firstProfileOnMachine: machineHadNoProfilesBefore,
+  });
+
+  // Show the profile context line first so the user understands why the
+  // following prompts are being asked.
+  await spinForMoment(
+    "Looking for existing profiles...",
+    machineHadNoProfilesBefore
+      ? `Creating Profile: ${paintValue(resolveProfileName(configScope))}`
+      : `Using Profile: ${paintValue(resolveProfileName(configScope))}`,
+  );
+
+  const portValue = await promptWithDefault(
+    formatTextPrompt("Pick a port for web/api", String(defaults.port)),
+    String(defaults.port),
+  );
 
-  const portValue = await promptWithDefault("Port", String(defaults.port));
   const dataDirValue = await promptWithDefault(
-    "Data directory",
+    formatTextPrompt(
+      "Pick a Data Directory to place the database",
+      defaults.data_dir,
+    ),
     defaults.data_dir,
   );
+
   const openBrowser = await promptBoolean(
-    "Open browser automatically",
+    formatBooleanPrompt(
+      "Open default browser when starting the server with hirotaskmanager",
+      defaults.open_browser,
+    ),
     defaults.open_browser,
   );
 
@@ -156,14 +250,34 @@ async function runLauncherSetup(overrides: {
     auth_dir: defaults.auth_dir,
     open_browser: openBrowser,
   };
-  const savedPath = writeConfigFile(config, configScope);
+  writeConfigFile(config, configScope);
   ensureRuntimeDirectories({
     ...configScope,
     dataDir: config.data_dir,
     authDir: config.auth_dir,
   });
-  console.log(`Saved launcher config to ${savedPath}`);
-  return config;
+
+  await spinForMoment(
+    machineHadNoProfilesBefore
+      ? `Saving Profile: ${paintValue(resolveProfileName(configScope))}`
+      : `Saving Profile: ${paintValue(resolveProfileName(configScope))}`,
+  );
+
+  printSavedProfileSummary({
+    created: machineHadNoProfilesBefore,
+    profileName: resolveProfileName(configScope),
+    appUrl: `http://127.0.0.1:${config.port}`,
+    dataDir: path.resolve(config.data_dir!),
+    openBrowser,
+  });
+
+  return {
+    config,
+    setupMeta: {
+      justFinishedInteractiveSetup: true,
+      firstProfileOnMachine: machineHadNoProfilesBefore,
+    },
+  };
 }
 
 async function openBrowser(url: string): Promise<void> {
@@ -188,6 +302,48 @@ async function openBrowser(url: string): Promise<void> {
   }
 }
 
+/**
+ * Poll for the recovery-key sidecar file written by the server during
+ * `setupPassphrase`. Returns the key string once available, then deletes the
+ * file so it is never left on disk.
+ */
+async function waitForRecoveryKeyFile(authDir: string): Promise<string> {
+  const keyPath = path.join(authDir, "recovery-key.tmp");
+  while (!existsSync(keyPath)) {
+    await Bun.sleep(250);
+  }
+  const key = readFileSync(keyPath, "utf8").trim();
+  try {
+    unlinkSync(keyPath);
+  } catch {
+    // Best-effort cleanup; the file has owner-only perms already.
+  }
+  return key;
+}
+
+async function waitForEnterKey(): Promise<void> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    await rl.question("");
+  } finally {
+    rl.close();
+  }
+}
+
+function resolveInstalledLauncherProfile(profile: string | undefined): string {
+  return resolveProfileName({
+    profile,
+    kind: "installed",
+  });
+}
+
+function printLauncherJson(data: unknown): void {
+  process.stdout.write(`${JSON.stringify(data)}\n`);
+}
+
 export function createHirotaskmanagerProgram(): Command {
   const program = new Command();
   program
@@ -206,21 +362,46 @@ export function createHirotaskmanagerProgram(): Command {
           ? path.resolve(options.dataDir.trim())
           : undefined;
         const overrideOpenBrowser = parseBrowserMode(options.browser);
-        const selectedProfile = resolveProfileName({
-          profile: options.profile,
-          kind: "installed",
-        });
+        const selectedProfile = resolveInstalledLauncherProfile(options.profile);
 
         const shouldRunSetup =
           options.setup ||
           !hasCliConfigFile({ profile: selectedProfile, kind: "installed" });
-        const launcherConfig = shouldRunSetup
+
+        const setupResult: LauncherSetupResult = shouldRunSetup
           ? await runLauncherSetup({
               profile: selectedProfile,
               dataDir: overrideDataDir,
               openBrowser: overrideOpenBrowser,
             })
-          : readConfigFile({ profile: selectedProfile, kind: "installed" });
+          : {
+              config: readConfigFile({
+                profile: selectedProfile,
+                kind: "installed",
+              }),
+              setupMeta: {
+                justFinishedInteractiveSetup: false,
+                firstProfileOnMachine: false,
+              },
+            };
+
+        // Registry installs can skip lifecycle hooks, so setup itself must
+        // print the exact `npx skills` commands users should run next.
+        const skillsInstalled = ensureBundledSkills();
+        if (shouldRunSetup) {
+          printSetupNextSteps({
+            profileName: selectedProfile,
+            skillsInstalled,
+          });
+          if (setupResult.setupMeta.justFinishedInteractiveSetup) {
+            // Keep setup blocked here so users see the required skills step
+            // before the server starts and the browser steals focus.
+            printSetupContinuePrompt();
+            await waitForEnterKey();
+          }
+        }
+
+        const launcherConfig = setupResult.config;
 
         const port =
           launcherConfig.port ?? CLI_DEFAULTS.INSTALLED_DEFAULT_PORT;
@@ -232,32 +413,205 @@ export function createHirotaskmanagerProgram(): Command {
               kind: "installed",
             }),
         );
+        const authDir = path.resolve(
+          launcherConfig.auth_dir ??
+            getDefaultInstalledAuthDir({
+              profile: selectedProfile,
+              kind: "installed",
+            }),
+        );
         const shouldOpenBrowser =
           overrideOpenBrowser ?? launcherConfig.open_browser ?? true;
 
+        const url = `http://127.0.0.1:${port}`;
+        const needsRecoveryKeyExitFlow =
+          setupResult.setupMeta.justFinishedInteractiveSetup &&
+          !isAuthInitialized(authDir);
+        // Keep normal launcher runs non-blocking, and avoid reopening the browser
+        // when the launcher is only attaching to an already running profile.
+        const alreadyRunning = shouldRunSetup
+          ? false
+          : (
+              await readServerStatus({
+                kind: "installed",
+                profile: selectedProfile,
+                port,
+              })
+            ).running;
+        const startPlan = resolveLauncherStartPlan({
+          shouldRunSetup,
+          needsRecoveryKeyExitFlow,
+          alreadyRunning,
+          shouldOpenBrowser,
+        });
+
+        const startupSpinner = startInlineSpinner(
+          `${alreadyRunning ? "Checking Server" : "Starting Server"} with profile ${paintValue(selectedProfile)}: ${paintValue(url)}`,
+        );
+        const previousSilentStartup = process.env.TASKMANAGER_SILENT_STARTUP_LOG;
+        // Let the launcher own startup copy so first-time setup stays compact.
+        process.env.TASKMANAGER_SILENT_STARTUP_LOG = "1";
+
         let browserHandled = false;
-        await startServer(
-          {
+        let runningUrl = url;
+        try {
+          await startServer(
+            {
+              kind: "installed",
+              profile: selectedProfile,
+              port,
+              dataDir,
+            },
+            startPlan.startMode,
+            async (status) => {
+              const finalUrl = status.url;
+              runningUrl = finalUrl;
+              startupSpinner.stop(
+                `${startPlan.readyLabel}, listening at ${paintValue(finalUrl)}`,
+              );
+
+              if (!browserHandled && startPlan.shouldOpenBrowserOnReady) {
+                browserHandled = true;
+                await openBrowser(finalUrl);
+              }
+
+              if (needsRecoveryKeyExitFlow) {
+                await printPassphraseHint();
+              }
+            },
+          );
+
+          if (needsRecoveryKeyExitFlow) {
+            const recoveryKey = await waitForRecoveryKeyFile(authDir);
+            printRecoveryKey(recoveryKey);
+            printRecoveryKeyExitHint(runningUrl);
+            await waitForEnterKey();
+          }
+        } finally {
+          if (previousSilentStartup === undefined) {
+            delete process.env.TASKMANAGER_SILENT_STARTUP_LOG;
+          } else {
+            process.env.TASKMANAGER_SILENT_STARTUP_LOG = previousSilentStartup;
+          }
+          startupSpinner.stop(null);
+        }
+      } catch (error) {
+        exitWithError(error);
+      }
+    });
+
+  const server = program
+    .command("server")
+    .description("Start, stop, or inspect the installed TaskManager server");
+
+  server
+    .command("start")
+    .description("Start the installed TaskManager server")
+    .option("--profile <name>", "Launcher profile name for this command")
+    .option("--data-dir <path>", "Override the task data directory")
+    .option("--foreground", "Run the server in the foreground")
+    .action(async (options: LauncherServerStartOptions, command: Command) => {
+      try {
+        const profile = resolveInstalledLauncherProfile(
+          (command.optsWithGlobals() as LauncherServerStartOptions).profile ?? options.profile,
+        );
+        const overrideDataDir = options.dataDir?.trim()
+          ? path.resolve(options.dataDir.trim())
+          : undefined;
+        const config = readConfigFile({ profile, kind: "installed" });
+        const port = config.port ?? CLI_DEFAULTS.INSTALLED_DEFAULT_PORT;
+        const dataDir = path.resolve(
+          overrideDataDir ??
+            config.data_dir ??
+            getDefaultInstalledDataDir({ profile, kind: "installed" }),
+        );
+        const status = await readServerStatus({
+          kind: "installed",
+          profile,
+          port,
+        });
+        const startPlan = resolveLauncherStartPlan({
+          shouldRunSetup: false,
+          needsRecoveryKeyExitFlow: false,
+          alreadyRunning: status.running,
+          shouldOpenBrowser: false,
+          preferForegroundWhenNotSetup: options.foreground === true,
+        });
+        const startupSpinner = startInlineSpinner(
+          `${status.running ? "Checking Server" : "Starting Server"} with profile ${paintValue(profile)}: ${paintValue(status.running ? status.url : `http://127.0.0.1:${port}`)}`,
+        );
+
+        try {
+          // Launcher `server start` is human-facing, so prefer concise text
+          // instead of JSON while still sharing the same server lifecycle path.
+          await startServer(
+            {
+              kind: "installed",
+              profile,
+              port,
+              dataDir,
+            },
+            startPlan.startMode,
+            async (started) => {
+              startupSpinner.stop(
+                `${startPlan.readyLabel}, listening at ${paintValue(started.url)}`,
+              );
+            },
+          );
+        } finally {
+          startupSpinner.stop(null);
+        }
+      } catch (error) {
+        exitWithError(error);
+      }
+    });
+
+  server
+    .command("status")
+    .description("Show whether the installed TaskManager server is running")
+    .option("--profile <name>", "Launcher profile name for this command")
+    .action(async (options: LauncherServerOptions, command: Command) => {
+      try {
+        const profile = resolveInstalledLauncherProfile(
+          (command.optsWithGlobals() as LauncherServerOptions).profile ?? options.profile,
+        );
+        printLauncherJson(
+          await readServerStatus({
             kind: "installed",
-            profile: selectedProfile,
-            port,
-            dataDir,
-          },
-          false,
-          async (status) => {
-            const url = status.url ?? `http://127.0.0.1:${port}`;
-            console.log(`TaskManager running at ${url}`);
-            if (!browserHandled && shouldOpenBrowser) {
-              browserHandled = true;
-              await openBrowser(url);
-            }
-          },
+            profile,
+          }),
         );
       } catch (error) {
         exitWithError(error);
       }
     });
 
+  server
+    .command("stop")
+    .description("Stop a background installed server started for this profile")
+    .option("--profile <name>", "Launcher profile name for this command")
+    .action(async (options: LauncherServerOptions, command: Command) => {
+      try {
+        const profile = resolveInstalledLauncherProfile(
+          (command.optsWithGlobals() as LauncherServerOptions).profile ?? options.profile,
+        );
+        const stopSpinner = startInlineSpinner(
+          `Stopping Server with profile ${paintValue(profile)}`,
+        );
+        try {
+          await stopServer({
+            kind: "installed",
+            profile,
+          });
+          stopSpinner.stop("Server stopped");
+        } finally {
+          stopSpinner.stop(null);
+        }
+      } catch (error) {
+        exitWithError(error);
+      }
+    });
+
   return program;
 }
 

package/src/cli/bootstrap/program.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getHirotmLauncherSetupCommand,
+  shouldRequireLauncherSetupForHirotm,
+} from "./program";
+
+describe("shouldRequireLauncherSetupForHirotm", () => {
+  test("requires launcher setup for installed mode without a saved profile", () => {
+    expect(
+      shouldRequireLauncherSetupForHirotm({
+        runtimeKind: "installed",
+        hasInstalledProfileConfig: false,
+      }),
+    ).toBe(true);
+  });
+
+  test("allows installed mode once the profile config exists", () => {
+    expect(
+      shouldRequireLauncherSetupForHirotm({
+        runtimeKind: "installed",
+        hasInstalledProfileConfig: true,
+      }),
+    ).toBe(false);
+  });
+
+  test("never blocks dev mode on launcher setup", () => {
+    expect(
+      shouldRequireLauncherSetupForHirotm({
+        runtimeKind: "dev",
+        hasInstalledProfileConfig: false,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("getHirotmLauncherSetupCommand", () => {
+  test("uses the plain launcher command for the default profile", () => {
+    expect(getHirotmLauncherSetupCommand("default")).toBe("hirotaskmanager");
+  });
+
+  test("includes the selected profile for named profiles", () => {
+    expect(getHirotmLauncherSetupCommand("work")).toBe(
+      "hirotaskmanager --profile work",
+    );
+  });
+});

package/src/cli/bootstrap/program.ts

@@ -8,8 +8,56 @@ import { registerStatusCommands } from "../commands/statuses";
 import { registerTaskCommands } from "../commands/tasks";
 import { registerTrashCommands } from "../commands/trash";
 import { createDefaultCliContext } from "../handlers/context";
+import { hasCliConfigFile, resolveProfileName, resolveRuntimeKind } from "../lib/config";
 import { syncCliOutputFormatFromGlobals } from "../lib/cliFormat";
-import { exitWithError, resetCliOutputFormat } from "../lib/output";
+import { CliError, exitWithError, resetCliOutputFormat } from "../lib/output";
+import { CLI_ERR } from "../types/errors";
+
+export function shouldRequireLauncherSetupForHirotm(options: {
+  runtimeKind: "installed" | "dev";
+  hasInstalledProfileConfig: boolean;
+}): boolean {
+  return (
+    options.runtimeKind === "installed" &&
+    options.hasInstalledProfileConfig === false
+  );
+}
+
+export function getHirotmLauncherSetupCommand(profileName: string): string {
+  return profileName === "default"
+    ? "hirotaskmanager"
+    : `hirotaskmanager --profile ${profileName}`;
+}
+
+function ensureInstalledProfileIsReadyForHirotm(): void {
+  const runtimeKind = resolveRuntimeKind();
+  const profileName = resolveProfileName({ kind: "installed" });
+  const hasInstalledProfileConfig = hasCliConfigFile({
+    profile: profileName,
+    kind: "installed",
+  });
+  if (
+    !shouldRequireLauncherSetupForHirotm({
+      runtimeKind,
+      hasInstalledProfileConfig,
+    })
+  ) {
+    return;
+  }
+
+  const setupCommand = getHirotmLauncherSetupCommand(profileName);
+  // Package managers can skip lifecycle scripts, so actionable `hirotm`
+  // commands must direct users back to the launcher for first-run setup.
+  throw new CliError(
+    `No installed TaskManager profile found for "${profileName}". Run \`${setupCommand}\` first to create and configure this profile.`,
+    2,
+    {
+      code: CLI_ERR.missingRequired,
+      profile: profileName,
+      hint: `Run \`${setupCommand}\` first.`,
+    },
+  );
+}
 
 /**
  * Build the hirotm Commander program.
@@ -21,6 +69,10 @@ export function createHirotmProgram(): Command {
     .name("hirotm")
     .description("TaskManager CLI for local app control and JSON queries")
     .option("--profile <name>", "Runtime profile name (default: default, dev)")
+    .option(
+      "--port <port>",
+      "HTTP port for the local API (default: from profile config.json)",
+    )
     .option(
       "--client-name <name>",
       "Human-friendly client label sent with API requests (for notifications)",
@@ -41,6 +93,7 @@ export function createHirotmProgram(): Command {
       quiet?: boolean;
     };
     syncCliOutputFormatFromGlobals(opts);
+    ensureInstalledProfileIsReadyForHirotm();
   });
 
   const ctx = createDefaultCliContext();

package/src/cli/bootstrap/runtime.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   readClientNameArg,
+  readPortArg,
   readProfileArg,
 } from "./runtime";
 
@@ -33,3 +34,17 @@ describe("readProfileArg", () => {
     expect(readProfileArg([])).toBeUndefined();
   });
 });
+
+describe("readPortArg", () => {
+  test("parses --port value form", () => {
+    expect(readPortArg(["hirotm", "--port", "3002", "boards"])).toBe(3002);
+  });
+
+  test("parses --port=value form", () => {
+    expect(readPortArg(["--port=4000"])).toBe(4000);
+  });
+
+  test("returns undefined when absent", () => {
+    expect(readPortArg(["boards", "list"])).toBeUndefined();
+  });
+});