@tyvm/knowhow 0.0.108-dev.126b29e → 0.0.108-dev.80f1ac6

package/src/clients/index.ts

@@ -577,11 +577,12 @@ export class AIClient {
    * @param modelQuery - the model name to search for (can be partial/normalized)
    * @param provider   - optional provider to restrict search to
    */
-  findModelFuzzy(modelQuery: string, provider?: string): { provider: string; model: string } | undefined {
+  findModelFuzzy(
+    modelQuery: string,
+    provider?: string
+  ): { provider: string; model: string } | undefined {
     const queryNorm = AIClient.normalizeModelId(modelQuery);
-    const providers = provider
-      ? [provider]
-      : Object.keys(this.clientModels);
+    const providers = provider ? [provider] : Object.keys(this.clientModels);
 
     for (const p of providers) {
       const models = (this.clientModels[p] as string[]) ?? [];
@@ -835,7 +836,7 @@ export class AIClient {
         const splitModel = m.id.split("/");
 
         if (splitModel.length < 2) {
-          console.error(`Cannot parse model format: ${m.id}`);
+          console.warn(`Cannot parse model format: ${m.id}`);
         }
 
         const provider = splitModel.length > 1 ? splitModel[0] : "";

package/src/clients/types.ts

@@ -1,4 +1,10 @@
-export type ModelModality = "completion" | "embedding" | "image" | "audio" | "video" | "transcription";
+export type ModelModality =
+  | "completion"
+  | "embedding"
+  | "image"
+  | "audio"
+  | "video"
+  | "transcription";
 
 export type MessageContent =
   | { type: "text"; text: string }
@@ -8,7 +14,7 @@ export type MessageContent =
 
 export interface Message {
   role: "system" | "user" | "assistant" | "tool";
-  content?: string | MessageContent[];
+  content?: string | MessageContent[] | null;
 
   name?: string;
   tool_call_id?: string;
@@ -16,7 +22,7 @@ export interface Message {
 }
 
 export interface OutputMessage extends Message {
-  content: string;
+  content?: string | null;
 }
 
 export interface ToolProp {
@@ -301,7 +307,9 @@ export interface GenericClient {
    * When modality is provided, return only models for that modality (static list).
    * When omitted, return ALL models (backward compat — may do a live API call).
    */
-  getModels(modality?: ModelModality): Promise<{ id: string; modality?: ModelModality[] }[]>;
+  getModels(
+    modality?: ModelModality
+  ): Promise<{ id: string; modality?: ModelModality[] }[]>;
   /**
    * Returns the context window limit and compression threshold for a given model,
    * or undefined if the model is not known to this client.

package/src/commands/agent.ts

@@ -0,0 +1,246 @@
+import { Command } from "commander";
+import { readPromptFile } from "../ai";
+import { AgentModule } from "../chat/modules/AgentModule";
+import { AskModule } from "../chat/modules/AskModule";
+import { SearchModule } from "../chat/modules/SearchModule";
+import { SessionsModule } from "../chat/modules/SessionsModule";
+import { SetupModule } from "../chat/modules/SetupModule";
+
+async function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+
+    process.stdin.on("readable", () => {
+      const chunk = process.stdin.read();
+      if (chunk !== null) data += chunk;
+    });
+
+    process.stdin.on("end", () => resolve(data.trim()));
+  });
+}
+
+export function addAgentCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("agent")
+    .description("Spin up agents directly from CLI")
+    .option(
+      "--provider <provider>",
+      "AI provider (openai, anthropic, google, xai)"
+    )
+    .option("--model <model>", "Specific model for the provider")
+    .option("--agent-name <name>", "Which agent to use", "Patcher")
+    .option(
+      "--max-time-limit <minutes>",
+      "Time limit for agent execution (minutes)",
+      "30"
+    )
+    .option(
+      "--max-spend-limit <dollars>",
+      "Cost limit for agent execution (dollars)",
+      "10"
+    )
+    .option("--message-id <messageId>", "Knowhow message ID for task tracking")
+    .option("--sync-fs", "Enable filesystem-based synchronization")
+    .option(
+      "--task-id <taskId>",
+      "Pre-generated task ID (used with --sync-fs for predictable agent directory path)"
+    )
+    .option("--prompt-file <path>", "Custom prompt template file with {text}")
+    .option("--input <text>", "Task input (fallback to stdin if not provided)")
+    .option(
+      "--resume",
+      "Resume a previously started task using the --task-id (local FS or remote)"
+    )
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+
+        if (options.resume) {
+          const threads = await agentModule.loadThreadsForTask(
+            options.taskId,
+            options.messageId
+          );
+          const resumeInput =
+            options.input || "Please continue from where you left off.";
+
+          await agentModule.initialize(chatService);
+          const { taskCompleted: resumed } =
+            await agentModule.resumeFromMessages({
+              agentName: options.agentName || "Patcher",
+              input: resumeInput,
+              threads,
+              messageId: options.messageId,
+              taskId: options.taskId,
+            });
+          await resumed;
+          return;
+        }
+
+        let input = options.input;
+
+        if (!input && !options.promptFile) {
+          input = await readStdin();
+        }
+
+        input = readPromptFile(options.promptFile, input);
+
+        if (!input) {
+          console.error(
+            "Error: No input provided. Use --input flag, pipe input via stdin, or provide --prompt-file."
+          );
+          process.exit(1);
+        }
+
+        await agentModule.initialize(chatService);
+        const { taskCompleted } = await agentModule.setupAgent({
+          ...options,
+          input,
+          maxTimeLimit: parseInt(options.maxTimeLimit, 10),
+          maxSpendLimit: parseFloat(options.maxSpendLimit),
+          run: true,
+        });
+        await taskCompleted;
+      } catch (error) {
+        console.error("Error running agent:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addAskCommand(program: Command, getChatService: () => any, getConfig: () => any): void {
+  program
+    .command("ask")
+    .description("Direct AI questioning without agent overhead")
+    .option("--provider <provider>", "AI provider to use")
+    .option("--model <model>", "Specific model")
+    .option("--input <text>", "Question (fallback to stdin if not provided)")
+    .option("--prompt-file <path>", "Custom prompt template file")
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const config = getConfig();
+        let input = options.input;
+
+        if (!input && !options.promptFile) {
+          input = await readStdin();
+        }
+
+        input = readPromptFile(options.promptFile, input);
+
+        if (!input) {
+          console.error(
+            "Error: No question provided. Use --input flag, pipe input via stdin, or provide --prompt-file."
+          );
+          process.exit(1);
+        }
+
+        const askModule = new AskModule();
+        await askModule.initialize(chatService);
+        await askModule.processAIQuery(input, {
+          plugins: config.plugins.enabled,
+          currentModel: options.model,
+          currentProvider: options.provider,
+          chatHistory: [],
+        });
+      } catch (error) {
+        console.error("Error asking AI:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSetupCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("setup")
+    .description("Ask the agent to configure knowhow")
+    .action(async () => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+        await agentModule.initialize(chatService);
+        const setupModule = new SetupModule(agentModule);
+        await setupModule.initialize(chatService);
+        await setupModule.handleSetupCommand([]);
+      } catch (error) {
+        console.error("Error running agent:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSearchCommand(program: Command): void {
+  program
+    .command("search")
+    .description("Search embeddings directly from CLI")
+    .option(
+      "--input <text>",
+      "Search query (fallback to stdin if not provided)"
+    )
+    .option(
+      "-e, --embedding <path>",
+      "Specific embedding path (default: all)",
+      "all"
+    )
+    .action(async (options) => {
+      try {
+        const { setupServices } = await import("./services");
+        await setupServices();
+        let input = options.input;
+        if (!input) {
+          input = await readStdin();
+          if (!input) {
+            console.error(
+              "Error: No search query provided. Use --input flag or pipe input via stdin."
+            );
+            process.exit(1);
+          }
+        }
+
+        await new SearchModule().searchEmbeddingsCLI(input, options.embedding);
+      } catch (error) {
+        console.error("Error searching embeddings:", error);
+        process.exit(1);
+      }
+    });
+}
+
+export function addSessionsCommand(program: Command, getChatService: () => any): void {
+  program
+    .command("sessions")
+    .description("Manage agent sessions from CLI")
+    .option(
+      "--all",
+      "Show all historical sessions (default: current process only)"
+    )
+    .option("--csv", "Output sessions as CSV")
+    .action(async (options) => {
+      try {
+        const chatService = getChatService();
+        const agentModule = new AgentModule();
+        await agentModule.initialize(chatService);
+        const sessionsModule = new SessionsModule(agentModule);
+        await sessionsModule.initialize(chatService);
+        await sessionsModule.logSessionTable(
+          options.all || false,
+          options.csv || false,
+          true
+        );
+      } catch (error) {
+        console.error("Error listing sessions:", error);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/misc.ts

@@ -0,0 +1,174 @@
+import { Command } from "commander";
+import { execSync } from "child_process";
+import { version } from "../../package.json";
+import { logger } from "../logger";
+import { generate, embed, upload, download, purge } from "../index";
+import { init } from "../config";
+import { login } from "../login";
+import { KnowhowSimpleClient } from "../services/KnowhowClient";
+import { startChat } from "../chat";
+
+export function addInitCommand(program: Command): void {
+  program
+    .command("init")
+    .description("Initialize knowhow configuration")
+    .action(async () => {
+      await init();
+    });
+}
+
+export function addLoginCommand(program: Command): void {
+  program
+    .command("login")
+    .description("Login to knowhow")
+    .option("--jwt", "Use manual JWT input instead of browser login")
+    .action(async (opts) => {
+      await login(opts.jwt);
+    });
+}
+
+export function addUpdateCommand(program: Command): void {
+  program
+    .command("update")
+    .description("Update knowhow to the latest version from npm")
+    .action(async () => {
+      try {
+        console.log("🔄 Checking for knowhow updates...");
+        console.log(`Current version: ${version}`);
+        console.log("📦 Installing latest version from npm...");
+        execSync("npm install -g @tyvm/knowhow@latest", {
+          stdio: "inherit",
+          encoding: "utf-8",
+        });
+        console.log("✓ knowhow has been updated successfully!");
+        console.log("Run 'knowhow --version' to see the new version.");
+      } catch (error) {
+        console.error("Error updating knowhow:", error.message);
+        process.exit(1);
+      }
+    });
+}
+
+export function addGenerateCommand(program: Command): void {
+  program
+    .command("generate")
+    .description("Generate documentation")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await generate();
+    });
+}
+
+export function addEmbedCommands(program: Command): void {
+  program
+    .command("embed")
+    .description("Create embeddings")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await embed();
+    });
+
+  program
+    .command("embed:purge")
+    .description("Purge embeddings matching a glob pattern")
+    .argument("<pattern>", "Glob pattern to match files for purging")
+    .action(async (pattern) => {
+      await purge(pattern);
+    });
+}
+
+export function addUploadCommand(program: Command): void {
+  program
+    .command("upload")
+    .description("Upload data")
+    .action(async () => {
+      await upload();
+    });
+}
+
+export function addDownloadCommand(program: Command): void {
+  program
+    .command("download")
+    .description("Download data")
+    .action(async () => {
+      await download();
+    });
+}
+
+export function addChatCommand(program: Command): void {
+  program
+    .command("chat")
+    .description("Start new chat interface")
+    .action(async () => {
+      const { setupServices } = await import("./services");
+      await setupServices();
+      await startChat();
+    });
+}
+
+export function addGithubCredentialsCommand(program: Command): void {
+  program
+    .command("github-credentials [action]")
+    .description(
+      "Git credential helper for GitHub. Use as: git config credential.helper 'knowhow github-credentials'"
+    )
+    .option(
+      "--repo <repo>",
+      "Repository in owner/repo format (e.g. myorg/myrepo)"
+    )
+    .action(async (action: string | undefined, options: { repo?: string }) => {
+      // Silence ALL output immediately — git credential helpers must produce
+      // only the protocol=.../host=.../username=.../password=... lines on stdout.
+      logger.silence();
+
+      const client = new KnowhowSimpleClient();
+
+      let repo = options.repo;
+
+      if (action === "get") {
+        const lines: string[] = [];
+        const readline = await import("readline");
+        const rl = readline.createInterface({
+          input: process.stdin,
+          terminal: false,
+        });
+        await new Promise<void>((resolve) => {
+          rl.on("line", (line) => {
+            if (line.trim()) lines.push(line.trim());
+          });
+          rl.on("close", resolve);
+        });
+      } else if (action === "store" || action === "erase") {
+        process.exit(0);
+      }
+
+      if (!repo) {
+        try {
+          const remoteUrl = execSync("git remote get-url origin", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+          }).trim();
+          const match =
+            remoteUrl.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/) ||
+            remoteUrl.match(/github\.com\/([^/]+\/[^/]+)/);
+          if (match) {
+            repo = match[1];
+          }
+        } catch {
+          // Not in a git repo or no remote — proceed without repo
+        }
+      }
+
+      try {
+        const credential = await client.getGitCredential(repo || "");
+        process.stdout.write(
+          `protocol=${credential.protocol}\nhost=${credential.host}\nusername=${credential.username}\npassword=${credential.password}\n`
+        );
+      } catch (error) {
+        console.error("Failed to get git credentials:", error.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/modules.ts

@@ -0,0 +1,182 @@
+import { Command } from "commander";
+import { execSync } from "child_process";
+import { getConfig, getGlobalConfig, updateConfig, updateGlobalConfig } from "../config";
+
+// Default built-in modules that `knowhow modules setup` adds to the config.
+export const BUILTIN_MODULES = [
+  "@tyvm/knowhow-module-script",
+  "@tyvm/knowhow-module-terminal",
+];
+
+export function addModulesCommand(program: Command): void {
+  const modulesCmd = program
+    .command("modules")
+    .description("Manage knowhow modules (install, add to config, list)");
+
+  modulesCmd
+    .command("setup")
+    .description(
+      "Add default built-in modules to your config and install them via npm"
+    )
+    .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
+    .action(async (opts) => {
+      try {
+        const isGlobal: boolean = opts.global ?? false;
+        const cfg = isGlobal ? await getGlobalConfig() : await getConfig();
+        const configLabel = isGlobal
+          ? "~/.knowhow/knowhow.json"
+          : ".knowhow/knowhow.json";
+
+        if (!cfg.modules) cfg.modules = [];
+
+        const toAdd = BUILTIN_MODULES.filter(
+          (m) => !cfg.modules!.includes(m)
+        );
+
+        if (toAdd.length === 0) {
+          console.log(
+            `✅ All default modules are already in ${configLabel}. Nothing to do.`
+          );
+          return;
+        }
+
+        // Install packages that are not local file paths
+        for (const mod of toAdd) {
+          if (!mod.startsWith(".") && !mod.startsWith("/")) {
+            console.log(`📦 Installing ${mod}...`);
+            const installFlag = isGlobal ? "-g" : "";
+            execSync(`npm install ${installFlag} ${mod}`, {
+              stdio: "inherit",
+              encoding: "utf-8",
+            });
+          }
+          cfg.modules!.push(mod);
+          console.log(`✅ Added ${mod} to ${configLabel}`);
+        }
+
+        if (isGlobal) {
+          await updateGlobalConfig(cfg);
+        } else {
+          await updateConfig(cfg);
+        }
+
+        console.log(
+          `\n🎉 Setup complete! ${toAdd.length} module(s) added to ${configLabel}`
+        );
+      } catch (error) {
+        console.error("Error during modules setup:", error.message ?? error);
+        process.exit(1);
+      }
+    });
+
+  modulesCmd
+    .command("install [module]")
+    .description(
+      "Install a module via npm and add it to your config. " +
+      "If no module name is given, installs all modules already in the config."
+    )
+    .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
+    .action(async (moduleName: string | undefined, opts) => {
+      try {
+        const isGlobal: boolean = opts.global ?? false;
+        const cfg = isGlobal ? await getGlobalConfig() : await getConfig();
+        const configLabel = isGlobal
+          ? "~/.knowhow/knowhow.json"
+          : ".knowhow/knowhow.json";
+
+        if (!cfg.modules) cfg.modules = [];
+
+        if (!moduleName) {
+          // No module specified — install everything already in the config
+          const installable = cfg.modules.filter(
+            (m) => !m.startsWith(".") && !m.startsWith("/")
+          );
+          if (installable.length === 0) {
+            console.log(
+              `ℹ No installable modules found in ${configLabel}.`
+            );
+            return;
+          }
+          console.log(
+            `📦 Installing ${installable.length} module(s) from ${configLabel}...`
+          );
+          const installFlag = isGlobal ? "-g" : "";
+          for (const mod of installable) {
+            console.log(`  📦 Installing ${mod}...`);
+            execSync(`npm install ${installFlag} ${mod}`, {
+              stdio: "inherit",
+              encoding: "utf-8",
+            });
+            console.log(`  ✅ Installed ${mod}`);
+          }
+          console.log(`\n🎉 All modules installed!`);
+          return;
+        }
+
+        // Install the specified module
+        const installFlag = isGlobal ? "-g" : "";
+        console.log(`📦 Installing ${moduleName}...`);
+        execSync(`npm install ${installFlag} ${moduleName}`, {
+          stdio: "inherit",
+          encoding: "utf-8",
+        });
+        console.log(`✅ Installed ${moduleName}`);
+
+        // Add to config if not already there
+        if (!cfg.modules.includes(moduleName)) {
+          cfg.modules.push(moduleName);
+          if (isGlobal) {
+            await updateGlobalConfig(cfg);
+          } else {
+            await updateConfig(cfg);
+          }
+          console.log(`✅ Added ${moduleName} to ${configLabel}`);
+        } else {
+          console.log(`ℹ ${moduleName} is already in ${configLabel}`);
+        }
+      } catch (error) {
+        console.error("Error during module install:", error.message ?? error);
+        process.exit(1);
+      }
+    });
+
+  modulesCmd
+    .command("list")
+    .description("List all modules in your config")
+    .option("--global", "Show global config modules only")
+    .action(async (opts) => {
+      try {
+        const isGlobal: boolean = opts.global ?? false;
+        const globalCfg = await getGlobalConfig();
+        const localCfg = isGlobal ? null : await getConfig();
+
+        const globalModules = globalCfg.modules || [];
+        const localModules = localCfg?.modules || [];
+
+        if (isGlobal) {
+          console.log(`\n🌐 Global modules (~/.knowhow/knowhow.json):`);
+          if (globalModules.length === 0) {
+            console.log("  (none)");
+          } else {
+            globalModules.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+          }
+        } else {
+          console.log(`\n🌐 Global modules (~/.knowhow/knowhow.json):`);
+          if (globalModules.length === 0) {
+            console.log("  (none)");
+          } else {
+            globalModules.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+          }
+          console.log(`\n📁 Local modules (.knowhow/knowhow.json):`);
+          if (localModules.length === 0) {
+            console.log("  (none)");
+          } else {
+            localModules.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
+          }
+        }
+      } catch (error) {
+        console.error("Error listing modules:", error.message ?? error);
+        process.exit(1);
+      }
+    });
+}