Initial commit: Wonderware / System Platform tools and reference
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,154 @@
|
||||
# AGENTS.md
|
||||
|
||||
Guidance for coding agents working in the `graccesscli` folder.
|
||||
|
||||
## Project Snapshot
|
||||
|
||||
This folder contains `graccesscli`, a .NET Framework 4.8 x86 CLI for automating AVEVA/Wonderware System Platform Galaxy configuration through the ArchestrA GRAccess COM/.NET interop library.
|
||||
|
||||
The important platform constraint is that GRAccess is a 32-bit COM stack. Do not try to directly load the native GRAccess DLL from a .NET 10 x64 process. The current CLI stays on `net48`, `x86`, and `[STAThread]` for COM compatibility.
|
||||
|
||||
For the detailed local investigation behind this constraint, read [`GRAccess-DLL-and-DotNet10-Notes.md`](GRAccess-DLL-and-DotNet10-Notes.md). Active mutation-path defect tracking lives in [`requirements-mutation-typelib-fix.md`](requirements-mutation-typelib-fix.md).
|
||||
|
||||
## Key Documentation
|
||||
|
||||
All paths below are relative to this `graccesscli/` folder.
|
||||
|
||||
- [`GRAccess-DLL-and-DotNet10-Notes.md`](GRAccess-DLL-and-DotNet10-Notes.md) - local GRAccess DLL, COM registration, architecture, and .NET 10 compatibility findings.
|
||||
- [`requirements-mutation-typelib-fix.md`](requirements-mutation-typelib-fix.md) - mutation-path COM lifecycle fixes (typelib regression resolved, follow-on defect tracked here).
|
||||
- [`CLAUDE.md`](CLAUDE.md) - existing detailed agent guide for this CLI.
|
||||
- [`graccess_documentation.md`](graccess_documentation.md) - full GRAccess Toolkit API reference.
|
||||
- [`graccess_operations.md`](graccess_operations.md) - GRAccess operations grouped by functional area with page references.
|
||||
- [`docs/usage.md`](docs/usage.md) - CLI commands, options, session mode, and IPC protocol. Update this whenever user-facing commands change.
|
||||
- [`docs/llm-integration.md`](docs/llm-integration.md) - LLM-facing operating contract, safety rules, and recommended CLI improvements for System Platform IDE automation.
|
||||
- [`docs/adding-features.md`](docs/adding-features.md) - checklist for adding commands, dispatcher handlers, capabilities metadata, LLM output, validation, tests, and documentation.
|
||||
- [`docs/zb-galaxy.md`](docs/zb-galaxy.md) - read-only documentation captured from the live `ZB` galaxy with `graccesscli`.
|
||||
- [`docs/zb-testmachine.md`](docs/zb-testmachine.md) - deep read-only documentation of the `ZB` `$TestMachine` template family and instances.
|
||||
- [`docs/template-parsing.md`](docs/template-parsing.md) - read-only workflow for inspecting existing templates such as `TestMachine`.
|
||||
- [`docs/attribute-parsing.md`](docs/attribute-parsing.md) - detailed workflow for parsing all template attributes and setting families.
|
||||
- [`docs/script-parsing.md`](docs/script-parsing.md) - workflow for parsing script libraries and object-level scripts.
|
||||
- [`docs/template-editing.md`](docs/template-editing.md) - end-to-end workflow for safely editing existing templates.
|
||||
- [`docs/template-instance-editing.md`](docs/template-instance-editing.md) - workflow for creating and editing template instances, areas, engine assignments, and I/O settings.
|
||||
- [`docs/attribute-editing.md`](docs/attribute-editing.md) - detailed workflow for editing template attributes, UDAs, extensions, and setting families.
|
||||
- [`docs/script-editing.md`](docs/script-editing.md) - workflow for editing script libraries and script-bearing template content.
|
||||
- [`usage.md`](usage.md) - compatibility copy of the CLI usage documentation; keep it aligned with [`docs/usage.md`](docs/usage.md) if edited.
|
||||
- [`docs/README.md`](docs/README.md) - index for CLI documentation stored under `docs/`.
|
||||
- [`docs/clifx_reference.md`](docs/clifx_reference.md) - local CliFx framework reference.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
graccesscli/
|
||||
ZB.MOM.WW.GRAccess.Cli.slnx
|
||||
lib/ArchestrA.GRAccess.dll
|
||||
src/ZB.MOM.WW.GRAccess.Cli/
|
||||
Program.cs
|
||||
Commands/
|
||||
GRAccess/
|
||||
Infrastructure/
|
||||
Protocol/
|
||||
Session/
|
||||
tests/ZB.MOM.WW.GRAccess.Cli.Tests/
|
||||
```
|
||||
|
||||
## Build And Test
|
||||
|
||||
Run commands from this `graccesscli` folder unless noted otherwise.
|
||||
|
||||
```powershell
|
||||
dotnet build src/ZB.MOM.WW.GRAccess.Cli/ZB.MOM.WW.GRAccess.Cli.csproj -p:Platform=x86
|
||||
dotnet test tests/ZB.MOM.WW.GRAccess.Cli.Tests/ZB.MOM.WW.GRAccess.Cli.Tests.csproj -p:Platform=x86
|
||||
dotnet test tests/ZB.MOM.WW.GRAccess.Cli.Tests --filter "FullyQualifiedName~TestName"
|
||||
```
|
||||
|
||||
Run the CLI:
|
||||
|
||||
```powershell
|
||||
dotnet run --project src/ZB.MOM.WW.GRAccess.Cli/ZB.MOM.WW.GRAccess.Cli.csproj -- <args>
|
||||
```
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
- Keep the CLI and tests targeting `net48` and `x86`.
|
||||
- Keep the entry point `[STAThread]`; GRAccess COM calls must run on an STA thread.
|
||||
- Route long-lived GRAccess work through the session daemon infrastructure when appropriate.
|
||||
- All GRAccess COM access in daemon mode must go through `Session/StaComThread.cs`.
|
||||
- Keep the `GRAccessApp` object alive for the lifetime of any GRAccess objects derived from it.
|
||||
- Check `CommandResult.Successful` after GRAccess calls. Multi-object calls return `CommandResults`.
|
||||
- For object changes, follow `CheckOut()` -> modify -> `Save()` -> `CheckIn(comment)`. Skipping `CheckIn` leaves the object locked in the Galaxy repo.
|
||||
- Treat GRAccess collections as 1-based unless the API docs prove otherwise.
|
||||
- Use `using ArchestrA.GRAccess;` for GRAccess API types.
|
||||
- Use CliFx command patterns already present in the repo: command classes implement `ICommand` and use `[Command]`, `[CommandParameter]`, and `[CommandOption]`.
|
||||
- C# language version is 9.0. `init` is supported through `IsExternalInit.cs`; do not use the `required` keyword.
|
||||
|
||||
## Session Mode
|
||||
|
||||
Session mode keeps a GRAccess connection open in a daemon to avoid expensive reconnects.
|
||||
|
||||
```powershell
|
||||
graccess session start --galaxy MyGalaxy --node MyNode
|
||||
graccess <command> --galaxy MyGalaxy
|
||||
graccess session status --galaxy MyGalaxy
|
||||
graccess session stop --galaxy MyGalaxy
|
||||
```
|
||||
|
||||
The daemon uses:
|
||||
|
||||
- Session file: `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\sessions\{galaxy}.json`
|
||||
- Log file: `%LOCALAPPDATA%\ZB.MOM.WW.GRAccess.Cli\logs\daemon-{galaxy}.log`
|
||||
- Named pipe: `graccess-session-{galaxy}`
|
||||
- Mutex: `Global\graccess-session-{galaxy}`
|
||||
- IPC: newline-delimited JSON
|
||||
|
||||
See [`docs/usage.md`](docs/usage.md) and [`CLAUDE.md`](CLAUDE.md) before changing session behavior.
|
||||
|
||||
## GRAccess References
|
||||
|
||||
The primary API entry point is `GRAccessAppClass`.
|
||||
|
||||
Typical flow:
|
||||
|
||||
```csharp
|
||||
GRAccessApp grAccess = new GRAccessAppClass();
|
||||
IGalaxies galaxies = grAccess.QueryGalaxies(Environment.MachineName);
|
||||
IGalaxy galaxy = galaxies["GalaxyName"];
|
||||
galaxy.Login("", "");
|
||||
// work with galaxy
|
||||
galaxy.Logout();
|
||||
```
|
||||
|
||||
Object model summary:
|
||||
|
||||
```text
|
||||
GRAccessApp
|
||||
IGalaxies -> IGalaxy
|
||||
IGalaxySecurity / roles / users
|
||||
IgObjects -> ITemplate / IInstance
|
||||
IAttributes -> IAttribute
|
||||
IToolsets
|
||||
IScriptLibraries
|
||||
ICommandResults
|
||||
```
|
||||
|
||||
For exact method signatures, enum names, and page references, use [`graccess_documentation.md`](graccess_documentation.md) and [`graccess_operations.md`](graccess_operations.md).
|
||||
|
||||
## Current CLI Query Surface
|
||||
|
||||
Galaxy-bound commands route through an active session when one exists, and otherwise fall back to one-shot mode:
|
||||
|
||||
```powershell
|
||||
graccess object list --galaxy ZB --node . --type instance --pattern '%'
|
||||
graccess template list --galaxy ZB --node . --pattern '%'
|
||||
graccess instance list --galaxy ZB --node . --pattern '%'
|
||||
graccess object attributes --galaxy ZB --node . --name DEV --type instance --configurable
|
||||
```
|
||||
|
||||
When a session is active, routed commands can omit `--node` and are dispatched by `SessionDaemon.ExecuteCommandAsync` through `GRAccessCommandDispatcher` on the daemon STA thread. GRAccess `namedLike` patterns use `%` as the wildcard. Attribute metadata should be read defensively because some COM-backed properties can throw when storage is unavailable; unavailable JSON fields are represented as `null`.
|
||||
|
||||
The expanded CLI surface is concentrated in `Commands/GRAccessSurfaceCommands.cs` and routes through `GRAccess/GRAccessCommandDispatcher.cs`. Mutating commands must pass `--confirm` and matching `--confirm-target`; keep that guard in place for delete, deploy, restore, migrate, import, GRLoad, and object configuration changes.
|
||||
|
||||
LLM-facing automation is documented in [`docs/llm-integration.md`](docs/llm-integration.md). Preserve legacy `--json` shapes; use `--llm-json` for stable envelopes. Keep `capabilities`, `validate`, `batch`, `object snapshot`, attribute value commands, object script commands, and area/engine/I/O wrappers aligned with `CommandCapabilityRegistry`.
|
||||
|
||||
For deep read-only parsing, prefer `object snapshot`, `object lineage`, and `object children` with `--llm-json`. These commands should use direct GRAccess typed reads first and may use temporary GRAccess-exported package parsing for lineage, contained objects, attribute values, and script bodies when direct COM properties are unavailable. Normal CLI behavior must not query the Galaxy Repository SQL database; SQL access is development verification/debugging only.
|
||||
|
||||
When adding new CLI features, follow [`docs/adding-features.md`](docs/adding-features.md) and update user-facing docs in the same change.
|
||||
Reference in New Issue
Block a user