shellscripts 0.23.1__py3-none-any.whl

shell_scripts/commands/doxygen_cmd.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+import os
+import shutil
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from shell_scripts.utils import require_project_root, require_commands, print_error
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Generate Doxygen documentation (HTML, PDF, Markdown)."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} doxygen ({version})")
+    print()
+    print("doxygen options:")
+    print("  --help  - Show this help message.")
+    print()
+    print("Generates HTML, PDF, and Markdown documentation in doxygen/ directory.")
+    print("Requires: doxygen, make, pdflatex.")
+
+
+def _supports_generate_markdown():
+    require_commands("doxygen")
+    try:
+        result = subprocess.run(
+            ["doxygen", "-x"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return "GENERATE_MARKDOWN" in result.stdout
+    except Exception:
+        return False
+
+
+def _write_doxyfile(path, project_root, src_dir, doxygen_dir, has_md):
+    content = f"""PROJECT_NAME           = "{project_root.name}"
+OUTPUT_DIRECTORY       = "{doxygen_dir}"
+INPUT                  = "{src_dir}"
+FILE_PATTERNS          = *.py *.sh *.js *.ts *.go *.java *.c *.cpp *.h *.hpp *.rb *.php *.rs *.swift *.kt *.scala *.lua *.r *.m *.mm *.cs
+RECURSIVE              = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_ANON_NSPACES   = YES
+JAVADOC_AUTOBRIEF      = YES
+MULTILINE_CPP_IS_BRIEF = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = YES
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = "{project_root}"
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+QUIET                  = YES
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_LATEX         = YES
+LATEX_OUTPUT           = latex
+USE_PDFLATEX           = YES
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+MARKDOWN_ID_STYLE      = GITHUB
+TOC_INCLUDE_HEADINGS   = 3
+"""
+    if has_md:
+        content += "GENERATE_MARKDOWN      = YES\nMARKDOWN_OUTPUT        = markdown\n"
+
+    Path(path).write_text(content)
+
+
+def _generate_markdown_fallback(xml_dir, markdown_dir):
+    markdown_dir.mkdir(parents=True, exist_ok=True)
+    index_xml = xml_dir / "index.xml"
+    if not index_xml.exists():
+        return
+
+    root = ET.parse(str(index_xml)).getroot()
+    entries = []
+    for compound in root.findall("compound"):
+        name = (compound.findtext("name") or "").strip()
+        kind = (compound.get("kind") or "").strip()
+        refid = (compound.get("refid") or "").strip()
+        if name:
+            entries.append((kind, name, refid))
+
+    entries.sort(key=lambda item: (item[0], item[1]))
+    lines = ["# Doxygen Markdown Index", "", "Generated from Doxygen XML output.", ""]
+    for kind, name, refid in entries:
+        lines.append(f"- `{kind}` `{name}` (`{refid}`)")
+
+    (markdown_dir / "index.md").write_text("\n".join(lines) + "\n")
+
+
+def run(args):
+    project_root = require_project_root()
+    os.chdir(project_root)
+
+    require_commands("doxygen")
+
+    src_dir = project_root / "src"
+    doxygen_dir = project_root / "doxygen"
+    html_dir = doxygen_dir / "html"
+    markdown_dir = doxygen_dir / "markdown"
+    pdf_dir = doxygen_dir / "pdf"
+    latex_dir = doxygen_dir / "latex"
+    xml_dir = doxygen_dir / "xml"
+
+    if not src_dir.is_dir():
+        print_error(f"Source directory not found: {src_dir}")
+        return 1
+
+    has_md = _supports_generate_markdown()
+
+    for d in (html_dir, markdown_dir, pdf_dir, latex_dir, xml_dir):
+        if d.exists():
+            shutil.rmtree(d)
+    doxygen_dir.mkdir(parents=True, exist_ok=True)
+    pdf_dir.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".conf", delete=False) as f:
+        doxyfile = f.name
+    try:
+        _write_doxyfile(doxyfile, project_root, src_dir, doxygen_dir, has_md)
+        result = subprocess.run(["doxygen", doxyfile])
+        if result.returncode != 0:
+            print_error("Doxygen generation failed.")
+            return 1
+    finally:
+        os.unlink(doxyfile)
+
+    if not has_md:
+        _generate_markdown_fallback(xml_dir, markdown_dir)
+
+    makefile = latex_dir / "Makefile"
+    if makefile.exists():
+        from shell_scripts.utils import command_exists
+
+        if command_exists("make") and command_exists("pdflatex"):
+            require_commands("make", "pdflatex")
+            subprocess.run(["make", "-C", str(latex_dir)], stdout=subprocess.DEVNULL)
+            refman = latex_dir / "refman.pdf"
+            if refman.exists():
+                shutil.copy2(str(refman), str(pdf_dir / "refman.pdf"))
+            else:
+                print_error(f"PDF artifact not generated: {refman}")
+        else:
+            print_error("'make' or 'pdflatex' not found; skipping PDF build.")
+
+    print(f"Generated: {html_dir}")
+    print(f"Generated: {markdown_dir}")
+    if (pdf_dir / "refman.pdf").exists():
+        print(f"Generated: {pdf_dir / 'refman.pdf'}")
+
+    return 0

shell_scripts/commands/edit_cmd.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""@brief MIME-based edit command wrapper.
+
+@details Exposes the `edit` CLI command and delegates category-based executable
+selection to shared `_dc_common.dispatch` logic.
+@satisfies PRJ-003, DES-007, REQ-023, REQ-024
+"""
+
+import sys
+
+from shell_scripts.config import get_dispatch_profile
+from shell_scripts.commands._dc_common import dispatch
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "File editor dispatcher by MIME type."
+
+
+def print_help(version):
+    """@brief Render command help for `edit`.
+
+    @details Prints usage, required file argument semantics, and argument
+    forwarding contract for the selected external editor executable.
+    @param version {str} Version string appended in usage output.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+    print(f"Usage: {PROGRAM} edit <file> [args...] ({version})")
+    print()
+    print("edit options:")
+    print("  <file>   - File to edit (required).")
+    print("  Additional arguments are passed to the selected editor.")
+    print("  --help   - Show this help message.")
+
+
+def run(args):
+    """@brief Execute MIME-routed edit dispatch.
+
+    @details Validates that a file argument exists; on missing argument prints
+    error plus help and returns status code `2`; otherwise resolves runtime
+    dispatch profile and delegates by file category through shared `_dc_common`.
+    @param args {list[str]} CLI args where `args[0]` is file path.
+    @return {int} Return code `2` on missing file; otherwise delegated dispatch result.
+    @satisfies REQ-023, REQ-024
+    """
+    if not args:
+        print("Error: file argument required.", file=sys.stderr)
+        print_help("")
+        return 2
+    category_cmds, fallback = get_dispatch_profile("edit")
+    return dispatch(category_cmds, fallback, args[0], args[1:])

shell_scripts/commands/gemini.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""@brief Google Gemini CLI launcher in project context.
+
+@details Ensures project-root prerequisite and executable availability before
+blocking subprocess invocation of `gemini`.
+@satisfies REQ-016, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch Google Gemini CLI in the project context."
+
+
+def print_help(version):
+    """@brief Print command-specific help for `gemini`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} gemini [args...] ({version})")
+    print()
+    print("gemini options:")
+    print("  All arguments are passed through to the Gemini CLI.")
+    print("  --help  - Show this help message.")
+
+
+def run(args):
+    """@brief Launch Gemini CLI after external executable validation.
+
+    @details Resolves project root, checks executable availability for
+    `gemini`, then executes pass-through args through blocking subprocess run.
+    @param args {list[str]} Additional CLI args forwarded to Gemini.
+    @return {int} Child process return code.
+    @satisfies REQ-016, REQ-055, REQ-056, REQ-064
+    """
+
+    require_project_root()
+    cmd = ["gemini", "--yolo"] + args
+    cmd[0] = require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/kiro.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""@brief Kiro CLI launcher in project context.
+
+@details Ensures project-root prerequisite and executable availability before
+blocking subprocess invocation of `kiro-cli`.
+@satisfies REQ-019, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch Kiro CLI in the project context."
+
+
+def print_help(version):
+    """@brief Print command-specific help for `kiro`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} kiro [args...] ({version})")
+    print()
+    print("kiro options:")
+    print("  All arguments are passed through to the Kiro CLI.")
+    print("  --help  - Show this help message.")
+
+
+def run(args):
+    """@brief Launch Kiro CLI after external executable validation.
+
+    @details Resolves project root, validates executable availability for
+    `kiro-cli`, then executes pass-through args through blocking subprocess run.
+    @param args {list[str]} Additional CLI args forwarded to Kiro.
+    @return {int} Child process return code.
+    @satisfies REQ-019, REQ-055, REQ-056, REQ-064
+    """
+
+    require_project_root()
+    cmd = ["kiro-cli"] + args
+    cmd[0] = require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/opencode.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""@brief OpenCode CLI launcher in project context.
+
+@details Ensures project-root prerequisite and executable availability before
+blocking subprocess invocation of `opencode`.
+@satisfies REQ-018, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch OpenCode CLI in the project context."
+
+
+def print_help(version):
+    """@brief Print command-specific help for `opencode`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} opencode [args...] ({version})")
+    print()
+    print("opencode options:")
+    print("  All arguments are passed through to the OpenCode CLI.")
+    print("  --help  - Show this help message.")
+
+
+def run(args):
+    """@brief Launch OpenCode CLI after external executable validation.
+
+    @details Resolves project root, checks executable availability for
+    `opencode`, then executes pass-through args through blocking subprocess run.
+    @param args {list[str]} Additional CLI args forwarded to OpenCode.
+    @return {int} Child process return code.
+    @satisfies REQ-018, REQ-055, REQ-056, REQ-064
+    """
+
+    require_project_root()
+    cmd = ["opencode"] + args
+    cmd[0] = require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode