atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/commands/__init__.py

@@ -0,0 +1 @@
+"""Commandsmith-discoverable command modules."""

atomadic_forge/commands/_registry.py

@@ -0,0 +1,36 @@
+"""
+Auto-generated by Commandsmith — do NOT hand-edit.
+Run ``atomadic-forge commandsmith sync`` to refresh.
+"""
+
+from __future__ import annotations
+
+import typer
+
+
+def register_all(app: typer.Typer) -> None:
+    """Register every Commandsmith-discovered command on ``app``."""
+    from atomadic_forge.commands.chat import app as _app_chat
+    app.add_typer(_app_chat, name='chat', help='Chat with a Forge-aware AI copilot over optional repo context.', hidden=False)
+    from atomadic_forge.commands.commandsmith import app as _app_commandsmith
+    app.add_typer(_app_commandsmith, name='commandsmith', help='``atomadic-forge commandsmith`` — manage the auto-wired CLI command registry.', hidden=False)
+    from atomadic_forge.commands.config_cmd import app as _app_config
+    app.add_typer(_app_config, name='config', help='Configure Atomadic Forge — setup wizard + config management.', hidden=False)
+    from atomadic_forge.commands.demo import app as _app_demo
+    app.add_typer(_app_demo, name='demo', help='One-shot launch-video verb: preset evolve + DEMO.md artifact.', hidden=False)
+    from atomadic_forge.commands.emergent import app as _app_emergent
+    app.add_typer(_app_emergent, name='emergent', help='Synthesise new feature candidates from existing components.', hidden=False)
+    from atomadic_forge.commands.emergent_then_synergy import app as _app_emergent_then_synergy
+    app.add_typer(_app_emergent_then_synergy, name='emergent-then-synergy', help='Run emergent to emit a JSON artifact, then feed it to synergy for the next phase.', hidden=False)
+    from atomadic_forge.commands.evolve import app as _app_evolve
+    app.add_typer(_app_evolve, name='evolve', help="Recursive self-improvement: run iterate N times, each round seeded by the previous round's growing catalog.", hidden=False)
+    from atomadic_forge.commands.evolve_then_iterate import app as _app_evolve_then_iterate
+    app.add_typer(_app_evolve_then_iterate, name='evolve-then-iterate', help='Run evolve to emit a JSON artifact, then feed it to iterate for the next phase.', hidden=False)
+    from atomadic_forge.commands.feature_then_emergent import app as _app_feature_then_emergent
+    app.add_typer(_app_feature_then_emergent, name='feature-then-emergent', help='Run any feature, then fan its JSON output into emergent scan to surface novel compositions.', hidden=False)
+    from atomadic_forge.commands.iterate import app as _app_iterate
+    app.add_typer(_app_iterate, name='iterate', help='Architecturally-coherent code generation: LLM emits, Forge enforces, loop iterates until certify clears.', hidden=False)
+    from atomadic_forge.commands.synergy import app as _app_synergy
+    app.add_typer(_app_synergy, name='synergy', help="Find feature/CLI synergies (producer-consumer pairs that aren't wired together) and optionally implement adapters.", hidden=False)
+    from atomadic_forge.commands.synergy_then_emergent import app as _app_synergy_then_emergent
+    app.add_typer(_app_synergy_then_emergent, name='synergy-then-emergent', help='Run synergy to emit a JSON artifact, then feed it to emergent for the next phase.', hidden=False)

atomadic_forge/commands/audit.py

