se-admin 0.2.0__tar.gz

se_admin-0.2.0/.gitignore

@@ -0,0 +1,126 @@
+# ============================================================
+# .gitignore (Keep unnecessary files out of the repository)
+# ============================================================
+# Updated 2026-05-06
+
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .gitignore.
+# WHY: Prevent committing generated artifacts, local state, secrets, and OS-specific files.
+
+# === Universal (all projects, all languages) ===
+
+# WHY: Logs are useful during debugging and verification.
+# ALT: Comment if logs must be inspected or validated.
+*.log
+logs/
+PRIVATE_NOTES.md
+PRIVATE-NOTES.md
+
+# WHY: Temporary and swap files are machine-local noise and create meaningless diffs.
+*.swo
+*.swp
+*.tmp
+*~
+
+# === VS Code (special case) ===
+
+# WHY: Ignore editor state while allowing a shared baseline configuration.
+.vscode/
+
+# WHY: Commit recommended extensions (opt-in) for consistent development experience.
+# NOTE: Share recommendations, not personal editor styles or preferences.
+# Must reinclude directory first so Git will traverse
+!.vscode/
+!.vscode/extensions.json
+!.vscode/settings.json
+
+# === OS-specific files (macOS / Windows) ===
+
+# WHY: OS-generated metadata files should never be tracked.
+.AppleDouble
+.DS_Store
+.LSOverride
+Icon\r
+._*
+.Spotlight-V100/
+.Trashes
+desktop.ini
+ehthumbs.db
+Thumbs.db
+
+# === Editors / IDEs (non-VS Code) ===
+
+# WHY: IDE metadata is machine-local and should not be tracked.
+*.code-workspace
+.idea/
+
+# === Environment variables and secrets ===
+
+# WHY: Never commit credentials or environment-specific configuration.
+.env
+.env.*
+*.env
+
+# === Documentation build output ===
+
+# WHY: Static site build output is generated.
+site/
+
+# === Generic caches ===
+
+# WHY: Generic caches are machine-local and should not be tracked.
+.cache/
+
+# === Python ===
+
+# WHY: Virtual environments are machine-local and reproducible.
+.venv/
+venv/
+
+# REQ.PYTHON: Do NOT git ignore uv.lock. Commit it and use it in CI/CD pipelines.
+
+# WHY: Python version when using scm matches any repo depth and any package name
+**/src/**/_version.py
+
+# WHY: Python bytecode is generated.
+__pycache__/
+*.pyc
+*.pyd
+*.pyo
+
+# WHY: Build and packaging artifacts are generated.
+.eggs/
+build/
+dist/
+*.egg
+*.egg-info/
+*.whl
+
+# WHY: Tooling caches should not be tracked.
+.coverage
+.coverage.*
+.mypy_cache/
+.pytest_cache/
+.pytype/
+.ruff_cache/
+.tox/
+
+# WHY: Notebook checkpoint state is generated.
+.ipynb_checkpoints/
+
+# WHY: Local test and coverage reports are generated.
+htmlcov/
+coverage.xml
+
+# WHY: Nox is common in Python tooling
+.nox/
+
+# === JS / docs tooling ===
+
+node_modules/
+out/
+
+# === Lean ===
+
+# WHY: Lake build and dependency state is generated.
+.lake/
+lake-packages/

se_admin-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Structural Explainability
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

