substack-cli 0.9.0__py3-none-any.whl

substack_cli/cli/_commands/whoami.py

@@ -0,0 +1,106 @@
+"""``substack-cli whoami`` — the smallest identity probe.
+
+Reports the agent's identity as declared in ``culture.yaml``: its nick
+(``suffix``), the backend it runs on, and the served model (if any) — plus the
+package version. Read-only; touches nothing but its own ``culture.yaml``.
+
+When you clone this template, rename the package and update ``culture.yaml`` —
+``whoami`` then reflects your new agent's identity with no code change.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from substack_cli import __version__
+from substack_cli.cli._output import emit_result
+
+_FALLBACK_NICK = "substack-cli"
+
+
+def find_culture_yaml() -> Path | None:
+    """Locate this agent's own ``culture.yaml`` by walking up from this module.
+
+    The identity must be the agent's own, not whatever ``culture.yaml`` happens
+    to sit in the caller's current working directory. In an editable / source
+    install, walking up from ``__file__`` finds the repo root; in a wheel
+    install no ``culture.yaml`` ships alongside the package and the caller falls
+    back to the literal defaults.
+    """
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "culture.yaml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_agent_fields() -> dict[str, str]:
+    """Return ``suffix``/``backend``/``model`` from the first agent block.
+
+    Parsed without a YAML dependency to keep the runtime deps empty. Reads
+    top-level ``key: value`` lines within the first agent entry; anything
+    fancier than the documented shape falls back to the defaults below.
+    """
+    fields = {"nick": _FALLBACK_NICK, "backend": "unknown", "model": "unknown"}
+    cfg = find_culture_yaml()
+    if cfg is None:
+        return fields
+    try:
+        text = cfg.read_text(encoding="utf-8")
+    except OSError:
+        return fields
+    seen_agent = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(("- suffix:", "suffix:")):
+            if seen_agent:  # second agent block — stop at the first
+                break
+            seen_agent = True
+            fields["nick"] = _scalar(stripped, "suffix")
+        elif seen_agent and stripped.startswith("backend:"):
+            fields["backend"] = _scalar(stripped, "backend")
+        elif seen_agent and stripped.startswith("model:"):
+            fields["model"] = _scalar(stripped, "model")
+    return fields
+
+
+def _scalar(line: str, key: str) -> str:
+    """Extract the scalar after ``key:`` from a ``culture.yaml`` line."""
+    _, _, value = line.partition(f"{key}:")
+    return value.strip().strip("'\"") or "unknown"
+
+
+def report() -> dict[str, object]:
+    fields = read_agent_fields()
+    return {
+        "nick": fields["nick"],
+        "version": __version__,
+        "backend": fields["backend"],
+        "model": fields["model"],
+    }
+
+
+def cmd_whoami(args: argparse.Namespace) -> None:
+    identity = report()
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(identity, json_mode=True)
+        return
+    text = (
+        f"nick: {identity['nick']}\n"
+        f"version: {identity['version']}\n"
+        f"backend: {identity['backend']}\n"
+        f"model: {identity['model']}"
+    )
+    emit_result(text, json_mode=False)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "whoami",
+        help="Report this agent's nick, version, backend, and served model.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

substack_cli/cli/_errors.py

@@ -0,0 +1,42 @@
+"""CliError and exit-code policy (stable-contract).
+
+Every failure inside substack-cli raises :class:`CliError`. The
+top-level ``main()`` catches it, formats via :mod:`substack_cli.cli._output`,
+and exits with :attr:`CliError.code`. This guarantees:
+
+* no Python traceback leaks to stderr (the agent-first error contract);
+* every error has a structured shape ``{code, message, remediation}``;
+* the exit-code policy is centralised in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy. Documented in ``substack-cli learn`` output.
+# 0      = success
+# 1      = user-input error (bad flag, missing required arg, unknown path)
+# 2      = environment / setup error (tool not installed, file unreadable)
+# 3+     = reserved for future categorisation
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class CliError(Exception):
+    """Structured error raised within the CLI; carries 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,
+        }

substack_cli/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 substack_cli.cli._errors import CliError
+
+
+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: CliError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a :class:`CliError` 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")

substack_cli/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 substack_cli.cli._errors import EXIT_USER_ERROR, CliError
+from substack_cli.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 CliError(
+        code=EXIT_USER_ERROR,
+        message=f"no explain entry for: {display}",
+        remediation="list entries with: substack-cli explain substack-cli",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

substack_cli/explain/catalog.py

@@ -0,0 +1,136 @@
+"""Markdown catalog for ``substack-cli explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
+and ``("substack-cli",)`` 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 = """\
+# substack-cli
+
+A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
+(cited from the teken `python-cli` reference), a mesh identity (`culture.yaml` +
+`CLAUDE.md`), the canonical guildmaster skill kit under `.claude/skills/`, and a
+buildable/deployable package baseline. Clone it, rename the package, edit
+`culture.yaml`, and you have a new agent.
+
+## Verbs
+
+- `substack-cli whoami` — identity probe from `culture.yaml`.
+- `substack-cli learn` — structured self-teaching prompt.
+- `substack-cli explain <path>` — markdown docs for any noun/verb.
+- `substack-cli overview` — descriptive snapshot of the agent.
+- `substack-cli doctor` — check the agent-identity invariants.
+- `substack-cli cli overview` — describe the CLI surface.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `substack-cli explain whoami`
+- `substack-cli explain doctor`
+"""
+
+_WHOAMI = """\
+# substack-cli whoami
+
+Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
+served model, and the package version. Read-only.
+
+## Usage
+
+    substack-cli whoami
+    substack-cli whoami --json
+"""
+
+_LEARN = """\
+# substack-cli learn
+
+Prints a structured self-teaching prompt covering purpose, command map,
+exit-code policy, `--json` support, and the `explain` pointer.
+
+## Usage
+
+    substack-cli learn
+    substack-cli learn --json
+"""
+
+_EXPLAIN = """\
+# substack-cli explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
+positional), `explain` is global and addressable by path.
+
+## Usage
+
+    substack-cli explain substack-cli
+    substack-cli explain whoami
+    substack-cli explain --json <path>
+"""
+
+_OVERVIEW = """\
+# substack-cli overview
+
+Read-only descriptive snapshot of the agent: identity (from `culture.yaml`), the
+verb surface, and the sibling-pattern artifacts the template carries. Accepts an
+ignored `target` so a stray path never hard-fails.
+
+## Usage
+
+    substack-cli overview
+    substack-cli overview --json
+"""
+
+_DOCTOR = """\
+# substack-cli doctor
+
+Checks the agent-identity invariants `steward doctor` verifies:
+prompt-file-present and backend-consistency (`claude` → `CLAUDE.md`), plus a
+skills-present check. Exits 1 when unhealthy.
+
+prompt-file-present requires the *resident* prompt the declared backend
+actually reads. Other harness prompt files recognized under the same backend
+name (`AGENTS.override.md`, `.pi/SYSTEM.md`, `QWEN.md`) belong to
+interactively available harnesses the mesh daemon never loads; they are
+reported by the informational harness-prompts check and never substituted.
+
+## Usage
+
+    substack-cli doctor
+    substack-cli doctor --json
+"""
+
+_CLI = """\
+# substack-cli cli
+
+Noun group for CLI-surface introspection. `cli overview` describes the CLI
+itself (distinct from the global `overview`, which describes the agent).
+
+## Usage
+
+    substack-cli cli overview
+    substack-cli cli overview --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("substack-cli",): _ROOT,
+    ("substack",): _ROOT,
+    ("whoami",): _WHOAMI,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("overview",): _OVERVIEW,
+    ("doctor",): _DOCTOR,
+    ("cli",): _CLI,
+    ("cli", "overview"): _CLI,
+}

substack_cli-0.9.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: substack-cli
+Version: 0.9.0
+Summary: Agent-first CLI to manage a Substack publication and account: publish and schedule posts, read posts and comments, run audience and post statistics, and manage subscribers. Unofficial community tool, not affiliated with Substack.
+Project-URL: Homepage, https://github.com/agentculture/substack-cli
+Project-URL: Issues, https://github.com/agentculture/substack-cli/issues
+Author: AgentCulture
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# substack-cli
+
+Agent-first CLI to manage a Substack publication and account: publish and schedule posts, read posts and comments, run audience and post statistics, and manage subscribers. Unofficial community tool, not affiliated with Substack.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  resident prompt file (`CLAUDE.md`, since this template runs
+  `backend: claude`). The mesh resident is one of **two separate
+  selections** over this clone — see
+  [Two selections, not one](#two-selections-not-one) below.
+- **Four harness prompt files**, one per agent harness, each read by exactly
+  one of them (see [Prompt files by harness](#prompt-files-by-harness) below).
+  All four harnesses are usable interactively regardless of which one
+  `culture.yaml` names as the mesh resident.
+- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
+  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Prompt files by harness
+
+Four harnesses, four root files, no shared base — each file is read by
+exactly one harness:
+
+| Harness | File(s) |
+|---------|---------|
+| Claude Code | [`CLAUDE.md`](CLAUDE.md) |
+| Pi / associate | [`AGENTS.override.md`](AGENTS.override.md) + [`.pi/SYSTEM.md`](.pi/SYSTEM.md) |
+| colleague | [`AGENTS.colleague.md`](AGENTS.colleague.md) |
+| Qwen Code | [`QWEN.md`](QWEN.md) |
+
+**Claude Code** — `CLAUDE.md` is the fullest write-up of the repo's
+conventions; read it first.
+
+**Pi / associate** — `AGENTS.override.md` replaces this directory's
+`AGENTS.md`/`CLAUDE.md` in Pi's context layer, so Pi does not inherit
+`CLAUDE.md`. `.pi/SYSTEM.md` replaces Pi's default system prompt with the
+non-coding `associate` identity (read/find/summarize only).
+
+**colleague** — colleague's prompt cascade is `AGENTS.md` →
+`AGENTS.colleague.md` → `AGENTS.colleague.<model>.md`. This repo ships only
+the middle layer: there is no `AGENTS.md` (a shared base across harnesses was
+considered and rejected) and no per-model override file.
+
+**Qwen Code** — Qwen Code reads `QWEN.md` and `AGENTS.md`; since there is no
+`AGENTS.md`, `QWEN.md` is its sole source of guidance.
+
+There is intentionally **no `AGENTS.md`** at the root — each harness gets an
+unrelated file rather than cascading from a shared base.
+
+## Two selections, not one
+
+It is tempting to read "switch harness" as one decision. It is actually two,
+and this template exists partly to keep them separate:
+
+1. **The interactive harness** — which binary you run (`claude`, `pi`,
+   `colleague`, `qwen`). `cd` into the clone and run any of them; all four
+   are live simultaneously, and none of them requires editing a file or
+   flipping a switch. A harness can be force-selected for one invocation
+   (e.g. a CI smoke check) without ever touching `culture.yaml` — see
+   [`docs/automation-contract.md`](docs/automation-contract.md).
+2. **The mesh resident** — the single `backend` `culture.yaml` declares,
+   which is what the Culture daemon starts and what `steward doctor`
+   checks. `guild harness use <name>` changes only this.
+
+`culture.yaml`'s `backend` affects (2) only. It never affects which harness
+you can invoke interactively in (1). See
+[`docs/harness-selection.md`](docs/harness-selection.md) for the full
+writeup, including who reads this config and why existing siblings are not
+retrofitted by this arc.
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run substack-cli whoami  # identity from culture.yaml
+uv run substack-cli learn   # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Make it your own
+
+1. Rename the package `substack_cli/` and the `substack-cli`
+   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
+   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
+   ~100 places, so list every occurrence first — see the `git grep` discovery
+   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+2. Edit `culture.yaml` with your `suffix` and `backend`.
+3. Rewrite `CLAUDE.md` for your agent and run `/init`. Rewrite the other three
+   harness files (`AGENTS.override.md` + `.pi/SYSTEM.md`, `AGENTS.colleague.md`,
+   `QWEN.md`) too if your agent uses those harnesses — don't let them drift out
+   of sync with `CLAUDE.md`.
+4. Re-vendor only the skills you need from guildmaster (see
+   [`docs/skill-sources.md`](docs/skill-sources.md)).
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
+the `cicd` PR lane, deploy setup).
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

substack_cli-0.9.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+substack_cli/__init__.py,sha256=mVRyVa6yeX2aqdyi7NrlPJA3V01BkJve5vkkuuWrk2c,406
+substack_cli/__main__.py,sha256=bYagIxRrQAwmYxYTY6sN1weaqhJwH60XMyNQCcPgd78,182
+substack_cli/cli/__init__.py,sha256=9B9ThdCOcBVXVc-deqXUG_Edcw9vm3gYA11stXLKiIs,5016
+substack_cli/cli/_errors.py,sha256=VFCJak9qVwkGzusUmBn6s0HNfyhozHvjkJxU7swEPRE,1307
+substack_cli/cli/_output.py,sha256=6cabSCl26xx7N0SE3-mgyd0MitvoJ4fXaUnx8SuKE24,1711
+substack_cli/cli/_commands/__init__.py,sha256=DqpfVkhBo7cj6eWOpSlwx1ag0nTbrYJkV8pnPgl2gyU,70
+substack_cli/cli/_commands/cli.py,sha256=frg0r-uiDzifLZG_4dhNpZSbe1bfG0-z85_9FkOhNWY,1689
+substack_cli/cli/_commands/doctor.py,sha256=YUep70WZFiaXKDVBkr3gCxRlgZSs4KlgNqoxKORGWho,7864
+substack_cli/cli/_commands/explain.py,sha256=RSjbTocY8EDtC4p9hX7-BDyw_CkklpwAVz84snu54qQ,1237
+substack_cli/cli/_commands/learn.py,sha256=aHBK3RjMUFtEF9HNrEs_yT8QbGR-n2w9G46-OcfJJnc,3027
+substack_cli/cli/_commands/overview.py,sha256=xy9fIpRbBmObcgchCngHtzdxGr22WtpLqbRELyYRlgw,3971
+substack_cli/cli/_commands/whoami.py,sha256=Q8Zmh_0Gwg7umgV_DSWgqovpVAiOsHry3h3OJ0Erl3w,3658
+substack_cli/explain/__init__.py,sha256=elAzIX4yqKIDUHo9VsTotcbOO_jVp9faB_ZHQZM_zes,712
+substack_cli/explain/catalog.py,sha256=v6cMCeGr3tSDCwj1V1FwzMUEiiZUTd-JD28Gt68GTZU,3649
+substack_cli-0.9.0.dist-info/METADATA,sha256=e7vz2eylrKNZU1eEpKOEXHHmmwqw7JvHFjjfeZwvQxo,6469
+substack_cli-0.9.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+substack_cli-0.9.0.dist-info/entry_points.txt,sha256=p39AC48B8VjDZseqOUIww6BQomRyYXoAwbAzhSXNDeM,51
+substack_cli-0.9.0.dist-info/licenses/LICENSE,sha256=UTsio4-AMxNDoMcES3iMDOVbdrnTy1rQD7Be7zWjqcA,11340
+substack_cli-0.9.0.dist-info/RECORD,,

substack_cli-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

substack_cli-0.9.0.dist-info/entry_points.txt

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