@crafter/cli-tree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crafter Station
+
+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,328 @@
+# cli-tree
+
+**Visualize and explore any CLI.** Parse help output, mine your shell history for real usage patterns, and (via a coding-agent skill) run LLM archaeology to discover hidden flags and canonical workflows.
+
+Zero dependencies. Bun-native. Works as a library, a binary, or a skill for Claude Code / Cursor / Codex.
+
+---
+
+## What it does
+
+```
+           ┌─────────────┐
+           │   cli-tree  │
+           └──────┬──────┘
+                  │
+      ┌───────────┼───────────┐
+      ▼           ▼           ▼
+  ┌──────┐   ┌────────┐   ┌───────────┐
+  │ tree │   │  mine  │   │archaeology│
+  └──────┘   └────────┘   └───────────┘
+     │           │              │
+  --help     shell history     LLM
+  parser     markov chain   (via skill)
+```
+
+Four things:
+
+1. **`tree`** — parse `--help` output of any CLI into a navigable box-drawing tree. 53+ real CLIs tested.
+2. **`flow`** — render workflow YAML files as terminal DAGs (6 curated examples).
+3. **`mine`** — analyze your shell history, detect repeated sequences, surface skill suggestions.
+4. **`archaeology`** — merge all three + LLM-proposed hidden flags, validated against real `--help`.
+
+---
+
+## Install
+
+From npm (recommended):
+
+```bash
+# One-shot (no install)
+bunx @crafter/cli-tree git
+npx  @crafter/cli-tree git
+
+# Global install
+bun add -g @crafter/cli-tree
+npm i  -g @crafter/cli-tree
+
+# Then
+clitree git
+clitree mine bun
+clitree archaeology docker
+```
+
+As a library in your project:
+
+```bash
+bun add @crafter/cli-tree
+```
+
+```ts
+import { parseHelpRecursive } from "@crafter/cli-tree";
+import { mineCli } from "@crafter/cli-tree/miner";
+import { runArchaeology } from "@crafter/cli-tree/archaeology";
+```
+
+From source:
+
+```bash
+git clone https://github.com/crafter-station/cli-tree
+cd cli-tree
+bun install
+bun src/cli.ts --help
+```
+
+---
+
+## Usage
+
+### Tree — parse any CLI's help output
+
+```bash
+clitree git
+clitree docker --depth 2
+clitree kubectl --compact --no-flags
+clitree bun --format html > bun-tree.html
+docker --help | clitree --stdin docker
+```
+
+### Flow — render workflow YAML as DAG
+
+```bash
+clitree flow workflows/git-pr-flow.yml
+clitree flow workflows/docker-deploy.yml --format html
+```
+
+Workflow YAML looks like:
+
+```yaml
+name: pr-flow
+cli: git
+description: Typical flow for creating a pull request
+nodes:
+  - id: add
+    command: git add .
+  - id: commit
+    command: git commit
+  - id: push
+    command: git push
+  - id: pr
+    command: gh pr create
+    optional: true
+edges:
+  - add -> commit
+  - commit -> push
+  - push -> pr
+```
+
+Output (ASCII, ANSI, or HTML):
+
+```
+git · pr-flow
+Typical flow for creating a pull request
+
+┌─────────────────┐
+│     git add     │
+└─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│   git commit    │
+└─────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│    git push     │
+└─────────────────┘
+         │
+         ▼
+┌┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┐
+┊  gh pr create   ┊
+└┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┘
+```
+
+### Mine — discover workflows from your shell history
+
+```bash
+clitree mine git
+clitree mine docker --min-support 5
+clitree mine bun --format json > bun-flows.json
+```
+
+Example output against real zsh history:
+
+```
+git — shell history analysis
+
+Usage:
+  Invocations:  1257
+  Subcommands:  31
+  Sessions:     483
+
+Top subcommands:
+  commit               ██████████████████████████████ 277
+  checkout             ██████████████████████████     237
+  push                 ████████████████████           183
+  add                  ██████████████████             167
+  pull                 █████████████                  124
+
+Discovered workflows:
+  add → commit               (116×)
+  commit → push              (85×)
+  add → commit → push        (64×)
+  checkout → pull            (38×)
+
+💡 Skill suggestions:
+
+  [MED] /ship — Run git add, then commit, then push as one command
+    You run this exact sequence 64 times — that's a lot of repetition
+    git add && git commit && git push
+```
+
+### Archaeology — full analysis
+
+```bash
+clitree archaeology git             # deterministic phases
+clitree archaeology docker --no-cache
+```
+
+Without the skill, archaeology runs `--help` parsing + history mining. For LLM-backed hidden-flag discovery, install the clitree skill (see below).
+
+---
+
+## The clitree skill
+
+The LLM-archaeology phase lives in a coding-agent skill. It is **agent-agnostic**: the skill is just markdown instructions that any coding agent (Claude Code, Cursor, Codex, Aider) can execute.
+
+Install:
+
+```bash
+bash ./skill/install.sh
+```
+
+Then, inside your coding agent:
+
+```
+/clitree git
+```
+
+The agent will:
+
+1. Parse `git --help` recursively.
+2. Mine your shell history for real workflows.
+3. **Use its own LLM** to propose hidden/undocumented flags.
+4. **Validate every proposal** by running `git <sub> --help` and checking man pages.
+5. **Reject hallucinations** automatically — only flags that actually exist make it into the final tree.
+6. **Suggest new skills** based on workflows you repeat often.
+
+No API keys. No external services. Works entirely inside your coding agent.
+
+---
+
+## How archaeology works
+
+The key insight is that an LLM's knowledge of a CLI is **unreliable alone** but **rich when validated**. Archaeology uses a closed loop:
+
+```
+┌─────────────┐     proposes       ┌───────────────┐
+│   The LLM   │ ─────────────────► │  cli-tree     │
+│  (in agent) │                    │  validator    │
+└─────────────┘                    └───────┬───────┘
+      ▲                                    │
+      │ next proposal                      │ runs
+      │                                    ▼
+      │                          ┌──────────────────┐
+      │                          │ <cli> <sub>      │
+      └──────  verdict ─────────│ --help / man     │
+                                  └──────────────────┘
+                                  verify or reject
+```
+
+- **LLM proposes** → hidden flags, canonical workflows, constraint maps
+- **Code executes** → `git commit --fixup` → real output → compare
+- **Truth survives** → only verified facts become part of the enriched tree
+
+Every piece of data carries a **source tag**:
+
+| Source | Confidence | Behavior |
+|--------|-----------|----------|
+| `help` | 1.0 | From parsed `--help` output |
+| `llm-validated` | 0.9 | LLM proposed, confirmed by `--help` |
+| `man` | 0.85 | From man page |
+| `llm-deep-dive` | 0.6 | LLM proposed, not confirmed (shown with `--include-unverified`) |
+| `llm-survey` | 0.2 | LLM hypothesis, rejected by validation |
+
+By default, only sources above `llm-validated` are shown.
+
+---
+
+## Architecture
+
+```
+src/
+├── parse.ts            # --help parser (53 CLIs tested)
+├── tree.ts             # tree renderer (box-drawing)
+├── compile.ts          # chart primitives
+│
+├── miner/              # shell history mining
+│   ├── history.ts      # zsh/bash/fish parser
+│   ├── sessions.ts     # temporal segmentation
+│   ├── transitions.ts  # markov chain
+│   ├── workflows.ts    # path clustering
+│   ├── stats.ts        # usage statistics
+│   └── suggest.ts      # skill suggestions
+│
+├── archaeology/        # LLM-backed exploration
+│   ├── types.ts        # Source/EnrichedCLINode
+│   ├── prompts.ts      # 4-phase prompt templates
+│   ├── validate.ts     # closed-loop validation
+│   ├── merge.ts        # multi-source merge
+│   ├── cache.ts        # ~/.clitree/cache/
+│   ├── delegate.ts     # agent-agnostic delegate
+│   └── orchestrator.ts # runs all phases
+│
+├── flow/               # workflow DAG rendering
+│   ├── types.ts
+│   ├── yaml.ts         # zero-dep YAML parser
+│   ├── layout.ts       # rank-based layout
+│   ├── render.ts       # box-drawing DAG
+│   └── encode.ts
+│
+└── cli.ts              # binary entrypoint
+```
+
+---
+
+## Tests
+
+```bash
+bun test                          # run all (~290 tests)
+bun test tests/flow               # flow subsystem
+bun test tests/miner              # miner subsystem
+bun test tests/archaeology        # archaeology subsystem
+bun test tests/parse-real-clis    # 53+ real CLIs
+```
+
+Recent run: **287 tests passing, 0 fails** across 8 test files.
+
+---
+
+## Roadmap
+
+- [x] `--help` parser (53 CLIs)
+- [x] Box-drawing tree renderer (ANSI / string / HTML)
+- [x] Workflow YAML DAG renderer
+- [x] Shell history miner (zsh / bash / fish)
+- [x] Skill suggestions from repeated workflows
+- [x] Archaeology types + validation loop + merge
+- [x] Disk cache
+- [x] Agent-agnostic skill
+- [ ] Makefile / package.json / Dockerfile scraping
+- [ ] Interactive TUI mode
+- [ ] Mermaid export for flows
+
+---
+
+## License
+
+MIT

