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

ai_forge_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: ai-forge-cli
+Version: 0.1.2
+Summary: Context walker for the Forge L0-L5 spec system
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file

ai_forge_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,21 @@
+ai_forge_cli-0.1.2.dist-info/licenses/LICENSE,sha256=6rxKXRsWhsA9SO1zfWXd8jFE_9oKQgq_6DONh9YaANI,1070
+cli/__init__.py,sha256=1nlEjQxN41Hlmc-9GYy1ecLhfJMx5mCRYElym9Zu5RQ,84
+cli/__main__.py,sha256=Gbyw2xwlaGxJHGrtnTvbyeOw6wNhESZe56TxZy0WBNY,84
+cli/bundle.py,sha256=ftLO0DVYrW0h6EcaAtUI85cdkf3pJWzANLGlcTdkkas,4415
+cli/common.py,sha256=amidWJznK9d740tio3E6tpsT2jstmPRj_hASHK1fG_w,4419
+cli/forge.py,sha256=mMShjqxO270u1J-66QTbBwfZ5WeSKKSmbdHdMsnpFV0,1887
+cli/index.py,sha256=PFPDx2WaLpLQVCXhxJTCAysSESaVps7c4i0naBoDmzI,5823
+cli/walker.py,sha256=LVYgUzHVQejB3hyvcmyunAHFVyPYk5CYKwPOFRl-7Wc,28884
+cli/commands/__init__.py,sha256=qzYYjJxLxk_wXOtH_6Dzi-ImA6vOOxJJ3ImL9Ix7T28,754
+cli/commands/base.py,sha256=oi6syCWU8WmCFkZx6W0CthmfRdA2wX6m3MscRbyFaWQ,900
+cli/commands/context.py,sha256=rme5IMQ7EqJDz1HaMbY7iVcVj747SZ9bk1vfQDKThQU,2060
+cli/commands/find.py,sha256=iqsy0FqAVUEz-UcxkMrlhKxHAY1J07Kv8iJLCrRDE5I,3961
+cli/commands/init.py,sha256=5XcI5ucxDEQ9cDfaBH9XQMEtpdN-AsCkdLZzSlgodBA,16068
+cli/commands/inspect.py,sha256=gOba_hDbsK7wmyW5GnwVA7UqE4mFPZj6-Mbw6_zOk7w,4065
+cli/commands/list_cmd.py,sha256=2jRUynPk2doqh5MjWrGpR3AZm8Vx5lhWJ0KVL2rocys,2232
+cli/commands/update.py,sha256=Wckgw-OOxU-g63vlIS-AP-0kKe-vmTjfQE6iWFzPET4,2727
+ai_forge_cli-0.1.2.dist-info/METADATA,sha256=MCzW4kYE2e1CIFnY5QKNW9BbGyA_-3OiiOb6t38rlM8,207
+ai_forge_cli-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ai_forge_cli-0.1.2.dist-info/entry_points.txt,sha256=rUEWRSNZOi7Hs279NqYig10R5RJIirVP9PUk0LX7DvE,41
+ai_forge_cli-0.1.2.dist-info/top_level.txt,sha256=2ImG917oaVHlm0nP9oJE-Qrgs-fq_fGWgba2H1f8fpE,4
+ai_forge_cli-0.1.2.dist-info/RECORD,,

ai_forge_cli-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ai_forge_cli-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+forge = cli.forge:main

ai_forge_cli-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

ai_forge_cli-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+cli

cli/__init__.py

@@ -0,0 +1,2 @@
+"""Forge CLI — context walker for the L0-L5 spec system."""
+__version__ = "0.1.0"

cli/__main__.py

@@ -0,0 +1,4 @@
+from cli.forge import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli/bundle.py

