mbse 0.1.0__tar.gz

mbse-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,54 @@
+FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04
+
+# Prevent interactive prompts during package installations
+ENV DEBIAN_FRONTEND=noninteractive
+
+################################################################################
+# Common packages
+################################################################################
+
+RUN apt-get update && apt-get install -y \
+    curl \
+    default-jre-headless \
+    graphviz \
+    git \
+    wget \
+    sudo \
+    locales \
+    python3 \
+    python3-pip \
+    python3-dev \
+    python3-setuptools \
+    python3-venv \
+    python-is-python3 \
+    xdg-utils \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+    
+# Install common Python tooling globally in the devcontainer so it is available
+# to the whole workspace without introducing an additional virtual environment
+# layer.  --break-system-packages is intentional here because this is a controlled
+# development container image rather than a shared host Python installation.
+RUN python -m pip install --break-system-packages \
+    Jinja2 \
+    jsonschema \
+    pytest \
+    quickjs
+
+# Configure locale (UTF-8)
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+################################################################################
+# AI support with OpenCode
+################################################################################
+
+# Switch to container user so AI tooling installs in the correct user paths
+USER vscode
+ENV HOME=/home/vscode
+
+# Install OpenCode
+RUN curl -fsSL https://opencode.ai/install | bash
+
+# Create ~/.local/state as vscode so OpenCode has write permissions
+RUN mkdir -p /home/vscode/.local/state

mbse-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "MBSE",
+  "dockerFile": "Dockerfile",
+  "mounts": [
+    // Load OpenCode state (including credentials and sessions) from host.
+    "source=${localEnv:HOME}/.local/share/opencode,target=/home/vscode/.local/share/opencode,type=bind"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "mhutchie.git-graph",
+        "spencerwmiles.vscode-task-buttons",
+        "bierner.markdown-preview-github-styles",
+        "ms-vscode.live-server"
+      ]
+    }
+  }
+}

mbse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get update && sudo apt-get install --yes graphviz
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[test]" build
+      - run: ruff check .
+      - run: pytest
+      - run: python -m build

mbse-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mbse
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get update && sudo apt-get install --yes graphviz
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[test]" build
+      - run: ruff check .
+      - run: pytest
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mbse-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.viewer-js-venv/
+.python-packages/
+.mbse-rendered/
+.mbse-cli-state/
+*.egg-info/
+build/
+dist/

mbse-0.1.0/.vscode/settings.json

@@ -0,0 +1,27 @@
+{
+  "workbench.tree.indent": 16,
+  "workbench.tree.expandMode": "doubleClick",
+  "editor.autoIndent": "full",
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "editor.detectIndentation": false,
+  "git.autofetch": true,
+  "debug.showInStatusBar": "always",
+  "VsCodeTaskButtons.tasks": [
+    {
+      "label": "🌐 OpenCode web GUI",
+      "task": "run_opencode_web_gui"
+    },
+    {
+      "label": "▶️ Open elevator example",
+      "task": "open_example_model"
+    },
+    {
+      "label": "✅ Run CI",
+      "task": "run_ci"
+    }
+  ],
+  "files.associations": {
+    "*.py": "python"
+  }
+}

mbse-0.1.0/.vscode/tasks/open_example_model.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -e
+
+echo "Open elevator example"
+
+cd "$(dirname "$0")/../.."
+exec env PYTHONPATH=src python -m mbse.examples.elevator --open-browser

mbse-0.1.0/.vscode/tasks/run_ci.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+PYTHON=".venv/bin/python"
+
+if [ ! -x "$PYTHON" ]; then
+  python -m venv .venv
+fi
+
+if ! command -v dot >/dev/null; then
+  echo "Graphviz is required: install it and ensure 'dot' is on PATH."
+  exit 1
+fi
+
+"$PYTHON" -m pip install -e ".[test]" build
+"$PYTHON" -m ruff check .
+"$PYTHON" -m pytest
+"$PYTHON" -m build

