en-US/Gerber-Help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh"> <command:command> <command:details> <command:name>Invoke-Gerber</command:name> <maml:description> <maml:para>Starts the interactive Gerber DevOps multitool.</maml:para> </maml:description> <command:verb>Invoke</command:verb> <command:noun>Gerber</command:noun> </command:details> <maml:description> <maml:para>`Invoke-Gerber` starts Gerber Core's interactive command palette in the current working directory. Core provides `/exit`, `/help`, `/plugins`, `/update`, `/secrets` and `/tools`. Plugins are separate modules, not Core dependencies. Plugin-contributed commands appear only while active plugins contribute them. Menus, completion, help and direct lookup share the active registry. Type `/` to browse or plain text such as `uuid` to search executable leaf actions. Use Up/Down to select, Tab to complete and Enter to accept the highlighted suggestion and execute a complete command. Roots prioritize `/exit`, `/help`, `/plugins`, `/update`; remaining roots are alphabetical. Bare submenu commands open inline choosers. Esc returns one level; double Esc within 200 ms returns to the root prompt without exiting. Startup attempts a bounded, noninteractive Core-only update check through PSModuleUpdate. An available-version notification refers to `/update list`. Startup never installs, asks for installation consent, requests credentials or checks plugins. Failed checks leave the session usable without claiming currency. Importing the module alone performs no update check or Nova lifecycle operation. `/update list` checks Core and eligible installed plugins afresh. Core is bound to official PSGallery and CurrentUser scope, without override, automatic repository registration or alternate-feed fallback. Plugin repositories come from the installed manifest's `PrivateData.Gerber.Repository` object: `Name` is displayed; `Uri` is passed to PMU. Absent metadata defaults to PSGallery; invalid explicit metadata never falls back. Legacy `RepositoryUri` is supported; canonical metadata wins. With plugin rows present, Up/Down and Space select available updates, then Enter reviews them. Selected packages are temporarily downloaded for manifest inspection without a separate inspection prompt. A required permitted Core update is visibly added; unsatisfied requirements block the dependent plugin. Installation confirmation defaults to Cancel. With nothing available, continue returns without a selection or installation prompt. Updates run sequentially through PMU, Core first when required. Dependent plugins are blocked on Core failure; independent selections can continue. Cancellation stops later attempts. Results distinguish installation, verification, recovery and fresh-process activation. Activation failure does not erase successful installation. There is no first installation, hot reload or batch rollback. Repository credentials are operation-local, not saved in metadata or fetched from native storage. `/update policy` saves Stable only (default) or Include prereleases for Core startup and manual Core/plugin discovery. Select Include prereleases to receive preview updates. Enter saves the current selection; Esc leaves it unchanged. Policy selection performs no discovery or installation; a change clears the old startup notification and requires a fresh `/update list` plan. After an update requiring restart, Continue with current version is the default; Esc also continues with a retained reminder. Exit Gerber returns to PowerShell without unloading modules. Console hosts also offer Exit Gerber and PowerShell; other hosts require restarting the session from the host. Restart PowerShell, then run `gerber` to activate installed updates. `/plugins list` and `info` are read-only and do not import unknown, declined or disabled plugins for inspection. Unknown plugins require GUID approval before import, with decline as the default. Decisions persist across sessions. Approval survives routine version updates but does not authenticate a publisher. `/plugins enable` explicitly approves and activates a selected installed inactive plugin without another approval prompt. `/plugins disable` removes its commands immediately while preserving approval and installation. There are no remove or revoke commands; uninstall the PowerShell module outside Gerber to remove or revoke it. `/plugins create` asks for a suffix behind the fixed `Gerber.` prefix, description, unused namespace, repository and destination parent (cwd by default). PSGallery is preselected and writes an explicit Repository object. A custom source takes a name and safe absolute URI; unknown URIs become `REPLACE_WITH_REPOSITORY_URI`, which must be replaced and rebuilt before remote publishing or updates. Creation validates a staged Plugin API v1 Nova project without overwriting existing files, then approves, associates and enables the GUID. It does not install or load the plugin. Generated name/version are available to read-only inventory before installation. NovaModuleTools and PSModuleUpdate are required runtime modules; Nova lifecycle operations run on demand. `/tools create-uuid` displays a hyphenated UUID and copies it when possible; Enter repeats and Esc returns to tools. `/tools base-64 encode` and `decode` convert UTF-8 text, optionally copy results and reopen after continue. Invalid input produces a recoverable error. `/secrets` offers list, get, test, set and remove backed by native credential storage. Listing and testing do not retrieve values. Get copies when possible before asking to reveal the value. Set uses non-echoing input and confirms overwrite; remove confirms deletion. No plaintext fallback is used.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Gerber</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>Gerber renders terminal-oriented status and help rather than returning pipeline objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Requires PowerShell 7.4 or later, NovaModuleTools and PSModuleUpdate. Plugin updates additionally require a PMU release exporting `Get-PSModuleUpdateTargetManifest`; the numeric minimum alone does not guarantee it. Live update has been verified on macOS only. The startup child-process wait budget is 2,000 ms, without a persistent cache. Noninteractive update views do not prompt or install. Failed discovery remains Unavailable; NoMatchingPackage requires PMU's structured PackageNotFound identifier. Neither result proves Core is current or offers installation. Core configuration uses `GerberCore.json` in the platform-resolved user directory. `GERBER_CONFIG_PATH` overrides the absolute Core file; a legacy `config.json` filename selects sibling `GerberCore.json`. Plugin JSON files follow the Core file's directory, using each module name. Plugin Configuration.Read/Save is identity-bound, with missing-file null results, strict JSON errors and atomic writes. The optional `coreUpdates.channel` is Stable or IncludePrerelease. Missing values default without creating configuration; explicit invalid values are errors. Obsolete `updates.modules.Gerber` settings cannot override PSGallery. Credential identifiers are case-insensitive `gerber:<scope>:<name>` values; plugin credentials use the manifest GUID's namespace. Secrets belong in native storage, not JSON or traces. Linux storage needs a desktop Secret Service session, D-Bus and libsecret. Unavailable storage fails with guidance, not plaintext fallback. Set `GERBER_PROMPT_TRACE=1` before launch to write JSON lines under `.gerber/prompt-debug.log` in cwd. Ordinary prompt input can appear in traces; review and redact before sharing.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1 ---------</maml:title> <maml:introduction> <maml:para>Start Gerber from PowerShell.</maml:para> <maml:para>€</maml:para> <maml:para>```powershell Invoke-Gerber ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 2 ---------</maml:title> <maml:introduction> <maml:para>Start the same session through its alias.</maml:para> <maml:para>€</maml:para> <maml:para>```powershell gerber ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 3 ---------</maml:title> <maml:introduction> <maml:para>After starting Gerber, use built-in help and Core tools.</maml:para> <maml:para>€</maml:para> <maml:para>```text /help /tools create-uuid /tools base-64 encode /tools base-64 decode ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 4 ---------</maml:title> <maml:introduction> <maml:para>Inside Gerber, inspect plugins and choose the preview update channel before checking available updates. Review the confirmation; Cancel is the default.</maml:para> <maml:para>€</maml:para> <maml:para>```text /plugins list /update policy /update list ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 5 ---------</maml:title> <maml:introduction> <maml:para>Inside Gerber, list stored identifiers or check one without retrieving its value.</maml:para> <maml:para>€</maml:para> <maml:para>```text /secrets list /secrets test ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Test-GerberPluginBoundary</maml:linkText> <maml:uri>./Test-GerberPluginBoundary.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Gerber project</maml:linkText> <maml:uri>https://github.com/stiwicourage/GerberCore</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command> <command:details> <command:name>Test-GerberPluginBoundary</command:name> <maml:description> <maml:para>Checks authored plugin source for identifiable private Gerber Core dependencies.</maml:para> </maml:description> <command:verb>Test</command:verb> <command:noun>GerberPluginBoundary</command:noun> </command:details> <maml:description> <maml:para>Parses source without executing it. Returns IsValid, FileCount, PublicApi and deterministic Diagnostics. This development check is not a PowerShell sandbox. It does not start Gerber or invoke Nova lifecycle operations. Importing Gerber still requires the declared NovaModuleTools and PSModuleUpdate runtime modules.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-GerberPluginBoundary</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>Path</maml:name> <maml:description /> <command:parameterValue required="true" variableLength="false">string</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Plugin project directory containing a src directory. Authored PowerShell under src, scripts and root entrypoints is inspected.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para>One result with IsValid, FileCount, PublicApi and Diagnostics. Each diagnostic contains project-relative File, one-based Line and Column, Dependency, Reason and actionable Resolution. Diagnostics are sorted deterministically.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>PowerShell 7.4 or later. Authored .ps1, .psm1 and .psd1 files beneath src and scripts are parsed recursively, along with root PowerShell files. Generated dist/artifacts and tests outside those authored roots are not scanned. Parse failures are diagnostics; missing paths or src directories are terminating errors. This is a development-time architecture check, not runtime isolation, permissions or a PowerShell sandbox. It recognizes static commands and literal imports, simple literal concatenation and unambiguous prior literal variable assignments. It does not prove arbitrary dynamic targets safe, follow aliases or perform interprocedural dataflow. Local/plugin-owned function declarations are respected. Review computed dependencies manually and request missing public capabilities.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- EXAMPLE 1 ---------</maml:title> <maml:introduction> <maml:para>```powershell $result = Test-GerberPluginBoundary -Path ./Gerber.Example $result.Diagnostics | Format-Table File, Line, Dependency, Reason, Resolution -Wrap if (-not $result.IsValid) { throw 'Fix plugin boundary diagnostics before building.' } ```</maml:para> <maml:para>€</maml:para> <maml:para>Checks an uninstalled plugin without executing its source. Invalid source produces structured diagnostics; callers decide whether to fail their build.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- EXAMPLE 2 ---------</maml:title> <maml:introduction> <maml:para>```powershell (Test-GerberPluginBoundary -Path .).PublicApi ```</maml:para> <maml:para>€</maml:para> <maml:para>Inspects operations derived from the installed Core's actual API v1 declarations. This does not start Gerber, load plugins or read user configuration.</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-Gerber</maml:linkText> <maml:uri>./Invoke-Gerber.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |