substack-cli 0.9.0__py3-none-any.whl

substack_cli/__init__.py

@@ -0,0 +1,13 @@
+"""substack-cli — agent-first CLI for an AgentCulture mesh agent."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("substack-cli")
+except PackageNotFoundError:  # pragma: no cover - editable install without metadata
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

substack_cli/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python -m substack_cli``."""
+
+from __future__ import annotations
+
+import sys
+
+from substack_cli.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

substack_cli/cli/__init__.py

@@ -0,0 +1,136 @@
+"""Unified CLI entry point for substack-cli.
+
+The agent-first global verbs (``whoami``, ``learn``, ``explain``, ``overview``,
+``doctor``) are registered here under :mod:`substack_cli.cli._commands`,
+alongside the ``cli`` noun group. Future noun groups register via their own
+``register()`` functions following the same pattern.
+
+Error propagation contract
+--------------------------
+Every handler raises :class:`substack_cli.cli._errors.CliError` on
+failure; ``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`substack_cli.cli._output`. Unknown exceptions are wrapped into a
+``CliError`` so no Python traceback leaks to stderr.
+
+Argparse errors (unknown verb, missing arg) also route through the structured
+format — ``_CliArgumentParser`` overrides ``.error()`` and the subparsers are
+built with ``parser_class=_CliArgumentParser``. Whether errors render as text or
+JSON depends on whether ``--json`` appears in the raw argv (:func:`main` sets
+``_json_hint`` before ``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from substack_cli import __version__
+from substack_cli.cli._errors import EXIT_USER_ERROR, CliError
+from substack_cli.cli._output import emit_error
+
+_ISSUES_URL = "https://github.com/agentculture/substack-cli/issues"
+
+
+class _CliArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`.
+
+    Argparse's default error handler writes ``prog: error: <msg>`` to stderr
+    and exits 2, skipping the CliError plumbing (and the ``hint:`` line agents
+    look for). This subclass emits the structured format and exits with
+    :attr:`EXIT_USER_ERROR`.
+
+    JSON mode: parse-time errors happen before ``args.json`` exists, so we rely
+    on a class-level ``_json_hint`` that :func:`main` pre-populates by scanning
+    raw argv for ``--json``. Shared across all subparser instances.
+    """
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = CliError(
+            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:
+    from substack_cli.cli._commands import cli as _cli_group
+    from substack_cli.cli._commands import doctor as _doctor_cmd
+    from substack_cli.cli._commands import explain as _explain_cmd
+    from substack_cli.cli._commands import learn as _learn_cmd
+    from substack_cli.cli._commands import overview as _overview_cmd
+    from substack_cli.cli._commands import whoami as _whoami_cmd
+
+    parser = _CliArgumentParser(
+        prog="substack-cli",
+        description="substack-cli — a clonable template for AgentCulture mesh agents.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    # parser_class propagates to every subparser so their .error() routes
+    # through _CliArgumentParser too.
+    sub = parser.add_subparsers(dest="command", parser_class=_CliArgumentParser)
+
+    _whoami_cmd.register(sub)
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _overview_cmd.register(sub)
+    _doctor_cmd.register(sub)
+    _cli_group.register(sub)
+    # Register your own noun groups here:
+    #   from substack_cli.cli._commands import my_noun as _my_noun_group
+    #   _my_noun_group.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    A handler may return ``None`` (success, exit 0) or an ``int`` exit code.
+    Failures MUST raise :class:`CliError`; 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 CliError 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 = CliError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation=f"file a bug at {_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.
+    _CliArgumentParser._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)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

substack_cli/cli/_commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules. Each exposes a ``register(sub)`` function."""

substack_cli/cli/_commands/cli.py

@@ -0,0 +1,43 @@
+"""``substack-cli cli`` — noun grouping CLI-surface introspection.
+
+Exists to satisfy the agent-first rubric's ``overview_cli_noun_exists`` check:
+any noun with action-verbs must also expose ``overview``. There are no
+action-verbs under ``cli`` today, but ``cli overview`` describes the CLI surface
+(distinct from the global ``overview``, which describes the agent).
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from substack_cli.cli._commands.overview import cli_sections, emit_overview
+
+
+def cmd_cli_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "substack-cli cli",
+        cli_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    # `substack-cli cli` with no sub-verb prints the noun's overview.
+    return cmd_cli_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "cli",
+        help="CLI-surface introspection (see 'substack-cli cli overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    # `p` is a _CliArgumentParser (the top-level subparsers were built with that
+    # parser_class); propagate it so `cli overview` parse errors route through
+    # the structured error contract instead of argparse's default stderr/exit 2.
+    noun_sub = p.add_subparsers(dest="cli_command", parser_class=type(p))
+    ov = noun_sub.add_parser("overview", help="Describe the substack-cli CLI surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_cli_overview)

substack_cli/cli/_commands/doctor.py

@@ -0,0 +1,194 @@
+"""``substack-cli doctor`` — check the agent-identity invariants.
+
+Mirrors the two invariants ``steward doctor`` verifies for a mesh agent:
+
+* **prompt-file-present** — the repo declares an agent in ``culture.yaml`` and
+  has the matching prompt file on disk;
+* **backend-consistency** — the declared ``backend`` is one this template
+  knows, and the *resident* prompt file that backend actually reads is on disk
+  (``claude`` → ``CLAUDE.md``, ``colleague`` → ``AGENTS.colleague.md``,
+  ``acp``/``codex``/``copilot`` → ``AGENTS.md``, ``gemini`` → ``GEMINI.md``).
+
+Additionally a **harness-prompts** info check reports which *other* recognized
+harness prompt files are present. Those files (``AGENTS.override.md``,
+``.pi/SYSTEM.md``, ``QWEN.md``) belong to interactively available harnesses
+that ride the same backend name; they are never accepted as substitutes for
+the resident prompt, because the Culture daemon does not read them.
+
+Plus a **skills-present** check (the vendored ``.claude/skills/`` kit). Read-only.
+
+Reports the rubric-shaped contract
+``{healthy, checks: [{id, passed, severity, message, remediation}]}`` so the
+agent-first rubric's bundle 7 passes. When run from a wheel install (no
+``culture.yaml`` alongside the package), it reports a single info check and
+exits 0 — there is nothing to diagnose.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from substack_cli.cli._commands.whoami import find_culture_yaml, read_agent_fields
+from substack_cli.cli._output import emit_result
+
+#: Shared by every AGENTS.md-reading backend (codex, acp, copilot).
+_AGENTS_MD = "AGENTS.md"
+
+# backend → every prompt file RECOGNIZED under that backend name.
+#
+# Values are tuples because four harnesses occupy only three backend names in
+# this template: Qwen Code runs on ``acp`` (QWEN.md), and associate/Pi runs on
+# ``colleague`` (AGENTS.override.md as context plus .pi/SYSTEM.md as the system
+# prompt). This is a *recognition* table — it answers "does some harness on
+# this backend read this file?", which is what tooling needs when it walks a
+# checkout and attributes files to backends.
+#
+# It is deliberately NOT the health check. See ``_RESIDENT_PROMPT`` below.
+#
+# This mirrors ``backends[*].prompt`` in
+# ``.claude/skills/agent-config/data/backend-fingerprints.yaml``;
+# ``tests/test_harness_registries.py`` asserts the two never drift apart.
+_PROMPT_FILE = {
+    "claude": ("CLAUDE.md",),
+    "colleague": ("AGENTS.colleague.md", "AGENTS.override.md", ".pi/SYSTEM.md"),
+    "acp": (_AGENTS_MD, "QWEN.md"),
+    "codex": (_AGENTS_MD,),
+    "copilot": (_AGENTS_MD,),
+    "gemini": ("GEMINI.md",),
+}
+
+# backend → the ONE prompt file the Culture daemon reads for a resident on
+# that backend. This is what ``prompt_file_present`` requires.
+#
+# The distinction from ``_PROMPT_FILE`` is load-bearing. Several files are
+# recognized under ``colleague`` and ``acp`` because *interactive harnesses*
+# ride those backend names — Pi reads ``AGENTS.override.md`` + ``.pi/SYSTEM.md``
+# and Qwen Code reads ``QWEN.md`` — but the mesh resident reads neither. A
+# clone declaring ``backend: colleague`` with only Pi's files on disk has no
+# resident prompt at all, and treating the harness files as interchangeable
+# alternatives let exactly that pass as healthy.
+_RESIDENT_PROMPT = {
+    "claude": "CLAUDE.md",
+    "colleague": "AGENTS.colleague.md",
+    "acp": _AGENTS_MD,
+    "codex": _AGENTS_MD,
+    "copilot": _AGENTS_MD,
+    "gemini": "GEMINI.md",
+}
+
+
+def _diagnose() -> dict[str, object]:
+    cfg = find_culture_yaml()
+    if cfg is None:
+        check = {
+            "id": "source_checkout",
+            "passed": True,
+            "severity": "info",
+            "message": "no culture.yaml found alongside the package; identity checks skipped",
+            "remediation": "",
+        }
+        return {"healthy": True, "checks": [check]}
+
+    root = cfg.parent
+    fields = read_agent_fields()
+    backend = fields["backend"]
+    checks: list[dict[str, object]] = []
+
+    # 1. backend-consistency: the RESIDENT prompt file for the declared
+    #    backend exists. Other harness prompt files recognized under the same
+    #    backend name are reported separately (check 2) and never substituted
+    #    here — the mesh daemon does not read them.
+    resident = _RESIDENT_PROMPT.get(backend)
+    if resident is None:
+        checks.append(
+            {
+                "id": "backend_consistency",
+                "passed": False,
+                "severity": "error",
+                "message": f"unknown backend '{backend}' in culture.yaml",
+                "remediation": f"set backend to one of: {', '.join(sorted(_RESIDENT_PROMPT))}",
+            }
+        )
+    else:
+        present = (root / resident).is_file()
+        checks.append(
+            {
+                "id": "prompt_file_present",
+                "passed": present,
+                "severity": "error",
+                "message": (
+                    f"backend '{backend}' reads {resident} as its resident prompt — "
+                    + ("present" if present else "missing")
+                ),
+                "remediation": "" if present else f"create {resident} at the repo root",
+            }
+        )
+
+        # 2. harness-prompts: report the other recognized prompt files on
+        #    disk for this backend. Informational — an interactively available
+        #    harness is not a health requirement, and its absence is not a
+        #    failure — but it must never stand in for the resident prompt.
+        others = [
+            name
+            for name in _PROMPT_FILE.get(backend, ())
+            if name != resident and (root / name).is_file()
+        ]
+        checks.append(
+            {
+                "id": "harness_prompts",
+                "passed": True,
+                "severity": "info",
+                "message": (
+                    "other harness prompt files on this backend: "
+                    + (", ".join(others) if others else "none")
+                    + " (not substitutes for the resident prompt)"
+                ),
+                "remediation": "",
+            }
+        )
+
+    # 3. skills-present: the vendored skill kit is on disk.
+    skills_dir = root / ".claude" / "skills"
+    has_skills = skills_dir.is_dir() and any(skills_dir.iterdir())
+    checks.append(
+        {
+            "id": "skills_present",
+            "passed": has_skills,
+            "severity": "warning",
+            "message": (
+                ".claude/skills/ vendored" if has_skills else ".claude/skills/ missing or empty"
+            ),
+            "remediation": (
+                "" if has_skills else "vendor the skill kit (see docs/skill-sources.md)"
+            ),
+        }
+    )
+
+    healthy = all(c["passed"] for c in checks)
+    return {"healthy": healthy, "checks": checks}
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    report = _diagnose()
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(report, json_mode=True)
+    else:
+        status = "healthy" if report["healthy"] else "unhealthy"
+        lines = [f"substack-cli doctor: {status}", ""]
+        for check in report["checks"]:
+            mark = "ok" if check["passed"] else "FAIL"
+            lines.append(f"[{mark}] {check['id']}: {check['message']}")
+            if not check["passed"] and check["remediation"]:
+                lines.append(f"  hint: {check['remediation']}")
+        emit_result("\n".join(lines), json_mode=False)
+    return 0 if report["healthy"] else 1
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "doctor",
+        help="Check the agent-identity invariants (prompt-file-present, backend-consistency).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_doctor)

substack_cli/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``substack-cli explain <path>...`` — global markdown catalog lookup (stable-contract).
+
+``explain`` is global (not nested under a noun). It takes zero or more path
+tokens and resolves them via the catalog in :mod:`substack_cli.explain`.
+Unknown paths raise :class:`CliError` with a remediation hint.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from substack_cli.cli._output import emit_result
+from substack_cli.explain import resolve
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    path = tuple(args.path) if args.path else ()
+    markdown = resolve(path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result({"path": list(path), "markdown": markdown}, json_mode=True)
+    else:
+        emit_result(markdown, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "explain",
+        help="Print markdown docs for a noun/verb path. Supports --json.",
+    )
+    p.add_argument(
+        "path",
+        nargs="*",
+        help="Command path tokens; empty = root (same as 'substack-cli').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

substack_cli/cli/_commands/learn.py

@@ -0,0 +1,88 @@
+"""``substack-cli learn`` — the learnability affordance.
+
+Prints a structured self-teaching prompt. Must satisfy the agent-first rubric:
+>=200 chars and mention purpose, command map, exit codes, --json, and explain.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from substack_cli import __version__
+from substack_cli.cli._output import emit_result
+
+_TEXT = """\
+substack-cli — a clonable template for AgentCulture mesh agents.
+
+Purpose
+-------
+Scaffold for a new Culture mesh agent: an agent-first CLI (cited from the teken
+`python-cli` reference), an identity (culture.yaml + CLAUDE.md), the canonical
+guildmaster skill kit under .claude/skills/, and a deploy/CI baseline. Clone it,
+rename the package, and edit culture.yaml to mint a new agent.
+
+Commands
+--------
+  substack-cli whoami             Identity from culture.yaml.
+  substack-cli learn              This self-teaching prompt.
+  substack-cli explain <path>...  Markdown docs for any noun/verb path.
+  substack-cli overview           Descriptive snapshot of the agent.
+  substack-cli doctor             Check the agent-identity invariants.
+  substack-cli cli overview       Describe the CLI surface itself.
+
+Machine-readable output
+-----------------------
+Every command supports --json. Errors in JSON mode emit
+{"code", "message", "remediation"} to stderr. Stdout and stderr never mix.
+
+Exit-code policy
+----------------
+  0 success
+  1 user-input error (bad flag, bad path, missing arg)
+  2 environment / setup error
+  3+ reserved
+
+More detail
+-----------
+  substack-cli explain substack-cli
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "substack-cli",
+        "version": __version__,
+        "purpose": "Clonable scaffold for a new AgentCulture mesh agent.",
+        "commands": [
+            {"path": ["whoami"], "summary": "Identity probe from culture.yaml."},
+            {"path": ["learn"], "summary": "Self-teaching prompt."},
+            {"path": ["explain"], "summary": "Markdown docs by path."},
+            {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
+            {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
+            {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
+        ],
+        "exit_codes": {
+            "0": "success",
+            "1": "user-input error",
+            "2": "environment/setup error",
+        },
+        "json_support": True,
+        "explain_pointer": "substack-cli 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)

substack_cli/cli/_commands/overview.py

@@ -0,0 +1,112 @@
+"""``substack-cli overview`` — read-only descriptive snapshot of the agent.
+
+Describes the agent to an agent reader: identity (from culture.yaml), the verb
+surface, and the sibling-pattern artifacts this template carries. The shared
+section/render helpers here are reused by the ``cli`` noun's ``overview`` (see
+:mod:`substack_cli.cli._commands.cli`).
+
+Descriptive verbs never hard-fail on a missing target path — an optional
+positional ``target`` is accepted and ignored (overview describes this agent,
+not an external target), so ``overview <bogus-path>`` still exits 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from substack_cli.cli._commands.whoami import report
+from substack_cli.cli._output import emit_result
+
+_ARTIFACTS = [
+    "culture.yaml + AGENTS.colleague.md — mesh identity (suffix + backend)",
+    ".claude/skills/ — the canonical guildmaster skill kit (cite-don't-import)",
+    "docs/skill-sources.md — skill provenance ledger",
+    "pyproject.toml + .github/workflows/ — buildable, deployable package baseline",
+]
+
+_VERBS = [
+    "whoami — identity probe (nick, version, backend, model)",
+    "learn — structured self-teaching prompt",
+    "explain <path> — markdown docs for a topic",
+    "overview — this descriptive snapshot",
+    "doctor — check the agent-identity invariants",
+]
+
+
+def agent_sections() -> list[dict[str, object]]:
+    """Sections describing the agent (used by the global verb)."""
+    ident = report()
+    return [
+        {
+            "title": "Identity",
+            "items": [
+                f"nick: {ident['nick']}",
+                f"version: {ident['version']}",
+                f"backend: {ident['backend']}",
+                f"model: {ident['model']}",
+            ],
+        },
+        {"title": "Verbs", "items": list(_VERBS)},
+        {"title": "Sibling-pattern artifacts", "items": list(_ARTIFACTS)},
+    ]
+
+
+def cli_sections() -> list[dict[str, object]]:
+    """Sections describing the CLI surface itself (used by `cli overview`)."""
+    return [
+        {
+            "title": "Verbs",
+            "items": list(_VERBS) + ["cli overview — describe the CLI surface (this command)"],
+        },
+        {
+            "title": "Conventions",
+            "items": [
+                "every command supports --json",
+                "results to stdout, errors/diagnostics to stderr (never mixed)",
+                "exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved",
+            ],
+        },
+    ]
+
+
+def render_text(subject: str, sections: list[dict[str, object]]) -> str:
+    lines = [f"# {subject}", ""]
+    for section in sections:
+        lines.append(f"## {section['title']}")
+        for item in section["items"]:
+            lines.append(f"- {item}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def emit_overview(subject: str, sections: list[dict[str, object]], *, json_mode: bool) -> None:
+    if json_mode:
+        emit_result({"subject": subject, "sections": sections}, json_mode=True)
+    else:
+        emit_result(render_text(subject, sections), json_mode=False)
+
+
+def cmd_overview(args: argparse.Namespace) -> int:
+    # `target` is accepted for rubric compatibility (descriptive verbs must not
+    # hard-fail on a missing path) but overview describes this agent itself.
+    emit_overview(
+        "substack-cli",
+        agent_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "overview",
+        help="Read-only descriptive snapshot of the agent (identity, verbs, artifacts).",
+    )
+    p.add_argument(
+        "target",
+        nargs="?",
+        help="Ignored — overview always describes this agent itself. Accepted so a "
+        "stray path argument never hard-fails.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_overview)