# @hasna/configs

AI coding agent configuration manager — store, version, apply, and share all your AI coding configs. CLI + MCP + REST API + Dashboard.

[![npm](https://img.shields.io/npm/v/@hasna/configs)](https://www.npmjs.com/package/@hasna/configs)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## Install

```bash
npm install -g @hasna/configs
```

## CLI Usage

```bash
configs --help
configs list                    # compact, paged summary
configs list --verbose          # expanded metadata, still paged
configs list --json             # full machine-readable records
configs show <slug>             # full metadata + content
configs inspect <slug>          # alias for show
configs profile resolve
configs profile apply --auto
```

Collection commands are compact by default to keep agent terminals and context
small. Human output is capped at 20 rows unless you pass `--limit`; use
`--cursor` to continue from the next page. Detail is explicit:

- `--verbose` expands list rows with descriptions, tags, and paths.
- `--json` preserves full machine-readable records for automation.
- `show`/`inspect` and `snapshot show` print full config or snapshot content.

## MCP Server

```bash
configs-mcp
```

Agent-facing MCP tools follow the same gradual disclosure model. `list_configs`
and `list_profiles` return paged compact envelopes by default and accept
`limit`, `cursor`, and `verbose`. `apply_config` and `apply_profile` omit
`previous_content` and `new_content` unless `verbose: true` is passed. Use
`get_config` when full config content is needed.

## HTTP mode

```bash
configs-mcp --http               # http://127.0.0.1:8807/mcp
MCP_HTTP=1 configs-mcp
```

Health: `GET http://127.0.0.1:8807/health`. MCP is also mounted on `configs-serve` at `/mcp`.

## REST API

```bash
configs-serve
```

## Storage Sync

This package supports optional remote storage sync through a package-local Postgres connection:

```bash
export HASNA_CONFIGS_DATABASE_URL=postgres://...
configs storage status
configs storage push
configs storage pull
configs storage sync
```

The MCP server also exposes `storage_status`, `storage_push`, `storage_pull`, and `storage_sync`.

## Data Directory

Data is stored in `~/.hasna/configs/`.

## Session Instruction Rendering

`configs session plan` and `configs session apply` render OpenIdentities and
OpenConfigs instruction sources into provider-native files for Claude, Codex,
Cursor, OpenCode, and Codewith.

```bash
configs session plan \
  --tool codewith \
  --profile account999 \
  --identity-export ./instructions.json \
  --source project:repo-rules=./CODEWITH.md \
  --json

configs session apply \
  --tool codex \
  --profile account999 \
  --identity-export ./instructions.json
```

Accepted source layers are `global`, `provider`/`tool`, `account`,
`identity`/`agent`, `project`, and `local`. Empty renders fail closed unless
`--allow-empty-sources` is passed. Apply writes generated manifests with file
hashes, checks previous manifests for drift, refuses unmanaged file conflicts
unless `--force` is passed, removes stale managed mirrors only when safe, and
writes local snapshots before mutating managed files.

## Machine-aware Profiles

`configs init` now seeds two platform profiles:

- `linux-arm64` for `linux-node-a` / `linux-node-b`
- `macos-arm64` for `macos-node-a` / `macos-node-b`

These profiles resolve machine variables like `{{WORKSPACE_ROOT}}`, `{{BUN_BIN_DIR}}`, `{{BUN_PATH}}`, and `{{PATH_PREFIX}}`, so synced configs can be portable across Linux and macOS arm64 machines.

They also include project dashboard variables used by agent-managed project
workflows:

- `{{PROJECT_DASHBOARD_DIR}}` -> `.hasna/project`
- `{{PROJECT_DASHBOARD_RENDER_MANIFEST}}` -> `.hasna/project/dashboard/render.json`
- `{{PROJECT_DASHBOARD_SNAPSHOTS_DIR}}` -> `.hasna/project/dashboard/snapshots`
- `{{PROJECT_CHANNEL_PREFIX}}` -> `iproj-`

`configs init` and `bun run seed` seed the
`agent-managed-project-dashboard-standard` reference. It documents the standard
`.hasna/project` layout, `projects dashboard *` commands, provider panel
commands, `#iproj-*` channel naming, durable todos/goal workflow, and the rule
that dashboards must show ids/statuses/evidence refs instead of raw private
documents or secrets.

## License

Apache-2.0 -- see [LICENSE](LICENSE)