ax-dev-commands

A message for an agent or a person names only what the installed tool runs: never a developer command, a repository path or a step that only works in a source checkout. An agent passes a next step on to the person, who has the installed tool and no checkout, so a step such as npm run writes -- on fails for them and leaves both stuck. A step that only a source checkout shows is marked sourceCheckout: true, and only then is it exempt.

Developer commands: npm, pnpm, yarn and bun scripts and installs (a global install is fine), npx of a dev tool or a file, node, tsx or another interpreter given a file in the repository, git, make, cargo and the other build tools, and a script run by its path. Repository paths: src/, scripts/, registry/, packages/, apps/, .github/, node_modules/, and in a command root files such as package.json. A web address is never a path.

npx shadcn@latest add ourostack/ouro-ui/ax-dev-commands#v1.3.10

It installs lib/ouro/ax/dev-commands.ts. Its tests are ax-dev-commands-tests. Every item runs on Node 22.18 or later as it is copied: the files import each other as ./<file>.ts. The Ouro AX guide shows how they fit together.

Exports

DevCommand

A message for an agent or a person names only what the installed tool runs: never a developer command, a repository path or a step that only works in a source checkout. An agent passes a next step on to the person, who has the installed tool and no checkout, so a step such as npm run writes -- on fails for them and leaves both stuck. A step that only a source checkout shows is marked sourceCheckout: true, and only then is it exempt.

Developer commands: npm, pnpm, yarn and bun scripts and installs (a global install is fine), npx of a dev tool or a file, node, tsx or another interpreter given a file in the repository, git, make, cargo and the other build tools, and a script run by its path. Repository paths: src/, scripts/, registry/, packages/, apps/, .github/, node_modules/, and in a command root files such as package.json. A web address is never a path.

interface DevCommand {
  match: string;
  kind: "command" | "path";
}

DevCommandFinding

interface DevCommandFinding extends DevCommand {
  where: string;
  text: string;
}

devCommandIn

The first developer command or repository path in a message, or null. Pass asCommand for a field that holds one command, such as a next step's command.

function devCommandIn(text: string, asCommand?: boolean): DevCommand | null

Example:

devCommandIn("Writes are off. Run npm run writes -- on, then try again.");
// { match: "npm run writes -- on", kind: "command" }
devCommandIn("notes sync", true); // null

devCommandsIn

Every developer command and repository path in a value: a message, a help --json, an outcome, an error or a checks report. command and fix strings are read as commands, everything else but a step's why as prose; an object marked sourceCheckout: true is skipped with all it holds. With messagesOnly, only what is under MESSAGE_KEYS.

function devCommandsIn(value: unknown, options?: DevCommandsOptions): DevCommandFinding[]

Example:

devCommandsIn({ next: [{ command: "npm run writes -- on", why: "Turn writes on" }] });
// [{ match: "npm run writes -- on", kind: "command", where: "next[0].command", text: "npm run writes -- on" }]

DevCommandsOptions

interface DevCommandsOptions {
  messagesOnly?: boolean;
}

MESSAGE_KEYS

The fields of an answer that speak to the agent or the person: next steps, a human's resume step, an error and a fix.

const MESSAGE_KEYS: ReadonlySet<string>

sourceCheckoutTexts

The strings a value marks sourceCheckout: true, so a checker can let the same words pass in the text output.

function sourceCheckoutTexts(value: unknown): string[]