chore(ansible): cluster-wide Tailscale-first SSH + Claude Code permission sync

.serena/project.yml

@@ -2,18 +2,49 @@
 project_name: "factorylm"
 
 
-# list of languages for which language servers are started
+# list of languages for which language servers are started; choose from:
+#   al                  angular             ansible             bash                clojure
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
+#   dart                elixir              elm                 erlang              fortran
+#   fsharp              go                  groovy              haskell             haxe
+#   hlsl                html                java                json                julia
+#   kotlin              lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        powershell          python
+#   python_jedi         python_ty           r                   rego                ruby
+#   ruby_solargraph     rust                scala               scss                solidity
+#   svelte              swift               systemverilog       terraform           toml
+#   typescript          typescript_vts      vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
 languages:
 - python
 - typescript
 
 # the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
 encoding: utf-8
 
 # whether to use project's .gitignore files to ignore files
 ignore_all_files_in_gitignore: true
 
 # list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
 ignored_paths:
 - "node_modules/**"
 - "_BUILDS/**"
@@ -28,34 +59,95 @@ ignored_paths:
 - "docs/archive/**"
 
 # whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
 read_only: false
 
 # list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 excluded_tools: []
 
-# list of tools to include that would otherwise be disabled
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 included_optional_tools: []
 
-# fixed set of tools to use as the base tool set
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 fixed_tools: []
 
-# initial prompt for the project.
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
 initial_prompt: >
   FactoryLM monorepo — industrial AI platform diagnosing factory faults
   using NVIDIA Cosmos Reason 2. Key dirs: cosmos/ (client, watcher, agent),
   services/matrix/ (FastAPI + SQLite), diagnosis/ (conveyor fault rules),
   sim/ (PLC simulator + Factory I/O bridge), core/ (shared Python library).
   Pipeline: Factory I/O -> Modbus TCP -> Matrix API -> Cosmos -> Diagnosis.
   SAFETY: NEVER modify code tagged # SAFETY, # PLC, or # CRITICAL.
-
 # list of mode names to that are always to be included in the set of active modes
 base_modes:
 
-# list of mode names that are to be activated by default.
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 default_modes:
 
 # time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
 symbol_info_budget:
 
 # The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
 language_backend:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []

PLAN.md

@@ -1,86 +1,92 @@
-# PLAN: MES Core — Week 2 (Modbus Machine State Reader)
+# PLAN: MES Core — Week 6 (Atlas CMMS Bidirectional Sync)
 
-**Branch:** `feat/mes-week2-state-reader`
-**Issue:** Mikecranesync/MIRA#320
-**PRD:** `docs/PRD-MES-CORE.md`
-**Date:** 2026-04-15
-**Depends on:** Week 1 (feat/mes-week1-db-schema) merged
+**Branch:** `feat/mes-week6-cmms-sync`
+**Issue:** Mikecranesync/MIRA#324
+**PRD:** `docs/PRD-MES-CORE.md §3 (ERP/CMMS Integration)`
+**Date:** 2026-04-16
+**Depends on:** Weeks 1–5 merged
 
 ---
 
 ## Objective
 
-Build the machine state reader: a background poller that reads the plc-modbus HTTP API every 5 seconds per configured line, detects state transitions (RUNNING/DOWN/IDLE/OFFLINE), writes them to `machine_states`, and exposes `GET /api/mes/lines` and `GET /api/mes/lines/{id}/state` REST endpoints.
+Bidirectional sync between the MES work order system and Atlas CMMS
+(implemented as a GitHub Gist-based portable work order format — see
+`cmms/gist_work_order.py` for the existing pattern).
+
+- **MES → CMMS (outbound)**: POST /api/mes/cmms/sync/{id} pushes a WO as a
+  Gist document (Markdown + CSV) readable by any CMMS.
+- **CMMS → MES (inbound)**: POST /api/mes/cmms/ingest accepts a CMMS work order
+  payload and creates/updates a WO in the MES database.
+- `cmms_enabled` config gate: sync is opt-in; tests run with it disabled.
 
 ## Affected Files
 
 **New:**
