Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,15 @@ pkexec cmake --install # caelestia-audit: allow-privilege

Use these sparingly - the store defaults to source-only with no surprise downloads or unexpected shelling out.

For findings where a same-line comment is impossible or wrong - JSON data artifacts (no comment syntax without corrupting the data), flagged text inside docstrings or string vocabularies (appending a comment would change the string), or assertion-target strings in tests - a plugin may ship a `.caelestia-audit-ignore` file next to its `metadata.json`. Each entry names a plugin-relative path, optionally restricted to a line or an inclusive line range, with a reason:

```
assistant/data/index/bm25.json # data artifact, not code
src/verbs.py:120-132 # string vocabulary, not a call
```

Entries suppress hard errors for exactly those paths and lines; soft warnings still surface. Keep the list short and the reasons honest - maintainers review every entry as part of the plugin diff.

## Maintainer review checklist

- CI passes.
Expand Down
82 changes: 82 additions & 0 deletions plugins/caelestia-assistant/.caelestia-audit-ignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# .caelestia-audit-ignore - documented opt-outs for scripts/check_safety.py
#
# The store's line-level opt-out is a trailing 'caelestia-audit:' comment;
# this file covers the cases where that is impossible or wrong:
# * JSON data artifacts cannot carry comments without corrupting data,
# * flagged text inside docstrings/string vocabularies where appending
# a comment would change the string,
# * assertion-target strings in tests (the banned pattern IS the test).
#
# Format: <plugin-relative path>[:line|:start-end] # reason
# Every entry was reviewed against the source; nothing here performs a
# network fetch or a privileged action (see the migration audit).
#
# assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml
# Shell sidebar QML: XMLHttpRequest calls the user-configured AI provider endpoints
(GlobalConfig.ai.*, incl. loopback Ollama default) - the opt-in, user-keyed cloud fallback tier;
disabled unless the user configures a provider. No other network use exists.
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:163
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:169
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1408
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1411
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1463
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1468
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1722
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1734
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1764
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:1797
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:2165
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:2232
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:2238
assistant/adapters/caelestia/shell/modules/sidebar/AiAssistant.qml:2359

# assistant/capabilities/diagnostics/argumentation.py
# Command tokenization: the literal 'sudo' is stripped/classified as a token; analysis only, never
executed.
assistant/capabilities/diagnostics/argumentation.py:278
assistant/capabilities/diagnostics/argumentation.py:281

# assistant/capabilities/diagnostics/risk.py
# Static risk classifier: deny-list REGEX VOCABULARY that matches dangerous shapes (curl|sh,
wget|sh, sudo, pkexec, doas) to LABEL commands PRIVILEGED/DESTRUCTIVE. Text patterns; the engine
never runs commands.
assistant/capabilities/diagnostics/risk.py:12
assistant/capabilities/diagnostics/risk.py:17
assistant/capabilities/diagnostics/risk.py:41
assistant/capabilities/diagnostics/risk.py:42
assistant/capabilities/diagnostics/risk.py:62

# assistant/capabilities/diagnostics/rules.d/config_kde.json
# Rulepack prose: display-only suggested command (assistant never executes; steps are labeled and
require explicit user confirmation).
assistant/capabilities/diagnostics/rules.d/config_kde.json:73

# assistant/capabilities/diagnostics/rules.d/install.json
# Rulepack: display-only copy-paste install commands, in-rule labeled PRIVILEGED via command_risk,
plus updater prose mentioning 'git clone'. Never executed by the assistant.
assistant/capabilities/diagnostics/rules.d/install.json:23
assistant/capabilities/diagnostics/rules.d/install.json:25
assistant/capabilities/diagnostics/rules.d/install.json:30
assistant/capabilities/diagnostics/rules.d/install.json:32
assistant/capabilities/diagnostics/rules.d/install.json:36
assistant/capabilities/diagnostics/rules.d/install.json:38
assistant/capabilities/diagnostics/rules.d/install.json:114
assistant/capabilities/diagnostics/rules.d/install.json:132
assistant/capabilities/diagnostics/rules.d/install.json:133
assistant/capabilities/diagnostics/rules.d/install.json:153
assistant/capabilities/diagnostics/rules.d/install.json:229

# assistant/capabilities/diagnostics/rules.d/known_regressions.json
# Rulepack prose: display-only suggested command string, confirmation-gated, never executed.
assistant/capabilities/diagnostics/rules.d/known_regressions.json:27

# assistant/capabilities/diagnostics/rules.d/runtime.json
# Rulepack prose: display-only suggested reinstall command string, confirmation-gated, never
executed.
assistant/capabilities/diagnostics/rules.d/runtime.json:74

# assistant/data/index/bm25.json
# Built BM25 search-index artifact (single-line JSON): term/document data mentioning 'curl', 'git
ls-remote'. Data, not code; JSON cannot carry line-level opt-out comments.
assistant/data/index/bm25.json:1

31 changes: 31 additions & 0 deletions plugins/caelestia-assistant/.github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: CI

on:
push:
branches: [main, dev]
pull_request:

jobs:
tests:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.12", "3.13", "3.14", "3.15"]
continue-on-error: ${{ matrix.python-version == '3.15' }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Run the full unittest suite
run: python3 -m unittest discover -s . -p "test_*.py"
- name: Selfcheck (rule schema + safety pins AST lint)
run: python3 -m assistant.hub selfcheck

shell-harness:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Bash test harness
run: bash tests/test_assistant.sh
4 changes: 4 additions & 0 deletions plugins/caelestia-assistant/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
__pycache__/
*.pyc
*.pyo
.pytest_cache/
13 changes: 13 additions & 0 deletions plugins/caelestia-assistant/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Contributing

- Python 3.12+, stdlib only (optional extras: `pip install ".[all]"`).
- Run the suite before proposing anything: `python3 -m unittest discover -s . -p "test_*.py"`,
then `python3 -m assistant.hub selfcheck` and `bash tests/test_assistant.sh`.
- Every capability ships with a manifest (permissions, risk tier, budgets)
and tests. Behavior changes need eval evidence: `python3 -m assistant eval --json`.
- Commands are passed as argv arrays through `assistant/executor` — never
shell strings. Destructive or privileged actions require explicit confirm.
- Golden outputs (`tests/goldens/`) change only via
`python3 scripts/regen_goldens.py` with a reviewed commit explaining why.
- No model files are ever committed or bundled.
- Keep the tree lean: no changelogs, scratch files, or committed build artifacts.
Loading
Loading