agentfront 0.9.0__py3-none-any.whl

agentfront/cite/references/python-cli/{{slug}}/cli/_commands/learn.py

@@ -0,0 +1,81 @@
+"""``{{project_name}} learn`` — the learnability affordance (shape-adapt).
+
+Update the text to describe {{project_name}} specifically. Must satisfy the
+agent-first rubric: >=200 chars and mention purpose, command map, exit
+codes, --json, explain.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from {{module}} import __version__
+from {{module}}.cli._output import emit_result
+
+_TEXT = """\
+{{project_name}} — <one-line tagline>.
+
+Purpose
+-------
+<Describe the tool's job. Write for an agent reader: concrete and terse.>
+
+Commands
+--------
+  {{project_name}} learn              Print this self-teaching prompt. Supports --json.
+  {{project_name}} explain <path>...  Print markdown docs for any noun/verb path.
+                              Supports --json.
+  # Add your noun-verb entries here.
+
+Machine-readable output
+-----------------------
+Every command that produces a listing or report supports --json. Errors in
+JSON mode emit {"code", "message", "remediation"} to stderr. Stdout and
+stderr are never mixed.
+
+Exit-code policy
+----------------
+  0 success
+  1 user-input error (bad flag, bad path, missing arg)
+  2 environment / setup error
+  3+ reserved
+
+More detail
+-----------
+  {{project_name}} explain {{project_name}}
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "{{project_name}}",
+        "version": __version__,
+        "purpose": "<describe purpose>",
+        "commands": [
+            {"path": ["learn"], "summary": "Self-teaching prompt."},
+            {"path": ["explain"], "summary": "Markdown docs by path."},
+        ],
+        "exit_codes": {
+            "0": "success",
+            "1": "user-input error",
+            "2": "environment/setup error",
+        },
+        "json_support": True,
+        "explain_pointer": "{{project_name}} explain <path>",
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    if getattr(args, "json", False):
+        emit_result(_as_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "learn",
+        help="Print a structured self-teaching prompt for agent consumers.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

agentfront/cite/references/python-cli/{{slug}}/cli/_errors.py

@@ -0,0 +1,41 @@
+"""AfiError and exit-code policy (stable-contract — copy verbatim).
+
+Every failure inside {{project_name}} raises :class:`AfiError`. The CLI entry
+point catches it and exits with :attr:`AfiError.code`. Guarantees:
+
+* no Python traceback leaks to stderr;
+* every error has shape ``{code, message, remediation}``;
+* the exit-code policy is centralised.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy (documented in ``{{project_name}} learn`` output).
+# 0  = success
+# 1  = user-input error (bad flag, bad path, missing arg)
+# 2  = environment / setup error
+# 3+ = reserved
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class AfiError(Exception):
+    """Structured error with a remediation hint for agents."""
+
+    code: int
+    message: str
+    remediation: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "remediation": self.remediation,
+        }

agentfront/cite/references/python-cli/{{slug}}/cli/_output.py

@@ -0,0 +1,53 @@
+"""stdout / stderr helpers with a strict split (stable-contract).
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from {{module}}.cli._errors import AfiError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (or ``stream``)."""
+    s = stream if stream is not None else sys.stdout
+    if json_mode:
+        json.dump(data, s, ensure_ascii=False)
+        s.write("\n")
+        return
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: AfiError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write an :class:`AfiError` to stderr.
+
+    Text mode renders as two lines when a remediation is present::
+
+        error: <message>
+        hint: <remediation>
+
+    The ``hint:`` prefix is required by the agent-first error rubric.
+    """
+    s = stream if stream is not None else sys.stderr
+    if json_mode:
+        json.dump(err.to_dict(), s, ensure_ascii=False)
+        s.write("\n")
+        return
+    s.write(f"error: {err.message}\n")
+    if err.remediation:
+        s.write(f"hint: {err.remediation}\n")
+
+
+def emit_diagnostic(message: str, *, stream: TextIO | None = None) -> None:
+    """Write a human diagnostic (progress, summary) to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")

agentfront/cite/references/python-cli/{{slug}}/explain/__init__.py

@@ -0,0 +1,24 @@
+"""Explain catalog — markdown keyed by command-path tuples (stable-contract).
+
+Every noun/verb registered in the CLI should have a catalog entry.
+"""
+
+from __future__ import annotations
+
+from {{module}}.cli._errors import EXIT_USER_ERROR, AfiError
+from {{module}}.explain.catalog import ENTRIES
+
+
+def resolve(path: tuple[str, ...]) -> str:
+    if path in ENTRIES:
+        return ENTRIES[path]
+    display = " ".join(path) if path else "<root>"
+    raise AfiError(
+        code=EXIT_USER_ERROR,
+        message=f"no explain entry for: {display}",
+        remediation="list known entries with: {{project_name}} explain {{project_name}}",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

agentfront/cite/references/python-cli/{{slug}}/explain/catalog.py

@@ -0,0 +1,66 @@
+"""Markdown catalog for ``{{project_name}} explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty
+tuple and ``("{{project_name}}",)`` both resolve to the root entry.
+
+Keep bodies self-contained: an agent reading one entry should get enough
+context without chaining reads.
+"""
+
+from __future__ import annotations
+
+_ROOT = """\
+# {{project_name}}
+
+<One-paragraph description of {{project_name}} aimed at an agent reader.>
+
+## Verbs
+
+- `{{project_name}} learn` — structured self-teaching prompt.
+- `{{project_name}} explain <path>` — markdown docs for any noun/verb.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `{{project_name}} explain learn`
+- `{{project_name}} explain explain`
+"""
+
+_LEARN = """\
+# {{project_name}} learn
+
+Prints a structured self-teaching prompt covering {{project_name}}'s purpose,
+command map, exit-code policy, `--json` support, and `explain` pointer.
+
+## Usage
+
+    {{project_name}} learn
+    {{project_name}} learn --json
+"""
+
+_EXPLAIN = """\
+# {{project_name}} explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help`
+(terse, positional), `explain` is global and addressable by path.
+
+## Usage
+
+    {{project_name}} explain {{project_name}}
+    {{project_name}} explain learn
+    {{project_name}} explain --json <path>
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("{{project_name}}",): _ROOT,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+}

