stackops 26.9.3__tar.gz → 26.9.4__tar.gz

stackops-26.9.4/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: stackops
+Version: 26.9.4
+Summary: Developer Stack Manager
+Author-email: Alex Al-Saffar <programmer@usa.com>
+License: Apache 2.0
+Project-URL: Homepage, https://github.com/thisismygitrepo/stackops
+Project-URL: Bug Tracker, https://github.com/thisismygitrepo/stackops/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: fire>=0.7.1
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: randomname>=0.2.1
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.3.3
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: textual>=8.2.7
+Requires-Dist: typer>=0.24.1
+Provides-Extra: windows
+Provides-Extra: plot
+Requires-Dist: duckdb>=1.5.4; extra == "plot"
+Requires-Dist: duckdb-engine>=0.17.0; extra == "plot"
+Requires-Dist: ipykernel>=7.3.0; extra == "plot"
+Requires-Dist: ipython>=9.15.0; extra == "plot"
+Requires-Dist: jupyterlab>=4.6.0; extra == "plot"
+Requires-Dist: kaleido>=1.3.0; extra == "plot"
+Requires-Dist: matplotlib>=3.11.0; extra == "plot"
+Requires-Dist: nbformat>=5.10.4; extra == "plot"
+Requires-Dist: numpy>=2.5.0; extra == "plot"
+Requires-Dist: plotly>=6.8.0; extra == "plot"
+Requires-Dist: polars>=1.42.0; extra == "plot"
+Requires-Dist: python-magic>=0.4.27; extra == "plot"
+Requires-Dist: sqlalchemy>=2.0.51; extra == "plot"
+
+<div align="center">
+
+<h1>🗜 StackOps</h1>
+
+<strong>Developer workstation and workflow CLI.</strong>
+
+<p>
+  <a href="https://thisismygitrepo.github.io/stackops/"><img alt="Docs" src="https://img.shields.io/badge/docs-online-2f6f6f"></a>
+  <a href="https://pypi.org/project/stackops/"><img alt="PyPI package" src="https://img.shields.io/pypi/v/stackops?color=2f6f6f"></a>
+  <img alt="Python 3.13+" src="https://img.shields.io/badge/python-3.13%2B-3776AB">
+  <img alt="Installed with uv" src="https://img.shields.io/badge/install-uv-f05d23">
+</p>
+
+</div>
+
+StackOps coordinates packages, configuration, repositories, data, terminal layouts, and coding-agent resources around the tools you already use. Install selected packages, synchronize declared configuration, or launch an authored tmux workspace through focused commands. Available installers and integrations vary by operating system and external tool.
+
+See the [online docs](https://thisismygitrepo.github.io/stackops/) for full usage and reference material.
+
+## Install
+
+Choose your platform and expand only the commands you need.
+
+<details>
+<summary><strong>Linux</strong></summary>
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install --upgrade --python 3.14 stackops
+stackops --help
+```
+
+</details>
+
+<details>
+<summary><strong>macOS</strong></summary>
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install --upgrade --python 3.14 stackops
+stackops --help
+```
+
+</details>
+
+<details>
+<summary><strong>Windows PowerShell</strong></summary>
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
+uv tool install --upgrade --python 3.14 stackops
+stackops --help
+```
+
+</details>
+
+
+## Codex Skill
+
+Install the StackOps skill for Codex with:
+
+```bash
+bunx skills add thisismygitrepo/stackops --skill stackops --global --agent codex --yes
+```
+
+
+## Start with a workflow
+
+Inspect the commands for the workflow you need:
+
+```bash
+devops install --help
+devops config sync --help
+terminal run --help
+```
+
+The [quickstart](https://thisismygitrepo.github.io/stackops/quickstart/) shows a selected-package example and configuration options.
+
+## Optional workstation setup
+
+This broader setup installs system and terminal package groups, copies bundled assets, applies public configuration mappings, and configures the default shell. Use it when you want those workstation conventions; existing customized systems can use individual commands instead. Package-group behavior depends on the platform and may invoke privileged package managers.
+
+```bash
+devops install --group sysabc
+devops config copy-assets all
+devops config sync down \
+  --sensitivity public \
+  --method copy \
+  --on-conflict throw-error \
+  --which all
+devops config terminal config-shell --which default
+devops install --group termabc
+```
+
+The scripted sync above copies configuration and stops on conflicts. The public copy/symlink choices in `devops config interactive` use `overwrite-default-path` and can replace existing targets; they are a different setup choice.
+
+
+## CLI
+
+StackOps exposes standalone commands and an umbrella wrapper:
+
+| Command | Purpose |
+| --- | --- |
+| `devops` | Package installation, repo automation, config/data sync, self-management, networking, script execution, vault |
+| `cloud` | Cloud sync, copy, mount, SSH transfer, and OneDrive helpers |
+| `terminal` | Terminal session and layout management |
+| `agents` | AI agent scaffolding, MCP catalog installs, prompt runs, parallel workflows |
+| `utils` | General-purpose utility commands |
+| `fire` | File, function, notebook, and app runner |
+| `preview` | File preview and `uv run` backend launcher |
+| `seek` | Interactive search across files, text matches, and symbols |
+| `stackops` | Umbrella wrapper that routes into all of the above |
+
+Run `<command> --help` for details, or `stackops --help` to see the command families.
+
+
+## Author
+
+Alex Al-Saffar. [email](mailto:programmer@usa.com)
+
+## Contributor
+
+Ruby Chan. [email](mailto:ruby.chan@sa.gov.au)

stackops-26.9.4/pyproject.toml

@@ -0,0 +1,179 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+# requires = ["hatchling"]
+# build-backend = "hatchling.build"
+
+[project]
+name = "stackops"
+version = "26.9.4"
+description = "Developer Stack Manager"
+readme = "README.md"
+license = {text = "Apache 2.0"}
+authors = [
+    {name = "Alex Al-Saffar", email = "programmer@usa.com"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fire>=0.7.1",
+    "gitpython>=3.1.46",
+    "psutil>=7.2.2",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "randomname>=0.2.1",
+    "requests>=2.32.5",
+    "rich>=14.3.3",
+    "tenacity>=9.1.4",
+    "textual>=8.2.7",
+    "typer>=0.24.1",
+]
+
+[project.optional-dependencies]
+windows = []
+plot = [
+    "duckdb>=1.5.4",
+    "duckdb-engine>=0.17.0",
+    "ipykernel>=7.3.0",
+    "ipython>=9.15.0",
+    "jupyterlab>=4.6.0",
+    "kaleido>=1.3.0",
+    "matplotlib>=3.11.0",
+    "nbformat>=5.10.4",
+    "numpy>=2.5.0",
+    "plotly>=6.8.0",
+    "polars>=1.42.0",
+    "python-magic>=0.4.27",
+    "sqlalchemy>=2.0.51",
+]
+
+
+[project.urls]
+"Homepage" = "https://github.com/thisismygitrepo/stackops"
+"Bug Tracker" = "https://github.com/thisismygitrepo/stackops/issues"
+
+[project.scripts]
+devops = "stackops.scripts.python.devops:main"
+cloud = "stackops.scripts.python.cloud:main"
+fire = "stackops.scripts.python.fire_jobs:main"
+agents = "stackops.scripts.python.agents:main"
+terminal = "stackops.scripts.python.terminal:main"
+preview = "stackops.scripts.python.preview:main"
+utils = "stackops.scripts.python.utils:main"
+stackops = "stackops.scripts.python.stackops_entry:main"
+seek = "stackops.scripts.python.seek:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+license-files = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stackops = ["**/*.toml", "**/*.md", "**/*.sh", "**/*.ps1", "**/*.txt", "utils/schemas/**/*.json", "utils/schemas/**/*.yaml"]
+
+[dependency-groups]
+dev = [
+    "aider>=0.2.6",
+    "build>=1.5.0",
+    "cleanpy>=0.5.1",
+    "cowsay>=6.1",
+    "duckdb>=1.5.4",
+    "gdown>=6.1.0",
+    "griffe>=2.1.0",
+    "ipdb>=0.13.13",
+    "ipykernel>=7.3.0",
+    "ipython>=9.15.0",
+    "jsonschema>=4.26.0",
+    "kaleido>=1.3.0",
+    "marimo>=0.23.11",
+    "matplotlib>=3.11.0",
+    "mkdocstrings>=1.0.4",
+    "mkdocstrings-python>=2.0.5",
+    "mypy>=2.1.0",
+    "numpy>=2.5.0",
+    "pandas>=3.0.3",
+    "paramiko>=5.0.0",
+    "playwright>=1.62.0",
+    "plotly>=6.8.0",
+    "polars>=1.42.0",
+    "pre-commit>=4.6.0",
+    "pudb>=2025.1.5",
+    "py7zr>=1.1.3",
+    "pydantic>=2.13.4",
+    "pydeps>=3.0.6",
+    "pyinstaller>=6.21.0",
+    "pylint>=4.0.6",
+    "pylsp-mypy>=0.7.3",
+    "pymupdf>=1.27.2.3",
+    "pypdf>=6.14.2",
+    "pyrefly>=1.1.1",
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "python-lsp-server[mypy]>=1.14.0",
+    "qrcode>=8.2",
+    "ruff>=0.15.20",
+    "ruff-lsp>=0.0.62",
+    "sqlalchemy>=2.0.51",
+    "trogon>=0.6.0",
+    "ty>=0.0.55",
+    "types-mysqlclient>=2.2.0.20260508",
+    "types-paramiko>=5.0.0.20260617",
+    "types-pytz>=2026.2.0.20260518",
+    "types-pyyaml>=6.0.12.20260518",
+    "types-requests>=2.33.0.20260518",
+    "types-sqlalchemy>=1.4.53.38",
+    "types-toml>=0.10.8.20260518",
+    "types-urllib3>=1.26.25.14",
+    "vt-py>=0.22.0",
+    "yapf>=0.43.0",
+    "zensical>=0.0.46",
+]
+other = [
+    "duckdb-engine>=0.17.0",
+    "pycrucible>=0.4.6",
+    "vt-py>=0.22.0",
+]
+plot = [
+    "duckdb>=1.5.4",
+    "ipykernel>=7.3.0",
+    "ipython>=9.15.0",
+    "jupyterlab>=4.6.0",
+    "kaleido>=1.3.0",
+    "matplotlib>=3.11.0",
+    "nbformat>=5.10.4",
+    "numpy>=2.5.0",
+    "plotly>=6.8.0",
+    "polars>=1.42.0",
+    "python-magic>=0.4.27",
+    "sqlalchemy>=2.0.51",
+]
+
+
+# [tool.uv]
+# default-groups = []
+
+[tool.pycrucible]
+entry = "src/stackops/scripts/python/devops.py"
+[tool.pycrucible.options]
+debug = false
+extract_to_temp = false
+delete_after_run = false
+offline_mode = false
+
+[tool.pycrucible.patterns]
+include = [
+    "**/*.py",
+    "**/*.ps1",
+    "**/*.sh",
+    "**/*.md",
+]
+exclude = [
+    "**/__pycache__/**",
+]

stackops-26.9.4/src/stackops/architecture_graph/cli.py

@@ -0,0 +1,70 @@
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from stackops.architecture_graph.graph import build_graph_page_payload
+from stackops.architecture_graph.renderer import write_html
+
+DEFAULT_DEPTH = 1
+DEFAULT_MAX_DEPTH = 3
+DEFAULT_OUTPUT_PATH = Path(".ai/architecture_dependencies.html")
+DEFAULT_PACKAGE_NAME = "stackops"
+DEFAULT_SOURCE_ROOT = Path("src/stackops")
+
+
+@dataclass(frozen=True, slots=True)
+class CliArgs:
+    source_root: Path
+    package_name: str
+    output_path: Path
+    depth: int
+    max_depth: int
+
+
+def main() -> None:
+    args = parse_cli_args()
+    if not args.source_root.exists():
+        raise SystemExit(f"source root does not exist: {args.source_root}")
+    payload = build_graph_page_payload(
+        source_root=args.source_root,
+        package_name=args.package_name,
+        initial_depth=args.depth,
+        max_depth=args.max_depth,
+    )
+    output_path = write_html(payload=payload, output_path=args.output_path)
+    print(f"Wrote {output_path}")
+
+
+def parse_cli_args() -> CliArgs:
+    parser = build_parser()
+    namespace = parser.parse_args()
+    source_root = cast(Path, getattr(namespace, "source_root"))
+    package_name = cast(str, getattr(namespace, "package_name"))
+    output_path = cast(Path, getattr(namespace, "output_path"))
+    depth = cast(int, getattr(namespace, "depth"))
+    max_depth = cast(int, getattr(namespace, "max_depth"))
+    if depth < 0:
+        raise SystemExit("--depth must be zero or greater")
+    if max_depth < depth:
+        raise SystemExit("--max-depth must be greater than or equal to --depth")
+    return CliArgs(
+        source_root=source_root,
+        package_name=package_name,
+        output_path=output_path,
+        depth=depth,
+        max_depth=max_depth,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m stackops.architecture_graph",
+        description="Generate an interactive HTML dependency graph for StackOps.",
+    )
+    parser.add_argument("--source-root", "-s", type=Path, default=DEFAULT_SOURCE_ROOT)
+    parser.add_argument("--package-name", "-p", default=DEFAULT_PACKAGE_NAME)
+    parser.add_argument("--output", "-o", dest="output_path", type=Path, default=DEFAULT_OUTPUT_PATH)
+    parser.add_argument("--depth", "-d", type=int, default=DEFAULT_DEPTH)
+    parser.add_argument("--max-depth", "-m", type=int, default=DEFAULT_MAX_DEPTH)
+    return parser

stackops-26.9.4/src/stackops/jobs/installer/checks/security_cli.py

@@ -0,0 +1,226 @@
+from functools import cache
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Literal
+
+import typer
+
+from stackops.jobs.installer.checks.security_helper import parse_apps_argument
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from rich.table import Table
+
+
+ReportFormat = Literal["table", "csv"]
+ReportView = Literal["engines", "app-summary", "apps", "options", "stats"]
+
+
+@cache
+def _console() -> Console:
+    from rich.console import Console
+
+    return Console()
+
+
+def _resolve_report_view(view: ReportView | None, summarize: bool) -> ReportView:
+    if view is not None:
+        return view
+    return "app-summary" if summarize else "engines"
+
+
+def _run_scan(app_names: list[str] | None, path_value: str | None, record: bool) -> None:
+    if path_value is not None:
+        from pathlib import Path
+
+        from stackops.jobs.installer.checks.security_helper import scan_single_path
+
+        scan_single_path(Path(path_value), record)
+    else:
+        from stackops.jobs.installer.checks.check_installations import scan_installed_apps
+
+        scan_installed_apps(app_names, write_reports_to_repo=record)
+
+
+def scan(
+    apps: Annotated[str | None, typer.Argument(help="Optional comma-separated app names to scan")] = None,
+    path: Annotated[
+        Path | None,
+        typer.Option(
+            "--path", "-p", help="Optional file path to scan instead of installed apps", exists=True, file_okay=True, dir_okay=False, resolve_path=True
+        ),
+    ] = None,
+    record: Annotated[
+        bool | None,
+        typer.Option(
+            "--record",
+            "-r",
+            help="Write scan results to the saved repo reports. Installed-app scans already record by default.",
+        ),
+    ] = None,
+) -> None:
+    if apps is not None and path is not None:
+        raise typer.BadParameter("Use either APPS or --path, not both.")
+    app_names = parse_apps_argument(apps)
+    path_value = str(path) if path is not None else None
+    resolved_record = record if record is not None else path is None
+
+    from stackops.utils.code import run_lambda_function
+
+    proc = run_lambda_function(
+        lambda: _run_scan(app_names=app_names, path_value=path_value, record=resolved_record),
+        uv_with=["vt-py"],
+        uv_project_dir=None,
+    )
+    if proc.returncode != 0:
+        raise typer.Exit(code=proc.returncode)
+
+
+def _build_apps_table(apps_to_scan: list[tuple[Path, str | None]]) -> Table:
+    import stackops.utils.path_core as path_core
+    from rich.table import Table
+
+    table = Table(title="Installed CLI Apps", show_lines=False)
+    table.add_column("Name")
+    table.add_column("Version", justify="right")
+    table.add_column("Path")
+    for app_path, version in apps_to_scan:
+        table.add_row(app_path.stem, version or "", path_core.collapseuser(app_path, strict=False).as_posix())
+    return table
+
+
+def list_apps(apps: Annotated[str | None, typer.Argument(help="Optional comma-separated app names to list")] = None) -> None:
+    from stackops.jobs.installer.checks.check_installations import collect_apps_to_scan
+
+    apps_names = parse_apps_argument(apps)
+    apps_to_scan = collect_apps_to_scan(apps_names)
+    if not apps_to_scan:
+        if apps_names is None:
+            typer.echo("No installed CLI apps found.", err=True)
+        else:
+            typer.echo(f"""No installed CLI apps matched: {", ".join(apps_names)}""", err=True)
+        raise typer.Exit(code=1)
+    _console().print(_build_apps_table(apps_to_scan))
+
+
+def upload(path: Annotated[Path, typer.Argument(..., help="Path to a local file to upload")]) -> None:
+    from stackops.jobs.installer.checks.install_utils import upload_app
+
+    link = upload_app(path)
+    if not link:
+        raise typer.Exit(code=1)
+    _console().print(link)
+
+
+def download(url: Annotated[str, typer.Argument(..., help="Google Drive URL or file id")]) -> None:
+    from stackops.jobs.installer.checks.install_utils import download_google_drive_file
+
+    path = download_google_drive_file(url)
+    _console().print(path.as_posix())
+
+
+def install(name: Annotated[str, typer.Argument(..., help="App name from app metadata report or 'essentials'")]) -> None:
+    from stackops.jobs.installer.checks.install_utils import download_safe_apps
+
+    if not download_safe_apps(name):
+        raise typer.Exit(code=1)
+
+
+def summary() -> None:
+    report(view="stats")
+
+
+def report(
+    apps: Annotated[str | None, typer.Argument(help="Optional comma-separated app names to show")] = None,
+    view: Annotated[
+        ReportView | None, typer.Option("--view", "-v", help="Which report view to show", case_sensitive=False, show_choices=True)
+    ] = None,
+    format_type: Annotated[
+        ReportFormat, typer.Option("--format", "-f", help="Output format for apps or engines views", case_sensitive=False, show_choices=True)
+    ] = "table",
+    summarize: Annotated[bool, typer.Option("--summarize", "-s", hidden=True)] = False,
+) -> None:
+    resolved_view = _resolve_report_view(view, summarize)
+    if resolved_view == "options":
+        from stackops.jobs.installer.checks.security_helper import build_report_options_text
+
+        _console().print(build_report_options_text())
+        return
+    if resolved_view not in {"apps", "engines"} and format_type != "table":
+        raise typer.BadParameter("--format csv is only supported with --view apps or --view engines.")
+
+    from stackops.jobs.installer.checks.security_helper import (
+        load_filtered_report_rows,
+        normalize_app_names,
+    )
+
+    apps_names = parse_apps_argument(apps)
+    normalized_app_names = normalize_app_names(apps_names)
+    app_rows, engine_rows, app_data_list, hydrated_engine_rows = load_filtered_report_rows(normalized_app_names)
+
+    if resolved_view == "stats":
+        from stackops.jobs.installer.checks.install_utils import APP_METADATA_PATH, ENGINE_RESULTS_PATH
+        from stackops.jobs.installer.checks.security_helper import build_report_stats_lines
+
+        if not app_data_list:
+            raise typer.Exit(code=1)
+        for line in build_report_stats_lines(app_data_list, APP_METADATA_PATH, ENGINE_RESULTS_PATH):
+            _console().print(line)
+        return
+    if resolved_view == "app-summary":
+        from stackops.jobs.installer.checks.report_utils import build_summary_group
+
+        if not app_data_list:
+            raise typer.Exit(code=1)
+        _console().print(build_summary_group(app_data_list))
+        return
+    if resolved_view == "apps":
+        from stackops.jobs.installer.checks.report_utils import APP_METADATA_KEYS
+
+        if not app_rows:
+            raise typer.Exit(code=1)
+        if format_type == "csv":
+            from stackops.jobs.installer.checks.security_helper import render_csv_text
+
+            _console().print(render_csv_text(app_rows, APP_METADATA_KEYS))
+            return
+        from stackops.jobs.installer.checks.security_helper import build_raw_csv_table
+
+        _console().print(build_raw_csv_table("App Metadata CSV", app_rows, APP_METADATA_KEYS))
+        return
+    if not engine_rows:
+        raise typer.Exit(code=1)
+    if format_type == "csv":
+        from stackops.jobs.installer.checks.report_utils import ENGINE_REPORT_KEYS
+        from stackops.jobs.installer.checks.security_helper import render_csv_text
+
+        _console().print(render_csv_text(engine_rows, ENGINE_REPORT_KEYS))
+        return
+    from stackops.jobs.installer.checks.report_utils import build_engine_results_table
+
+    _console().print(build_engine_results_table(hydrated_engine_rows))
+
+
+def get_app() -> typer.Typer:
+    app = typer.Typer(
+        name="security-cli",
+        help="Security related CLI tools.",
+        no_args_is_help=True,
+        add_help_option=True,
+        add_completion=False,
+        context_settings={"help_option_names": ["-h", "--help"]},
+    )
+
+    app.command(name="scan", help="<s> Scan installed apps or a single file path with VirusTotal", no_args_is_help=True)(scan)
+    app.command(name="s", help="<s> Scan installed apps or a single file path with VirusTotal", hidden=True, no_args_is_help=True)(scan)
+    app.command(name="list", help="<l> List installed apps, optionally filtered by comma-separated app names")(list_apps)
+    app.command(name="l", help="<l> List installed apps, optionally filtered by comma-separated app names", hidden=True)(list_apps)
+    app.command(name="upload", help="<u> Upload a local file to cloud storage", no_args_is_help=True)(upload)
+    app.command(name="u", help="<u> Upload a local file to cloud storage", hidden=True, no_args_is_help=True)(upload)
+    app.command(name="download", help="<d> Download a file from Google Drive", no_args_is_help=True)(download)
+    app.command(name="d", help="<d> Download a file from Google Drive", hidden=True, no_args_is_help=True)(download)
+    app.command(name="install", help="<i> Install safe apps from app metadata report", no_args_is_help=True)(install)
+    app.command(name="i", help="<i> Install safe apps from app metadata report", hidden=True, no_args_is_help=True)(install)
+    app.command(name="report", help="<r> Show the full saved scan report by default, or CSV rows/summary stats")(report)
+    app.command(name="r", help="<r> Show the full saved scan report by default, or CSV rows/summary stats", hidden=True)(report)
+
+    return app