se_admin-0.2.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: se-admin
+Version: 0.2.0
+Project-URL: Homepage, https://github.com/structural-explainability/se-admin
+Project-URL: Repository, https://github.com/structural-explainability/se-admin
+Project-URL: Documentation, https://structural-explainability.github.io/se-admin/
+Project-URL: Issues, https://github.com/structural-explainability/se-admin/issues
+Project-URL: Changelog, https://github.com/structural-explainability/se-admin/blob/main/CHANGELOG.md
+License-File: LICENSE
+Requires-Python: >=3.15
+Requires-Dist: se-manifest-schema
+Requires-Dist: tomlkit
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: packaging; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: zensical==0.0.37; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# se-admin
+
+[![Docs Site](https://img.shields.io/badge/docs-site-blue?logo=github)](https://structural-explainability.github.io/se-admin/)
+[![Repo](https://img.shields.io/badge/repo-GitHub-black?logo=github)](https://github.com/structural-explainability/se-admin)
+[![Python 3.15+](https://img.shields.io/badge/python-3.15%2B-blue?logo=python)](./pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
+
+[![CI](https://github.com/structural-explainability/se-admin/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/ci-python-zensical.yml)
+[![Docs](https://github.com/structural-explainability/se-admin/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/deploy-zensical.yml)
+[![Links](https://github.com/structural-explainability/se-admin/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/links.yml)
+
+> Structural Explainability Admin:
+> administration of the SE ecosystem.
+
+SE Admin is a data-driven system that applies composable operations
+over repository surfaces
+with declarative targets and selectable scope
+to move repos between states.
+
+## Owns
+
+- enforcement of constitution (automation)
+- repository lifecycle operations
+- cross-repository consistency
+
+## Includes
+
+scaffolding
+
+- repository templates
+
+synchronization
+
+- configuration propagation
+
+validation orchestration
+
+- multi-repo validation execution
+
+workflow reuse
+
+- shared GitHub Actions
+
+bulk operations
+
+- dependency upgrades
+- structural updates
+
+## Overview
+
+```text
+data/       = declared desired state, no logic, only declarations
+observe/    = actual repo state, no decisions, only facts
+checks/     = pure comparison, no side effects
+actions/    = primitive mutations
+migrations/ = composed actions
+reports/    = human/machine output projections only
+```
+
+```text
+domain/
+  repo        - repository
+  profile     = named bundle of expectations (paths, workflows, checks)
+  selector    = how you choose repos (set, name, pattern)
+  finding     = result of a check
+```
+
+```text
+repos.toml       = instances: which repos exist, repo sets, assigned profiles
+profiles.toml    = reusable traits: profile definitions
+checks.toml      = constraints: check definitions and canonical comparisons
+migrations.toml  = transformations: named migration recipes
+```
+
+```text
+data (declared) -> observe (actual) -> checks (compare) -> actions/migrations -> reports
+```
+
+## Operation Requirements
+
+Data describes operations and a small interpreter executing them
+
+All operations must be:
+
+- deterministic
+- idempotent
+- side-effect scoped
+
+Examples:
+
+- delete_file is OK if missing
+- add_dependency is OK if already present
+- replace_text is no-op if not found
+
+## Operation Taxonomy
+
+### Detection (no side effects)
+
+- path_exists
+- path_missing
+- toml_key_exists
+- toml_value_equals
+- dependency_present
+- workflow_present
+
+### Mutation (single responsibility)
+
+Filesystem
+
+- create_file
+- delete_file
+- copy_file
+- ensure_directory
+- rename_path
+  TOML
+- toml_set_key
+- toml_remove_key
+- toml_add_dependency
+- toml_remove_dependency
+- toml_ensure_table
+  Workflows (still files, but special intent)
+- ensure_workflow
+- remove_workflow
+- replace_workflow
+  Text
+- replace_block
+- insert_block
+- remove_block
+  Process
+- run_command
+
+## Composition
+
+```text
+Operation =
+  AtomicOperation
+  | Sequence[Operation]
+  | Conditional(condition, Operation)
+```
+
+## Example
+
+A tool transition is a declarative description of how to
+remove one capability and establish another across all affected surfaces.
+
+```text
+Sequence(
+  Conditional(detect_mkdocs, Sequence(
+    delete_file("mkdocs.yml"),
+    toml_remove_dependency("mkdocs"),
+    remove_workflow("deploy-mkdocs.yml")
+  )),
+
+  Sequence(
+    create_file("zensical.toml"),
+    toml_add_dependency(group="docs", name="zensical"),
+    ensure_workflow("deploy-zensical.yml"),
+    ensure_directory("docs")
+  )
+)
+```
+
+## Command Reference
+
+<details>
+<summary>Show command reference</summary>
+
+### In a machine terminal
+
+Open a machine terminal where you want the project:
+
+```shell
+git clone https://github.com/structural-explainability/se-admin
+
+cd se-admin
+code .
+```
+
+### In a VS Code terminal
+
+```shell
+# if strange errors, clean uv cache
+# uv cache clean
+
+uv self update
+uv python pin 3.15
+uv sync --extra dev --extra docs --upgrade
+
+uvx pre-commit install
+
+git add -A
+uvx pre-commit run --all-files
+# repeat if changes were made
+git add -A
+uvx pre-commit run --all-files
+
+# run the module
+uv run python -m se_admin show
+
+# do chores
+uv run python -m pyright
+uv run python -m pytest
+uv run python -m zensical build
+
+# save progress
+git add -A
+git commit -m "update"
+git push -u origin main
+```
+
+Portability fixture checks verifying that `se-admin`
+can load and operate on a non-SE repository family
+using an alternate data root.
+
+```shell
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data repos
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data check --set modules
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data check --set admin
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data run --dry-run normalize_core_files
+
+</details>
+
+## Citation
+
+[CITATION.cff](./CITATION.cff)
+
+## License
+
+[LICENSE](./LICENSE)
+
+## Manifest
+
+[SE_MANIFEST.toml](./SE_MANIFEST.toml)

se_admin-0.2.0/README.md

@@ -0,0 +1,233 @@
+# se-admin
+
+[![Docs Site](https://img.shields.io/badge/docs-site-blue?logo=github)](https://structural-explainability.github.io/se-admin/)
+[![Repo](https://img.shields.io/badge/repo-GitHub-black?logo=github)](https://github.com/structural-explainability/se-admin)
+[![Python 3.15+](https://img.shields.io/badge/python-3.15%2B-blue?logo=python)](./pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
+
+[![CI](https://github.com/structural-explainability/se-admin/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/ci-python-zensical.yml)
+[![Docs](https://github.com/structural-explainability/se-admin/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/deploy-zensical.yml)
+[![Links](https://github.com/structural-explainability/se-admin/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-admin/actions/workflows/links.yml)
+
+> Structural Explainability Admin:
+> administration of the SE ecosystem.
+
+SE Admin is a data-driven system that applies composable operations
+over repository surfaces
+with declarative targets and selectable scope
+to move repos between states.
+
+## Owns
+
+- enforcement of constitution (automation)
+- repository lifecycle operations
+- cross-repository consistency
+
+## Includes
+
+scaffolding
+
+- repository templates
+
+synchronization
+
+- configuration propagation
+
+validation orchestration
+
+- multi-repo validation execution
+
+workflow reuse
+
+- shared GitHub Actions
+
+bulk operations
+
+- dependency upgrades
+- structural updates
+
+## Overview
+
+```text
+data/       = declared desired state, no logic, only declarations
+observe/    = actual repo state, no decisions, only facts
+checks/     = pure comparison, no side effects
+actions/    = primitive mutations
+migrations/ = composed actions
+reports/    = human/machine output projections only
+```
+
+```text
+domain/
+  repo        - repository
+  profile     = named bundle of expectations (paths, workflows, checks)
+  selector    = how you choose repos (set, name, pattern)
+  finding     = result of a check
+```
+
+```text
+repos.toml       = instances: which repos exist, repo sets, assigned profiles
+profiles.toml    = reusable traits: profile definitions
+checks.toml      = constraints: check definitions and canonical comparisons
+migrations.toml  = transformations: named migration recipes
+```
+
+```text
+data (declared) -> observe (actual) -> checks (compare) -> actions/migrations -> reports
+```
+
+## Operation Requirements
+
+Data describes operations and a small interpreter executing them
+
+All operations must be:
+
+- deterministic
+- idempotent
+- side-effect scoped
+
+Examples:
+
+- delete_file is OK if missing
+- add_dependency is OK if already present
+- replace_text is no-op if not found
+
+## Operation Taxonomy
+
+### Detection (no side effects)
+
+- path_exists
+- path_missing
+- toml_key_exists
+- toml_value_equals
+- dependency_present
+- workflow_present
+
+### Mutation (single responsibility)
+
+Filesystem
+
+- create_file
+- delete_file
+- copy_file
+- ensure_directory
+- rename_path
+  TOML
+- toml_set_key
+- toml_remove_key
+- toml_add_dependency
+- toml_remove_dependency
+- toml_ensure_table
+  Workflows (still files, but special intent)
+- ensure_workflow
+- remove_workflow
+- replace_workflow
+  Text
+- replace_block
+- insert_block
+- remove_block
+  Process
+- run_command
+
+## Composition
+
+```text
+Operation =
+  AtomicOperation
+  | Sequence[Operation]
+  | Conditional(condition, Operation)
+```
+
+## Example
+
+A tool transition is a declarative description of how to
+remove one capability and establish another across all affected surfaces.
+
+```text
+Sequence(
+  Conditional(detect_mkdocs, Sequence(
+    delete_file("mkdocs.yml"),
+    toml_remove_dependency("mkdocs"),
+    remove_workflow("deploy-mkdocs.yml")
+  )),
+
+  Sequence(
+    create_file("zensical.toml"),
+    toml_add_dependency(group="docs", name="zensical"),
+    ensure_workflow("deploy-zensical.yml"),
+    ensure_directory("docs")
+  )
+)
+```
+
+## Command Reference
+
+<details>
+<summary>Show command reference</summary>
+
+### In a machine terminal
+
+Open a machine terminal where you want the project:
+
+```shell
+git clone https://github.com/structural-explainability/se-admin
+
+cd se-admin
+code .
+```
+
+### In a VS Code terminal
+
+```shell
+# if strange errors, clean uv cache
+# uv cache clean
+
+uv self update
+uv python pin 3.15
+uv sync --extra dev --extra docs --upgrade
+
+uvx pre-commit install
+
+git add -A
+uvx pre-commit run --all-files
+# repeat if changes were made
+git add -A
+uvx pre-commit run --all-files
+
+# run the module
+uv run python -m se_admin show
+
+# do chores
+uv run python -m pyright
+uv run python -m pytest
+uv run python -m zensical build
+
+# save progress
+git add -A
+git commit -m "update"
+git push -u origin main
+```
+
+Portability fixture checks verifying that `se-admin`
+can load and operate on a non-SE repository family
+using an alternate data root.
+
+```shell
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data repos
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data check --set modules
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data check --set admin
+uv run python -m se_admin --data tests/fixtures/streaming-admin/data run --dry-run normalize_core_files
+
+</details>
+
+## Citation
+
+[CITATION.cff](./CITATION.cff)
+
+## License
+
+[LICENSE](./LICENSE)
+
+## Manifest
+
+[SE_MANIFEST.toml](./SE_MANIFEST.toml)