Unify LDS shell, core and CLI execution

[abmmhasan]

Scope

Unifies LocalDevStack's execution UX around a new canonical lds shell command while preserving the existing hardened Core/CLI execution substrate and legacy compatibility surfaces.

lds shell

Canonical forms:

• lds shell
• lds shell <target>
• lds shell <target> [--] <command> [args...]
• lds shell <target> --shell <shell-expression>
• lds shell <target> --interactive <command> [args...]

Bare selector

lds shell with no arguments presents a stable numbered catalog grouped as:

• Applications / Domains
• Application Directories
• Services
• Containers
• Utilities

The selector accepts a global number or exact name. Collisions require a qualified selector such as domain:, app:, service:, container:, or utility:tools.

Explicit target resolution

Unqualified targets resolve deterministically:

1. exact discovered domain;
2. reserved tools;
3. exact current-project Compose service;
4. exact Docker container name/ID;
5. exact direct child server-tools:/app/<target>;
6. not found.

There is no fuzzy matching, implicit case conversion, or hostname-shape guessing. Image names are not implicitly instantiated.

Execution behavior

• domains retain application-aware working directories;
• Node domains use /app;
• other domains use resolved docroot, then /app, then /;
• application-directory fallback opens server-tools at /app/<name>;
• normal commands preserve argv exactly;
• --shell is the explicit shell-syntax escape hatch;
• --interactive uses the real-TTY interactive argv helper;
• child exit codes / Ctrl-C style exit 130 propagate unchanged.

Compatibility consolidation

The following surfaces now share the same normalized shell-context execution layer instead of maintaining parallel generic execution orchestration:

• lds shell
• lds core
• lds cli
• lds stack exec / lds exec
• lds tools sh|exec|shell-exec
• lds ui

Legacy contracts remain intentionally narrow where required:

• cli remains service/container-only;
• core keeps its existing domain behavior;
• stack exec remains Compose-service-only;
• tools file remains inspection functionality.

No runtime deprecation warnings are emitted in this release; compatibility is documented instead so existing automation stays quiet.

Hardening retained

• shared lib/container-exec.sh substrate;
• exact argv preservation;
• adaptive stdin/TTY flags;
• real-TTY enforcement for interactive shells/TUIs;
• Bash -> sh fallback;
• current-project scoping;
• Git Bash/MSYS path-conversion protection;
• domain/container ambiguity protection;
• exact qualified-container collision handling;
• stopped/missing/ambiguous error precedence;
• explicit host-side Graphify routing.

Validation

Final head: de5dd8f0ae2185ab3c80c713591ae4fd6c32976b

Final push run #1119: green.
Final pull-request run #1145: green.

Validated:

• ShellCheck/static;
• CLI contract;
• unified shell execution/selector contracts;
• container execution substrate;
• environment/catalog;
• PHP/Node runtime contracts;
• networking;
• wrappers;
• service hardening;
• QoL;
• permissions;
• documentation contract/build;
• Windows bridge;
• Compose;
• Graphify minimum/latest;
• common LLM;
• published image baseline.

The completed shell-unification plan has been retired, and the docs contract again rejects lingering completed planning artifacts under docs/plans.

Branch is synchronized with main (0 commits behind).

No merge performed.

Documentation audit

User-facing documentation was rechecked against the unified shell implementation after the code work:

• README now uses the exact grouped selector terminology and documents utility:tools;
• architecture documents the normalized shell-context execution layer and target precedence;
• quickstart introduces lds shell as a first-check navigation surface;
• domain setup now teaches lds shell instead of lds core / lds cli as the primary workflow;
• operations/support uses lds shell service:<name> for normal command/shell execution;
• database and secrets guides use the canonical service/Tools shell targets;
• CLI reference documents all qualifiers, including utility:tools;
• Local AI docs clarify that logical llm is an operational alias while lds shell service:<name> is intentionally exact;
• embedded plain/Markdown help matches the same qualifier set;
• docs contracts now enforce the canonical examples and prevent the domain guide from drifting back to old primary commands.

Remaining references to core, cli, stack exec, exec, and tools sh are intentional compatibility documentation only.

Documentation build and documentation contract are green on PR run #1145.