ofplang-export 0.1.0__tar.gz

ofplang_export-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Normalise line endings in the repository; CI runs on Linux.
+* text=auto eol=lf
+*.png binary
+*.svg text eol=lf

ofplang_export-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Working notes — not published (same convention as the sibling ofplang repos).
+/dev-notes/
+
+# Node / Vite
+node_modules/
+dist/
+dist-single/
+*.tsbuildinfo
+
+# Datasets are generated from external/ at build time (design.md D9 ①).
+/web/public/datasets/
+
+# Python
+__pycache__/
+*.egg-info/
+/build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+# Built from web/ by `npm run build:single`; the wheel carries it (design.md D50).
+/ofplang/export/_template/
+
+# Editor / OS
+.DS_Store
+Thumbs.db
+*.local
+
+# Playwright
+/web/shots/
+/web/test-results/
+/web/playwright-report/
+/web/blob-report/

ofplang_export-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/ofplang-schedule"]
+	path = external/ofplang-schedule
+	url = https://github.com/ofplang/schedule.git

ofplang_export-0.1.0/LICENSE

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

ofplang_export-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# setuptools-scm puts every tracked file in the sdist. The viewer template is
+# built, not tracked, so it is named here; the web sources it is built from are
+# not Python and stay out.
+include ofplang/export/_template/viewer.html
+prune web
+prune prototype
+prune external
+prune .github
+prune skills

