teken 0.8.0__py3-none-any.whl

teken/__init__.py

@@ -0,0 +1,13 @@
+"""teken — Agent First Interface scaffolder."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _v
+
+from teken import _brand
+
+try:
+    __version__ = _v(_brand.DIST)
+except PackageNotFoundError:  # editable install without metadata
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

teken/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running teken as ``python -m teken``."""
+
+import sys
+
+from teken.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

teken/_brand.py

@@ -0,0 +1,27 @@
+"""Single source of truth for brand-identifying strings.
+
+The project was renamed from ``afi`` to ``teken`` (Hebrew תֶּקֶן, "standard").
+Every user-facing reference to the program name, distribution, or dot-directory
+should read from here so a future rename is a one-line change. ``LEGACY_*``
+values keep the old ``afi`` surface working during the migration.
+"""
+
+PROG = "teken"  # primary CLI command + argparse prog
+LEGACY_PROG = "afi"  # deprecated alias command
+DIST = "teken"  # canonical PyPI distribution (importlib.metadata key)
+LEGACY_DIST = "afi-cli"  # wrapper distribution; self-doctor still recognises it
+DOTDIR = ".teken"  # primary dot-directory for cited references
+LEGACY_DOTDIR = ".afi"  # read-fallback dot-directory (existing trees)
+REPO_URL = "https://github.com/agentculture/teken"
+ISSUES_URL = f"{REPO_URL}/issues"
+
+__all__ = [
+    "PROG",
+    "LEGACY_PROG",
+    "DIST",
+    "LEGACY_DIST",
+    "DOTDIR",
+    "LEGACY_DOTDIR",
+    "REPO_URL",
+    "ISSUES_URL",
+]

teken/cite/__init__.py

@@ -0,0 +1,19 @@
+"""``teken cli cite`` engine — emit the agent-first reference tree.
+
+Public API:
+
+* :func:`emit_reference` — copy the reference tree for ``lang`` into
+  ``<target>/.teken/reference/<lang>-cli/`` (tokens left literal) and add
+  ``.teken/`` to ``.gitignore`` if missing.
+* :class:`CiteReport` — structured outcome (used by CLI for json/text output).
+* :data:`SUPPORTED_LANGS` — tuple of renderer names shipped today.
+
+The tree under :mod:`teken.cite.references` is package data; token substitution
+is *not* performed — the consuming agent does that.
+"""
+
+from __future__ import annotations
+
+from teken.cite._engine import SUPPORTED_LANGS, CiteReport, emit_reference
+
+__all__ = ["CiteReport", "SUPPORTED_LANGS", "emit_reference"]

teken/cite/_engine.py

