<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# 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.

```sh
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](ax.md) 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.

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

### `DevCommandFinding`

```ts
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`.

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

Example:

```ts
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`.

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

Example:

```ts
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`

```ts
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.

```ts
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.

```ts
function sourceCheckoutTexts(value: unknown): string[]
```