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
The table of contents is too big for display.
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
145 changes: 145 additions & 0 deletions plugins/caelestia-assistant/.caelestia-audit-ignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
# .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/brain/qa.py
# Question-type cue table: the literal 'sudo' is a string keyword used to classify question text;
nothing is executed.
assistant/capabilities/brain/qa.py:243

# 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/capabilities/generative/rag.py
# Command-verb vocabulary used to LABEL suggested command lines (SUGGESTED_NOT_EXECUTED; over-
labeling is the safe direction). Verbs are string data, never executed.
assistant/capabilities/generative/rag.py:90
assistant/capabilities/generative/rag.py:91
assistant/capabilities/generative/rag.py:96

# assistant/capabilities/genius/sysintel.py
# Command-intent parsing strips the literal 'sudo' token; analysis only, never executed.
assistant/capabilities/genius/sysintel.py:85
assistant/capabilities/genius/sysintel.py:87

# assistant/capabilities/retrieval/tools/build_docs_corpus.py
# Offline retrieval synonym strings ('git clone fails', 'submodule empty') - search synonyms over
local docs; no network calls.
assistant/capabilities/retrieval/tools/build_docs_corpus.py:62

# assistant/capabilities/shellkb/cmdparse.py
# CLI grammar: regex matching curl/wget pipe-to-shell shapes in order to CLASSIFY them
destructive. Parser never executes matches.
assistant/capabilities/shellkb/cmdparse.py:94

# 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

# tests/brain/test_command_gate_qml.py
# The string 'XMLHttpRequest' is the assertion TARGET: this test asserts the CommandGate QML must
never contain it (gate executes nothing).
tests/brain/test_command_gate_qml.py:200

# tests/diagnostics/test_argumentation.py
# Test fixtures: risky command strings as classification test data (assistant's own argumentation
tests).
tests/diagnostics/test_argumentation.py:168
tests/diagnostics/test_argumentation.py:192
tests/diagnostics/test_argumentation.py:201
tests/diagnostics/test_argumentation.py:205
tests/diagnostics/test_argumentation.py:265
tests/diagnostics/test_argumentation.py:267
tests/diagnostics/test_argumentation.py:279

# tests/diagnostics/test_safety_lint.py
# Test fixtures for the assistant's own safety linter: destructive/privileged command strings as
expected-classification data.
tests/diagnostics/test_safety_lint.py:23
tests/diagnostics/test_safety_lint.py:24
tests/diagnostics/test_safety_lint.py:50
tests/diagnostics/test_safety_lint.py:51

# tests/generative/test_generative.py
# Test fixtures: privileged command strings verifying the SUGGESTED_NOT_EXECUTED labeling
invariant.
tests/generative/test_generative.py:197
tests/generative/test_generative.py:209
tests/generative/test_generative.py:318

# tests/shellkb/test_howto.py
# The string 'sudo rm' is the assertion TARGET: the test asserts it is NOT present in any how-to
step (safety invariant).
tests/shellkb/test_howto.py:28

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