@howdoi-cli/core 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 howdoi-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @howdoi-cli/core
+
+The engine, renderer, and `howdoi` binary.
+
+You don't install this directly — it's pulled in automatically when you install any knowledge base package.
+
+```bash
+npm install -g @howdoi-cli/unix   # core comes along for free
+```
+
+See the [main README](https://github.com/SiphoChris/howdoi-cli) for full documentation.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+
+// src/engine/loader.ts
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+import yaml from "js-yaml";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getXdgDataDir() {
+  const xdgBase = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+  return join(xdgBase, "howdoi");
+}
+function discoverFromNodeModules() {
+  const dataDirs = [];
+  const candidates = [
+    join(__dirname, "..", "..", "..", ".."),
+    // global: node_modules/@howdoi-cli/core/dist -> ../../../../
+    join(__dirname, "..", "..", "..", "..", "..")
+    // deeper nesting
+  ];
+  for (const base of candidates) {
+    const scope = join(base, "node_modules", "@howdoi-cli");
+    if (!existsSync(scope)) continue;
+    for (const pkg of readdirSync(scope)) {
+      if (pkg === "core") continue;
+      const pkgJson = join(scope, pkg, "package.json");
+      if (!existsSync(pkgJson)) continue;
+      try {
+        const manifest = JSON.parse(readFileSync(pkgJson, "utf-8"));
+        const dataDir = manifest?.howdoi?.dataDir;
+        if (dataDir) {
+          dataDirs.push(join(scope, pkg, dataDir));
+        }
+      } catch {
+      }
+    }
+  }
+  return dataDirs;
+}
+function loadFromDir(dataDir, tools) {
+  if (!existsSync(dataDir)) return;
+  const categories = readdirSync(dataDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  for (const category of categories) {
+    const categoryDir = join(dataDir, category);
+    const files = readdirSync(categoryDir).filter((f) => f.endsWith(".yaml"));
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(categoryDir, file), "utf-8");
+        const parsed = yaml.load(raw);
+        tools.push(parsed);
+      } catch {
+      }
+    }
+  }
+}
+function loadAllTools() {
+  const tools = [];
+  const xdgDir = getXdgDataDir();
+  if (existsSync(xdgDir)) {
+    for (const pkg of readdirSync(xdgDir, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+      loadFromDir(join(xdgDir, pkg.name), tools);
+    }
+  }
+  if (tools.length === 0) {
+    for (const dir of discoverFromNodeModules()) {
+      loadFromDir(dir, tools);
+    }
+  }
+  if (tools.length === 0) {
+    console.error(
+      "\nNo knowledge bases found. Install one to get started:\n\n  npm install -g @howdoi-cli/unix\n  npm install -g @howdoi-cli/git\n"
+    );
+    process.exit(1);
+  }
+  return tools;
+}
+
+// src/engine/search.ts
+import Fuse from "fuse.js";
+var SearchEngine = class {
+  fuse;
+  intentFuse;
+  index;
+  exampleIntents;
+  constructor(tools) {
+    this.index = [];
+    for (const tool of tools) {
+      const exampleIntents = new Set(tool.examples.map((e) => e.intent));
+      this.index.push({ intent: tool.tool, tool, isExampleIntent: false });
+      this.index.push({ intent: tool.description, tool, isExampleIntent: false });
+      for (const intent of tool.intents) {
+        this.index.push({
+          intent,
+          tool,
+          isExampleIntent: exampleIntents.has(intent)
+        });
+      }
+    }
+    this.fuse = new Fuse(this.index, {
+      keys: ["intent"],
+      threshold: 0.45,
+      distance: 100,
+      minMatchCharLength: 2,
+      includeScore: true
+    });
+    this.exampleIntents = [
+      ...new Set(
+        this.index.filter((i) => i.isExampleIntent).map((i) => i.intent)
+      )
+    ].sort();
+    this.intentFuse = new Fuse(
+      this.exampleIntents.map((i) => ({ intent: i })),
+      {
+        keys: ["intent"],
+        threshold: 0.35,
+        distance: 100,
+        minMatchCharLength: 2,
+        includeScore: true
+      }
+    );
+  }
+  search(query) {
+    const raw = this.fuse.search(query);
+    const seen = /* @__PURE__ */ new Map();
+    for (const r of raw) {
+      const toolName = r.item.tool.tool;
+      const score = r.score ?? 1;
+      if (!seen.has(toolName) || score < seen.get(toolName).score) {
+        seen.set(toolName, {
+          tool: r.item.tool,
+          matchedIntent: r.item.isExampleIntent ? r.item.intent : void 0,
+          score
+        });
+      }
+    }
+    return Array.from(seen.values()).sort((a, b) => a.score - b.score);
+  }
+  suggestIntents(query) {
+    if (!query || query.trim().length < 2) return this.exampleIntents.slice(0, 10);
+    return this.intentFuse.search(query).slice(0, 10).map((r) => r.item.intent);
+  }
+  getAllIntents() {
+    return this.exampleIntents;
+  }
+  getToolsByCategory() {
+    const map = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set();
+    for (const entry of this.index) {
+      const tool = entry.tool;
+      if (seen.has(tool.tool)) continue;
+      seen.add(tool.tool);
+      const list = map.get(tool.category) ?? [];
+      list.push(tool);
+      map.set(tool.category, list);
+    }
+    return map;
+  }
+};
+
+// src/renderer/display.ts
+import chalk from "chalk";
+
+// src/engine/types.ts
+var CATEGORY_LABELS = {
+  "file-management": "File Management",
+  "text-processing": "Text Processing",
+  "file-inspection": "File Inspection",
+  "git": "Git",
+  "ssh": "SSH",
+  "docker": "Docker",
+  "networking": "Networking"
+};
+var CATEGORY_ORDER = [
+  "file-management",
+  "text-processing",
+  "file-inspection",
+  "git",
+  "ssh",
+  "docker",
+  "networking"
+];
+var PACKAGE_CATEGORY_MAP = {
+  "@howdoi-cli/unix": ["file-management", "text-processing", "file-inspection"],
+  "@howdoi-cli/git": ["git"],
+  "@howdoi-cli/ssh": ["ssh"],
+  "@howdoi-cli/docker": ["docker"],
+  "@howdoi-cli/networking": ["networking"]
+};
+
+// src/renderer/display.ts
+function rule(width = 56) {
+  return chalk.dim("\u2500".repeat(width));
+}
+function badge(category) {
+  const labels = {
+    "file-management": chalk.bgYellow.black(" FILE "),
+    "text-processing": chalk.bgCyan.black(" TEXT "),
+    "file-inspection": chalk.bgMagenta.black(" INSPECT "),
+    "git": chalk.bgRed.black(" GIT "),
+    "ssh": chalk.bgBlue.black(" SSH "),
+    "docker": chalk.bgBlue.black(" DOCKER "),
+    "networking": chalk.bgGreen.black(" NET ")
+  };
+  return labels[category] ?? chalk.bgWhite.black(` ${category.toUpperCase()} `);
+}
+function osBadge(os) {
+  if (!os) return "";
+  const labels = {
+    "linux": chalk.dim(" [linux/macos]"),
+    "macos": chalk.dim(" [linux/macos]"),
+    "linux-only": chalk.yellow(" [linux only]"),
+    "macos-only": chalk.yellow(" [macos only]")
+  };
+  return labels[os] ?? "";
+}
+function renderToolCard(tool, intentFilter) {
+  const examples = intentFilter ? tool.examples.filter((e) => e.intent === intentFilter) : tool.examples;
+  const displayExamples = examples.length > 0 ? examples : tool.examples;
+  console.log();
+  console.log(
+    `${badge(tool.category)}  ${chalk.bold.white(tool.tool)}  ${chalk.dim(tool.description)}`
+  );
+  console.log(rule());
+  for (const example of displayExamples) {
+    renderExample(example);
+  }
+  console.log(rule());
+  console.log();
+}
+function renderExample(example) {
+  console.log();
+  console.log(`  ${chalk.dim("\u25B8")} ${chalk.white(example.title)}${osBadge(example.os)}`);
+  console.log(`    ${chalk.green.bold(example.command)}`);
+}
+function renderNoResults(query) {
+  console.log();
+  console.log(chalk.yellow("  No results found for: ") + chalk.bold(`"${query}"`));
+  console.log(chalk.dim("  Try rephrasing \u2014 e.g. 'search file for text' or 'undo last commit'"));
+  console.log(chalk.dim("  Or browse with: howdoi (no args)"));
+  console.log();
+}
+function renderWelcome() {
+  console.log();
+  console.log(chalk.bold.white("  howdoi") + chalk.dim(" \u2014 intent-based command discovery"));
+  console.log(chalk.dim("  ") + rule(52));
+  console.log();
+}
+function renderList(tools, packageFilter) {
+  const packageMap = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    const pkg = tool.package ?? "unknown";
+    if (packageFilter) {
+      const short = pkg.replace("@howdoi-cli/", "");
+      if (short !== packageFilter && pkg !== packageFilter) continue;
+    }
+    if (!packageMap.has(pkg)) packageMap.set(pkg, /* @__PURE__ */ new Map());
+    const catMap = packageMap.get(pkg);
+    if (!catMap.has(tool.category)) catMap.set(tool.category, []);
+    catMap.get(tool.category).push(tool);
+  }
+  const filteredTools = packageFilter ? tools.filter((t) => {
+    const short = (t.package ?? "").replace("@howdoi-cli/", "");
+    return short === packageFilter || t.package === packageFilter;
+  }) : tools;
+  const packageCount = packageMap.size;
+  if (packageMap.size === 0) {
+    console.log();
+    if (packageFilter) {
+      console.log(chalk.yellow(`  No tools found for package: `) + chalk.bold(`"${packageFilter}"`));
+      console.log(chalk.dim(`  Available packages: ${Object.keys(PACKAGE_CATEGORY_MAP).map((p) => p.replace("@howdoi-cli/", "")).join(", ")}`));
+    } else {
+      console.log(chalk.yellow("  No tools found."));
+    }
+    console.log();
+    return;
+  }
+  console.log();
+  const packageOrder = Object.keys(PACKAGE_CATEGORY_MAP);
+  const sortedPackages = [...packageMap.keys()].sort(
+    (a, b) => packageOrder.indexOf(a) - packageOrder.indexOf(b)
+  );
+  for (const pkg of sortedPackages) {
+    const catMap = packageMap.get(pkg);
+    console.log(chalk.bold.white(`  ${pkg}`));
+    console.log(chalk.dim("  " + "\u2500".repeat(50)));
+    const sortedCats = [...catMap.keys()].sort(
+      (a, b) => CATEGORY_ORDER.indexOf(a) - CATEGORY_ORDER.indexOf(b)
+    );
+    for (const cat of sortedCats) {
+      const catTools = catMap.get(cat);
+      console.log();
+      console.log(`    ${chalk.bold.yellow(CATEGORY_LABELS[cat] ?? cat)}`);
+      for (const tool of catTools) {
+        console.log(
+          `      ${chalk.green(tool.tool.padEnd(22))} ${chalk.dim(tool.description)}`
+        );
+      }
+    }
+    console.log();
+  }
+  console.log(
+    chalk.dim(`  ${filteredTools.length} tool${filteredTools.length !== 1 ? "s" : ""} across ${packageCount} package${packageCount !== 1 ? "s" : ""}`)
+  );
+  console.log();
+}
+
+// src/cli/index.ts
+import chalk2 from "chalk";
+import { select } from "@inquirer/prompts";
+var VERSION = "__HOWDOI_VERSION__";
+async function promptSelect(message, choices) {
+  try {
+    return await select({
+      message,
+      choices: choices.map((c) => ({
+        name: c.description ? `${c.name}  ${chalk2.dim(c.description)}` : c.name,
+        value: c.value
+      })),
+      pageSize: 12
+    });
+  } catch {
+    return null;
+  }
+}
+async function guidedMode(engine) {
+  renderWelcome();
+  const categoryMap = engine.getToolsByCategory();
+  const selectedCategory = await promptSelect(
+    "What area are you working in?",
+    CATEGORY_ORDER.filter((c) => categoryMap.has(c)).map((c) => ({
+      name: CATEGORY_LABELS[c] ?? c,
+      value: c,
+      description: `${categoryMap.get(c).length} tools`
+    }))
+  );
+  if (!selectedCategory) {
+    console.log(chalk2.dim("\n  Bye!\n"));
+    return;
+  }
+  const tools = categoryMap.get(selectedCategory) ?? [];
+  const selectedTool = await promptSelect(
+    `Which ${CATEGORY_LABELS[selectedCategory]} tool?`,
+    tools.map((t) => ({
+      name: t.tool,
+      value: t.tool,
+      description: t.description
+    }))
+  );
+  if (!selectedTool) {
+    console.log(chalk2.dim("\n  Bye!\n"));
+    return;
+  }
+  const tool = tools.find((t) => t.tool === selectedTool);
+  if (tool) renderToolCard(tool);
+}
+function intentSearch(query, engine) {
+  const results = engine.search(query);
+  if (results.length === 0) {
+    renderNoResults(query);
+    return;
+  }
+  const top = results[0];
+  renderToolCard(top.tool, top.matchedIntent);
+  if (results.length > 1) {
+    console.log(chalk2.dim("  Also relevant:"));
+    for (const r of results.slice(1, 4)) {
+      console.log(
+        `    ${chalk2.cyan(r.tool.tool.padEnd(22))} ${chalk2.dim(r.tool.description)}`
+      );
+    }
+    console.log();
+  }
+}
+function printVersion() {
+  console.log(`howdoi v${VERSION}`);
+}
+function printHelp() {
+  console.log();
+  console.log(chalk2.bold.white("  howdoi") + "  \u2014 intent-based command discovery");
+  console.log();
+  console.log("  " + chalk2.bold("Usage"));
+  console.log(`    ${chalk2.green("howdoi")}                         ${chalk2.dim("guided category browser")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("<intent>")}               ${chalk2.dim("search by what you want to do")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("<tool>")}                 ${chalk2.dim("show all examples for a tool")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("--list")}                 ${chalk2.dim("list all tools grouped by package")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("--list <package>")}       ${chalk2.dim("list tools for a specific package")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("--version")}              ${chalk2.dim("show installed version")}`);
+  console.log(`    ${chalk2.green("howdoi")} ${chalk2.yellow("--help")}                 ${chalk2.dim("show this help message")}`);
+  console.log();
+  console.log("  " + chalk2.bold("Examples"));
+  console.log(`    ${chalk2.green("howdoi")} search for text in file`);
+  console.log(`    ${chalk2.green("howdoi")} undo last commit`);
+  console.log(`    ${chalk2.green("howdoi")} add ssh key to agent`);
+  console.log(`    ${chalk2.green("howdoi")} run container in background`);
+  console.log(`    ${chalk2.green("howdoi")} grep`);
+  console.log(`    ${chalk2.green("howdoi")} --list`);
+  console.log(`    ${chalk2.green("howdoi")} --list unix`);
+  console.log(`    ${chalk2.green("howdoi")} --list git`);
+  console.log(`    ${chalk2.green("howdoi")} --version`);
+  console.log();
+  console.log("  " + chalk2.bold("Install knowledge bases"));
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/unix")}`);
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/git")}`);
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/ssh")}`);
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/docker")}`);
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/networking")}`);
+  console.log(`    ${chalk2.cyan("npm install -g @howdoi-cli/all")}  ${chalk2.dim("\u2190 everything")}`);
+  console.log();
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === "--version" || args[0] === "-v") {
+    printVersion();
+    return;
+  }
+  if (args[0] === "--help" || args[0] === "-h") {
+    printHelp();
+    return;
+  }
+  const tools = loadAllTools();
+  const engine = new SearchEngine(tools);
+  if (args[0] === "--list" || args[0] === "-l") {
+    const packageFilter = args[1];
+    renderWelcome();
+    renderList(tools, packageFilter);
+    return;
+  }
+  if (args.length === 0) {
+    await guidedMode(engine);
+    return;
+  }
+  const query = args.join(" ").trim();
+  const exactTool = tools.find(
+    (t) => t.tool.toLowerCase() === query.toLowerCase()
+  );
+  if (exactTool) {
+    renderToolCard(exactTool);
+    return;
+  }
+  intentSearch(query, engine);
+}
+main().catch((err) => {
+  console.error(chalk2.red("Error: ") + err.message);
+  process.exit(1);
+});

