Metadata-Version: 2.4
Name: runglet
Version: 0.5.1
Summary: Typed PLC language and offline toolchain built for coding-agent authoring and exact-scan testing
Author: Runglet contributors
License-Expression: MPL-2.0
Project-URL: Homepage, https://pypi.org/project/runglet/
Project-URL: Repository (private alpha), https://github.com/vedit/Runglet
Project-URL: Documentation (private alpha), https://vedit.github.io/Runglet/
Project-URL: Issues (private alpha), https://github.com/vedit/Runglet/issues
Project-URL: Changelog (private alpha), https://github.com/vedit/Runglet/blob/master/CHANGELOG.md
Project-URL: Releases (private alpha), https://github.com/vedit/Runglet/releases
Keywords: automation,compiler,coding-agents,control-systems,domain-specific-language,industrial-control,industrial-automation,language-server,ladder-logic,plc,plc-programming,static-analysis,verification,vscode
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSING.md
License-File: NOTICE
Requires-Dist: lark==1.3.1
Requires-Dist: lsprotocol==2025.0.0
Requires-Dist: pygls==2.1.1
Provides-Extra: dev
Requires-Dist: coverage==7.10.1; extra == "dev"
Requires-Dist: hypothesis==6.136.7; extra == "dev"
Requires-Dist: mypy==1.17.0; extra == "dev"
Requires-Dist: pyinstaller==6.21.0; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Requires-Dist: pytest-cov==6.2.1; extra == "dev"
Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
Requires-Dist: ruff==0.12.3; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs==1.6.1; extra == "docs"
Requires-Dist: mkdocs-material==9.7.7; extra == "docs"
Dynamic: license-file

# Runglet

