feat(jay): create skeleton walk and run sub-commands (#408)

[plastikfan]

Summary by CodeRabbit

Release Notes

• New Features

  • Added walk command for directory traversal with subscription control, action targeting, and resume support.
  • Added run command for concurrent directory traversal via worker pool with CPU configuration options.
  • Introduced UI abstraction with Linear display mode for consistent output formatting.
  • Added inspect tool to query exported declarations from cached Go modules.

• Documentation

  • Added comprehensive documentation for configuration, command architecture, and integration patterns.

• Chores

  • Refactored CLI bootstrap and parameter management for improved maintainability.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds a comprehensive CLI command infrastructure for the jay application. It introduces Bootstrap-based startup wiring, implements synchronous (walk) and concurrent (run) directory traversal commands via the agenor library, abstracts terminal UI output through a Manager interface with a linear text implementation, and adds an inspect utility tool for examining cached Go modules. Supporting changes include parameter set definitions, configuration enhancements, and developer documentation.

Changes

Cohort / File(s)	Summary
Documentation .claude/COMMON-COMMANDS.md, CLAUDE.md, cmd/jay/CLAUDE.md, .vscode/settings.json, Taskfile.yml	Added project documentation, development commands reference, VS Code dictionary entries, and task for installing the inspect tool.
Bootstrap Infrastructure cmd/command/bootstrap.go, cmd/command/const.go, cmd/command/root-cmd.go	Refactored startup to use Bootstrap pattern with LocaleDetector/Jabber for language detection, centralized Viper configuration loading, persistent parameter set registration, and UI manager injection into root command context.
Command Parameter Sets cmd/command/param-sets.go, cmd/command/inputs.go	Defined RootParameterSet, WalkParameterSet, RunParameterSet with subscription/action/pipeline/resume flags, and introduced SharedFamilies struct for reusable inherited parameter families across commands.
Walk Command cmd/command/walk-cmd.go	Implemented synchronous directory traversal via agenor's Tortoise facade with support for prime/resume modes, subscription modes, per-node callbacks to UI manager, and completion metrics reporting.
Run Command cmd/command/run-cmd.go	Implemented concurrent directory traversal via agenor's Hare facade with worker-pool configuration (CPU/worker-count flags), WaitGroup synchronization, error handling via UI manager, and metrics reporting.
UI Abstraction cmd/ui/manager.go, cmd/ui/linear.go, cmd/ui/doc.go, cmd/ui/manager_test.go, cmd/ui/ui_suite_test.go	Created Manager interface for output abstraction, implemented linear text renderer with mutex-protected stdout writes, added factory/registry for UI mode selection, and comprehensive test coverage for mode registration and output methods.
Configuration cmd/internal/cfg/loader.go, cmd/internal/cfg/types.go	Renamed internal decode function parameters for clarity and corrected comment wording; no functional changes to configuration loading logic.
Development Tools tools/inspect/main.go	Added CLI utility to inspect cached Go modules, extract exported declarations (vars/consts/types/funcs/interfaces), handle semantic versioning in cache paths, and format AST nodes to readable signatures.

Sequence Diagram(s)

sequenceDiagram
    participant User as User/CLI Entry
    participant Bootstrap
    participant Root as Root Command
    participant Viper as Configuration
    participant LangDetect as Language Detector
    participant Container as Cobra Container

    User->>Bootstrap: Create Bootstrap instance
    Bootstrap->>Bootstrap: prepare() - set defaults
    User->>Bootstrap: Root(options...) 
    Bootstrap->>Bootstrap: apply options
    Bootstrap->>Viper: configure() - init Viper
    Viper-->>Bootstrap: load config file
    Bootstrap->>LangDetect: Scan() detect language
    LangDetect-->>Bootstrap: language.Tag
    Bootstrap->>Bootstrap: handleLangSetting() - set i18n
    Bootstrap->>Container: NewCobraContainer(root)
    Container->>Root: Register root command
    Bootstrap->>Container: MustRegisterParamSet (root, families)
    Container-->>Bootstrap: configured container
    Bootstrap-->>User: *cobra.Command (root)

Loading

sequenceDiagram
    participant CLI as Walk Command
    participant Input as Input Parser
    participant Options as Option Builder
    participant Agenor as Agenor Engine
    participant UI as UI Manager

    CLI->>Input: Parse flags, tree path
    Input->>Input: ResolveSubscription(flag)
    Input-->>CLI: WalkInputs struct
    CLI->>Options: buildOptions(shared flags)
    Options-->>CLI: []agenor.Option
    CLI->>Agenor: pref.Using(facade) or pref.Relic(facade)
    Agenor->>Agenor: Tortoise(isPrime)(facade, opts...).Navigate(ctx)
    loop For each visited node
        Agenor->>UI: OnNode(*core.Node)
        UI-->>Agenor: nil or error
    end
    Agenor-->>CLI: traversal result
    CLI->>UI: Info/Error (completion metrics)

Loading

sequenceDiagram
    participant CLI as Run Command
    participant Input as Input Parser
    participant Agenor as Agenor Engine
    participant Pool as Worker Pool
    participant UI as UI Manager
    participant WG as WaitGroup

    CLI->>Input: Parse flags, tree path, worker config
    Input-->>CLI: RunInputs (includes WorkerPool ParamSet)
    CLI->>Agenor: pref.Using or pref.Relic with facade
    Agenor->>Agenor: apply pool options (--cpu/--now)
    Agenor->>Pool: Initialize worker pool
    CLI->>WG: Create WaitGroup
    CLI->>Agenor: age.Hare(isPrime)(facade, opts...).Navigate(ctx)
    par Concurrent Traversal
        Agenor->>Pool: Distribute work to workers
        Pool->>Pool: Process nodes concurrently
        Pool->>UI: OnNode (synchronized via mutex)
        UI-->>Pool: callback result
    end
    Agenor->>WG: Complete
    WG->>CLI: Wait() returns
    CLI->>UI: Info (completion metrics)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(jay): add skeleton root command (#399) #402: Overlapping changes to Bootstrap startup logic (LocaleDetector/Jabber implementation, Bootstrap.Root method, configuration initialization patterns).
• feat(resume): implement spawn resume (#273) #293: Related through resume strategy implementation (spawn/fastward constants and resolution logic) wired into walk and run command execution flows.

Poem

🐰 Behold! Commands bootstrap with grace,
Walk and run through the forest's embrace,
UI abstracted, the inspect tool gleams,
Parameters dancing in organized schemes,
A warren of features, now ready to test! 🌿

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding skeleton implementations for walk and run sub-commands to the jay CLI application, which is the primary focus of this changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/create-jay-skeleton-walk-and-run-cmds

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.

OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required.