package/dist/archaeology/cache.d.ts

@@ -0,0 +1,11 @@
+import type { ArchaeologyCache, EnrichedCLINode } from "./types";
+export interface CacheOptions {
+    cacheDir?: string;
+    ttlDays?: number;
+}
+export declare function loadCache(cli: string, opts?: CacheOptions): Promise<ArchaeologyCache | null>;
+export declare function saveCache(cli: string, cache: ArchaeologyCache, opts?: CacheOptions): Promise<void>;
+export declare function invalidateCache(cli: string, opts?: CacheOptions): Promise<void>;
+export declare function isCacheStale(cache: ArchaeologyCache, currentVersion?: string, ttlDays?: number): boolean;
+export declare function detectCliVersion(binary: string): Promise<string | undefined>;
+export declare function createEmptyCache(cli: string, tree: EnrichedCLINode, cliVersion?: string): ArchaeologyCache;

package/dist/archaeology/delegate.d.ts

@@ -0,0 +1,43 @@
+import type { DeepDiveProposal, SurveyHypothesis, FlagConstraint } from "./types";
+export interface ArchaeologyDelegate {
+    readonly name: string;
+    readonly available: boolean;
+    survey?(cli: string, version?: string): Promise<SurveyHypothesis>;
+    proposeHiddenFlags?(cli: string, subcommand: string[]): Promise<DeepDiveProposal>;
+    proposeConstraints?(cli: string, subcommand: string[]): Promise<FlagConstraint[]>;
+}
+export declare class NullDelegate implements ArchaeologyDelegate {
+    readonly name = "null";
+    readonly available = false;
+}
+export declare class BridgeFileDelegate implements ArchaeologyDelegate {
+    readonly name = "bridge-file";
+    readonly available = true;
+    private requestsPath;
+    private responsesPath;
+    private timeoutMs;
+    constructor(opts?: {
+        requestsPath?: string;
+        responsesPath?: string;
+        timeoutMs?: number;
+    });
+    survey(cli: string, version?: string): Promise<SurveyHypothesis>;
+    proposeHiddenFlags(cli: string, subcommand: string[]): Promise<DeepDiveProposal>;
+    proposeConstraints(cli: string, subcommand: string[]): Promise<FlagConstraint[]>;
+    private writeRequest;
+    private awaitResponse;
+    private readFile;
+}
+export declare class InlineDelegate implements ArchaeologyDelegate {
+    private handlers;
+    readonly name = "inline";
+    readonly available = true;
+    constructor(handlers: {
+        survey?: (cli: string, version?: string) => Promise<SurveyHypothesis>;
+        proposeHiddenFlags?: (cli: string, subcommand: string[]) => Promise<DeepDiveProposal>;
+        proposeConstraints?: (cli: string, subcommand: string[]) => Promise<FlagConstraint[]>;
+    });
+    survey(cli: string, version?: string): Promise<SurveyHypothesis>;
+    proposeHiddenFlags(cli: string, subcommand: string[]): Promise<DeepDiveProposal>;
+    proposeConstraints(cli: string, subcommand: string[]): Promise<FlagConstraint[]>;
+}

