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` 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`; 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. Gerber Core has not yet been published to PSGallery. 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 you choose `/tools base-64 encode` or `/tools base-64 decode`, Gerber returns to that same action prompt after `Press Enter to continue` so repeated conversions stay in the selected tool flow. `/list ado-agents` shows a read-only Azure DevOps BUILD and DEPLOY agent report, retrieves the active profile PAT from secure credential storage only when authentication is required, and returns to the main menu after `Press Enter to continue`. `/list` keeps the built-in `ado-agents` and `ado-team-members` actions, and installed plugins may contribute additional read-only list actions beneath the same root. `/pipelines` keeps the built-in tag-maintenance actions, and installed plugins may contribute additional pipeline workflows beneath the same root. `/pipelines tags delete` asks for the current tag, finds every Azure DevOps build/run that still carries the current tag, shows those matches in one checkbox selector grouped by pipeline, removes the tag on each selected run, continues across per-run failures, and returns to the same tag-delete flow after `Press Enter to continue`. `/pipelines tags update` asks for the current tag and replacement tag, finds every Azure DevOps build/run that still carries the current tag, shows those matches in one checkbox selector grouped by pipeline, removes the old tag and adds the new tag on each selected run, continues across per-run failures, and returns to the same tag-update flow after `Press Enter to continue`. Installed plugins may also contribute `/repository` subcommands; Gerber.ExampleOrg currently provides `/repository review`, which accepts a PR number in the configured Azure DevOps project or a full PR URL, reviews the whole relevant file for each changed path, groups findings by the standardized DevOps review categories, shows that Markdown review directly in the terminal, copies the same text for PR notes when possible, and returns to the `/repository review` prompt after `Press Enter to continue`. `/secrets list` returns to the `/secrets` chooser after `Press Enter to continue`, while the input-driven `/secrets` actions reopen their selected flow. `/branch find` scans all Azure DevOps repositories for a given branch path and shows matching repos with a found-count summary. `/branch set-searchable` reads one or more comma-separated branch names, prompts for a Replace or Merge mode, previews the planned policy changes across all repositories, applies the changes after confirmation, and shows a created/updated/unchanged/failed summary. `/branch set-default` reads a branch name, previews which repositories would be updated, which are already on target, and which do not contain the branch, applies the default-branch change after one confirmation, and shows an updated/already-on-target/not-found/failed summary; repositories where the target branch does not exist are skipped silently during apply and reported in the final summary. `/repository create` prompts for an Azure DevOps project, template repository, repository name, and owner team; shows a preview of the planned mutations; creates the repository from the selected template; replaces legacy `PackageName` placeholders in paths, folder names, and content; creates pipelines from template YAML files; creates missing branches; copies branch policies from the selected template; links build validation policies to the newly created pipelines; creates an auto-include reviewer policy for the chosen team; continues past partial failures and reports them in the summary; and returns to the repository-name prompt after `Press Enter to continue`. Press `Esc` from an interactive prompt or continue screen to return to the main Gerber menu. Root slash browsing includes `/exit`, `/help`, `/plugins`, `/update`, `/branch`, `/list`, `/pipelines`, `/repository`, `/secrets`, and `/tools`, plus active plugin root commands, while plain-text root input searches executable leaf actions. `/tools` offers built-in actions such as `create-uuid` and `base-64` plus any installed plugin-provided tools, `/tools base-64` offers `encode` and `decode` for one-line UTF-8 text, `/list` offers `ado-agents` and `ado-team-members` plus any installed plugin-provided list actions, `/pipelines` offers `tags delete` and `tags update` plus any installed plugin-provided pipeline actions, `/branch` offers `find`, `set-searchable`, and `set-default`, `/repository` offers the built-in `create` action plus any installed plugin-provided repository actions such as Gerber.ExampleOrg's `review`, `/plugins` offers `list`, `info`, `enable`, and `disable`, and `/secrets` offers `list`, `get`, `test`, `set`, and `remove`. `/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` performs fresh Core discovery and shows installed/available versions, repository and status. Installation requires explicit confirmation with Cancel as the default. PMU performs installation and reports verification, recovery and restart requirements; Gerber never hot reloads Core. Failed discovery is not "up to date". Plugin updates remain planned. `/plugins create` asks for a module suffix behind a fixed `Gerber.` prefix, description, unused command namespace, and existing destination parent (current directory by default). 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 and lifecycle state, explicitly Installed: No. 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. PMU's explicit Stable/CurrentUser policy handles installed prerelease metadata: stable `0.1.0` can supersede `0.1.0-preview`; newer prereleases are excluded. Gerber Core has not yet been published to PSGallery. No matching package is not a configuration error, a currency claim or permission to install. 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. The inline Azure DevOps setup flow validates Azure DevOps Services and Server project URLs through the shared parser, asks for an explicit Server root only when required, stores profile metadata in user configuration, stores PATs only in secure credential storage as `gerber:ado:<profile>:pat`, and fails clearly without prompting when input is redirected. 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 updates in PSGallery inside Gerber; no repository setup is needed. Cancel is the default; no installation occurs without acceptance.</maml:para> <maml:para>€</maml:para> <maml:para>```text /update ```</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 overview</maml:linkText> <maml:uri>../../../README.md</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> |