stackops 26.11__tar.gz → 26.11.1__tar.gz

stackops-26.11.1/.codex/config.toml

@@ -0,0 +1,26 @@
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+allow_login_shell = false
+web_search = "live"
+project_doc_max_bytes = 32768
+project_doc_fallback_filenames = []
+mcp_oauth_credentials_store = "auto"
+
+[sandbox_workspace_write]
+network_access = true
+
+[features]
+multi_agent = true
+remote_models = true
+
+[tui]
+status_line = ["model-with-reasoning", "context-remaining", "current-dir", "model-name", "project-root", "git-branch", "context-used", "five-hour-limit"]
+
+[analytics]
+enabled = false
+
+[history]
+persistence = "none"
+
+[feedback]
+enabled = false

stackops-26.11.1/.devcontainer/devcontainer.json

@@ -0,0 +1,63 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
+{
+	"name": "MAC_CFG",
+	// "build": {
+	// 	// Sets the run context to one level up instead of the .devcontainer folder.
+	// 	"context": "..",
+	// 	// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
+	// 	"dockerfile": "../Dockerfile"
+	// }
+	"image": "statistician/stackops-slim:latest",
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {
+
+	// },
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Uncomment the next line to run commands after the container is created.
+	// "postCreateCommand": "cat /etc/os-release",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"GitHub.copilot",
+				"GitHub.copilot-chat",
+				"ms-toolsai.jupyter",
+				"ms-toolsai.vscode-jupyter-cell-tags",
+				"ms-toolsai.jupyter-keymap",
+				"ms-toolsai.jupyter-renderers",
+				"ms-toolsai.vscode-jupyter-slideshow",
+				"ms-python.mypy-type-checker",
+				"ms-python.vscode-pylance",
+				"ms-python.pylint",
+				"ms-python.python",
+				"ms-python.debugpy",
+				"ahmadawais.shades-of-purple",
+				"ms-vscode.vscode-speech",
+				"ms-vscode-remote.remote-containers",
+				"ms-azuretools.vscode-docker",
+				"ms-vscode.remote-server",
+				"ms-vscode.remote-explorer",
+				"ms-vscode-remote.vscode-remote-extensionpack"
+			],
+			"settings": {
+				"python.pythonPath": "/root",
+				"python.defaultInterpreterPath": ""
+			}
+		}
+	},
+
+	// Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "devcontainer"
+	"remoteUser": "root",
+	// changing this complicates the process: https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user
+	"mounts": [
+		"source=${localEnv:HOME}/data,target=/root/data,type=bind,consistency=cached",
+		"source=${localEnv:HOME}/dotfiles,target=/root/dotfiles,type=bind,consistency=cached"
+		// "target=/root/.vscode-server,type=volume"
+	]
+}

stackops-26.11.1/.dockerignore

@@ -0,0 +1,10 @@
+# Docker does not read .gitignore; exclude local-only state explicitly.
+.git/
+.ai/
+.agents/
+.cursor/
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

stackops-26.11.1/.gitattributes

@@ -0,0 +1,5 @@
+
+* text=auto eol=lf
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf
+*.{ps1,[pP][sS]1} text eol=crlf

stackops-26.11.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**StackOps CLI version**
+<!-- For example: 26.8.2 -->
+
+**Operating system / distribution**
+<!-- For example: macOS 15.6, Ubuntu 24.04, or Windows 11 -->
+
+**Python version**
+<!-- Paste `python --version` or the equivalent for the interpreter running StackOps. -->
+
+**Installation method**
+<!-- For example: uv tool, pipx, pip, or a source checkout -->
+
+**Command**
+<!-- Paste the exact command, replacing secrets and sensitive values with placeholders. -->
+```console
+
+```
+
+**Sanitized output**
+<!-- Paste the complete output or traceback. Remove credentials, tokens, private URLs, hostnames, and other sensitive values. -->
+```console
+
+```
+
+**Steps to reproduce**
+1.
+2.
+3.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

stackops-26.11.1/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

stackops-26.11.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

stackops-26.11.1/.github/PYPI_PUBLISHING_SETUP.md

