SciTeX Dev (scitex-dev)

Shared developer utilities for the SciTeX ecosystem

Full Documentation · uv pip install scitex-dev[all]

Problem and Solution

Installation

There are exactly two installs. The CLI, the MCP server, icon rendering and skills all ship in the base install — there is no per-feature menu to assemble, and nothing to forget to add.

# Everything you need to USE scitex-dev:
pip install scitex-dev

# Plus the maintainer toolchain (pytest, sphinx, ...) — for working ON it:
pip install scitex-dev[all]

[all] adds development and documentation tooling and optional integrations, including the Flask dashboard and NumPy diagnostics, on top of the base install. Extra names are restricted to {all, dev, docs} by PS-225, because a per-feature extra is something somebody eventually pins — and a pin naming an extra that does not exist installs anyway, warns into a log nobody reads, and silently omits the capability.

Configuration

Copy .env.example to .env (gitignored) at your project root, then edit. CLI flags always override env vars. The full list (with inline comments) lives in .env.example.

Architecture

scitex_dev/
├── _cli/
│   ├── audit/                ← rule corpus (PA*, PS*, SK*, §*)
│   │   ├── _api/             ← Python-API rules (PA-1xx)
│   │   ├── _project/         ← project-structure rules (PS-1xx, PS-5xx)
│   │   ├── _skills/          ← skill-file rules (SK-1xx)
│   │   └── _summary/         ← CLI/MCP §-rules + audit-all wrapper
│   ├── ecosystem/            ← cross-package commands (audit-all, list, …)
│   └── skills/               ← `scitex-dev dev skills` implementation
├── _ecosystem/               ← shared helpers (skill-quality, ECOSYSTEM map)
├── _skills/                  ← canonical skill-file corpus shipped to agents
└── testing/                  ← `audit_all_for_package` pytest helper

Audit rules live alongside the code they check. Each rule has a docstring, an entry in RULES, a severity in _SEVERITY_OVERRIDES, and at least one unit test under tests/.../_audit/_project/.

Demo

flowchart LR
    A["scitex-dev ecosystem<br/>audit-all <pkg>"] --> B[audit-cli]
    A --> C[audit-mcp-tools]
    A --> D[audit-skills]
    A --> E[audit-python-apis]
    A --> F[audit-project]
    B & C & D & E & F --> G{any error?}
    G -- "yes" --> H["exit 1<br/>(CI fails)"]
    G -- "no" --> I["exit 0<br/>(CI green)"]

scitex-dev is a CLI/audit tool — its "demo" is the audit running on a package. Sample output (run on scitex-io):

=== audit-cli ===
ok    scitex-io: no CLI convention violations

=== audit-mcp-tools ===
ok  scitex-io: no MCP convention violations

=== audit-skills ===
ok  scitex-io: no skills violations

=== audit-python-apis ===
ok  scitex-io: no Python API violations

=== audit-project ===
ok  scitex-io: no project-structure violations

Failure mode (sample, scitex-dsp before the Hilbert fix):

=== audit-project ===
fail  scitex-dsp (/home/ywatanabe/proj/scitex-dsp): 2 error(s)
  [E] [PS-141 §1] README.md: missing mandatory `## Demo` section
  [E] [PS-503 §5] examples/01_demo_out: no FINISHED_SUCCESS/<session_id>/ subdir

See examples/ for runnable demos that exercise scitex-dev's own commands (search, version-management, docs aggregation).

Five Interfaces

# Discover installed versions and documentation
from scitex_dev import list_versions, get_docs, search
versions = list_versions()
get_docs(package="scitex-writer")
search("save figure")

# Preview changes; applying a plan is a separate action
from scitex_dev import fix_local, preview_rename
fix_local(packages=["scitex-stats"], confirm=False)
preview_rename(pattern="old_name", replacement="new_name", directory=".")

# LLM-friendly types
from scitex_dev import Result, ErrorCode, supports_return_as

# Active project (scitex-dev >=0.62.0)
from scitex_dev.project import resolve_project
resolve_project(explicit="synthetic/owned")

# Ecosystem management
scitex-dev ecosystem list
scitex-dev ecosystem list --versions
scitex-dev ecosystem validate-versions --dry-run

# Active project (scitex-dev >=0.62.0)
scitex-dev project use synthetic/owned
scitex-dev project get --json
scitex-dev project clear

# Documentation
scitex-dev docs get
scitex-dev docs search "save figure"

# Bulk rename
scitex-dev rename-symbols old_name new_name --dry-run

# See all commands
scitex-dev --help
scitex-dev --help-recursive

# Start server
scitex-dev mcp start

# Check setup
scitex-dev mcp doctor
scitex-dev mcp list-tools

# Installation info
scitex-dev mcp install

{
  "mcpServers": {
    "scitex-dev": {
      "command": "scitex-dev",
      "args": ["mcp", "start"]
    }
  }
}

scitex-dev dev skills list --package scitex-dev --json
scitex-dev dev skills get scitex-dev SKILL
scitex-dev dev skills install --package scitex-dev --claude-symlink --dry-run --json
# Review the plan; omit --dry-run to install. Use --link for editable sources.

Part of SciTeX

scitex-dev is part of SciTeX. Install via the umbrella with pip install scitex[dev] to use as scitex.dev (Python) or scitex dev ... (CLI).

SciTeX follows the Four Freedoms for Research below, inspired by the Free Software Definition:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

Federated executable hooks

Leaves register scitex_dev.hooks providers and own their HookRule.check implementations. scitex-dev discovers and dispatches these checks without embedding a package's output, container, or credential policy.

scitex-dev dev hooks install --provider scitex-logging --harness claude --config .claude/settings.local.json --dry-run

Omit --dry-run to merge the provider's bindings into native configuration. Hermes uses --harness hermes --config <profile>/config.yaml and its own atomic writer, so run installation where Hermes is available. Use --python when the target's interpreter differs from the installer. Other settings/providers are preserved; repeating installation does not duplicate bindings. Native commands call python -m scitex_dev.hooks.dispatch --provider <distribution> with the harness JSON payload on stdin. A missing provider or failing check refuses verification with exit code 2. Post-tool checks report after the operation; only pre-tool events can prevent that operation. Harness approval is separate from installation and is never silently granted by this installer.