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

# ax-bundle

A diagnostics bundle: one JSON file a doctor writes for an agent to read or attach, the agent's version of a desktop app's "get logs" menu item. Every string in it is redacted first (ax-redact), and the whole text is checked for anything shaped like a token, an id or an address before a byte is written: a leak refuses the bundle.

```sh
npx shadcn@latest add ourostack/ouro-ui/ax-bundle#v1.3.344
```

It installs `lib/ouro/ax/bundle.ts`, with `ax-redact`. Its tests are `ax-bundle-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

### `BundleOptions`

`home` becomes `~`, and `rules` are the app's own shapes (ax-redact).

```ts
type BundleOptions = RedactOptions;
```

### `BundleParts`

A diagnostics bundle: one JSON file a doctor writes for an agent to read or attach, the agent's version of a desktop app's "get logs" menu item. Every string in it is redacted first (ax-redact), and the whole text is checked for anything shaped like a token, an id or an address before a byte is written: a leak refuses the bundle.

```ts
interface BundleParts {
  facts: Record<string, unknown>;
  logs: Record<string, readonly string[]>;
}
```

Example:

```ts
const file = writeBundle(
  { facts: { tool: "notes doctor", verdict: report.verdict, rows: report.rows }, logs: { service: tailLines(logFile, 300) } },
  { dir: logsDir, prefix: "notes-doctor", at: Date.now(), home: os.homedir() },
);
```

### `bundleText`

The bundle's text, redacted. Throws, naming the shapes, when anything shaped like a secret is left, such as an email address used as a key.

```ts
function bundleText(parts: BundleParts, opts?: RedactOptions): string
```

Example:

```ts
const text = bundleText({ facts: { verdict: "failed" }, logs: { service: ["signed in as jordan@contoso.com"] } });
// logs.service is ["signed in as [email]"]
```

### `tailLines`

The last `n` lines of a file, reading at most `maxBytes` from its end, without blank lines; none when it isn't there.

```ts
function tailLines(file: string, n: number, maxBytes?: number): string[]
```

Example:

```ts
tailLines(`${logsDir}/service.log`, 300); // the service log's last 300 lines
```

### `writeBundle`

Writes the bundle into `dir` as `<prefix>-<time>.json`, readable by this user only, never over an existing file, and returns its path for the tool to print.

```ts
function writeBundle(parts: BundleParts, { dir, prefix, at, ...opts }: RedactOptions & { dir: string; prefix: string; at: number; }): string
```

Example:

```ts
const file = writeBundle(parts, { dir: logsDir, prefix: "notes-doctor", at: Date.now(), home: os.homedir() });
stdout.write(`Bundle (redacted), for an agent to read or attach:\n  ${file}\n`);
```
