Metadata-Version: 2.4
Name: ace-wrapper
Version: 0.1.1
Summary: Augment Context Engine (ACE) Wrapper
Project-URL: Documentation, https://github.com/ferstar/ace-wrapper#readme
Project-URL: Issues, https://github.com/ferstar/ace-wrapper/issues
Project-URL: Source, https://github.com/ferstar/ace-wrapper
Author-email: ferstar <zhangjianfei3@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: auggie-sdk>=0.1.12
Description-Content-Type: text/markdown

# ACE Wrapper

Semantic codebase retrieval using the Augment Context Engine through a small `ace` command.

Use it when the relevant identifiers are unknown and the query is about behavior, intent, architecture, or data flow. Treat results as candidate files, then read the returned files and confirm exact identifiers or call sites with literal search.

## Authentication

Before searching, you must authenticate using **one** of the following methods:

### Method 1: Standard Login (Official)

If you have an official Augment account:

```bash
auggie login
```

### Method 2: ACE Relay (Alternative)

If you use an `ace relay` middleman service, you can **skip** `auggie login` by manually configuring `~/.augment/session.json` with relay-specific settings:

- `accessToken`: Use the relay token (e.g., starts with `ace_`).
- `tenantURL`: Change to the relay endpoint (e.g., `https://acemcp.heroman.wtf/relay/`).
- `scopes`: Typically set to `["email"]`.

## Install

From this repository:

```bash
uv tool install .
```

From a published package:

```bash
uv tool install ace-wrapper
```

## Usage

```bash
timeout 60s ace "How is the authentication flow implemented?" -w /path/to/project/root
timeout 60s ace "Find where uploaded files are validated and stored" -w /path/to/project/root
timeout 60s ace "用户登录流程在哪里实现" -w /path/to/project/root
```

Use `--verbose` for debug logs:

```bash
timeout 60s ace "config loading" -w /path/to/project/root --verbose
```


## AI Agent Integration

To use `ace` effectively with AI coding agents, refer to [references/prompts.md](references/prompts.md) for recommended prompt instructions and best practices.

## Reliability Boundaries

- ACE is a candidate-file generator, not proof that a feature exists.
- Verify important conclusions by reading files and using exact search.
- Split unrelated workflows into separate queries.
- Use literal search for exact identifiers, error strings, routes, events, and config keys.

Detailed usage guidance and AI Agent prompt templates live in [references/](references/).

## Release

Publishing is handled by GitHub Actions. Create and push a version tag to build, publish to PyPI, and create a GitHub Release:

```bash
git tag v0.1.1
git push origin v0.1.1
```

The PyPI publish job uses Trusted Publishing, so the PyPI project must allow the `ferstar/ace-wrapper` repository and the `pypi` GitHub environment.
