agentforge-py 0.2.1__py3-none-any.whl

agentforge/cli/_shared_scaffold.py

@@ -0,0 +1,174 @@
+"""Shared scaffold injection (feat-019).
+
+After `agentforge new` finishes Copier-rendering the chosen
+template, this module copies the contents of
+`agentforge.templates._shared` into the destination, rendering each
+file through Jinja with the same answer context Copier saw. Each
+shared file gets a marker header and an entry in the managed-files
+lock — they participate in `agentforge upgrade` / `fork` exactly
+like template-rendered files do.
+
+The shared directory carries the runbooks, AGENTS.md, CLAUDE.md,
+.cursorrules, and .github/copilot-instructions.md that ship with
+every scaffolded agent. Putting them in one place keeps the
+framework's six templates from each maintaining a near-duplicate
+copy.
+
+A `.tmpl` extension on a file marks it as Jinja-templated; the
+extension is stripped on write. Files without `.tmpl` are copied
+verbatim (apart from the marker header prepend).
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jinja2 import Environment
+
+from agentforge.cli._scaffold_state import (
+    END_MANAGED_MARKER,
+    answers_path,
+    hash_content,
+    lock_path,
+    marker_for,
+    read_lock,
+    write_lock,
+)
+
+
+def inject_shared_scaffold(
+    dst: Path,
+    *,
+    template_name: str,
+    template_version: str,
+) -> int:
+    """Copy `_shared/` into the destination after Copier rendered.
+
+    Returns the count of files written.
+    """
+    shared_root = _shared_root()
+    if shared_root is None:
+        return 0
+
+    context = _build_context(dst, template_name=template_name)
+    # The shared payload is markdown / YAML / plain text — never HTML
+    # rendered to a browser — so HTML escaping would actively corrupt
+    # the output (e.g. `&` in code blocks becomes `&`).
+    env = Environment(  # nosec B701 — markdown output, not HTML
+        autoescape=False,  # noqa: S701
+        keep_trailing_newline=True,
+    )
+
+    lock = read_lock(dst)
+    count = 0
+    for src_path in _walk(shared_root):
+        rel_path = src_path.relative_to(shared_root)
+        out_rel, content = _render_one(src_path, rel_path, env, context)
+        target = dst / out_rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        marker = marker_for(
+            target.suffix, f"template:{template_name}", template_version, hash_content(content)[:12]
+        )
+        body = content
+        if marker is not None and not content.lstrip().startswith(marker.strip()):
+            body = marker + "\n" + content
+        target.write_text(body, encoding="utf-8")
+
+        lock[str(out_rel)] = {
+            "hash": hash_content(content),
+            "source_module": f"template:{template_name}:_shared",
+            "source_version": template_version,
+            "forked": False,
+        }
+        count += 1
+
+    write_lock(dst, lock)
+    return count
+
+
+def _walk(root: Path) -> list[Path]:
+    """Walk `root` and return every regular file path."""
+    return sorted(path for path in root.rglob("*") if path.is_file())
+
+
+def _render_one(
+    src_path: Path,
+    rel_path: Path,
+    env: Environment,
+    context: dict[str, Any],
+) -> tuple[Path, str]:
+    """Render a single shared file, returning (out_rel_path, content).
+
+    `.tmpl`-suffixed files have the suffix stripped and are run
+    through Jinja. Everything else is copied verbatim.
+    """
+    body = src_path.read_text(encoding="utf-8")
+    if src_path.suffix == ".tmpl":
+        body = env.from_string(body).render(**context)
+        out_rel = rel_path.with_suffix("")  # drop `.tmpl`
+    else:
+        out_rel = rel_path
+    if not body.endswith("\n"):
+        body += "\n"
+    if END_MANAGED_MARKER in body:
+        # Three-section file (feat-019 chunk 1) — already terminates
+        # the managed section explicitly.
+        return out_rel, body
+    return out_rel, body
+
+
+def _build_context(dst: Path, *, template_name: str) -> dict[str, Any]:
+    """Pull the Copier answer file into a Jinja context, supplementing
+    with framework metadata."""
+    answers = _read_answers(dst)
+    return {
+        "project_name": answers.get("project_name", "My Agent"),
+        "project_slug": answers.get("project_slug", "my-agent"),
+        "llm_provider": answers.get("llm_provider", "bedrock"),
+        "description": answers.get("description", "An AgentForge agent."),
+        "template_name": template_name,
+        "framework_version": _framework_version(),
+        "module_list": [],
+    }
+
+
+def _read_answers(dst: Path) -> dict[str, Any]:
+    path = answers_path(dst)
+    if not path.exists():
+        return {}
+    raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(raw, dict):
+        return {}
+    return {str(k): v for k, v in raw.items()}
+
+
+def _framework_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version  # noqa: PLC0415
+
+    try:
+        return version("agentforge")
+    except PackageNotFoundError:  # pragma: no cover
+        return "0.0.0+unknown"
+
+
+def _shared_root() -> Path | None:
+    """Return the on-disk path of the `_shared/` template directory."""
+    try:
+        traversable = resources.files("agentforge.templates").joinpath("_shared")
+    except ModuleNotFoundError:
+        return None
+    with resources.as_file(traversable) as path:
+        if not path.exists() or not path.is_dir():
+            return None
+        return Path(path)
+
+
+# Silence unused-imports warning for re-exported markers.
+_ = (lock_path,)
+
+
+__all__ = ["inject_shared_scaffold"]

agentforge/cli/config_cmd.py

@@ -0,0 +1,174 @@
+"""`agentforge config {validate,show,schema}` — read-only config CLI.
+
+All three commands invoke the loader and surface useful output:
+- **validate**: loads the file, runs schema + module-schema
+  validation, prints "OK" on success or the error path on failure.
+- **show**: prints the fully-resolved config as YAML; `--resolved`
+  expands env vars + overrides (default), `--raw` shows the parsed
+  YAML pre-interpolation.
+- **schema**: emits the root `AgentForgeConfig` JSON Schema for
+  editor autocomplete (SchemaStore-style).
+
+The destructive `add/swap/remove` commands ship in a follow-up
+sub-feat (deferred from feat-010 alongside this PR).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import yaml
+from agentforge_core.config import (
+    AgentForgeConfig,
+    load_config,
+    validate_module_configs,
+)
+from agentforge_core.production.exceptions import ModuleError
+from pydantic import ValidationError
+
+
+def register_config_cmd(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    """Attach the `config` subcommand + its `validate`/`show`/`schema`
+    children to the parent subparser action."""
+    config_parser = sub.add_parser(
+        "config",
+        help="Inspect and validate `agentforge.yaml`.",
+    )
+    config_sub = config_parser.add_subparsers(dest="config_target", required=True)
+
+    validate = config_sub.add_parser(
+        "validate",
+        help="Validate `agentforge.yaml` (schema + module schemas).",
+    )
+    _attach_load_args(validate)
+    validate.add_argument(
+        "--strict-modules",
+        action="store_true",
+        help=(
+            "Fail when a module the config references isn't installed. "
+            "Default: lenient — skip missing modules and only validate "
+            "the schema of installed ones."
+        ),
+    )
+    validate.set_defaults(_handler=_run_validate)
+
+    show = config_sub.add_parser(
+        "show",
+        help="Print the loaded config as YAML.",
+    )
+    _attach_load_args(show)
+    show_mode = show.add_mutually_exclusive_group()
+    show_mode.add_argument(
+        "--resolved",
+        action="store_true",
+        help=(
+            "Print after env-var interpolation + overrides (default). "
+            "Shows exactly what the agent will see."
+        ),
+    )
+    show_mode.add_argument(
+        "--raw",
+        action="store_true",
+        help="Print the raw YAML on disk, pre-interpolation.",
+    )
+    show.set_defaults(_handler=_run_show)
+
+    schema = config_sub.add_parser(
+        "schema",
+        help="Print the root config's JSON Schema (for IDE autocomplete).",
+    )
+    schema.add_argument(
+        "--indent",
+        type=int,
+        default=2,
+        help="JSON indent level (default 2).",
+    )
+    schema.set_defaults(_handler=_run_schema)
+
+
+def _attach_load_args(parser: argparse.ArgumentParser) -> None:
+    """Args shared by `validate` and `show` — point at a file, pick
+    an env layer, apply overrides."""
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=None,
+        help="Path to agentforge.yaml (default: $AGENTFORGE_CONFIG or ./agentforge.yaml).",
+    )
+    parser.add_argument(
+        "--env",
+        default=None,
+        help="Environment layer (selects agentforge.<env>.yaml overlay).",
+    )
+    parser.add_argument(
+        "--override",
+        action="append",
+        default=[],
+        metavar="DOTTED.PATH=VALUE",
+        help="Override a config value (repeatable).",
+    )
+
+
+def _run_validate(args: argparse.Namespace) -> int:
+    try:
+        cfg = load_config(args.path, env=args.env, overrides=args.override)
+    except ModuleError as exc:
+        sys.stderr.write(f"agentforge.yaml load failed: {exc}\n")
+        return 1
+    except ValidationError as exc:
+        _print_validation_errors(exc)
+        return 1
+    try:
+        validate_module_configs(cfg, strict=args.strict_modules)
+    except ModuleError as exc:
+        sys.stderr.write(f"module config validation failed: {exc}\n")
+        return 1
+    sys.stdout.write("OK\n")
+    return 0
+
+
+def _run_show(args: argparse.Namespace) -> int:
+    if args.raw:
+        return _show_raw(args)
+    try:
+        cfg = load_config(args.path, env=args.env, overrides=args.override)
+    except (ModuleError, ValidationError) as exc:
+        sys.stderr.write(f"agentforge.yaml load failed: {exc}\n")
+        return 1
+    payload = cfg.model_dump(mode="json")
+    sys.stdout.write(yaml.safe_dump(payload, sort_keys=False, default_flow_style=False))
+    return 0
+
+
+def _show_raw(args: argparse.Namespace) -> int:
+    path = args.path
+    if path is None:
+        env_path = os.environ.get("AGENTFORGE_CONFIG")
+        path = Path(env_path) if env_path else Path.cwd() / "agentforge.yaml"
+    if not Path(path).exists():
+        sys.stderr.write(f"no config file at {path}\n")
+        return 1
+    sys.stdout.write(Path(path).read_text())
+    return 0
+
+
+def _run_schema(args: argparse.Namespace) -> int:
+    schema = AgentForgeConfig.model_json_schema()
+    sys.stdout.write(json.dumps(schema, indent=args.indent) + "\n")
+    return 0
+
+
+def _print_validation_errors(exc: ValidationError) -> None:
+    """Render pydantic errors with their dotted YAML paths."""
+    sys.stderr.write("agentforge.yaml validation failed:\n")
+    for err in exc.errors(include_url=False):
+        loc = ".".join(str(p) for p in err["loc"])
+        sys.stderr.write(f"  {loc}: {err['msg']}\n")
+
+
+__all__: Sequence[str] = ["register_config_cmd"]