package/dist/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@howdoi-cli/core",
+  "version": "1.0.1",
+  "description": "The howdoi CLI engine — intent-based command discovery for the terminal.",
+  "type": "module",
+  "bin": {
+    "howdoi": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/cli/index.ts",
+    "build": "tsup",
+    "prepublishOnly": "bun run build",
+    "publish:npm": "npm publish"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0",
+    "fuse.js": "^7.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "keywords": [
+    "cli",
+    "unix",
+    "terminal",
+    "git",
+    "commands",
+    "developer-tools",
+    "howdoi"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SiphoChris/howdoi-cli"
+  },
+  "homepage": "https://github.com/SiphoChris/howdoi-cli#readme",
+  "bugs": {
+    "url": "https://github.com/SiphoChris/howdoi-cli/issues"
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@howdoi-cli/core",
+  "version": "1.0.1",
+  "description": "The howdoi CLI engine — intent-based command discovery for the terminal.",
+  "type": "module",
+  "bin": {
+    "howdoi": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/cli/index.ts",
+    "build": "tsup",
+    "prepublishOnly": "bun run build",
+    "publish:npm": "npm publish"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0",
+    "fuse.js": "^7.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "keywords": [
+    "cli",
+    "unix",
+    "terminal",
+    "git",
+    "commands",
+    "developer-tools",
+    "howdoi"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SiphoChris/howdoi-cli"
+  },
+  "homepage": "https://github.com/SiphoChris/howdoi-cli#readme",
+  "bugs": {
+    "url": "https://github.com/SiphoChris/howdoi-cli/issues"
+  }
+}