ai-forge-cli 0.1.2__py3-none-any.whl

cli/commands/update.py

@@ -0,0 +1,78 @@
+"""`forge update` — refresh init-managed project assets in place."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from cli.commands import init as init_cmd
+
+NAME = "update"
+HELP = "Refresh init-managed project assets to the current Forge version."
+DESCRIPTION = (
+    "Refreshes the same project-managed assets that `forge init` lays down: "
+    "the spec directory structure, schema template symlinks, and project-local "
+    "skill symlinks. This command does not overwrite authored spec YAML files. "
+    "After refresh, it prints the recommended forge-audit follow-up."
+)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(NAME, help=HELP, description=DESCRIPTION)
+    p.add_argument(
+        "--spec-subdir", default=".forge",
+        help="Relative path from project root for the spec directory. Default: .forge",
+    )
+    p.add_argument(
+        "--skip-skills", action="store_true",
+        help="Skip project-local skill symlink refresh.",
+    )
+    p.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    project_root = Path.cwd()
+    spec_dir = project_root / args.spec_subdir
+
+    if spec_dir.exists() and not spec_dir.is_dir():
+        print(f"error: spec path exists and is not a directory: {spec_dir}", file=sys.stderr)
+        return 1
+    if not spec_dir.exists():
+        print(
+            f"error: no forge project detected at {spec_dir}/. "
+            "Run `forge init` first, or pass --spec-subdir if your project uses a custom spec dir.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        forge_repo, skills_src = init_cmd._resolve_forge_sources()
+    except FileNotFoundError as e:
+        lines = str(e).splitlines()
+        print(f"error: {lines[0]}", file=sys.stderr)
+        for line in lines[1:]:
+            print(line, file=sys.stderr)
+        return 1
+
+    print()
+    print(init_cmd._color(init_cmd._FIRE_PRIMARY, "▸ ") + init_cmd._bold("Forge update ") + init_cmd._dim(f"in {project_root}"))
+    print()
+
+    ok = init_cmd._color(init_cmd._OK_GREEN, "✓")
+
+    init_cmd._ensure_spec_structure(project_root, spec_dir, ok=ok)
+    init_cmd._install_schema_templates(spec_dir, forge_repo, force=True, ok=ok)
+
+    if not args.skip_skills:
+        init_cmd._install_skill_symlinks(project_root, skills_src, force=True, ok=ok)
+
+    print()
+    print(init_cmd._divider("Next step"))
+    print()
+    print(init_cmd._dim("  Run a compliance pass against the refreshed project:"))
+    print(f"    {init_cmd._bold(init_cmd._color(init_cmd._FIRE_PRIMARY, '/forge-audit'))}")
+    print(f"    {init_cmd._bold('\"Audit the specs before implementation\"')}")
+    print()
+
+    return 0

cli/common.py

@@ -0,0 +1,120 @@
+"""
+Shared helpers used by multiple command modules.
+
+Keep this module light: argument decorators, index loading, error
+messaging, and text utilities. Anything walker- or bundle-specific
+belongs in those modules.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from cli import index as index_mod
+
+
+# Kind constants used by `list` filter and `inspect` branching.
+BUNDLEABLE_KINDS: tuple[str, ...] = ("atom", "module", "journey", "flow", "artifact")
+ALL_KINDS: tuple[str, ...] = (
+    "atom", "module", "journey", "flow", "artifact",
+    "policy", "type", "error", "constant", "external_schema", "marker",
+)
+
+
+# ----------------------------------------------------------------------
+# Argparse decorators — standard flags reused by multiple commands.
+# ----------------------------------------------------------------------
+
+def add_spec_dir_arg(parser: argparse.ArgumentParser) -> None:
+    """Adds the standard --spec-dir flag. Resolution order is documented in
+    resolve_spec_dir: --spec-dir > $FORGE_SPEC_DIR > auto-discover."""
+    parser.add_argument(
+        "--spec-dir", default=None,
+        help="Path to spec directory. Overrides $FORGE_SPEC_DIR and auto-discovery.",
+    )
+
+
+# ----------------------------------------------------------------------
+# Index loading — wraps resolve + load with stderr error messaging.
+# ----------------------------------------------------------------------
+
+def load_index(spec_dir_arg: str | None) -> tuple[index_mod.Index | None, int]:
+    """Resolve spec dir and load an Index.
+
+    Returns (index, 0) on success or (None, 1) if resolution/loading fails.
+    The error is already printed to stderr by the time 1 is returned, so
+    callers can bail with the returned code directly.
+    """
+    try:
+        spec_dir = index_mod.resolve_spec_dir(spec_dir_arg)
+        idx = index_mod.load(spec_dir)
+        return idx, 0
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return None, 1
+
+
+# ----------------------------------------------------------------------
+# Id suggestion — used by commands that accept an id argument to help
+# users recover from typos.
+# ----------------------------------------------------------------------
+
+def suggest_similar(idx: index_mod.Index, target: str, limit: int = 5) -> None:
+    """Print up to `limit` ids close to `target`, best matches first.
+
+    Scoring prefers ids in the same namespace (shared dot-separated
+    prefix) over coincidental substring matches. Writes to stderr.
+    Silent if there are no reasonable candidates.
+    """
+    target_low = target.lower()
+    target_parts = target_low.split(".")
+
+    scored: list[tuple[int, str]] = []
+    for e in idx.entries.values():
+        eid_low = e.id.lower()
+        # Score = number of matching leading dot-segments (higher is better).
+        eid_parts = eid_low.split(".")
+        shared_prefix = 0
+        for a, b in zip(target_parts, eid_parts):
+            if a == b:
+                shared_prefix += 1
+            else:
+                break
+        substring_hit = target_low in eid_low or eid_low in target_low
+        if shared_prefix > 0 or substring_hit:
+            # Primary key: shared prefix segments; secondary: substring hit.
+            score = shared_prefix * 10 + (1 if substring_hit else 0)
+            scored.append((score, e.id))
+
+    if not scored:
+        return
+    scored.sort(key=lambda x: (-x[0], x[1]))
+    print("\nDid you mean:", file=sys.stderr)
+    for _, candidate in scored[:limit]:
+        print(f"  {candidate}", file=sys.stderr)
+
+
+# ----------------------------------------------------------------------
+# Description utilities — used by list and inspect.
+# ----------------------------------------------------------------------
+
+def full_description(data: Any) -> str:
+    """Full description text (uncapped) — newlines collapsed to spaces."""
+    if not isinstance(data, dict):
+        return ""
+    desc = data.get("description") or data.get("message") or ""
+    if not isinstance(desc, str):
+        return ""
+    return " ".join(desc.strip().split())
+
+
+def one_line_description(data: Any, max_chars: int = 80) -> str:
+    """Compact description capped for table rendering."""
+    text = full_description(data)
+    if not text:
+        return ""
+    if len(text) > max_chars:
+        return text[: max_chars - 3] + "..."
+    return text

cli/forge.py

@@ -0,0 +1,65 @@
+"""
+`forge` CLI entry point.
+
+This module is deliberately thin: it collects registered command
+modules, lets each build its own subparser, and dispatches via
+`args.handler`. Adding a new command requires zero edits here — see
+`cli.commands.__init__` for the registration point.
+"""
+
+from __future__ import annotations
+
+import argparse
+from importlib import metadata
+
+from cli.commands import ALL_COMMANDS
+
+
+def _version_string() -> str:
+    """Return the installed forge-cli package version."""
+    for dist_name in ("forge-ai-cli", "forge-cli"):
+        try:
+            return metadata.version(dist_name)
+        except metadata.PackageNotFoundError:
+            continue
+    return "unknown"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="forge",
+        description=(
+            "Context walker for the Forge L0-L5 spec system. "
+            "Assembles everything an agent needs to implement an atom, "
+            "module, journey, flow, or artifact into a single bundle."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  forge context atm.pay.charge_card --spec-dir src/example\n"
+            "  forge list --kind atom\n"
+            "  forge inspect PAY\n\n"
+            "Spec dir resolution: --spec-dir > $FORGE_SPEC_DIR > auto-discover."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"forge {_version_string()}",
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    for cmd in ALL_COMMANDS:
+        cmd.register(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli/index.py

@@ -0,0 +1,156 @@
+"""
+Spec directory loader and flat id index.
+
+Loads every YAML under a spec directory (L0 singleton, L1 singleton,
+L2 modules + policies, L3 atoms + artifacts, L4 flows + journeys,
+L5 singleton) and produces a flat dict keyed by id for O(1) lookup.
+
+L0 sub-sections (errors, types, constants, external_schemas) are
+exploded into individually-keyed entries so callers can ask for a
+single error code or type id without knowing the registry's shape.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class Entry:
+    id: str
+    kind: str           # atom|module|journey|flow|artifact|policy|type|error|constant|external_schema|marker
+    data: Any
+    file: Path | None = None
+
+
+@dataclass
+class Index:
+    spec_dir: Path
+    entries: dict[str, Entry] = field(default_factory=dict)
+    l0: dict[str, Any] = field(default_factory=dict)   # raw L0 registry
+    l1: dict[str, Any] = field(default_factory=dict)   # raw L1 conventions
+    l5: dict[str, Any] = field(default_factory=dict)   # raw L5 operations
+
+    def get(self, entity_id: str) -> Entry | None:
+        return self.entries.get(entity_id)
+
+    def by_kind(self, kind: str) -> list[Entry]:
+        return [e for e in self.entries.values() if e.kind == kind]
+
+    def naming_regex(self, key: str) -> re.Pattern[str] | None:
+        pat = self.l0.get("naming_ledger", {}).get(key)
+        return re.compile(pat) if pat else None
+
+
+# ---------- discovery ----------
+
+def resolve_spec_dir(explicit: str | None = None) -> Path:
+    """Resolve spec dir from explicit arg, env var, or auto-discover."""
+    if explicit:
+        return Path(explicit).expanduser().resolve()
+    env = os.environ.get("FORGE_SPEC_DIR")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    cwd = Path.cwd().resolve()
+    for candidate in [cwd, *cwd.parents]:
+        if (candidate / "L0_registry.yaml").is_file():
+            return candidate
+        if (candidate / ".forge" / "L0_registry.yaml").is_file():
+            return candidate / ".forge"
+        # Back-compat for projects initialized before the .forge convention:
+        if (candidate / "forge" / "docs" / "L0_registry.yaml").is_file():
+            return candidate / "forge" / "docs"
+        # Also check for a .forge/ with just the structure (L-layer dirs / templates)
+        # even if L0_registry.yaml hasn't been written yet (e.g., fresh init, not yet run discover).
+        if (candidate / ".forge").is_dir() and (candidate / ".forge" / "L2_modules").is_dir():
+            return candidate / ".forge"
+    raise FileNotFoundError(
+        "Cannot locate spec dir. Pass --spec-dir, set FORGE_SPEC_DIR, "
+        "or run `forge init` to bootstrap a new project."
+    )
+
+
+# ---------- loader ----------
+
+def load(spec_dir: Path) -> Index:
+    spec_dir = Path(spec_dir).resolve()
+    if not spec_dir.is_dir():
+        raise FileNotFoundError(f"Spec dir not found: {spec_dir}")
+
+    idx = Index(spec_dir=spec_dir)
+
+    _load_singleton(idx, spec_dir / "L0_registry.yaml", slot="l0")
+    _load_singleton(idx, spec_dir / "L1_conventions.yaml", slot="l1")
+    _load_singleton(idx, spec_dir / "L5_operations.yaml", slot="l5")
+
+    _explode_l0(idx)
+
+    _load_dir(idx, spec_dir / "L2_modules", kind="module", top_key="module")
+    _load_dir(idx, spec_dir / "L2_policies", kind="policy", top_key="policy")
+    _load_dir(idx, spec_dir / "L3_atoms", kind="atom", top_key="atom")
+    _load_dir(idx, spec_dir / "L3_artifacts", kind="artifact", top_key="artifact")
+    _load_dir(idx, spec_dir / "L4_flows", kind="flow", top_key="orchestration")
+    _load_dir(idx, spec_dir / "L4_journeys", kind="journey", top_key="journey")
+
+    return idx
+
+
+def _load_singleton(idx: Index, path: Path, slot: str) -> None:
+    if not path.is_file():
+        return
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    setattr(idx, slot, data)
+
+
+def _load_dir(idx: Index, directory: Path, kind: str, top_key: str) -> None:
+    if not directory.is_dir():
+        return
+    for path in sorted(directory.glob("*.yaml")):
+        with path.open("r", encoding="utf-8") as f:
+            doc = yaml.safe_load(f) or {}
+        body = doc.get(top_key) or {}
+        entity_id = body.get("id")
+        if not entity_id:
+            continue
+        idx.entries[entity_id] = Entry(id=entity_id, kind=kind, data=body, file=path)
+
+
+def _explode_l0(idx: Index) -> None:
+    """Index individual errors/types/constants/external_schemas/markers by id."""
+    l0 = idx.l0
+    for code, body in (l0.get("errors") or {}).items():
+        idx.entries[code] = Entry(id=code, kind="error", data=body)
+    for tid, body in (l0.get("types") or {}).items():
+        idx.entries[tid] = Entry(id=tid, kind="type", data=body)
+    for cid, body in (l0.get("constants") or {}).items():
+        idx.entries[cid] = Entry(id=cid, kind="constant", data=body)
+    for sid, body in (l0.get("external_schemas") or {}).items():
+        idx.entries[sid] = Entry(id=sid, kind="external_schema", data=body)
+    for marker, desc in (l0.get("side_effect_markers") or {}).items():
+        idx.entries[marker] = Entry(id=marker, kind="marker", data={"description": desc})
+
+
+# ---------- id dispatch ----------
+
+_BUNDLEABLE = {"atom", "module", "journey", "flow", "artifact"}
+
+
+def classify(idx: Index, entity_id: str) -> str:
+    """Return the kind for an id, raising if unknown or not bundleable."""
+    entry = idx.get(entity_id)
+    if entry is None:
+        raise KeyError(f"Unknown id: {entity_id}")
+    if entry.kind not in _BUNDLEABLE:
+        raise ValueError(
+            f"{entity_id} is a {entry.kind}; only {sorted(_BUNDLEABLE)} "
+            "can be bundled via `forge context`."
+        )
+    return entry.kind