mbse-0.1.0/.vscode/tasks/run_opencode_web_gui.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -e
+
+echo "🌐 OpenCode web GUI"
+
+# Validate required commands.
+if ! command -v opencode >/dev/null 2>&1; then
+    echo "❌ Error: opencode not found."
+    exit 1
+fi
+
+HOSTNAME="0.0.0.0"
+PORT="4096"
+
+exec opencode web --hostname "${HOSTNAME}" --port "${PORT}"

mbse-0.1.0/.vscode/tasks.json

@@ -0,0 +1,29 @@
+{
+  "version": "2.0.0",
+  "options": {
+    "env": {
+      "TASKS_PATH": "${workspaceFolder}/.vscode/tasks"
+    }
+  },
+  "tasks": [
+    {
+      "label": "run_opencode_web_gui",
+      "type": "shell",
+      "command": "${TASKS_PATH}/run_opencode_web_gui.sh"
+    },
+    {
+      "label": "open_example_model",
+      "type": "shell",
+      "command": "${TASKS_PATH}/open_example_model.sh"
+    },
+    {
+      "label": "run_ci",
+      "type": "shell",
+      "command": "${TASKS_PATH}/run_ci.sh",
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      }
+    }
+  ]
+}

mbse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MBSE
+
+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.

mbse-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: mbse
+Version: 0.1.0
+Summary: Python runtime and local web viewer for MBSE JSON models.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ferran-bofill-elausa/mbse
+Project-URL: Issues, https://github.com/ferran-bofill-elausa/mbse/issues
+Keywords: mbse,modeling,runtime,state-machine
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2<4,>=3.1
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: referencing<1,>=0.36
+Provides-Extra: test
+Requires-Dist: pytest<10,>=9; extra == "test"
+Requires-Dist: ruff<1,>=0.11; extra == "test"
+Dynamic: license-file
+
+# MBSE
+
+Python runtime and local web viewer for MBSE JSON models.
+
+## Install
+
+```bash
+pip install mbse
+```
+
+The web viewer requires [Graphviz](https://graphviz.org/) and its `dot`
+command on `PATH`.
+
+```bash
+# Ubuntu/Debian
+sudo apt install graphviz
+
+# macOS
+brew install graphviz
+```
+
+On Windows, install Graphviz from its [download page](https://graphviz.org/download/)
+and add its `bin` directory to `PATH`.
+
+## Model Validation And Discovery
+
+Load a project to validate its project document and every recognized MBSE JSON
+model below `project_root`. The registry rejects duplicate model ids, multiple
+contexts, and invalid entrypoints.
+
+```python
+from mbse.model.project.project_registry import ProjectRegistry
+
+registry = ProjectRegistry.load("project.json")
+models = registry.iterExecutableModels()
+print([model.getDocumentId() for model in models])
+```
+
+The registry validates JSON shape. Action-language handlers are normal Python
+imports and must be available in the active environment when the runtime
+executes them.
+
+## Automated Runtime Tests
+
+```python
+from mbse.model.project.project_registry import ProjectRegistry
+from mbse.runtime.runtime import Runtime
+
+registry = ProjectRegistry.load("project.json")
+runtime = Runtime()
+runtime.init(registry)
+runtime.play()
+runtime.sendEvent("start")  # A declared HSM event.
+
+assert runtime.getState()["id"] == "running"
+```
+
+Use `getExecutionLog()`, `getVariable()`, and `getState()` for assertions.
+`sendEvent()` and `getState()` require an HSM project entrypoint. See the
+[Runtime Layer](src/mbse/runtime/doc/runtime.md) for stepping and inspection.
+
+## Web Viewer
+
+```bash
+mbse-view project.json --open-browser
+```
+
+Run the packaged elevator example with nested Activity models:
+
+```bash
+mbse-example-view
+```
+
+The viewer lists every executable model, renders its diagram, and provides
+events, typed variables, execution logs, model-call stepping, and breakpoints.
+It is a local debugging tool that listens on `127.0.0.1` by default.
+
+The viewer requires an HSM project entrypoint. Activity models can be rendered,
+listed, and debugged when called from that entrypoint.
+
+## Documentation
+
+- [Model Layer](src/mbse/model/doc/model.md): JSON schemas, validation, and
+  project discovery.
+- [Context Model](src/mbse/model/context/doc/context_model.md),
+  [HSM Model](src/mbse/model/hsm/doc/hsm_model.md),
+  [Activity Model](src/mbse/model/activity/doc/activity_model.md), and
+  [Project Model](src/mbse/model/project/doc/project_model.md): authoring
+  formats.
+- [Runtime Layer](src/mbse/runtime/doc/runtime.md): execution and test API.
+- [HSM Runtime](src/mbse/runtime/hsm/doc/hsm_runtime.md) and
+  [Activity Runtime](src/mbse/runtime/activity/doc/activity_runtime.md):
+  execution semantics.
+- [Viewer Server](src/mbse_web_viewer/server/doc/server.md),
+  [Render Layer](src/mbse_web_viewer/render/doc/render.md), and
+  [Browser Viewer](src/mbse_web_viewer/static/doc/static.md): local visual
+  debugging architecture.
+- [Reference Project](tests/reference_model/project/doc/reference_project.md):
+  runnable multi-model fixture used by the test suite.
+- [Elevator Example](src/mbse/examples/elevator/README.md): packaged viewer
+  demonstration with nested Activity models.
+- [Test Suite](tests/): executable coverage and fixture documentation.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+ruff check .
+pytest
+```
+
+VS Code users can run the `✅ Run CI` status-bar button to create `.venv` when
+needed and execute the same validation steps as CI locally.
+
+## Releases
+
+### One-Time Setup
+
+Configure a branch protection rule for `main` that requires pull requests and
+the `CI / test` status check before merging. Do not push directly to `main`.
+
+Configure a PyPI pending publisher with:
+
+- Project name: `mbse`
+- GitHub owner: `<owner>`
+- Repository: `<repository>`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+### Change Flow
+
+1. Create a branch and open a pull request against `main`.
+2. Merge only after `CI / test` passes.
+
+### Release Flow
+
+1. After the release changes are merged, create and push a version tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The publish workflow validates, builds, and uploads the package to PyPI. A
+failed workflow never uploads a package, but does not remove the pushed tag.

mbse-0.1.0/README.md

@@ -0,0 +1,147 @@
+# MBSE
+
+Python runtime and local web viewer for MBSE JSON models.
+
+## Install
+
+```bash
+pip install mbse
+```
+
+The web viewer requires [Graphviz](https://graphviz.org/) and its `dot`
+command on `PATH`.
+
+```bash
+# Ubuntu/Debian
+sudo apt install graphviz
+
+# macOS
+brew install graphviz
+```
+
+On Windows, install Graphviz from its [download page](https://graphviz.org/download/)
+and add its `bin` directory to `PATH`.
+
+## Model Validation And Discovery
+
+Load a project to validate its project document and every recognized MBSE JSON
+model below `project_root`. The registry rejects duplicate model ids, multiple
+contexts, and invalid entrypoints.
+
+```python
+from mbse.model.project.project_registry import ProjectRegistry
+
+registry = ProjectRegistry.load("project.json")
+models = registry.iterExecutableModels()
+print([model.getDocumentId() for model in models])
+```
+
+The registry validates JSON shape. Action-language handlers are normal Python
+imports and must be available in the active environment when the runtime
+executes them.
+
+## Automated Runtime Tests
+
+```python
+from mbse.model.project.project_registry import ProjectRegistry
+from mbse.runtime.runtime import Runtime
+
+registry = ProjectRegistry.load("project.json")
+runtime = Runtime()
+runtime.init(registry)
+runtime.play()
+runtime.sendEvent("start")  # A declared HSM event.
+
+assert runtime.getState()["id"] == "running"
+```
+
+Use `getExecutionLog()`, `getVariable()`, and `getState()` for assertions.
+`sendEvent()` and `getState()` require an HSM project entrypoint. See the
+[Runtime Layer](src/mbse/runtime/doc/runtime.md) for stepping and inspection.
+
+## Web Viewer
+
+```bash
+mbse-view project.json --open-browser
+```
+
+Run the packaged elevator example with nested Activity models:
+
+```bash
+mbse-example-view
+```
+
+The viewer lists every executable model, renders its diagram, and provides
+events, typed variables, execution logs, model-call stepping, and breakpoints.
+It is a local debugging tool that listens on `127.0.0.1` by default.
+
+The viewer requires an HSM project entrypoint. Activity models can be rendered,
+listed, and debugged when called from that entrypoint.
+
+## Documentation
+
+- [Model Layer](src/mbse/model/doc/model.md): JSON schemas, validation, and
+  project discovery.
+- [Context Model](src/mbse/model/context/doc/context_model.md),
+  [HSM Model](src/mbse/model/hsm/doc/hsm_model.md),
+  [Activity Model](src/mbse/model/activity/doc/activity_model.md), and
+  [Project Model](src/mbse/model/project/doc/project_model.md): authoring
+  formats.
+- [Runtime Layer](src/mbse/runtime/doc/runtime.md): execution and test API.
+- [HSM Runtime](src/mbse/runtime/hsm/doc/hsm_runtime.md) and
+  [Activity Runtime](src/mbse/runtime/activity/doc/activity_runtime.md):
+  execution semantics.
+- [Viewer Server](src/mbse_web_viewer/server/doc/server.md),
+  [Render Layer](src/mbse_web_viewer/render/doc/render.md), and
+  [Browser Viewer](src/mbse_web_viewer/static/doc/static.md): local visual
+  debugging architecture.
+- [Reference Project](tests/reference_model/project/doc/reference_project.md):
+  runnable multi-model fixture used by the test suite.
+- [Elevator Example](src/mbse/examples/elevator/README.md): packaged viewer
+  demonstration with nested Activity models.
+- [Test Suite](tests/): executable coverage and fixture documentation.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+ruff check .
+pytest
+```
+
+VS Code users can run the `✅ Run CI` status-bar button to create `.venv` when
+needed and execute the same validation steps as CI locally.
+
+## Releases
+
+### One-Time Setup
+
+Configure a branch protection rule for `main` that requires pull requests and
+the `CI / test` status check before merging. Do not push directly to `main`.
+
+Configure a PyPI pending publisher with:
+
+- Project name: `mbse`
+- GitHub owner: `<owner>`
+- Repository: `<repository>`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+### Change Flow
+
+1. Create a branch and open a pull request against `main`.
+2. Merge only after `CI / test` passes.
+
+### Release Flow
+
+1. After the release changes are merged, create and push a version tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The publish workflow validates, builds, and uploads the package to PyPI. A
+failed workflow never uploads a package, but does not remove the pushed tag.

mbse-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=69", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mbse"
+dynamic = ["version"]
+description = "Python runtime and local web viewer for MBSE JSON models."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mbse", "modeling", "runtime", "state-machine"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "Jinja2>=3.1,<4",
+  "jsonschema>=4.26,<5",
+  "referencing>=0.36,<1",
+]
+
+[project.scripts]
+mbse-view = "mbse_web_viewer.server.viewer_app:main"
+mbse-example-view = "mbse.examples.elevator:main"
+
+[project.urls]
+Repository = "https://github.com/ferran-bofill-elausa/mbse"
+Issues = "https://github.com/ferran-bofill-elausa/mbse/issues"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=9,<10",
+  "ruff>=0.11,<1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools_scm]
+version_scheme = "no-guess-dev"
+local_scheme = "no-local-version"
+
+[tool.setuptools.package-data]
+"*" = [
+  "*.css",
+  "*.html",
+  "*.j2",
+  "*.js",
+  "*.json",
+  "*.md",
+  "*.svg",
+]
+
+[tool.ruff]
+line-length = 80
+indent-width = 2
+target-version = "py311"
+
+[tool.ruff.lint]
+# TODO: Restore "I" and fix the existing import ordering violations.
+select = [
+  "E",  # pycodestyle errors
+  "F",  # pyflakes (real errors)
+]
+
+# TODO: Fix the existing violations and remove these exceptions.
+ignore = [
+  "E402",  # Module docstrings intentionally follow future imports.
+  "E501",  # Existing source has not yet been wrapped to the configured width.
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mbse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+