package/dist/archaeology/index.d.ts

@@ -0,0 +1,12 @@
+export type { Source, SourceKind, EnrichedCLINode, EnrichedFlag, EnrichedArg, Example, FlagConstraint, SurveyHypothesis, DeepDiveProposal, ValidationVerdict, ArchaeologyCache, ArchaeologyOptions, } from "./types";
+export { toCLINode, fromCLINode } from "./types";
+export { surveyPrompt, excavationPrompt, deepDivePrompt, cartographyPrompt, validationInstructions, extractJsonFromLlmResponse, } from "./prompts";
+export { runHelpCommand, validateSubcommandExists, validateSurvey, excavateCommand, validateDeepDive, summarizeValidation, } from "./validate";
+export type { ValidationSummary } from "./validate";
+export { mergeNodes, filterUnverified } from "./merge";
+export { loadCache, saveCache, invalidateCache, isCacheStale, detectCliVersion, createEmptyCache } from "./cache";
+export type { CacheOptions } from "./cache";
+export type { ArchaeologyDelegate } from "./delegate";
+export { NullDelegate, BridgeFileDelegate, InlineDelegate } from "./delegate";
+export { runArchaeology, enrichedToTree } from "./orchestrator";
+export type { ArchaeologyProgress, ArchaeologyResult } from "./orchestrator";

