command-scout

简体中文

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

The adapter (dsh-command-scout/adapter) is a Cordis plugin. The harness
loader validates and defaults the config through the exported Schemastery
schema, waits for the declared services, calls apply(ctx, config), and
calls the returned disposer on unload or config hot-reload. The package
main (dsh-command-scout) deliberately stays free of harness imports and
exposes only the embedding API.

Export	Kind	Purpose
name	string	command-scout
inject	string[]	['tools'] — activation waits for the service
Config	schema	validated configuration (below)
apply	function	scans the root, registers tools, returns a disposer

Events

• tools/change is emitted by the harness registry for every register and
  unregister, so UIs observing the registry refresh automatically.
• The plugin itself emits no events; it only registers tools on activation.

Re-scanning

Discovery happens once per activation. Editing a Makefile or package.json
does not re-trigger a scan; reload the plugin (config hot-reload or a new
session) to refresh the tool set.

Configuration

Configuration is supplied through the plugin row's config (in
cordis.patch.yml or the profile patch). All fields have defaults; the
example below shows every option:

- insert:
    - id: command-scout
      name: dsh-command-scout/adapter
      config:
        root: '.'                    # directory scanned, relative to process cwd
        collectors:
          makefile:
            enabled: true
          scripts:
            enabled: true
            runner: auto             # auto | npm | yarn | pnpm | bun
            lockfilePriority:        # probed in order by runner: auto
              - pnpm-lock.yaml
              - yarn.lock
              - bun.lockb
              - bun.lock
              - package-lock.json
          justfile:
            enabled: true
          deno:
            enabled: true
        naming:
          style: scoped              # scoped | flat
        execution:
          timeoutMs: 120000          # per-command hard budget

Runner detection (scripts)

runner: auto resolves in this order:

1. the packageManager field of package.json ("[email protected]" → pnpm),
2. the first lockfile present, in lockfilePriority order,
3. npm as fallback.

The resolved runner also names the tools (pnpm_dev vs npm_dev), so two
projects using different runners never collide.

Naming

• scoped (default): make_build, pnpm_dev, just_lint, deno_serve.
• flat: bare names (build, dev); on collision the first recipe keeps
  the bare name and later ones get numeric suffixes (dev_2).

Tool names only ever contain lowercase letters, digits and underscores
(names with no such characters at all, e.g. CJK-only script names, get a
deterministic task_<hash> form), and the reserved harness name run_code
is never produced.

Tools the agent gets

One tool per command, named as above. Example for a Makefile target:

make_build — Project makefile command "build" (from Makefile).
Compile the release bundle
Run: make build
Acceptable variables: VERSION, CC (pass as VAR=value via "args")
Prerequisites: clean
Additional shell arguments can be appended through the "args" parameter.

Every tool accepts one optional parameter, args: a string appended to the
command line verbatim. It is the single extension point for flags and
overrides (--port 8080, VERSION=2.0.0).

Execution semantics:

• runs through the platform shell with the scan root as working directory,
• hard timeout per execution.timeoutMs; timeouts and harness cancellation
  kill the whole process tree (not just the shell wrapper), so build tools
  cannot leak as orphan processes,
• stdout/stderr captured and truncated at 1 MiB per stream,
• returns { command, ok, exitCode, stdout, stderr, killed, durationMs }.

Security note: commands run as the harness user with the project's own
definitions, and args is appended verbatim — both are shell code by
design. The harness approval policy (tools/pre-execute) still applies to
every call; run under a workspace-write sandbox as usual.

CLI

The standalone CLI needs no harness:

# Inspect a project's commands as a table
command-scout scan --root path/to/project

# Machine-readable output
command-scout scan --root path/to/project --format json

# Generate a COMMANDS.md reference document
command-scout docs --root path/to/project [--output COMMANDS.md]

Example table output:

source    name              command           description
makefile  build             make build        Compile the release bundle
makefile  clean             make clean        Remove build artifacts
scripts   dev               pnpm run dev      vite
scripts   test              pnpm run test     vitest run

Programming interface

import { discover, runCommand } from 'dsh-command-scout'

const { book, diagnostics, detectedFiles } = discover('.')
const toolNames = book.assignToolNames('scoped')
for (const recipe of book.entries()) {
  console.log(toolNames.get(recipe.id), recipe.command)
}

const result = await runCommand('make build', { cwd: '.', timeoutMs: 30_000 })
console.log(result.stdout)

Exports: discover, RecipeBook, createRecipe, runCommand,
renderTable / renderJson / renderMarkdown, normalizeConfig,
DEFAULT_CONFIG. (The plugin contract name / Config / apply /
inject is exported from the dsh-command-scout/adapter subpath.)

Development

node --test          # run the test suite (built-in node:test, no deps)
node bin/command-scout.mjs scan --root test/fixtures/mixed   # smoke test

Test fixtures live in test/fixtures/ (mixed project, per-runner lockfile
projects, empty project).

Project layout

bin/command-scout.mjs      CLI launcher
src/config.js              defaults and config normalization
src/recipe.js              the Recipe domain object
src/recipe-book.js         aggregation, dedupe, naming, ordering
src/discover.js            scan orchestration (the Scout)
src/execute.js             shell execution with capture and timeouts
src/render.js              table / JSON / Markdown rendering
src/cli.js                 CLI implementation
src/dsh-adapter.js         the Cordis plugin surface
src/collectors/            one module per build system
test/                      node:test suite + fixtures

License

MIT