aisef 0.1.0__py3-none-any.whl

aisdlc/cli/__init__.py

@@ -0,0 +1,101 @@
+"""Giao diện dòng lệnh.
+
+Mọi lệnh đều **gọi-một-lần**: đọc trạng thái trên đĩa, làm việc, ghi lại,
+rồi thoát. Không lệnh nào giả định mình là tiến trình chính, không lệnh
+nào chạy nền. Đó là điều kiện để cùng bộ lệnh này dùng được ở hai chế độ
+(quyết định Đ2):
+
+* **driver-led** — script hoặc CI gọi ``aisdlc run``;
+* **agent-led** — chính agent gọi ``aisdlc next`` / ``verify`` / ``complete``
+  qua Bash, ngay trong phiên chat của Claude Desktop hay OpenCode.
+
+Quy ước mã thoát: ``0`` thành công · ``1`` lỗi dùng sai · ``2`` trạng thái
+chưa đạt (cổng chưa duyệt, doctor không đạt) — để CI phân biệt được
+"hỏng" với "chưa xong".
+
+Bố cục gói (chia theo pha, không đổi hành vi):
+
+* :mod:`._common` — mã thoát, gốc artifact, kho duyệt/trạng thái, adapter;
+* :mod:`.doctor` — lệnh ``doctor``;
+* :mod:`.plan` — cổng người + pha lập kế hoạch;
+* :mod:`.implement` — pha hiện thực và nghiệm thu;
+* :mod:`.harness` — dựng và vận hành harness;
+* :mod:`.parser` — bộ phân tích tham số và ``main``.
+
+Mọi tên module-level cũ được xuất lại ở đây, nên ``from aisdlc.cli import
+main`` và bạn bè vẫn chạy y như khi còn là một file.
+"""
+
+from __future__ import annotations
+
+from ._common import (
+    ARTIFACT_ROOT,
+    _GATE_MARK,
+    EXIT_NOT_READY,
+    EXIT_OK,
+    EXIT_USAGE,
+    _approvals,
+    _artifact_root,
+    _client,
+    _gate_arg,
+    _state,
+)
+from .doctor import _hook_paths_elsewhere, cmd_doctor
+from .harness import cmd_compile, cmd_doc, cmd_guard, cmd_init, cmd_setup, cmd_skill
+from .implement import (
+    _project_has_ui,
+    cmd_devsecops,
+    cmd_evidence,
+    cmd_predeploy,
+    cmd_qa,
+    cmd_report,
+    cmd_run,
+    cmd_status,
+    cmd_tool,
+    cmd_verify,
+)
+from .parser import build_parser, main
+from .plan import (
+    _preflight_lines,
+    cmd_approve,
+    cmd_auto_approve,
+    cmd_change,
+    cmd_gates,
+    cmd_mockup,
+    cmd_plan,
+    cmd_reject,
+    cmd_review,
+)
+
+__all__ = [
+    "ARTIFACT_ROOT",
+    "EXIT_NOT_READY",
+    "EXIT_OK",
+    "EXIT_USAGE",
+    "build_parser",
+    "cmd_approve",
+    "cmd_auto_approve",
+    "cmd_change",
+    "cmd_compile",
+    "cmd_devsecops",
+    "cmd_doc",
+    "cmd_doctor",
+    "cmd_evidence",
+    "cmd_gates",
+    "cmd_guard",
+    "cmd_init",
+    "cmd_mockup",
+    "cmd_plan",
+    "cmd_predeploy",
+    "cmd_qa",
+    "cmd_reject",
+    "cmd_report",
+    "cmd_review",
+    "cmd_run",
+    "cmd_setup",
+    "cmd_skill",
+    "cmd_status",
+    "cmd_tool",
+    "cmd_verify",
+    "main",
+]

aisdlc/cli/__main__.py

@@ -0,0 +1,9 @@
+"""Giữ nguyên `python -m aisdlc.cli` — trước khi tách, `cli.py` có khối
+``if __name__ == "__main__"`` làm đúng việc này."""
+
+import sys
+
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

