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>Gerber.AzureDevOps 0.1.0 is a declared RequiredModules dependency. Import alone does not approve, activate or register its commands. Normal discovery and saved approval/enable/disable rules remain authoritative. `Invoke-Gerber` opens the interactive Gerber terminal workflow for the current working directory. Startup attempts a bounded Gerber Core update check through PSModuleUpdate using the fixed official PSGallery repository. An eligible available-version notification refers to `/update list`; startup never installs, asks to install or requests credentials. Offline, timed-out or no-matching-package checks leave the session usable without claiming it is up to date. A read-only public PMU check on 2026-10-25 returned installed/target 0.1.0 and UpToDate from PSGallery; no installation was attempted. The session starts with a minimal prompt-first home screen and reveals matching root commands as you type `/`, or matching executable leaf action commands as you type plain text such as `uuid`, `base`, `ado`, or `help`. The root prompt supports interactive autocomplete with `Tab`, `Up`, and `Down`, including help previews for matching commands. Root browsing and completion show `/exit`, `/help`, `/plugins`, and `/update` first, in that order, followed by all remaining Core and active plugin root commands alphabetically. Submenu ordering is unchanged. Pressing `Enter` accepts the highlighted suggestion and executes it once the selected command is complete, whether you started from slash input or plain root action-search text. The currently selected suggestion is visually highlighted to stay readable across terminal themes while you navigate with arrow keys. Bare submenu commands such as `/tools`, `/list`, `/pipelines`, `/branch`, `/repository`, `/plugins`, and `/secrets` open an inline submenu prompt that shows the available subcommands directly on the command line. Nested submenu flows such as installed plugin tools and `/tools base-64` keep the same arrow-key suggestion behavior while narrowing the prompt to that tool's actions. After `/tools base-64 encode` or `decode`, continue reopens the same action. Azure DevOps commands are supplied by the approved, enabled Gerber.AzureDevOps plugin, not built into Core. Their existing paths remain `/list ado-agents`, `/list ado-team-members`, `/repository create`, `/branch find`, `/branch set-searchable`, `/branch set-default`, `/pipelines tags delete` and `/pipelines tags update`. The plugin owns profile selection, lazy setup, reports/export, REST, retry and pagination, repositories, branches and pipelines. Shared Enter, Escape and continue routing remain unchanged. Inactive plugins contribute no commands; unrelated Core tools and secret management remain usable. Press `Esc` from an interactive prompt or continue screen to return to the main Gerber menu. Shared `/branch`, `/list`, `/pipelines` and `/repository` roots appear only while active plugins contribute available actions. Empty intermediate submenus disappear too. Several plugins may share a root; disabling one preserves the others, while disabling the last hides the empty menu. Menus, completion, help and direct command lookup use the same active command tree. Standalone Core tools, `/plugins`, `/update` and `/secrets` remain available without product plugins. `/plugins enable` lists installed inactive plugins, including previously declined or approved-but-disabled plugins. Selecting a plugin counts as explicit approval without an additional approval prompt. `/plugins disable` removes an active plugin's commands while preserving its approval and leaving its PowerShell module installed. Both actions update menus, completion, and dispatch immediately without restarting Gerber. `/update` opens the shared list/policy submenu, consistent with other slash menus. `/update list` performs fresh Core and eligible installed-plugin discovery and shows installed/available versions, repository and status. Core always uses the official PSGallery endpoint. Only discovered, associated, approved, enabled plugins participate, using `PrivateData.Gerber.Repository` from the current installed manifest: `Name` is displayed and canonical `Uri` is sent to PMU. The name remains visible on unavailable/no-matching-package lookup results. Absent metadata defaults to PSGallery and its official endpoint; invalid explicit metadata never falls back. Legacy `RepositoryUri` is supported, mapping the official Gallery URL to PSGallery and retaining custom raw URL display until a name is added. Canonical metadata takes precedence when both keys exist. Trust confirmations retain the actual URL. Startup remains Core-only. When plugin rows exist, use Up/Down and Space in the shared checkbox to select available updates, then Enter to review. Exact selected-package inspection checks GUID, Plugin API v1 and required Core version. Trust/license-gated inspection requires separate default-Cancel consent for temporary download without installation. A required Core candidate is visibly added to the combined default-Cancel installation preview, with full versions, source, scope and operation-local trust/license choices. Unavailable Core requirements block the dependent plugin. Empty selection cancels; Esc follows shared back navigation. Noninteractive views render all status rows without prompting or installing. After acceptance, PMU installs the original plans sequentially, Core first when needed. Core failure blocks dependent plugins while independent updates continue; individual plugin failures do not stop independent later attempts, but user cancellation does. Results separate installation, verification, recovery and fresh-process activation. An installed package remains Installed even when activation fails. There is no first installation, hot reload or batch rollback. Repository credentials are requested through per-operation secure input, never saved in metadata or fetched from native storage. Restart PowerShell, then run `gerber` before using installed components. Failed discovery is not "up to date". `/update policy` selects Stable only (default) or Include prereleases for Core startup and Core/plugin manual discovery. The current choice is preselected; Enter saves, Esc cancels, and continue returns to the chooser. Selection performs no discovery or installation and clears an old startup notification only after a channel change. Esc returns to the update submenu; continuing after list results returns there too. Gerber requires numeric PSModuleUpdate 0.2.0 or later, currently available from PSGallery. The local plugin-update implementation additionally uses a new PMU target-manifest inspection API that is not published in 0.2.0. The declared minimum is unchanged; source builds and disposable tests do not deploy those APIs or qualify hosted/live plugin updates. Dependency installation remains a separate, explicitly approved action. Gerber does not automatically migrate or clean up local Gerber copies. When PMU reports installed and available 0.1.0 with disposition UpToDate, the Available column shows 0.1.0 and no installation is offered. PMU remains the sole discovery and version-selection authority, using the fixed official PSGallery endpoint, selected channel and CurrentUser scope. The separate upstream PackageNotFound classification correction is locally implemented but unpublished; Gerber uses NoMatchingPackage only for explicit PMU.PackageNotFound. Published 0.2.0 can still report a generic discovery failure. Neither outcome proves Core is current or establishes complete live-install qualification. Building this checkout does not replace installed or loaded PMU for an existing `gerber` launcher. A failed check remains Available `-` / Unavailable. PMU does not select or migrate flat-only Gerber copies as versioned installations; an unsupported layout is not a PSGallery failure. Structured PMU.UnsupportedInstallation errors now receive generic supported numeric-version module directory guidance: restart PowerShell after arranging a supported installation, then retry `/update list`. Gerber does not parse provider text, assume every such error is flat-only, or claim installation/rollback success. An existing installed Gerber copy needs a separate update to receive this source diagnostic; no automatic installation migration is performed. `/plugins create` asks for a module suffix behind a fixed `Gerber.` prefix, description, unused command namespace, repository choice, and existing destination parent (current directory by default). The shared repository chooser appears after the namespace and defaults to PSGallery, which writes an explicit `Manifest.PrivateData.Gerber.Repository` object with its `Name` and official `Uri` without further repository questions. Another repository asks for its name, then a known absolute URI without credentials, query or fragment, or Enter if unknown. Blank names are corrected locally. Known URIs are stored in `Repository.Uri`, without an Update intermediary; Enter writes `REPLACE_WITH_REPOSITORY_URI`. Invalid URI input stays at the prompt with correction guidance, and shared Esc cancels from the chooser, name or URI input without creation or approval. It generates and validates a working Plugin API v1 Nova project in a new child directory without overwriting existing files. Successful creation approves, associates and enables the generated manifest GUID, but does not install or load the plugin. Run `Publish-NovaModule -Local` from that project, restart Gerber and try its namespaced `hello` command. NovaModuleTools and PSModuleUpdate are mandatory runtime dependencies. Nova lifecycle operations run on demand; the creation handler's missing-tool fallback requires consent. Shared `Esc` navigation cancels, and invalid input can be corrected without approval. Creation fields have separated headings, descriptions, examples and visible current-directory/project-child defaults. The completion summary shows actual name, version, namespace, location, repository name and URI, and lifecycle state, explicitly Installed: No. A placeholder summary requires replacing `Manifest.PrivateData.Gerber.Repository.Uri` before remote publishing or updates. Build, tests and isolated local publish still work; update consumption rejects the explicit placeholder without package lookup or Gallery fallback. Read-only list/info show the generated name and initial version before installation using GUID-keyed association display metadata; discovered manifest metadata wins. Generated projects use only the canonical manifest GUID and include a complete Unreleased changelog plus AGENTS.md, thin Claude/Copilot bridges, scoped instructions, a plugin development agent and actionable command/API/Nova skills.</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>System.String</maml:name> </dev:type> <maml:description> <maml:para>Gerber writes terminal-oriented status and help text while the interactive session is running.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Core updates always explicitly use PSGallery and its official endpoint. This application-owned repository cannot be overridden by user settings, environment variables or plugin configuration and has no fallback or chooser. Obsolete `updates.modules.Gerber` settings are ignored without rewriting unrelated configuration. Core never reports Unconfigured or retrieves credentials. The channel is saved as optional `coreUpdates.channel` in existing user configuration: Stable by default, or IncludePrerelease for stable releases and previews. Plugins share this channel for manual checks only. Startup's Core-only child process uses the same file, including GERBER_CONFIG_PATH. Missing values do not create configuration; explicit invalid values are errors. Save failures and noninteractive policy dispatch do not change the channel. Changed-policy installation plans require a new `/update list` check. PMU handles installed prerelease metadata: stable `0.1.0` can supersede `0.1.0-preview`; Stable excludes newer prereleases. No matching package is not a configuration error, a currency claim or permission to install. Disposable fixture checks do not qualify live installation. Startup retains a 2,000 ms child-process budget with no persistent cache. Noninteractive update views do not prompt or install. Module import alone performs no update check or Nova lifecycle operation. Plugin enable and disable decisions are saved in the existing Gerber user configuration and survive restarts. Disabled plugins cannot execute commands through Gerber until enabled again. Plugin inventory and details remain read-only. The `/tools base-64` utility is text-focused in v1, shows results in the terminal, and copies them to the clipboard when Gerber finds a supported clipboard command. Gerber resolves Azure DevOps connections lazily: startup, `/help`, `/secrets`, plugin discovery, and unrelated commands do not prompt for Azure DevOps configuration, while authenticated ADO commands can configure a missing profile or missing PAT inline and then continue the same command. When no Azure DevOps default profile is configured, Gerber uses the configured default when present, offers to use the single existing profile when exactly one profile exists, lets the user choose when multiple profiles exist, and offers to configure the explicitly requested profile instead of silently switching to a different one. Core lifecycle/platform settings use GerberCore.json; Azure DevOps profiles use Gerber.AzureDevOps.json in the same platform-resolved directory. Plugin API v1 provides identity-bound Configuration.Read and Configuration.Save without paths or Core access. Missing files return null; invalid JSON is reported, not replaced; writes are atomic. The repeatable legacy config.json transition preserves unknown and destination settings, retains originals on conflict/failure, and deletes the old file only after verified transfer. It never changes approval or credentials. The AzureDevOps plugin uses Secrets under GUID a468dee5-c7a0-43e4-ae88-bb19158fe679 and logical path ado/<profile>/pat. Missing PATs are entered again during interactive authenticated use; legacy Core credentials are never automatically reused, migrated or deleted. Noninteractive missing credentials do not open prompts. PATs are not stored in JSON or diagnostics. The `/list ado-agents` report reads Azure DevOps connection settings from `Properties.json`, queries automation and deployment task pools, keeps empty sections and empty pools explicit, color-codes version lines consistently per run, shows a version legend, and retrieves the active profile PAT from secure credential storage only when authentication is required. The `/pipelines tags delete` workflow asks for the current tag, lists every Azure DevOps build/run that still carries that tag, groups the checkbox selection screen by pipeline name, removes the tag on each selected run, continues across per-run failures, and shows one final deleted / failed / skipped summary before it returns to the same tag-delete flow after `Press Enter to continue`. The `/pipelines tags update` workflow asks for the current tag and replacement tag, lists every Azure DevOps build/run that still carries the current tag, groups the checkbox selection screen by pipeline name, removes the old tag and adds the new tag on each selected run, continues across per-run failures, and shows one final updated / failed / skipped summary before it returns to the same tag-update flow after `Press Enter to continue`. The `/repository review` workflow is contributed by the Gerber.ExampleOrg plugin. Gerber Core supplies the shared command registry plus the public Plugin API, while Gerber.ExampleOrg owns the review rules in `Gerber.ExampleOrg/src/resources/Properties.json`, accepts either a PR number in the configured project or a full PR URL, uses the same Gerber-owned Azure DevOps connection-readiness flow as Core commands, reviews the whole relevant file for each changed path, groups results by the standard DevOps review categories, shows that Markdown review in the terminal, and copies the same text for PR notes when clipboard copy is available. The `/secrets` menu uses secure credential storage, accepts case-insensitive Gerber identifiers such as `gerber:<scope>:<name>`, lists only non-sensitive identifiers, supports existence checks with `/secrets test`, copies a selected value to the clipboard before any terminal reveal when possible, and asks for confirmation before revealing, overwriting, or removing sensitive values.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1 ---------</maml:title> <maml:introduction> <maml:para>Start the interactive Gerber session.</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 the module 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>Use plain-text root search to jump directly to a leaf action.</maml:para> <maml:para>€</maml:para> <maml:para>```text uuid ado help ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 4 ---------</maml:title> <maml:introduction> <maml:para>Use autocomplete inside the root prompt.</maml:para> <maml:para>€</maml:para> <maml:para>```text / /to<Tab> uuid /tools ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 5 ---------</maml:title> <maml:introduction> <maml:para>Use the interactive Base64 tool after Gerber starts.</maml:para> <maml:para>€</maml:para> <maml:para>```text /tools /tools base-64 /tools base-64 encode /tools base-64 decode /list /list ado-agents /pipelines /pipelines tags delete /pipelines tags update /branch /branch find /branch set-searchable /branch set-default /repository /repository create /repository review /plugins /plugins list /plugins info /plugins enable /plugins disable /secrets /secrets list /secrets get /secrets test /secrets set /secrets remove ```</maml:para> </maml:introduction> <dev:code /> <dev:remarks /> </command:example> <command:example> <maml:title>--------- Example 6 ---------</maml:title> <maml:introduction> <maml:para>Review Core and eligible installed-plugin updates inside Gerber. Use arrow keys and Space to select available components when plugin rows exist. Review any automatically added Core requirement before confirming. Cancel is the default; no installation occurs without acceptance.</maml:para> <maml:para>€</maml:para> <maml:para>```text /update list ```</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>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.</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 authored PowerShell under src.</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> |