@@ -0,0 +1,117 @@
+"""
+Bundle formatter — renders a walker output dict as YAML, JSON, or markdown.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import OrderedDict
+from typing import Any
+
+import yaml
+
+
+# Human-readable headers for each bundle section.
+_SECTION_HEADERS: dict[str, str] = {
+    "target":                     "Target",
+    "l0_registry_slice":          "L0 — Registry (sliced)",
+    "l1_conventions":             "L1 — Conventions",
+    "l2_module":                  "L2 — Owner Module",
+    "l2_entry_points":            "L2 — Invoking Entry Points",
+    "policies_applied":           "L2 — Policies Applied",
+    "policies":                   "L2 — Policies",
+    "shared_module_interfaces":   "L2 — Whitelisted Module Interfaces",
+    "l3_atom":                    "L3 — Target Atom",
+    "l3_artifact":                "L3 — Target Artifact",
+    "owned_atoms":                "L3 — Owned Atoms",
+    "owned_artifacts":            "L3 — Owned Artifacts",
+    "called_atom_signatures":     "L3 — Called Atom Signatures",
+    "producer_atom_signature":    "L3 — Producer Atom Signature",
+    "source_artifacts":           "L3 — Upstream Source Artifacts",
+    "consumer_signatures":        "L3 — Consumer Signatures",
+    "training_artifact":          "L3 — Training Artifact",
+    "handler_atoms":              "L3 — Handler Atoms",
+    "step_atom_signatures":       "L3 — Step Atom Signatures",
+    "l4_journey":                 "L4 — Target Journey",
+    "l4_orchestration":           "L4 — Target Orchestration",
+    "invoked_orchestrations":     "L4 — Invoked Orchestrations",
+    "l4_callers":                 "L4 — Callers (atoms consumed here)",
+    "l5_operations":              "L5 — Operations",
+}
+
+
+# Ensure PyYAML emits OrderedDicts in insertion order.
+def _represent_ordered_dict(dumper, data):
+    return dumper.represent_mapping("tag:yaml.org,2002:map", data.items())
+
+
+yaml.add_representer(OrderedDict, _represent_ordered_dict)
+
+
+def render(bundle: OrderedDict[str, Any], fmt: str = "yaml") -> str:
+    if fmt == "json":
+        return json.dumps(bundle, indent=2, default=_json_default)
+    if fmt == "markdown":
+        return _render_markdown(bundle)
+    return _render_yaml(bundle)
+
+
+def _render_yaml(bundle: OrderedDict[str, Any]) -> str:
+    parts: list[str] = []
+    target = bundle.get("target") or {}
+    parts.append("# " + "=" * 66)
+    parts.append(f"# FORGE CONTEXT BUNDLE")
+    parts.append(f"# target: {target.get('id', '<unknown>')}")
+    parts.append(f"# kind:   {target.get('kind', '<unknown>')}")
+    if target.get("atom_kind"):
+        parts.append(f"# atom_kind: {target['atom_kind']}")
+    parts.append("# " + "=" * 66)
+    parts.append("")
+
+    for key, value in bundle.items():
+        if key == "target":
+            continue
+        if value is None or (isinstance(value, (dict, list)) and not value):
+            continue
+        header = _SECTION_HEADERS.get(key, key)
+        parts.append("# " + "-" * 66)
+        parts.append(f"# {header}")
+        parts.append("# " + "-" * 66)
+        parts.append(yaml.dump({key: value}, sort_keys=False, allow_unicode=True,
+                               default_flow_style=False, width=100).rstrip())
+        parts.append("")
+
+    return "\n".join(parts) + "\n"
+
+
+def _render_markdown(bundle: OrderedDict[str, Any]) -> str:
+    target = bundle.get("target") or {}
+    parts: list[str] = [
+        f"# Forge context: `{target.get('id', '<unknown>')}`",
+        "",
+        f"- **kind**: `{target.get('kind', '<unknown>')}`",
+    ]
+    if target.get("atom_kind"):
+        parts.append(f"- **atom_kind**: `{target['atom_kind']}`")
+    parts.append("")
+
+    for key, value in bundle.items():
+        if key == "target":
+            continue
+        if value is None or (isinstance(value, (dict, list)) and not value):
+            continue
+        header = _SECTION_HEADERS.get(key, key)
+        parts.append(f"## {header}")
+        parts.append("")
+        parts.append("```yaml")
+        parts.append(yaml.dump({key: value}, sort_keys=False, allow_unicode=True,
+                               default_flow_style=False, width=100).rstrip())
+        parts.append("```")
+        parts.append("")
+    return "\n".join(parts)
+
+
+def _json_default(o: Any) -> Any:
+    if isinstance(o, OrderedDict):
+        return dict(o)
+    raise TypeError(f"Unserializable: {type(o)}")

cli/commands/__init__.py

@@ -0,0 +1,28 @@
+"""
+Command registry.
+
+To add a new command:
+  1. Create `cli/commands/<name>.py` exposing NAME, HELP, register, run
+     (see `base.py` for the contract, or copy any existing command as a
+     starting point).
+  2. Import it below and append to ALL_COMMANDS.
+
+That's it — `forge.py` auto-discovers every command in ALL_COMMANDS,
+builds its subparser, and wires dispatch via `args.handler`.
+"""
+
+from cli.commands import context as _context
+from cli.commands import find as _find
+from cli.commands import init as _init
+from cli.commands import inspect as _inspect
+from cli.commands import list_cmd as _list_cmd
+from cli.commands import update as _update
+
+ALL_COMMANDS = [
+    _init,
+    _update,
+    _context,
+    _list_cmd,
+    _inspect,
+    _find,
+]

cli/commands/base.py

@@ -0,0 +1,26 @@
+"""
+Command module contract.
+
+Every module in `cli.commands` must expose:
+
+  NAME: str
+      The subcommand name. Used as `forge <NAME> ...` on the CLI.
+
+  HELP: str
+      One-line help text shown in `forge --help`.
+
+  def register(sub: argparse._SubParsersAction) -> None:
+      Add this command's subparser with all its arguments to the
+      provided _SubParsersAction. MUST call
+      `parser.set_defaults(handler=run)` on the created subparser so
+      dispatch works without any if/elif chain in forge.main.
+
+  def run(args: argparse.Namespace) -> int:
+      Execute the command. Return an exit code:
+        0 = success
+        1 = usage error (unknown id, missing spec dir, etc.)
+        2 = soft warning (e.g., bundle emitted but has unresolved refs)
+
+Commands should reuse helpers from `cli.common` rather than reimplementing
+spec-dir loading, id suggestion, or description formatting.
+"""

cli/commands/context.py

@@ -0,0 +1,66 @@
+"""`forge context <id>` — build a full context bundle."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli import bundle as bundle_mod
+from cli import common
+from cli import index as index_mod
+from cli import walker
+
+NAME = "context"
+HELP = "Build a full implementation-ready context bundle for an id."
+DESCRIPTION = (
+    "Walks the spec dependency graph from <id> and emits everything "
+    "an agent needs to implement it: the target spec, referenced L0 "
+    "entries (sliced, not the whole registry), the owning module, "
+    "applicable policies, L1 conventions, L4 callers with derived "
+    "implications, and L5 operations."
+)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(NAME, help=HELP, description=DESCRIPTION)
+    p.add_argument(
+        "id",
+        help="Target id. Must be an atom, module, journey, flow, or artifact.",
+    )
+    common.add_spec_dir_arg(p)
+    p.add_argument(
+        "--format", choices=["yaml", "json", "markdown"], default="yaml",
+        help=(
+            "Output format. yaml (default) is most token-efficient. "
+            "json is most parseable. markdown wraps each section in a "
+            "heading + code block for pasting into a chat."
+        ),
+    )
+    p.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    idx, rc = common.load_index(args.spec_dir)
+    if rc != 0:
+        return rc
+
+    try:
+        index_mod.classify(idx, args.id)
+    except (KeyError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        common.suggest_similar(idx, args.id)
+        return 1
+
+    bundle, unresolved = walker.walk(idx, args.id)
+    output = bundle_mod.render(bundle, fmt=args.format)
+    sys.stdout.write(output)
+
+    if unresolved:
+        seen: set[str] = set()
+        uniq = [u for u in unresolved if not (u in seen or seen.add(u))]
+        print(f"\n# Unresolved references ({len(uniq)}):", file=sys.stderr)
+        for u in uniq:
+            print(f"#   - {u}", file=sys.stderr)
+        return 2
+
+    return 0

cli/commands/find.py

@@ -0,0 +1,122 @@
+"""`forge find <query>` — substring search across entity IDs and descriptions.
+
+Used as the scanning primitive for reuse-before-create probes in the
+forge-discover and forge-decompose skills. Agents call this before writing
+a new module / atom / type / error to surface potential matches, then
+present them advisorily to the human.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli import common
+
+NAME = "find"
+HELP = "Search for entities whose ID or description matches a query."
+DESCRIPTION = (
+    "Case-insensitive substring search across every entity in the spec "
+    "directory. Matches on ID (atom/module/type/error name) and on "
+    "description. Ranked output: entities matching on both ID and "
+    "description rank above single-match hits. Ties break by kind "
+    "priority (atoms/modules first) then alphabetical."
+)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(NAME, help=HELP, description=DESCRIPTION)
+    p.add_argument(
+        "query",
+        help="Search string. Case-insensitive substring match.",
+    )
+    p.add_argument(
+        "--kind", choices=common.ALL_KINDS, default=None,
+        help="Restrict results to a single kind (atom, module, type, error, etc.).",
+    )
+    p.add_argument(
+        "--limit", type=int, default=10,
+        help="Maximum number of matches to show. Default 10. Use 0 for no limit.",
+    )
+    common.add_spec_dir_arg(p)
+    p.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    idx, rc = common.load_index(args.spec_dir)
+    if rc != 0:
+        return rc
+
+    if not args.query.strip():
+        print("error: query must be non-empty", file=sys.stderr)
+        return 1
+
+    query_lower = args.query.lower()
+    kind_priority = {k: i for i, k in enumerate(common.ALL_KINDS)}
+
+    matches: list[tuple[int, int, str, str, list[str], str]] = []
+    # tuple shape: (-score, kind_priority, id, kind, signals, description)
+
+    for entry in idx.entries.values():
+        if args.kind and entry.kind != args.kind:
+            continue
+
+        id_match = query_lower in entry.id.lower()
+        description = common.full_description(entry.data)
+        desc_match = bool(description) and query_lower in description.lower()
+
+        if not (id_match or desc_match):
+            continue
+
+        signals: list[str] = []
+        if id_match:
+            signals.append("id")
+        if desc_match:
+            signals.append("desc")
+        score = len(signals)
+
+        matches.append((
+            -score,                                  # primary: higher score first (neg for asc sort)
+            kind_priority.get(entry.kind, 999),      # secondary: bundleable kinds first
+            entry.id,                                # tertiary: alphabetical
+            entry.kind,
+            signals,
+            description,
+        ))
+
+    matches.sort()
+
+    total = len(matches)
+    if total == 0:
+        print(f"# forge find {args.query!r} — no matches")
+        return 0
+
+    limit = args.limit if args.limit > 0 else total
+    shown = min(total, limit)
+
+    header = f"# forge find {args.query!r} — {total} match{'es' if total != 1 else ''}"
+    if shown < total:
+        header += f" (showing top {shown})"
+    print(header)
+    print()
+
+    # Column widths from the subset we'll actually render.
+    subset = matches[:shown]
+    id_width = max(len(m[2]) for m in subset)
+    kind_width = max(len(m[3]) for m in subset)
+
+    for _, _, entity_id, kind, signals, description in subset:
+        signal_str = f"[{'+'.join(signals)}]"
+        desc_preview = _preview(description, 80)
+        print(f"  {entity_id:<{id_width}}  {kind:<{kind_width}}  {signal_str:<10}  {desc_preview}")
+
+    return 0
+
+
+def _preview(text: str, max_chars: int) -> str:
+    if not text:
+        return ""
+    text = " ".join(text.strip().split())
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - 3] + "..."