@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/_triage_subscribe_cli.py

@@ -0,0 +1,140 @@
+"""CLI helpers for ``scripts/triage_subscribe.py`` (D14 / #1133)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+_RECONCILE_HINT = (
+    "  Reconciliation: run `task triage:bootstrap -- --resume` to "
+    "backfill / mark out-of-scope cached entries."
+)
+
+
+def build_parser(op: str) -> argparse.ArgumentParser:
+    """Build the subscribe / unsubscribe arg parser. ``op`` is one of the two."""
+    if op not in {"subscribe", "unsubscribe"}:
+        raise ValueError(f"unknown op {op!r}")
+    parser = argparse.ArgumentParser(
+        prog=f"triage_subscribe.py {op}",
+        description=(
+            f"{op.capitalize()} a rule on plan.policy.triageScope[]. "
+            "Exactly one of --label / --milestone / --issue is required. "
+            "Atomic; idempotent; appends a subscription-change record to "
+            "vbrief/.eval/subscription-history.jsonl (D14 / #1133)."
+        ),
+    )
+    parser.add_argument(
+        "op",
+        choices=["subscribe", "unsubscribe"],
+        help="The operation to perform (positional discriminator).",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=os.environ.get("DEFT_PROJECT_ROOT", "."),
+        help=(
+            "Consumer project root (default: $DEFT_PROJECT_ROOT or cwd)."
+        ),
+    )
+    parser.add_argument(
+        "--label",
+        default=None,
+        help="Label name to (un)subscribe (mutually exclusive with --milestone/--issue).",
+    )
+    parser.add_argument(
+        "--milestone",
+        default=None,
+        help="Milestone name to (un)subscribe (mutually exclusive).",
+    )
+    parser.add_argument(
+        "--issue",
+        type=int,
+        default=None,
+        help="Issue number to (un)subscribe via explicit-watch (mutually exclusive).",
+    )
+    parser.add_argument(
+        "--issue-note",
+        default="added via task triage:subscribe",
+        help=(
+            "Note attached to a new explicit-watch entry (subscribe only; "
+            "ignored on unsubscribe). Required for future-operator legibility "
+            "per #1131 Decision 4."
+        ),
+    )
+    parser.add_argument(
+        "--actor",
+        default=None,
+        help=(
+            "Override the audit-log actor field (default: $DEFT_TRIAGE_ACTOR "
+            "or 'user:<login>')."
+        ),
+    )
+    return parser
+
+
+def run_cli(argv: list[str] | None, module: Any) -> int:
+    """Dispatch the subscribe / unsubscribe CLI."""
+    raw = list(argv) if argv is not None else sys.argv[1:]
+    if not raw or raw[0] not in {"subscribe", "unsubscribe"}:
+        print(
+            "triage:subscribe: first positional arg must be 'subscribe' or "
+            "'unsubscribe'; e.g. task triage:subscribe -- --label=bug",
+            file=sys.stderr,
+        )
+        return 2
+    op = raw[0]
+    parser = build_parser(op)
+    args = parser.parse_args(raw)
+
+    project_root = Path(args.project_root).resolve()
+    if not project_root.exists() or not project_root.is_dir():
+        print(
+            f"triage:{op}: --project-root {project_root} does not exist "
+            "or is not a directory.",
+            file=sys.stderr,
+        )
+        return 2
+
+    chosen = sum(
+        1 for v in (args.label, args.milestone, args.issue) if v is not None
+    )
+    if chosen != 1:
+        print(
+            f"triage:{op}: exactly one of --label / --milestone / --issue "
+            "is required.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        if op == "subscribe":
+            changed, message = module.subscribe(
+                project_root,
+                label=args.label,
+                milestone=args.milestone,
+                issue=args.issue,
+                issue_note=args.issue_note,
+                actor=args.actor,
+            )
+        else:
+            changed, message = module.unsubscribe(
+                project_root,
+                label=args.label,
+                milestone=args.milestone,
+                issue=args.issue,
+                actor=args.actor,
+            )
+    except Exception as exc:  # pylint: disable=broad-except
+        print(f"triage:{op}: {exc}", file=sys.stderr)
+        return 1
+
+    if not changed:
+        print(f"triage:{op}: {message} (no-op).", file=sys.stderr)
+        return 0
+
+    print(f"triage:{op}: {message}.")
+    print(_RECONCILE_HINT, file=sys.stderr)
+    return 0

package/scripts/_triage_welcome_cli.py

@@ -0,0 +1,421 @@
+"""CLI + prompt helpers for ``scripts/triage_welcome.py`` (#1143).
+
+Extracted from ``scripts/triage_welcome.py`` so the parent module stays
+under the 500-line SHOULD ceiling from ``coding/coding.md``. The public
+ritual surface lives in :mod:`triage_welcome`; this module is the
+argparse shim, the deterministic-questions-compliant numbered-menu
+helpers, and the yes/no + integer prompt helpers only.
+
+Mirrors the split convention established by ``scripts/_triage_scope_cli.py``
+(#1131 / D12) and ``scripts/_triage_queue_cli.py`` (#1128 / D11).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover -- import-time-only typing alias
+    from triage_welcome import PriorState, WelcomeOutcome
+
+# ---------------------------------------------------------------------------
+# Default-mode (non-onboard) nudge strings (#1309)
+# ---------------------------------------------------------------------------
+
+#: Environment variable used by Taskfile wrappers to tell the Python CLI which
+#: namespace prefix exposes sibling tasks in the caller's project.
+TASK_PREFIX_ENV_VAR: str = "DEFT_TASK_PREFIX"
+
+#: Default-mode nudge string emitted by :func:`run_default_mode` when the
+#: operator has never run ``deft triage:welcome --onboard``. Kept as a
+#: module-level constant so tests can pin the exact byte-shape and so
+#: future copy edits land in one place.
+FIRST_TIME_NUDGE: str = (
+    "[welcome] First-time? Run `deft triage:welcome --onboard` "
+    "to set up triage."
+)
+
+#: Template for the partial-onboarding nudge. ``{missing}`` is filled with
+#: a stable `" + "`-joined list of absent state pieces (see
+#: :func:`_classify_onboarding`).
+INCOMPLETE_NUDGE_TEMPLATE: str = (
+    "[welcome] Onboarding incomplete: {missing}. Run "
+    "`deft triage:welcome --onboard` to resume."
+)
+
+
+# ---------------------------------------------------------------------------
+# Default IO -- tests inject overrides
+# ---------------------------------------------------------------------------
+
+
+def default_input(prompt: str) -> str:
+    return input(prompt)
+
+
+def default_output(line: str = "") -> None:
+    print(line)
+
+
+# ---------------------------------------------------------------------------
+# Numbered-menu prompts (contracts/deterministic-questions.md compliant)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PromptOutcome:
+    """Structured prompt result -- ``discuss`` / ``back`` / ``value``."""
+
+    discuss: bool = False
+    back: bool = False
+    value: Any = None
+
+
+def prompt_menu(
+    *,
+    title: str,
+    options: list[tuple[str, str]],
+    default_index: int,
+    input_fn: Callable[[str], str],
+    output_fn: Callable[[str], None],
+) -> PromptOutcome:
+    """Render a numbered menu and return the operator's choice.
+
+    Options are ``(label, value-key)`` tuples; the renderer appends
+    ``Discuss`` and ``Back`` as the canonical final two options per
+    :doc:`contracts/deterministic-questions.md`. Empty input accepts
+    *default_index* (0-based). Invalid input re-renders the menu.
+    """
+    discuss_idx = len(options) + 1
+    back_idx = len(options) + 2
+    while True:
+        output_fn(title)
+        for i, (label, _key) in enumerate(options, start=1):
+            marker = " (default)" if i - 1 == default_index else ""
+            output_fn(f"  {i}) {label}{marker}")
+        output_fn(f"  {discuss_idx}) Discuss")
+        output_fn(f"  {back_idx}) Back")
+        try:
+            raw = input_fn(f"  > [{default_index + 1}] ")
+        except EOFError:
+            raw = ""
+        choice = raw.strip()
+        if not choice:
+            _label, key = options[default_index]
+            return PromptOutcome(value=key)
+        if not choice.isdecimal():
+            output_fn(f"  ! Invalid selection: {choice!r}. Pick a number.")
+            continue
+        n = int(choice)
+        if 1 <= n <= len(options):
+            _label, key = options[n - 1]
+            return PromptOutcome(value=key)
+        if n == discuss_idx:
+            output_fn(
+                "  [discuss] Pausing the ritual. Re-run "
+                "`deft triage:welcome` after the discussion to resume."
+            )
+            return PromptOutcome(discuss=True)
+        if n == back_idx:
+            return PromptOutcome(back=True)
+        output_fn(f"  ! Out-of-range selection: {n}. Pick 1..{back_idx}.")
+
+
+def prompt_yes_no(
+    *,
+    title: str,
+    default_yes: bool,
+    input_fn: Callable[[str], str],
+    output_fn: Callable[[str], None],
+) -> bool:
+    """Yes/no confirm; empty input accepts *default_yes*."""
+    suffix = "[Y/n]" if default_yes else "[y/N]"
+    try:
+        raw = input_fn(f"  {title} {suffix} ")
+    except EOFError:
+        raw = ""
+    text = raw.strip().lower()
+    if not text:
+        return default_yes
+    if text in {"y", "yes"}:
+        return True
+    if text in {"n", "no"}:
+        return False
+    output_fn(f"  ! Unrecognized: {raw!r}; treating as 'n'.")
+    return False
+
+
+def prompt_int(
+    *,
+    title: str,
+    default: int,
+    input_fn: Callable[[str], str],
+    output_fn: Callable[[str], None],
+    minimum: int = 1,
+) -> int | None:
+    """Free-text positive int with default; returns None on Discuss/Back."""
+    while True:
+        try:
+            raw = input_fn(f"  {title} (default {default}): ")
+        except EOFError:
+            raw = ""
+        text = raw.strip()
+        if not text:
+            return default
+        if text.lower() in {"discuss", "back"}:
+            return None
+        if not text.isdecimal():
+            output_fn(f"  ! Not a positive integer: {raw!r}. Try again.")
+            continue
+        value = int(text)
+        if value < minimum:
+            output_fn(f"  ! Value {value} below minimum {minimum}. Try again.")
+            continue
+        return value
+
+
+# ---------------------------------------------------------------------------
+# argparse shim
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="triage_welcome.py",
+        description=(
+            "Emit the `deft triage:welcome` session-start status surface "
+            "(#1309 default mode -- summary one-liner plus a state-conditional "
+            "first-time / incomplete-onboarding nudge), or run the full "
+            "6-phase interactive onboarding ritual (#1143) under --onboard. "
+            "Idempotent -- re-run after a partial completion to resume cleanly."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        default=os.environ.get("DEFT_PROJECT_ROOT", "."),
+        help="Consumer project root (default: $DEFT_PROJECT_ROOT or cwd).",
+    )
+    parser.add_argument(
+        "--onboard",
+        action="store_true",
+        help=(
+            "Run the interactive 6-phase onboarding ritual (#1143). "
+            "Without this flag (the default), `deft triage:welcome` emits "
+            "the non-interactive summary one-liner plus a state-conditional "
+            "nudge pointing at `--onboard` when state is missing or partial "
+            "(#1309)."
+        ),
+    )
+    parser.add_argument(
+        "--no-subprocess",
+        action="store_true",
+        help=(
+            "Skip the `deft triage:bootstrap` / `deft scope:demote` / "
+            "`deft triage:summary` follow-up hops. Test-mode flag for the "
+            "--onboard ritual; never set in production runs."
+        ),
+    )
+    parser.add_argument(
+        "--task-prefix",
+        default=os.environ.get(TASK_PREFIX_ENV_VAR, ""),
+        help=(
+            "Optional Taskfile namespace prefix for sibling task dispatches "
+            "(for example `deft:` in consumer includes). Defaults to "
+            f"${TASK_PREFIX_ENV_VAR}."
+        ),
+    )
+    parser.add_argument(
+        "--skip-bootstrap",
+        action="store_true",
+        help=(
+            "Explicitly decline the --onboard Phase 3 `deft triage:bootstrap` "
+            "invocation (#1244). The ritual still completes but emits a "
+            "visible audit message AND records the decline in "
+            "`meta/policy-changes.log`; downstream verbs that depend on "
+            "`vbrief/.eval/candidates.jsonl` will refuse to run until "
+            "bootstrap is invoked separately."
+        ),
+    )
+    parser.add_argument(
+        "--no-history",
+        action="store_true",
+        help=(
+            "Suppress the `vbrief/.eval/summary-history.jsonl` append "
+            "when emitting the default-mode summary (#1309). Test-mode "
+            "flag; production callers SHOULD let the history sidecar "
+            "track every invocation."
+        ),
+    )
+    return parser
+
+
+def run_cli(argv: list[str] | None, tw_module: Any) -> int:
+    """Dispatch ``triage_welcome`` CLI args using ``tw_module`` backend.
+
+    ``tw_module`` is the parent :mod:`triage_welcome` module; passed
+    explicitly to avoid a circular import at module-load time.
+
+    Default invocation (no ``--onboard``) routes to the non-interactive
+    :func:`triage_welcome.run_default_mode` surface (#1309); ``--onboard``
+    routes to the original 6-phase interactive ritual
+    :func:`triage_welcome.run_welcome` (#1143).
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    project_root = Path(args.project_root).resolve()
+    if not project_root.is_dir():
+        print(
+            f"triage:welcome: --project-root {project_root} is not a directory.",
+            file=sys.stderr,
+        )
+        return 2
+    if args.onboard:
+        outcome = tw_module.run_welcome(
+            project_root,
+            run_subprocess=not args.no_subprocess,
+            skip_bootstrap=args.skip_bootstrap,
+            task_prefix=args.task_prefix,
+        )
+    else:
+        outcome = tw_module.run_default_mode(
+            project_root,
+            write_history=not args.no_history,
+            task_prefix=args.task_prefix,
+        )
+    return outcome.exit_code
+
+
+# ---------------------------------------------------------------------------
+# Default-mode (non-onboard) helpers (#1309)
+#
+# Hosted here -- not in :mod:`triage_welcome` -- so the parent module stays
+# under the 1000-line MUST cap from ``coding/coding.md``. Re-exported by
+# :mod:`triage_welcome` for backward compatibility with callers / tests that
+# reference ``triage_welcome.<name>``.
+# ---------------------------------------------------------------------------
+
+
+def _classify_onboarding(state: PriorState) -> tuple[str, list[str]]:
+    """Return ``(state_label, missing_pieces)`` for the default-mode nudge.
+
+    Three discrete states keyed off the canonical "has the operator run
+    onboarding?" signals (#1309 vBRIEF / paired with #1308):
+
+    - ``"first-time"`` -- NONE of the three signals present: no
+      ``vbrief/.eval/candidates.jsonl``, no ``plan.policy.triageScope``,
+      no ``plan.policy.wipCap``. The operator has never run
+      ``deft triage:welcome --onboard``.
+    - ``"incomplete"`` -- a strict subset (1 or 2) of the three signals
+      present; ``missing_pieces`` names the absent piece(s) so the
+      operator-facing nudge can be specific.
+    - ``"fully-set-up"`` -- all three signals present.
+
+    Pure helper -- no I/O, no audit log.
+    """
+    signals = {
+        "candidates.jsonl": state.audit_log_present,
+        "triageScope": state.triage_scope_set,
+        "wipCap": state.wip_cap_set,
+    }
+    present = [name for name, ok in signals.items() if ok]
+    missing = [name for name, ok in signals.items() if not ok]
+    if not present:
+        return "first-time", missing
+    if not missing:
+        return "fully-set-up", []
+    return "incomplete", missing
+
+
+def emit_oneliner(
+    project_root: Path,
+    *,
+    output_fn: Callable[[str], None] | None = None,
+    write_history: bool = True,
+) -> str:
+    """Emit the ``deft triage:summary`` one-liner via internal Python call.
+
+    Mirrors the byte-shape produced by
+    ``scripts/triage_summary.py::main`` (the headline plus, when
+    applicable, the second ``[triage:scope]`` line per #1270) without
+    spawning a subprocess. ``write_history`` controls whether the
+    rolling ``vbrief/.eval/summary-history.jsonl`` sidecar is appended
+    to; default-mode welcome runs DO append so observability stays
+    aligned with direct ``deft triage:summary`` invocations.
+
+    Returns the rendered line(s) so callers can compose with downstream
+    state without re-rendering.
+    """
+    # Lazy-import to keep startup cost off the interactive ritual path
+    # and to mirror the existing :func:`run_welcome` Phase 6 idiom of
+    # treating ``triage_summary`` as a sibling module.
+    import triage_summary  # noqa: I001
+
+    out_fn = output_fn or default_output
+    result = triage_summary.compute_summary(project_root)
+    line = triage_summary.format_summary(result)
+    out_fn(line)
+    if write_history:
+        history_path = project_root / triage_summary.SUMMARY_HISTORY_REL_PATH
+        triage_summary.append_history(history_path, result, line)
+    return line
+
+
+def run_default_mode(
+    project_root: Path,
+    *,
+    output_fn: Callable[[str], None] | None = None,
+    write_history: bool = True,
+    task_prefix: str | None = None,
+) -> WelcomeOutcome:
+    """Non-interactive default mode for ``deft triage:welcome`` (#1309).
+
+    Subsumes the prior session-start step of running
+    ``deft triage:summary`` plus a state-conditional first-time /
+    incomplete-onboarding nudge so a fresh consumer sees one
+    actionable line. The interactive 6-phase ritual now lives behind
+    ``deft triage:welcome --onboard`` (see :func:`run_cli`).
+
+    No interactive prompts; the function never reads from stdin and is
+    safe to invoke from any non-tty surface (CI, cloud agents, etc.).
+    Always returns ``exit_code=0`` -- the default-mode surface is a
+    status report, not a gate.
+    """
+    # Lazy-import the parent module so we can reach ``detect_prior_state``
+    # / ``WelcomeOutcome`` without a module-load cycle (parent module
+    # imports names from this file at top level; reverse direction MUST
+    # be deferred).
+    import triage_welcome  # noqa: I001
+
+    out_fn = output_fn or default_output
+    outcome = triage_welcome.WelcomeOutcome()
+    outcome.phases_run.append(0)  # "phase 0" = default-mode summary
+    emit_oneliner(project_root, output_fn=out_fn, write_history=write_history)
+    state = triage_welcome.detect_prior_state(project_root)
+    label, missing = _classify_onboarding(state)
+    canonical_onboard_command = triage_welcome.format_welcome_command(
+        ["triage:welcome", "--onboard"]
+    )
+    onboard_command = triage_welcome.format_welcome_command(
+        ["triage:welcome", "--onboard"],
+        task_prefix=task_prefix,
+    )
+    if label == "first-time":
+        out_fn(FIRST_TIME_NUDGE.replace(canonical_onboard_command, onboard_command))
+    elif label == "incomplete":
+        # Stable, deterministic ordering for the missing-piece list so
+        # tests can pin the byte-shape across runs.
+        joined = " + ".join(missing)
+        out_fn(
+            INCOMPLETE_NUDGE_TEMPLATE.format(missing=joined).replace(
+                canonical_onboard_command,
+                onboard_command,
+            )
+        )
+    # ``fully-set-up`` is silent -- the summary line alone is enough.
+    outcome.exit_code = 0
+    return outcome