NebulaShell/AGENTS.md

AGENTS.md — NebulaShell

Quick start

pip install -r requirements.txt
python -m oss.cli serve              # start server on :8080
# or: python main.py
# or: oss serve (after pip install -e .)

Architecture (minimal core philosophy)

• Core framework (oss/) loads only one builtin plugin: store/@{NebulaShell}/plugin-loader/
• plugin-loader then scans store/@{NebulaShell}/ and manages all other plugins
• Two store namespaces: @{NebulaShell} (26 official plugins) and @{Falck} (2 plugins)
• Entry point: oss/cli.py:main() → PluginManager → PluginLoader.load_core_plugin("plugin-loader")
• Each store plugin at store/@{NebulaShell}/<name>/main.py must export a New() factory function
• Plugin base class: oss/plugin/types.py:Plugin (abstract: init, start, stop)

Commands

Action	Command
Start server	python -m oss.cli serve
Show info	python -m oss.cli info
Hidden achievements	Prefix with !! (e.g., !!help, !!list, !!stats, !!debug)
Docker	docker-compose up (ports 8080-8082)

Hidden commands defined in oss/core/achievements.py — they are a gamification layer, not real administration.

Config

• oss.config.json — runtime config (port, host, data/store dirs, log level, permissions)
• Priority: env var > oss.config.json > hardcoded defaults (oss/config/config.py)
• Must set PYTHONPATH to repo root before running anything
• PYTHONUNBUFFERED=1 recommended for dev

Test

pytest -v --tb=short          # single test file: oss/tests/test_nodejs_adapter.py

Tests require Node.js/npm on $PATH or many tests skip. No CI workflows exist.

Toolchain

black oss/ store/@{NebulaShell}/   # formatter (line-length=88)
pylint oss/ store/@{NebulaShell}/  # linter (references .pylintrc, file may not exist)

No typechecker configured. No CI.

Rename history

This project was renamed from FutureOSS → NebulaShell. Old name may still appear in git history, external URLs, or stale wiki references. Always use "NebulaShell" in new code.

Ports

Port	Service
8080	HTTP API + WebUI
8081	WebSocket
8082	HTTP TCP