aisdlc/cli/_common.py

@@ -0,0 +1,72 @@
+"""Mảnh dùng chung của bộ lệnh: mã thoát, gốc artifact, kho duyệt/trạng
+thái, adapter client, và bộ chuyển tham số tên cổng.
+
+Mọi module lệnh khác nhập từ đây, nên file này không được nhập ngược lại
+chúng — giữ đồ thị nhập một chiều.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..control.approvals import GATE_ORDER, ApprovalStore, Gate, Status
+from ..control.state import StateStore
+
+
+ARTIFACT_ROOT = "_bmad-output"
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_NOT_READY = 2
+
+#: Ký hiệu trạng thái cổng, đủ để đọc lướt.
+_GATE_MARK = {
+    Status.APPROVED: "✅",
+    Status.PENDING: "⏳",
+    Status.CHANGES_REQUESTED: "✗",
+    Status.STALE: "⚠️",
+}
+
+
+def _artifact_root(args) -> Path:
+    """Gốc artifact — **một** gốc cho cả dự án (bất biến 2).
+
+    Agent chạy trong worktree của story, nên `--project .` ở đó trỏ vào
+    worktree. Ghi bằng chứng vào đấy thì cổng đọc ở gốc chính không thấy
+    gì, và story "chưa từng chạy test" dù nó vừa chạy.
+    """
+    from ..control.worktree import main_repo
+
+    return main_repo(args.project) / ARTIFACT_ROOT
+
+
+def _approvals(args) -> ApprovalStore:
+    return ApprovalStore(_artifact_root(args))
+
+
+def _state(args) -> StateStore:
+    return StateStore(_artifact_root(args))
+
+
+def _gate_arg(value: str) -> Gate:
+    try:
+        return Gate(value)
+    except ValueError:
+        valid = ", ".join(g.value for g in GATE_ORDER)
+        raise argparse.ArgumentTypeError(f"cổng không hợp lệ: {value}. Hợp lệ: {valid}")
+
+
+def _client(args):
+    """Adapter đã kiểm tên và tình trạng cài đặt. None nếu không dùng được."""
+    from ..clients.compile import ADAPTERS
+
+    if args.client not in ADAPTERS:
+        print(f"✗ client không hỗ trợ: {args.client}", file=sys.stderr)
+        return None, EXIT_USAGE
+    adapter = ADAPTERS[args.client]()
+    if not adapter.available():
+        print(f"✗ chưa cài {args.client} trên máy này", file=sys.stderr)
+        return None, EXIT_NOT_READY
+    return adapter, EXIT_OK

aisdlc/cli/doctor.py

@@ -0,0 +1,286 @@
+"""Lệnh ``doctor`` — kiểm môi trường, cấu hình, hook và skill đã cài."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from ..config import Config, ConfigError
+from ._common import EXIT_NOT_READY, EXIT_OK
+
+
+def _hook_paths_elsewhere(project: Path) -> list[str] | None:
+    """Đường dẫn dự án ghi trong hook/plugin biên dịch mà **khác** dự án này.
+    None khi không có hook nào để so."""
+    import re as _re
+
+    goc = project.resolve()
+    thay: list[str] = []
+    hook = project / ".claude" / "settings.json"
+    if hook.is_file():
+        thay += _re.findall(r"--project\s+(\S+)\s+guard", hook.read_text(encoding="utf-8", errors="replace"))
+    plugin = project / ".opencode" / "plugin" / "aisdlc-guard.ts"
+    if plugin.is_file():
+        thay += _re.findall(r'const PROJECT = "([^"]+)"', plugin.read_text(encoding="utf-8", errors="replace"))
+    if not thay:
+        return None
+    return sorted({p for p in thay if Path(p).resolve() != goc})
+
+
+def cmd_doctor(args) -> int:
+    """Kiểm tra môi trường có đủ chạy framework không."""
+    project = Path(args.project)
+    problems: list[str] = []
+    lines: list[str] = []
+
+    def check(label: str, ok: bool, detail: str = "", *, required: bool = True) -> None:
+        mark = "✅" if ok else ("✗" if required else "○")
+        lines.append(f"  {mark} {label}{(' — ' + detail) if detail else ''}")
+        if required and not ok:
+            problems.append(label)
+
+    lines.append("Môi trường:")
+    check("python >= 3.11", sys.version_info >= (3, 11), sys.version.split()[0])
+    check("git", bool(shutil.which("git")))
+
+    claude = shutil.which("claude")
+    check("claude CLI", bool(claude), claude or "không tìm thấy", required=False)
+    opencode = shutil.which("opencode")
+    check("opencode CLI", bool(opencode), opencode or "không tìm thấy", required=False)
+
+    docker_ok = False
+    if shutil.which("docker"):
+        try:
+            docker_ok = subprocess.run(
+                ["docker", "info"], capture_output=True, timeout=10
+            ).returncode == 0
+        except (subprocess.TimeoutExpired, OSError):
+            docker_ok = False
+    check(
+        "docker daemon",
+        docker_ok,
+        "chạy" if docker_ok else "không chạy — sandbox sẽ suy biến, bảo đảm thấp hơn",
+        required=False,
+    )
+
+    from ..harness.browser import availability as browser_availability
+    from ..harness.tools import image_for
+
+    browser_why = browser_availability(project)
+    check(
+        "playwright + chromium",
+        not browser_why,
+        "sẵn sàng" if not browser_why else f"{browser_why} — không trích được hợp đồng mockup",
+        required=False,
+    )
+
+    lines.append("Dự án:")
+    check("thư mục dự án", project.is_dir(), str(project))
+    from ..harness import sandbox as _sandbox
+
+    try:
+        cfg_for_sandbox = Config.load(project)
+        image = image_for(project, cfg_for_sandbox)
+        spec = _sandbox.SandboxSpec(
+            workspace=project, cmd=["true"],
+            use_docker=cfg_for_sandbox["sandbox.use_docker"],
+            provider=cfg_for_sandbox["sandbox.provider"],
+        )
+    except ConfigError:
+        image, spec = "?", _sandbox.SandboxSpec(workspace=project, cmd=["true"])
+    # Provider đang dùng và bảo đảm nó khai (ADR-005 V5): người đọc biết
+    # bằng chứng sắp ghi `degraded` vì **thiếu gì**, trước khi chạy story nào.
+    try:
+        prov, missing = _sandbox.select_provider(spec)
+    except (RuntimeError, ValueError, ImportError, AttributeError) as e:
+        prov, missing = None, []
+        check("sandbox provider", False, str(e), required=False)
+    if prov is not None:
+        co = sorted(g.value for g, s in prov.guarantees(spec.level).items() if s.blocks_at_source)
+        check(
+            "sandbox provider", not missing,
+            f"{prov.id} — bảo đảm ở {spec.level.value}: {', '.join(co) or 'không có'}"
+            + (f"; THIẾU {', '.join(missing)} — công cụ chạy ngoài cách ly, bằng chứng ghi degraded"
+               if missing else ""),
+            required=False,
+        )
+    if prov is not None and prov.id == "docker":
+        # Chỉ Docker mới bàn về ảnh; provider khác chạy công cụ của máy.
+        check(
+            "ảnh sandbox",
+            image != "alpine:latest",
+            image + (" — không có công cụ của stack nào, test sẽ đỏ vì thiếu công cụ"
+                     if image == "alpine:latest" else " (hợp stack)"),
+            required=False,
+        )
+    req = project / "docs" / "requirements.md"
+    check("docs/requirements.md", req.is_file(), str(req))
+
+    # Hook sinh ra ≠ hook chạy. Story chạy trong worktree; worktree chỉ có
+    # `.claude/` nếu dự án commit nó. Harness nay truyền `--settings` tường
+    # minh (G4), nhưng thứ đó chỉ được chứng minh bằng hợp quy — ở đây nói
+    # thẳng tình trạng để người đọc biết mình đang dựa vào lớp nào.
+    plugin = project / ".opencode" / "plugin" / "aisdlc-guard.ts"
+    if plugin.is_file():
+        tracked = subprocess.run(
+            ["git", "-C", str(project), "ls-files", "--error-unmatch", str(plugin)],
+            capture_output=True, text=True,
+        ).returncode == 0
+        check(
+            "plugin OpenCode trong worktree",
+            tracked,
+            "`.opencode/plugin` đã commit — worktree tự có plugin" if tracked else
+            "`.opencode/plugin` chưa commit — worktree KHÔNG có plugin, OpenCode chạy "
+            "story với zero guard (đo hợp quy 2026-09-05); commit `.opencode/` hoặc "
+            "không dùng OpenCode cho `run`",
+            required=False,
+        )
+    hook = project / ".claude" / "settings.json"
+    if hook.is_file():
+        tracked = subprocess.run(
+            ["git", "-C", str(project), "ls-files", "--error-unmatch", str(hook)],
+            capture_output=True, text=True,
+        ).returncode == 0
+        check(
+            "hook trong worktree",
+            tracked,
+            "`.claude/settings.json` đã commit — worktree tự có hook" if tracked else
+            "`.claude/settings.json` chưa commit — worktree không có hook; harness "
+            "truyền `--settings` tường minh, cổng story mục \"guard có chạy\" sẽ "
+            "trượt nếu hook không tới",
+            required=False,
+        )
+
+    # Guard framework thêm sau lần `compile` cuối thì hook cũ không biết —
+    # ví dụ `process-ref` (luật 6, 2026-09-05). Không kiểm thì guard mới chỉ
+    # có trong mã, không có trong phiên agent nào.
+    rep = project / "_bmad-output" / "compile-report.json"
+    if rep.is_file():
+        from ..harness.guardrails import GUARD_MATCHERS
+
+        try:
+            data = json.loads(rep.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            data = {}
+        for c in data.get("clients", []):
+            thieu = sorted(set(GUARD_MATCHERS) - set(c.get("guards_wired") or []) - set(c.get("guards_post_hoc") or []))
+            check(
+                f"hook {c.get('client')} đủ guard", not thieu,
+                f"{len(GUARD_MATCHERS)} guard" if not thieu else
+                f"thiếu {', '.join(thieu)} — framework có guard mới sau lần biên dịch; chạy `aisdlc compile --client {c.get('client')}`",
+            )
+
+    # Ngưỡng cỡ story chỉ đáng tin chừng nào nó còn khớp dữ liệu thật
+    # (ADR-004 R5). Bảng hiệu chuẩn do `run` tự ghi sau mỗi story.
+    from ..control import complexity
+
+    rows = complexity.load_calibration(project / "_bmad-output")
+    if rows:
+        lech_nguong = complexity.divergence(rows)
+        check(
+            "ngưỡng cỡ story khớp dữ liệu", not lech_nguong,
+            f"{len(rows)} story đã đo, không thấy lệch" if not lech_nguong else
+            "; ".join(lech_nguong) + " — chỉnh `story.max_complexity` trong "
+            "`.ai/config.json` hoặc xem lại trọng số ở `control/complexity.py`",
+            required=False,
+        )
+
+    lech = _hook_paths_elsewhere(project)
+    if lech is not None:
+        check(
+            "hook trỏ đúng dự án", not lech,
+            "đường dẫn `--project`/`PROJECT` trong hook khớp thư mục này" if not lech else
+            f"hook trỏ sang {', '.join(lech[:2])} — dự án bị chép/di chuyển? guard sẽ ghi bằng "
+            "chứng vào dự án ấy; chạy `aisdlc compile` lại",
+        )
+
+    try:
+        cfg = Config.load(project)
+        check("cấu hình", True, cfg.source)
+        lenh = str(cfg.get("tools.test", "") or "")
+        if lenh:
+            co_cov = any(k in lenh for k in ("--coverage", "--cov", "--experimental-test-coverage", "c8 ", "nyc "))
+            check(
+                "lệnh test in coverage", co_cov,
+                "cổng `coverage.min` đọc được số" if co_cov else
+                f"`tools.test` = `{lenh}` không in coverage → mục coverage của cổng sẽ là **chưa cấu hình** "
+                "(thêm `--coverage` / `--cov` / `--experimental-test-coverage`)",
+                required=False,
+            )
+            # Tên test đọc được không (ADR-005 V9)? Có bằng chứng thì tin bằng
+            # chứng: lần `tool_run test` gần nhất ghi `test_format`; chưa có
+            # thì đoán từ cờ lệnh. e9/par: 220/377 lần test không đọc được tên.
+            from ..harness.observe import TOOL_RUN, EvidenceStore
+
+            store = EvidenceStore(project / "_bmad-output")
+            lan = [e for sid in store.stories() for e in store.read(sid).of(TOOL_RUN)
+                   if e.name in ("test", "test:baseline") and not e.detail.get("skipped")]
+            if lan:
+                doc_ten = bool(lan[-1].detail.get("test_format"))
+                vi = f"lần test gần nhất ghi test_format={lan[-1].detail.get('test_format') or ''!r}"
+            else:
+                doc_ten = any(k in lenh for k in ("-v", "--verbose", "--reporter=verbose",
+                                                  "--test-reporter", "node --test", "ctrf"))
+                vi = "chưa có bằng chứng — đoán từ cờ lệnh"
+            check(
+                "lệnh test in tên test", doc_ten,
+                f"cổng đọc được tên test ({vi})" if doc_ten else
+                f"{vi} → mục `tiêu chí có test`/`không làm đỏ test có sẵn` là **chưa cấu hình**. "
+                "Dùng reporter in tên hoặc CTRF: pytest `-v` hay `pip install pytest-json-ctrf` + "
+                "`pytest --ctrf /dev/stdout`; vitest `--reporter=verbose` hay `vitest-ctrf-json-reporter` "
+                "(in `vitest-ctrf/report.json` ra stdout, giữ mã thoát); node `--test-reporter=spec|tap`",
+                required=False,
+            )
+    except ConfigError as e:
+        check("cấu hình", False, str(e))
+
+    skills_dir = project / ".claude" / "skills"
+    if skills_dir.is_dir():
+        from ..kit.security_filter import Verdict, classify_all
+
+        installed = [d for d in skills_dir.iterdir() if d.is_dir()]
+        lines.append("Skill đã cài:")
+        check("có skill", bool(installed), f"{len(installed)} thư mục")
+
+        # Bất biến: skill tấn công không bao giờ được có mặt trong dự án.
+        offensive = [
+            c.skill.name
+            for c in classify_all(skills_dir)
+            if c.verdict is Verdict.OFFENSIVE
+        ]
+        # Skill của framework nằm trong kho framework; dự án giữ một bản
+        # sao. Sửa skill mà không cài lại thì agent vẫn chạy bản cũ, và
+        # cách duy nhất phát hiện là ngồi so từng file.
+        from ..kit.install import OWN_SKILLS
+
+        stale = []
+        for own in sorted(OWN_SKILLS.glob("*/SKILL.md")) if OWN_SKILLS.is_dir() else []:
+            copied = skills_dir / own.parent.name / "SKILL.md"
+            if copied.is_file() and copied.read_bytes() != own.read_bytes():
+                stale.append(own.parent.name)
+        check(
+            "skill framework cập nhật",
+            not stale,
+            "khớp bản gốc" if not stale
+            else f"cũ hơn kho: {', '.join(stale)} — chạy `aisdlc setup`",
+            required=False,
+        )
+
+        check(
+            "không có skill tấn công",
+            not offensive,
+            "sạch" if not offensive else f"LỌT: {', '.join(offensive[:5])}",
+        )
+    else:
+        lines.append("Skill đã cài:")
+        check("đã chạy setup", False, "chưa — chạy: aisdlc setup", required=False)
+
+    print("\n".join(lines))
+    if problems:
+        print(f"\n✗ thiếu: {', '.join(problems)}")
+        return EXIT_NOT_READY
+    print("\n✅ sẵn sàng")
+    return EXIT_OK