@grifhinz/logics-manager 2.0.4 → 2.1.0

package/logics_manager/assist.py

@@ -14,6 +14,7 @@ from typing import Any
 from .config import ConfigError, find_repo_root, load_repo_config
 from .doctor import doctor_payload
 from .lint import lint_payload
+from .termstyle import colorize_help
 
 
 DEFAULT_HYBRID_AUDIT_LOG = "logics/.cache/hybrid_assist_audit.jsonl"
@@ -21,6 +22,7 @@ DEFAULT_HYBRID_MEASUREMENT_LOG = "logics/.cache/hybrid_assist_measurements.jsonl
 DEFAULT_HYBRID_ROI_RECENT_LIMIT = 8
 DEFAULT_HYBRID_ROI_WINDOW_DAYS = 14
 DEFAULT_ESTIMATED_REMOTE_TOKENS_PER_LOCAL_RUN = 1200
+HELP_FLAGS = ("-h", "--help")
 
 
 CLAUDE_BRIDGE_VARIANTS: tuple[dict[str, object], ...] = (
@@ -1347,6 +1349,364 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _build_help() -> str:
+    return "\n".join(
+        [
+            "Logics Assist CLI",
+            "Inspect runtime signals and build context bundles.",
+            "",
+            "Usage:",
+            "  logics-manager assist <command> [args...]",
+            "",
+            "Runtime and diagnostics:",
+            "  runtime-status",
+            "    Report local assist runtime readiness.",
+            "    Flags: --backend, --model-profile, --model, --ollama-host, --timeout, --format {text,json}, --out, --dry-run",
+            "  diff-risk",
+            "    Classify the current git diff using deterministic heuristics.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  commit-plan",
+            "    Draft a minimal commit plan from the current git diff.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  changed-surface-summary",
+            "    Summarize the current changed repository surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "",
+            "Review and governance:",
+            "  doc-consistency",
+            "    Review workflow docs for consistency issues without mutating them.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  review-checklist",
+            "    Generate a bounded review checklist for the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  validation-checklist",
+            "    Generate a deterministic validation checklist from the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  validation-summary",
+            "    Summarize lint, doctor, and validation impact signals.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  test-impact-summary",
+            "    Summarize the likely test impact of the current change surface.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  roi-report",
+            "    Summarize hybrid assist ROI from local audit and measurement logs.",
+            "    Flags: --audit-log, --measurement-log, --recent-limit, --window-days, --format {text,json}, --out, --dry-run",
+            "",
+            "Context and prompts:",
+            "  claude-bridges",
+            "    Render the canonical Claude runtime publication manifest and prompts.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  context <flow_name> [ref]",
+            "    Build a shared assist context bundle for a flow.",
+            "    Flags: --context-mode {summary-only,diff-first,full}, --profile {tiny,normal,deep}, --include-graph, --include-registry, --include-doctor, --format {text,json}, --out, --dry-run",
+            "  claude-instructions",
+            "    Render the canonical assistant instructions derived from the integrated runtime.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  next-step [ref]",
+            "    Suggest the next bounded Logics step for a target doc.",
+            "    Flags: --format {text,json}, --dry-run",
+            "  request-draft",
+            "    Draft a bounded request doc from an intent.",
+            "    Flags: --intent, --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  spec-first-pass <ref>",
+            "    Draft a first-pass spec outline from a backlog item.",
+            "    Flags: --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  backlog-groom <ref>",
+            "    Draft a bounded backlog proposal from a request doc.",
+            "    Flags: --format {text,json}, --execution-mode {suggestion-only,execute}, --dry-run",
+            "  closure-summary [ref]",
+            "    Summarize a delivered request, backlog item, or task.",
+            "    Flags: --format {text,json}, --dry-run",
+            "",
+            "Examples:",
+            "  logics-manager assist runtime-status --format json",
+            "  logics-manager assist context request req_001_my_request --profile deep",
+            "  logics-manager assist request-draft --intent \"Improve onboarding\"",
+        ]
+    )
+
+
+def _build_command_help(command: str) -> str:
+    if command == "runtime-status":
+        return "\n".join(
+            [
+                "Logics Assist Runtime Status",
+                "Report local assist runtime readiness.",
+                "",
+                "Usage:",
+                "  logics-manager assist runtime-status [args...]",
+                "",
+                "Flags:",
+                "  --backend",
+                "  --model-profile",
+                "  --model",
+                "  --ollama-host",
+                "  --timeout",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "context":
+        return "\n".join(
+            [
+                "Logics Assist Context",
+                "Build a shared assist context bundle for a flow.",
+                "",
+                "Usage:",
+                "  logics-manager assist context <flow_name> [ref] [args...]",
+                "",
+                "Flags:",
+                "  --context-mode {summary-only,diff-first,full}",
+                "  --profile {tiny,normal,deep}",
+                "  --include-graph",
+                "  --include-registry",
+                "  --include-doctor",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "request-draft":
+        return "\n".join(
+            [
+                "Logics Assist Request Draft",
+                "Draft a bounded request doc from an intent.",
+                "",
+                "Usage:",
+                "  logics-manager assist request-draft [args...]",
+                "",
+                "Flags:",
+                "  --intent",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "spec-first-pass":
+        return "\n".join(
+            [
+                "Logics Assist Spec First Pass",
+                "Draft a first-pass spec outline from a backlog item.",
+                "",
+                "Usage:",
+                "  logics-manager assist spec-first-pass <ref> [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "backlog-groom":
+        return "\n".join(
+            [
+                "Logics Assist Backlog Groom",
+                "Draft a bounded backlog proposal from a request doc.",
+                "",
+                "Usage:",
+                "  logics-manager assist backlog-groom <ref> [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --execution-mode {suggestion-only,execute}",
+                "  --dry-run",
+            ]
+        )
+    if command == "closure-summary":
+        return "\n".join(
+            [
+                "Logics Assist Closure Summary",
+                "Summarize a delivered request, backlog item, or task.",
+                "",
+                "Usage:",
+                "  logics-manager assist closure-summary [ref] [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "roi-report":
+        return "\n".join(
+            [
+                "Logics Assist ROI Report",
+                "Summarize hybrid assist ROI from local audit and measurement logs.",
+                "",
+                "Usage:",
+                "  logics-manager assist roi-report [args...]",
+                "",
+                "Flags:",
+                "  --audit-log",
+                "  --measurement-log",
+                "  --recent-limit",
+                "  --window-days",
+                "  --format {text,json}",
+                "  --out",
+                "  --dry-run",
+            ]
+        )
+    if command == "diff-risk":
+        return "\n".join(
+            [
+                "Logics Assist Diff Risk",
+                "Classify the current git diff using deterministic heuristics.",
+                "",
+                "Usage:",
+                "  logics-manager assist diff-risk [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "commit-plan":
+        return "\n".join(
+            [
+                "Logics Assist Commit Plan",
+                "Draft a minimal commit plan from the current git diff.",
+                "",
+                "Usage:",
+                "  logics-manager assist commit-plan [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "changed-surface-summary":
+        return "\n".join(
+            [
+                "Logics Assist Changed Surface Summary",
+                "Summarize the current changed repository surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist changed-surface-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "doc-consistency":
+        return "\n".join(
+            [
+                "Logics Assist Doc Consistency",
+                "Review workflow docs for consistency issues without mutating them.",
+                "",
+                "Usage:",
+                "  logics-manager assist doc-consistency [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "review-checklist":
+        return "\n".join(
+            [
+                "Logics Assist Review Checklist",
+                "Generate a bounded review checklist for the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist review-checklist [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "validation-checklist":
+        return "\n".join(
+            [
+                "Logics Assist Validation Checklist",
+                "Generate a deterministic validation checklist from the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist validation-checklist [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "validation-summary":
+        return "\n".join(
+            [
+                "Logics Assist Validation Summary",
+                "Summarize lint, doctor, and validation impact signals.",
+                "",
+                "Usage:",
+                "  logics-manager assist validation-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "test-impact-summary":
+        return "\n".join(
+            [
+                "Logics Assist Test Impact Summary",
+                "Summarize the likely test impact of the current change surface.",
+                "",
+                "Usage:",
+                "  logics-manager assist test-impact-summary [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "claude-bridges":
+        return "\n".join(
+            [
+                "Logics Assist Claude Bridges",
+                "Render the canonical Claude runtime publication manifest and prompts.",
+                "",
+                "Usage:",
+                "  logics-manager assist claude-bridges [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "claude-instructions":
+        return "\n".join(
+            [
+                "Logics Assist Claude Instructions",
+                "Render the canonical assistant instructions derived from the integrated runtime.",
+                "",
+                "Usage:",
+                "  logics-manager assist claude-instructions [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    if command == "next-step":
+        return "\n".join(
+            [
+                "Logics Assist Next Step",
+                "Suggest the next bounded Logics step for a target doc.",
+                "",
+                "Usage:",
+                "  logics-manager assist next-step [ref] [args...]",
+                "",
+                "Flags:",
+                "  --format {text,json}",
+                "  --dry-run",
+            ]
+        )
+    return _build_help()
+
+
+def _print_help(text: str) -> None:
+    print(colorize_help(text))
+
+
 def _get_global_claude_home() -> Path:
     return Path(os.environ.get("LOGICS_CLAUDE_GLOBAL_HOME") or (Path.home() / ".claude")).resolve()
 
@@ -2213,6 +2573,12 @@ def cmd_context(args: argparse.Namespace) -> dict[str, object]:
 
 
 def main(argv: list[str]) -> int:
+    if not argv or argv[0] in HELP_FLAGS:
+        _print_help(_build_help())
+        return 0
+    if argv[0] in {"runtime-status", "context", "request-draft", "spec-first-pass", "backlog-groom", "closure-summary", "roi-report", "diff-risk", "commit-plan", "changed-surface-summary", "doc-consistency", "review-checklist", "validation-checklist", "validation-summary", "test-impact-summary", "claude-bridges", "claude-instructions", "next-step"} and len(argv) > 1 and argv[1] in HELP_FLAGS:
+        _print_help(_build_command_help(argv[0]))
+        return 0
     parser = build_parser()
     args = parser.parse_args(argv)
     payload = args.func(args)

package/logics_manager/cli.py

@@ -6,7 +6,6 @@ import subprocess
 import sys
 from shutil import which
 from pathlib import Path
-from textwrap import dedent
 
 from .bootstrap import bootstrap_payload, render_bootstrap
 from .assist import main as assist_main
@@ -16,10 +15,97 @@ from .config import ConfigError, find_repo_root, render_config_show
 from .index import index_payload, render_index
 from .lint import lint_payload, render_lint
 from .doctor import render_doctor
+from .termstyle import colorize_help
 
 
 DEFAULT_SELF_UPDATE_PY_PACKAGE = "logics-manager"
 DEFAULT_SELF_UPDATE_PACKAGE = "@grifhinz/logics-manager"
+HELP_ARGV = (["-h"], ["--help"])
+ROOT_COMMANDS = (
+    "bootstrap",
+    "flow",
+    "sync",
+    "assist",
+    "audit",
+    "index",
+    "lint",
+    "config",
+    "doctor",
+    "mcp",
+    "self-update",
+)
+
+
+def _build_root_help() -> str:
+    sections = [
+        "Logics Manager CLI",
+        "Canonical CLI for workflow, validation, and runtime ops.",
+        "",
+        "Usage:",
+        "  logics-manager <command> [args...]",
+        "  logics-manager config show [options]",
+        "",
+        "Top-level options:",
+        "  -h, --help      Show this help message and exit.",
+        "  -v, --version   Print the installed version.",
+        "  --version       Print the installed version.",
+        "",
+        "Commands:",
+        "  bootstrap",
+        "    Prepare or check the workflow tree and generated instructions.",
+        "    Options: --check, --format {text,json}",
+        "",
+        "  flow",
+        "    Create and manage workflow docs.",
+        "    Subcommands: new, list, companion, promote, split, close, finish",
+        "    Key flags: --title, --slug, --from-version, --understanding, --confidence, --status, --complexity, --theme, --progress, --format {text,json}, --dry-run",
+        "",
+        "  sync",
+        "    Synchronize workflow transitions and exports.",
+        "    Subcommands: close-eligible-requests, refresh-mermaid-signatures, schema-status, read-doc, list-docs, search-docs, update-indicators, append-note, context-pack, export-graph",
+        "",
+        "  assist",
+        "    Inspect runtime signals and build context bundles.",
+        "    Subcommands: runtime-status, diff-risk, commit-plan, changed-surface-summary, doc-consistency, review-checklist, validation-checklist, validation-summary, test-impact-summary, roi-report, claude-bridges, context, claude-instructions, next-step, request-draft, spec-first-pass, backlog-groom, closure-summary",
+        "",
+        "  audit",
+        "    Audit request, backlog, and task consistency.",
+        "    Options: --stale-days, --skip-ac-traceability, --skip-gates, --legacy-cutoff-version, --format {text,json}, --group-by-doc, --autofix-ac-traceability, --paths, --refs, --since-version, --token-hygiene, --autofix-structure, --governance-profile",
+        "",
+        "  index",
+        "    Generate `logics/INDEX.md` from the workflow corpus.",
+        "    Options: --out, --format {text,json}",
+        "",
+        "  lint",
+        "    Lint workflow documents for filenames, headings, and indicators.",
+        "    Options: --require-status, --format {text,json}",
+        "",
+        "  config show",
+        "    Render the merged runtime config.",
+        "    Options: --format {text,json}",
+        "",
+        "  doctor",
+        "    Check required workflow directories and schema metadata.",
+        "    Options: --format {text,json}",
+        "",
+        "  mcp",
+        "    Expose bounded Logics tools for MCP clients.",
+        "    Subcommands: serve, serve-http, connect, tools, call",
+        "",
+        "  self-update",
+        "    Update the installed Python or npm package.",
+        "    Options: --manager {auto,pip,npm}, --package, --python-package, --dry-run",
+        "",
+        "Examples:",
+        '  logics-manager flow new request --title "My request"',
+        "  logics-manager audit",
+        "  logics-manager config show --format json",
+    ]
+    return "\n".join(sections)
+
+
+def _print_help(text: str) -> None:
+    print(colorize_help(text))
 
 
 def get_cli_version() -> str:
@@ -41,34 +127,22 @@ def get_cli_version() -> str:
 def main(argv: list[str] | None = None) -> int:
     if argv is None:
         argv = sys.argv[1:]
-    parser = argparse.ArgumentParser(
-        prog="logics-manager",
-        description="Canonical Logics CLI for workflow, validation, and runtime operations.",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=dedent(
-            """
-            Examples:
-              logics-manager flow new request --title "My request"
-              logics-manager audit
-              logics-manager config show --format json
-            """
-        ).strip(),
-    )
-    parser.add_argument("--version", action="version", version=f"logics-manager {get_cli_version()}")
-    parser.add_argument(
-        "command",
-        nargs="?",
-        choices=("bootstrap", "flow", "sync", "assist", "audit", "index", "lint", "config", "doctor", "self-update"),
-    )
-    parser.add_argument("rest", nargs=argparse.REMAINDER)
-    args = parser.parse_args(argv[:1])
-
-    if args.command is None:
-        parser.print_help()
+    if not argv:
+        _print_help(_build_root_help())
         return 1
+    if argv[0] in ("-h", "--help"):
+        _print_help(_build_root_help())
+        return 0
+    if argv[0] in {"-v", "--version"}:
+        print(f"logics-manager {get_cli_version()}")
+        return 0
+
+    command = argv[0]
+    if command not in ROOT_COMMANDS:
+        raise SystemExit(f"Unsupported command: {command}")
 
     rest = argv[1:]
-    if args.command == "config":
+    if command == "config":
         if not rest or rest[0] != "show":
             raise SystemExit("Usage: logics-manager config show [args...]")
         config_args = rest[1:]
@@ -82,7 +156,7 @@ def main(argv: list[str] | None = None) -> int:
             raise SystemExit(str(exc)) from exc
         print(output)
         return 0
-    if args.command == "doctor":
+    if command == "doctor":
         doctor_args = rest
         parser = argparse.ArgumentParser(prog="logics-manager doctor", add_help=False)
         parser.add_argument("--format", choices=("text", "json"), default="text")
@@ -94,7 +168,7 @@ def main(argv: list[str] | None = None) -> int:
             raise SystemExit(str(exc)) from exc
         print(output)
         return 0
-    if args.command == "bootstrap":
+    if command == "bootstrap":
         parser = argparse.ArgumentParser(prog="logics-manager bootstrap", add_help=False)
         parser.add_argument("--check", action="store_true")
         parser.add_argument("--format", choices=("text", "json"), default="text")
@@ -106,7 +180,7 @@ def main(argv: list[str] | None = None) -> int:
         payload = bootstrap_payload(repo_root, check=parsed.check)
         print(render_bootstrap(payload, output_format=parsed.format))
         return 0 if payload["ok"] else 1
-    if args.command == "self-update":
+    if command == "self-update":
         parser = argparse.ArgumentParser(prog="logics-manager self-update", add_help=False)
         parser.add_argument("--manager", choices=("auto", "pip", "npm"), default="auto")
         parser.add_argument("--package", default=DEFAULT_SELF_UPDATE_PACKAGE)
@@ -141,21 +215,25 @@ def main(argv: list[str] | None = None) -> int:
             target = parsed.python_package if manager == "pip" else parsed.package
             print(f"Updated {target} via {manager}.")
         return result.returncode
-    if args.command == "flow" and rest[:1] in (["new"], ["companion"], ["promote"], ["split"], ["close"], ["finish"]):
+    if command == "flow" and (rest[:1] in (["new"], ["list"], ["companion"], ["promote"], ["split"], ["close"], ["finish"]) or rest[:1] in HELP_ARGV):
         from .flow import main as flow_main
 
         return flow_main(rest)
-    if args.command == "sync":
-        if rest[:1] not in (["close-eligible-requests"], ["refresh-mermaid-signatures"], ["schema-status"], ["context-pack"], ["export-graph"]):
+    if command == "sync":
+        if rest[:1] not in (["close-eligible-requests"], ["refresh-mermaid-signatures"], ["schema-status"], ["read-doc"], ["list-docs"], ["search-docs"], ["update-indicators"], ["append-note"], ["context-pack"], ["export-graph"]) and rest[:1] not in HELP_ARGV:
             raise SystemExit("Unsupported sync subcommand for the native CLI slice.")
         from .sync import main as sync_main
 
         return sync_main(rest)
-    if args.command == "assist":
-        if rest[:1] not in (["runtime-status"], ["diff-risk"], ["commit-plan"], ["changed-surface-summary"], ["doc-consistency"], ["review-checklist"], ["validation-checklist"], ["validation-summary"], ["test-impact-summary"], ["roi-report"], ["next-step"], ["claude-bridges"], ["claude-instructions"], ["request-draft"], ["spec-first-pass"], ["backlog-groom"], ["closure-summary"], ["context"]):
+    if command == "assist":
+        if rest[:1] not in (["runtime-status"], ["diff-risk"], ["commit-plan"], ["changed-surface-summary"], ["doc-consistency"], ["review-checklist"], ["validation-checklist"], ["validation-summary"], ["test-impact-summary"], ["roi-report"], ["next-step"], ["claude-bridges"], ["claude-instructions"], ["request-draft"], ["spec-first-pass"], ["backlog-groom"], ["closure-summary"], ["context"]) and rest[:1] not in HELP_ARGV:
             raise SystemExit("Unsupported assist subcommand for the native CLI slice.")
         return assist_main(rest)
-    if args.command == "audit":
+    if command == "mcp":
+        from .mcp import main as mcp_main
+
+        return mcp_main(rest)
+    if command == "audit":
         audit_parser = build_audit_parser()
         parsed, _unknown = audit_parser.parse_known_args(rest)
         repo_root = find_repo_root(Path.cwd())
@@ -195,7 +273,7 @@ def main(argv: list[str] | None = None) -> int:
             raise SystemExit(str(exc)) from exc
         print(output)
         return 0 if payload["ok"] else 1
-    if args.command == "index":
+    if command == "index":
         parser = argparse.ArgumentParser(prog="logics-manager index", add_help=False)
         parser.add_argument("--out", default="logics/INDEX.md")
         parser.add_argument("--format", choices=("text", "json"), default="text")
@@ -208,7 +286,7 @@ def main(argv: list[str] | None = None) -> int:
         output = render_index(repo_root, out=parsed.out, output_format=parsed.format) if parsed.format == "json" else f"Wrote {payload['output_path']}"
         print(output)
         return 0 if payload["ok"] else 1
-    if args.command == "lint":
+    if command == "lint":
         parser = argparse.ArgumentParser(prog="logics-manager lint", add_help=False)
         parser.add_argument("--require-status", action="store_true")
         parser.add_argument("--format", choices=("text", "json"), default="text")
@@ -221,4 +299,4 @@ def main(argv: list[str] | None = None) -> int:
             raise SystemExit(str(exc)) from exc
         print(output)
         return 0 if payload["ok"] else 1
-    raise SystemExit(f"Unsupported command: {args.command}")
+    raise SystemExit(f"Unsupported command: {command}")