bash-classify 0.1.0__tar.gz

bash_classify-0.1.0/.claude/rules/command-database.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "src/bash_classify/commands/**"
+---
+
+@docs/classification-guidance.md
+@schemas/command.schema.json
+
+Every YAML file must:
+- Start with `# $schema: ../../../schemas/command.schema.json` on the first line
+- Have a `command:` field matching the filename (without `.yaml`)
+- Have a `description:` field with a short one-liner
+- Pass schema validation (`uv run pytest tests/test_schema.py`)

bash_classify-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "bash-classify",
+  "description": "Bash command classifier with Claude Code plugin for auto-allowing readonly commands",
+  "metadata": {
+    "pluginRoot": "./coding-agent-plugins/claude-code"
+  },
+  "plugins": [
+    {
+      "name": "bash-classify-hook",
+      "source": "."
+    }
+  ]
+}

bash_classify-0.1.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml,json,toml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

bash_classify-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Ruff check
+        run: uv run ruff check --output-format github .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  schema:
+    name: Validate YAML schema
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Validate command database
+        run: uv run pytest tests/test_schema.py -v

bash_classify-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bash-classify
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

bash_classify-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing / Coverage
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

bash_classify-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

bash_classify-0.1.0/CLAUDE.md

@@ -0,0 +1,2 @@
+@README.md
+