@@ -0,0 +1,142 @@
+"""Tier a4 — `forge audit` verb: surface .atomadic-forge lineage.
+
+Lane D1 of the post-audit plan. Closes the 'lineage exists but is
+invisible' friction point: every --apply already writes to
+.atomadic-forge/lineage.jsonl, but until now there was no verb to
+query it short of `cat | jq`.
+
+Subcommands:
+  forge audit list <project> [--last N] [--json]
+      Summary of distinct artifacts, run counts, and latest write times.
+
+  forge audit show <project> <artifact> [--json]
+      Pretty-print the named manifest (scout, cherry, wire, certify, …).
+
+  forge audit log  <project> [--last N] [--json]
+      Raw lineage entries (newest-last).
+
+Future subcommands ('trend', 'replay') need lineage-shape extension
+and are reserved for their own lane.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ..a1_at_functions.error_hints import format_hint
+from ..a1_at_functions.lineage_reader import (
+    list_artifacts,
+    load_manifest,
+    read_lineage,
+)
+
+COMMAND_NAME = "audit"
+COMMAND_HELP = (
+    "Surface the .atomadic-forge lineage log: list runs, inspect "
+    "saved manifests, replay history."
+)
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+
+@app.command("list")
+def list_cmd(
+    project: Annotated[Path, typer.Argument(
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True,
+        help="Project root containing .atomadic-forge/.")] = Path("."),
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Summarize each artifact: run count, latest write time, path."""
+    entries = list_artifacts(project)
+    if json_out:
+        typer.echo(json.dumps(
+            {"schema_version": "atomadic-forge.audit.list/v1",
+             "project": str(project),
+             "artifact_count": len(entries),
+             "artifacts": entries},
+            indent=2, default=str))
+        return
+    if not entries:
+        typer.echo(f"\nNo lineage found at {project}/.atomadic-forge/lineage.jsonl")
+        typer.echo("\nLineage is recorded automatically when you run any verb")
+        typer.echo("with --apply (forge auto, forge cherry, forge finalize).")
+        return
+    typer.echo(f"\nForge audit — artifacts under {project}/.atomadic-forge/")
+    typer.echo("-" * 60)
+    for e in entries:
+        typer.echo(
+            f"  {e['artifact']:<20} runs={e['run_count']:<3} "
+            f"latest={e['latest_ts_utc']}  ({e['path']})"
+        )
+    typer.echo(f"\n  {len(entries)} distinct artifact(s).")
+
+
+@app.command("show")
+def show_cmd(
+    project: Annotated[Path, typer.Argument(
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)],
+    artifact: Annotated[str, typer.Argument(
+        help="Manifest name: scout | cherry | assimilate | wire | certify | "
+             "auto | (custom).")],
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Pretty-print the JSON manifest for ``artifact``."""
+    data = load_manifest(project, artifact)
+    if data is None:
+        raise typer.BadParameter(
+            format_hint("not_a_forge_manifest",
+                        path=project / ".atomadic-forge" / f"{artifact}.json")
+        )
+    if json_out:
+        typer.echo(json.dumps(data, indent=2, default=str))
+        return
+    schema = data.get("schema_version", "(unknown)")
+    typer.echo(f"\nForge audit — {artifact} ({schema})")
+    typer.echo("-" * 60)
+    # Compact summary lines: top-level keys with non-collection values,
+    # plus collection sizes. Verbose dump available via --json.
+    for key, value in data.items():
+        if isinstance(value, dict):
+            typer.echo(f"  {key}: <dict, {len(value)} keys>")
+        elif isinstance(value, list):
+            typer.echo(f"  {key}: <list, {len(value)} items>")
+        else:
+            typer.echo(f"  {key}: {value}")
+    typer.echo("\n  (re-run with --json for full payload)")
+
+
+@app.command("log")
+def log_cmd(
+    project: Annotated[Path, typer.Argument(
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)] = Path("."),
+    last: Annotated[int, typer.Option("--last",
+        help="Show only the most recent N entries.")] = 20,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Show raw lineage entries (newest-last)."""
+    entries = read_lineage(project, last=last)
+    if json_out:
+        typer.echo(json.dumps(
+            {"schema_version": "atomadic-forge.audit.log/v1",
+             "project": str(project),
+             "entry_count": len(entries),
+             "entries": entries},
+            indent=2, default=str))
+        return
+    if not entries:
+        typer.echo(f"\nNo lineage entries at {project}/.atomadic-forge/lineage.jsonl")
+        return
+    typer.echo(f"\nForge audit — last {len(entries)} lineage entries")
+    typer.echo("-" * 60)
+    for e in entries:
+        typer.echo(f"  {e.get('ts_utc', '?')}  "
+                   f"{e.get('artifact', '?'):<20}  "
+                   f"{e.get('path', '?')}")
+
+
+def register(parent: typer.Typer) -> None:
+    """Hook used by the unified CLI to mount this sub-app."""
+    parent.add_typer(app, name=COMMAND_NAME, help=COMMAND_HELP)

atomadic_forge/commands/chat.py

@@ -0,0 +1,133 @@
+"""``forge chat`` — chat copilot over Forge + optional repo context."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import click
+import typer
+
+from atomadic_forge.a1_at_functions.chat_context import (
+    build_chat_context,
+    chat_system_prompt,
+    render_chat_prompt,
+)
+from atomadic_forge.a1_at_functions.provider_resolver import (
+    PROVIDER_HELP,
+    resolve_provider,
+)
+
+COMMAND_NAME = "chat"
+COMMAND_HELP = "Chat with a Forge-aware AI copilot over optional repo context."
+
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+
+def _provider(name: str):
+    try:
+        return resolve_provider(name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _context_paths(context: list[Path] | None, cwd_context: bool) -> list[Path]:
+    if context:
+        return context
+    return [Path.cwd()] if cwd_context else []
+
+
+@app.command("ask")
+def ask_cmd(
+    message: Annotated[str, typer.Argument(help="Question or request for the copilot.")],
+    provider: Annotated[str, typer.Option("--provider",
+        help=PROVIDER_HELP)] = "auto",
+    context: Annotated[list[Path] | None, typer.Option("--context", "-c",
+        exists=True, file_okay=True, dir_okay=True, resolve_path=True,
+        help="File or directory to include as bounded context. Repeatable.")] = None,
+    cwd_context: Annotated[bool, typer.Option("--cwd-context/--no-cwd-context",
+        help="Use the current directory as context when --context is omitted.")] = True,
+    max_files: Annotated[int, typer.Option("--max-files",
+        help="Maximum files to pack into the chat context.")] = 12,
+    max_chars: Annotated[int, typer.Option("--max-chars",
+        help="Maximum context characters sent to the provider.")] = 16_000,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Ask one copilot question and print the answer."""
+    llm = _provider(provider)
+    ctx = build_chat_context(
+        _context_paths(context, cwd_context),
+        cwd=Path.cwd(),
+        max_files=max_files,
+        max_chars=max_chars,
+    )
+    prompt = render_chat_prompt(message, context=ctx["context"])
+    try:
+        answer = llm.call(prompt, system=chat_system_prompt())
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if json_out:
+        typer.echo(json.dumps({
+            "schema_version": "atomadic-forge.chat/v1",
+            "provider": llm.name,
+            "message": message,
+            "answer": answer,
+            "context": {
+                "file_count": ctx["file_count"],
+                "char_count": ctx["char_count"],
+                "files": ctx["files"],
+            },
+        }, indent=2, default=str))
+        return
+    typer.echo(answer.rstrip())
+
+
+@app.command("repl")
+def repl_cmd(
+    provider: Annotated[str, typer.Option("--provider",
+        help=PROVIDER_HELP)] = "auto",
+    context: Annotated[list[Path] | None, typer.Option("--context", "-c",
+        exists=True, file_okay=True, dir_okay=True, resolve_path=True,
+        help="File or directory to include as bounded context. Repeatable.")] = None,
+    cwd_context: Annotated[bool, typer.Option("--cwd-context/--no-cwd-context",
+        help="Use the current directory as context when --context is omitted.")] = True,
+    max_files: Annotated[int, typer.Option("--max-files")] = 12,
+    max_chars: Annotated[int, typer.Option("--max-chars")] = 16_000,
+) -> None:
+    """Start an interactive copilot session. Type ``/exit`` to leave."""
+    llm = _provider(provider)
+    ctx = build_chat_context(
+        _context_paths(context, cwd_context),
+        cwd=Path.cwd(),
+        max_files=max_files,
+        max_chars=max_chars,
+    )
+    typer.echo(f"Forge chat copilot ({llm.name}). Type /exit to leave.")
+    if ctx["file_count"]:
+        typer.echo(f"Context: {ctx['file_count']} file(s), {ctx['char_count']} chars.")
+    history: list[dict[str, str]] = []
+    while True:
+        try:
+            message = typer.prompt("you").strip()
+        except (EOFError, KeyboardInterrupt):
+            typer.echo("")
+            break
+        if message.lower() in {"/exit", "/quit", "exit", "quit", ":q"}:
+            break
+        if not message:
+            continue
+        prompt = render_chat_prompt(message, context=ctx["context"], history=history)
+        try:
+            answer = llm.call(prompt, system=chat_system_prompt()).rstrip()
+        except RuntimeError as exc:
+            typer.secho(f"Provider error: {exc}", fg=typer.colors.RED, err=True)
+            continue
+        typer.echo("")
+        typer.echo(answer)
+        typer.echo("")
+        history.extend([
+            {"role": "user", "content": message},
+            {"role": "assistant", "content": answer},
+        ])

atomadic_forge/commands/commandsmith.py

@@ -0,0 +1,178 @@
+"""``atomadic-forge commandsmith`` — manage the auto-wired CLI command registry.
+
+This is the operator-facing surface for the Commandsmith feature.  Every
+ASS-ADE assimilation cycle ends by adding new symbols (classes, functions)
+under ``atomadic_forge/``.  Commandsmith turns those symbols into invocable CLI
+verbs without any hand-editing of ``unified_cli.py``.
+
+Sub-commands:
+
+* ``atomadic-forge commandsmith discover``     — list discoverable command modules.
+* ``atomadic-forge commandsmith sync``         — regenerate registry + docs + manifest.
+* ``atomadic-forge commandsmith wrap``         — generate a Typer wrapper around a class.
+* ``atomadic-forge commandsmith smoke``        — run ``--help`` against every command.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a3_og_features.commandsmith_feature import Commandsmith
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Auto-register, document, and smoke-test ASS-ADE CLI commands.",
+)
+
+
+def _resolve_package_root() -> Path:
+    """Locate ``src/atomadic_forge`` from this file's location."""
+    here = Path(__file__).resolve()
+    return here.parent.parent  # commands/ -> atomadic_forge/
+
+
+@app.command("discover")
+def discover_cmd(
+    json_out: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+) -> None:
+    """List discoverable command modules under ``atomadic_forge/commands/``."""
+    cs = Commandsmith(package_root=_resolve_package_root())
+    cards = cs.discover()
+    if json_out:
+        typer.echo(json.dumps(cards, indent=2))
+        return
+    typer.echo(f"Discovered {len(cards)} command module(s):")
+    for c in cards:
+        flag = " [hidden]" if c["hidden"] else ""
+        typer.echo(f"  - {c['name']:24s} {c['surface']:14s} {c['module']}{flag}")
+
+
+@app.command("sync")
+def sync_cmd(
+    smoke: Annotated[bool, typer.Option("--smoke",
+        help="Also smoke-test every command's --help.")] = False,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Rebuild registry, per-command docs, and the manifest."""
+    cs = Commandsmith(package_root=_resolve_package_root())
+    manifest = cs.sync(smoke=smoke)
+    if json_out:
+        typer.echo(json.dumps(manifest, indent=2))
+        return
+    typer.echo(f"Wrote registry → {cs.commands_dir / '_registry.py'}")
+    typer.echo(f"Wrote docs    → {cs.docs_root}")
+    typer.echo(f"Manifest      → {cs.manifest_dir / 'commandsmith_manifest.json'}")
+    typer.echo(f"Total verbs:    {len(manifest['commands'])}")
+    if smoke:
+        passed = sum(1 for v in manifest["smoke_results"].values() if v)
+        typer.echo(f"Smoke:          {passed}/{len(manifest['smoke_results'])} passed")
+
+
+@app.command("wrap")
+def wrap_cmd(
+    target_module: Annotated[str, typer.Argument(
+        help="Importable module path of the class to wrap.")],
+    target_class: Annotated[str, typer.Argument(
+        help="Class name to wrap (must be importable).")],
+    command_name: Annotated[str, typer.Option("--name", "-n",
+        help="CLI verb to expose (kebab-case).")] = "",
+    help_text: Annotated[str, typer.Option("--help-text",
+        help="One-line help string for the generated subcommand group.")] = "",
+    out_dir: Annotated[Path | None, typer.Option("--out-dir",
+        help="Where to write the wrapper module (defaults to commands/).",
+        file_okay=False, dir_okay=True, resolve_path=True)] = None,
+) -> None:
+    """Generate a Typer wrapper around an importable class."""
+    cs = Commandsmith(package_root=_resolve_package_root())
+    name = command_name or target_class.lower()
+    name = "".join("-" + c.lower() if c.isupper() and i > 0 else c.lower()
+                   for i, c in enumerate(target_class)).lstrip("-")
+    name = command_name or name
+    out = cs.wrap_class(
+        target_module=target_module,
+        target_class=target_class,
+        command_name=name,
+        help_text=help_text or f"Auto-wrapped {target_class}",
+        out_dir=out_dir,
+    )
+    typer.echo(f"Wrote wrapper → {out}")
+    typer.echo("Run ``atomadic-forge commandsmith sync`` to register it.")
+
+
+_CORE_VERBS = [
+    "init", "auto", "recon", "cherry", "finalize", "wire", "plan",
+    "context-pack", "preflight", "recipes", "plan-list", "plan-show",
+    "plan-step", "plan-apply", "enforce", "certify", "sbom", "diff",
+    "doctor", "cs1", "sidecar", "mcp", "status",
+]
+
+
+@app.command("smoke")
+def smoke_cmd(
+    include_core: Annotated[bool, typer.Option(
+        "--include-core/--no-core",
+        help="Also smoke-test core verbs (init, wire, certify, etc.).")] = True,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Run ``<verb> --help`` for every registered command and report."""
+    import os
+    import subprocess
+    cs = Commandsmith(package_root=_resolve_package_root())
+    cards = cs.discover()
+    results = cs.smoke(cards)
+    if include_core:
+        env = os.environ.copy()
+        env["PYTHONIOENCODING"] = "utf-8"
+        env["PYTHONUTF8"] = "1"
+        cli = [sys.executable, "-m", "atomadic_forge.a4_sy_orchestration.cli"]
+        for verb in _CORE_VERBS:
+            if verb in results:
+                continue
+            try:
+                rc = subprocess.run(
+                    cli + [verb, "--help"],
+                    capture_output=True, timeout=20, env=env,
+                ).returncode
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                rc = 1
+            results[verb] = rc == 0
+    if json_out:
+        typer.echo(json.dumps(results, indent=2))
+        return
+    pad = max((len(n) for n in results), default=0)
+    for name, ok in sorted(results.items()):
+        mark = "PASS" if ok else "FAIL"
+        typer.echo(f"  {mark:5s} {name:<{pad}}")
+    failed = [n for n, ok in results.items() if not ok]
+    if failed:
+        typer.echo(f"\n{len(failed)} verb(s) failed --help:", err=True)
+        raise typer.Exit(1)
+
+
+@app.command("repair-imports")
+def repair_imports_cmd(
+    package_root: Annotated[Path, typer.Argument(
+        help="Path to <output>/src/<package>/ produced by atomadic-forge assimilate.",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True)],
+    apply: Annotated[bool, typer.Option("--apply",
+        help="Write changes (default: dry-run).")] = False,
+) -> None:
+    """Repair broken cross-symbol imports in an assimilated tier tree.
+
+    The assimilator emits one file per symbol but does not always rewrite
+    intra-package references (``from <flat-name> import X``).  This pass
+    looks each name up in the tier-local sibling files and rewrites the
+    import to a relative sibling reference.
+    """
+    from atomadic_forge.a1_at_functions.commandsmith_import_repair import (
+        repair_assimilation_output,
+    )
+    diffs = repair_assimilation_output(package_root, dry_run=not apply)
+    total = sum(len(v) for v in diffs.values())
+    for tier, items in diffs.items():
+        typer.echo(f"  {tier}: {len(items)} files {'rewritten' if apply else 'would change'}")
+    typer.echo(f"TOTAL: {total} files {'rewritten' if apply else 'would change'} ({'applied' if apply else 'dry-run'})")

atomadic_forge/commands/config_cmd.py

@@ -0,0 +1,145 @@
+"""Tier a4 — config management CLI commands (show, set, test, wizard)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from atomadic_forge.a0_qk_constants.config_defaults import (
+    CONFIG_FILE_NAME,
+    GLOBAL_CONFIG_DIR,
+    LOCAL_CONFIG_DIR,
+)
+from atomadic_forge.a1_at_functions.config_io import (
+    load_config,
+    read_config_file,
+    save_config,
+    validate_config,
+)
+from atomadic_forge.a1_at_functions.provider_detect import test_provider
+
+COMMAND_NAME = "config"
+COMMAND_HELP = "Configure Atomadic Forge — setup wizard + config management."
+
+app = typer.Typer(no_args_is_help=True, help=COMMAND_HELP)
+
+_CWD = Path(".")
+
+
+@app.command("wizard")
+def wizard_cmd(
+    project_dir: Annotated[
+        Path,
+        typer.Option("--project", file_okay=False, dir_okay=True, resolve_path=True,
+                     help="Project directory (default: cwd)."),
+    ] = _CWD,
+) -> None:
+    """Interactive setup wizard — configure LLM, defaults, and workspace."""
+    from atomadic_forge.a3_og_features.setup_wizard import run_wizard
+    run_wizard(project_dir.resolve())
+
+
+@app.command("show")
+def show_cmd(
+    project_dir: Annotated[
+        Path,
+        typer.Option("--project", file_okay=False, dir_okay=True, resolve_path=True,
+                     help="Project directory (default: cwd)."),
+    ] = _CWD,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Print the current merged config (local → global → defaults)."""
+    config = load_config(project_dir.resolve())
+    issues = validate_config(config)
+
+    if json_out:
+        typer.echo(json.dumps({"config": config, "issues": issues}, indent=2))
+        return
+
+    typer.echo("\nAtomadic Forge — config")
+    typer.echo("-" * 44)
+    for k, v in config.items():
+        if "key" in k and v:
+            s = str(v)
+            display = s[:8] + "..." + s[-4:] if len(s) > 12 else "***"
+        else:
+            display = str(v) if v is not None else "(not set)"
+        typer.echo(f"  {k:28s} {display}")
+
+    if issues:
+        typer.echo("\nValidation issues:")
+        for issue in issues:
+            typer.secho(f"  - {issue}", fg="yellow")
+    else:
+        typer.secho("\n  Config is valid.", fg="green")
+
+
+@app.command("set")
+def set_cmd(
+    key: Annotated[str, typer.Argument(help="Config key to set.")],
+    value: Annotated[str, typer.Argument(help="Value to assign.")],
+    project_dir: Annotated[
+        Path,
+        typer.Option("--project", file_okay=False, dir_okay=True, resolve_path=True,
+                     help="Project directory (default: cwd)."),
+    ] = _CWD,
+    global_: Annotated[
+        bool,
+        typer.Option("--global", help="Write to global config (~/.atomadic-forge/config.json)."),
+    ] = False,
+) -> None:
+    """Set a single config key in the local (or --global) config file."""
+    if global_:
+        config_path = Path(GLOBAL_CONFIG_DIR).expanduser() / CONFIG_FILE_NAME
+    else:
+        config_path = project_dir.resolve() / LOCAL_CONFIG_DIR / CONFIG_FILE_NAME
+
+    current = read_config_file(config_path)
+
+    # Coerce obvious types so booleans and numbers round-trip cleanly.
+    coerced: object = value
+    if value.lower() in ("true", "false"):
+        coerced = value.lower() == "true"
+    else:
+        try:
+            coerced = float(value) if "." in value else int(value)
+        except ValueError:
+            pass
+
+    current[key] = coerced
+    save_config(current, config_path)
+    typer.echo(f"  Set {key!r} = {coerced!r}  →  {config_path}")
+
+
+@app.command("test")
+def test_cmd(
+    project_dir: Annotated[
+        Path,
+        typer.Option("--project", file_okay=False, dir_okay=True, resolve_path=True,
+                     help="Project directory (default: cwd)."),
+    ] = _CWD,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help="Override provider to test."),
+    ] = None,
+    json_out: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Test the configured LLM provider connection."""
+    config = load_config(project_dir.resolve())
+    p = provider or config.get("provider", "auto")
+    result = test_provider(p, config)
+
+    if json_out:
+        typer.echo(json.dumps(result, indent=2))
+        return
+
+    color = "green" if result["ok"] else "red"
+    typer.secho(f"\nProvider test — {p}", bold=True)
+    typer.secho(f"  Status:    {'OK' if result['ok'] else 'FAIL'}", fg=color)
+    typer.echo(f"  Model:     {result['model']}")
+    typer.echo(f"  Latency:   {result['latency_ms']}ms")
+    if result["error"]:
+        typer.secho(f"  Error:     {result['error']}", fg="yellow")