@tyvm/knowhow 0.0.159 → 0.0.161

package/tests/unit/clients/withRetry.test.ts

@@ -1,319 +0,0 @@
-/**
- * Unit tests for withRetry — retry, timeout, and AbortSignal behaviour.
- *
- * These tests are isolated from AIClient: they exercise the withRetry helper
- * directly using a mock async function.
- */
-import { withRetry } from "../../../src/clients/withRetry";
-
-describe("withRetry", () => {
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  // ─── Success path ────────────────────────────────────────────────────────
-
-  describe("success path", () => {
-    it("returns the result immediately when fn succeeds on the first attempt", async () => {
-      const fn = jest.fn().mockResolvedValue({ answer: 42 });
-      const result = await withRetry(fn, { maxRetries: 2 });
-      expect(result).toEqual({ answer: 42 });
-      expect(fn).toHaveBeenCalledTimes(1);
-    });
-
-    it("passes undefined signal to fn when no timeout or external signal is provided", async () => {
-      let receivedSignal: AbortSignal | undefined = "not-called" as any;
-      const fn = jest.fn().mockImplementation((signal: any) => {
-        receivedSignal = signal;
-        return Promise.resolve("ok");
-      });
-      await withRetry(fn, {});
-      expect(receivedSignal).toBeUndefined();
-    });
-
-    it("passes a signal to fn when a timeout is provided", async () => {
-      let receivedSignal: AbortSignal | undefined;
-      const fn = jest.fn().mockImplementation((signal: any) => {
-        receivedSignal = signal;
-        return Promise.resolve("ok");
-      });
-      await withRetry(fn, { timeout: 5000 });
-      expect(receivedSignal).toBeInstanceOf(AbortSignal);
-      expect(receivedSignal!.aborted).toBe(false);
-    });
-  });
-
-  // ─── Retry path ──────────────────────────────────────────────────────────
-
-  describe("retry on retriable errors", () => {
-    it("retries on a 429 rate-limit error and eventually succeeds", async () => {
-      jest.useFakeTimers();
-      const fn = jest
-        .fn()
-        .mockRejectedValueOnce(new Error("429 Too Many Requests"))
-        .mockResolvedValueOnce({ answer: "retried" });
-
-      const promise = withRetry(fn, { maxRetries: 2, backoffMs: 100 });
-      await jest.runAllTimersAsync();
-      const result = await promise;
-
-      expect(result).toEqual({ answer: "retried" });
-      expect(fn).toHaveBeenCalledTimes(2);
-    });
-
-    it("retries on a 500 server error and eventually succeeds", async () => {
-      jest.useFakeTimers();
-      const fn = jest
-        .fn()
-        .mockRejectedValueOnce(new Error("500 Internal Server Error"))
-        .mockResolvedValueOnce({
-          choices: [{ message: { role: "assistant", content: "hi" } }],
-        });
-
-      const promise = withRetry(fn, { maxRetries: 2, backoffMs: 100 });
-      await jest.runAllTimersAsync();
-      const result = await promise;
-
-      expect(result).toMatchObject({
-        choices: [{ message: { content: "hi" } }],
-      });
-      expect(fn).toHaveBeenCalledTimes(2);
-    });
-
-    it("retries on ECONNRESET and succeeds", async () => {
-      jest.useFakeTimers();
-      const fn = jest
-        .fn()
-        .mockRejectedValueOnce(new Error("ECONNRESET"))
-        .mockResolvedValueOnce("success");
-
-      const promise = withRetry(fn, { maxRetries: 2, backoffMs: 100 });
-      await jest.runAllTimersAsync();
-      const result = await promise;
-
-      expect(result).toBe("success");
-      expect(fn).toHaveBeenCalledTimes(2);
-    });
-
-    it("retries up to maxRetries times then throws", async () => {
-      jest.useFakeTimers();
-      const fn = jest.fn().mockImplementation(() =>
-        Promise.reject(new Error("500 Server Error"))
-      );
-
-      const resultPromise = withRetry(fn, { maxRetries: 2, backoffMs: 10 });
-      // Suppress unhandled rejection warning while timers run
-      resultPromise.catch(() => {});
-      await jest.runAllTimersAsync();
-      await expect(resultPromise).rejects.toThrow("500 Server Error");
-      // 1 initial attempt + 2 retries = 3 total calls
-      expect(fn).toHaveBeenCalledTimes(3);
-    });
-
-    it("does NOT retry on a non-retriable error (e.g. 400 Bad Request)", async () => {
-      const fn = jest
-        .fn()
-        .mockRejectedValue(new Error("400 Bad Request"));
-      await expect(withRetry(fn, { maxRetries: 2 })).rejects.toThrow(
-        "400 Bad Request"
-      );
-      expect(fn).toHaveBeenCalledTimes(1);
-    });
-
-    it("does NOT retry when maxRetries is 0", async () => {
-      const fn = jest
-        .fn()
-        .mockRejectedValue(new Error("500 Server Error"));
-      await expect(withRetry(fn, { maxRetries: 0 })).rejects.toThrow(
-        "500 Server Error"
-      );
-      expect(fn).toHaveBeenCalledTimes(1);
-    });
-
-    it("uses exponential backoff between retries", async () => {
-      jest.useFakeTimers();
-
-      const error = new Error("500 err");
-      const fn = jest
-        .fn()
-        .mockRejectedValueOnce(error)
-        .mockRejectedValueOnce(error)
-        .mockResolvedValueOnce("done");
-
-      // Spy on setTimeout to capture backoff delay values
-      const observedDelays: number[] = [];
-      const origSetTimeout = global.setTimeout;
-      const spy = jest
-        .spyOn(global, "setTimeout")
-        .mockImplementation((cb: any, delay?: number, ...args: any[]) => {
-          if (delay === 100 || delay === 200) {
-            observedDelays.push(delay!);
-          }
-          // Always run immediately so the test doesn't stall
-          return origSetTimeout(cb, 0, ...args);
-        });
-
-      const promise = withRetry(fn, { maxRetries: 2, backoffMs: 100 });
-      await jest.runAllTimersAsync();
-      await promise;
-
-      spy.mockRestore();
-
-      // Attempt 0 backoff = 100 * 2^0 = 100ms; attempt 1 backoff = 100 * 2^1 = 200ms
-      expect(observedDelays).toContain(100);
-      expect(observedDelays).toContain(200);
-    });
-  });
-
-  // ─── Timeout path ────────────────────────────────────────────────────────
-
-  describe("per-attempt timeout", () => {
-    it("aborts fn via signal when timeout fires and retries on the next attempt", async () => {
-      jest.useFakeTimers();
-
-      // First call: honours the signal abort (simulates slow network)
-      // Second call: resolves immediately
-      const fn = jest
-        .fn()
-        .mockImplementationOnce((signal: AbortSignal) => {
-          return new Promise<string>((_, reject) => {
-            signal.addEventListener("abort", () => reject(signal.reason));
-          });
-        })
-        .mockResolvedValueOnce("completed after timeout retry");
-
-      const promise = withRetry(fn, {
-        timeout: 1000,
-        maxRetries: 2,
-        backoffMs: 10,
-      });
-
-      // Advance timers: fires the timeout on the first attempt, then the backoff
-      await jest.runAllTimersAsync();
-
-      const result = await promise;
-      expect(result).toBe("completed after timeout retry");
-      expect(fn).toHaveBeenCalledTimes(2);
-    });
-
-    it("throws after all retries are exhausted by timeouts", async () => {
-      jest.useFakeTimers();
-
-      // Every call hangs waiting for the abort signal
-      const fn = jest.fn().mockImplementation((signal: AbortSignal) => {
-        return new Promise<string>((_, reject) => {
-          signal.addEventListener("abort", () => reject(signal.reason));
-        });
-      });
-
-      const promise = withRetry(fn, {
-        timeout: 500,
-        maxRetries: 1,
-        backoffMs: 10,
-      });
-      // Suppress unhandled rejection while timers run
-      promise.catch(() => {});
-      await jest.runAllTimersAsync();
-
-      await expect(promise).rejects.toMatchObject({ name: "TimeoutError" });
-      // 1 initial + 1 retry, both timed out
-      expect(fn).toHaveBeenCalledTimes(2);
-    });
-  });
-
-  // ─── AbortSignal (external cancel) ───────────────────────────────────────
-
-  describe("external AbortSignal", () => {
-    it("does not call fn when signal is already aborted before invocation", async () => {
-      const controller = new AbortController();
-      controller.abort();
-
-      const fn = jest.fn().mockResolvedValue("should not reach");
-      await expect(
-        withRetry(fn, { signal: controller.signal, maxRetries: 2 })
-      ).rejects.toMatchObject({ name: "AbortError" });
-
-      expect(fn).not.toHaveBeenCalled();
-    });
-
-    it("cancels an in-flight request when signal is aborted externally", async () => {
-      const controller = new AbortController();
-
-      const fn = jest.fn().mockImplementation((signal: AbortSignal) => {
-        return new Promise<string>((_, reject) => {
-          signal.addEventListener("abort", () => reject(signal.reason));
-        });
-      });
-
-      const promise = withRetry(fn, {
-        signal: controller.signal,
-        maxRetries: 2,
-      });
-
-      // Abort from outside while in-flight
-      setImmediate(() =>
-        controller.abort(new DOMException("User cancelled", "AbortError"))
-      );
-
-      await expect(promise).rejects.toMatchObject({ name: "AbortError" });
-      // Must NOT retry after external abort
-      expect(fn).toHaveBeenCalledTimes(1);
-    });
-
-    it("does not retry after external abort even if error string looks retriable", async () => {
-      const controller = new AbortController();
-      controller.abort(new DOMException("Aborted", "AbortError"));
-
-      const fn = jest.fn().mockResolvedValue("ok");
-      await expect(
-        withRetry(fn, { signal: controller.signal, maxRetries: 3 })
-      ).rejects.toMatchObject({ name: "AbortError" });
-
-      expect(fn).not.toHaveBeenCalled();
-    });
-
-    it("forwards the combined signal to fn and it is not aborted on success", async () => {
-      const controller = new AbortController();
-      let receivedSignal: AbortSignal | undefined;
-
-      const fn = jest.fn().mockImplementation((signal: AbortSignal) => {
-        receivedSignal = signal;
-        return Promise.resolve("ok");
-      });
-
-      await withRetry(fn, { signal: controller.signal, timeout: 5000 });
-
-      expect(receivedSignal).toBeInstanceOf(AbortSignal);
-      expect(receivedSignal!.aborted).toBe(false);
-    });
-  });
-
-  // ─── Combined timeout + external signal ──────────────────────────────────
-
-  describe("timeout + external signal combined", () => {
-    it("abort via external signal takes priority over pending timeout", async () => {
-      const controller = new AbortController();
-
-      const fn = jest.fn().mockImplementation((signal: AbortSignal) => {
-        return new Promise<string>((_, reject) => {
-          signal.addEventListener("abort", () => reject(signal.reason));
-        });
-      });
-
-      const promise = withRetry(fn, {
-        signal: controller.signal,
-        timeout: 10_000, // long timeout — won't fire before external abort
-        maxRetries: 2,
-      });
-
-      // Abort externally right away
-      setImmediate(() =>
-        controller.abort(new DOMException("User cancelled", "AbortError"))
-      );
-
-      await expect(promise).rejects.toMatchObject({ name: "AbortError" });
-      // No retry after external abort
-      expect(fn).toHaveBeenCalledTimes(1);
-    });
-  });
-});

