pocketsync 0.10.0__py3-none-any.whl

pocketsync/cli/_commands/whoami.py

@@ -0,0 +1,106 @@
+"""``pocketsync 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 pocketsync import __version__
+from pocketsync.cli._output import emit_result
+
+_FALLBACK_NICK = "pocketsync"
+
+
+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)

pocketsync/cli/_errors.py

@@ -0,0 +1,42 @@
+"""CliError and exit-code policy (stable-contract).
+
+Every failure inside pocketsync raises :class:`CliError`. The
+top-level ``main()`` catches it, formats via :mod:`pocketsync.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 ``pocketsync 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,
+        }

pocketsync/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 pocketsync.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")

pocketsync/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 pocketsync.cli._errors import EXIT_USER_ERROR, CliError
+from pocketsync.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: pocketsync explain pocketsync",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

pocketsync/explain/catalog.py

@@ -0,0 +1,135 @@
+"""Markdown catalog for ``pocketsync explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
+and ``("pocketsync",)`` 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 = """\
+# pocketsync
+
+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
+
+- `pocketsync whoami` — identity probe from `culture.yaml`.
+- `pocketsync learn` — structured self-teaching prompt.
+- `pocketsync explain <path>` — markdown docs for any noun/verb.
+- `pocketsync overview` — descriptive snapshot of the agent.
+- `pocketsync doctor` — check the agent-identity invariants.
+- `pocketsync cli overview` — describe the CLI surface.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `pocketsync explain whoami`
+- `pocketsync explain doctor`
+"""
+
+_WHOAMI = """\
+# pocketsync whoami
+
+Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
+served model, and the package version. Read-only.
+
+## Usage
+
+    pocketsync whoami
+    pocketsync whoami --json
+"""
+
+_LEARN = """\
+# pocketsync learn
+
+Prints a structured self-teaching prompt covering purpose, command map,
+exit-code policy, `--json` support, and the `explain` pointer.
+
+## Usage
+
+    pocketsync learn
+    pocketsync learn --json
+"""
+
+_EXPLAIN = """\
+# pocketsync explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
+positional), `explain` is global and addressable by path.
+
+## Usage
+
+    pocketsync explain pocketsync
+    pocketsync explain whoami
+    pocketsync explain --json <path>
+"""
+
+_OVERVIEW = """\
+# pocketsync 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
+
+    pocketsync overview
+    pocketsync overview --json
+"""
+
+_DOCTOR = """\
+# pocketsync 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
+
+    pocketsync doctor
+    pocketsync doctor --json
+"""
+
+_CLI = """\
+# pocketsync cli
+
+Noun group for CLI-surface introspection. `cli overview` describes the CLI
+itself (distinct from the global `overview`, which describes the agent).
+
+## Usage
+
+    pocketsync cli overview
+    pocketsync cli overview --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("pocketsync",): _ROOT,
+    ("whoami",): _WHOAMI,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("overview",): _OVERVIEW,
+    ("doctor",): _DOCTOR,
+    ("cli",): _CLI,
+    ("cli", "overview"): _CLI,
+}

pocketsync-0.10.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: pocketsync
+Version: 0.10.0
+Summary: Sync Pocket voice-recorder recordings, transcripts (STT) and summaries from the Pocket cloud to local disk or S3 - a durable landing zone that culture-rules workflows fan out to anywhere.
+Project-URL: Homepage, https://github.com/agentculture/pocketsync
+Project-URL: Issues, https://github.com/agentculture/pocketsync/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
+
+# pocketsync
+
+Sync Pocket voice-recorder recordings, transcripts (STT) and summaries from the Pocket cloud to local disk or S3 - a durable landing zone that culture-rules workflows fan out to anywhere.
+
+## 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 pocketsync whoami  # identity from culture.yaml
+uv run pocketsync 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 `pocketsync/` and the `pocketsync`
+   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`, and adjust its
+   `gate` section (below) to your project's setup and test commands.
+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).
+
+## The `gate` section
+
+`culture.yaml` may carry a top-level `gate` section that declares how to set
+up and test this repo, so tooling (for example a PR-fixer that re-runs the
+checks before pushing) needs no per-repo knowledge:
+
+```yaml
+gate:
+  setup:
+  - [uv, sync]
+  test:
+  - [uv, run, pytest, -n, auto]
+```
+
+`setup` and `test` are each a list of commands, and each command is an argv
+list (never a shell string), run in order from the repo root. The values are
+configuration only; no tool supplies a default. Culture's loader ignores
+unknown top-level keys, so the section is safe alongside `agents`.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

pocketsync-0.10.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+pocketsync/__init__.py,sha256=NYpSctaj8iph2EHMoZ0ugFQPLBqSxMdOm1f7pMEJNfw,402
+pocketsync/__main__.py,sha256=yz078z6gJ4Tzm5IRPztoFfpLhTMJQeSIuhwa6A6sxDU,178
+pocketsync/cli/__init__.py,sha256=MXQPXQOh2kPCzalYVNdcVKhsPElLonr6n5O-0uAfApo,4982
+pocketsync/cli/_errors.py,sha256=z7XNf3wWDqb46ylPkDcg2z-LsYG79_EJ14o01ZgMO0c,1301
+pocketsync/cli/_output.py,sha256=Zdi9g_CcoioC0uxC7bbzi8cJnL0m6dl8bMSz0fZv1VI,1709
+pocketsync/cli/_commands/__init__.py,sha256=DqpfVkhBo7cj6eWOpSlwx1ag0nTbrYJkV8pnPgl2gyU,70
+pocketsync/cli/_commands/cli.py,sha256=4t_M8Y-DTTw-cnMhfpkaqnHeJpnYCiIoXSsnetZQg74,1677
+pocketsync/cli/_commands/doctor.py,sha256=0IOePf4PLmZQ0CNGai-3ZfpLM6wOR_rju38zxD_QwCs,7856
+pocketsync/cli/_commands/explain.py,sha256=nmwS10b3Fu9J49nTDIqTH_16CAot-QczihepTwJZAOM,1227
+pocketsync/cli/_commands/learn.py,sha256=NwcjMOOvXxk-WERbuxkYCVmEH9h94vfv82CQIBmsNsk,2999
+pocketsync/cli/_commands/overview.py,sha256=joS7fQMQCD9P8ZZCZd_BX3YXIquHPKYORidiQ2JXypc,3961
+pocketsync/cli/_commands/whoami.py,sha256=Xg9aZd9k4N0ayFlrQmOsrMLLs5DPhi9lo0NCdJeJgEE,3650
+pocketsync/explain/__init__.py,sha256=sdFX0sX4tAOC9zjD81mOtokbdFtU0QXas_PlWZAbJFg,704
+pocketsync/explain/catalog.py,sha256=kjkadO5QGAJgRzfXkBkCFrrzJgRfP_2GQ1-Zz2tDfUM,3559
+pocketsync-0.10.0.dist-info/METADATA,sha256=DX6o_WIj-8wTyY93xrQEzLdo_2pfWLar43pJckAv1p8,7059
+pocketsync-0.10.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pocketsync-0.10.0.dist-info/entry_points.txt,sha256=YdBMQkHq7Rx7SC2nzdIYq6a8cNFRsv28DTQLTr4PGvk,51
+pocketsync-0.10.0.dist-info/licenses/LICENSE,sha256=UTsio4-AMxNDoMcES3iMDOVbdrnTy1rQD7Be7zWjqcA,11340
+pocketsync-0.10.0.dist-info/RECORD,,

pocketsync-0.10.0.dist-info/WHEEL

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

pocketsync-0.10.0.dist-info/entry_points.txt

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