简体中文

command-scout

Discover the build commands a project already declares — Makefile targets, package.json scripts (npm / yarn / pnpm / bun), just recipes, deno tasks — and expose them to the agent as ready-to-run tools. Instead of guessing how to build, test or lint a project, the agent reads exactly what the project itself defines.

• Scans at startup: on plugin activation the workspace root is inspected once and every command found becomes a registered tool.
• Multiple build systems: Makefile, package.json scripts with automatic runner detection, justfile, deno.json / deno.jsonc tasks.
• Rich metadata: descriptions (## comments in Makefiles, trailing text in justfiles), prerequisite lists, referenced variables, argument hints.
• Safe naming: tool names are deterministic (make_build, pnpm_dev, just_lint) and collisions are resolved with numeric suffixes.
• Self-contained: zero runtime dependencies, plain Node.js ESM, works with or without a harness — a CLI (scan / docs) ships in the box.

How it works

project root
   │  Makefile  package.json  justfile  deno.json(c)
   ▼
collectors ──► RecipeBook (dedupe, order, resolve names)
   │
   ├─► dsh adapter: registers one tool per recipe (ctx.tools.register)
   └─► CLI:        table / JSON / generated COMMANDS.md

Each collector parses one file format into recipes. A recipe carries the command line to run, a description, its source file, prerequisites, and the variables it accepts. The adapter turns recipes into agent tools whose execute runs the command through the platform shell and returns stdout, stderr and the exit code.

Requirements

• Node.js >= 18.17
• For the dsh integration: a working DeepSeek Harness install with @deepseek-ai/dsh-base (provides the tools service), and pnpm for dsh plugin management.

Installation

Installing in DSH

dsh plugin --profile demo add github:JohnXu22786/command-scout

As a dsh bundle (recommended)

A bundle is an npm package that contributes a configuration layer. From the directory containing this checkout:

dsh plugin --profile demo add ./path/to/command-scout

This initializes the demo profile (with @deepseek-ai/dsh-base as its first bundle), links the checkout, and appends dsh-command-scout to the profile's bundle list because package.json declares dsh.bundle. Verify and boot:

dsh --profile demo --dump-config   # shows the "# == dsh-command-scout" layer
dsh --profile demo

The contributed patch layer (cordis.patch.yml) inserts one plugin row mounting the adapter entry (a package subpath, resolved through the package's exports map):

- insert:
    - id: command-scout
      name: dsh-command-scout/adapter

As a patch overlay (no packaging)

Point the plugin row directly at the adapter source. Create an overlay file command-scout-patch.yml:

- insert:
    - id: command-scout
      name: '<abs-path>/src/dsh-adapter.js'

and pass it to the harness:

dsh --patch ./command-scout-patch.yml

Standalone (no harness)

node bin/command-scout.mjs scan --root /path/to/project
npm install -g .     # provides the `command-scout` command

Plugin contract

…