new-feature 0.1.0__tar.gz

new_feature-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tool-generated local artifacts
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/

new_feature-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: new-feature
+Version: 0.1.0
+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` creates isolated git worktree environments for feature work, allocates conflict-free runtime values, and launches an interactive Codex session in the new worktree.
+
+## Usage
+
+```bash
+uvx new-feature my-feature
+uvx new-feature merge-feature my-feature
+uvx new-feature teardown my-feature
+uvx new-feature teardown my-feature --force
+```
+
+## Project Config
+
+Add config to the target repo's `pyproject.toml`:
+
+```toml
+[tool.new-feature]
+target_branch = "main"
+branch_prefix = "feature/"
+agent = "codex"
+push = false
+setup = ["uv sync"]
+pre_merge = ["uv run pytest"]
+post_merge = ["uv run pytest"]
+teardown = []
+
+[tool.new-feature.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" }
+```
+
+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 `.worktrees/my-feature`, reserves env values in `.new-feature/manifest.toml`, runs setup, and launches interactive Codex in the worktree. It automatically adds `.new-feature/` and `.worktrees/` to `.gitignore`.
+
+`new-feature merge-feature 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 teardown commands, removes the worktree, deletes the branch, and removes the manifest entry. If the feature has not gone through `merge-feature`, pass `--force` to abandon it deliberately.
+
+## Generated State
+
+The generated manifest is a single ignored TOML file in the main checkout:
+
+```text
+.new-feature/manifest.toml
+.new-feature/manifest.lock
+```
+
+The manifest stores all active feature env allocations, so ports, names, paths, and namespaces can be reserved without scanning generated worktrees.
+
+## Publishing
+
+See [docs/PUBLISHING.md](docs/PUBLISHING.md) for PyPI release setup and verification.

new_feature-0.1.0/README.md

@@ -0,0 +1,66 @@
+# new-feature
+
+`new-feature` creates isolated git worktree environments for feature work, allocates conflict-free runtime values, and launches an interactive Codex session in the new worktree.
+
+## Usage
+
+```bash
+uvx new-feature my-feature
+uvx new-feature merge-feature my-feature
+uvx new-feature teardown my-feature
+uvx new-feature teardown my-feature --force
+```
+
+## Project Config
+
+Add config to the target repo's `pyproject.toml`:
+
+```toml
+[tool.new-feature]
+target_branch = "main"
+branch_prefix = "feature/"
+agent = "codex"
+push = false
+setup = ["uv sync"]
+pre_merge = ["uv run pytest"]
+post_merge = ["uv run pytest"]
+teardown = []
+
+[tool.new-feature.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" }
+```
+
+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 `.worktrees/my-feature`, reserves env values in `.new-feature/manifest.toml`, runs setup, and launches interactive Codex in the worktree. It automatically adds `.new-feature/` and `.worktrees/` to `.gitignore`.
+
+`new-feature merge-feature 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 teardown commands, removes the worktree, deletes the branch, and removes the manifest entry. If the feature has not gone through `merge-feature`, pass `--force` to abandon it deliberately.
+
+## Generated State
+
+The generated manifest is a single ignored TOML file in the main checkout:
+
+```text
+.new-feature/manifest.toml
+.new-feature/manifest.lock
+```
+
+The manifest stores all active feature env allocations, so ports, names, paths, and namespaces can be reserved without scanning generated worktrees.
+
+## Publishing
+
+See [docs/PUBLISHING.md](docs/PUBLISHING.md) for PyPI release setup and verification.

new_feature-0.1.0/pyproject.toml

@@ -0,0 +1,242 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "new-feature"
+version = "0.1.0"
+description = "Create isolated feature worktrees with allocated runtime environments."
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [
+    { name = "Ricardo Decal", email = "public@ricardodecal.com" },
+]
+keywords = ["codex", "git", "worktree", "automation", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "beartype>=0.22.9",
+    "filelock>=3.29.7",
+    "tomli-w>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/crypdick/new-feature"
+Issues = "https://github.com/crypdick/new-feature/issues"
+Source = "https://github.com/crypdick/new-feature"
+
+[project.scripts]
+new-feature = "new_feature.app:main"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/pyproject.toml",
+    "/README.md",
+    "/src/new_feature",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/new_feature"]
+
+[dependency-groups]
+dev = [
+    "coverage>=7.15.0",
+    "detect-secrets>=1.5.0",
+    "flynt>=1.0.6",
+    "mypy>=2.2.0",
+    "pre-commit>=4.6.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "pyupgrade>=3.21.2",
+    "ruff>=0.15.21",
+    "vulture>=2.16",
+]
+
+[tool.ruff]
+line-length = 110
+preview = true
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ANN001",
+    "ANN002",
+    "ANN003",
+    "ANN201",
+    "ANN202",
+    "ANN204",
+    "ANN205",
+    "ANN206",
+    "ANN401",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "COM818",
+    "C90",
+    "D402",
+    "D414",
+    "D418",
+    "D419",
+    "DOC102",
+    "DOC202",
+    "DOC403",
+    "DTZ",
+    "E",
+    "ERA",
+    "EXE",
+    "F",
+    "FA",
+    "FBT",
+    "FURB101",
+    "FURB103",
+    "FURB122",
+    "FURB129",
+    "FURB132",
+    "FURB157",
+    "FURB161",
+    "FURB162",
+    "FURB168",
+    "FURB169",
+    "FURB171",
+    "FURB177",
+    "FURB181",
+    "FURB188",
+    "G",
+    "I",
+    "INP",
+    "ISC004",
+    "LOG",
+    "N",
+    "PERF",
+    "PGH",
+    "PIE",
+    "PLC",
+    "PLE",
+    "PLR0124",
+    "PLR0133",
+    "PLR0206",
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR0915",
+    "PLR1702",
+    "PLR1704",
+    "PLR1711",
+    "PLR1714",
+    "PLR1716",
+    "PLR1722",
+    "PLR1733",
+    "PLR1736",
+    "PLR5501",
+    "PLW",
+    "PT",
+    "PTH",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "SLF",
+    "SLOT",
+    "T10",
+    "T20",
+    "TC",
+    "TID",
+    "TRY004",
+    "TRY201",
+    "TRY203",
+    "TRY300",
+    "TRY400",
+    "TRY401",
+    "UP",
+    "W",
+    "YTT",
+]
+ignore = [
+    "E501",
+    "TRY003",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.per-file-ignores]
+"src/new_feature/__init__.py" = ["RUF067"]
+"tests/**/*.py" = ["ALL"]
+"scripts/**/*.py" = ["C901", "PLR0912", "PLR0915", "S603", "S607", "T20"]
+"src/new_feature/agent.py" = ["S404", "S603", "TC003"]
+"src/new_feature/allocator.py" = ["PLR0913", "TC001"]
+"src/new_feature/cli.py" = ["T201"]
+"src/new_feature/commands.py" = ["S404", "S602", "S603", "T201", "TC003"]
+"src/new_feature/config.py" = ["TC003"]
+"src/new_feature/git.py" = ["S404", "S603", "S607"]
+"src/new_feature/gitignore.py" = ["TC003"]
+"src/new_feature/manifest.py" = ["TC003"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+show_error_codes = true
+pretty = true
+disable_error_code = ["no-untyped-call", "no-untyped-def"]
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+check_untyped_defs = false
+ignore_errors = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--no-header -n auto -q --durations=5 --durations-min=1.0 --cov=new_feature --cov-report=term-missing --cov-report=html --cov-fail-under=100 --failed-first"
+timeout = 20
+timeout_method = "thread"
+
+[tool.coverage.run]
+branch = true
+source = ["new_feature"]
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+    "*/__pycache__/*",
+    "*/conftest.py",
+]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+    "@abc.abstractmethod",
+]
+
+[tool.vulture]
+min_confidence = 80
+exclude = [".venv/"]
+paths = ["src", "tests"]

new_feature-0.1.0/src/new_feature/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import warnings
+
+from beartype import BeartypeConf
+from beartype.claw import beartype_this_package
+from beartype.roar import BeartypeClawDecorWarning
+
+warnings.filterwarnings("ignore", category=BeartypeClawDecorWarning)
+
+beartype_this_package(
+    conf=BeartypeConf(
+        claw_is_pep526=False,
+        warning_cls_on_decorator_exception=BeartypeClawDecorWarning,
+    ),
+)

new_feature-0.1.0/src/new_feature/__main__.py

@@ -0,0 +1,3 @@
+from new_feature.cli import main
+
+raise SystemExit(main())

new_feature-0.1.0/src/new_feature/agent.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def build_initial_prompt(name: str) -> str:
+    return (
+        f"Interview Ricardo to turn `{name}` into a concise PRD for this repository. "
+        "Inspect the local repo context first. If the feature name is descriptive enough "
+        "and the repo context makes the likely implementation clear, summarize your "
+        "inferred plan briefly and ask whether to get right to work."
+    )
+
+
+def launch_interactive_agent(agent: str, worktree: Path, env: dict[str, str], prompt: str) -> int:
+    return subprocess.call([agent, prompt], cwd=worktree, env={**os.environ, **env})

new_feature-0.1.0/src/new_feature/allocator.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import hashlib
+import re
+import socket
+from pathlib import Path
+
+from new_feature.config import EnvSpec, ProjectConfig
+from new_feature.errors import NewFeatureError
+from new_feature.manifest import Manifest
+
+
+def allocate_env(
+    *,
+    config: ProjectConfig,
+    manifest: Manifest,
+    name: str,
+    slug: str,
+    branch: str,
+    worktree: Path,
+    repo_root: Path,
+) -> dict[str, str]:
+    env = {
+        "NEW_FEATURE_NAME": name,
+        "NEW_FEATURE_SLUG": slug,
+        "NEW_FEATURE_BRANCH": branch,
+        "NEW_FEATURE_WORKTREE": str(worktree),
+        "NEW_FEATURE_REPO_ROOT": str(repo_root),
+    }
+    for key, spec in config.env.items():
+        env[key] = _allocate_value(key, spec, manifest, slug, repo_root)
+    return env
+
+
+def _allocate_value(key: str, spec: EnvSpec, manifest: Manifest, slug: str, repo_root: Path) -> str:
+    if spec.value is not None:
+        return spec.value
+    reserved = {record.env[key] for record in manifest.features.values() if key in record.env}
+    match spec.allocate:
+        case "port":
+            return _allocate_port(key, spec, reserved)
+        case "integer":
+            return _allocate_integer(key, spec, reserved)
+        case "name":
+            return _allocate_name(key, spec, slug, repo_root)
+        case "slug":
+            prefix = _safe_token(spec.prefix or key.lower(), separator="-")
+            return f"{prefix}-{slug}" if prefix else slug
+        case "path":
+            base = spec.base or ".new-feature"
+            return str(Path(base) / slug)
+        case None:
+            raise NewFeatureError(f"env spec {key} must set value or allocate")
+        case other:
+            raise NewFeatureError(f"unsupported allocator for {key}: {other}")
+
+
+def _allocate_port(key: str, spec: EnvSpec, reserved: set[str]) -> str:
+    minimum = spec.minimum if spec.minimum is not None else 1024
+    maximum = spec.maximum if spec.maximum is not None else 65535
+    for port in range(minimum, maximum + 1):
+        if str(port) in reserved:
+            continue
+        if _port_available(port):
+            return str(port)
+    raise NewFeatureError(f"no available port for {key} in range {minimum}-{maximum}")
+
+
+def _allocate_integer(key: str, spec: EnvSpec, reserved: set[str]) -> str:
+    minimum = spec.minimum if spec.minimum is not None else 0
+    maximum = spec.maximum if spec.maximum is not None else 65535
+    for value in range(minimum, maximum + 1):
+        if str(value) not in reserved:
+            return str(value)
+    raise NewFeatureError(f"no available integer for {key} in range {minimum}-{maximum}")
+
+
+def _allocate_name(key: str, spec: EnvSpec, slug: str, repo_root: Path) -> str:
+    prefix = _safe_token(spec.prefix or key.lower(), separator="_")
+    body = _safe_token(slug, separator="_")
+    digest = hashlib.sha256(f"{repo_root}:{slug}:{key}".encode()).hexdigest()[:8]
+    value = f"{prefix}_{body}_{digest}" if prefix else f"{body}_{digest}"
+    if spec.max_length and len(value) > spec.max_length:
+        suffix = f"_{digest}"
+        value = value[: spec.max_length - len(suffix)].rstrip("_") + suffix
+    return value
+
+
+def _safe_token(value: str, *, separator: str) -> str:
+    token = re.sub(r"[^a-zA-Z0-9]+", separator, value).strip(separator).lower()
+    return re.sub(rf"{re.escape(separator)}+", separator, token)
+
+
+def _port_available(port: int) -> bool:
+    with socket.socket() as sock:
+        try:
+            sock.bind(("127.0.0.1", port))
+        except OSError:
+            return False
+    return True

new_feature-0.1.0/src/new_feature/app.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+
+from new_feature.cli import main as cli_main
+
+
+def main(argv: list[str] | None = None) -> int:
+    return cli_main(sys.argv[1:] if argv is None else argv)

new_feature-0.1.0/src/new_feature/cli.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from new_feature.agent import build_initial_prompt, launch_interactive_agent
+from new_feature.allocator import allocate_env
+from new_feature.commands import run_commands
+from new_feature.config import load_project_config
+from new_feature.errors import NewFeatureError
+from new_feature.git import (
+    abort_merge,
+    begin_merge_without_commit,
+    commit_merge,
+    create_worktree,
+    push_target,
+    remove_worktree_and_branch,
+    repo_root,
+    worktree_is_clean,
+)
+from new_feature.gitignore import ensure_generated_paths_ignored
+from new_feature.manifest import FeatureRecord, load_manifest, manifest_lock, save_manifest
+from new_feature.slug import feature_key, slugify
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="new-feature",
+        description="Create isolated feature worktrees and launch an interactive agent.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    create = subparsers.add_parser("create", help="create a feature worktree")
+    create.add_argument("name")
+    create.add_argument("--no-launch", action="store_true")
+    create.add_argument("--dry-run", action="store_true")
+    create.set_defaults(command="create")
+
+    merge = subparsers.add_parser("merge-feature")
+    merge.add_argument("name")
+    merge.set_defaults(command="merge-feature")
+
+    teardown = subparsers.add_parser("teardown")
+    teardown.add_argument("name")
+    teardown.add_argument("--force", action="store_true")
+    teardown.set_defaults(command="teardown")
+    return parser
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    if argv and argv[0] not in {"create", "merge-feature", "teardown"} and not argv[0].startswith("-"):
+        argv = ["create", *argv]
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.error("feature name or subcommand is required")
+    return args
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    try:
+        root = repo_root(Path.cwd())
+        if args.command == "create":
+            return _create(root, args.name, no_launch=args.no_launch, dry_run=args.dry_run)
+        if args.command == "merge-feature":
+            return _merge_feature(root, args.name)
+        if args.command == "teardown":
+            return _teardown(root, args.name, force=args.force)
+        raise NewFeatureError(f"unknown command: {args.command}")
+    except NewFeatureError as exc:
+        print(f"new-feature: {exc}", file=sys.stderr)
+        return 1
+
+
+def _create(root: Path, name: str, *, no_launch: bool, dry_run: bool) -> int:
+    config = load_project_config(root)
+    slug = slugify(name)
+    key = feature_key(slug)
+    branch = f"{config.branch_prefix}{slug}"
+    worktree = root / ".worktrees" / slug
+
+    ensure_generated_paths_ignored(root)
+    with manifest_lock(root):
+        manifest = load_manifest(root)
+        if key in manifest.features:
+            raise NewFeatureError(f"feature already exists: {slug}")
+        env = allocate_env(
+            config=config,
+            manifest=manifest,
+            name=name,
+            slug=slug,
+            branch=branch,
+            worktree=worktree,
+            repo_root=root,
+        )
+        if dry_run:
+            for env_key, env_value in sorted(env.items()):
+                print(f"{env_key}={env_value}")
+            return 0
+        create_worktree(root, branch=branch, worktree=worktree, target_branch=config.target_branch)
+        manifest.features[key] = FeatureRecord(
+            name=name,
+            slug=slug,
+            branch=branch,
+            worktree=str(worktree.relative_to(root)),
+            target_branch=config.target_branch,
+            status="active",
+            created_at=_now(),
+            env=env,
+        )
+        save_manifest(root, manifest)
+
+    run_commands(config.setup, cwd=worktree, env=env)
+    if no_launch:
+        return 0
+    prompt = build_initial_prompt(slug)
+    return launch_interactive_agent(config.agent, worktree, env, prompt)
+
+
+def _merge_feature(root: Path, name: str) -> int:
+    config = load_project_config(root)
+    key = feature_key(slugify(name))
+    with manifest_lock(root):
+        manifest = load_manifest(root)
+        record = manifest.features.get(key)
+        if record is None:
+            raise NewFeatureError(f"unknown feature: {name}")
+    worktree = root / record.worktree
+    run_commands(config.pre_merge, cwd=worktree, env=record.env)
+    if not worktree_is_clean(worktree):
+        raise NewFeatureError("feature worktree has uncommitted changes; commit them before merging")
+    if not worktree_is_clean(root):
+        raise NewFeatureError("target checkout has uncommitted changes; commit or stash them before merging")
+    begin_merge_without_commit(root, branch=record.branch, target_branch=record.target_branch)
+    try:
+        run_commands(config.post_merge, cwd=root, env=record.env)
+    except NewFeatureError:
+        abort_merge(root)
+        raise
+    commit_merge(root, name=record.name)
+    if config.push:
+        push_target(root, target_branch=record.target_branch)
+    with manifest_lock(root):
+        manifest = load_manifest(root)
+        record = manifest.features.get(key)
+        if record is None:
+            raise NewFeatureError(f"unknown feature after merge: {name}")
+        record.status = "merged"
+        record.merged_at = _now()
+        save_manifest(root, manifest)
+    return 0
+
+
+def _teardown(root: Path, name: str, *, force: bool) -> int:
+    config = load_project_config(root)
+    key = feature_key(slugify(name))
+    with manifest_lock(root):
+        manifest = load_manifest(root)
+        record = manifest.features.get(key)
+        if record is None:
+            raise NewFeatureError(f"unknown feature: {name}")
+        merged = record.status == "merged"
+        if not merged and not force:
+            raise NewFeatureError("feature is not merged; pass --force to abandon it")
+    worktree = root / record.worktree
+    run_commands(config.teardown, cwd=worktree, env=record.env)
+    remove_worktree_and_branch(root, branch=record.branch, worktree=worktree, force=force or not merged)
+    with manifest_lock(root):
+        manifest = load_manifest(root)
+        del manifest.features[key]
+        save_manifest(root, manifest)
+    return 0
+
+
+def _now() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")

new_feature-0.1.0/src/new_feature/commands.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from pathlib import Path
+
+from new_feature.errors import NewFeatureError
+
+logger = logging.getLogger(__name__)
+
+
+def run_commands(commands: list[str], *, cwd: Path, env: dict[str, str]) -> None:
+    process_env = {**os.environ, **env}
+    for command in commands:
+        logger.info("running configured command", extra={"command": command})
+        result = subprocess.run(command, shell=True, cwd=cwd, env=process_env, check=False)
+        if result.returncode != 0:
+            raise NewFeatureError(f"command failed with exit code {result.returncode}: {command}")

new_feature-0.1.0/src/new_feature/config.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from new_feature.errors import NewFeatureError
+
+
+@dataclass(frozen=True)
+class EnvSpec:
+    allocate: str | None = None
+    value: str | None = None
+    minimum: int | None = None
+    maximum: int | None = None
+    prefix: str | None = None
+    max_length: int | None = None
+    base: str | None = None
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    target_branch: str = "main"
+    branch_prefix: str = "feature/"
+    agent: str = "codex"
+    push: bool = False
+    setup: list[str] = field(default_factory=list)
+    pre_merge: list[str] = field(default_factory=list)
+    post_merge: list[str] = field(default_factory=list)
+    teardown: list[str] = field(default_factory=list)
+    env: dict[str, EnvSpec] = field(default_factory=dict)
+
+
+def _string_list(raw: dict[str, Any], name: str) -> list[str]:
+    value = raw.get(name, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise NewFeatureError(f"tool.new-feature.{name} must be a list of strings")
+    return list(value)
+
+
+def load_project_config(repo_root: Path) -> ProjectConfig:
+    pyproject = repo_root / "pyproject.toml"
+    if not pyproject.exists():
+        return ProjectConfig()
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    raw = data.get("tool", {}).get("new-feature", {})
+    if not isinstance(raw, dict):
+        raise NewFeatureError("[tool.new-feature] must be a TOML table")
+
+    env_raw = raw.get("env", {})
+    if not isinstance(env_raw, dict):
+        raise NewFeatureError("[tool.new-feature.env] must be a TOML table")
+
+    env: dict[str, EnvSpec] = {}
+    for key, value in env_raw.items():
+        if not isinstance(value, dict):
+            raise NewFeatureError(f"env spec {key} must be a TOML inline table")
+        env[key] = EnvSpec(
+            allocate=value.get("allocate"),
+            value=value.get("value"),
+            minimum=value.get("min"),
+            maximum=value.get("max"),
+            prefix=value.get("prefix"),
+            max_length=value.get("max_length"),
+            base=value.get("base"),
+        )
+
+    return ProjectConfig(
+        target_branch=str(raw.get("target_branch", "main")),
+        branch_prefix=str(raw.get("branch_prefix", "feature/")),
+        agent=str(raw.get("agent", "codex")),
+        push=bool(raw.get("push", False)),
+        setup=_string_list(raw, "setup"),
+        pre_merge=_string_list(raw, "pre_merge"),
+        post_merge=_string_list(raw, "post_merge"),
+        teardown=_string_list(raw, "teardown"),
+        env=env,
+    )

new_feature-0.1.0/src/new_feature/errors.py

@@ -0,0 +1,2 @@
+class NewFeatureError(RuntimeError):
+    """User-facing error raised by the new-feature CLI."""

new_feature-0.1.0/src/new_feature/git.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from new_feature.errors import NewFeatureError
+
+
+def repo_root(cwd: Path) -> Path:
+    result = _git(cwd, "rev-parse", "--show-toplevel", capture=True)
+    return Path(result.stdout.strip())
+
+
+def ensure_repo_has_commits(root: Path) -> None:
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", "HEAD"], cwd=root, capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        raise NewFeatureError("repository has no commits; make an initial commit before creating worktrees")
+
+
+def create_worktree(root: Path, *, branch: str, worktree: Path, target_branch: str) -> None:
+    ensure_repo_has_commits(root)
+    worktree.parent.mkdir(parents=True, exist_ok=True)
+    _git(root, "worktree", "add", "-b", branch, str(worktree), target_branch)
+
+
+def worktree_is_clean(worktree: Path) -> bool:
+    result = _git(worktree, "status", "--porcelain", capture=True)
+    return not result.stdout.strip()
+
+
+def is_branch_merged(root: Path, *, branch: str, target_branch: str) -> bool:
+    result = subprocess.run(
+        ["git", "merge-base", "--is-ancestor", branch, target_branch], cwd=root, check=False
+    )
+    return result.returncode == 0
+
+
+def begin_merge_without_commit(root: Path, *, branch: str, target_branch: str) -> None:
+    _git(root, "checkout", target_branch)
+    _git(root, "merge", "--no-commit", "--no-ff", branch)
+
+
+def commit_merge(root: Path, *, name: str) -> None:
+    _git(root, "commit", "-m", f"Merge feature {name}")
+
+
+def abort_merge(root: Path) -> None:
+    subprocess.run(["git", "merge", "--abort"], cwd=root, check=False, env=_git_env())
+
+
+def push_target(root: Path, *, target_branch: str) -> None:
+    _git(root, "push", "origin", target_branch)
+
+
+def remove_worktree_and_branch(root: Path, *, branch: str, worktree: Path, force: bool) -> None:
+    args = ["worktree", "remove"]
+    if force:
+        args.append("--force")
+    args.append(str(worktree))
+    _git(root, *args)
+    _git(root, "branch", "-D" if force else "-d", branch)
+
+
+def _git(cwd: Path, *args: str, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    try:
+        result = subprocess.run(
+            ["git", *args], cwd=cwd, text=True, capture_output=capture, check=False, env=_git_env()
+        )
+    except OSError as exc:
+        raise NewFeatureError(f"git command failed: {exc}") from exc
+    if result.returncode != 0:
+        detail = result.stderr.strip() if capture and result.stderr else " ".join(args)
+        raise NewFeatureError(f"git command failed: {detail}")
+    return result
+
+
+def _git_env() -> dict[str, str]:
+    env = os.environ.copy()
+    for key in ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"):
+        env.pop(key, None)
+    return env

new_feature-0.1.0/src/new_feature/gitignore.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+GENERATED_PATTERNS = [".new-feature/", ".worktrees/"]
+
+
+def ensure_generated_paths_ignored(repo_root: Path) -> None:
+    gitignore = repo_root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8").splitlines() if gitignore.exists() else []
+    changed = False
+    for pattern in GENERATED_PATTERNS:
+        if pattern not in existing:
+            existing.append(pattern)
+            changed = True
+    if changed or not gitignore.exists():
+        gitignore.write_text("\n".join(existing) + "\n", encoding="utf-8")

new_feature-0.1.0/src/new_feature/manifest.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomli_w
+from filelock import FileLock
+
+MANIFEST_DIR = ".new-feature"
+MANIFEST_FILE = "manifest.toml"
+LOCK_FILE = "manifest.lock"
+
+
+@dataclass
+class FeatureRecord:
+    name: str
+    slug: str
+    branch: str
+    worktree: str
+    target_branch: str
+    status: str
+    created_at: str
+    merged_at: str = ""
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class Manifest:
+    version: int = 1
+    features: dict[str, FeatureRecord] = field(default_factory=dict)
+
+
+def manifest_path(repo_root: Path) -> Path:
+    return repo_root / MANIFEST_DIR / MANIFEST_FILE
+
+
+@contextmanager
+def manifest_lock(repo_root: Path) -> Iterator[None]:
+    lock_path = repo_root / MANIFEST_DIR / LOCK_FILE
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with FileLock(str(lock_path)):
+        yield
+
+
+def load_manifest(repo_root: Path) -> Manifest:
+    path = manifest_path(repo_root)
+    if not path.exists():
+        return Manifest()
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    features: dict[str, FeatureRecord] = {}
+    for key, raw in data.get("features", {}).items():
+        features[key] = FeatureRecord(
+            name=str(raw["name"]),
+            slug=str(raw["slug"]),
+            branch=str(raw["branch"]),
+            worktree=str(raw["worktree"]),
+            target_branch=str(raw["target_branch"]),
+            status=str(raw["status"]),
+            created_at=str(raw.get("created_at", "")),
+            merged_at=str(raw.get("merged_at", "")),
+            env={str(env_key): str(env_value) for env_key, env_value in raw.get("env", {}).items()},
+        )
+    return Manifest(version=int(data.get("version", 1)), features=features)
+
+
+def save_manifest(repo_root: Path, manifest: Manifest) -> None:
+    path = manifest_path(repo_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "version": manifest.version,
+        "features": {
+            key: {
+                "name": record.name,
+                "slug": record.slug,
+                "branch": record.branch,
+                "worktree": record.worktree,
+                "target_branch": record.target_branch,
+                "status": record.status,
+                "created_at": record.created_at,
+                "merged_at": record.merged_at,
+                "env": record.env,
+            }
+            for key, record in sorted(manifest.features.items())
+        },
+    }
+    path.write_text(tomli_w.dumps(data), encoding="utf-8")

new_feature-0.1.0/src/new_feature/slug.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import re
+
+from new_feature.errors import NewFeatureError
+
+
+def slugify(name: str) -> str:
+    raw = name.strip().lower()
+    if not raw:
+        raise NewFeatureError("feature name cannot be empty")
+    slug = re.sub(r"[^a-z0-9]+", "-", raw).strip("-")
+    slug = re.sub(r"-{2,}", "-", slug)
+    if not slug:
+        raise NewFeatureError("feature name must contain letters or numbers")
+    return slug
+
+
+def feature_key(slug: str) -> str:
+    return slug.replace("-", "_")