Metadata-Version: 2.4
Name: unlegacy-cli
Version: 0.6.1
Summary: Unlegacy setup CLI for external coding agents
Author: Unlegacy
Project-URL: Homepage, https://app.unlegacy.ai
Project-URL: Repository, https://github.com/unlegacy-ai/unlegacy-core
Keywords: unlegacy,mcp,cli,coding-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# unlegacy-cli

Installable CLI for connecting local coding agents to Unlegacy MCP.

Unlegacy generates repository documentation, API references, knowledge graph
data, and Vault investigation docs in the platform. This CLI configures
external coding agents so they can consume that MCP surface.

## Install

Published package:

```sh
uv tool install unlegacy-cli
```

or:

```sh
pip install unlegacy-cli
```

After install, the command is saved on the user's machine as:

```sh
unlegacy --help
```

From a checkout:

```sh
pip install .
```

or:

```sh
uv tool install .
```

One-shot setup without preinstalling:

```sh
uv tool run --from unlegacy-cli unlegacy setup --token mcp_live_xxx --endpoint https://app.unlegacy.ai/ai/mcp
```

## Distribution

Build the package artifacts:

```sh
uv build
```

The build creates `dist/unlegacy_cli-<version>.tar.gz` and
`dist/unlegacy_cli-<version>-py3-none-any.whl`. Publish those artifacts to the
Python package index used by Unlegacy clients.

## Setup

```sh
unlegacy setup
```

The flow:

1. Shows the Unlegacy logo.
2. Prompts for the MCP token from the Unlegacy frontend.
3. Prompts for the MCP endpoint. Press Enter to use the local app endpoint: `http://localhost:5173/ai/mcp`.
4. Lets the user select supported clients.
5. Writes or merges MCP config.
6. Installs the packaged Unlegacy and Forge skill bundle.
7. Runs `unlegacy doctor`.

Non-interactive usage:

```sh
UNLEGACY_MCP_TOKEN=mcp_live_xxx \
unlegacy setup --client claude-code --client codex --endpoint https://app.unlegacy.ai/ai/mcp
```

For local development:

```sh
UNLEGACY_MCP_TOKEN=mcp_live_xxx \
unlegacy setup --client claude-code --client codex --endpoint http://localhost:5173/ai/mcp
```

Supported client values:

- `claude-code`
- `codex`
- `cursor`
- `vscode-copilot`
- `opencode`
- `all`

## Commands

```sh
unlegacy setup
unlegacy doctor
unlegacy install-skills --client codex
unlegacy status
```

## Bundled skills

`unlegacy setup` and `unlegacy install-skills` install one versioned skill bundle:

- `unlegacy` - repository and Vault knowledge retrieval
- `using-forge` - Forge modernization routing and design readiness
- `preparing-forge-build` - complete artifact-only ledger and workspace gate
- `executing-forge-build` - lifecycle-first, bounded obligation slices and checkpoints
- `developing-forge-obligations` - behavior-preserving RED-GREEN-REFACTOR
- `debugging-forge-build` - root-cause-first failure investigation
- `reviewing-forge-slices` - separate specification and quality reviews
- `verifying-forge-build` - evidence and obligation reconciliation
- `finishing-forge-build` - assembled replacement and cutover verification
- `using-forge-subagents` - preferred fresh-context execution when supported

The bundle is self-contained; installing the external Superpowers plugin is not
required. Subagents are strongly encouraged on clients that support them, while
the sequential workflow enforces the same gates on every supported client.
The methodology is inspired by `obra/superpowers`; attribution is packaged in
`assets/skills/NOTICE.md`.

Forge builds maintain committed coordination state under `.forge/`, including a
locked manifest, build state, obligation evidence, decisions, and slice reviews.
This state is builder-owned local evidence, not independent Forge certification.
Preparation cannot edit target files: an integrity-checked validator bundled with
the skill reconciles fetched payloads against the authoritative manifest index
and requires a stable digest, all-pending state, safe path boundaries, and an
artifact-only Git diff from the captured preparation base before execution begins.

The CLI is not used during modernization. Its responsibility ends after it
installs/updates the skills, configures MCP, and diagnoses bundle integrity. The
coding agent performs modernization with the installed skills, Unlegacy MCP, Git,
and the target repository's native toolchain.

`unlegacy doctor` validates every required skill and supporting executable
against the packaged bundle and reports missing, stale, or modified files per
client. Reinstall the bundle with `unlegacy install-skills` when doctor reports
an integrity issue.

## Vault-aware MCP tools

The packaged `unlegacy` skill now teaches agents how to use both repo-scoped
and Vault-scoped tools.

Repo-scoped tools are still the right starting point for single-repository work:

- `list_repos`
- `repo_brief`
- `list_docs`
- `search_docs`
- `doc_outline`
- `read_doc`
- `repo_info`
- `search`
- `symbol_context`
- `impact`
- `cypher`
- `get_code`

Vault-scoped tools are the right starting point for product, migration, or
system questions that cross repository boundaries:

- `list_vaults`
- `vault_brief`
- `list_vault_repos`
- `list_vault_docs`
- `read_vault_doc`
- `search_vault_docs`
- `search_repo_kg`
- `list_needs_input`

Typical Vault flow for an installed coding agent:

1. Call `list_vaults` unless the user gave an exact Vault id.
2. Call `vault_brief(vault_id)` to load the Vault summary, member repos,
   generated docs, missing evidence, and Needs Input.
3. Use `list_vault_docs` and `read_vault_doc` before drilling into source.
4. Use `list_vault_repos` to keep follow-up repo reads inside the Vault.
5. Use `search_repo_kg` for code-graph verification within a Vault member repo.
6. Use `list_needs_input` before presenting cross-repo conclusions that depend
   on missing docs, API refs, or KG evidence.

`unlegacy doctor` also validates that the connected MCP endpoint exposes the
required repo and Vault tools.

## Development

```sh
uv run pytest
```
