# 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.