factorysemantics-mes 0.2.0__tar.gz → 0.3.1__tar.gz

factorysemantics_mes-0.3.1/.dockerignore

@@ -0,0 +1,78 @@
+# What never goes into an image's build context.
+#
+# Every `docker build` here reads this file, and `docker/Dockerfile` copies
+# named paths rather than the whole tree, so this is about the context that is
+# sent to the builder, not about what ends up in the image. Two reasons it is
+# worth having: a plant's own data must never be able to reach a published
+# image by accident, and the generated replay under `labs/multiplant/*/out/` is
+# 9.7 MB for bottling alone - it is generated from the seed in `line.json` on
+# first start and is never shipped.
+#
+# What this excludes:
+#
+#   */out/, .data/        generated line data and plant state, written at run
+#                         time, regenerated from a seed, never shipped
+#   *.db, *.sqlite, *-wal a plant's own database, in every spelling the code
+#                         writes, plus its write-ahead files
+#   logs/, *.log          a plant's logs
+#   .env, *.pem, *.key,   credentials and certificates. `.env.*` as well as
+#   certs/, .secrets/     `.env`, because an editor's `.env.bak` is a
+#                         committable copy of a credentials file
+#   .venv/, __pycache__/, a developer machine's build leavings, which are for
+#   *.egg-info/, .git/    this platform and this interpreter, not the image's
+#   lab-results/,         evidence from one machine on one day
+#   backups/
+#
+# Wholesale rules rather than an enumerated list of directories, for the reason
+# `.gitignore` gives at the same place: an enumerated rule goes stale silently
+# the first time the code writes somewhere new.
+#
+# Nothing here may match a path `docker/Dockerfile` copies, and nothing here
+# may match a path `pyproject.toml` force-includes into the wheel. The day one
+# does, the image loses a plant pack and `pip install` inside it fails - which
+# is what happened on 2026-10-12 for the other reason, and is why
+# `tests/test_the_docker_image_carries_the_packs.py` reads this file too.
+
+# Generated line data and plant state
+**/out/
+**/.data/
+lab-results/
+backups/
+
+# A plant's own database and logs
+**/*.db
+**/*.db-wal
+**/*.db-shm
+**/*.sqlite
+**/*.sqlite3
+**/*.parquet
+**/logs/
+**/*.log
+
+# Credentials and certificates
+.env
+.env.*
+!.env.example
+**/.secrets/
+**/certs/
+**/*.pem
+**/*.key
+**/*.token
+
+# This machine's build leavings
+.git/
+.venv/
+venv/
+**/__pycache__/
+**/*.py[cod]
+**/*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+site/
+skills-dist/
+*.zip

factorysemantics_mes-0.3.1/.env.example

@@ -0,0 +1,112 @@
+# FactorySemantics MES configuration. Copy to .env and adjust; every value has a sane default.
+# All settings are read from environment variables prefixed MES_ (or this file).
+
+# --- Database -------------------------------------------------------------
+# SQLite (default, zero-setup):
+MES_DATABASE_URL=sqlite:///fsmes.db
+# PostgreSQL (scale deployment, matches docker-compose):
+# MES_DATABASE_URL=postgresql+psycopg://mes:mes@localhost:5432/mes_twin
+
+# --- Which plant is this --------------------------------------------------
+# The shape of this deployment: laptop | plant | fleet. `laptop` is the
+# evaluation profile - `fsmes demo` and the labs - and needs nothing else set
+# here. Anything else refuses to start without a plant name.
+MES_PLANT_PROFILE=laptop
+# What this plant is called. It appears on every screen, in /health, on every
+# metric, in every backup and on every namespace event, so a person looking
+# at two plants can tell which one they are looking at. Letters, digits and
+# _ . : @ = - only: it is published as one segment of the namespace topic.
+# MES_PLANT_NAME=northgate
+# The zone this plant works in, as an IANA name. It decides where a shift
+# starts, when a gauge falls due, and what time every screen shows. Left out,
+# the MES uses this machine's own zone and says "defaulted" wherever it
+# reports it. On Windows the zone database comes from `pip install tzdata`.
+# MES_PLANT_TIMEZONE=America/Chicago
+
+# --- Shadow mode ----------------------------------------------------------
+# The MES watches a real plant and can change nothing in it: no PLC
+# write-back, no live ERP, no MQTT publish, nothing about this plant off the
+# box. This is how you run it beside the MES already in charge on a line.
+# Read once at start-up; leaving it is a restart, recorded in the audit
+# trail. With it on, MES_ERP_MODE may only be off or file and MES_UNS_MODE
+# only off or log - anything else refuses to start and says which variable.
+# See docs/operate/shadow-mode.md.
+MES_SHADOW=false
+
+# --- Logging --------------------------------------------------------------
+MES_LOG_LEVEL=INFO
+MES_LOG_DIR=logs
+
+# --- API ------------------------------------------------------------------
+MES_API_HOST=127.0.0.1
+MES_API_PORT=8000
+
+# --- OPC UA ---------------------------------------------------------------
+# Endpoint the agent connects to. Points at the bundled simulator by default;
+# change to your real PLC/gateway endpoint to leave twin mode.
+MES_OPC_ENDPOINT=opc.tcp://127.0.0.1:4840/mes-twin/sim
+MES_OPC_NAMESPACE=urn:mes-twin:sim
+MES_TAG_MAP_FILE=config/tag_map.json
+# The KepSim six-station line instead of the two demo machines:
+#   config/tag_map_kepsim.json   played back by `fsmes run-opc-sim --replay`
+#   config/tag_map_kepware.json  read from a real KEPServerEX (see labs/kepsim)
+
+# Client security. Empty = anonymous and unencrypted, which is all the bundled
+# simulator needs. A real server usually offers only SignAndEncrypt with a named
+# user — Kepware does. The certificate is minted on first use.
+# MES_OPC_SECURITY=Basic256Sha256,SignAndEncrypt
+# MES_OPC_USER=Administrator
+# MES_OPC_PASSWORD=
+MES_OPC_CERT_DIR=certs
+MES_OPC_APPLICATION_URI=urn:mes-twin:agent
+
+# Where `fsmes run-opc-sim --replay` reads the generated KepSim tables from.
+MES_REPLAY_DIR=labs/kepsim/out
+
+# --- ERP integration ------------------------------------------------------
+# rest = poll an ERP REST API (mock ERP by default) | file = B2MML-style file
+# exchange via the inbox/outbox folders | erpnext = a real ERPNext/Frappe
+# instance | off = no ERP sync
+MES_ERP_MODE=rest
+MES_ERP_BASE_URL=http://127.0.0.1:8001
+MES_ERP_INBOX=erp_exchange/inbox
+MES_ERP_OUTBOX=erp_exchange/outbox
+MES_ERP_ARCHIVE=erp_exchange/archive
+MES_ERP_POLL_SECONDS=5
+
+# --- ERPNext (MES_ERP_MODE=erpnext) ---------------------------------------
+# One bench can serve several sites on one port; the site is chosen by the Host
+# header. Leave MES_ERPNEXT_SITE empty only if the bench serves a single site —
+# on a shared one, the default site is somebody else's company.
+MES_ERPNEXT_BASE_URL=http://localhost:8090
+MES_ERPNEXT_SITE=mes.localhost
+MES_ERPNEXT_USER=Administrator
+MES_ERPNEXT_PASSWORD=admin   # the Frappe dev-bench default; a real site uses the API key below
+# Preferred for a long-running worker (ERPNext: User -> API Access -> generate):
+# MES_ERPNEXT_API_KEY=
+# MES_ERPNEXT_API_SECRET=
+# Which company's work orders to import. Empty (the default) imports every
+# company's; a bench serving more than one company must set this.
+# MES_ERPNEXT_COMPANY=Your Company
+# Post finished quantities as real Manufacture stock entries. Off records what
+# the MES counted without moving ERPNext's stock.
+MES_ERPNEXT_POST_STOCK_ENTRY=true
+
+# --- Simulator ------------------------------------------------------------
+# >1.0 makes the simulated plant run faster than real time (demo uses 4).
+MES_SIM_SPEED=1.0
+
+# --- The judgment model (development build loop only) ---------------------
+# A hosted model asked fixed, typed questions about a simulated run's log,
+# beside the local model's open-ended pass. Nothing in the product asks it
+# anything, and shadow mode refuses the call outright (register: llm.jev).
+# Unset — the normal case — and the run record says it was not asked.
+# The key belongs in this file or the environment, never in the repository.
+# MES_JEV_API_KEY=
+# Pinned, never a moving alias: an answer stored against `-latest` cannot be
+# read again. The version actually served is stored with every answer.
+# `fsmes jev models --resolve` says which concrete version answers today.
+# MES_JEV_MODEL=jev-1.13.0
+# Empty uses the client's own endpoint.
+# MES_JEV_BASE_URL=
+# MES_JEV_TIMEOUT_SECONDS=5.0