package/dist/archaeology/index.js

@@ -0,0 +1,61 @@
+import {
+  BridgeFileDelegate,
+  InlineDelegate,
+  NullDelegate,
+  cartographyPrompt,
+  createEmptyCache,
+  deepDivePrompt,
+  detectCliVersion,
+  enrichedToTree,
+  excavateCommand,
+  excavationPrompt,
+  extractJsonFromLlmResponse,
+  filterUnverified,
+  fromCLINode,
+  invalidateCache,
+  isCacheStale,
+  loadCache,
+  mergeNodes,
+  runArchaeology,
+  runHelpCommand,
+  saveCache,
+  summarizeValidation,
+  surveyPrompt,
+  toCLINode,
+  validateDeepDive,
+  validateSubcommandExists,
+  validateSurvey,
+  validationInstructions
+} from "../chunk-ykze151b.js";
+import"../chunk-5aahbfr2.js";
+export {
+  validationInstructions,
+  validateSurvey,
+  validateSubcommandExists,
+  validateDeepDive,
+  toCLINode,
+  surveyPrompt,
+  summarizeValidation,
+  saveCache,
+  runHelpCommand,
+  runArchaeology,
+  mergeNodes,
+  loadCache,
+  isCacheStale,
+  invalidateCache,
+  fromCLINode,
+  filterUnverified,
+  extractJsonFromLlmResponse,
+  excavationPrompt,
+  excavateCommand,
+  enrichedToTree,
+  detectCliVersion,
+  deepDivePrompt,
+  createEmptyCache,
+  cartographyPrompt,
+  NullDelegate,
+  InlineDelegate,
+  BridgeFileDelegate
+};
+
+//# debugId=EAE38CC12C5BE71664756E2164756E21

package/dist/archaeology/index.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "EAE38CC12C5BE71664756E2164756E21",
+  "names": []
+}

package/dist/archaeology/llm.d.ts

@@ -0,0 +1 @@
+export { type ArchaeologyDelegate, NullDelegate, BridgeFileDelegate, InlineDelegate, } from "./delegate";

package/dist/archaeology/merge.d.ts

@@ -0,0 +1,3 @@
+import type { EnrichedCLINode } from "./types";
+export declare function mergeNodes(a: EnrichedCLINode, b: EnrichedCLINode): EnrichedCLINode;
+export declare function filterUnverified(node: EnrichedCLINode): EnrichedCLINode;

package/dist/archaeology/orchestrator.d.ts

@@ -0,0 +1,25 @@
+import { type EnrichedCLINode, type ArchaeologyOptions } from "./types";
+import type { ArchaeologyDelegate } from "./delegate";
+import type { CLINode } from "../types";
+export interface ArchaeologyProgress {
+    phase: "cache" | "excavation" | "survey" | "deep-dive" | "cartography" | "merge" | "done";
+    message: string;
+    percent?: number;
+}
+export interface ArchaeologyResult {
+    tree: EnrichedCLINode;
+    stats: {
+        helpCommands: number;
+        llmProposed: number;
+        verified: number;
+        rejected: number;
+        unconfirmed: number;
+        hallucinations: string[];
+    };
+    fromCache: boolean;
+}
+export declare function runArchaeology(binary: string, delegate?: ArchaeologyDelegate, opts?: ArchaeologyOptions & {
+    onProgress?: (p: ArchaeologyProgress) => void;
+    maxHelpDepth?: number;
+}): Promise<ArchaeologyResult>;
+export declare function enrichedToTree(enriched: EnrichedCLINode): CLINode;

package/dist/archaeology/prompts.d.ts

