diff --git a/.github/agents/architect.agent.md b/.github/agents/architect.agent.md index cbb84c43..17fbc342 100644 --- a/.github/agents/architect.agent.md +++ b/.github/agents/architect.agent.md @@ -37,6 +37,7 @@ Design or reshape changes that cross public commands, private helper boundaries, ## Skills to use - `/powershell-module-development` +- `/terminal-ux-design` - `/release-and-changelog` - `/markdown-authoring` - `/building-maintainable-code` diff --git a/.github/agents/docs-site.agent.md b/.github/agents/docs-site.agent.md index 8815a31c..fb1d0877 100644 --- a/.github/agents/docs-site.agent.md +++ b/.github/agents/docs-site.agent.md @@ -14,6 +14,7 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused, - Update `docs/*.html` when end-user workflows, examples, or website wording change. - Preserve the separation between CLI-oriented website docs and PowerShell cmdlet help. - Check whether source, tests, help docs, and website docs still agree after a change. +- Keep command-surface-toggle pages honest by splitting CLI-only and PowerShell-only wording into the matching `data-command-visibility` blocks instead of mixing both spellings in shared prose. ## Inputs to inspect @@ -37,15 +38,18 @@ Keep the GitHub Pages documentation under `docs/*.html` accurate, user-focused, - Treat `docs/*.html` as end-user website docs, not cmdlet help. - Keep CLI and cmdlet surfaces clearly separated. - Mention PowerShell-only commands in CLI-oriented docs only when there is no CLI equivalent for that scenario, such as installing NovaModuleTools with `Install-Module`. +- On pages with the surface toggle, only show `--option` spellings in command-line-visible blocks and only show `-Parameter` spellings in PowerShell-visible blocks unless the wording is fully surface-neutral. ## Definition of done - The changed website docs reflect the current behavior. - CLI-oriented docs do not drift into cmdlet-help wording. +- Surface-specific labels, flags, and parameter names match the active website command surface. - Relevant contributor docs and changelog were reviewed for follow-up impact. ## Must not do - Must not mix cmdlet syntax into CLI docs when a CLI variant exists. +- Must not leave shared always-visible HTML copy with both CLI flags and PowerShell parameters when the page already has the command-surface toggle. - Must not use `docs/*.html` as a duplicate of `docs/NovaModuleTools/en-US/*.md`. - Must not leave installation/documentation exceptions implicit; state them clearly. diff --git a/.github/agents/powershell-developer.agent.md b/.github/agents/powershell-developer.agent.md index 3a7dc0cc..2a0090d4 100644 --- a/.github/agents/powershell-developer.agent.md +++ b/.github/agents/powershell-developer.agent.md @@ -32,6 +32,7 @@ Implement PowerShell command and helper changes in the NovaModuleTools style. ## Skills to use - `/powershell-module-development` +- `/terminal-ux-design` - `/pester-testing` - `/building-maintainable-code` - `/codescene-quality` diff --git a/.github/agents/reviewer.agent.md b/.github/agents/reviewer.agent.md index aab9fde0..69fcb879 100644 --- a/.github/agents/reviewer.agent.md +++ b/.github/agents/reviewer.agent.md @@ -41,6 +41,7 @@ Review changes for correctness, maintainability, test coverage, workflow safety, ## Skills to use +- `/terminal-ux-design` - `/codescene-quality` - `/safeguarding-ai-generated-code` - `/building-maintainable-code` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e8a83d51..55b93ee4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,15 +37,15 @@ For new or not-yet-scoped work, use the `architect` agent with `.github/prompts/ The table below shows how to route work. Prompts are the task entry points; each prompt delegates to its agent, which uses the listed skills, which in turn enforce the listed instructions. -| Task | Prompt | Agent | Primary skills | Primary instructions | -| ----------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| Design or scope a change | `design-change.prompt.md` | `architect` | `powershell-module-development`, `github-actions`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix` | -| Implement an issue | `implement-issue.prompt.md` | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` | -| Review a change | `review-change.prompt.md` | `reviewer` | `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md` | -| Improve test coverage | `improve-test-coverage.prompt.md` | `test-engineer` | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer` | -| Prepare a release | `prepare-release.prompt.md` | `release-manager` | `release-and-changelog`, `markdown-authoring` | `release-policy`, `repository-conventions` | -| Fix a CI failure | `fix-ci-failure.prompt.md` | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing` | `testing-policy`, `psscriptanalyzer`, `repository-conventions` | -| Update website docs | (no dedicated prompt — invoke agent) | `docs-site` | `docs-site`, `markdown-authoring` | `documentation-separation` | +| Task | Prompt | Agent | Primary skills | Primary instructions | +|--------------------------|--------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| Design or scope a change | `design-change.prompt.md` | `architect` | `powershell-module-development`, `terminal-ux-design`, `github-actions`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix` | +| Implement an issue | `implement-issue.prompt.md` | `powershell-developer` | `powershell-module-development`, `terminal-ux-design`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` | +| Review a change | `review-change.prompt.md` | `reviewer` | `terminal-ux-design`, `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md` | +| Improve test coverage | `improve-test-coverage.prompt.md` | `test-engineer` | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer` | +| Prepare a release | `prepare-release.prompt.md` | `release-manager` | `release-and-changelog`, `markdown-authoring` | `release-policy`, `repository-conventions` | +| Fix a CI failure | `fix-ci-failure.prompt.md` | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing` | `testing-policy`, `psscriptanalyzer`, `repository-conventions` | +| Update website docs | (no dedicated prompt — invoke agent) | `docs-site` | `docs-site`, `markdown-authoring` | `documentation-separation` | ## Notation @@ -61,5 +61,6 @@ The table below shows how to route work. Prompts are the task entry points; each - PSScriptAnalyzer workflow: `.github/instructions/psscriptanalyzer.instructions.md` - PowerShell coding standards: `.github/instructions/powershell-coding-standards.instructions.md` - PlatyPS help generation: `.github/instructions/platyps-help.instructions.md` +- Terminal UX: `.github/instructions/terminal-ux-design.instructions.md` + `terminal-ux-design` skill - Release flow: `.github/instructions/release-policy.instructions.md` + `release-and-changelog` skill - Documentation separation: `.github/instructions/documentation-separation.instructions.md` + `docs-site` skill diff --git a/.github/instructions/documentation-separation.instructions.md b/.github/instructions/documentation-separation.instructions.md index 226af0fd..e8ff6450 100644 --- a/.github/instructions/documentation-separation.instructions.md +++ b/.github/instructions/documentation-separation.instructions.md @@ -20,6 +20,10 @@ NovaModuleTools has multiple documentation surfaces with different audiences. Ke - Do not write cmdlet help markdown as if it were `nova` CLI documentation. - Use CLI syntax in CLI-oriented website docs when a CLI variant exists. - Use cmdlet syntax in help markdown and PowerShell-specific contributor guidance. +- On website pages that support the command-surface toggle, keep surface-specific wording behind the matching visibility gate. + - CLI-only flags, labels, and guidance belong in elements marked with `data-command-visibility="command-line"`. + - PowerShell-only parameters, labels, and guidance belong in elements marked with `data-command-visibility="powershell"`. + - Shared prose should stay surface-neutral instead of mixing `--option` and `-Parameter` spellings in the same always-visible paragraph. ## Allowed exception @@ -33,6 +37,7 @@ NovaModuleTools has multiple documentation surfaces with different audiences. Ke - Does this page describe a `nova` workflow or a PowerShell cmdlet workflow? - If a `nova` command exists, is the website doc using it instead of the cmdlet? - If a cmdlet is shown in website docs, is it there because no CLI variant exists? +- If the page uses the command-surface toggle, do the visible labels, flags, and parameter names match the selected surface? - Would an end user mistake this page for cmdlet help? ## Follow-up expectations diff --git a/.github/instructions/platyps-help.instructions.md b/.github/instructions/platyps-help.instructions.md index dcb320ce..b2714daf 100644 --- a/.github/instructions/platyps-help.instructions.md +++ b/.github/instructions/platyps-help.instructions.md @@ -66,6 +66,9 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/.md | - The `external help file` field must always use the module name, not the command name: `NovaModuleTools-Help.xml`. The `Module Name` field must match the project name. When both fields use the module name, Nova build produces a single `-Help.xml` under `dist//en-US/`. If either field contains a command name instead, the build produces per-command XML files and the module manifest cannot find its help. - Keep the H1 title equal to the exact command name. - Preserve the standard PlatyPS section order with uppercase H2 headers: `SYNOPSIS`, `SYNTAX`, optional `ALIASES`, `DESCRIPTION`, `EXAMPLES`, `PARAMETERS`, `INPUTS`, `OUTPUTS`, `NOTES`, and `RELATED LINKS`. +- In `## RELATED LINKS`, use only a bulleted list of Markdown links. Do not use bare URLs or backticked command names as list items. +- Prefer relative links to sibling command-help files when the related topic has a matching file in `docs/NovaModuleTools/en-US/`, for example `[Invoke-NovaBuild](./Invoke-NovaBuild.md)`. +- Do not use GitHub blob URLs in shipped command help. If a relative command-help link is not suitable after PlatyPS validation, use the related topic's `novamoduletools.com` `HelpUri` instead. - Keep at least one example under `## EXAMPLES`. - Keep parameter sections as `### -ParameterName` blocks with the PlatyPS-generated YAML metadata code block. - Only hand-edit parameter metadata when PlatyPS cannot infer it correctly, especially `DefaultValue` and `SupportsWildcards`. @@ -82,6 +85,7 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/.md | - Use `Update-MarkdownCommandHelp` after command or parameter changes so syntax, aliases, and parameter metadata stay synchronized with the implementation. - Use `Test-MarkdownCommandHelp` as the quick structural gate before handoff; use `Import-MarkdownCommandHelp` diagnostics when you need more detail. - Use existing valid files under `docs/NovaModuleTools/en-US/` as the structural template before inventing a new layout. +- Validate any new `RELATED LINKS` target style through the real PlatyPS import/export path before applying it repo-wide. - Keep command help separate from contributor docs and project/site docs. ## Review expectations @@ -90,4 +94,5 @@ Import-MarkdownCommandHelp -Path ./docs/NovaModuleTools/en-US/.md | - Reviewers should flag help files where `external help file` contains a command name (e.g., `Get-Something-Help.xml`) instead of the module name (`NovaModuleTools-Help.xml`). This produces per-command XML files that the module manifest cannot locate at runtime. - Reviewers should flag help files that would fail `Test-MarkdownCommandHelp` or produce diagnostics/errors when imported with `Import-MarkdownCommandHelp`. - Reviewers should flag any new public entry point that does not add its matching command-help file in the same change. +- Reviewers should flag `RELATED LINKS` entries that use GitHub blob URLs, plain URLs, or bare/backticked command names instead of Markdown links. - Treat build errors from `Import-MarkdownCommandHelp` as a sign that the file is not valid PlatyPS help yet. diff --git a/.github/instructions/terminal-ux-design.instructions.md b/.github/instructions/terminal-ux-design.instructions.md new file mode 100644 index 00000000..a6312f2d --- /dev/null +++ b/.github/instructions/terminal-ux-design.instructions.md @@ -0,0 +1,21 @@ +--- +applyTo: "**" +--- + +# Terminal UX design + +Use the `terminal-ux-design` skill when a change touches any user-facing command, terminal output, prompt, help surface, progress indicator, warning, error message, or scaffold guidance for those surfaces. + +This applies to: + +- PowerShell cmdlets +- `% nova` CLI routes +- private helpers that shape user-visible terminal behavior +- contributor docs, command help, and scaffold content that teach those workflows + +Keep PowerShell cmdlet UX and `% nova` CLI UX distinct, but hold both to the same terminal UX bar. + +The skill is authoritative for: + +- Atlassian's 10 design principles for delightful CLIs +- Jakob Nielsen's 10 usability heuristics for user interface design diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0adae173..c327641d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -20,6 +20,7 @@ - [ ] Dependency or manifest changes (`project.json`, workflow dependencies, release tooling) - [ ] Security-sensitive change - [ ] Documentation-only change +- [ ] Agentic Copilot Workflow + scaffold mirror + scaffold-sync guardrail test. - [ ] Other ## Review guidance diff --git a/.github/skills/docs-site/SKILL.md b/.github/skills/docs-site/SKILL.md index fa788890..ec145ea2 100644 --- a/.github/skills/docs-site/SKILL.md +++ b/.github/skills/docs-site/SKILL.md @@ -24,11 +24,13 @@ Use this skill when changing `docs/*.html`, end-user examples, installation guid - Use CLI-oriented examples when the workflow has a `nova` variant. - Mention PowerShell cmdlets only when no CLI equivalent exists for that scenario. - Keep installation guidance explicit about PowerShell-only steps such as `Install-Module`. +- On pages with the command-surface toggle, keep option/parameter wording aligned with the active surface by using `data-command-visibility="command-line"` and `data-command-visibility="powershell"` blocks instead of one shared paragraph that mixes CLI flags with PowerShell parameters. - Recheck the matching command-help markdown when public behavior changes. ## Common pitfalls - Mixing `Get-/Set-/Invoke-/Install-` cmdlets into CLI docs where `nova` exists +- Leaving `--option` text visible in PowerShell mode, or `-Parameter` text visible in command-line mode, because the surrounding prose was not split by `data-command-visibility` - Duplicating cmdlet help text in website docs instead of adapting it for end users - Forgetting that `docs/NovaModuleTools/en-US/*.md` and `docs/*.html` serve different audiences - Updating website docs without reviewing changelog or contributor-doc impact @@ -36,5 +38,6 @@ Use this skill when changing `docs/*.html`, end-user examples, installation guid ## Verification - Read the touched HTML page as an end-user flow +- Toggle the page mentally between PowerShell and command-line surfaces and confirm the visible option/parameter names still match that surface - Check whether the same behavior is documented consistently in help markdown or contributor docs - Use docs-only validation when no executable behavior changed diff --git a/.github/skills/terminal-ux-design/SKILL.md b/.github/skills/terminal-ux-design/SKILL.md new file mode 100644 index 00000000..b83d8b56 --- /dev/null +++ b/.github/skills/terminal-ux-design/SKILL.md @@ -0,0 +1,145 @@ +--- +name: terminal-ux-design +description: Guidance for designing terminal-first PowerShell cmdlets and CLI workflows with Atlassian's CLI principles and Jakob Nielsen's usability heuristics. +--- + +# Skill: terminal UX design + +## When to use + +Use this skill when: + +- adding or changing a public PowerShell cmdlet +- adding or changing a CLI command/route or its help/output flow +- shaping prompts, progress, warnings, success messages, or error messages +- reviewing terminal-facing behavior in scaffolds, contributor docs, or command help + +This skill applies even when the surface is not named "CLI". In NovaModuleTools, PowerShell cmdlets are also terminal UX. + +## Two surfaces, two conventions + +The same underlying PowerShell code can present itself through two distinct user-facing surfaces, and each is held to its own conventions: + +- **PowerShell cmdlet surface** — anything invoked as `Verb-Noun -Parameter` in a PowerShell session. Follow PowerShell conventions: approved verbs, `-Parameter` naming, `Write-*` streams, `Get-Help`, `-WhatIf` / `-Confirm`, pipeline-friendly output. +- **CLI alias surface** — anything invoked as a unix-style command, including PowerShell aliases or wrapper functions that emulate a CLI (for example `nova --flag`). Follow CLI conventions: `--flag` / `-f`, subcommands, `--help`, predictable exit codes, `Ctrl+C` cancellation, text-stream output. + +Decide which surface a command exposes before applying the per-principle guidance below. A single command may be reachable through both surfaces; in that case, evaluate each surface against its own conventions instead of blending them. + +## Relevant surfaces + +This skill is intentionally surface-based rather than path-based, so it applies the same way in this repository and in any project scaffolded by `nova init`, regardless of folder layout. Apply it to any change that touches: + +- a public PowerShell cmdlet or its parameters, help, output, or error contract +- a CLI command/route, its help text, flags, exit codes, or output +- a helper that shapes terminal-visible help, prompts, progress, warnings, or errors +- command help authored for PlatyPS or equivalent help generators +- contributor-facing agent, instruction, or skill files that describe terminal-facing behavior + +## Atlassian's 10 design principles for delightful CLIs + +1. **Align with established conventions** + Use established PowerShell and terminal conventions so users do not have to relearn basic command behavior. + PowerShell cmdlets: prefer approved verbs, common parameter semantics, and standard streams. + CLI: prefer familiar `--flag` / `-f` patterns, standard help forms, and predictable exit codes. +2. **Build help into the CLI** + Help must be discoverable from the command itself, not only from external docs. + PowerShell cmdlets: keep comment-based help complete and `Get-Help -Full` useful. + CLI: keep `--help` and ` --help` accurate and task-focused. +3. **Show progress visually** + Long-running work should expose state, phases, and forward motion. + PowerShell cmdlets: use `Write-Progress` when work is meaningful enough to justify it. + CLI: show clear step transitions and status lines instead of silent waiting. +4. **Create a reaction for every action** + Every meaningful user action should receive clear feedback. + PowerShell cmdlets: success, cancellation, and failure paths should be explicit. + CLI: commands should not silently succeed, silently cancel, or fail without context. +5. **Craft human-readable error messages** + Errors should explain what happened and what to do next. + PowerShell cmdlets: surface actionable `Stop-NovaOperation` messages and preserve a stable `ErrorId`. + CLI: convert internal failures into user-readable guidance instead of raw backend output. +6. **Support your skim-readers** + Terminal output should be easy to scan under time pressure. + PowerShell cmdlets: prefer short paragraphs, focused bullets, and restrained output. + CLI: keep normal-path output minimal and make the important line easy to spot. +7. **Suggest the next best step** + After a successful action, guide the user to the most likely follow-up. + PowerShell cmdlets: mention the next cmdlet or validation step when it helps. + CLI: suggest the next subcommand instead of forcing the user back to docs. +8. **Consider your options** + Make common cases easy with prompts, defaults, and clear required inputs. + PowerShell cmdlets: use sensible defaults, parameter validation, and prompts only when the flow is intentionally interactive. + CLI: accept explicit flags for automation, but guide the user when required context is missing. +9. **Provide an easy way out** + Users need a clear cancellation and escape path. + PowerShell cmdlets: preserve native `-WhatIf`, `-Confirm`, and cancellation semantics. + CLI: make `Ctrl+C`, cancel choices, and non-destructive previews obvious. +10. **Flags over args** + Favor named inputs over memory-heavy positional usage. + PowerShell cmdlets: prefer explicit parameter names and sensible aliases over positional-only designs. + CLI: prefer `--environment production` over unlabeled ordered arguments. + +## Jakob Nielsen's 10 usability heuristics for user interface design + +1. **Visibility of system status** + Keep users informed about current state, current step, and recent outcome within a reasonable time. +2. **Match between the system and the real world** + Use the user's language, not internal implementation jargon, and order information the way users expect. +3. **User control and freedom** + Support cancel, undo, preview, and escape paths so users do not feel trapped in a workflow. +4. **Consistency and standards** + Use one meaning per word, one shape per interaction, and familiar platform conventions across cmdlets, CLI routes, and docs. +5. **Error prevention** + Prevent common mistakes with defaults, validation, confirmations, and constraints before the user commits. +6. **Recognition rather than recall** + Show the needed options, values, examples, and names instead of forcing the user to remember them from earlier output. +7. **Flexibility and efficiency of use** + Support both newcomers and experts with clear defaults plus shortcuts, aliases, and low-friction repeated flows. +8. **Aesthetic and minimalist design** + Every line in the terminal competes for attention. Keep normal-path output focused on what matters now. +9. **Help users recognize, diagnose, and recover from errors** + State the problem plainly, show where it happened, and suggest recovery steps that a user can act on immediately. +10. **Help and documentation** + Make help searchable, contextual, concise, and task-oriented. Users should not have to leave the workflow to understand the next step. + +## Combined mapping table + +| Concern | Concrete PowerShell / CLI mechanism | Atlassian principle(s) | Nielsen heuristic(s) | +|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|----------------------| +| Surface routing | Decide whether the command exposes a PowerShell cmdlet surface, a unix-style CLI alias surface, or both, and apply the matching conventions per surface | 1, 10 | 2, 4 | +| Status visibility | `Write-Progress`, stage-by-stage status lines, clear completion/cancel summaries | 3, 4, 7 | 1 | +| Familiar language | Approved PowerShell verbs, user-facing terminology, surface-specific wording in docs and help | 1 | 2, 4 | +| Safe exits | `-WhatIf`, `-Confirm`, `SupportsShouldProcess`, explicit cancel choices, `Ctrl+C` support | 9 | 3, 5 | +| Error prevention | Parameter validation, pre-flight checks, sensible defaults, explicit `-OverrideWarning` / `--override-warning` gates | 8 | 5 | +| Recognition over recall | Comment-based help, CLI `--help`, examples, prompts that show available choices, discoverable defaults | 2, 8, 10 | 6, 10 | +| Expert efficiency | Parameter aliases, short CLI flags, repeatable subcommand flows, next-step hints for common sequences | 7, 10 | 7 | +| Minimal output | Short paragraphs, focused bullets, no decorative banners in normal mode, use `-Verbose` for detail | 6 | 8 | +| Recoverable errors | `Stop-NovaOperation` with stable `ErrorId`, plain language, and actionable recovery guidance | 5 | 9 | +| Help quality | Accurate `Get-Help`, accurate CLI ` --help`, related links, task-oriented examples | 2 | 10 | +| Consistent surfaces | Do not mix cmdlet `-Parameter` syntax into CLI guidance or CLI `--flag` syntax into cmdlet help | 1, 10 | 2, 4 | + +## Expected practices + +- Keep PowerShell cmdlet UX and CLI UX distinct, but hold both to the same terminal UX bar. +- Tell users what happened, especially after mutating, long-running, or risky operations. +- Prefer visible choices, examples, and defaults over forcing users to remember values from prior steps. +- Prevent high-cost mistakes before execution; recover clearly when prevention is not enough. +- Keep normal-path output concise, with optional detail on demand through the appropriate verbose/help surface. +- When a next step is common and useful, suggest it explicitly. + +## Common pitfalls + +- leaking internal jargon, object names, or backend wording into user-facing messages +- returning success with no visible reaction +- printing raw exception text without recovery guidance +- forcing users to remember flag names, route names, IDs, or paths from earlier output +- mixing cmdlet syntax and CLI syntax in the same always-visible guidance +- using large banner-style output where one clear status line would do +- adding confirmations or prompts in a way that breaks automation + +## Definition of done + +- The user can discover how to invoke the command from the terminal surface they are using. +- Long-running, risky, and error paths expose enough state to keep the user oriented. +- The command uses user language, not internal implementation language. +- The normal path is concise and scannable. +- The user has a clear recovery path after errors and a clear exit path during risky or interactive flows. diff --git a/AGENTS.md b/AGENTS.md index 8801c37d..015cd5f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,15 +39,15 @@ For new or not-yet-scoped work, use the `architect` agent with `.github/prompts/ The table below shows how to route work. Prompts are the task entry points; each prompt delegates to its agent, which uses the listed skills, which in turn enforce the listed instructions. -| Task | Prompt | Agent | Primary skills | Primary instructions | -| ----------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| Design or scope a change | `design-change.prompt.md` | `architect` | `powershell-module-development`, `github-actions`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix` | -| Implement an issue | `implement-issue.prompt.md` | `powershell-developer` | `powershell-module-development`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` | -| Review a change | `review-change.prompt.md` | `reviewer` | `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md` | -| Improve test coverage | `improve-test-coverage.prompt.md` | `test-engineer` | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer` | -| Prepare a release | `prepare-release.prompt.md` | `release-manager` | `release-and-changelog`, `markdown-authoring` | `release-policy`, `repository-conventions` | -| Fix a CI failure | `fix-ci-failure.prompt.md` | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing` | `testing-policy`, `psscriptanalyzer`, `repository-conventions` | -| Update website docs | (no dedicated prompt — invoke agent) | `docs-site` | `docs-site`, `markdown-authoring` | `documentation-separation` | +| Task | Prompt | Agent | Primary skills | Primary instructions | +|--------------------------|--------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| +| Design or scope a change | `design-change.prompt.md` | `architect` | `powershell-module-development`, `terminal-ux-design`, `github-actions`, `release-and-changelog`, `markdown-authoring` | `repository-conventions`, `code-quality-matrix` | +| Implement an issue | `implement-issue.prompt.md` | `powershell-developer` | `powershell-module-development`, `terminal-ux-design`, `pester-testing`, `building-maintainable-code`, `codescene-quality`, `safeguarding-ai-generated-code` | `repository-conventions`, `code-quality-matrix`, `psscriptanalyzer`, `powershell-coding-standards`, `platyps-help` | +| Review a change | `review-change.prompt.md` | `reviewer` | `terminal-ux-design`, `codescene-quality`, `safeguarding-ai-generated-code`, `building-maintainable-code`, `docs-site`, `markdown-authoring`, `pester-testing`, `release-and-changelog`, `github-actions` | All `.github/instructions/*.instructions.md` | +| Improve test coverage | `improve-test-coverage.prompt.md` | `test-engineer` | `pester-testing`, `building-maintainable-code`, `codescene-quality`, `github-actions`, `guiding-refactoring-with-code-health`, `safeguarding-ai-generated-code` | `testing-policy`, `psscriptanalyzer` | +| Prepare a release | `prepare-release.prompt.md` | `release-manager` | `release-and-changelog`, `markdown-authoring` | `release-policy`, `repository-conventions` | +| Fix a CI failure | `fix-ci-failure.prompt.md` | `powershell-developer` (or `test-engineer`) | `github-actions`, `pester-testing` | `testing-policy`, `psscriptanalyzer`, `repository-conventions` | +| Update website docs | (no dedicated prompt — invoke agent) | `docs-site` | `docs-site`, `markdown-authoring` | `documentation-separation` | ## Notation @@ -63,5 +63,6 @@ The table below shows how to route work. Prompts are the task entry points; each - PSScriptAnalyzer workflow: `.github/instructions/psscriptanalyzer.instructions.md` - PowerShell coding standards: `.github/instructions/powershell-coding-standards.instructions.md` - PlatyPS help generation: `.github/instructions/platyps-help.instructions.md` +- Terminal UX: `.github/instructions/terminal-ux-design.instructions.md` + `terminal-ux-design` skill - Release flow: `.github/instructions/release-policy.instructions.md` + `release-and-changelog` skill - Documentation separation: `.github/instructions/documentation-separation.instructions.md` + `docs-site` skill diff --git a/CHANGELOG.md b/CHANGELOG.md index 525373a8..fda1aab7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Added +- Added `Invoke-NovaAgenticCopilotScaffold` and `% nova copilot` for applying or refreshing Nova's managed Agentic Copilot scaffold in an existing project root. + - The workflow reads `ProjectName` and `Description` from `project.json`, requires a `ShortName` on every run for token replacement, and fails clearly when the project metadata or short name is invalid. + - Nova refreshes only the approved managed Agentic Copilot paths under `.github/` plus `AGENTS.md` and `CONTRIBUTING.md`, while `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are created only when they are missing. + - The new cmdlet and CLI route prompt before overwriting managed scaffold content by default, and support non-interactive execution only through `-OverrideWarning` / `--override-warning` / `-o`. +- Added `terminal-ux-design` to Nova's repository-local and scaffolded Agentic Copilot guidance. + - The new guidance combines Atlassian's 10 design principles for delightful CLIs with Jakob Nielsen's 10 usability heuristics for user interface design, and applies them to both the PowerShell cmdlet surface and any unix-style CLI alias surface (such as `% nova`) as terminal-first user interfaces. + - The new skill ships with a "two surfaces, two conventions" framing, a shared mapping table for concrete PowerShell cmdlet and CLI alias UX mechanisms, a universal instruction that points terminal-facing changes at the skill, and updated architect, implementation, and review agent entry points. + ### Changed +- `Deploy-NovaPackage` now shows a concise resolved-upload summary before execution, reports progress while multiple artifacts are uploading, and prints a short completion summary with a suggested verification step after successful raw uploads. +- `Get-NovaProjectInfo` now fails with clearer recovery guidance when `-Path` does not exist, points to a file, or the target folder is missing `project.json`. +- `Get-NovaUpdateNotificationPreference -Verbose` now explains whether Nova is reading a stored preference or the built-in default, and the command help now points read-only PowerShell users to the matching `% nova notification` workflow. +- `Initialize-NovaModule` now shows scaffold progress, ends with the created project root plus the next suggested cmdlet, and fails with clearer guidance when the target project folder already exists. +- `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the destination directory is not yet available from the shell. +- `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and fails with clearer cancellation guidance when the overwrite warning is declined. +- `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module. +- `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated PlatyPS help topic for the PowerShell wrapper surface. +- `Invoke-NovaRelease` now shows progress for the main release phases, ends with the publish target plus a next-step hint, and uses a plan summary instead of a success summary when `-WhatIf` previews the release. +- `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode. +- `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode. +- `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied. +- `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail. +- `Update-NovaModuleTool` now ends with a visible up-to-date, preview, cancelled, or updated summary, skips prerelease confirmation during `-WhatIf`, shows progress for the actual self-update step, and suggests `Get-NovaProjectInfo -Installed` after a successful update. +- `Update-NovaModuleVersion` now ends with a visible preview, cancelled, or updated summary, prints the resolved version file plus the detected/applied release label, shows progress while writing `project.json`, and suggests the next command to run after the bump. + ### Deprecated ### Removed ### Fixed +- `Test-NovaBuild` now expands configured Pester coverage globs into concrete source files before invoking Pester, so nested helpers remain measurable in `artifacts/coverage.xml` while repository and scaffolded `project.json` defaults can stay on the simpler `src/private/**/*.ps1` entry. +- PowerShell command help `RELATED LINKS` now use valid PlatyPS Markdown links and point to shipped help topics instead of GitHub blob pages. + ### Security ## [3.0.1] - 2026-05-18 @@ -412,6 +439,7 @@ This release was yanked because it removed the implicit `Pester` dependency, bef - All basic functionality of Module is ready [Unreleased]: https://github.com/stiwicourage/NovaModuleTools/compare/3.0.1...HEAD + [3.0.1]: https://github.com/stiwicourage/NovaModuleTools/compare/3.0.0...3.0.1 [3.0.0]: https://github.com/stiwicourage/NovaModuleTools/compare/2.4.0...3.0.0 [2.4.0]: https://github.com/stiwicourage/NovaModuleTools/compare/2.3.1...2.4.0 @@ -432,4 +460,3 @@ This release was yanked because it removed the implicit `Pester` dependency, bef [0.0.6]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.5...Version_0.0.6 [0.0.5]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.4...Version_0.0.5 [0.0.4]: https://github.com/stiwicourage/NovaModuleTools/compare/Version_0.0.3...Version_0.0.4 - diff --git a/README.md b/README.md index 46c29699..5b90aa06 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,19 @@ Direct PowerShell cmdlets such as `Publish-NovaModule`, `Deploy-NovaPackage`, an The module does not export a PowerShell alias named `nova`. Install the bundled launcher with `Install-NovaCli` when you want `% nova ...` available directly from your shell. +### Apply or refresh the Agentic Copilot scaffold + +Use the dedicated scaffold command when you want to add Nova's maintained Agentic Copilot workflow to an existing project, or refresh an older scaffold to Nova's latest managed version: + +```powershell +PS> Invoke-NovaAgenticCopilotScaffold -ShortName NMT +% nova copilot --short-name NMT +``` + +The target directory must contain a valid `project.json`. Nova reads `ProjectName` and `Description` from that file, requires `ShortName` on every run for token replacement, and refreshes only the Nova-managed Agentic Copilot paths under `.github/` plus `AGENTS.md` and `CONTRIBUTING.md`. Existing `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are preserved and are created only when they are missing. + +By default the scaffold flow prompts before it overwrites the managed paths. Use `-OverrideWarning` or `--override-warning` only when you intentionally want a non-interactive apply. The CLI also supports the short form `% nova copilot -n NMT -o`. Use `-WhatIf` or `--what-if` when you want to preview the operation without changing files. + ### Reload the built module while iterating Use the built output during development so you validate the same shape CI uses: diff --git a/RELEASE_NOTE.md b/RELEASE_NOTE.md index ad8d57ae..d7cae159 100644 --- a/RELEASE_NOTE.md +++ b/RELEASE_NOTE.md @@ -6,14 +6,37 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang ### Added +- Added `Invoke-NovaAgenticCopilotScaffold` and `% nova copilot` for adding or refreshing Nova's managed Agentic Copilot workflow in an existing project. + - The workflow reads `ProjectName` and `Description` from `project.json`, requires an explicit `ShortName` on every run, and stops with a clear validation error when the target project metadata is missing or invalid. + - Nova refreshes only its managed Agentic Copilot files and folders, while `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are created only when they are missing. + - The command prompts before overwrite by default and supports non-interactive execution only through `-OverrideWarning` / `--override-warning` / `-o`. + ### Changed +- `Deploy-NovaPackage` now shows clearer terminal feedback during raw package uploads, including a concise pre-flight summary, progress across multiple artifacts, and a short verification hint after success. +- `Get-NovaProjectInfo` now explains how to recover when `-Path` is invalid or the target folder is not a Nova project root. +- `Get-NovaUpdateNotificationPreference -Verbose` now tells you whether Nova is using a stored update-notification preference or the built-in default, and the help now points to the matching `% nova notification` workflow. +- `Initialize-NovaModule` now shows scaffold progress, ends with the project root and the next suggested cmdlet, and gives clearer recovery guidance when the target project folder already exists. +- `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the launcher directory is not yet available from the shell. +- `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and gives clearer cancellation guidance when the overwrite warning is declined. +- `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module. +- `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated help topic for the PowerShell wrapper surface. +- `Invoke-NovaRelease` now shows progress for the main release phases, ends with the publish target plus a next-step hint, and uses a plan summary instead of a success summary when `-WhatIf` previews the release. +- `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode. +- `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode. +- `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied. +- `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail. +- `Update-NovaModuleTool` now ends with a visible up-to-date, preview, cancelled, or updated summary, skips prerelease confirmation during `-WhatIf`, shows progress for the actual self-update step, and suggests `Get-NovaProjectInfo -Installed` after a successful update. +- `Update-NovaModuleVersion` now ends with a visible preview, cancelled, or updated summary, prints the resolved version file plus the detected/applied release label, shows progress while writing `project.json`, and suggests the next command to run after the bump. + ### Deprecated ### Removed ### Fixed +- PowerShell command help `RELATED LINKS` now use valid help-topic. + ### Security ## [3.0.1] - 2026-05-18 @@ -195,4 +218,3 @@ This release was yanked because it removed the implicit `Pester` dependency befo ## [0.0.4] - 2024-06-25 ### Added - First PowerShell Gallery release of NovaModuleTools with the initial module workflow support. - diff --git a/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md b/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md index aaa4dc8e..7494f2a8 100644 --- a/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md +++ b/docs/NovaModuleTools/en-US/Deploy-NovaPackage.md @@ -1,10 +1,10 @@ ---- +--- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: https://www.novamoduletools.com/packaging-and-delivery.html#upload Locale: en-US Module Name: NovaModuleTools -ms.date: 04/25/2026 +ms.date: 05.24.2026 PlatyPS schema version: 2024-05-01 title: Deploy-NovaPackage --- @@ -19,10 +19,15 @@ Uploads one or more generated package artifacts to a raw HTTP endpoint. ### __AllParameterSets -```powershell -PS> Deploy-NovaPackage [[-PackagePath] ] [[-PackageType] ] [[-Url] ] [[-Repository] ] [[-UploadPath] ] [[-Headers] ] [[-Token] ] [[-TokenEnvironmentVariable] ] [[-AuthenticationScheme] ] [-WhatIf] [-Confirm] [] +``` +Deploy-NovaPackage [[-PackagePath] ] [[-PackageType] ] [[-Url] ] + [[-Repository] ] [-WhatIf] [-Confirm] [-UploadPath ] [-Headers ] + [-Token ] [-TokenEnvironmentVariable ] [-AuthenticationScheme ] + [] ``` +## ALIASES + ## DESCRIPTION `Deploy-NovaPackage` uploads existing package artifacts that were generated by `New-NovaModulePackage`. @@ -42,6 +47,8 @@ This command is intentionally separate from `Publish-NovaModule`. `Deploy-NovaPa When you run `Deploy-NovaPackage -Confirm`, PowerShell uses its native confirmation prompt against the full resolved upload set instead of prompting once per artifact. +Before uploads start, `Deploy-NovaPackage` prints a concise summary of the resolved upload set. During multi-artifact uploads it shows progress, and after success it prints a short completion summary plus a verification hint while still returning result objects for automation. + ## EXAMPLES ### EXAMPLE 1 @@ -87,10 +94,10 @@ Uploads the explicitly selected package files instead of discovering them from t ### EXAMPLE 6 ```powershell -PS> Deploy-NovaPackage -Repository LocalNexus -WhatIf +PS> Deploy-NovaPackage -PackageType @('NuGet', 'Zip') -Repository LocalNexus ``` -Previews which package artifacts would be uploaded and which destination URLs would be used. +Uploads both matching `.nupkg` and `.zip` artifacts, shows progress as each artifact is sent, and prints a short completion summary with a suggested verification step. ### EXAMPLE 7 @@ -102,130 +109,138 @@ Uses PowerShell's native confirmation prompt for the full resolved upload set be ## PARAMETERS -### -PackagePath +### -AuthenticationScheme -Optional explicit package file path list. When omitted, the command resolves matching artifacts from the configured package output directory. +Optional authentication scheme prefix used when formatting the resolved authentication header value. ```yaml -Type: System.String[] +Type: System.String DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -PackageType +### -Confirm -Optional package type filter. Supported values follow the same normalization as `Package.Types`, including `NuGet`, -`Zip`, `.nupkg`, and `.zip`. +Prompts for confirmation before uploading package artifacts. ```yaml -Type: System.String[] -DefaultValue: '' +Type: System.Management.Automation.SwitchParameter +DefaultValue: False SupportsWildcards: false -Aliases: [ ] +Aliases: +- cf ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -Url +### -Headers -Explicit raw upload base URL. This takes precedence over repository or package configuration. +Optional additional HTTP headers. These are merged with `Package.Headers` and repository-specific headers. +Optional additional HTTP headers. +These are merged with `Package.Headers` and repository-specific headers. ```yaml -Type: System.String +Type: System.Collections.Hashtable DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -Repository +### -PackagePath -Repository name to resolve from `Package.Repositories`. +Optional explicit package file path list. When omitted, the command resolves matching artifacts from the configured package output directory. +Optional explicit package file path list. +When omitted, the command resolves matching artifacts from the configured package output directory. ```yaml -Type: System.String +Type: System.String[] DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -UploadPath +### -PackageType -Optional extra path segment appended between the resolved base URL and the uploaded package file name. +Optional package type filter. Supported values follow the same normalization as `Package.Types`, including `NuGet`, +`Zip`, `.nupkg`, and `.zip`. +Optional package type filter. +Supported values follow the same normalization as `Package.Types`, including `NuGet`, +`Zip`, `.nupkg`, and `.zip`. ```yaml -Type: System.String +Type: System.String[] DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -Headers +### -Repository -Optional additional HTTP headers. These are merged with `Package.Headers` and repository-specific headers. +Repository name to resolve from `Package.Repositories`. ```yaml -Type: System.Collections.Hashtable +Type: System.String DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` @@ -237,16 +252,16 @@ Optional explicit token value used to populate the resolved authentication heade Type: System.String DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` @@ -258,89 +273,93 @@ Optional environment variable name that holds the upload token. Type: System.String DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -AuthenticationScheme +### -UploadPath -Optional authentication scheme prefix used when formatting the resolved authentication header value. +Optional extra path segment appended between the resolved base URL and the uploaded package file name. ```yaml Type: System.String DefaultValue: '' SupportsWildcards: false -Aliases: [ ] +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -WhatIf +### -Url -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Explicit raw upload base URL. This takes precedence over repository or package configuration. +Explicit raw upload base URL. +This takes precedence over repository or package configuration. ```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: False +Type: System.String +DefaultValue: '' SupportsWildcards: false -Aliases: - - wi +Aliases: [] ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` -### -Confirm +### -WhatIf -Prompts for confirmation before uploading package artifacts. +Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: System.Management.Automation.SwitchParameter DefaultValue: False SupportsWildcards: false Aliases: - - cf +- wi ParameterSets: - - Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false DontShow: false -AcceptedValues: [ ] +AcceptedValues: [] HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, -`-InformationVariable`, `-OutBuffer`, `-OutVariable`, `-PipelineVariable`, `-ProgressAction`, `-Verbose`, -`-WarningAction`, `-WarningVariable`, `-WhatIf`, and `-Confirm`. +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -363,5 +382,5 @@ If no upload target can be resolved, `Deploy-NovaPackage` fails fast with a clea ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/New-NovaModulePackage.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md +- [New-NovaModulePackage](./New-NovaModulePackage.md) +- [Publish-NovaModule](./Publish-NovaModule.md) diff --git a/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md b/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md index 9f6beab3..3674e6c6 100644 --- a/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md +++ b/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/project-json-reference.html' Locale: en-US Module Name: NovaModuleTools ms.date: 05/06/2026 @@ -50,6 +50,9 @@ When you use `-Version`, the command returns only the project version string ins When you use `-Installed`, the command returns the installed `NovaModuleTools` module name and version string instead of project metadata. +When `-Path` does not resolve to an existing project root folder, or the folder does not contain `project.json`, +the command fails with an actionable error that tells you how to recover. + ## EXAMPLES ### EXAMPLE 1 @@ -185,10 +188,13 @@ Returned by default. The object includes project metadata, defaulted build setti This command throws a clear error when `project.json` is missing or empty. +If `-Path` points to a file or a folder that does not exist, `Get-NovaProjectInfo` tells you to rerun it from a +Nova project root or pass `-Path` to the folder that contains `project.json`. + `-Installed` does not require a project path or a `project.json` file. ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Test-NovaBuild](./Test-NovaBuild.md) +- [Update-NovaModuleVersion](./Update-NovaModuleVersion.md) diff --git a/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md b/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md index 16309cc1..65b0d666 100644 --- a/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md +++ b/docs/NovaModuleTools/en-US/Get-NovaUpdateNotificationPreference.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/versioning-and-updates.html#notification-preferences' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -32,6 +32,11 @@ The same stored preference is also used by `Update-NovaModuleTool` (alias: `Upda Stable self-updates remain available and do not require prerelease eligibility. +If no settings file exists yet, the command reports the default behavior: prerelease self-updates are enabled and +stable self-updates remain available. + +Use `% nova notification` when you want the CLI-oriented view of the same preference. + ## EXAMPLES ### EXAMPLE 1 @@ -44,6 +49,15 @@ Shows whether prerelease self-updates are currently enabled, whether stable self ### EXAMPLE 2 +```text +PS> Get-NovaUpdateNotificationPreference -Verbose +``` + +Shows the current status and writes a short explanation that tells you whether Nova is using a stored settings file +or the built-in default. + +### EXAMPLE 3 + ```text PS> Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications PS> Get-NovaUpdateNotificationPreference @@ -77,10 +91,14 @@ Use `Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications` to st Use `Set-NovaUpdateNotificationPreference -EnablePrereleaseNotifications` to allow prerelease self-updates again. +Use `-Verbose` when you want a short explanation of whether Nova is reading a stored preference or falling back to +the default. + When prerelease notifications are enabled again, `Update-NovaModuleTool` / `Update-NovaModuleTools` may again select a prerelease target. Prerelease self-updates still require explicit confirmation before the update proceeds, and that confirmation defaults to `No` so pressing Enter cancels the update. ## RELATED LINKS -- `Invoke-NovaBuild` -- `Set-NovaUpdateNotificationPreference` -- `Update-NovaModuleTool` +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Set-NovaUpdateNotificationPreference](./Set-NovaUpdateNotificationPreference.md) +- [Install-NovaCli](./Install-NovaCli.md) +- [Update-NovaModuleTool](./Update-NovaModuleTools.md) diff --git a/docs/NovaModuleTools/en-US/Initialize-NovaModule.md b/docs/NovaModuleTools/en-US/Initialize-NovaModule.md index ae42d956..7c396754 100644 --- a/docs/NovaModuleTools/en-US/Initialize-NovaModule.md +++ b/docs/NovaModuleTools/en-US/Initialize-NovaModule.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/core-workflows.html#scaffold' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -45,6 +45,8 @@ Use `-Example` when you want the scaffold to start from the packaged example pro This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the scaffold target after the interactive answers have been collected, without creating folders, writing `project.json`, or initializing Git. +During scaffold creation, Nova shows progress for the main setup phases and finishes with the created project root plus the next cmdlet to run. + ## EXAMPLES ### EXAMPLE 1 @@ -150,7 +152,9 @@ Generated projects start with NovaModuleTools defaults for recursive discovery, `-WhatIf` and `-Confirm` support. +Press `Ctrl+C` during the interactive prompt flow if you want to cancel before Nova creates the scaffold. + ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) diff --git a/docs/NovaModuleTools/en-US/Install-NovaCli.md b/docs/NovaModuleTools/en-US/Install-NovaCli.md index 3a0bb0bf..35647ec3 100644 --- a/docs/NovaModuleTools/en-US/Install-NovaCli.md +++ b/docs/NovaModuleTools/en-US/Install-NovaCli.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/commands.html#setup-and-project' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -30,7 +30,8 @@ PS> Install-NovaCli [[-DestinationDirectory] ] [-Force] [-WhatIf] [-Conf By default, the launcher is installed to `~/.local/bin/nova` on macOS and Linux. If that directory is not on your `PATH`, the command warns so you can update your shell profile. -After a successful install, `Install-NovaCli` also prints the release notes link from the installed module manifest. +After a successful install, `Install-NovaCli` prints the installed launcher path, suggests the next command to run, +and also prints the release notes link from the installed module manifest. Use this command when you want `nova` to be available directly from your shell as the launcher-oriented CLI entrypoint. @@ -168,8 +169,13 @@ Returns the installed command name, destination directory, installed path, and w ## NOTES -After running `Install-NovaCli`, add the destination directory to your shell `PATH` if needed. +`Install-NovaCli` currently supports macOS and Linux. On Windows, use `Invoke-NovaCli` from `pwsh` after importing +NovaModuleTools. + +After running `Install-NovaCli`, add the destination directory to your shell `PATH` if needed, start a new shell, +and then run `nova --help` to confirm the launcher is available. ## RELATED LINKS -- `Publish-NovaModule` +- [Update-NovaModuleTool](./Update-NovaModuleTools.md) +- [Publish-NovaModule](./Publish-NovaModule.md) diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md b/docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md new file mode 100644 index 00000000..351f34f1 --- /dev/null +++ b/docs/NovaModuleTools/en-US/Invoke-NovaAgenticCopilotScaffold.md @@ -0,0 +1,211 @@ +--- +document type: cmdlet +external help file: NovaModuleTools-Help.xml +HelpUri: 'https://www.novamoduletools.com/core-workflows.html#agentic-copilot' +Locale: en-US +Module Name: NovaModuleTools +ms.date: 05/20/2026 +PlatyPS schema version: 2024-05-01 +title: Invoke-NovaAgenticCopilotScaffold +--- + +# Invoke-NovaAgenticCopilotScaffold + +## SYNOPSIS + +Apply or refresh Nova's managed Agentic Copilot scaffold in an existing project. + +## SYNTAX + +### __AllParameterSets + +```text +Invoke-NovaAgenticCopilotScaffold [[-Path] ] [-ShortName] [-OverrideWarning] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +`Invoke-NovaAgenticCopilotScaffold` applies Nova's maintained Agentic Copilot scaffold to an existing project root. + +The command reads `ProjectName` and `Description` from the target `project.json`, requires a `ShortName` on every run for token replacement, and refreshes only Nova-managed Agentic Copilot paths. Existing `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are preserved and are created only when they are missing. + +By default the workflow shows an overwrite warning before it updates the managed scaffold paths. Use `-OverrideWarning` only when you intentionally want a non-interactive apply or refresh. + +The target path must contain a valid `project.json`. Invalid project metadata or an invalid short name stops the command with a clear validation error. + +During apply or refresh, Nova shows progress for the main scaffold phases and ends with the project root plus the next suggested review and validation steps. + +## EXAMPLES + +### EXAMPLE 1 + +```text +PS> Invoke-NovaAgenticCopilotScaffold -ShortName NMT +``` + +Apply or refresh the Nova-managed Agentic Copilot scaffold in the current project root after the overwrite warning is confirmed. + +### EXAMPLE 2 + +```text +PS> Invoke-NovaAgenticCopilotScaffold -Path ~/Work/MyModule -ShortName NMT -OverrideWarning +``` + +Apply or refresh the managed scaffold in a specific project root without showing the overwrite warning prompt. + +### EXAMPLE 3 + +```text +PS> Invoke-NovaAgenticCopilotScaffold -ShortName NMT -WhatIf +``` + +Preview the managed scaffold apply workflow without writing or overwriting files. + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OverrideWarning + +Skip the overwrite warning prompt and continue directly with the managed scaffold apply or refresh workflow. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Project root that contains the existing `project.json` file. Defaults to the current location. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ShortName + +Short placeholder name used in generated guidance tokens such as `Invoke-*`. Use a value that starts with a letter and contains only letters or numbers. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Runs the command in a mode that only reports what would happen without performing the actions. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +You can't pipe objects to this cmdlet. + +## OUTPUTS + +### None + +This cmdlet does not emit an output object. + +## NOTES + +This workflow does not persist `ShortName` to `project.json` and does not infer it from any existing scaffold files. It refreshes only these Nova-managed paths: + +- `.github/agents/` +- `.github/instructions/` +- `.github/prompts/` +- `.github/skills/` +- `.github/copilot-instructions.md` +- `.github/pull_request_template.md` +- `AGENTS.md` +- `CONTRIBUTING.md` + +`README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are created only when they are missing. + +Press `Ctrl+C` before confirming the overwrite warning if you want to cancel the apply without changing files. + +## RELATED LINKS + +- [Initialize-NovaModule](./Initialize-NovaModule.md) +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md b/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md index 4a20df7a..1dffe62c 100644 --- a/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md +++ b/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/core-workflows.html#build' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -29,6 +29,8 @@ PS> Invoke-NovaBuild [-ContinuousIntegration] [-OverrideWarning] [-WhatIf] [-Con This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the build target without clearing `dist/` or generating new build output. +During a real build, Nova shows progress for the main build phases and ends with the output module directory plus the next suggested validation step. + Use `-ContinuousIntegration` when the same PowerShell session needs to keep using the freshly built `dist/` module after the build completes. In CI/self-hosting flows, that re-activates the built module before the command returns. Use `-OverrideWarning` only when you intentionally want to continue a build even though a file under `src/public` @@ -62,7 +64,7 @@ If `Preamble` is configured, those lines are written at the very top of the gene PS> Invoke-NovaBuild ``` -Builds the current project into `dist//`. +Builds the current project into `dist//`, prints the output module directory, and suggests `Test-NovaBuild` as the next validation step. ### EXAMPLE 2 @@ -70,7 +72,7 @@ Builds the current project into `dist//`. PS> Invoke-NovaBuild -Verbose ``` -Builds the current project and writes verbose progress for the build workflow. +Builds the current project, shows phase progress for the build workflow, and writes verbose details from the underlying build helpers. ### EXAMPLE 3 @@ -172,9 +174,11 @@ When `-ContinuousIntegration` is used together with a real build, the command re Files under `src/public` are expected to contain exactly one top-level function each. Use `-OverrideWarning` only when you intentionally want to bypass that guard for the current build. +Use `Ctrl+C` if you need to stop a running build before all phases complete. + ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) +- [Test-NovaBuild](./Test-NovaBuild.md) +- [Publish-NovaModule](./Publish-NovaModule.md) +- [Update-NovaModuleTool](./Update-NovaModuleTools.md) diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaCli.md b/docs/NovaModuleTools/en-US/Invoke-NovaCli.md new file mode 100644 index 00000000..5ebe9a78 --- /dev/null +++ b/docs/NovaModuleTools/en-US/Invoke-NovaCli.md @@ -0,0 +1,191 @@ +--- +document type: cmdlet +external help file: NovaModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: NovaModuleTools +ms.date: 05/24/2026 +PlatyPS schema version: 2024-05-01 +title: Invoke-NovaCli +--- + +# Invoke-NovaCli + +## SYNOPSIS + +Runs Nova's launcher-style command routing from PowerShell. + +## SYNTAX + +### __AllParameterSets + +```text +PS> Invoke-NovaCli [[-Command] ] [[-Arguments] ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +`Invoke-NovaCli` is the PowerShell entrypoint behind the launcher-style `nova ` workflow. + +Use this cmdlet when you want Nova's routed CLI experience from inside PowerShell, including root help, per-command help, and the routed command surfaces such as `build`, `test`, `package`, `publish`, `release`, `update`, and `notification`. + +When `-Command` is omitted or blank, Nova falls back to the root CLI help. + +This cmdlet forwards `-WhatIf` and `-Confirm` semantics to the routed command surface instead of treating `Invoke-NovaCli` itself as the mutating operation owner. + +Use `Get-Help Invoke-NovaCli -Full` when you want the PowerShell wrapper help. Use `nova --help`, `nova --help`, or `nova --help ` when you want launcher-native CLI help. + +## EXAMPLES + +### EXAMPLE 1 + +```text +PS> Invoke-NovaCli +``` + +Shows the root Nova CLI help. + +### EXAMPLE 2 + +```text +PS> Invoke-NovaCli build --help +``` + +Shows the short help for the routed `build` command by using launcher-style arguments from PowerShell. + +### EXAMPLE 3 + +```text +PS> Invoke-NovaCli --help build +``` + +Shows the long help for the routed `build` command. + +### EXAMPLE 4 + +```text +PS> Invoke-NovaCli publish --repository PSGallery --api-key -WhatIf +``` + +Previews the routed publish workflow without changing files or publishing artifacts. + +## PARAMETERS + +### -Arguments + +Pass the remaining launcher-style arguments for the routed command. + +Use CLI syntax here, for example `--help`, `--verbose`, `--what-if`, or route-specific flags such as `--repository`. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: + - Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: true +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Command + +Choose the routed Nova command to run, for example `build`, `test`, `package`, `publish`, `release`, `notification`, `update`, or the root help/version forms such as `--help` and `--version`. + +When this parameter is omitted or blank, Nova shows the root CLI help. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: + - Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Forward confirmation behavior to routed mutating commands that support Nova's CLI confirmation flow. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: + - cf +ParameterSets: + - Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Forward preview behavior to routed commands that support Nova's non-destructive preview flow. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: + - wi +ParameterSets: + - Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +You can't pipe objects to this cmdlet. + +## OUTPUTS + +### System.Object + +This cmdlet returns the routed command result or CLI help text for help and version requests. + +## NOTES + +`Invoke-NovaCli` is a PowerShell wrapper around Nova's launcher-style command routing. The routed command surfaces keep CLI syntax such as `--help`, `--verbose`, and `--what-if`. + +Use `Ctrl+C` if you need to cancel a running routed workflow. + +## RELATED LINKS + +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Test-NovaBuild](./Test-NovaBuild.md) +- [Install-NovaCli](./Install-NovaCli.md) +- [NovaModuleTools Module](./NovaModuleTools.md) diff --git a/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md b/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md index 352a37aa..30f32bb3 100644 --- a/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md +++ b/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/packaging-and-delivery.html#release' Locale: en-US Module Name: NovaModuleTools ms.date: 05/03/2026 @@ -57,6 +57,8 @@ When local release mode is selected, the resolved local publish target is previe This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the entire release workflow and resolved publish target without building, testing, versioning, or publishing. +During the workflow, Nova shows progress for the main release phases. When the workflow completes, Nova prints the publish target and a short next-step hint. In `-WhatIf` mode, Nova ends with a release-plan summary instead of a release-complete message. + ## EXAMPLES ### EXAMPLE 1 @@ -323,9 +325,11 @@ When `-ContinuousIntegration` is used, the release workflow restores the built ` `Invoke-NovaRelease` uses `SupportsShouldProcess`, so `Get-Help Invoke-NovaRelease -Full` surfaces native `-WhatIf` and `-Confirm` support. +Use `Ctrl+C` if you need to stop a running release before all phases complete. + ## RELATED LINKS -- `Invoke-NovaBuild` -- `Test-NovaBuild` -- `Update-NovaModuleVersion` -- `Publish-NovaModule` +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Test-NovaBuild](./Test-NovaBuild.md) +- [Update-NovaModuleVersion](./Update-NovaModuleVersion.md) +- [Publish-NovaModule](./Publish-NovaModule.md) diff --git a/docs/NovaModuleTools/en-US/New-NovaModulePackage.md b/docs/NovaModuleTools/en-US/New-NovaModulePackage.md index 257971bd..772b4baf 100644 --- a/docs/NovaModuleTools/en-US/New-NovaModulePackage.md +++ b/docs/NovaModuleTools/en-US/New-NovaModulePackage.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/packaging-and-delivery.html#pack' Locale: en-US Module Name: NovaModuleTools ms.date: 04/26/2026 @@ -35,6 +35,8 @@ Use `-OverrideWarning` only when you intentionally want the nested build to cont The package is written to `artifacts/packages/` by default. You can override generic package metadata through the optional `Package` section in `project.json`. +During a packaging run, Nova shows progress for the build-validation phase and the artifact-creation phase. When packaging completes, Nova prints the package target together with the next suggested step. In `-WhatIf` mode, Nova ends with a package-plan summary instead of a package-created summary. + Use this `project.json` shape when you want to control package types and the package output directory: ```json @@ -275,7 +277,9 @@ When `-SkipTests` is used, only `Test-NovaBuild` is skipped. Build still runs. Files under `src/public` are expected to contain exactly one top-level function each. `-OverrideWarning` bypasses that guard only for the current packaging run. +Use `Ctrl+C` if you need to stop a running packaging workflow before the package artifacts are created. + ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Test-NovaBuild](./Test-NovaBuild.md) diff --git a/docs/NovaModuleTools/en-US/NovaModuleTools.md b/docs/NovaModuleTools/en-US/NovaModuleTools.md index 840c2a44..0dd02f5d 100644 --- a/docs/NovaModuleTools/en-US/NovaModuleTools.md +++ b/docs/NovaModuleTools/en-US/NovaModuleTools.md @@ -32,6 +32,10 @@ Shows whether prerelease update notifications are enabled. Stable release notifi Installs the bundled command-line launcher into a user command directory on macOS or Linux. +### `PS> Invoke-NovaCli` + +Runs Nova's launcher-style command routing from inside PowerShell. + ### `PS> Invoke-NovaBuild` Builds the current NovaModuleTools project into a ready-to-import PowerShell module. diff --git a/docs/NovaModuleTools/en-US/Publish-NovaModule.md b/docs/NovaModuleTools/en-US/Publish-NovaModule.md index a9271e4b..2fd8e6c9 100644 --- a/docs/NovaModuleTools/en-US/Publish-NovaModule.md +++ b/docs/NovaModuleTools/en-US/Publish-NovaModule.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/packaging-and-delivery.html#publish' Locale: en-US Module Name: NovaModuleTools ms.date: 04/26/2026 @@ -45,10 +45,12 @@ Use `-ContinuousIntegration` when the same CI/self-hosting session should switch Use `-OverrideWarning` only when you intentionally want the nested build to continue even though a file under `src/public` contains zero or multiple top-level functions. -This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the resolved publish target and workflow without building, testing, or publishing. +This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` when you want the normal build-validation flow to run but the nested publish step to stay in preview mode. Use `-Confirm` when you want PowerShell to prompt before the publish workflow starts. +During a publish run, Nova shows progress for the build-validation phase, the publish phase, the local import phase when applicable, and the CI restore phase when `-ContinuousIntegration` is used. When the run completes, Nova prints the publish target together with the next suggested verification step. In `-WhatIf` mode, Nova ends with a publish-plan summary instead of a publish-completed summary. + ## EXAMPLES ### EXAMPLE 1 @@ -89,7 +91,7 @@ Prompts before the repository publish workflow starts. PS> Publish-NovaModule -Local -WhatIf ``` -Previews the local publish workflow and target directory without making changes. No module copy or import happens when `-WhatIf` is used. +Runs the normal build-validation flow, then previews the local publish target directory without copying or importing the module. ### EXAMPLE 6 @@ -300,8 +302,10 @@ When `-ContinuousIntegration` is used, Nova restores the built `dist/` module af `Publish-NovaModule` uses `SupportsShouldProcess`, so `Get-Help Publish-NovaModule -Full` should surface native `-WhatIf` and `-Confirm` support. +Use `Ctrl+C` if you need to stop a running publish workflow before the publish step finishes. + ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Test-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Test-NovaBuild](./Test-NovaBuild.md) +- [Invoke-NovaRelease](./Invoke-NovaRelease.md) diff --git a/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md b/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md index c84effb2..be8b3ee7 100644 --- a/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md +++ b/docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/versioning-and-updates.html#notification-preferences' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -38,6 +38,8 @@ The same stored preference is also used by `Update-NovaModuleTool` (alias: `Upda Stable self-updates remain available and do not require prerelease eligibility. +When the preference changes, Nova prints the settings file path together with the next recommended verification command. In `-WhatIf` mode, Nova ends with a preview summary instead of writing the preference file. + ## EXAMPLES ### EXAMPLE 1 @@ -46,7 +48,7 @@ Stable self-updates remain available and do not require prerelease eligibility. PS> Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications ``` -Turns off prerelease self-update eligibility and restricts `Update-NovaModuleTool` to stable releases only. +Turns off prerelease self-update eligibility, keeps stable releases available, and suggests `Get-NovaUpdateNotificationPreference` as the next verification step. ### EXAMPLE 2 @@ -55,7 +57,7 @@ PS> Set-NovaUpdateNotificationPreference -EnablePrereleaseNotifications ``` Turns prerelease self-update eligibility back on, which allows `Update-NovaModuleTool` / -`Update-NovaModuleTools` to consider a prerelease target again. +`Update-NovaModuleTools` to consider a prerelease target again and suggests `Get-NovaUpdateNotificationPreference` as the next verification step. ### EXAMPLE 3 @@ -63,7 +65,7 @@ Turns prerelease self-update eligibility back on, which allows `Update-NovaModul PS> Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications -WhatIf ``` -Previews the change that would disable prerelease self-update eligibility. +Previews the change that would disable prerelease self-update eligibility without writing the settings file. ### EXAMPLE 4 @@ -195,7 +197,9 @@ Returns the current prerelease self-update state, the always-available stable-up Use this command together with `Get-NovaUpdateNotificationPreference` when you want to confirm the stored setting. +Use `-WhatIf` or `-Confirm` when you want an easy way to preview or stop the change before the settings file is updated. + ## RELATED LINKS -- `Get-NovaUpdateNotificationPreference` -- `Update-NovaModuleTool` +- [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md) +- [Update-NovaModuleTool](./Update-NovaModuleTools.md) diff --git a/docs/NovaModuleTools/en-US/Test-NovaBuild.md b/docs/NovaModuleTools/en-US/Test-NovaBuild.md index cf54b51c..e2a51466 100644 --- a/docs/NovaModuleTools/en-US/Test-NovaBuild.md +++ b/docs/NovaModuleTools/en-US/Test-NovaBuild.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/core-workflows.html#test' Locale: en-US Module Name: NovaModuleTools ms.date: 04/26/2026 @@ -40,6 +40,8 @@ With the default This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the planned test run and XML output path without creating `artifacts/` or invoking Pester. +During a test run, Nova shows progress for the optional pre-test build, test-result preparation, the Pester run, result writing, and code-coverage validation. When tests pass, Nova prints the result file path, a coverage summary when one is available, and a suggested next step. In `-WhatIf` mode, Nova ends with a test-plan summary instead of invoking Pester. + ## EXAMPLES ### EXAMPLE 1 @@ -48,7 +50,7 @@ This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShoul PS> Test-NovaBuild ``` -Runs the Pester tests for the current project. +Runs the Pester tests for the current project and prints the result file path plus the next suggested command when the run succeeds. ### EXAMPLE 2 @@ -56,7 +58,7 @@ Runs the Pester tests for the current project. PS> Test-NovaBuild -Build ``` -Builds the project first, then runs the configured Pester test workflow. +Builds the project first, then runs the configured Pester test workflow with the same completion summary as a normal test run. ### EXAMPLE 3 @@ -88,7 +90,7 @@ Overrides the console output settings for the current test run while keeping col PS> Test-NovaBuild -WhatIf ``` -Previews the planned Pester run without executing tests or writing `artifacts/TestResults.xml`. +Previews the planned Pester run, prints the planned result file path, and does not execute tests or write `artifacts/TestResults.xml`. ### EXAMPLE 7 @@ -96,7 +98,7 @@ Previews the planned Pester run without executing tests or writing `artifacts/Te PS> Test-NovaBuild -Build -WhatIf ``` -Previews the build-before-test workflow without rebuilding the project or running Pester. +Previews the build-before-test workflow, including the planned result file path and configured coverage target, without rebuilding the project or running Pester. ## PARAMETERS @@ -258,8 +260,10 @@ If `project.json` configures `Pester.CodeCoverage.CoveragePercentTarget`, `Test- `Test-NovaBuild` uses `SupportsShouldProcess`, so `Get-Help Test-NovaBuild -Full` surfaces native `-WhatIf` and `-Confirm` support. +Use `Ctrl+C` if you need to stop a running test workflow before Pester completes. + ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Publish-NovaModule.md +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Publish-NovaModule](./Publish-NovaModule.md) diff --git a/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md b/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md index e73fc390..2b4bda46 100644 --- a/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md +++ b/docs/NovaModuleTools/en-US/Update-NovaModuleTools.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/versioning-and-updates.html#self-update' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -38,7 +38,9 @@ When prerelease notifications are enabled, `Update-NovaModuleTool` may target a Stable updates do not require prerelease confirmation. -After a successful update, `Update-NovaModuleTool` prints the release notes link from the installed module manifest. +When a newer version is available, `Update-NovaModuleTool` shows progress while it installs the update and reads the release-notes link from the updated module. Every command path ends with a visible summary: up-to-date, preview, cancelled, or updated. + +After a successful update, `Update-NovaModuleTool` prints the release notes link from the installed module manifest and suggests `Get-NovaProjectInfo -Installed` as the next verification step. ## EXAMPLES @@ -48,7 +50,7 @@ After a successful update, `Update-NovaModuleTool` prints the release notes link PS> Update-NovaModuleTool ``` -Updates the installed `NovaModuleTools` module by using the stored prerelease preference to resolve the update candidate. +Updates the installed `NovaModuleTools` module by using the stored prerelease preference to resolve the update candidate, then prints the current version, target version, and the next suggested verification step. ### EXAMPLE 2 @@ -76,13 +78,13 @@ Successful updates print the release notes link from the installed module manife PS> Update-NovaModuleTool -WhatIf ``` -Previews the resolved update action without running `Update-Module`. +Previews the resolved update action without prompting for prerelease confirmation or running `Update-Module`. ## PARAMETERS ### -WhatIf -Shows what would happen if the cmdlet runs. `Update-NovaModuleTool` resolves the target version first, then previews the selected stable or prerelease update action without changing the installed module. +Shows what would happen if the cmdlet runs. `Update-NovaModuleTool` resolves the target version first, then previews the selected stable or prerelease update action without prompting for prerelease confirmation or changing the installed module. ```yaml Type: System.Management.Automation.SwitchParameter @@ -147,8 +149,11 @@ If the PowerShell Gallery cannot be reached well enough to resolve an update can Use `Get-NovaUpdateNotificationPreference` and `Set-NovaUpdateNotificationPreference` to inspect or change the stored prerelease setting. +Use `Ctrl+C` if you need to stop an active self-update before `Update-Module` finishes. + ## RELATED LINKS -- `Get-NovaUpdateNotificationPreference` -- `Set-NovaUpdateNotificationPreference` -- `Invoke-NovaBuild` +- [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md) +- [Set-NovaUpdateNotificationPreference](./Set-NovaUpdateNotificationPreference.md) +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) diff --git a/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md b/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md index dfba2f23..989e0977 100644 --- a/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md +++ b/docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md @@ -1,7 +1,7 @@ --- document type: cmdlet external help file: NovaModuleTools-Help.xml -HelpUri: '' +HelpUri: 'https://www.novamoduletools.com/versioning-and-updates.html#bump' Locale: en-US Module Name: NovaModuleTools ms.date: 04/25/2026 @@ -43,7 +43,7 @@ When Git tags exist, only commits since the latest tag are considered. If Git-ba If the repository exists but has no commits yet, the command stops with: `Cannot bump version because the repository has no commits yet. Create an initial commit first.` -This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the calculated release label and the exact next version without changing the stored version. +This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the calculated release label and the exact next version without changing the stored version. The command now ends with a clear plan, cancellation, or success summary, prints the resolved version file plus the detected/applied release label, and suggests the next step to run. Use `-ContinuousIntegration` when the same session should first re-activate the built `dist/` module before the version bump workflow starts. This is useful in CI/self-hosting flows where an earlier command changed the active module state. @@ -58,7 +58,7 @@ When the current version is already a prerelease for the selected release line, PS> Update-NovaModuleVersion ``` -Updates the version in the current project using the release label inferred from recent commit messages. +Updates the version in the current project using the release label inferred from recent commit messages, then prints the version file plus the next suggested validation step. ### EXAMPLE 2 @@ -81,7 +81,7 @@ Label: Minor CommitCount: 12 ``` -Shows the calculated version update without modifying `project.json`. +Shows the calculated version update without modifying `project.json`, then ends with a version-update plan summary and a reminder to rerun without `-WhatIf` when you are ready to write the new version. ### EXAMPLE 4 @@ -111,7 +111,7 @@ Label: Minor CommitCount: 12 ``` -Shows how `-Preview` keeps the detected semantic label for reporting but deterministically enters the next patch preview track when the current version is stable. +Shows how `-Preview` keeps the detected semantic label for reporting but deterministically enters the next patch preview track when the current version is stable, while the plan summary still points to the exact next version that would be written. ### EXAMPLE 6 @@ -165,7 +165,7 @@ Label: Major CommitCount: 34 ``` -Shows how stable `0.y.z` bumps still warn that `1.0.0` must be set manually when the API becomes stable, while breaking-change commits on that line continue to plan the next minor version instead of jumping straight to `1.0.0`. +Shows how stable `0.y.z` bumps still warn that `1.0.0` must be set manually when the API becomes stable, while breaking-change commits on that line continue to plan the next minor version instead of jumping straight to `1.0.0`. The plan output also keeps both the detected and applied release labels visible. ### EXAMPLE 10 @@ -303,6 +303,6 @@ When Git-based inference is unavailable, `Update-NovaModuleVersion` now requires ## RELATED LINKS -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md -- https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaRelease.md +- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md) +- [Invoke-NovaBuild](./Invoke-NovaBuild.md) +- [Invoke-NovaRelease](./Invoke-NovaRelease.md) diff --git a/docs/assets/site.css b/docs/assets/site.css index 958fc032..f652c0d0 100644 --- a/docs/assets/site.css +++ b/docs/assets/site.css @@ -11,7 +11,7 @@ --outline: rgba(255, 255, 255, 0.12); --shadow: 0 20px 60px rgba(0, 0, 0, 0.28); --radius: 22px; - --max-width: none; + --max-width: 1600px; --anchor-offset: 2.90rem; } diff --git a/docs/commands.html b/docs/commands.html index 5e8b8637..c9e4f198 100644 --- a/docs/commands.html +++ b/docs/commands.html @@ -208,6 +208,52 @@

Start a new project

See the scaffold guide

+
+

Apply or refresh the copilot workflow

+ +
+

Cmdlet: Invoke-NovaAgenticCopilotScaffold

+
+

Add Nova's maintained Agentic Copilot workflow to an existing project, or + refresh an older Nova-managed scaffold to the current version.

+
    +
  • Use when: the project already exists and you want Nova to add or refresh + the managed Agentic guidance files without recreating the scaffold +
    • +
  • Requires: a valid project.json and an explicit short name + on every run for placeholders such as Invoke-<ShortName>*
    • + +
  • Common parameters: + -ShortName, -Path, -WhatIf, and + -OverrideWarning
    • +
  • Default safety: Nova prompts before overwriting the managed scaffold + paths and only creates README.md, CHANGELOG.md, and + RELEASE_NOTE.md when they are missing +
    • +
+
+
+

Apply the managed scaffold

+

Showing: PowerShell

+
+ +
+ 
PS> Invoke-NovaAgenticCopilotScaffold -ShortName NMT
+PS> Invoke-NovaAgenticCopilotScaffold -Path ~/Work/MyModule -ShortName NMT -OverrideWarning
+
+
+

See the copilot apply + guide

+
+

Inspect the current project