agentforge/cli/db_cmd.py

@@ -0,0 +1,262 @@
+"""`agentforge db` subcommands (feat-017 chunk 7).
+
+Routed to the active `MemoryStore`:
+
+    agentforge db migrate                  # call init_schema if present
+    agentforge db backup --to FILE|-       # JSONL dump of every claim
+    agentforge db restore --from FILE      # bulk put() from a JSONL file
+    agentforge db purge --older-than 30d   # delete by filter
+                       --run-id RUN_ID
+                       --category CAT
+    agentforge db query 'category:X agent:Y limit:50'
+
+`db migrate` is a no-op (info + exit 0) for drivers without an
+`init_schema` method (InMemoryStore, SqliteMemoryStore which creates
+its schema eagerly).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import re
+import sys
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.values.claim import Claim
+
+from agentforge.cli._build import build_memory_from_config
+
+
+def register_db_cmd(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    parser = sub.add_parser(
+        "db",
+        help="Operate on the configured memory store (migrate / backup / restore / purge / query).",
+    )
+    parser.add_argument("--path", type=Path, default=None)
+    parser.add_argument("--env", default=None)
+    parser.add_argument("--override", action="append", default=[])
+    db_sub = parser.add_subparsers(dest="db_command", required=True)
+
+    db_sub.add_parser(
+        "migrate",
+        help="Apply pending schema migrations (feat-024) or call init_schema fallback.",
+    )
+    db_sub.add_parser(
+        "migrate-status",
+        help="List applied + pending migrations for the configured store (feat-024).",
+    )
+
+    backup = db_sub.add_parser("backup", help="Dump every claim to JSONL.")
+    backup.add_argument("--to", required=True, help="Output path or '-' for stdout.")
+
+    restore = db_sub.add_parser("restore", help="Bulk put() claims from a JSONL file.")
+    restore.add_argument("--from", dest="src", required=True, help="Input path or '-'.")
+
+    purge = db_sub.add_parser("purge", help="Delete claims by filter.")
+    purge.add_argument("--older-than", default=None, help="Duration like 30d, 24h, 90m.")
+    purge.add_argument("--run-id", default=None)
+    purge.add_argument("--category", default=None)
+    purge.add_argument("--yes", action="store_true", help="Skip the confirmation prompt.")
+
+    query = db_sub.add_parser("query", help="Tiny DSL → MemoryStore.query.")
+    query.add_argument("dsl", help="Tokens like 'category:X agent:Y run_id:Z'.")
+    query.add_argument("--limit", type=int, default=100)
+    query.add_argument(
+        "--output-format",
+        choices=("rich", "json", "plain"),
+        default="plain",
+    )
+
+    parser.set_defaults(_handler=_db_handler)
+
+
+def _db_handler(args: argparse.Namespace) -> int:
+    return asyncio.run(_dispatch(args))
+
+
+async def _dispatch(args: argparse.Namespace) -> int:
+    from agentforge_core.config.loader import load_config  # noqa: PLC0415
+
+    config = load_config(args.path, env=args.env, overrides=list(args.override) or None)
+    memory = build_memory_from_config(config)
+    if memory is None:
+        sys.stderr.write("agentforge db: modules.memory must be configured.\n")
+        return 1
+
+    dispatch = {
+        "migrate": _do_migrate,
+        "migrate-status": _do_migrate_status,
+        "backup": _do_backup,
+        "restore": _do_restore,
+        "purge": _do_purge,
+        "query": _do_query,
+    }
+    handler = dispatch[args.db_command]
+    return await handler(memory, args)
+
+
+async def _do_migrate(memory: Any, args: argparse.Namespace) -> int:
+    """Apply pending migrations via the feat-024 framework when the
+    driver exposes a `migrator()` method; otherwise fall back to
+    legacy `init_schema()`."""
+    del args
+    migrator_factory = getattr(memory, "migrator", None)
+    if callable(migrator_factory):
+        migrator = migrator_factory()
+        applied = await migrator.apply_pending()
+        if not applied:
+            sys.stdout.write("  → schema up to date; no pending migrations.\n")
+        else:
+            for migration in applied:
+                sys.stdout.write(f"  → applied {migration.id}_{migration.name}\n")
+        return 0
+    init = getattr(memory, "init_schema", None)
+    if not callable(init):
+        sys.stdout.write(
+            "  → driver has no migrator()/init_schema(); nothing to migrate.\n",
+        )
+        return 0
+    await init()
+    sys.stdout.write("  → schema initialised (legacy init_schema path).\n")
+    return 0
+
+
+async def _do_migrate_status(memory: Any, args: argparse.Namespace) -> int:
+    """List applied + pending migrations for the configured store
+    (feat-024). Drivers without a `migrator()` method print a
+    diagnostic and exit 0."""
+    del args
+    migrator_factory = getattr(memory, "migrator", None)
+    if not callable(migrator_factory):
+        sys.stdout.write(
+            "  → driver has no migrator() method; cannot report status.\n",
+        )
+        return 0
+    migrator = migrator_factory()
+    statuses = await migrator.status()
+    if not statuses:
+        sys.stdout.write("  → no migrations bundled with this driver.\n")
+        return 0
+    for status in statuses:
+        if status.applied:
+            checksum_flag = "✓" if status.checksum_match else "✗"
+            sys.stdout.write(
+                f"  ✓ {status.migration.id}_{status.migration.name} "
+                f"(applied {status.applied_at}; checksum {checksum_flag})\n"
+            )
+        else:
+            sys.stdout.write(f"    {status.migration.id}_{status.migration.name} — pending\n")
+    return 0
+
+
+async def _do_backup(memory: Any, args: argparse.Namespace) -> int:
+    target = args.to
+    out_stream: Any = (
+        sys.stdout if target == "-" else Path(target).open("w", encoding="utf-8")  # noqa: SIM115, ASYNC230 — closed in finally
+    )
+    count = 0
+    try:
+        async for claim in memory.stream():
+            out_stream.write(claim.model_dump_json() + "\n")
+            count += 1
+    finally:
+        if target != "-":
+            out_stream.close()
+    sys.stderr.write(f"  → wrote {count} claims.\n")
+    return 0
+
+
+async def _do_restore(memory: Any, args: argparse.Namespace) -> int:
+    src = args.src
+    text = (
+        sys.stdin.read() if src == "-" else Path(src).read_text(encoding="utf-8")  # noqa: ASYNC240 — CLI one-shot
+    )
+    count = 0
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        await memory.put(Claim.model_validate_json(stripped))
+        count += 1
+    sys.stdout.write(f"  → restored {count} claims.\n")
+    return 0
+
+
+async def _do_purge(memory: Any, args: argparse.Namespace) -> int:
+    older_than = _parse_duration(args.older_than) if args.older_than else None
+    if args.run_id is None and args.category is None and older_than is None:
+        sys.stderr.write(
+            "agentforge db purge: pass at least one of --older-than / --run-id / --category.\n"
+        )
+        return 1
+    if not args.yes:
+        sys.stderr.write("Proceed? [y/N]: ")
+        sys.stderr.flush()
+        confirm = sys.stdin.readline().strip().lower()
+        if confirm not in {"y", "yes"}:
+            sys.stderr.write("cancelled.\n")
+            return 1
+    try:
+        removed = await memory.delete(
+            run_id=args.run_id,
+            older_than=older_than,
+            category=args.category,
+        )
+    except ModuleError as exc:
+        sys.stderr.write(f"agentforge db purge: {exc}\n")
+        return 1
+    sys.stdout.write(f"  → removed {removed} claims.\n")
+    return 0
+
+
+async def _do_query(memory: Any, args: argparse.Namespace) -> int:
+    try:
+        filters = _parse_dsl(args.dsl)
+    except ValueError as exc:
+        sys.stderr.write(f"agentforge db query: {exc}\n")
+        return 1
+    claims = await memory.query(limit=args.limit, **filters)
+    if args.output_format == "json":
+        print(json.dumps([c.model_dump(mode="json") for c in claims], indent=2))
+    else:
+        for c in claims:
+            print(f"{c.id}  {c.category:<20} run={c.run_id:<26} agent={c.agent}")
+    return 0
+
+
+_DURATION_RE = re.compile(r"^(\d+)([smhd])$")
+
+
+def _parse_duration(s: str) -> datetime:
+    m = _DURATION_RE.match(s)
+    if m is None:
+        msg = f"--older-than expects e.g. '30d', '24h', '15m'; got {s!r}."
+        raise ValueError(msg)
+    n, unit = int(m.group(1)), m.group(2)
+    seconds = {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit] * n
+    return datetime.now(UTC) - timedelta(seconds=seconds)
+
+
+_QUERY_KEYS = {"category", "agent", "project", "run_id"}
+
+
+def _parse_dsl(dsl: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for token in dsl.split():
+        if ":" not in token:
+            msg = f"token {token!r} not in key:value form."
+            raise ValueError(msg)
+        k, v = token.split(":", 1)
+        if k not in _QUERY_KEYS:
+            msg = f"unknown query key {k!r}; supported: {sorted(_QUERY_KEYS)}."
+            raise ValueError(msg)
+        out[k] = v
+    return out
+
+
+__all__ = ["register_db_cmd"]