@@ -0,0 +1,13 @@
+import type { EnrichedCLINode } from "./types";
+export interface PromptContext {
+    cli: string;
+    version?: string;
+    knownCommands?: string[];
+    knownTree?: EnrichedCLINode;
+}
+export declare function surveyPrompt(ctx: PromptContext): string;
+export declare function excavationPrompt(ctx: PromptContext, subcommandPath: string[]): string;
+export declare function deepDivePrompt(ctx: PromptContext, subcommandPath: string[]): string;
+export declare function cartographyPrompt(ctx: PromptContext, subcommandPath: string[]): string;
+export declare function validationInstructions(cli: string): string;
+export declare function extractJsonFromLlmResponse(response: string): unknown;

package/dist/archaeology/types.d.ts

@@ -0,0 +1,101 @@
+import type { CLINode, Flag, Arg } from "../types";
+export type SourceKind = "help" | "llm-survey" | "llm-deep-dive" | "llm-cartography" | "llm-validated" | "man" | "completion" | "user";
+export interface Source {
+    type: SourceKind;
+    confidence: number;
+    verifiedAt?: string;
+    note?: string;
+}
+export interface EnrichedFlag extends Flag {
+    hidden?: boolean;
+    deprecated?: boolean;
+    experimental?: boolean;
+    source?: Source;
+    examples?: string[];
+    excludes?: string[];
+    requires?: string[];
+}
+export interface EnrichedArg extends Arg {
+    source?: Source;
+}
+export interface Example {
+    command: string;
+    description?: string;
+    source?: Source;
+}
+export interface FlagConstraint {
+    type: "mutually-exclusive" | "requires" | "implies";
+    flags: string[];
+    description?: string;
+}
+export interface EnrichedCLINode {
+    name: string;
+    description?: string;
+    aliases?: string[];
+    hidden?: boolean;
+    deprecated?: boolean;
+    experimental?: boolean;
+    subcommands?: EnrichedCLINode[];
+    flags?: EnrichedFlag[];
+    args?: EnrichedArg[];
+    constraints?: FlagConstraint[];
+    examples?: Example[];
+    source?: Source;
+}
+export interface SurveyHypothesis {
+    cli: string;
+    description: string;
+    families: Array<{
+        name: string;
+        description: string;
+        subcommands: string[];
+    }>;
+    topLevelFlags: string[];
+}
+export interface DeepDiveProposal {
+    command: string[];
+    flags: Array<{
+        name: string;
+        short?: string;
+        type: "boolean" | "string" | "number" | "enum";
+        hidden?: boolean;
+        deprecated?: boolean;
+        description?: string;
+    }>;
+    examples: string[];
+}
+export interface ValidationVerdict {
+    command: string[];
+    exists: boolean;
+    verifiedFlags: string[];
+    rejectedFlags: string[];
+    unconfirmedFlags: string[];
+    rawHelp?: string;
+    error?: string;
+}
+export interface ArchaeologyCache {
+    cli: string;
+    cliVersion?: string;
+    createdAt: string;
+    tree: EnrichedCLINode;
+    phases: {
+        survey: boolean;
+        excavation: boolean;
+        deepDive: boolean;
+        cartography: boolean;
+    };
+}
+export interface ArchaeologyOptions {
+    cacheDir?: string;
+    skipCache?: boolean;
+    includeUnverified?: boolean;
+    maxDepth?: number;
+    phases?: {
+        survey?: boolean;
+        excavation?: boolean;
+        deepDive?: boolean;
+        cartography?: boolean;
+    };
+}
+export declare function toCLINode(node: EnrichedCLINode): CLINode;
+export declare function fromCLINode(node: CLINode, source?: Source): EnrichedCLINode;

package/dist/archaeology/validate.d.ts

@@ -0,0 +1,18 @@
+import type { CLINode } from "../types";
+import type { ValidationVerdict, SurveyHypothesis, DeepDiveProposal } from "./types";
+export declare function runHelpCommand(binary: string, subcommandPath: string[]): Promise<string | null>;
+export declare function validateSubcommandExists(binary: string, subcommandPath: string[]): Promise<boolean>;
+export declare function validateSurvey(binary: string, survey: SurveyHypothesis): Promise<{
+    confirmed: string[];
+    rejected: string[];
+}>;
+export declare function excavateCommand(binary: string, subcommandPath: string[]): Promise<CLINode | null>;
+export declare function validateDeepDive(binary: string, proposal: DeepDiveProposal): Promise<ValidationVerdict>;
+export interface ValidationSummary {
+    totalProposed: number;
+    verified: number;
+    rejected: number;
+    unconfirmed: number;
+    hallucinations: string[];
+}
+export declare function summarizeValidation(verdicts: ValidationVerdict[]): ValidationSummary;