@@ -0,0 +1,76 @@
+# GitHub Action PyPI Publishing Setup
+
+This repository is configured with a GitHub Action that automatically builds and publishes the package to PyPI when the version in `pyproject.toml` is updated.
+
+## How it works
+
+The workflow triggers on every push to the `main` branch and:
+
+1. **Version Check**: Checks whether the version in `pyproject.toml` is already on PyPI
+2. **Build & Publish**: Runs checks and builds the package, then publishes an unpublished version to PyPI
+3. **GitHub Release**: Creates a GitHub release with the new version tag
+4. **Test Build**: Already published versions and pull requests run checks without publishing
+
+## Setup Instructions
+
+### 1. Set up PyPI Token
+
+You need to configure a PyPI API token as a GitHub secret:
+
+1. **Generate PyPI API Token**:
+   - Go to [PyPI Account Settings](https://pypi.org/manage/account/token/)
+   - Click "Add API Token"
+   - Set token name (e.g., "GitHub Actions - stackops")
+   - Set scope to "Entire account" or limit to your package
+   - Copy the generated token (starts with `pypi-`)
+
+2. **Add GitHub Secret**:
+   - Go to your GitHub repository
+   - Navigate to Settings → Secrets and variables → Actions
+   - Click "New repository secret"
+   - Name: `PYPI_TOKEN`
+   - Value: Paste your PyPI API token
+   - Click "Add secret"
+
+### 2. Publishing a new version
+
+The developer-only `release` command is available when `~/code/stackops` is a StackOps Git checkout. It always operates on that checkout.
+
+To prepare a release for local review:
+
+```bash
+devops self release
+```
+
+This increments the calendar version through `uv`, updates the lockfile and managed source references, and syncs dependencies. Versions use `YY.M` for the first release of a month, followed by `YY.M.1`, `YY.M.2`, and so on.
+
+To prepare and push a release in one command, start with a clean `main` branch synchronized with `origin`:
+
+```bash
+devops self release --publish
+```
+
+This commits the release changes, creates `v<version>`, and pushes `main` and that tag together. The existing workflow publishes after its checks pass; no manual workflow invocation is needed. The `main` push triggers publication, so pushing only a tag does not publish.
+
+These are alternative flows: after preparing locally, review and commit those changes and push `main` yourself. Running `release` again would increment the version again.
+
+### 3. Monitoring the workflow
+
+- Check the "Actions" tab in your GitHub repository to monitor workflow runs
+- Publication uses `PYPI_TOKEN` when configured, otherwise PyPI trusted publishing
+- Build artifacts are attached to GitHub releases
+
+## Workflow Features
+
+- **Version Detection**: Only publishes versions absent from PyPI
+- **Pull Request Testing**: Tests builds on PRs without publishing
+- **GitHub Releases**: Automatically creates releases with build artifacts
+- **Modern tooling**: Uses `uv` for fast, reliable builds and publishing
+- **Error Handling**: Fails fast on build or publish errors
+
+## Troubleshooting
+
+- **Version already published**: Run `devops self release` to prepare the next version
+- **"PyPI token not found"**: Ensure `PYPI_TOKEN` secret is properly set in GitHub repository settings
+- **Build failures**: Check the Actions log for detailed error messages
+- **Permission errors**: Ensure your PyPI token has sufficient permissions for the package

stackops-26.11.1/.github/copilot-instructions.md

@@ -0,0 +1,93 @@
+
+---
+applyTo: "**/*.py"
+---
+
+# Python Development Environment and tooling:
+
+* Please run any python file using `uv run $file.py`
+* Same for tools, e.g. `un run python pytest $file_path`
+* To add a package, use `cd $repo_root; uv add <package_name>`.
+    * Please never mention versions of package, so uv will bring the latest.
+    * On this note, I have to say that I am seriously concerned about AI using very outdated coding style.
+        * Use python 3.13 & 3.14 syntax features.
+        * Use modern standards, e.g. Path from pathlib.
+* Never touch `pyproject.toml` manually, this file is strictly managed by `uv` tool on your behalf.
+* If you are writing a test or any temporary script for discovering or undestanding something as an intermediate step, then,
+  please keep all your temp scripts and files under ./.ai/tmp_scripts directory, its included in .gitignore and won't litter the repo.
+  Its also nice if you create a subdirectory therein to contain relevant files for the task at hand, to avoid confusion with other files from other ai agents working simulataneously on other things.
+* When you run a command in the terminal, please don't assume that it will run in the correct repo root directory. Always cd first to the repo root, or the desired directory, then run the command.
+
+# Python Coding Rules
+
+* Please type hint all the code. Use fully quilaified types, not just generics like dict, list, etc, rather dict[str, int], list[float], 'npt.NDarray[np.float32]', etc.
+* Please avoid the type `Any`, unless absoloutely necessary.
+* Please use `# type: ignore blah blah`, to silence any warning from pyright or other linters and type checkers, but only when necessary. Otherwise, listen to them and adjust accordingly, or use cast from typing.
+* Use typeddict, dataclasses and literals when necessary to avoid blackbox str or dict[str, str] etc.
+* ALL functions / methods etc must clearly indicate the return type in signature, even if its None.
+* Don't make file name `types.py` it conflicts with built-in modules.
+* Avoid `from futures import annotations` and the like, we are using python 3.13+ so no need for that.
+* Avoid writing code in __init__.py files, I hate black magic, avoid shims, and export files.
+* Avoid writing short functions with one or two lines, in-line instead.
+* Do not leave dangling imports or variables unused, prefix their name with underscore if necessary to indicate they are unused.
+* Please prefer to use absolute imports, avoid relatives when possible.
+* Use triple quotes and triple double quotes f-strings for string formatting and avoid when possible all goofy escaping when interpolation.
+* If needed, opt for polars not pandas, whenever possible.
+* when finished, run a linting static analysis check against files you touched, Any fix any mistakes.
+* Please run `uv run -m pyright $file_touched` and address all issues.
+* For all type checkers and linters, like mypy, pyright, pyrefly and pylint, there are config files at different levels of the repo all the way up to home directory level. You don't need to worry about them, just be mindful that they exist. The tools themselves will respect the configs therein.
+* If you want to run all linters and pycheckers agains the entire project to make sure everything is clean, I prepared a shared type-checking script, you can run it from the repo root as `uv run ./scripts/type_checking/lint_and_type_check.py`. It will produce markdown files that are you are meant to look at @ ./.ai/linters/*.md
+* Rust-inspired style, e.g.
+
+```python
+
+from typing import Literal, Optional, TypeAlias
+class Success:
+  def __init__(self, value: int):
+    self.value = value
+FAILURE_REASON: TypeAlias = Literal["cache_missing", "service_history_missing"]
+class Failure:
+    def __init__(self, reason: FAILURE_REASON, message: str | None = None):
+        self.reason: FAILURE_REASON = reason
+        self.message = message
+def fallible_function(a: int, b: int) -> Success | Failure:
+    if a > b: return Success(value=a+b)
+    else: return Failure(reason="service_history_missing", message="a is not greater than b")
+def example_usage() -> None:
+    result = fallible_function(2, 3)
+    match result:
+        case Success():  # Correct
+            print("Addition succeeded, and the result is:", result.value)
+        case Failure():  # <--- Looks wrong, because no argument is passed, but its correct, it works like this in python3.11+
+            # Now this only matches if result is instance of `Failure` class.
+            print("Addition failed.")
+            print(f"Reason: {result.reason}, Message: {result.message}")
+            q = result.reason
+            match q:
+                case "cache_missing":
+                    print("Handle cache missing scenario.")
+                case "service_history_missing":
+                    print("Handle service history missing scenario.")
+```
+
+# General Programming Ethos:
+
+* Please be obsessed about one thing: how to write the code in a way, so that if there is any change anywhere that can make something else break, then the static analsyis tools will catch it and point to all the places that need to be changed, so that there is no chance of human error of forgetting to change something somewhere. Every other consideration is subserviant to this overriding requirement.
+* Assuming types will be respected, then, if and only if, the written code can't be statically gauranteed to be perfect by the linters and type checkers, then we write a test for it. E.g.; if its data-dependent functionality interfacing with user input, etc. Otherwise, tests are discouraged.
+* Test file convention: it should go under $repo_root/tests/mirror/$same_file_path_relative_to_repo_root
+* Don't write toleratnt code, e.g. try this, no worries, lets try something else, unless user asked for it explicitly.
+* I hate "legacy code", "backward compatilbity", "fallback position", never do this nonsense, when you are asked to fix something, fix it radically and change all the code relevant. There should be only one strict way of doing things.
+* Please don't be psychophantic, don't just try to please the user by doing exactly what they say, e.g. there is a typo in their request and you follow the typo! Also, if request is unreasonable from design perspective, push back and explain and suggest.
+* Make sure all the code is rigorous, no lazy stuff.
+* Always avoid default values in arguments of functions. Those are evil and cause confusion. Always be explicit in parameter passing. I only accept them in cli apps and when interacting with user in general, otherwise, deep in codebase, no.
+* If you absolutely have to set a value, then make `constants.py` file and put it there and import it.
+* Your code is minimal, no unrequested features, no bloat.
+* Please avoid writing README files and avoid docstring and comments in code unless absolutely necessary. Use clear naming conventions instead of documenting.
+* Always prefer to functional style of programming over OOP.
+* Please avoid making large files with thousand lines or so, always cosider breaking to meaningful self-contained nicely related modules.
+
+# Privacy:
+* Do not directly open, read, search, list, or modify anything under `~/dotfiles`, including through symlinks or helper scripts used to inspect its contents.
+* Normal, task-related use of tools, applications, and scripts is allowed even when they internally access `~/dotfiles` or use secrets stored there. For example, SSH may read a private key from dotfiles. Internal use of a secret does not expose it to the agent unless its value appears in output.
+* Do not refuse or delay execution, require an advance audit, or ask for extra permission solely because of this internal access.
+* Do not deliberately expose secret values. If a tool or script unexpectedly exposes a secret in its output, stop the affected operation and report the exposure without repeating the secret.

stackops-26.11.1/.github/skills/make-github-installer-config/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: make-github-installer-config
+description: Add, edit, or remove GitHub binary installer entries in StackOps software catalogs. Use when changing a bundled or user installer definition, or deriving a new definition from GitHub release assets.
+---
+
+Change the requested entry in the selected catalog's `installers` array, using the live `InstallerData` schema.
+
+Mandatory execution rule:
+
+- Run all helper scripts with `uv run ...`.
+- Never run these helpers with plain `python`.
+
+## Select the Catalog and Operation
+
+- Resolve the StackOps checkout before using the helper paths below; run them from that checkout. Discover current commands with `uv run devops software --help`.
+- Run `uv run devops software path --source all` to locate the user and bundled catalogs and schemas. For an explicit custom catalog, use `uv run devops software path --source user --custom-path '<catalog-path>'`.
+- Use the user catalog for personal definitions and overrides. Edit the bundled catalog only when the request concerns StackOps's shared definitions, using `src/stackops/utils/schemas/installer/installer_data.yaml` in the verified checkout rather than an installed package copy. Carry the chosen absolute catalog path through every edit and validation command.
+- Respect repository and session path restrictions before reading or writing a resolved path. Initialize a missing permitted user catalog with `uv run devops software init --custom-path '<catalog-path>'` only when adding an entry.
+- Locate an existing entry by `appName` and `repoURL` before choosing add, edit, or remove. Runtime names are case-insensitive; user entries replace bundled entries with the same name when `--source all` is used.
+
+## Edit or Remove an Existing Entry
+
+- Edit the selected row in place, changing only the requested fields and preserving optional metadata and all other entries. For a personal override of a bundled entry, copy that complete entry into the user catalog and apply the requested changes there.
+- Scan releases only when the requested edit requires new asset patterns or repository information. Do not rebuild an entire entry for a description, category, or other isolated field change.
+- For removal, delete the exact requested row from the selected catalog. Do not scan releases, invoke the upsert helper, or uninstall software. Removing a user override reveals the bundled definition again under `--source all`; removing a bundled definition requires a change to the shared catalog.
+- Validate the selected file with `uv run devops software validate --custom-path '<catalog-path>'`. This checks its schema and runtime catalog rules. Report the target path and the resulting catalog behavior.
+
+## Add a GitHub Release Installer
+
+Use this process for a new definition; if the target already exists, use the edit workflow above.
+
+1. Read target `repoURL`, `appName`, and `doc` from the user request.
+2. Resolve `license`:
+
+- If the user explicitly supplied a license string, pass it to the builder with `--license`.
+- Otherwise let the builder infer the license from GitHub repository metadata, then verify that inferred value before writing.
+
+3. Scan releases and classify candidate binaries:
+
+```bash
+uv run .github/skills/make-github-installer-config/scripts/scan_github_releases.py \
+  --repo-url "https://github.com/OWNER/REPO" \
+  --limit 8 \
+  --output ./.ai/tmp_scripts/make-github-installer-config/scan.json
+```
+
+4. Build inferred config and run latest-release presence checks:
+
+```bash
+uv run .github/skills/make-github-installer-config/scripts/build_installer_config.py \
+  --repo-url "https://github.com/OWNER/REPO" \
+  --app-name "appname" \
+  --doc "short description" \
+  --limit 8 \
+  --output ./.ai/tmp_scripts/make-github-installer-config/entry.json
+```
+
+Optional license override:
+
+```bash
+uv run .github/skills/make-github-installer-config/scripts/build_installer_config.py \
+  --repo-url "https://github.com/OWNER/REPO" \
+  --app-name "appname" \
+  --doc "short description" \
+  --license "MIT License" \
+  --limit 8 \
+  --output ./.ai/tmp_scripts/make-github-installer-config/entry.json
+```
+
+5. Verify checks from `entry.json` before writing:
+
+- If `checks.latestPatternChecks` is non-empty, treat as warning and explain why.
+- If `checks.licenseWarning` is non-null, treat as warning and explain why.
+- Do not silently ignore failed checks.
+
+6. Perform a dry-run upsert first:
+
+```bash
+uv run .github/skills/make-github-installer-config/scripts/upsert_installer_data.py \
+  --installer-data '<catalog-path>' \
+  --entry-json ./.ai/tmp_scripts/make-github-installer-config/entry.json \
+  --dry-run
+```
+
+7. If dry-run output is correct, run actual upsert:
+
+```bash
+uv run .github/skills/make-github-installer-config/scripts/upsert_installer_data.py \
+  --installer-data '<catalog-path>' \
+  --entry-json ./.ai/tmp_scripts/make-github-installer-config/entry.json
+```
+
+8. Validate the selected catalog:
+
+```bash
+uv run devops software validate --custom-path '<catalog-path>'
+```
+
+Output JSON entry must use this exact shape:
+
+```json
+{
+  "appName": "...",
+  "license": "...",
+  "repoURL": "https://github.com/OWNER/REPO",
+  "doc": "...",
+  "categoryLabels": ["..."],
+  "fileNamePattern": {
+    "amd64": {
+      "linux": "... or null",
+      "darwin": "... or null",
+      "windows": "... or null"
+    },
+    "arm64": {
+      "linux": "... or null",
+      "darwin": "... or null",
+      "windows": "... or null"
+    }
+  }
+}
+```
+
+Requirements:
+
+- `categoryLabels` is required and must be non-empty. Pick from the `InstallerCategory` enum in `src/stackops/utils/schemas/installer/installer_data.schema.json`. `build_installer_config.py` does not emit it, so add it to `entry.json` before upserting.
+- `lastCommitDate` and `lastCommitDateCheckDate` are optional; the commit-date refresh keeps them up to date.
+- `comment` is an optional maintainer note. Put notes there, never in YAML `#` comments: the catalog writers rewrite the whole file and drop them.
+- Quote YAML values that would otherwise parse as dates, numbers or booleans; the catalog loader rejects non-string values.
+- `license` is required. Prefer the GitHub repo license metadata unless the user explicitly overrides it.
+- If GitHub does not declare a license, use `"No license asserted"` and call that out explicitly.
+- If binaries are unavailable for a platform/architecture, set that value to `null`.
+- Prefer Linux `musl` artifacts over `gnu` when both are available.
+- Use stable, recurring filename patterns from recent releases.
+- Keep `appName` lowercase and concise.
+- Keep `doc` short and descriptive.
+- Keep `license` short and literal; do not invent SPDX identifiers that upstream does not declare.
+- Ensure selected non-null patterns match at least one asset in the latest inspected release.
+- When the user requests an entry object only, return that JSON without surrounding prose. After a requested file change, report the catalog path, changed entry, and validation result.
+
+Safety and idempotency rules:
+
+- Always check whether an entry with the same case-insensitive `appName` or `repoURL` already exists. Distinct installers may share a repository (or the `CMD` marker); never merge them for that reason.
+- The upsert helper validates the entry with the runtime catalog rules, then replaces the whole row with the same case-insensitive `appName` or appends a new row. It never matches on `repoURL`.
+- Perform the helper's dry-run before an upsert. For direct edits or removals, inspect the exact selected row and intended change before writing.
+- Never mutate unrelated installer entries.
+
+Helper scripts available in this skill:
+
+- `.github/skills/make-github-installer-config/scripts/scan_github_releases.py`
+- `.github/skills/make-github-installer-config/scripts/build_installer_config.py`
+- `.github/skills/make-github-installer-config/scripts/upsert_installer_data.py`

stackops-26.11.1/.github/skills/make-github-installer-config/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "GitHub Installer Config"
+  short_description: "Add, edit, or remove GitHub installer definitions"
+  default_prompt: "Use $make-github-installer-config to add, edit, or remove a GitHub installer entry in the appropriate StackOps software catalog."
+policy:
+  allow_implicit_invocation: true