Metadata-Version: 2.4
Name: new-feature
Version: 0.6.4
Summary: Create isolated feature worktrees with allocated runtime environments.
Project-URL: Homepage, https://github.com/crypdick/new-feature
Project-URL: Issues, https://github.com/crypdick/new-feature/issues
Project-URL: Source, https://github.com/crypdick/new-feature
Author-email: Ricardo Decal <public@ricardodecal.com>
Keywords: automation,cli,codex,git,worktree
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.13
Requires-Dist: beartype>=0.22.9
Requires-Dist: filelock>=3.29.7
Requires-Dist: tomli-w>=1.2.0
Description-Content-Type: text/markdown

# new-feature

`new-feature` aims to eliminate friction for creating new features. In a single command, it creates isolated git worktrees, allocates conflict-free runtime values, runs project-defined setup and teardown commands (such as creating and deleting a feature database), and launches the configured coding agent in the new worktree.

## Install

```bash
uv tool install new-feature
new-feature setup
```

`new-feature setup` launches the configured coding agent (Codex by default) in the
current repository. The agent inspects the project, proposes a repository-specific
configuration, asks about unresolved choices such as the optional Codex hook, and waits
for approval before editing. Run it again to review and improve an existing integration.

## Releases

Changing `[project].version` in `pyproject.toml` and merging that change to `main`
publishes the distributions to PyPI, tags the merged commit as `v<VERSION>`, and creates
a GitHub Release. Keep the project version in `uv.lock` synchronized with `pyproject.toml`.
The release workflow can also be run manually to recover from a partial release.

## Usage

```bash
# Ask an agent to configure or improve new-feature for this repository.
new-feature setup
# Create a feature worktree and launch the configured agent.
new-feature my-feature
# Create a feature worktree without launching another agent.
new-feature my-feature --no-agent
# Merges the worktree into the main branch
new-feature merge my-feature
# Run configured teardown and remove the feature worktree.
new-feature teardown my-feature
# Teardown a worktree even if it has uncommitted work.
new-feature teardown my-feature --force
# Inspect managed features and diagnose stale state.
new-feature list
new-feature doctor
new-feature doctor --repair
```

## Codex hook

Install the Codex hook in the current repository:

```bash
new-feature install-codex-hook
```

This writes `.codex/hooks.json`; Codex loads the guard only for this trusted repository.

## Project Config

Add config to the target repo's `new-feature.toml`:

```toml
target_branch = "main"
agent = ["codex"]
push = false
setup = ["uv sync"]
pre_merge = ["uv run pytest"]
post_merge = ["uv run pytest"]
teardown = []

[env]
WEB_PORT = { allocate = "port", min = 3000, max = 3999 }
API_PORT = { allocate = "port", min = 4000, max = 4999 }
DATABASE_NAME = { allocate = "name", prefix = "myapp", max_length = 63 }
CACHE_DIR = { allocate = "path", base = ".new-feature/cache" }
```

All settings remain optional. If both `new-feature.toml` and `pyproject.toml` exist,
`new-feature.toml` takes precedence. For projects that prefer to keep tool configuration in
`pyproject.toml`, place the same settings under `[tool.new-feature]` and use
`[tool.new-feature.env]` instead of `[env]`.

`agent` is the command and arguments used to launch the coding agent. `new-feature` appends its
generated feature prompt as the final argument, so agents that require a prompt flag can be configured
directly:

```toml
agent = ["copilot", "--prompt"]
```

`setup` runs after worktree creation; `teardown` runs before worktree removal.

Supported env entries:

- `{ value = "literal" }`
- `{ allocate = "port", min = 3000, max = 3999 }`
- `{ allocate = "integer", min = 1, max = 15 }`
- `{ allocate = "name", prefix = "myapp", max_length = 63 }`
- `{ allocate = "slug", prefix = "myapp" }`
- `{ allocate = "path", base = ".new-feature/cache" }`

## Lifecycle

`new-feature my-feature` creates branch `my-feature` and worktree `.worktrees/my-feature`, reserves env values in `.new-feature/manifest.toml`, runs setup, and launches the configured agent in the worktree. It automatically adds `.new-feature/` and `.worktrees/` to `.gitignore`. If setup fails, it runs a forced teardown so the partial worktree, branch, and manifest entry do not linger.

`new-feature list` shows each managed feature and its current Git/worktree state. `new-feature doctor` reports stale manifest entries, dirty worktrees, unmerged branches, and configuration drift. `doctor --repair` removes only manifest entries whose worktree and branch are both already gone.

`new-feature merge my-feature` runs pre-merge checks in the feature worktree, starts a no-commit merge into the target branch, runs post-merge checks on the merged target checkout, commits the merge only if those checks pass, and pushes only when `push = true`.

`new-feature teardown my-feature` runs the configured teardown commands before removing the worktree, deleting the branch, and removing the manifest entry. If the worktree has uncommitted changes or the branch has commits that are not in the target branch, pass `--force` to abandon them deliberately.
