# Developing argsbarg

Notes for maintainers of this repository. Also shipped under `node_modules/argsbarg/docs/` for fork maintainers.

## Prerequisites

- [Bun](https://bun.sh) ≥ 1.3
- [just](https://github.com/casey/just) — `just` lists recipes
- `gh` and `npm` logged in for release

## Day-to-day

```bash
just check    # typecheck + format
just test     # check + unit tests
just typegen  # regenerate index.d.ts
```

## Release

```bash
just release patch   # or minor | major
```

The release script bumps `package.json`, promotes `[Unreleased]` in `CHANGELOG.md`, commits, tags, pushes, creates a GitHub release, and publishes to npm. Run `just test` first (the `just release` recipe does).

Update `CHANGELOG.md` under `[Unreleased]` before releasing.

## Cursor test hook (optional)

Copy templates and the argsbarg repo root include `.cursor/hooks.json` plus `.cursor/hooks/run-tests-on-stop.ts`. On agent **stop** (completed turn), when git shows changes to `justfile` or `*.{ts,tsx,js,jsx}` (excluding `node_modules/`, `dist/`, `.cursor/`), the hook runs `just test`. Failures return a `followup_message` (up to **20** auto-retries via `loop_limit`). Requires [Cursor hooks](https://cursor.com/docs/hooks); not part of `AGENTS.md`. New projects get hooks via `argsbarg create`.

## Local consumer apps

Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_apps` variable, e.g. `~/dev/ss/sqsp-workspaces`):

| Recipe | When | Effect |
| --- | --- | --- |
| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; fix `.bin/argsbarg` symlink; refresh `AGENTS.md` from template (preserves app-specific sections below managed block) |
| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge `AGENTS.md`, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
| `just consumers-schemagen` | After `@sg` type changes in consumers | Runs `argsbarg schemagen` in each `consumer_apps` path (fails if missing) |

`consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.

**Argsbarg authoring rules** — `scripts/merge-agents-md.ts` copies the template from `examples/full-example-json/AGENTS.md` into each consumer. The framework baseline is placed at the top, and all app-specific sections live below `<!-- /argsbarg:managed -->` where they take precedence over framework defaults.

**Recommended in each consumer:** replace template placeholders under `## App conventions` with project-specific bullets. Commit `AGENTS.md`; merges refresh the managed section, not your app-specific sections.

## Upgrading consumer apps to 7.0

Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unreleased]`.

1. **Schemagen:** replace `export type configType|inputType|outputType` with `/** @sg */` immediately above `export interface` / `export type` (no blank line).
2. **Imports:** `configSchema` → `{AppConfig}Schema` (type name + `Schema`); same for leaf `inputSchema` / `outputSchema` imports (`StatusJsonOutputSchema`, etc.).
3. **Run** `argsbarg schemagen` (or `just schemagen`) after every type change.
4. **HTTP:** use `/api/...` REST routes only (`POST /tools/*` removed).
5. **Hooks:** remove manual `ctx.locals.requestId` in `beforeInvoke` — framework seeds it.
6. **Exports:** stop importing `loadLeafInputs` / `CliHttpResponseConfig` from `argsbarg` (use `ctx.inputs`, leaf `http.successContentType`).
7. **Agent instructions:** `just consumers-dev` merges `AGENTS.md` + `CLAUDE.md` (includes **Abstractions** needless-extraction rule).
8. **Verify:** `just test` and `just docgen` in each consumer repo.

**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure install`, which updates `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.

## npm package contents

`npm publish` does **not** honor `.gitignore`. Only paths listed in `package.json` `files` are included in the tarball (plus always-excluded defaults like `node_modules`).

When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).

Exclude `examples/full-example/node_modules/` and `examples/full-example-json/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).

## Copy templates

Both [`examples/full-example/`](../examples/full-example/) (CLI) and [`examples/full-example-json/`](../examples/full-example-json/) (schema-first) use `argsbarg: file:../..` in-repo; `just setup` fixes the Bun `.bin/argsbarg` symlink so `argsbarg schemagen` works. They must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:

```bash
just example-full-check
just test
```

See [docs/README.md](README.md) for the full documentation map.

## Advanced imports

Subpath exports (root barrel still re-exports everything):

```typescript
import { Cli, type CliProgram } from "argsbarg/cli";
import { generateOpenApi, httpServeHttp } from "argsbarg/http";
import { packMcpBundle } from "argsbarg/mcp"; // @experimental
import { shouldRunHeadless } from "argsbarg/headless";
import { runSchemagen } from "argsbarg/schemagen";
```

## Module boundaries

| Layer | Role |
| --- | --- |
| `schema.ts`, `parse.ts`, `context.ts` | Transport-agnostic CLI core |
| `http/` | HTTP tool server (`httpServer` capability) |
| `mcp/` | MCP stdio server and bundle (`mcpServer` capability) |
| `configure/artifacts/` | Agent artifact install/refresh (`configure` capability) |
| `docs/` | Built-in documentation generators |

Capabilities are declared on `CliProgram`; builtins wire them in [`src/builtins/`](../src/builtins/).

## Docs

See [README.md](README.md) for the documentation map. Framework authoring guide: [cli-program.md](cli-program.md).