ofplang_export-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: ofplang-export
+Version: 0.1.0
+Summary: Write Object-flow Programming Language documents out in a form people read.
+Author-email: Kazunari Kaizu <kwaizu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ofplang/export
+Project-URL: Repository, https://github.com/ofplang/export
+Project-URL: Viewer, https://ofplang.github.io/export/
+Keywords: ofplang,dataflow,workflow,schedule,viewer,html
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# ofplang export
+
+[![CI](https://github.com/ofplang/export/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/export/actions/workflows/ci.yml)
+
+Readable views of [ofplang](https://github.com/ofplang/spec) documents: a
+workflow as its dataflow graph, and the execution plans
+[`ofp-schedule`](https://github.com/ofplang/schedule) produces from it, shown
+side by side and linked — as a web site, and as one self-contained HTML file.
+
+It reads the documents the ofplang specifications define and nothing more, so
+it does not depend on any dialect built on top of them.
+
+```sh
+pip install ofplang-export
+ofp-export view plan.yaml -o plan.html        # a plan; its workflow and environment come from its meta
+ofp-export view workflow.yaml -o wf.html      # a workflow on its own
+```
+
+`ofp-export view` writes the viewer as **one HTML file with the documents in
+it**, to open from disk or send to someone. It is also meant to be reachable as
+`ofp export view` and, under labcode, `lc export view`.
+
+**→ [ofplang.github.io/export](https://ofplang.github.io/export/)**
+— ten plans are bundled; `?doc=plate_batch` opens one directly. Drop your own
+YAML on the window to read that instead: a plan, a workflow, an environment, or
+all three at once. A workflow on its own is fine — the graph does not need a
+plan to be read. Either pane can take the whole window: *Both / Workflow / Plan*
+in the top bar, or `&layout=workflow` / `&layout=plan` in the address.
+
+The point is to be able to hand someone a URL. They open it and see the
+dataflow graph and the Gantt chart of a plan side by side, linked: pick a bar
+and the workflow node it came from lights up, pick a node and every bar under
+it lights up. No install, no server, no Python.
+
+> **Status: early but usable.** Both panes work and are linked: pick a bar and
+> the workflow box it came from lights up, pick a box and everything under it
+> lights up in the plan. Plans can be exported as SVG or put in a link.
+> `prototype/` holds the single-file look-and-feel study the visual decisions
+> were made against.
+
+## The command
+
+```sh
+ofp-export view <file>... [-o OUT] [--layout split|workflow|plan] [--gantt device|flow|activity]
+                          [--name NAME] [--no-follow] [--json]
+```
+
+- Files are a plan, a workflow and/or an environment, in any order; which is
+  which is read from the file. A plan's `meta` supplies the workflow and the
+  environment unless they are given (`--no-follow` turns that off).
+- Without `-o` the HTML goes to standard output, as `ofp-schedule` does with a
+  plan. With `-o` the path written is printed; `--json` prints a summary instead.
+- Exit codes: **0** written (warnings, if any, on stderr — parts of a workflow
+  the viewer shows only as source structure), **2** bad input, **3** refused
+  and nothing written — a joint plan (several workflows scheduled together as
+  jobs), which this viewer does not draw.
+
+[`skills/ofp-export/SKILL.md`](skills/ofp-export/SKILL.md) says the same for an
+agent calling the command, as a skill to install where the agent looks for them.
+
+## A single file
+
+The same viewer also builds as **one self-contained HTML file** that carries
+its documents inside it: open it from disk, no server, nothing beside it.
+`npm run build:single` writes the empty template, `web/dist-single/viewer.html`
+(also kept as the `viewer-template` artifact of every CI run), and
+`web/scripts/embed.mjs` puts documents into it:
+
+```sh
+node scripts/embed.mjs dist-single/viewer.html out.html plan.yaml --workflow w.yaml --env e.yaml
+```
+
+The documents go in as the YAML text as written, in one element —
+`<script type="application/json" id="ofp-documents" data-contract="1">` — and
+the page reads them with the same reader it uses for a dropped file. An empty
+template (`null` in that element) is an offline viewer to drop files on. The
+web fonts stay a link, so offline the page falls back to system fonts; *Copy
+link* is hidden, since a link made from a file on disk would point at the disk.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `web/` | the application — Vite + TypeScript, no runtime dependency beyond `yaml` |
+| `web/src/model/` | types for the workflow, the environment and the execution document |
+| `web/src/read/` | YAML → those types; the only part that tracks the specifications |
+| `web/src/model/scene.ts` | the indices every view is built on — by node, by arc, by machine |
+| `web/src/layout/` | lanes, bars and the time scale; pure functions, no DOM |
+| `web/src/view/` | SVG rendering, the inspector, and the SVG export |
+| `web/scripts/collect-datasets.mjs` | turns the submodule's examples into the bundled datasets |
+| `web/scripts/build-single.mjs` | folds the build into the one-file viewer template |
+| `web/scripts/embed.mjs` | puts documents into that template — the contract, in one place |
+| `ofplang/export/` | the `ofp-export` Python package; `template.py` is the same contract in Python |
+| `tests/` | its tests (pytest), against the pinned submodule's examples |
+| `web/tests/golden/` | every example the pinned submodule ships must read |
+| `external/ofplang-schedule` | submodule, pinned by tag — specifications and examples |
+| `prototype/` | a single-file look-and-feel study; not the codebase |
+
+## Why a TypeScript reader instead of reusing the Python one
+
+The sibling repositories own the specifications and the semantics, and this one
+does not modify them. It also has to run with nothing installed on the viewer's
+machine, which rules out a Python pre-processing step. So the document readers
+here are a deliberate, bounded re-implementation of two stable schemas —
+`SPECIFICATIONS.md` §5 (environment) and §6 (execution document) — kept honest
+by the golden test against the pinned submodule's own examples.
+
+Anything outside that subset — `$import`, generics, structured nodes, and
+joint plans that schedule several workflows together as jobs — is refused
+rather than guessed at.
+
+## Working on it
+
+```sh
+git clone --recurse-submodules git@github.com:ofplang/export.git
+cd web
+npm install
+
+npm run dev        # development server (collects the datasets first)
+npm run datasets   # rebuild public/datasets/ from external/
+npm run typecheck  # tsc --noEmit
+npm test           # golden tests against external/ofplang-schedule
+npm run build      # typecheck + production build into web/dist
+npm run build:single  # …and the one-file template into web/dist-single
+npm run test:e2e   # the browser tests (builds the template first)
+```
+
+The Python package, from the repository root (after `npm run build:single`,
+which also puts the template into `ofplang/export/_template/`):
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+A release is a `v*` tag: `publish.yml` builds the template and the wheel from
+the same commit and publishes through PyPI trusted publishing (an `rc` tag goes
+to TestPyPI). Installing straight from git gives no template — it is built, not
+committed — and the command says so.
+
+Already cloned without `--recurse-submodules`? `git submodule update --init`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ofplang_export-0.1.0/README.md

@@ -0,0 +1,145 @@
+# ofplang export
+
+[![CI](https://github.com/ofplang/export/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/export/actions/workflows/ci.yml)
+
+Readable views of [ofplang](https://github.com/ofplang/spec) documents: a
+workflow as its dataflow graph, and the execution plans
+[`ofp-schedule`](https://github.com/ofplang/schedule) produces from it, shown
+side by side and linked — as a web site, and as one self-contained HTML file.
+
+It reads the documents the ofplang specifications define and nothing more, so
+it does not depend on any dialect built on top of them.
+
+```sh
+pip install ofplang-export
+ofp-export view plan.yaml -o plan.html        # a plan; its workflow and environment come from its meta
+ofp-export view workflow.yaml -o wf.html      # a workflow on its own
+```
+
+`ofp-export view` writes the viewer as **one HTML file with the documents in
+it**, to open from disk or send to someone. It is also meant to be reachable as
+`ofp export view` and, under labcode, `lc export view`.
+
+**→ [ofplang.github.io/export](https://ofplang.github.io/export/)**
+— ten plans are bundled; `?doc=plate_batch` opens one directly. Drop your own
+YAML on the window to read that instead: a plan, a workflow, an environment, or
+all three at once. A workflow on its own is fine — the graph does not need a
+plan to be read. Either pane can take the whole window: *Both / Workflow / Plan*
+in the top bar, or `&layout=workflow` / `&layout=plan` in the address.
+
+The point is to be able to hand someone a URL. They open it and see the
+dataflow graph and the Gantt chart of a plan side by side, linked: pick a bar
+and the workflow node it came from lights up, pick a node and every bar under
+it lights up. No install, no server, no Python.
+
+> **Status: early but usable.** Both panes work and are linked: pick a bar and
+> the workflow box it came from lights up, pick a box and everything under it
+> lights up in the plan. Plans can be exported as SVG or put in a link.
+> `prototype/` holds the single-file look-and-feel study the visual decisions
+> were made against.
+
+## The command
+
+```sh
+ofp-export view <file>... [-o OUT] [--layout split|workflow|plan] [--gantt device|flow|activity]
+                          [--name NAME] [--no-follow] [--json]
+```
+
+- Files are a plan, a workflow and/or an environment, in any order; which is
+  which is read from the file. A plan's `meta` supplies the workflow and the
+  environment unless they are given (`--no-follow` turns that off).
+- Without `-o` the HTML goes to standard output, as `ofp-schedule` does with a
+  plan. With `-o` the path written is printed; `--json` prints a summary instead.
+- Exit codes: **0** written (warnings, if any, on stderr — parts of a workflow
+  the viewer shows only as source structure), **2** bad input, **3** refused
+  and nothing written — a joint plan (several workflows scheduled together as
+  jobs), which this viewer does not draw.
+
+[`skills/ofp-export/SKILL.md`](skills/ofp-export/SKILL.md) says the same for an
+agent calling the command, as a skill to install where the agent looks for them.
+
+## A single file
+
+The same viewer also builds as **one self-contained HTML file** that carries
+its documents inside it: open it from disk, no server, nothing beside it.
+`npm run build:single` writes the empty template, `web/dist-single/viewer.html`
+(also kept as the `viewer-template` artifact of every CI run), and
+`web/scripts/embed.mjs` puts documents into it:
+
+```sh
+node scripts/embed.mjs dist-single/viewer.html out.html plan.yaml --workflow w.yaml --env e.yaml
+```
+
+The documents go in as the YAML text as written, in one element —
+`<script type="application/json" id="ofp-documents" data-contract="1">` — and
+the page reads them with the same reader it uses for a dropped file. An empty
+template (`null` in that element) is an offline viewer to drop files on. The
+web fonts stay a link, so offline the page falls back to system fonts; *Copy
+link* is hidden, since a link made from a file on disk would point at the disk.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `web/` | the application — Vite + TypeScript, no runtime dependency beyond `yaml` |
+| `web/src/model/` | types for the workflow, the environment and the execution document |
+| `web/src/read/` | YAML → those types; the only part that tracks the specifications |
+| `web/src/model/scene.ts` | the indices every view is built on — by node, by arc, by machine |
+| `web/src/layout/` | lanes, bars and the time scale; pure functions, no DOM |
+| `web/src/view/` | SVG rendering, the inspector, and the SVG export |
+| `web/scripts/collect-datasets.mjs` | turns the submodule's examples into the bundled datasets |
+| `web/scripts/build-single.mjs` | folds the build into the one-file viewer template |
+| `web/scripts/embed.mjs` | puts documents into that template — the contract, in one place |
+| `ofplang/export/` | the `ofp-export` Python package; `template.py` is the same contract in Python |
+| `tests/` | its tests (pytest), against the pinned submodule's examples |
+| `web/tests/golden/` | every example the pinned submodule ships must read |
+| `external/ofplang-schedule` | submodule, pinned by tag — specifications and examples |
+| `prototype/` | a single-file look-and-feel study; not the codebase |
+
+## Why a TypeScript reader instead of reusing the Python one
+
+The sibling repositories own the specifications and the semantics, and this one
+does not modify them. It also has to run with nothing installed on the viewer's
+machine, which rules out a Python pre-processing step. So the document readers
+here are a deliberate, bounded re-implementation of two stable schemas —
+`SPECIFICATIONS.md` §5 (environment) and §6 (execution document) — kept honest
+by the golden test against the pinned submodule's own examples.
+
+Anything outside that subset — `$import`, generics, structured nodes, and
+joint plans that schedule several workflows together as jobs — is refused
+rather than guessed at.
+
+## Working on it
+
+```sh
+git clone --recurse-submodules git@github.com:ofplang/export.git
+cd web
+npm install
+
+npm run dev        # development server (collects the datasets first)
+npm run datasets   # rebuild public/datasets/ from external/
+npm run typecheck  # tsc --noEmit
+npm test           # golden tests against external/ofplang-schedule
+npm run build      # typecheck + production build into web/dist
+npm run build:single  # …and the one-file template into web/dist-single
+npm run test:e2e   # the browser tests (builds the template first)
+```
+
+The Python package, from the repository root (after `npm run build:single`,
+which also puts the template into `ofplang/export/_template/`):
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+A release is a `v*` tag: `publish.yml` builds the template and the wheel from
+the same commit and publishes through PyPI trusted publishing (an `rc` tag goes
+to TestPyPI). Installing straight from git gives no template — it is built, not
+committed — and the command says so.
+
+Already cloned without `--recurse-submodules`? `git submodule update --init`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ofplang_export-0.1.0/ofplang/export/__init__.py

@@ -0,0 +1,13 @@
+"""ofplang export: write ofplang documents out in a form people read.
+
+The one target so far is `view` — the interactive viewer as a single HTML
+file. See `ofplang.export.cli` for the command, `ofplang.export.template` for
+the contract between this package and the page it fills.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ofplang-export")
+except PackageNotFoundError:  # a source tree without installed metadata
+    __version__ = "0+unknown"

ofplang_export-0.1.0/ofplang/export/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())