[![PyPI](https://img.shields.io/pypi/v/runglet)](https://pypi.org/project/runglet/)
[![Python](https://img.shields.io/pypi/pyversions/runglet)](https://pypi.org/project/runglet/)
[![License](https://img.shields.io/badge/license-MPL--2.0-blue)](#contributing-and-license)

> **Internal alpha:** PyPI distribution is public for installation convenience. The
> GitHub repository, Releases, Issues, CI, and hosted documentation are intentionally
> private and their links require invited alpha access.

Runglet lets you develop PLC control software with coding agents instead of drawing
ladder diagrams by hand.

It is a typed, deterministic source language and offline toolchain. You describe
control intent and scan-level tests as text; Runglet gives people and agents structured
diagnostics, versioned authoring context, exact-scan scenarios, and deterministic
builds. A checked program lowers to canonical Relay IR and, for a supported target
subset, vendor artifacts such as ladder logic.

The aim is not to hide PLC semantics. It is to make scan behavior, state ownership,
interlocks, numeric policy, and output arbitration explicit enough for an agent to
write, inspect, test, repair, and review without using a vendor editor as the primary
programming environment.

You still need to understand the controlled process and the PLC execution model. You
should not have to learn a vendor's ladder drawing workflow just to express and test
that logic.

Runglet is alpha software. The compiler, reference runtime, formatter, language server,
VS Code extension, and offline project workflow are usable today. Target deployment is
still evidence-gated and is not production-ready. The current package is `0.5.1`; the
portable language specification is independently versioned and frozen at `0.22.0`.

## Why Runglet

- **Ladder is a target, not the authoring interface.** Application logic is written and
  tested as ordinary text. Supported backends take responsibility for the mechanical
  target representation.
- **Scan behavior is part of the program.** Snapshot-atomic state, following-scan
  commits, timer behavior, and output ownership are checked instead of inferred from
  rung order.
- **Tests live beside the logic.** Embedded scenarios run against an exact-scan
  reference runtime without a PLC or vendor IDE.
- **Builds are reviewable.** Source, Relay IR, target plans, profiles, and generated
  artifacts carry deterministic identities and stable semantic IDs.
- **Agents get a real development interface.** Generated workflow files, bounded context
  packs, stable diagnostics, JSON inspection, checked examples, and fail-closed target
  discovery keep an agent tied to the installed compiler rather than its memory of the
  language.

## Agentic development is a compiler feature

`runglet init` creates more than a sample program. It creates an agent-ready workspace
with task guidance, a machine-readable capability manifest, thin tool skills, agent
entry points, checked source, and a scaffold identity. From there, the supported loop
is explicit:

```text
requirements brief
  -> discover the installed language, libraries, and target limits
  -> author Runglet source and scenarios
  -> repair stable compiler diagnostics
  -> format, check, and run exact-scan tests
  -> inspect deterministic builds and target plans
  -> hand reviewable evidence to the target-specific engineering step
```

The agent does not need to read Runglet's Python implementation or guess syntax from a
prompt. These commands expose the contract it needs:

```shell
runglet authoring-context --profile core --format markdown
runglet inspect --package runglet.std.control --json
runglet check runglet.toml --json
runglet suite runglet.toml
runglet target inspect fatek-fbs --json
```

This does not remove the need to understand the controlled process, electrical design,
failure behavior, or commissioning boundary. It removes hand-authored ladder from the
normal implementation loop. Read the
[agentic authoring guide](https://vedit.github.io/Runglet/agentic-authoring/) for the
workspace contract and a practical task handoff.

## A one-minute example

Install the command-line application with `pipx`:

```shell
pipx install runglet==0.5.1
runglet init demo --name demo
cd demo
runglet check src/main.rung
runglet suite src/main.rung --scan-period-ms 10
```

The starter contains ordinary control logic and two executable scenarios:

```runglet
RULE run_permission:
  ID "RULE-RUN-PERMISSION-001"
  DRIVE permitted
  WHEN:
    start_requested
  END
END

OUTPUT_LOGIC demo_command:
  ID "LOGIC-DEMO-COMMAND-001"
  DEFAULT FALSE
  TURN_ON WHEN:
    permitted
  END
END
```

The suite result is short enough to read in a terminal and detailed enough to retain as
JSON when needed:

```text
SCENARIO SCENARIO-REQUESTED-COMMAND-001: PASS scans=1
SCENARIO SCENARIO-IDLE-COMMAND-001: PASS scans=1
SUMMARY passed=2 failed=0 total=2
```

Start with the [getting-started guide](https://vedit.github.io/Runglet/getting-started/)
for installation choices, VS Code setup, and the full authoring loop.

## What works today

| Surface | Current state |
|---|---|
| Language and compiler | Frozen language 0.22; typed analysis, canonical formatting, projects, packages, components, deterministic machines, bounded data, explicit numeric policies, executable-contract lifecycle, properties, and exact diagnostics |
| Reference execution | Exact-scan scenarios, traces, semantic coverage, properties, and mutation campaigns |
| Agentic authoring | Generated agent workflow and capability files, bounded context packs, stable JSON diagnostics, package/target discovery, deterministic scenarios, and reviewable evidence |
| Human authoring | CLI, LSP, and a VS Code extension with diagnostics, formatting, completion, hover, navigation, and compiler tasks |
| Standard library | Reviewed source packages for events, numeric/data handling, signals, validation, tables, filters, fixed-point control, and profiles |
| Relay IR builds | Deterministic, hash-bound, backend-neutral build artifacts |
| FATEK FBs target | A documented offline lowering subset with fail-closed planning; complete deployment evidence remains open |
| Siemens S7-1500 | Planned second backend: SCL first, then a LAD wrapper and a bounded direct-LAD subset |
| Certified safety or production deployment | Not claimed |

The current status and exact exclusions are maintained in
[Language readiness](https://vedit.github.io/Runglet/readiness-and-safety/), not inferred
from release notes or screenshots.

## Installation

Runglet requires Python 3.12 or later.

```shell
pipx install runglet==0.5.1
```

To install a reviewed wheel into an existing environment:

```shell
python -m pip install ./runglet-0.5.1-py3-none-any.whl
```

For invited alpha testers, tagged
[GitHub Releases](https://github.com/vedit/Runglet/releases) also provide:

- the Python wheel and source archive;
- a standalone Windows ZIP containing `runglet.exe`, `runglet-lsp.exe`, and their
  private runtime;
- the matching VS Code VSIX; and
- `SHA256SUMS` for the published assets.

The Windows executables launch directly and do not use PowerShell. See
[Windows installation](https://vedit.github.io/Runglet/getting-started/#standalone-windows-package).

For invited contributors with repository access, source development starts with:

```shell
git clone https://github.com/vedit/Runglet.git
cd Runglet
uv sync --extra dev --locked
```

## How it fits together

```text
Runglet source
    │
    ├── analysis, diagnostics, formatting, LSP
    │
    └── canonical Relay IR
          ├── reference scenarios, traces, properties
          ├── portable resource reports
          └── target preflight, planning, and review bundles
```

Relay IR is the portable semantic boundary. A backend must preserve the selected
execution model, use a named emulation strategy, or reject the program. Vendor syntax
acceptance alone is not treated as proof of equivalent behavior.

Physical addresses are not written into `.rung` source. Acquisition and output
publication live in separate, versioned binding manifests so logical behavior can be
reviewed and tested before a physical contract exists.

## Project workflow

Use a project layout when the program will have multiple files or standard-library
dependencies:

```shell
runglet init plant-control --name plant_control --layout project
cd plant-control
runglet authoring-context --profile core --format markdown
runglet check runglet.toml
runglet suite runglet.toml
runglet build runglet.toml --output build/main
```

Useful discovery commands include:

```shell
runglet help --all
runglet inspect --package runglet.std.control --json
runglet inspect --package runglet.std.control --example
runglet target list --json
runglet target inspect fatek-fbs --json
```

The [CLI and project guide](https://vedit.github.io/Runglet/cli-and-projects/) covers
locks, offline packages, target planning, and deterministic output ownership.

## Boundaries

Runglet is not a certified or qualified safety development tool. A passing check,
scenario suite, vendor import, simulator run, or isolated bench observation establishes
only the claim attached to that exact gate and artifact.

Authoring and compilation do not authorize contact with WinProLadder, a PLC, HIL, or
production equipment. Credited protection must remain independent unless a separate
safety lifecycle explicitly establishes otherwise.

Read [Readiness and safety](https://vedit.github.io/Runglet/readiness-and-safety/) before
using generated target logic beyond offline review.

## Documentation

The hosted links below currently require invited alpha access. The installed package
remains self-describing through `runglet help --all`, `runglet authoring-context`,
`runglet inspect --package`, and `runglet target inspect`.

- [Getting started](https://vedit.github.io/Runglet/getting-started/)
- [Agentic authoring](https://vedit.github.io/Runglet/agentic-authoring/)
- [Language tour](https://vedit.github.io/Runglet/language-tour/)
- [VS Code](https://vedit.github.io/Runglet/vscode/)
- [Scenarios and tracing](https://vedit.github.io/Runglet/scenarios-and-tracing/)
- [Standard library](https://vedit.github.io/Runglet/standard-library/)
- [Compiler and Relay IR](https://vedit.github.io/Runglet/compiler-and-relay-ir/)
- [Target support](https://vedit.github.io/Runglet/targets/)
- [Language reference](https://vedit.github.io/Runglet/language/grammar/)

## Contributing and license

Invited contributors can see
[CONTRIBUTING.md](https://github.com/vedit/Runglet/blob/master/CONTRIBUTING.md) for
the locked development workflow and review expectations. Please also read the
[code of conduct](https://github.com/vedit/Runglet/blob/master/CODE_OF_CONDUCT.md) and
use the [security policy](https://github.com/vedit/Runglet/blob/master/SECURITY.md) for
private vulnerability reports.

Runglet is licensed under the Mozilla Public License 2.0. User-authored Runglet programs
and compiler-generated artifacts are not relicensed merely because Runglet processes
them. The precise boundary is described in
[LICENSING.md](https://github.com/vedit/Runglet/blob/master/LICENSING.md).
