@crafter/cli-tree 0.1.2 → 0.2.0

package/dist/cli.js

@@ -5,9 +5,13 @@ import {
   treeToString
 } from "./chunk-v5w3w6bd.js";
 import {
+  crossCliToFlowWorkflow,
+  formatTimeRange,
   mineCli,
-  minedToFlowWorkflow
-} from "./chunk-dnq2rnr7.js";
+  mineCrossCli,
+  minedToFlowWorkflow,
+  sparkline
+} from "./chunk-9pnqbn7b.js";
 import {
   NullDelegate,
   runArchaeology
@@ -28,7 +32,7 @@ import"./chunk-q4se2rwe.js";
 // src/cli.ts
 var args = process.argv.slice(2);
 var subcommand = args[0];
-var HELP_SUBCOMMANDS = new Set(["flow", "mine", "archaeology"]);
+var HELP_SUBCOMMANDS = new Set(["flow", "mine", "archaeology", "safe-help", "cross"]);
 var isHelpFlag = args.includes("--help") || args.includes("-h");
 if (!subcommand || isHelpFlag && !HELP_SUBCOMMANDS.has(subcommand ?? "")) {
   printMainHelp();
@@ -41,6 +45,10 @@ if (isHelpFlag) {
     printMineHelp();
   else if (subcommand === "archaeology")
     printArchaeologyHelp();
+  else if (subcommand === "safe-help")
+    printSafeHelpHelp();
+  else if (subcommand === "cross")
+    printCrossHelp();
   else
     printMainHelp();
   process.exit(0);
@@ -51,6 +59,10 @@ if (subcommand === "flow") {
   await runMine(args.slice(1));
 } else if (subcommand === "archaeology") {
   await runArchaeologyCmd(args.slice(1));
+} else if (subcommand === "safe-help") {
+  await runSafeHelp(args.slice(1));
+} else if (subcommand === "cross") {
+  await runCross(args.slice(1));
 } else {
   await runTree(args);
 }
@@ -62,22 +74,98 @@ function printMainHelp() {
     clitree <binary> [options]              Render command tree from --help
     clitree flow <file> [options]           Render a workflow YAML as a DAG
     clitree mine <binary> [options]         Mine shell history for workflows
+    clitree cross [options]                 Detect cross-CLI workflows (git + gh, docker + kubectl)
     clitree archaeology <binary> [options]  Full analysis: tree + mining + (LLM)
+    clitree safe-help <binary> [sub...]     Fetch clean help for any CLI (no pager, no overstriking)
 
   Examples:
     clitree docker                          # basic tree
     clitree mine git                        # "what workflows do I repeat with git?"
+    clitree cross                           # cross-CLI flows across your history
     clitree archaeology bun                 # tree + mining + LLM archaeology
+    clitree safe-help git commit            # avoid the git man-page pager trap
 
   Subcommands:
     tree          Parse --help output (default; passing a binary name invokes this)
     flow          Render a workflow YAML file as an ASCII DAG
-    mine          Discover workflows from your shell history
+    mine          Discover workflows from your shell history (single CLI)
+    cross         Discover workflows that span multiple CLIs (e.g. git → gh)
     archaeology   Run full analysis (tree + mine + LLM proposals when available)
+    safe-help     Return inline help for any CLI, handling pager/overstrike edge cases
 
   Help for a subcommand: clitree <subcommand> --help
 `);
 }
+function printCrossHelp() {
+  console.log(`
+  clitree cross — Mine cross-CLI workflows from your shell history
+
+  Usage:
+    clitree cross [options]
+
+  This is mineCli's bigger sibling. Instead of filtering history to a single
+  binary, it looks at every command in a session and finds sequences that weave
+  between tools — e.g.:
+
+    git push → gh pr create
+    docker build → docker push → kubectl apply
+    bun test → git commit → git push
+
+  These patterns are invisible to 'clitree mine <cli>' because they cross boundaries.
+
+  Examples:
+    clitree cross                           # top 10 cross-CLI workflows
+    clitree cross --top-k 5                 # just the top 5
+    clitree cross --only git,gh,docker      # restrict to a set of CLIs
+    clitree cross --format json             # raw data
+
+  Options:
+    --top-k <n>             Max workflows to return (default: 10)
+    --min-support <n>       Minimum occurrences (default: 3)
+    --min-path-length <n>   Minimum chain length (default: 2)
+    --max-path-length <n>   Maximum chain length (default: 5)
+    --min-distinct-clis <n> Require at least this many distinct CLIs (default: 2)
+    --only <csv>            Whitelist: only include these CLIs (comma-separated)
+    --format <fmt>          ansi (default) or json
+    --no-color              Disable ANSI colors
+    --no-flow               Skip DAG rendering of the top workflow
+    -h, --help              Show this help
+`);
+}
+function printSafeHelpHelp() {
+  console.log(`
+  clitree safe-help — Fetch clean help output for any CLI
+
+  Usage:
+    clitree safe-help <binary> [subcommand...] [options]
+
+  Why this exists:
+    Running '<cli> --help' directly is a minefield on agents and scripts:
+      - 'git commit --help' opens a pager in a TTY and hangs
+      - Piping 'git <sub> --help' returns nroff with overstrike (ffiixxuupp)
+      - Some CLIs use 'help <sub>' instead of '<sub> --help'
+      - macOS man pages emit \\b sequences that need col -bx
+
+    safe-help tries the right variants in order, cleans overstrikes, and
+    returns plain text every time.
+
+  Strategy (in order):
+    1. <cli> <sub> -h                        — short inline help
+    2. <cli> <sub> --help                    — long help (captured, overstrike-stripped)
+    3. <cli> help <sub>                      — alternate syntax
+    4. MANPAGER=cat man <cli>-<sub> | col -bx — final man fallback
+
+  Examples:
+    clitree safe-help git commit
+    clitree safe-help docker run
+    clitree safe-help kubectl get pods
+    clitree safe-help bun install
+
+  Options:
+    --no-color           Disable ANSI codes (auto-detects non-TTY)
+    -h, --help           Show this help
+`);
+}
 function printMineHelp() {
   console.log(`
   clitree mine — Mine your shell history for CLI workflows
@@ -87,22 +175,26 @@ function printMineHelp() {
 
   Examples:
     clitree mine git
+    clitree mine git --top-k 3                    # render top 3 workflows as DAGs
     clitree mine docker --min-support 5 --with-flow
     clitree mine bun --format json > bun-flows.json
     clitree mine git --no-color | tee report.txt
+    clitree mine git --no-activity                # skip temporal sparklines
 
   Options:
     --min-support <n>    Minimum occurrences to count as a workflow (default: 3)
     --history-path <p>   Custom shell history path (default: ~/.zsh_history)
     --format <fmt>       Output format: ansi (default), json
-    --max-paths <n>      Max workflows to show (default: 10)
-    --with-flow          Always render the top workflow as an ASCII DAG
-    --no-flow            Never render the DAG (overrides auto-detect)
+    --max-paths <n>      Max workflows to show in text list (default: 10)
+    --top-k <n>          Render top N workflows as DAGs (default: 1)
+    --with-flow          Include 2-step workflows in DAG rendering
+    --no-flow            Skip DAG rendering entirely
+    --no-activity        Skip hour/day/30-day activity sparklines
     --no-color           Disable ANSI colors (also auto-disabled when stdout is not a TTY)
     -h, --help           Show this help
 
-  By default, the top workflow is rendered as a DAG only when it has 3+ steps.
-  Use --with-flow to force it on even for 2-step chains, or --no-flow to skip.
+  By default, the top 3+ step workflow is rendered as a DAG.
+  --top-k bumps that to N distinct workflows stacked on top of each other.
 `);
 }
 function printArchaeologyHelp() {
@@ -273,6 +365,117 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+function stripOverstrike(text) {
+  return text.replace(/(.)\b\1/g, "$1").replace(/_\b(.)/g, "$1").replace(/\b/g, "").replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+function looksLikeHelp(text) {
+  if (!text.trim())
+    return false;
+  if (text.length < 40)
+    return false;
+  const firstChunk = text.slice(0, 200).toLowerCase();
+  if (/(unknown|invalid|no such|not a \w+ command|flag needs an argument|unrecognized)/.test(firstChunk)) {
+    return false;
+  }
+  if (/run '.+' for more information/.test(firstChunk))
+    return false;
+  return true;
+}
+async function tryHelpVariant(binary, argv, timeoutMs = 5000) {
+  try {
+    const proc = Bun.spawn([binary, ...argv], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, PAGER: "cat", MANPAGER: "cat", GIT_PAGER: "cat" }
+    });
+    const timer = setTimeout(() => proc.kill(), timeoutMs);
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text()
+    ]);
+    clearTimeout(timer);
+    await proc.exited;
+    const combined = stdout || stderr;
+    if (!looksLikeHelp(combined))
+      return null;
+    return stripOverstrike(combined);
+  } catch {
+    return null;
+  }
+}
+async function tryManPage(binary, subPath, timeoutMs = 5000) {
+  const candidates = [
+    subPath.length > 0 ? [`${binary}-${subPath.join("-")}`] : [binary],
+    [binary, ...subPath]
+  ];
+  for (const args2 of candidates) {
+    try {
+      const proc = Bun.spawn(["man", ...args2], {
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, MANPAGER: "cat", PAGER: "cat" }
+      });
+      const timer = setTimeout(() => proc.kill(), timeoutMs);
+      const [stdout] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text()
+      ]);
+      clearTimeout(timer);
+      await proc.exited;
+      if (looksLikeHelp(stdout))
+        return stripOverstrike(stdout);
+    } catch {}
+  }
+  return null;
+}
+async function runSafeHelp(args2) {
+  let binary = null;
+  const subPath = [];
+  for (const arg of args2) {
+    if (arg === "--no-color" || arg === "--help" || arg === "-h")
+      continue;
+    if (!binary) {
+      binary = arg;
+    } else {
+      subPath.push(arg);
+    }
+  }
+  if (!binary) {
+    console.error("Error: provide a binary name");
+    console.error("Run 'clitree safe-help --help' for usage");
+    process.exit(1);
+  }
+  const variants = [
+    { label: "short help (-h)", args: [...subPath, "-h"] },
+    { label: "long help (--help)", args: [...subPath, "--help"] }
+  ];
+  if (subPath.length > 0) {
+    variants.push({ label: "help subcommand", args: ["help", ...subPath] });
+  }
+  for (const variant of variants) {
+    const output = await tryHelpVariant(binary, variant.args);
+    if (output) {
+      process.stdout.write(output);
+      if (!output.endsWith(`
+`))
+        process.stdout.write(`
+`);
+      return;
+    }
+  }
+  const manOutput = await tryManPage(binary, subPath);
+  if (manOutput) {
+    process.stdout.write(manOutput);
+    if (!manOutput.endsWith(`
+`))
+      process.stdout.write(`
+`);
+    return;
+  }
+  console.error(`Error: could not fetch help for ${binary} ${subPath.join(" ")}`);
+  console.error("Tried: -h, --help, help subcommand, and man page.");
+  process.exit(1);
+}
 function shouldUseColor(args2) {
   if (args2.includes("--no-color"))
     return false;
@@ -305,6 +508,8 @@ async function runMine(args2) {
   let format = "ansi";
   let maxPaths = 10;
   let withFlow = "auto";
+  let topK = 1;
+  let showActivity = true;
   for (let i = 0;i < args2.length; i++) {
     const arg = args2[i];
     if (arg === "--min-support" && args2[i + 1]) {
@@ -315,10 +520,16 @@ async function runMine(args2) {
       format = args2[++i];
     } else if (arg === "--max-paths" && args2[i + 1]) {
       maxPaths = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--top-k" && args2[i + 1]) {
+      topK = Number.parseInt(args2[++i], 10);
+      if (withFlow === "auto")
+        withFlow = "on";
     } else if (arg === "--with-flow" || arg === "--flow") {
       withFlow = "on";
     } else if (arg === "--no-flow") {
       withFlow = "off";
+    } else if (arg === "--no-activity") {
+      showActivity = false;
     } else if (arg !== "--no-color" && !arg.startsWith("-")) {
       binary = arg;
     }
@@ -352,6 +563,9 @@ ${C.bold}${C.magenta}${binary}${C.reset} ${C.gray}— shell history analysis${C.
       }
       console.log();
     }
+    if (showActivity && result.activity.total > 0) {
+      renderActivitySection(result.activity, C);
+    }
     if (result.workflows.length > 0) {
       console.log(`${C.bold}Discovered workflows:${C.reset}`);
       for (const wf of result.workflows.slice(0, maxPaths)) {
@@ -373,12 +587,18 @@ ${C.bold}${C.magenta}${binary}${C.reset} ${C.gray}— shell history analysis${C.
     }
     if (withFlow !== "off") {
       const minSteps = withFlow === "on" ? 2 : 3;
-      const topForFlow = pickWorkflowForFlow(result.workflows, minSteps);
-      if (topForFlow) {
-        const flowWorkflow = minedToFlowWorkflow(topForFlow);
-        const rendered = shouldUseColor(args2) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
-        console.log(`${C.bold}Top workflow (visualized):${C.reset}`);
-        console.log(rendered);
+      const topK_effective = Math.max(1, topK);
+      const candidates = pickWorkflowsForFlow(result.workflows, minSteps, topK_effective);
+      if (candidates.length > 0) {
+        const header = candidates.length === 1 ? "Top workflow (visualized):" : `Top ${candidates.length} workflows (visualized):`;
+        console.log(`${C.bold}${header}${C.reset}`);
+        for (let i = 0;i < candidates.length; i++) {
+          if (i > 0)
+            console.log(`${C.gray}${"─".repeat(60)}${C.reset}`);
+          const flowWorkflow = minedToFlowWorkflow(candidates[i]);
+          const rendered = shouldUseColor(args2) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
+          console.log(rendered);
+        }
         console.log();
       }
     }
@@ -387,13 +607,124 @@ ${C.bold}${C.magenta}${binary}${C.reset} ${C.gray}— shell history analysis${C.
     process.exit(1);
   }
 }
-function pickWorkflowForFlow(workflows, minSteps = 3) {
+function renderActivitySection(activity, C) {
+  if (activity.firstSeen === 0)
+    return;
+  const dayNames = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  console.log(`${C.bold}Activity:${C.reset}`);
+  const range = formatTimeRange(activity.firstSeen, activity.lastSeen);
+  console.log(`  ${C.dim}Tracked over:${C.reset} ${C.cyan}${range}${C.reset}`);
+  const hourSpark = sparkline(activity.hourOfDay);
+  console.log(`  ${C.dim}Hour of day: ${C.reset}${C.cyan}${hourSpark}${C.reset} ${C.dim}(0h → 23h)${C.reset}`);
+  const dowMax = Math.max(...activity.dayOfWeek);
+  if (dowMax > 0) {
+    console.log(`  ${C.dim}Day of week:${C.reset}`);
+    for (let i = 0;i < 7; i++) {
+      const count = activity.dayOfWeek[i];
+      const barLen = dowMax > 0 ? Math.round(count / dowMax * 20) : 0;
+      const bar = "█".repeat(Math.max(count > 0 ? 1 : 0, barLen));
+      console.log(`    ${C.gray}${dayNames[i]}${C.reset} ${C.cyan}${bar}${C.reset} ${C.dim}${count}${C.reset}`);
+    }
+  }
+  if (activity.last30Days.some((v) => v > 0)) {
+    const monthSpark = sparkline(activity.last30Days);
+    console.log(`  ${C.dim}Last 30 days:${C.reset} ${C.cyan}${monthSpark}${C.reset} ${C.dim}(30d ago → today)${C.reset}`);
+  }
+  console.log();
+}
+function pickWorkflowsForFlow(workflows, minSteps, topK) {
+  const result = [];
+  const signatures = new Set;
   for (const wf of workflows) {
     const len = wf.path[0]?.length ?? 0;
-    if (len >= minSteps)
-      return wf;
+    if (len < minSteps)
+      continue;
+    const sig = wf.path[0].join(" → ");
+    if (signatures.has(sig))
+      continue;
+    signatures.add(sig);
+    result.push(wf);
+    if (result.length >= topK)
+      break;
+  }
+  return result;
+}
+async function runCross(args2) {
+  let format = "ansi";
+  let topK = 10;
+  let minSupport = 3;
+  let minPathLength = 2;
+  let maxPathLength = 5;
+  let minDistinctCLIs = 2;
+  let onlyList = [];
+  let withFlow = true;
+  for (let i = 0;i < args2.length; i++) {
+    const arg = args2[i];
+    if (arg === "--top-k" && args2[i + 1]) {
+      topK = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--min-support" && args2[i + 1]) {
+      minSupport = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--min-path-length" && args2[i + 1]) {
+      minPathLength = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--max-path-length" && args2[i + 1]) {
+      maxPathLength = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--min-distinct-clis" && args2[i + 1]) {
+      minDistinctCLIs = Number.parseInt(args2[++i], 10);
+    } else if (arg === "--only" && args2[i + 1]) {
+      onlyList = args2[++i].split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (arg === "--format" && args2[i + 1]) {
+      format = args2[++i];
+    } else if (arg === "--no-flow") {
+      withFlow = false;
+    }
+  }
+  try {
+    const result = await mineCrossCli({
+      topK,
+      minSupport,
+      minPathLength,
+      maxPathLength,
+      minDistinctCLIs,
+      allowedCLIs: onlyList.length > 0 ? onlyList : undefined
+    });
+    if (format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const C = makeColors(shouldUseColor(args2));
+    console.log(`
+${C.bold}${C.magenta}cross-CLI workflow analysis${C.reset}
+`);
+    console.log(`${C.bold}Scope:${C.reset}`);
+    console.log(`  ${C.dim}Sessions analyzed:${C.reset}  ${C.cyan}${result.sessionsAnalyzed}${C.reset}`);
+    console.log(`  ${C.dim}Distinct CLIs:${C.reset}      ${C.cyan}${result.distinctCLIs.length}${C.reset}`);
+    console.log(`  ${C.dim}Transitions:${C.reset}        ${C.cyan}${result.totalTransitions}${C.reset}
+`);
+    if (result.workflows.length === 0) {
+      console.log(`${C.dim}No cross-CLI workflows found. Try lowering --min-support or --min-distinct-clis.${C.reset}
+`);
+      return;
+    }
+    console.log(`${C.bold}Cross-CLI workflows (top ${result.workflows.length}):${C.reset}`);
+    for (let i = 0;i < result.workflows.length; i++) {
+      const wf = result.workflows[i];
+      const chain = wf.path.map((s) => `${C.green}${s.cli}${C.reset} ${C.cyan}${s.subcommand}${C.reset}`).join(` ${C.gray}→${C.reset} `);
+      console.log(`  ${C.dim}${(i + 1).toString().padStart(2)}.${C.reset} ${chain}`);
+      console.log(`      ${C.dim}seen ${wf.support}×, ${wf.uniqueCLIs} distinct CLIs${C.reset}`);
+    }
+    console.log();
+    if (withFlow && result.workflows.length > 0) {
+      const top = result.workflows[0];
+      const flowWorkflow = crossCliToFlowWorkflow(top);
+      const rendered = shouldUseColor(args2) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
+      console.log(`${C.bold}Top cross-CLI workflow (visualized):${C.reset}`);
+      console.log(rendered);
+      console.log();
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
   }
-  return null;
 }
 async function runArchaeologyCmd(args2) {
   let binary = null;
@@ -470,4 +801,4 @@ ${C.bold}${C.yellow}\uD83D\uDCA1 Skill suggestions:${C.reset}`);
   }
 }
 
-//# debugId=FADAD3DCBCB5252964756E2164756E21
+//# debugId=36C7EC67BF0C8B9764756E2164756E21