@@ -0,0 +1,181 @@
+"""Cite engine — copies the reference tree and updates ``.gitignore``.
+
+The operation is safe by construction:
+
+* writes only under ``out`` (default ``<target>/.teken/reference/<lang>-cli/``);
+* ``out`` is required to resolve to a path strictly inside ``target_path`` —
+  this bounds the :func:`shutil.rmtree`/``copytree`` blast radius to the
+  caller's project, mitigating path-injection (S2083) from a hostile
+  ``--out`` override;
+* adds one line to ``<target>/.gitignore`` only when ``.teken/`` is absent;
+* touches nothing else in the target project;
+* re-running wipes and re-copies ``out`` — always the latest reference.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from teken import _brand
+from teken.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, AfiError
+
+SUPPORTED_LANGS = ("python",)
+
+GITIGNORE_ENTRY = f"{_brand.DOTDIR}/"
+
+_REFERENCES_DIR = Path(__file__).resolve().parent / "references"
+
+
+@dataclass(frozen=True)
+class CiteReport:
+    out: Path
+    written_count: int
+    gitignore_updated: bool
+
+    def describe_next_steps(self) -> list[str]:
+        return [
+            f"Read {self.out / 'AGENT.md'} — describes each file's role "
+            "(stable-contract vs shape-adapt) and lists the {{tokens}} to substitute.",
+            "Apply the pattern to your project: copy stable-contract files verbatim, "
+            "reshape shape-adapt files to your module layout, then substitute "
+            "{{project_name}}, {{slug}}, {{module}} throughout.",
+            "Run `teken cli verify .` to confirm the result satisfies the agent-first rubric.",
+        ]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "out": str(self.out),
+            "written_count": self.written_count,
+            "gitignore_updated": self.gitignore_updated,
+            "next_steps": self.describe_next_steps(),
+            "further_reading": {
+                "agent_md": str(self.out / "AGENT.md"),
+                "explain": ["teken explain cli cite", "teken explain cli verify"],
+            },
+        }
+
+
+def _validated_out(out: Path, target_path: Path) -> Path:
+    """Resolve ``out`` and verify it sits strictly inside ``target_path``.
+
+    This is the anti-path-injection gate. ``shutil.rmtree`` is destructive; we
+    only accept an ``out`` that resolves to a descendant of the already
+    resolved target directory. ``out == target_path`` is also rejected (would
+    wipe the whole project). Symlinks are followed before comparison.
+    """
+    resolved = out.resolve()
+    if resolved == target_path:
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message="--out cannot equal the target path (would wipe the project)",
+            remediation="pass a subpath inside the target, e.g. --out ./reference/",
+        )
+    try:
+        resolved.relative_to(target_path)
+    except ValueError as err:
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"--out must be inside the target path: {resolved} is not under {target_path}",
+            remediation="pick a path inside the target project, or omit --out for the default",
+        ) from err
+    return resolved
+
+
+def emit_reference(
+    target_path: Path,
+    *,
+    lang: str = "python",
+    out: Path | None = None,
+) -> CiteReport:
+    """Copy the ``lang`` reference tree into ``out`` and touch ``.gitignore``."""
+    if lang not in SUPPORTED_LANGS:
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"unsupported lang: {lang}",
+            remediation=f"supported langs: {', '.join(SUPPORTED_LANGS)}",
+        )
+    try:
+        target_path = target_path.resolve(strict=True)
+    except FileNotFoundError as err:
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"target path does not exist: {target_path}",
+            remediation="pass a path to an existing directory, or '.' for cwd",
+        ) from err
+    if not target_path.is_dir():
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"target path is not a directory: {target_path}",
+            remediation="pass a path to an existing directory, or '.' for cwd",
+        )
+
+    if out is None:
+        out = target_path / _brand.DOTDIR / "reference" / f"{lang}-cli"
+    # Canonicalise + validate: out must resolve inside target_path. Bounds the
+    # blast radius of the `shutil.rmtree(out)` call below (CWE-22 / S2083).
+    out = _validated_out(out, target_path)
+    if out.exists() and not out.is_dir():
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"--out exists but is not a directory: {out}",
+            remediation="remove that file or pick a different --out",
+        )
+
+    src = _REFERENCES_DIR / f"{lang}-cli"
+    if not src.is_dir():
+        raise AfiError(
+            code=EXIT_ENV_ERROR,
+            message=f"reference tree missing at {src}",
+            remediation="file a bug — reference data not packaged",
+        )
+
+    if out.exists():
+        shutil.rmtree(out)  # out has been validated to live inside target_path
+    out.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, out)
+
+    written = sum(1 for p in out.rglob("*") if p.is_file())
+    gitignore_updated = _ensure_gitignore_line(target_path)
+
+    return CiteReport(out=out, written_count=written, gitignore_updated=gitignore_updated)
+
+
+def _ensure_gitignore_line(project_root: Path) -> bool:
+    """Ensure ``GITIGNORE_ENTRY`` is present in ``<project_root>/.gitignore``.
+
+    Security (S2083 defence in depth): ``project_root`` must be an already
+    resolved, absolute directory. The callee *validates* that precondition
+    before touching the filesystem, then constructs the path using a literal
+    filename (``.gitignore``) — no user-controlled traversal component can
+    escape ``project_root``.
+
+    Returns ``True`` if the file was created or appended; ``False`` if the
+    line (or an equivalent glob) was already present.
+    """
+    if not project_root.is_absolute() or not project_root.is_dir():
+        raise AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"project_root is not a resolved directory: {project_root}",
+            remediation="pass an existing directory; '.' is resolved internally",
+        )
+    # Literal filename — the only path component we concatenate onto the
+    # pre-validated project_root. S2083 sanitiser pattern: validated root +
+    # static leaf = bounded write target.
+    gitignore = project_root / ".gitignore"
+
+    line = GITIGNORE_ENTRY
+    equivalents = {line, line.rstrip("/"), line + "**", line.rstrip("/") + "/**"}
+    if gitignore.is_file():
+        existing = {s.strip() for s in gitignore.read_text().splitlines()}
+        if existing & equivalents:
+            return False
+        body = gitignore.read_text()
+        if body and not body.endswith("\n"):
+            body += "\n"
+        body += line + "\n"
+        gitignore.write_text(body)
+        return True
+    gitignore.write_text(line + "\n")
+    return True

teken/cite/references/python-cli/AGENT.md

@@ -0,0 +1,98 @@
+# Agent-first CLI reference — integration guide
+
+You (the agent) are reading this because someone ran `teken cli cite` against
+their project. This folder contains the Python agent-first CLI pattern as a
+reference — `{{tokens}}` are **not substituted**. Your job is to apply the
+pattern to the host project on its own terms.
+
+## Tokens
+
+Substitute these throughout every file you integrate:
+
+| Token             | Meaning                                    | Example        |
+| ----------------- | ------------------------------------------ | -------------- |
+| `{{project_name}}` | The published package / CLI name.          | `acme-tool`    |
+| `{{slug}}`         | snake_case package slug (dashes→underscores). | `acme_tool`  |
+| `{{module}}`       | Importable top-level module (same as slug).   | `acme_tool`  |
+
+## File roles
+
+### stable-contract — copy verbatim, then token-substitute
+
+These files express the contract the rubric checks. Reshape them only if
+your project already has equivalents; otherwise copy byte-for-byte.
+
+- `{{slug}}/cli/_errors.py` — `AfiError`, exit-code policy.
+- `{{slug}}/cli/_output.py` — stdout/stderr split + `--json` helpers.
+- `{{slug}}/cli/_commands/explain.py` — the `explain` command.
+- `{{slug}}/explain/__init__.py` + `{{slug}}/explain/catalog.py` — catalog resolver.
+
+### shape-adapt — model the structure; rewrite to fit the host project
+
+These show the target shape but will almost certainly be reshaped to match
+the host project's existing module layout, prog name, and commands.
+
+- `{{slug}}/cli/__init__.py` — the parser + `_dispatch`. Reuse the
+  `_ArgumentParser` override and the try/except pattern verbatim; add your
+  own noun groups in the marked location.
+- `{{slug}}/cli/_commands/learn.py` — keep the structure (TEXT body + JSON
+  payload) but rewrite the content to describe the host tool.
+- `{{slug}}/explain/catalog.py` — rewrite entries for the host tool's
+  commands; keep the `()` / `("{{project_name}}",)` alias pattern.
+- `{{slug}}/__init__.py`, `{{slug}}/__main__.py` — usually already exist in
+  the host project; update only if missing.
+- `tests/test_cli.py` — merge into the host's test suite; adjust imports
+  and the `{{project_name}}` literal expectations.
+
+## Integration workflow (recommended)
+
+1. Read `MANIFEST.json` for a machine-readable file inventory.
+2. Copy the **stable-contract** files into the host project at the
+   equivalent paths under the host's package. Substitute tokens.
+3. Port the **shape-adapt** files: read them, take the structure, rewrite
+   content to match the host's naming and command surface.
+4. Wire the parser: import `learn` and `explain` modules and call their
+   `register(sub)` functions in the host's argparse setup.
+5. Ensure the host's top-level parser installs the `_ArgumentParser`
+   override so unknown-verb errors emit with a `hint:` line.
+6. Run `teken cli doctor .` from the host project to confirm the seven
+   rubric bundles pass.
+
+## Rubric bundles checked by `teken cli doctor`
+
+1. **Structure** — `pyproject.toml` with `[project.scripts]`, `tests/` dir,
+   `<tool> --help` exits 0, `main(argv) -> int` signature conforms.
+2. **Learnability** — `<tool> learn` exits 0, stdout ≥ 200 chars,
+   mentions purpose, commands, exit codes, `--json`, `explain`.
+3. **JSON** — `<tool> learn --json` is parseable; stderr clean on success;
+   `<tool> explain --json` works.
+4. **Errors** — bogus verb exits non-zero with a `hint:` line and no
+   Python traceback.
+5. **Explain** — `explain`, `explain <tool>`, and bogus-path-failure with
+   hint all work.
+6. **Overview** — `<tool> overview` and `<tool> cli overview` succeed;
+   `overview --json` carries `subject` + `sections` keys; missing target
+   paths fall back gracefully (descriptive verbs do not hard-fail).
+7. **Doctor** — `<tool> doctor` produces a non-empty report;
+   `<tool> doctor --json` carries `healthy` (bool) + `checks` (list);
+   each check entry has `id`, `passed`, `severity`, `message`; failed
+   checks supply a non-empty `remediation`.
+
+> Note: this reference tree currently scaffolds `learn` and `explain` only.
+> A target CLI must also implement `overview` (bundle 6) and `doctor`
+> (bundle 7) to pass the full rubric. Use teken's own implementations as
+> templates: `teken explain overview` and `teken explain doctor` describe the
+> contract; the source under `teken/overview/` and `teken/doctor/` shows the
+> shape. (Tracked: ship `overview.py` and `doctor.py` reference templates
+> in a follow-up cite refresh.)
+
+## After integration
+
+Delete this reference (`rm -rf .teken/reference/`) or re-run `teken cli cite` to
+refresh it. The `.teken/` entry in `.gitignore` keeps it out of commits.
+
+## Rubric audit verb
+
+Run `teken cli doctor .` from the host project to confirm the seven rubric
+bundles pass. `teken cli verify` is a deprecated alias for the same command
+and will be removed in v0.6.0.

teken/cite/references/python-cli/MANIFEST.json

@@ -0,0 +1,65 @@
+{
+  "lang": "python",
+  "tokens": {
+    "project_name": "Published package / CLI name (e.g. 'acme-tool').",
+    "slug": "snake_case package slug (dashes replaced by underscores).",
+    "module": "Importable top-level module name (same as slug)."
+  },
+  "files": [
+    {
+      "path": "{{slug}}/__init__.py",
+      "role": "shape-adapt",
+      "summary": "Top-level package init; exports __version__ via importlib.metadata."
+    },
+    {
+      "path": "{{slug}}/__main__.py",
+      "role": "shape-adapt",
+      "summary": "`python -m {{module}}` entry point; delegates to cli.main."
+    },
+    {
+      "path": "{{slug}}/cli/__init__.py",
+      "role": "shape-adapt",
+      "summary": "Parser + _dispatch. _ArgumentParser override and try/except are stable-contract sub-blocks within this file."
+    },
+    {
+      "path": "{{slug}}/cli/_errors.py",
+      "role": "stable-contract",
+      "summary": "AfiError dataclass + exit-code policy (EXIT_SUCCESS/USER/ENV)."
+    },
+    {
+      "path": "{{slug}}/cli/_output.py",
+      "role": "stable-contract",
+      "summary": "emit_result / emit_error / emit_diagnostic with stdout/stderr split."
+    },
+    {
+      "path": "{{slug}}/cli/_commands/__init__.py",
+      "role": "stable-contract",
+      "summary": "Empty package init."
+    },
+    {
+      "path": "{{slug}}/cli/_commands/learn.py",
+      "role": "shape-adapt",
+      "summary": "The learn command. Structure is stable; content describes the host tool."
+    },
+    {
+      "path": "{{slug}}/cli/_commands/explain.py",
+      "role": "stable-contract",
+      "summary": "The explain command; resolves against the explain catalog."
+    },
+    {
+      "path": "{{slug}}/explain/__init__.py",
+      "role": "stable-contract",
+      "summary": "resolve() + known_paths() against ENTRIES."
+    },
+    {
+      "path": "{{slug}}/explain/catalog.py",
+      "role": "shape-adapt",
+      "summary": "ENTRIES dict — rewrite for the host tool's command set."
+    },
+    {
+      "path": "tests/test_cli.py",
+      "role": "shape-adapt",
+      "summary": "Smoke tests for --version, learn, learn --json, explain, bogus-path-fails."
+    }
+  ]
+}

teken/cite/references/python-cli/tests/test_cli.py

@@ -0,0 +1,46 @@
+"""Smoke tests for {{project_name}}'s CLI (shape-adapt)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from {{module}} import __version__
+from {{module}}.cli import main
+
+
+def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_learn_exits_zero(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["learn"]) == 0
+    out = capsys.readouterr().out
+    assert len(out) >= 200
+    for marker in ["purpose", "commands", "exit", "--json", "explain"]:
+        assert marker.lower() in out.lower()
+
+
+def test_learn_json_parseable(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["learn", "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["tool"] == "{{project_name}}"
+
+
+def test_explain_self(capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["explain", "{{project_name}}"]) == 0
+    assert capsys.readouterr().out.startswith("#")
+
+
+def test_explain_unknown_path_fails_with_hint(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    rc = main(["explain", "zzz-not-a-real-noun"])
+    assert rc != 0
+    err = capsys.readouterr().err
+    assert "error:" in err
+    assert "hint:" in err

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

@@ -0,0 +1,12 @@
+"""{{project_name}} — agent-first CLI package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("{{project_name}}")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

teken/cite/references/python-cli/{{slug}}/__main__.py

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

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

@@ -0,0 +1,84 @@
+"""Unified CLI entry point for {{project_name}}.
+
+Noun-based command groups and globals are registered here. Top-level globals
+(``learn``, ``explain``) live under :mod:`{{module}}.cli._commands`; per-noun
+groups follow the same pattern.
+
+Error-propagation contract: every handler raises
+:class:`{{module}}.cli._errors.AfiError` on failure; :func:`main` catches it
+via :func:`_dispatch` and routes through :mod:`{{module}}.cli._output`.
+Unknown exceptions are wrapped so no Python traceback leaks.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from {{module}} import __version__
+from {{module}}.cli._commands import explain as _explain_cmd
+from {{module}}.cli._commands import learn as _learn_cmd
+from {{module}}.cli._errors import EXIT_USER_ERROR, AfiError
+from {{module}}.cli._output import emit_error
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that emits errors via our structured format."""
+
+    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=False)
+        raise SystemExit(err.code)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _ArgumentParser(
+        prog="{{project_name}}",
+        description="{{project_name}} — agent-first CLI.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    # Register noun groups here:
+    #   from {{module}}.cli._commands import my_noun as _my_noun_group
+    #   _my_noun_group.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        return 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
+        wrapped = AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+
+
+def main(argv: list[str] | None = None) -> int:
+    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())

teken/cite/references/python-cli/{{slug}}/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``{{project_name}} 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:`{{module}}.explain`.
+Unknown paths raise :class:`AfiError` with a remediation hint.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from {{module}}.cli._output import emit_result
+from {{module}}.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 (e.g. '{{project_name}} explain cli foo').",
+    )
+    p.add_argument(
+        "path",
+        nargs="*",
+        help="Command path tokens; empty = root (same as '{{project_name}}').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)