bash_classify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filip Prochazka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bash_classify-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: bash-classify
+Version: 0.1.0
+Summary: Classify bash commands as READONLY, WRITE, DANGEROUS, or UNKNOWN
+Project-URL: Homepage, https://github.com/fprochazka/bash-classify
+Project-URL: Repository, https://github.com/fprochazka/bash-classify
+Project-URL: Issues, https://github.com/fprochazka/bash-classify/issues
+Project-URL: Documentation, https://github.com/fprochazka/bash-classify/blob/main/SPEC.md
+Author-email: Filip Procházka <dev@fprochazka.cz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bash,classification,cli,security,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Shells
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tree-sitter-bash>=0.23
+Requires-Dist: tree-sitter>=0.24
+Description-Content-Type: text/markdown
+
+# bash-classify
+
+Classify bash commands by their side-effect risk level.
+
+## What it does
+
+bash-classify parses bash expressions using tree-sitter, classifies each command against a database of 120+ known commands, and outputs a structured JSON verdict. Commands are classified into four levels: `READONLY`, `WRITE`, `DANGEROUS`, and `UNKNOWN`.
+
+Designed primarily as a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hook to automatically allow safe, read-only commands while flagging risky ones for human review.
+
+## Installation
+
+```bash
+uv tool install bash-classify
+# or
+pip install bash-classify
+```
+
+## Quick start
+
+```bash
+$ echo 'kubectl get pods -n production' | bash-classify | jq '.classification'
+"READONLY"
+
+$ echo 'git push --force origin main' | bash-classify | jq '.classification'
+"DANGEROUS"
+
+$ echo 'cp file.txt /etc/config' | bash-classify | jq '.classification'
+"DANGEROUS"
+
+$ echo 'find . -name "*.pyc" -delete' | bash-classify | jq '.classification'
+"DANGEROUS"
+```
+
+## Claude Code hook
+
+Install as a Claude Code hook to auto-allow read-only commands and require approval for everything else:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | bash-classify",
+            "timeout": 5000,
+            "on_output": [
+              {
+                "matcher": "\"classification\": \"READONLY\"",
+                "action": "approve"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Command database
+
+The classification database includes 120+ command definitions covering common Unix utilities, package managers, container tools, cloud CLIs, and more.
+
+- See [docs/classification-guidance.md](docs/classification-guidance.md) for how to add new commands
+- YAML definitions are validated against a JSON Schema for IDE autocomplete and CI checks
+
+## Classification levels
+
+| Level | Description | Examples |
+|---|---|---|
+| `READONLY` | No side effects, safe to auto-approve | `ls`, `cat`, `grep`, `kubectl get` |
+| `WRITE` | Modifies local files or state | `mkdir`, `cp`, `git commit` |
+| `DANGEROUS` | Destructive, system-wide, or irreversible | `rm -rf`, `git push --force`, `chmod` |
+| `UNKNOWN` | Command not in database | Any unrecognized command |
+
+## How it works
+
+- **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
+- **YAML command database** -- each command has classification rules with subcommand and option matching
+- **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
+
+## Python API
+
+```python
+from bash_classify import classify_expression
+
+result = classify_expression("kubectl get pods")
+print(result.classification)  # Classification.READONLY
+```
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Development
+
+```bash
+git clone https://github.com/fprochazka/bash-classify.git
+cd bash-classify
+uv sync --dev
+```
+
+Run tests and linting before committing:
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pytest
+```
+
+To add or modify command definitions, see [docs/classification-guidance.md](docs/classification-guidance.md). All YAML files in `src/bash_classify/commands/` are validated against a [JSON Schema](schemas/command.schema.json) — your IDE will provide autocomplete if it supports the `# $schema:` comment.
+
+## License
+
+[MIT](LICENSE)

bash_classify-0.1.0/README.md

@@ -0,0 +1,118 @@
+# bash-classify
+
+Classify bash commands by their side-effect risk level.
+
+## What it does
+
+bash-classify parses bash expressions using tree-sitter, classifies each command against a database of 120+ known commands, and outputs a structured JSON verdict. Commands are classified into four levels: `READONLY`, `WRITE`, `DANGEROUS`, and `UNKNOWN`.
+
+Designed primarily as a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hook to automatically allow safe, read-only commands while flagging risky ones for human review.
+
+## Installation
+
+```bash
+uv tool install bash-classify
+# or
+pip install bash-classify
+```
+
+## Quick start
+
+```bash
+$ echo 'kubectl get pods -n production' | bash-classify | jq '.classification'
+"READONLY"
+
+$ echo 'git push --force origin main' | bash-classify | jq '.classification'
+"DANGEROUS"
+
+$ echo 'cp file.txt /etc/config' | bash-classify | jq '.classification'
+"DANGEROUS"
+
+$ echo 'find . -name "*.pyc" -delete' | bash-classify | jq '.classification'
+"DANGEROUS"
+```
+
+## Claude Code hook
+
+Install as a Claude Code hook to auto-allow read-only commands and require approval for everything else:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | bash-classify",
+            "timeout": 5000,
+            "on_output": [
+              {
+                "matcher": "\"classification\": \"READONLY\"",
+                "action": "approve"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Command database
+
+The classification database includes 120+ command definitions covering common Unix utilities, package managers, container tools, cloud CLIs, and more.
+
+- See [docs/classification-guidance.md](docs/classification-guidance.md) for how to add new commands
+- YAML definitions are validated against a JSON Schema for IDE autocomplete and CI checks
+
+## Classification levels
+
+| Level | Description | Examples |
+|---|---|---|
+| `READONLY` | No side effects, safe to auto-approve | `ls`, `cat`, `grep`, `kubectl get` |
+| `WRITE` | Modifies local files or state | `mkdir`, `cp`, `git commit` |
+| `DANGEROUS` | Destructive, system-wide, or irreversible | `rm -rf`, `git push --force`, `chmod` |
+| `UNKNOWN` | Command not in database | Any unrecognized command |
+
+## How it works
+
+- **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
+- **YAML command database** -- each command has classification rules with subcommand and option matching
+- **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
+
+## Python API
+
+```python
+from bash_classify import classify_expression
+
+result = classify_expression("kubectl get pods")
+print(result.classification)  # Classification.READONLY
+```
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Development
+
+```bash
+git clone https://github.com/fprochazka/bash-classify.git
+cd bash-classify
+uv sync --dev
+```
+
+Run tests and linting before committing:
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pytest
+```
+
+To add or modify command definitions, see [docs/classification-guidance.md](docs/classification-guidance.md). All YAML files in `src/bash_classify/commands/` are validated against a [JSON Schema](schemas/command.schema.json) — your IDE will provide autocomplete if it supports the `# $schema:` comment.
+
+## License
+
+[MIT](LICENSE)