agentfront/cli/__init__.py

@@ -0,0 +1,160 @@
+"""Unified CLI entry point for agentfront.
+
+Noun-based command groups and globals are registered here. Top-level globals
+(``learn``, ``explain``) live under :mod:`agentfront.cli._commands`; per-noun groups
+(``cli``, later ``mcp``, ``site``) are registered via their own ``register()``
+functions following the same pattern.
+
+Error propagation contract
+--------------------------
+Every handler raises :class:`agentfront.cli._errors.AfiError` on failure; the
+top-level ``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`agentfront.cli._output`. Unknown exceptions are wrapped into an ``AfiError``
+so no Python traceback leaks to stderr.
+
+Argparse errors (unknown verb, missing required arg) also route through our
+structured format — ``_AgentfrontArgumentParser`` overrides ``.error()``. The
+subparsers are built with ``parser_class=_AgentfrontArgumentParser`` so subparser
+errors follow the same path. Whether the error is emitted as text or JSON
+depends on whether ``--json`` appears in the raw argv (:func:`main` sets
+``_AgentfrontArgumentParser._json_hint`` before ``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from agentfront import __version__, _brand
+from agentfront.cli._errors import EXIT_USER_ERROR, AfiError
+from agentfront.cli._output import emit_error
+
+# Note: _commands submodules are imported lazily inside :func:`_build_parser`
+# to avoid a circular dependency. agentfront.cite._engine imports agentfront.cli._errors;
+# eagerly loading agentfront.cli._commands.cli (which imports agentfront.cite) at module
+# init would create a cycle when agentfront.cite is the first-touched package.
+
+
+class _AgentfrontArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`.
+
+    Argparse's default error handler writes ``prog: error: <msg>`` to stderr
+    and exits with code 2. That skips our AfiError plumbing and — crucially —
+    produces no ``hint:`` line, which would make agentfront itself fail the rubric's
+    error-propagation bundle. This subclass emits our structured error format
+    instead and exits with :attr:`EXIT_USER_ERROR`.
+
+    JSON mode: parse-time errors happen before ``args.json`` is populated, so
+    we rely on a class-level ``_json_hint`` that :func:`main` pre-populates
+    by scanning the raw argv for ``--json`` / ``--json=…``. Best-effort and
+    shared across all subparser instances (argparse's subparser factory
+    produces instances of the class but doesn't thread state).
+    """
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = AfiError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=type(self)._json_hint)
+        raise SystemExit(err.code)
+
+
+def _argv_has_json(argv: list[str] | None) -> bool:
+    tokens = argv if argv is not None else sys.argv[1:]
+    return any(t == "--json" or t.startswith("--json=") for t in tokens)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # Deferred imports (see module-level note): avoids agentfront.cite ↔ agentfront.cli cycle.
+    from agentfront.cli._commands import cli as _cli_group
+    from agentfront.cli._commands import doctor as _doctor_cmd
+    from agentfront.cli._commands import explain as _explain_cmd
+    from agentfront.cli._commands import learn as _learn_cmd
+    from agentfront.cli._commands import overview as _overview_cmd
+
+    parser = _AgentfrontArgumentParser(
+        prog=_brand.PROG,
+        description=f"{_brand.PROG} — Agent First Interface scaffolder",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    # parser_class propagates to every subparser so their .error() routes
+    # through _AgentfrontArgumentParser too. Without this, `agentfront cli bogus --foo`
+    # would hit argparse's default error path (no hint: line, wrong code).
+    sub = parser.add_subparsers(dest="command", parser_class=_AgentfrontArgumentParser)
+
+    # Globals (top-level, not nested under a noun).
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _overview_cmd.register(sub)
+    _doctor_cmd.register(sub)
+
+    # Noun groups.
+    _cli_group.register(sub)
+    # Future noun groups (mcp, site) will register here in v0.4 / v0.5.
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    Handler protocol: a handler may return ``None`` (treated as success,
+    exit 0) or an ``int`` (used directly as the exit code). Failures MUST
+    raise :class:`AfiError`; any other exception is wrapped into one so no
+    Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except AfiError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort; wrap and route cleanly
+        wrapped = AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation=f"file a bug at {_brand.ISSUES_URL}",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Pre-parse peek so argparse-level errors honour --json.
+    _AgentfrontArgumentParser._json_hint = _argv_has_json(argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return _dispatch(args)
+
+
+def main_teken_alias(argv: list[str] | None = None) -> int:
+    """Entry point for the deprecated ``teken`` command.
+
+    The project was renamed ``teken`` → ``agentfront``. The ``teken`` console script is
+    retained as an alias; it prints a one-line deprecation note to **stderr**
+    (never stdout, so ``--json`` output stays clean) and forwards to :func:`main`.
+    """
+    print(
+        f"deprecated: the '{_brand.LEGACY_PROG}' command is now '{_brand.PROG}'; "
+        f"'{_brand.LEGACY_PROG}' will be removed in a future release.",
+        file=sys.stderr,
+    )
+    return main(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentfront/cli/_commands/cli.py

@@ -0,0 +1,198 @@
+"""The ``cli`` noun group — verbs ``cite``, ``doctor``, ``overview``.
+
+``agentfront cli cite``     — drop the agent-first CLI reference tree into the target
+                       project under ``.agentfront/reference/<lang>-cli/``.
+``agentfront cli doctor``   — run the seven-bundle rubric against a target CLI
+                       and surface inconsistencies with actionable remediation
+                       (replaces ``agentfront cli verify``; ``--fix`` applies any
+                       auto-fixable handlers).
+``agentfront cli overview`` — read-only descriptive snapshot of a target CLI.
+
+``agentfront cli verify`` is kept as a deprecated alias that forwards to
+``cli doctor`` for one minor cycle; removed in v0.6.0.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from agentfront.cite import SUPPORTED_LANGS, emit_reference
+from agentfront.cli._commands.doctor import cmd_cli_doctor, cmd_cli_verify_deprecated
+from agentfront.cli._output import emit_result
+from agentfront.overview import build as build_overview
+from agentfront.overview import to_json_dict, to_markdown
+
+_JSON_HELP = "Emit structured JSON."
+_PATH_HELP = "Target project path (default: .)."
+_STRICT_HELP = "Treat warnings as failures (non-zero exit on any not-passed check)."
+
+
+def cmd_cite(args: argparse.Namespace) -> None:
+    """Handler for ``agentfront cli cite``.
+
+    Returns ``None`` on success (treated as ``EXIT_SUCCESS`` by
+    :func:`agentfront.cli._dispatch`); every failure path raises
+    :class:`AfiError`.
+    """
+    target_path = Path(args.path).resolve()
+    lang = args.lang
+    out = Path(args.out).resolve() if args.out else None
+    report = emit_reference(target_path, lang=lang, out=out)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(report.to_dict(), json_mode=True)
+        return
+
+    lines = [
+        f"Wrote {report.written_count} files to {report.out}",
+        (
+            "Added `.agentfront/` to .gitignore"
+            if report.gitignore_updated
+            else ".gitignore already ignores `.agentfront/`"
+        ),
+        "",
+        "Next steps:",
+    ]
+    for i, step in enumerate(report.describe_next_steps(), start=1):
+        lines.append(f"  {i}. {step}")
+    lines.extend(
+        [
+            "",
+            "For details on any step:  agentfront explain cli cite",
+            "For the rubric itself:    agentfront explain cli doctor",
+        ]
+    )
+    emit_result("\n".join(lines), json_mode=False)
+
+
+def cmd_cli_overview(args: argparse.Namespace) -> int:
+    """Handler for ``agentfront cli overview [path]``.
+
+    Read-only descriptive snapshot. If ``path`` is missing or points at a
+    project without a detectable CLI surface, emits the overview of agentfront's
+    own scaffolded template (the "zero-target default").
+    """
+    raw = getattr(args, "path", None)
+    path: Path | None = Path(raw).resolve() if raw else None
+    report = build_overview("cli", path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(to_json_dict(report), json_mode=True)
+    else:
+        emit_result(to_markdown(report), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    cli_parser = sub.add_parser(
+        "cli",
+        help="CLI-related commands: cite a reference tree, doctor against the rubric.",
+    )
+    cli_sub = cli_parser.add_subparsers(dest="cli_command")
+
+    cite = cli_sub.add_parser(
+        "cite",
+        help="Emit the agent-first CLI reference tree into <path>/.agentfront/reference/.",
+    )
+    cite.add_argument("path", nargs="?", default=".", help=_PATH_HELP)
+    cite.add_argument(
+        "--lang",
+        default="python",
+        choices=list(SUPPORTED_LANGS),
+        help="Reference language (default: python).",
+    )
+    cite.add_argument(
+        "--out",
+        default=None,
+        help="Override output directory (default: <path>/.agentfront/reference/<lang>-cli/).",
+    )
+    cite.add_argument("--json", action="store_true", help=_JSON_HELP)
+    cite.set_defaults(func=cmd_cite)
+
+    doctor = cli_sub.add_parser(
+        "doctor",
+        help=(
+            "Audit the CLI at <path> against the seven-bundle agent-first rubric "
+            "and surface remediations; --fix applies auto-fixable ones."
+        ),
+    )
+    # Default kept as None (not "."): the cwd fallback lives in cmd_cli_doctor
+    # so we can tell "no args" from "explicit path" and reject `--package`
+    # combined with an explicit path.
+    doctor.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help=_PATH_HELP + " Omit and pass --package to audit by distribution name.",
+    )
+    doctor.add_argument(
+        "--package",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Audit an editable-installed distribution by name (looks up "
+            "its source root via PEP 610 direct_url.json). Mutually "
+            "exclusive with the path positional."
+        ),
+    )
+    doctor.add_argument("--json", action="store_true", help=_JSON_HELP)
+    # --fix and --dry-run are alternatives: --dry-run previews what --fix
+    # would do. Mutually exclusive at the argparse layer so passing both
+    # gives a clear error instead of silent precedence.
+    fix_group = doctor.add_mutually_exclusive_group()
+    fix_group.add_argument(
+        "--fix",
+        action="store_true",
+        help="Apply auto-fixable remediations.",
+    )
+    fix_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        dest="dry_run",
+        help="Preview which fixes would be applied without mutating.",
+    )
+    doctor.add_argument(
+        "--strict",
+        action="store_true",
+        help=_STRICT_HELP,
+    )
+    doctor.set_defaults(func=cmd_cli_doctor)
+
+    # Deprecated alias for one minor cycle. Mirror the v0.4 verify shape so
+    # CI and scripts that call `agentfront cli verify .` keep working; the deprecation
+    # diagnostic is emitted by cmd_cli_verify_deprecated to stderr.
+    verify = cli_sub.add_parser(
+        "verify",
+        help="(Deprecated) Alias for `agentfront cli doctor`. Removed in v0.6.0.",
+    )
+    verify.add_argument("path", nargs="?", default=".", help=_PATH_HELP)
+    verify.add_argument("--json", action="store_true", help=_JSON_HELP)
+    verify.add_argument(
+        "--strict",
+        action="store_true",
+        help=_STRICT_HELP,
+    )
+    verify.set_defaults(func=cmd_cli_verify_deprecated)
+
+    overview = cli_sub.add_parser(
+        "overview",
+        help="Read-only descriptive snapshot of the CLI at <path> (defaults: agentfront template).",
+    )
+    overview.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help=(
+            "Target project path. If omitted (or the target has no CLI surface), "
+            "describe agentfront's default scaffolded template."
+        ),
+    )
+    overview.add_argument("--json", action="store_true", help=_JSON_HELP)
+    overview.set_defaults(func=cmd_cli_overview)
+
+    def _no_verb(_args: argparse.Namespace) -> int:
+        cli_parser.print_help()
+        return 0
+
+    cli_parser.set_defaults(func=_no_verb)