Skip to content

Commit 46b659c

Browse files
hyperpolymathclaude
andcommitted
feat: add OPSM runtime extension — tool/runtime version management
Adds a complete runtime version management subsystem to OPSM: - Nickel contract (runtime-plugin.ncl) defining the RuntimePlugin type - 71 core plugins auto-converted from hyperpolymath asdf-tool-plugins - Faceted classification system (function, ecosystem, usage, tier) - Minter: interactive + quick-mode plugin definition creator - Provisioner: bootstrap installer reading Nickel definitions - Configurator: .tool-versions compatible version management - PanLL panel harness: visual runtime manager with trust dashboard - RSR repo generator: creates full RSR-compliant repos from plugins - Conversion script: batch converts asdf Bash plugins to Nickel Design: Nickel definitions are declarative and type-checked (no arbitrary code execution). Integrates with OPSM trust pipeline for attestation. Zig shim dispatcher planned for production (bootstrap uses Bash shims). Reads .tool-versions for asdf compatibility. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b5ccd81 commit 46b659c

82 files changed

Lines changed: 6382 additions & 4 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,12 @@ secrets/
8383
*.tmp
8484
/tmp/
8585

86+
# Release artifacts
87+
*.tar
88+
89+
# Runtime extension
90+
/runtime/community/*.ncl.bak
91+
8692
# Test/Coverage
8793
/coverage/
8894
htmlcov/

.machine_readable/6a2/STATE.a2ml

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,22 @@
44

55
[metadata]
66
project = "odds-and-sods-package-manager"
7-
version = "0.1.0"
8-
last-updated = "2026-03-15"
7+
version = "2.0.0"
8+
last-updated = "2026-03-23"
99
status = "active"
1010

1111
[project-context]
1212
name = "odds-and-sods-package-manager"
13-
completion-percentage = 0
14-
phase = "In development"
13+
completion-percentage = 45
14+
phase = "Active development"
15+
16+
[runtime-extension]
17+
added = "2026-03-23"
18+
status = "initial-implementation"
19+
core-plugins = 71
20+
community-plugins = 0
21+
contract-version = "1.0.0"
22+
tools = ["minter", "provisioner", "configurator", "convert-asdf-plugins"]
23+
panel-harness = "manifest.json + panel.html"
24+
rsr-generator = true
25+
notes = "Nickel-based runtime/tool version management. Faceted classification. PanLL panel harness. .tool-versions compatibility."

runtime/README.adoc

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= OPSM Runtime Extension
3+
:revdate: 2026-03-23
4+
:toc: macro
5+
6+
**Tool and runtime version management for OPSM.**
7+
8+
Manages developer tool versions (compilers, runtimes, CLIs) with the same
9+
trust pipeline, formal verification, and federation that OPSM brings to
10+
package management. Reads `.tool-versions` for asdf compatibility.
11+
12+
toc::[]
13+
14+
== Architecture
15+
16+
[source]
17+
----
18+
runtime/
19+
├── contract/ # Nickel contract (the spec)
20+
│ └── runtime-plugin.ncl # RuntimePlugin type definition
21+
├── core/ # hyperpolymath-maintained plugins (71)
22+
│ ├── zig.ncl
23+
│ ├── deno.ncl
24+
│ ├── erlang.ncl
25+
│ └── ...
26+
├── community/ # Community-contributed plugins
27+
├── tools/ # Developer tooling
28+
│ ├── convert-asdf-plugins.sh # Batch converter: asdf → Nickel
29+
│ ├── minter/
30+
│ │ ├── mint-runtime-plugin.sh # Interactive plugin creator
31+
│ │ └── generate-rsr-repo.sh # RSR repo generator
32+
│ ├── provisioner/
33+
│ │ └── provision.sh # Bootstrap installer
34+
│ └── configurator/
35+
│ └── configure.sh # Version management CLI
36+
├── panel-harness/ # PanLL integration
37+
│ ├── manifest.json # Panel manifest v2
38+
│ └── panel.html # Runtime manager UI
39+
└── README.adoc # This file
40+
----
41+
42+
== Quick Start
43+
44+
=== Create a new plugin (interactive)
45+
46+
[source,bash]
47+
----
48+
./runtime/tools/minter/mint-runtime-plugin.sh
49+
----
50+
51+
=== Create a new plugin (one-liner)
52+
53+
[source,bash]
54+
----
55+
./runtime/tools/minter/mint-runtime-plugin.sh --quick age FiloSottile/age age
56+
----
57+
58+
=== Install a runtime
59+
60+
[source,bash]
61+
----
62+
./runtime/tools/provisioner/provision.sh runtime/core/just.ncl 1.46.0
63+
----
64+
65+
=== Install from .tool-versions
66+
67+
[source,bash]
68+
----
69+
./runtime/tools/provisioner/provision.sh --from-tool-versions .tool-versions
70+
----
71+
72+
=== Generate a standalone RSR repo for a plugin
73+
74+
[source,bash]
75+
----
76+
./runtime/tools/minter/generate-rsr-repo.sh runtime/core/zig.ncl
77+
----
78+
79+
== Contributing a Plugin
80+
81+
**Option A: Single file PR (recommended)**
82+
83+
1. Create a `.ncl` file using the minter or by hand
84+
2. Place it in `runtime/community/`
85+
3. Open a PR — the Nickel contract validates your definition
86+
87+
**Option B: Standalone repo**
88+
89+
1. Run `generate-rsr-repo.sh` with your `.ncl` file
90+
2. Push to your own GitHub repo
91+
3. We periodically vendor community repos into `runtime/community/`
92+
93+
Either way, you get full attribution (git blame, contributor field in Nickel).
94+
95+
== Faceted Classification
96+
97+
Plugins are classified across orthogonal facets, not a tree:
98+
99+
[cols="1,3"]
100+
|===
101+
| Facet | Values
102+
103+
| **Function** | Runtime, Compiler, Linter, Formatter, BuildTool, PackageManager, Database, Security, Server, CLI, Editor, ContainerTool
104+
| **Ecosystem** | beam, rust, javascript, python, jvm, go, zig, haskell, system, ...
105+
| **Usage** | Interactive (REPL), Batch (compiler), Daemon (server), Oneshot (CLI)
106+
| **Tier** | Core (hyperpolymath), Community (contributed), Experimental (auto-converted), Upstream (vendored)
107+
|===
108+
109+
== PanLL Integration
110+
111+
The panel harness at `panel-harness/` provides:
112+
113+
- Visual runtime browser with faceted filtering
114+
- One-click install with trust pipeline results
115+
- Per-panel version switching (PanLL environment injection)
116+
- Project `.tool-versions` editor
117+
- Trust dashboard with SLSA provenance and attestation scores
118+
119+
== Acknowledgements
120+
121+
OPSM's runtime plugin catalogue builds on the pioneering work of the asdf
122+
plugin ecosystem. We gratefully acknowledge the hundreds of plugin authors
123+
whose work established the patterns and tool mappings that informed our
124+
Nickel definitions. Original asdf plugins remain available at their
125+
respective repositories and are credited in each OPSM plugin file.

0 commit comments

Comments
 (0)