-- `services/mes/backend/services/__init__.py`
-- `services/mes/backend/services/plc_client.py`    — async HTTP client wrapping plc-modbus
-- `services/mes/backend/services/state_machine.py` — pure state detection from IO snapshot
-- `services/mes/backend/services/state_poller.py`  — asyncio background poll loop
-- `services/mes/backend/routes/lines.py`           — GET /api/mes/lines, GET /lines/{id}/state
-- `services/mes/tests/test_machine_states.py`      — 10 unit tests, all mocked
+- `services/mes/alembic/versions/0002_add_cmms_ref.py`  — adds cmms_ref + cmms_synced_at to work_orders
+- `services/mes/backend/services/cmms_client.py`         — CMMS Gist HTTP adapter
+- `services/mes/backend/routes/cmms.py`                  — sync endpoints
+- `services/mes/tests/test_cmms.py`                      — unit tests
 
 **Modified:**
-- `services/mes/requirements.txt`  — add httpx
-- `services/mes/backend/config.py` — add plc_modbus_url setting
-- `services/mes/backend/main.py`   — wire poller into lifespan, add lines router
-- `docker-compose.yml`             — add PLC_MODBUS_URL env to mes container
+- `services/mes/backend/models/db_models.py`             — WorkOrder gets cmms_ref, cmms_synced_at
+- `services/mes/backend/config.py`                       — cmms_enabled, cmms_github_token
+- `services/mes/backend/main.py`                         — include cmms router
+- `PLAN.md`
+
+---
 
 ## Approach
 
-1. `plc_client.py` — thin async wrapper around `GET /api/plc/io` (httpx). Raises `PLCOfflineError` on timeout/connection failure so caller can set OFFLINE state.
-2. `state_machine.py` — pure function `detect_state(io_data)` → `(MachineStateEnum, reason_code | None)`. Derived from `VFDStatus` and `ErrorCode` registers. No DB or network calls — fully testable without mocks.
-3. `state_poller.py` — asyncio task, one iteration per line every 5s. Maintains in-memory cache to avoid DB reads on every tick. Writes to `machine_states` only on transition.
-4. `lines.py` routes — two endpoints: list all lines (from DB), get current state (from in-memory cache + last DB row).
-5. `main.py` lifespan — start poller task on startup, cancel on shutdown.
+### 1. DB migration 0002
 
-State transition write: close open row (`ended_at = NOW()`), insert new row.
+Adds to work_orders:
+  - `cmms_ref TEXT` — GitHub Gist ID once synced (NULL = not yet pushed)
+  - `cmms_synced_at TIMESTAMPTZ` — timestamp of last successful push
 
-## State Machine
+### 2. CMMS Client (`cmms_client.py`)
 
-```
-IO: VFDStatus=1, ErrorCode=0  → RUNNING
-IO: VFDStatus=2 OR ErrorCode>0 → DOWN  (reason_code from ErrorCode map)
-IO: VFDStatus=0, ErrorCode=0  → IDLE
-HTTP failure / timeout         → OFFLINE
-```
+Sync HTTP adapter using `httpx.Client`. Controlled by `settings.cmms_enabled`.
+When disabled, `push_work_order()` returns a mock response — no real API calls.
 
-## ErrorCode → reason_code map
+Functions:
+- `format_work_order(wo, line_name, product_sku, product_name) -> dict`
+  Maps MES WO fields to the CMMS Gist metadata schema.
+- `push_work_order(metadata, gist_id=None) -> dict`
+  Creates Gist if gist_id is None, updates if provided.
+  Returns `{gist_id, gist_url}`.
 
-```python
-{1: "OVERLOAD", 2: "OVERHEAT", 3: "SENSOR_FAIL", 4: "JAM", 7: "E_STOP"}
-```
+GitHub Gist API:
+  POST  https://api.github.com/gists                 — create
+  PATCH https://api.github.com/gists/{gist_id}       — update
 
-## Risks
+### 3. CMMS Routes (`cmms.py`)
 
-- plc-modbus in mock mode returns VFDStatus=0 at rest — poller sees IDLE immediately (expected)
-- Multiple lines share one plc-modbus service currently — same io_data, different `line_id` rows
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/mes/cmms/sync/{work_order_id}` | Push WO to CMMS Gist; saves cmms_ref back to DB |
+| GET  | `/api/mes/cmms/sync/{work_order_id}` | Return sync status (cmms_ref, cmms_synced_at) |
+| POST | `/api/mes/cmms/ingest`              | Import CMMS work order → create/update in MES |
 
-## Rollback
+Ingest body resolves product by SKU, line by name. Creates WO as PENDING
+with `cmms_ref` already populated (marks it as CMMS-originated).
 
-```bash
-git checkout feat/mes-week1-db-schema
-```
+---
 
-## Verification Steps
+## Risks
 
-```bash
-# Unit tests (no docker needed)
-cd services/mes && pytest tests/test_machine_states.py -v
+- `cmms_enabled=False` must short-circuit cleanly in both sync and ingest paths.
+- GitHub token is a secret — never logged or returned in API responses.
+- `cmms_ref` uniqueness: if the same WO is synced twice, update the Gist, don't create a second.
 
-# Integration: start stack, check state endpoint
-docker compose up mes-db mes plc-modbus -d
-curl localhost:8300/api/mes/lines
-curl localhost:8300/api/mes/lines/<id>/state
+## Rollback
 
-# Inject a fault and verify DB transition
-curl -X POST localhost:8001/api/plc/mock/fault -H "Content-Type: application/json" -d '{"fault_type":"jam"}'
-sleep 8
-curl localhost:8300/api/mes/lines/<id>/state  # should show DOWN / JAM
-```
+Delete new files, remove import from main.py.
+Run migration downgrade: `ALTER TABLE work_orders DROP COLUMN cmms_ref; DROP COLUMN cmms_synced_at;`
 
-## Note on Active Focus Window
+## Verification
 
-Explicitly authorized by Mike (2026-04-15 session).
+1. `pytest tests/test_cmms.py -v` — all new tests pass
+2. `pytest tests/ -v` — full suite (95 + new) passes, zero regressions
+3. With cmms_enabled=False: sync endpoint returns 200 with mock gist_id
+4. Ingest: POST with valid line/product → WO appears in GET /api/mes/work-orders

infra/ansible/README.md

@@ -44,6 +44,39 @@ ansible-playbook -i inventory.ini playbook.yml --check
 | Shell config | Universal env vars + aliases in `.zshrc` (preserves existing content) |
 | tmux | Deploys shared `~/.tmux.conf`, auto-attaches on SSH login |
 | Remote Login | Enables macOS SSH access |
+| **SSH config (Tailscale-first)** | Deploys canonical `~/.ssh/config` pointing every alias (alpha/bravo/charlie/plc/travel/prod/pi) at Tailscale IPs. Source: `templates/ssh_config.j2` |
+| **Claude Code permissions** | Merges canonical allow-list (ssh/scp/rsync/tailscale/nc/ping/dig/host) into every node's `~/.claude/settings.json` so agents never prompt for cluster-internal commands. Source: `files/merge_claude_permissions.py` |
+
+### Canonical SSH Aliases (after sync)
+
+```bash
+ssh alpha       # 100.107.140.12  (factorylm@)
+ssh bravo       # 100.86.236.11   (bravonode@)   # Tailscale default
+ssh bravo-lan   # 192.168.1.11                    # same-subnet fallback
+ssh charlie     # 100.70.49.126   (charlienode@)
+ssh plc         # 100.72.2.99     (hharp@)
+ssh travel      # 100.83.251.23   (hharp@)
+ssh prod        # 100.68.120.99   (root@)        # VPS via Tailscale
+ssh prod-public # 165.245.138.91                  # DigitalOcean fallback
+ssh pi          # 100.66.216.6    (pi@)
+```
+
+The first time each node receives the template, Ansible writes a timestamped backup alongside (e.g. `~/.ssh/config.3854.2026-04-24@…~`) so a pre-existing hand-edit is never lost.
+
+### Canonical Claude Code Permissions
+
+Appended to every node's `~/.claude/settings.json` → `permissions.allow`:
+
+```
+Bash(ssh *)     Bash(scp *)     Bash(rsync *)
+Bash(tailscale *)  Bash(/opt/homebrew/bin/tailscale *)
+Bash(nc -z *)   Bash(ping -c* *)
+Bash(dig *)     Bash(host *)
+```
+
+The merge is additive: only adds missing entries, preserves existing hooks / statusLine / model settings. A version marker at `~/.claude/.permissions-merged-v<N>` short-circuits re-runs at the same version.
+
+To roll out a new canonical entry: edit `files/merge_claude_permissions.py`, raise `CANONICAL_VERSION`, commit, re-run the playbook.
 
 ## Adding New Packages