factorysemantics_mes-0.3.1/.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+updates:
+  # Python updates run through the `uv` ecosystem, not `pip`, because this
+  # repository has a lockfile and CI requires it to be current.
+  #
+  # `pip` edits the version constraints in `pyproject.toml` and has no
+  # concept of `uv.lock` — it never regenerates it. Since #74 made
+  # `uv lock --check` a required check, that combination meant every
+  # Python bump Dependabot opened arrived with a stale lock and failed
+  # `lockfile` on arrival; #86 (ruff 0.16.7 → 0.16.8) is the one that made
+  # it obvious. The `uv` ecosystem reads `pyproject.toml` and `uv.lock`
+  # together and writes both in the same commit, so the required check
+  # passes without anyone running `uv lock` by hand.
+  #
+  # The group below is carried over unchanged. It groups on `patterns`,
+  # which `uv` supports; the one grouping key `uv` does not support is
+  # `dependency-type`, and this repository never used it. `uv` also treats
+  # every declared dependency as a production one — it draws no dev/prod
+  # line — which changes nothing here, because `patterns: ["*"]` already
+  # puts the runtime dependencies and the `dev`, `docs`, `postgres`,
+  # `mcp`, `agent`, `mqtt` and `jev` extras in one pull request.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

factorysemantics_mes-0.3.1/.github/scripts/assistant_folder_from_the_wheel.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Prove the assistant folder comes out of a built wheel, offline, on Linux and
+on Windows.
+
+This is the first line of the assistant handoff's definition of done, checked
+the way a person would check it:
+
+1. `pipx install factorysemantics-mes` on a PC that may reach the internet
+   once and never again - here, a fresh virtual environment with the wheel in
+   it and the network off afterwards;
+2. `fsmes skills list` names `assistant`, and says the folder came out of the
+   installation rather than out of a checkout lying above the working
+   directory;
+3. `fsmes skills unpack assistant ./x` writes the seven markdown pages **and**
+   `plant-from-your-mes/` inside them, every file byte-for-byte the
+   checkout's;
+4. nothing in what it wrote is a symlink, and the repository has no second
+   copy of the nested folder. That pair is the whole reason `INCLUDES` exists:
+   one copy in git, nested at build and unpack time, and a zip of a symlink
+   unpacks on Windows as a text file with a path in it.
+
+Windows as well as Linux because the first person to install this was on
+Windows, and because a path separator is the kind of thing that only breaks
+there.
+
+`plant_from_shape.py` beside this already builds the two virtual environments
+and turns the network off; this imports those helpers rather than keeping a
+second copy of them, for the same reason the skill folder has one copy.
+
+Usage:  python .github/scripts/assistant_folder_from_the_wheel.py --wheel dist/<name>.whl
+"""
+
+from __future__ import annotations
+
+import argparse
+import filecmp
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from plant_from_shape import (
+    AS_WORDS,
+    fail,
+    make_venv,
+    offline,
+    prove_the_network_is_off,
+    run,
+    say,
+    venv_bin,
+)
+
+#: The skill a person downloads, and the one it carries.
+SKILL = "assistant"
+INSIDE = "plant-from-your-mes"
+#: Pages the folder is useless without, and the two files that prove the
+#: nesting really happened. Named here rather than globbed so that a
+#: `force-include` line somebody forgets is a red job and not a quiet gap.
+MUST_CARRY = (
+    "SKILL.md",
+    "README.md",
+    "0-how-to-help.md",
+    "1-install.md",
+    "2-your-plant.md",
+    "3-shadow-mode.md",
+    "4-migration.md",
+    f"{INSIDE}/SKILL.md",
+    f"{INSIDE}/scripts/profile.py",
+)
+
+
+def what_the_checkout_holds(repo: Path) -> list[str]:
+    """Every file the unpacked folder should have, from the one copy in git."""
+    wanted = []
+    for name, under in ((SKILL, ""), (INSIDE, f"{INSIDE}/")):
+        folder = repo / "skills" / name
+        wanted += [f"{under}{p.relative_to(folder).as_posix()}"
+                   for p in folder.rglob("*")
+                   if p.is_file() and "__pycache__" not in p.parts]
+    return sorted(wanted)
+
+
+def the_repository_has_one_copy(repo: Path) -> None:
+    """No `skills/assistant/plant-from-your-mes/` in git, and no symlink to it."""
+    second = repo / "skills" / SKILL / INSIDE
+    if second.exists() or second.is_symlink():
+        fail(f"skills/{SKILL}/{INSIDE} exists in the checkout. The nested folder is "
+             f"made at build time from fsmes.skills.INCLUDES, from the one copy in "
+             f"skills/{INSIDE}/ — a second copy in git drifts, and a symlink unpacks "
+             f"on Windows as a text file with a path in it.")
+    linked = [p for p in (repo / "skills" / SKILL).rglob("*") if p.is_symlink()]
+    if linked:
+        fail(f"symlink(s) in skills/{SKILL}/: {[p.name for p in linked]}")
+    say(f"  skills/{SKILL}/ is {len(list((repo / 'skills' / SKILL).glob('*')))} real "
+        f"file(s) and no link; skills/{INSIDE}/ is the only copy of the nested folder")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--wheel", required=True, help="the built wheel to prove")
+    args = parser.parse_args()
+
+    repo = Path(__file__).resolve().parents[2]
+    wheel = Path(args.wheel).resolve()
+    if not wheel.is_file():
+        fail(f"no wheel at {wheel}")
+
+    say("== one copy in the repository ==")
+    the_repository_has_one_copy(repo)
+
+    work = Path(tempfile.mkdtemp(prefix="fsmes-assistant-")).resolve()
+    say(f"\n== a clean machine: {work} ==")
+    if repo in work.parents:
+        fail(f"{work} is inside the checkout at {repo}; this proves nothing")
+
+    say("== the person's PC: a fresh venv with the wheel in it ==")
+    theirs = make_venv(work / ".venv-fsmes", wheel=wheel)
+    fsmes = venv_bin(theirs, "fsmes")
+    python = venv_bin(theirs, "python")
+    reported = subprocess.run([str(fsmes), "--version"], check=True, cwd=work,
+                              capture_output=True, **AS_WORDS)
+    say(f"  installed: {reported.stdout.strip()}")
+
+    say("== the network, off, for everything from here on ==")
+    environment = offline(dict(os.environ))
+    prove_the_network_is_off(python, environment)
+
+    say(f"== `fsmes skills list` names {SKILL} ==")
+    listed = run([str(fsmes), "skills", "list"], cwd=work, env=environment)
+    if "inside this installation" not in listed.stdout:
+        fail("`fsmes skills list` did not say the folder came out of the installation; "
+             "it may have found a checkout above the working directory instead")
+    # One folder per indented line; the last indented line is the hint, which
+    # has spaces in it and no skill name does.
+    named = [line.strip() for line in listed.stdout.splitlines()
+             if line.startswith("  ") and " " not in line.strip()]
+    if SKILL not in named:
+        fail(f"`fsmes skills list` did not name {SKILL}. It named: {named}. Check the "
+             f"force-include lines in pyproject.toml.")
+    say(f"  {SKILL} is one of {len(named)} folder(s) listed: {', '.join(named)}")
+
+    say(f"== `fsmes skills unpack {SKILL}` writes the tree, offline ==")
+    run([str(fsmes), "skills", "unpack", SKILL, str(work / "out")],
+        cwd=work, env=environment)
+    folder = work / "out" / SKILL
+    written = sorted(p.relative_to(folder).as_posix()
+                     for p in folder.rglob("*") if p.is_file())
+    say(f"  {len(written)} file(s) written to {folder}")
+
+    missing = [f for f in MUST_CARRY if f not in written]
+    if missing:
+        fail(f"the unpacked folder is missing {', '.join(missing)}. If the pages are "
+             f"there and the nested folder is not, fsmes.skills.INCLUDES did not run; "
+             f"if a page is missing, add its force-include line to pyproject.toml.")
+
+    wanted = what_the_checkout_holds(repo)
+    if wanted != written:
+        fail(f"the unpacked folder is not the checkout's. In skills/ only: "
+             f"{sorted(set(wanted) - set(written)) or 'none'}. Unpacked only: "
+             f"{sorted(set(written) - set(wanted)) or 'none'}.")
+    differ = [f for f in wanted
+              if not filecmp.cmp(repo / "skills" / (f if f.startswith(f"{INSIDE}/")
+                                                    else f"{SKILL}/{f}"),
+                                 folder / f, shallow=False)]
+    if differ:
+        fail(f"{len(differ)} file(s) differ from the checkout: {differ}")
+    say(f"  byte-for-byte the checkout's skills/{SKILL}/ and skills/{INSIDE}/")
+
+    linked = [p.relative_to(folder).as_posix() for p in folder.rglob("*") if p.is_symlink()]
+    if linked:
+        fail(f"the unpacked folder contains symlink(s): {linked}")
+    nested = [f for f in written if f.startswith(f"{INSIDE}/")]
+    say(f"  nothing in it is a symlink; {len(nested)} of {len(written)} file(s) are the "
+        f"nested {INSIDE}/ folder, which is stage 2")
+
+    say(f"\nthe assistant folder came out of the wheel on {sys.platform}, with the "
+        f"network off: {len(written)} file(s), {INSIDE}/ inside it, no second copy in "
+        f"git and no symlink anywhere.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())