devague 0.3.2__py3-none-any.whl

devague/__init__.py

@@ -0,0 +1,11 @@
+"""devague — turns a vague feature idea into a buildable spec by working backwards."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _v
+
+try:
+    __version__ = _v("devague")
+except PackageNotFoundError:  # pragma: no cover  — editable install without metadata
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

devague/__main__.py

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

devague/cli/__init__.py

@@ -0,0 +1,123 @@
+"""Unified CLI entry point for devague.
+
+Error-propagation contract: every handler raises
+:class:`devague.cli._errors.DevagueError` on failure; ``main()`` catches it
+via :func:`_dispatch` and routes through :mod:`devague.cli._output`. Unknown
+exceptions are wrapped into a ``DevagueError`` so no Python traceback leaks.
+
+Argparse errors (unknown verb, missing required arg) also route through the
+structured format — :class:`_DevagueArgumentParser` overrides ``.error()``.
+Whether errors render as text or JSON depends on whether ``--json`` appears in
+the raw argv (:func:`main` sets ``_DevagueArgumentParser._json_hint`` before
+``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from devague import __version__
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._output import emit_error
+
+
+class _DevagueArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`."""
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = DevagueError(
+            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:
+    parser = _DevagueArgumentParser(
+        prog="devague",
+        description="devague — turns a vague idea into a buildable spec by working backwards.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", parser_class=_DevagueArgumentParser)
+
+    from devague.cli._commands import capture as _capture_cmd
+    from devague.cli._commands import confirm as _confirm_cmd
+    from devague.cli._commands import converge as _converge_cmd
+    from devague.cli._commands import explain as _explain_cmd
+    from devague.cli._commands import export as _export_cmd
+    from devague.cli._commands import interrogate as _interrogate_cmd
+    from devague.cli._commands import learn as _learn_cmd
+    from devague.cli._commands import list_frames as _list_cmd
+    from devague.cli._commands import new as _new_cmd
+    from devague.cli._commands import park as _park_cmd
+    from devague.cli._commands import reject as _reject_cmd
+    from devague.cli._commands import show as _show_cmd
+
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _new_cmd.register(sub)
+    _capture_cmd.register(sub)
+    _interrogate_cmd.register(sub)
+    _confirm_cmd.register(sub)
+    _reject_cmd.register(sub)
+    _park_cmd.register(sub)
+    _converge_cmd.register(sub)
+    _export_cmd.register(sub)
+    _show_cmd.register(sub)
+    _list_cmd.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`` (treated as success, exit 0) or an ``int``
+    used directly as the exit code. Failures MUST raise :class:`DevagueError`;
+    any other exception is wrapped so no Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except DevagueError 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 = DevagueError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/devague/issues",
+        )
+        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:
+    _DevagueArgumentParser._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())

devague/cli/_commands/capture.py

@@ -0,0 +1,31 @@
+"""``devague capture`` — record and classify a claim."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.frame import CLAIM_KINDS
+
+
+def cmd_capture(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    claim = frame.add_claim(args.kind, args.text, origin=args.origin)
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"id": claim.id, "kind": claim.kind, "status": claim.status}, json_mode=True)
+    else:
+        emit_result(f"captured {claim.id} ({claim.kind}, {claim.status})", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("capture", help="Record and classify a claim.")
+    p.add_argument("text", help="The claim text.")
+    p.add_argument("--kind", required=True, choices=CLAIM_KINDS, help="Claim kind.")
+    p.add_argument("--origin", choices=("user", "llm"), default="user", help="Who proposed it.")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_capture)

devague/cli/_commands/confirm.py

@@ -0,0 +1,38 @@
+"""``devague confirm`` — confirm a claim or honesty condition (user-only transition)."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+
+
+def _transition(args: argparse.Namespace, status: str) -> int:
+    frame = resolve(args.frame)
+    if not frame.set_status(args.id, status):
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            f"no such claim or honesty condition: {args.id}",
+            "run 'devague show'",
+        )
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"id": args.id, "status": status}, json_mode=True)
+    else:
+        emit_result(f"{args.id} -> {status}", json_mode=False)
+    return 0
+
+
+def cmd_confirm(args: argparse.Namespace) -> int:
+    return _transition(args, "confirmed")
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("confirm", help="Confirm a claim or honesty condition.")
+    p.add_argument("id", help="Claim id (c*) or honesty id (h*).")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_confirm)

devague/cli/_commands/converge.py

@@ -0,0 +1,37 @@
+"""``devague converge`` — evaluate the convergence gate."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.convergence import evaluate
+
+
+def cmd_converge(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    result = evaluate(frame)
+    if result.passed and frame.status == "drafting":
+        frame.status = "converged"
+        store.save(frame)
+    elif not result.passed and frame.status == "converged":
+        frame.status = "drafting"
+        store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"passed": result.passed, "missing": result.missing}, json_mode=True)
+    elif result.passed:
+        emit_result("converged ✓", json_mode=False)
+    else:
+        emit_result(
+            "not converged:\n" + "\n".join(f"  - {m}" for m in result.missing), json_mode=False
+        )
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("converge", help="Check whether the frame can export a spec.")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_converge)

devague/cli/_commands/explain.py

@@ -0,0 +1,31 @@
+"""``devague explain <move>`` — print docs for a single move."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague.cli._commands.learn import MOVES
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._output import emit_result
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    desc = MOVES.get(args.move)
+    if desc is None:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            f"unknown move: {args.move}",
+            f"available moves: {', '.join(MOVES)}",
+        )
+    if getattr(args, "json", False):
+        emit_result({"move": args.move, "description": desc}, json_mode=True)
+    else:
+        emit_result(f"{args.move}: {desc}", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("explain", help="Explain a devague move.")
+    p.add_argument("move", help="A move name (e.g. converge).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

devague/cli/_commands/export.py

@@ -0,0 +1,49 @@
+"""``devague export`` — write the buildable spec, only if the frame has converged."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from devague import render, store
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.convergence import evaluate
+
+SPECS_DIR = Path("docs/specs")
+
+
+def cmd_export(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    result = evaluate(frame)
+    if not result.passed:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            "frame has not converged; cannot export",
+            "resolve: " + "; ".join(result.missing),
+        )
+    text = render.render(frame, args.format)
+    SPECS_DIR.mkdir(parents=True, exist_ok=True)
+    out_path = SPECS_DIR / f"{frame.slug}.md"
+    out_path.write_text(text, encoding="utf-8")
+    frame.status = "exported"
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"path": str(out_path), "format": args.format}, json_mode=True)
+    else:
+        emit_result(f"exported spec to {out_path}", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("export", help="Export the buildable spec (requires convergence).")
+    p.add_argument(
+        "--format",
+        default="spec-md",
+        choices=("spec-md",),
+        help="Renderer format (default: spec-md).",
+    )
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_export)

devague/cli/_commands/interrogate.py

@@ -0,0 +1,66 @@
+"""``devague interrogate`` — pressure-test a claim with honesty conditions / hard questions."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._errors import EXIT_USER_ERROR, DevagueError
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+
+
+def cmd_interrogate(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    claim = frame.find_claim(args.claim_id)
+    if claim is None:
+        raise DevagueError(EXIT_USER_ERROR, f"no such claim: {args.claim_id}", "run 'devague show'")
+    added: list[dict] = []
+    if args.honesty:
+        h = frame.add_honesty(claim, args.honesty, origin=args.origin)
+        added.append({"kind": "honesty", "id": h.id, "status": h.status})
+    if args.risk:
+        q = frame.add_hard_question(claim, f"risk: {args.risk}", blocking=False)
+        added.append({"kind": "hard_question", "id": q.id, "status": "open"})
+    if args.hard_question:
+        q = frame.add_hard_question(claim, args.hard_question, blocking=args.blocking)
+        added.append(
+            {"kind": "hard_question", "id": q.id, "status": "blocking" if q.blocking else "open"}
+        )
+    if args.contradicts:
+        q = frame.add_hard_question(claim, f"contradiction with {args.contradicts}?", blocking=True)
+        added.append({"kind": "hard_question", "id": q.id, "status": "blocking"})
+    if not added:
+        raise DevagueError(
+            EXIT_USER_ERROR,
+            "nothing to interrogate",
+            "pass --honesty / --hard-question / --risk / --contradicts",
+        )
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"claim": claim.id, "added": added}, json_mode=True)
+    else:
+        emit_result(
+            f"interrogated {claim.id}: " + ", ".join(f"{a['kind']} {a['id']}" for a in added),
+            json_mode=False,
+        )
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("interrogate", help="Attach honesty conditions / hard questions to a claim.")
+    p.add_argument("claim_id", help="Claim id (e.g. c1).")
+    p.add_argument("--honesty", help="An honesty condition (what must be true).")
+    p.add_argument("--hard-question", dest="hard_question", help="A hard question.")
+    p.add_argument("--risk", help="A risk (recorded as a non-blocking hard question).")
+    p.add_argument("--contradicts", help="Claim id this contradicts (records a blocking question).")
+    p.add_argument("--blocking", action="store_true", help="Mark the hard question blocking.")
+    p.add_argument(
+        "--origin",
+        choices=("user", "llm"),
+        default="llm",
+        help="Who proposed the honesty condition.",
+    )
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_interrogate)

devague/cli/_commands/learn.py

@@ -0,0 +1,88 @@
+"""``devague learn`` — teach the working-backwards method and the moves."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import __version__
+from devague.cli._output import emit_result
+
+MOVES = {
+    "new": "Start a frame from the announcement (pretend it shipped).",
+    "capture": "Record and classify a claim (audience, after_state, boundary, ...).",
+    "interrogate": "Pressure-test a claim: honesty conditions, hard questions, contradictions.",
+    "confirm": "Confirm a claim or honesty condition (user-only — no fabricated rigor).",
+    "reject": "Reject a claim or honesty condition.",
+    "park": "Move uncertainty into first-class open vagueness instead of forcing an answer.",
+    "converge": "Check whether the frame is solid enough to export a spec.",
+    "export": "Write the buildable spec — only once the frame converges.",
+    "show": "Render the Announcement Frame.",
+    "list": "List frames.",
+}
+
+FIRST_QUESTION = "What's the announcement?"
+SUPPORTING_PROMPT = (
+    "Pretend this shipped successfully. What would you announce to users, "
+    "teammates, or yourself?"
+)
+
+# The canonical guided sequence (devague#4). The engine is move-driven, not a
+# rigid wizard — this is the recommended arc, with the move that advances each.
+STAGES = [
+    ("Announcement", "what are we saying shipped?", "new"),
+    ("Audience", "who needs this?", "capture --kind audience"),
+    ("After", "what changed for them?", "capture --kind after_state"),
+    ("Matter", "why is it worth doing?", "capture --kind why_it_matters"),
+    ("Before", "what pain made this necessary?", "capture --kind before_state"),
+    ("Honest", "what must be true for the announcement to be honest?", "interrogate --honesty"),
+    ("FAQ", "what hard questions remain?", "interrogate --hard-question"),
+    ("Boundaries", "what are we not promising?", "capture --kind boundary"),
+    ("Success", "how will we know?", "capture --kind success_signal"),
+    ("Spec", "what should be built?", "converge -> export"),
+]
+
+_TEXT = (
+    "devague turns a vague idea into a buildable spec by working backwards.\n\n"
+    f"First question: {FIRST_QUESTION}\n"
+    f"  {SUPPORTING_PROMPT}\n\n"
+    "Start from that announcement, then build an Announcement Frame by capturing\n"
+    "claims, interrogating them, parking what's still vague, and converging.\n"
+    "The arc emerges from the moves; it is not a fixed wizard. You (the agent)\n"
+    "choose the next move; devague tracks state. LLM-proposed claims and honesty\n"
+    "conditions stay 'proposed' until the user confirms them.\n\n"
+    "Guided stages (the recommended sequence — drive them with the moves):\n"
+    + "\n".join(
+        f"  {i:>2}. {name:<13} {prompt}  [{move}]"
+        for i, (name, prompt, move) in enumerate(STAGES, 1)
+    )
+    + "\n\nMoves:\n"
+    + "\n".join(f"  {name:<11} {desc}" for name, desc in MOVES.items())
+)
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    if getattr(args, "json", False):
+        emit_result(
+            {
+                "tool": "devague",
+                "version": __version__,
+                "first_question": FIRST_QUESTION,
+                "supporting_prompt": SUPPORTING_PROMPT,
+                "stages": [
+                    {"step": i, "name": name, "prompt": prompt, "move": move}
+                    for i, (name, prompt, move) in enumerate(STAGES, 1)
+                ],
+                "moves": list(MOVES),
+                "summary": _TEXT,
+            },
+            json_mode=True,
+        )
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("learn", help="Teach devague's working-backwards method.")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

devague/cli/_commands/list_frames.py

@@ -0,0 +1,27 @@
+"""``devague list`` — list frames and mark the current one."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._output import emit_result
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    slugs = store.list_slugs()
+    current = store.current_slug()
+    if getattr(args, "json", False):
+        emit_result({"frames": slugs, "current": current}, json_mode=True)
+    elif not slugs:
+        emit_result("no frames yet", json_mode=False)
+    else:
+        lines = [("* " if s == current else "  ") + s for s in slugs]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("list", help="List frames.")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_list)

devague/cli/_commands/new.py

@@ -0,0 +1,33 @@
+"""``devague new`` — start a frame from an announcement (the first move)."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._output import emit_result
+from devague.frame import Frame
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    title = args.title or args.announcement
+    frame = Frame(slug=store.unique_slug(store.slugify(title)), title=title)
+    frame.add_claim("announcement", args.announcement, origin="user")
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"slug": frame.slug, "title": title, "claims": 1}, json_mode=True)
+    else:
+        emit_result(f"created frame '{frame.slug}' (announcement = c1)", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("new", help="Start a frame from an announcement.")
+    p.add_argument(
+        "announcement",
+        help="What's the announcement? Pretend this shipped successfully — what "
+        "would you announce to users, teammates, or yourself?",
+    )
+    p.add_argument("--title", help="Frame title (defaults to the announcement).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_new)

devague/cli/_commands/park.py

@@ -0,0 +1,31 @@
+"""``devague park`` — move uncertainty into first-class open vagueness."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import store
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.frame import VAGUENESS_KINDS
+
+
+def cmd_park(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    v = frame.add_vagueness(args.text, args.kind, claim_id=args.claim)
+    store.save(frame)
+    if getattr(args, "json", False):
+        emit_result({"id": v.id, "kind": v.kind}, json_mode=True)
+    else:
+        emit_result(f"parked {v.id} ({v.kind})", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("park", help="Record open vagueness instead of forcing an answer.")
+    p.add_argument("text", help="The uncertainty.")
+    p.add_argument("--kind", required=True, choices=VAGUENESS_KINDS, help="Vagueness kind.")
+    p.add_argument("--claim", help="Link to a claim id.")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_park)

devague/cli/_commands/reject.py

@@ -0,0 +1,19 @@
+"""``devague reject`` — reject a claim or honesty condition."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague.cli._commands.confirm import _transition
+
+
+def cmd_reject(args: argparse.Namespace) -> int:
+    return _transition(args, "rejected")
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("reject", help="Reject a claim or honesty condition.")
+    p.add_argument("id", help="Claim id (c*) or honesty id (h*).")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_reject)

devague/cli/_commands/show.py

@@ -0,0 +1,27 @@
+"""``devague show`` — render the current frame (markdown, or --json for raw state)."""
+
+from __future__ import annotations
+
+import argparse
+
+from devague import render
+from devague.cli._frames import resolve
+from devague.cli._output import emit_result
+from devague.frame import to_dict
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    frame = resolve(args.frame)
+    if getattr(args, "json", False):
+        emit_result(to_dict(frame), json_mode=True)
+    else:
+        emit_result(render.render(frame, args.format), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser("show", help="Render the current frame.")
+    p.add_argument("--format", default="frame-md", help="Renderer format (default: frame-md).")
+    p.add_argument("--frame", help="Frame slug (default: current).")
+    p.add_argument("--json", action="store_true", help="Emit the raw frame as JSON.")
+    p.set_defaults(func=cmd_show)