package/tests/unit/commands/agents.test.ts

@@ -1,111 +0,0 @@
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { Command } from "commander";
-
-const startChat = jest.fn().mockResolvedValue(undefined);
-const setupServices = jest.fn().mockResolvedValue(undefined);
-
-jest.mock("../../../src/chat", () => ({ startChat }));
-jest.mock("../../../src/commands/services", () => ({ setupServices }));
-
-import { addAgentsCommand, getStatus } from "../../../src/commands/agents";
-
-describe("agents resume terminal UX", () => {
-  let previousCwd: string;
-  let tempDir: string;
-  let isTTYDescriptor: PropertyDescriptor | undefined;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    previousCwd = process.cwd();
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-agents-command-"));
-    process.chdir(tempDir);
-    const taskId = "1700000000-resumable-task";
-    fs.mkdirSync(path.join(".knowhow", "processes", "agents", taskId), {
-      recursive: true,
-    });
-    fs.writeFileSync(
-      path.join(".knowhow", "processes", "agents", taskId, "metadata.json"),
-      JSON.stringify({ taskId, status: "completed", threads: [[]] })
-    );
-    isTTYDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
-    Object.defineProperty(process.stdin, "isTTY", {
-      configurable: true,
-      value: true,
-    });
-  });
-
-  afterEach(() => {
-    process.chdir(previousCwd);
-    fs.rmSync(tempDir, { recursive: true, force: true });
-    if (isTTYDescriptor) {
-      Object.defineProperty(process.stdin, "isTTY", isTTYDescriptor);
-    } else {
-      delete (process.stdin as NodeJS.ReadStream & { isTTY?: boolean }).isTTY;
-    }
-  });
-
-  test("opens chat with the interactive resume command by default", async () => {
-    const program = new Command();
-    addAgentsCommand(program, jest.fn());
-
-    await program.parseAsync([
-      "node",
-      "knowhow",
-      "agents",
-      "resume",
-      "1700000000-resumable-task",
-      "--rollback",
-      "2",
-    ]);
-
-    expect(setupServices).toHaveBeenCalledTimes(1);
-    expect(startChat).toHaveBeenCalledWith(
-      "/resume 1700000000-resumable-task --rollback 2"
-    );
-  });
-});
-
-describe("agents effective status", () => {
-  let previousCwd: string;
-  let tempDir: string;
-
-  beforeEach(() => {
-    previousCwd = process.cwd();
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "knowhow-agent-status-"));
-    process.chdir(tempDir);
-  });
-
-  afterEach(() => {
-    process.chdir(previousCwd);
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  test("keeps a running status when the recorded process is alive", () => {
-    expect(getStatus("task", { status: "running", pid: process.pid })).toBe(
-      "running"
-    );
-  });
-
-  test("reports a running task as failed when its process exited", () => {
-    expect(getStatus("task", { status: "running", pid: 2_147_483_647 })).toBe(
-      "failed"
-    );
-  });
-
-  test("reports old legacy running records without a pid as stale", () => {
-    expect(
-      getStatus("task", {
-        status: "running",
-        lastUpdate: new Date(Date.now() - 10 * 60 * 1000).toISOString(),
-      })
-    ).toBe("stale");
-  });
-
-  test("never overrides a persisted terminal status", () => {
-    expect(getStatus("task", { status: "completed", pid: process.pid })).toBe(
-      "completed"
-    );
-  });
-});

package/tests/unit/commands/github-credentials.test.ts

@@ -1,210 +0,0 @@
-/**
- * Unit tests for the github-credentials command.
- *
- * Key invariant: running `github-credentials` must NEVER write anything other than
- * the credential lines to stdout. Module loading logs, warnings, etc. must be
- * silenced so the git credential helper protocol is not corrupted.
- */
-
-// Mock config before any imports that depend on it
-jest.mock("../../../src/config", () => ({
-  getConfig: jest.fn().mockResolvedValue({ modules: [] }),
-  getGlobalConfig: jest.fn().mockResolvedValue({ modules: [] }),
-  getConfigSync: jest.fn().mockReturnValue({}),
-  migrateConfig: jest.fn().mockResolvedValue(undefined),
-}));
-
-// Mock clients to avoid openai.ts side-effects
-jest.mock("../../../src/clients", () => ({
-  AIClient: jest.fn(),
-  Clients: { registerClient: jest.fn(), registerModels: jest.fn() },
-}));
-
-// Mock KnowhowSimpleClient so we control what getGitCredential returns
-// without needing a real JWT or network connection
-jest.mock("../../../src/services/KnowhowClient", () => ({
-  KnowhowSimpleClient: jest.fn().mockImplementation(() => ({
-    getGitCredential: jest.fn().mockResolvedValue({
-      protocol: "https",
-      host: "github.com",
-      username: "x-access-token",
-      password: "ghu_TESTTOKEN123",
-    }),
-  })),
-}));
-
-// Mock readline so the 'get' action doesn't hang waiting for stdin
-jest.mock("readline", () => ({
-  createInterface: jest.fn().mockReturnValue({
-    on: jest.fn().mockImplementation(function (event: string, cb: Function) {
-      // Immediately fire 'close' so the readline promise resolves
-      if (event === "close") {
-        setImmediate(() => cb());
-      }
-      return this;
-    }),
-  }),
-}));
-
-import { Command } from "commander";
-import { addGithubCredentialsCommand } from "../../../src/commands/misc";
-import { logger } from "../../../src/logger";
-
-describe("github-credentials command", () => {
-  /**
-   * This test verifies the EARLY silencing logic in cli.ts main().
-   * The problem: modules load BEFORE parseAsync, so any module that emits
-   * warnings (e.g. Terminal module: no TunnelHandler) does so before the
-   * action's logger.silence() call can stop it.
-   *
-   * The fix: cli.ts checks process.argv before module loading and silences early.
-   * This test simulates that logic directly.
-   */
-  describe("early silencing (pre-module-load)", () => {
-    beforeEach(() => {
-      logger.unsilence();
-      logger.installConsoleOverload();
-    });
-
-    afterEach(() => {
-      logger.unsilence();
-      logger.uninstallConsoleOverload();
-    });
-
-    it("silences before module loading when github-credentials is in argv", () => {
-      const originalArgv = process.argv;
-      process.argv = ["node", "knowhow", "github-credentials", "get"];
-
-      // Simulate the exact early-detection logic from cli.ts main()
-      const rawArgs = process.argv.slice(2);
-      const SILENT_COMMANDS = ["github-credentials"];
-      if (rawArgs.some((a) => SILENT_COMMANDS.includes(a))) {
-        logger.silence();
-      }
-
-      // Now any module-load-time console.log/warn should be suppressed
-      const consoleSpy = jest.spyOn(process.stdout, "write");
-      console.log("some module loading noise that should be suppressed");
-
-      expect(consoleSpy).not.toHaveBeenCalled();
-      consoleSpy.mockRestore();
-      process.argv = originalArgv;
-    });
-
-    it("does NOT silence for other commands", () => {
-      const originalArgv = process.argv;
-      process.argv = ["node", "knowhow", "chat"];
-
-      const rawArgs = process.argv.slice(2);
-      const SILENT_COMMANDS = ["github-credentials"];
-      if (rawArgs.some((a) => SILENT_COMMANDS.includes(a))) {
-        logger.silence();
-      }
-
-      expect(logger.isSilenced()).toBe(false);
-      process.argv = originalArgv;
-    });
-  });
-
-  let program: Command;
-  let stdoutSpy: jest.SpyInstance;
-  let writtenToStdout: string[];
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-
-    // Reset logger silence state between tests
-    logger.unsilence();
-
-    // Capture process.stdout.write — this is what the credential helper uses
-    writtenToStdout = [];
-    stdoutSpy = jest
-      .spyOn(process.stdout, "write")
-      .mockImplementation((chunk: any) => {
-        writtenToStdout.push(typeof chunk === "string" ? chunk : chunk.toString());
-        return true;
-      });
-
-    program = new Command();
-    program.exitOverride(); // prevent process.exit during tests
-    addGithubCredentialsCommand(program);
-  });
-
-  afterEach(() => {
-    stdoutSpy.mockRestore();
-    logger.unsilence();
-  });
-
-  it("outputs only credential lines to stdout for 'get' action", async () => {
-    await program.parseAsync([
-      "node", "knowhow", "github-credentials", "get", "--repo", "myorg/myrepo",
-    ]);
-
-    expect(writtenToStdout).toHaveLength(1);
-    expect(writtenToStdout[0]).toBe(
-      "protocol=https\nhost=github.com\nusername=x-access-token\npassword=ghu_TESTTOKEN123\n"
-    );
-  });
-
-  it("silences the logger immediately so module logs don't pollute stdout", async () => {
-    await program.parseAsync([
-      "node", "knowhow", "github-credentials", "get", "--repo", "myorg/myrepo",
-    ]);
-
-    // The action must have called logger.silence() — state persists after action
-    expect(logger.isSilenced()).toBe(true);
-  });
-
-  it("produces exactly 4 credential field lines and nothing else", async () => {
-    await program.parseAsync([
-      "node", "knowhow", "github-credentials", "get", "--repo", "myorg/myrepo",
-    ]);
-
-    const allOutput = writtenToStdout.join("");
-    const lines = allOutput.trim().split("\n");
-
-    expect(lines).toHaveLength(4);
-    expect(lines[0]).toMatch(/^protocol=/);
-    expect(lines[1]).toMatch(/^host=/);
-    expect(lines[2]).toMatch(/^username=/);
-    expect(lines[3]).toMatch(/^password=/);
-  });
-
-  it("exits cleanly for 'store' action without writing credentials", async () => {
-    let exitCode: number | undefined;
-    // Throw to stop execution after exit() is called — otherwise the mock
-    // just sets a flag and the action continues to fetch credentials.
-    const exitSpy = jest
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        exitCode = code ?? 0;
-        throw new Error(`process.exit(${exitCode})`);
-      }) as any);
-
-    await expect(
-      program.parseAsync(["node", "knowhow", "github-credentials", "store"])
-    ).rejects.toThrow("process.exit(0)");
-
-    expect(exitCode).toBe(0);
-    expect(writtenToStdout).toHaveLength(0);
-    exitSpy.mockRestore();
-  });
-
-  it("exits cleanly for 'erase' action without writing credentials", async () => {
-    let exitCode: number | undefined;
-    const exitSpy = jest
-      .spyOn(process, "exit")
-      .mockImplementation(((code?: number) => {
-        exitCode = code ?? 0;
-        throw new Error(`process.exit(${exitCode})`);
-      }) as any);
-
-    await expect(
-      program.parseAsync(["node", "knowhow", "github-credentials", "erase"])
-    ).rejects.toThrow("process.exit(0)");
-
-    expect(exitCode).toBe(0);
-    expect(writtenToStdout).toHaveLength(0);
-    exitSpy.mockRestore();
-  });
-});