SciTeX Dev (scitex-dev)

Shared developer utilities for the SciTeX ecosystem

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

Problem and Solution

Installation

The base install includes the CLI, MCP server, icon rendering and skills. Maintainers can add the all extra for development and documentation tooling.

# 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.

Use scitex dev when the umbrella is installed. scitex-dev provides the standalone bootstrap CLI.

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

Rules and tests follow their owning audit domain. Project rules enter the shared RULES registry through central entries, co-located declarations or package providers. Co-located defaults live in their rule tuples; the final _patch pass applies severity and slug overrides after all registrations. Tests live under the corresponding audit modules.

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]
    A --> G[audit-django]
    B & C & D & E & F & G --> H{Any unresolved failure?}
    H -- "yes" --> I["exit 1"]
    H -- "no" --> J["exit 0"]

The wrapper aggregates auditor exit codes and applies the declared skip-rule policy. Read the actual exit status and per-auditor findings: a tally of zero unmasked errors alone does not establish success. Invocation or configuration errors can return exit code 2.

Illustrative output structure, rather than a current package assessment:

=== 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

Illustrative failure shape:

=== 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).

Selective discovery and context accounting

scitex-dev context measure --input selected-snapshot.json --json measures caller-selected advertised MCP definitions and skill headers. The same pure API is scitex_dev.measure_context and the MCP tool is dev_context_measure. configure_mcp_discovery reuses FastMCP search after host policy; no custom search engine or tokenizer is introduced. Reports show JSON bytes/code points, explicit owner attribution and unknown client context, without echoing tool descriptions. See scope, schema and client limits. The umbrella route is scitex dev context measure when Dev is installed.

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 skills list --package scitex-dev --json
scitex dev skills get scitex-dev SKILL
scitex dev skills install --package scitex-dev --directory /tmp/scitex-skills --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.