diff --git a/.github/PSModule.yml b/.github/PSModule.yml index abf5f13..4dadc2e 100644 --- a/.github/PSModule.yml +++ b/.github/PSModule.yml @@ -1,24 +1,18 @@ -# This file is used to configure the Process-PSModule workflow. -# Reference: -# - https://github.com/PSModule/Process-PSModule?tab=readme-ov-file#configuration +# Repository overrides for Process-PSModule. +# https://psmodule.io/Process-PSModule/reference/settings/ + +ImportantFilePatterns: + - '^src/' + - '^README\.md$' + - '^tests/' + - '^\.github/PSModule\.yml$' + - '^\.github/workflows/' + - '^\.github/linters/' + - '^\.github/zensical\.toml$' Test: CodeCoverage: PercentTarget: 80 -# TestResults: -# Skip: true -# SourceCode: -# Skip: true -# PSModule: -# Skip: true -# Module: -# Windows: -# Skip: true -# MacOS: -# Skip: true -# Build: -# Docs: -# Skip: true Linter: env: diff --git a/.github/mkdocs.yml b/.github/mkdocs.yml deleted file mode 100644 index df5e17a..0000000 --- a/.github/mkdocs.yml +++ /dev/null @@ -1,75 +0,0 @@ -site_name: -{{ REPO_NAME }}- -theme: - name: material - language: en - font: - text: Roboto - code: Sono - logo: Assets/icon.png - favicon: Assets/icon.png - palette: - # Palette toggle for automatic mode - - media: "(prefers-color-scheme)" - toggle: - icon: material/link - name: Switch to dark mode - # Palette toggle for dark mode - - media: '(prefers-color-scheme: dark)' - scheme: slate - toggle: - primary: black - accent: green - icon: material/toggle-switch-off-outline - name: Switch to light mode - # Palette toggle for light mode - - media: '(prefers-color-scheme: light)' - scheme: default - toggle: - primary: indigo - accent: green - icon: material/toggle-switch - name: Switch to system preference - icon: - repo: material/github - features: - - navigation.instant - - navigation.instant.progress - - navigation.indexes - - navigation.top - - navigation.tracking - - navigation.expand - - search.suggest - - search.highlight - -repo_name: -{{ REPO_OWNER }}-/-{{ REPO_NAME }}- -repo_url: https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}- - -plugins: - - search - -markdown_extensions: - - toc: - permalink: true # Adds a link icon to headings - - attr_list - - admonition - - md_in_html - - pymdownx.details # Enables collapsible admonitions - -extra: - social: - - icon: fontawesome/brands/discord - link: https://discord.gg/jedJWCPAhD - name: -{{ REPO_OWNER }}- on Discord - - icon: fontawesome/brands/github - link: https://github.com/-{{ REPO_OWNER }}-/ - name: -{{ REPO_OWNER }}- on GitHub - consent: - title: Cookie consent - description: >- - We use cookies to recognize your repeated visits and preferences, as well - as to measure the effectiveness of our documentation and whether users - find what they're searching for. With your consent, you're helping us to - make our documentation better. - actions: - - accept - - reject diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..2838f16 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ + + + + + + +--- +
+Technical details + + + +
+ +
+Relevant issues (or links) + + + +
diff --git a/.github/workflows/Process-PSModule.yml b/.github/workflows/Process-PSModule.yml index 1181c77..01fb159 100644 --- a/.github/workflows/Process-PSModule.yml +++ b/.github/workflows/Process-PSModule.yml @@ -29,7 +29,7 @@ permissions: jobs: Process-PSModule: - uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8 + uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@105e4dcefe1946782066aa50a5c7d3658319895a # v8.0.7 secrets: PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }} GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }} diff --git a/.github/zensical.toml b/.github/zensical.toml new file mode 100644 index 0000000..b860b80 --- /dev/null +++ b/.github/zensical.toml @@ -0,0 +1,112 @@ +# Zensical configuration +# https://zensical.org/docs/setup/basics/ + +[project] +site_name = "Fonts" +site_url = "https://psmodule.io/Fonts/" +docs_dir = "docs" +repo_name = "PSModule/Fonts" +repo_url = "https://github.com/PSModule/Fonts" + +[project.theme] +language = "en" +font.text = "Mona Sans" +font.code = "Source Code Pro" +logo = "Assets/icon.png" +favicon = "Assets/icon.png" +features = [ + "announce.dismiss", + "content.code.annotate", + "content.code.copy", + "content.tooltips", + "navigation.expand", + "navigation.footer", + "navigation.indexes", + "navigation.instant", + "navigation.instant.prefetch", + "navigation.instant.preview", + "navigation.instant.progress", + "navigation.tabs", + "navigation.top", + "navigation.tracking", + "search.highlight", + "search.share", + "search.suggest", + "toc.follow", +] + +[project.theme.icon] +repo = "material/github" +link = "material/link-variant" + +[[project.theme.palette]] +media = "(prefers-color-scheme)" +toggle.icon = "lucide/sun-moon" +toggle.name = "Switch to dark mode" + +[[project.theme.palette]] +media = "(prefers-color-scheme: dark)" +scheme = "slate" +primary = "black" +accent = "light blue" +toggle.icon = "lucide/moon" +toggle.name = "Switch to light mode" + +[[project.theme.palette]] +media = "(prefers-color-scheme: light)" +scheme = "default" +primary = "black" +accent = "light blue" +toggle.icon = "lucide/sun" +toggle.name = "Switch to system preference" + +[project.plugins.meta] + +[project.plugins.search] + +[project.markdown_extensions.toc] +permalink = "#" + +[project.markdown_extensions.attr_list] + +[project.markdown_extensions.abbr] + +[project.markdown_extensions.admonition] + +[project.markdown_extensions.def_list] + +[project.markdown_extensions.footnotes] + +[project.markdown_extensions.md_in_html] + +[project.markdown_extensions.tables] + +[project.markdown_extensions.pymdownx.details] + +[project.markdown_extensions.pymdownx.superfences] +custom_fences = [ + { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }, +] + +[project.markdown_extensions.pymdownx.tasklist] +custom_checkbox = true + +[[project.extra.social]] +icon = "fontawesome/brands/discord" +link = "https://discord.psmodule.io" +name = "PSModule on Discord" + +[[project.extra.social]] +icon = "fontawesome/brands/github" +link = "https://github.com/PSModule/" +name = "PSModule on GitHub" + +[project.extra.consent] +title = "Cookie consent" +description = """ +We use cookies to recognize your repeated visits and preferences, as well +as to measure the effectiveness of our documentation and whether users +find what they're searching for. With your consent, you're helping us to +make our documentation better. +""" +actions = ["accept", "reject"] diff --git a/.gitignore b/.gitignore index 8af6555..04c9ff7 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ # PSModule framework outputs folder outputs/* +/.PSModule/ # .Net build output bin/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..67d5ed8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# Agent guidance + +Fonts is a PowerShell module for listing, installing, and uninstalling fonts on Windows, Linux, and macOS. + +Read [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md), then follow the canonical +[Process-PSModule guidance](https://psmodule.io/Process-PSModule/), including its +[repository standard](https://psmodule.io/Process-PSModule/reference/repository-standard/) and +[PowerShell module standard](https://psmodule.io/Process-PSModule/reference/powershell-module-standard/). + +The approved [PowerShell 5.1 compatibility exception](CONTRIBUTING.md#powershell-51-compatibility-exception) +takes precedence over the framework's latest-LTS-only policy. Follow the contribution guide's test-isolation rules +to keep local checks away from real font directories and registry entries. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3f07d74 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Claude Code + +@AGENTS.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..cd804dd --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all +individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, +neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or +religion, national or social origin, socio-economic position, level of education, or other status. The same privileges +of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive +behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, +background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our +shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors +are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any + clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group + of people. +3. **Stereotyping or discrimination.** Characterizing anyone's personality or behavior on the basis of immutable + identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context + or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade + enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms + of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any + other restricted behaviors. + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict +represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help +avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. To report a possible violation, email +[support@psmodule.io](mailto:support@psmodule.io). + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. +They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing +witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent +as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are +carried out in private with the involved parties, but communicating to the whole community may be part of a mutually +agreed upon resolution. + +## Addressing and Repairing Harm + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following +enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals +involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1. Warning + - Event: A violation involving a single incident or series of incidents. + - Consequence: A private, written warning from the Community Moderators. + - Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking + clarification on expectations. +2. Temporarily Limited Activities + - Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a + more serious violation. + - Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness + of the situation and give the community members involved time to process the incident. The cooldown period may be + limited to particular communication channels or interactions with particular community members. + - Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and + impact, and being thoughtful about re-entering community spaces after the period is over. +3. Temporary Suspension + - Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, + or a single serious violation. + - Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions + give the person being suspended time to reflect upon their behavior and possible corrective actions. + - Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for + return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4. Permanent Ban + - Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, + or a violation so serious that the Community Moderators determine there is no way to keep the community safe + with this person as a member. + - Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans + should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through + other remedies has failed to change the behavior. + - Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their +discretion and judgment, in keeping with the best interests of our community. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing +the community in public or other spaces. Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at +[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. +To view a copy of this license, visit +[https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/). + +For answers to common questions about Contributor Covenant, see the FAQ at +[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). +Translations are provided at +[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). +Additional enforcement and community guideline resources can be found at +[https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). +The enforcement ladder was inspired by the work of +[Mozilla's code of conduct team](https://github.com/mozilla/inclusion). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..31a1ebf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing + +Fonts welcomes bug reports, feature requests, documentation improvements, and code contributions. +Read the [README](README.md), search [existing issues](https://github.com/PSModule/Fonts/issues), and open an issue +when you need to report a problem or discuss a change. Include the module version, PowerShell version, operating system, +expected and actual behavior, and steps to reproduce the problem. Remove secrets and personal information from logs. + +Follow the [code of conduct](CODE_OF_CONDUCT.md). Use the private reporting route in [SECURITY.md](SECURITY.md) for +security vulnerabilities and [SUPPORT.md](SUPPORT.md) for support questions. + +## Making a change + +1. Start a focused branch from `main`. +2. Follow the canonical [repository standard](https://psmodule.io/Process-PSModule/reference/repository-standard/) + and [PowerShell module standard](https://psmodule.io/Process-PSModule/reference/powershell-module-standard/), + subject to the PowerShell compatibility exception below. +3. Keep module source under `src/`, behavioral tests under `tests/`, and realistic usage examples under `examples/`. + Declare external module dependencies with `#Requires -Modules` in the function files that use them. + The build collects those declarations into the compiled manifest; do not add `RequiredModules` to `src/manifest.psd1`. +4. Add or update tests and comment-based help for changed behavior. Test files use + `#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.1.0'; MaximumVersion = '6.*' }`. +5. Run the relevant checks in an isolated environment as described below, then open a draft pull request against `main`. + Describe the user-facing outcome and include validation results and any unavailable platform checks. + Push focused commits and address review feedback before a maintainer moves the pull request to ready for review. + +The [MSX contribution workflow](https://msx.no/docs/Ways-of-Working/Contribution-Workflow/) and +[PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) provide the shared review and pull request conventions. + +## PowerShell 5.1 compatibility exception + +Fonts retains Windows PowerShell 5.1 support and `PowerShellVersion = '5.1'` in `src/manifest.psd1`. +This is an explicitly approved repository exception to Process-PSModule's latest-LTS-only runtime policy. +Framework and template upgrades must preserve this minimum runtime and existing module behavior. + +Keep shipped source compatible with Windows PowerShell 5.1 and its .NET Framework APIs. +Do not introduce PowerShell Core-only syntax or APIs, remove Desktop support, or raise the manifest's minimum version +as part of framework alignment. Any change to this compatibility commitment requires a separate, explicit decision. + +Build tools and Pester tests follow the current framework's tooling requirements; those requirements do not change +the module's supported runtime. Current-PowerShell parsing, static compatibility checks, and the normal cross-platform +pipeline are useful checks, but they do not prove execution on Windows PowerShell 5.1. +When changing shipped code, verify the built module's import and affected commands with Windows PowerShell 5.1 +on an isolated Windows host. Report unavailable minimum-runtime validation explicitly. + +## Validation and font safety + +[Process-PSModule](https://psmodule.io/Process-PSModule/guides/calling-the-workflow/) runs the repository's build, +source checks, module tests, coverage checks, and documentation build. Repository overrides live in `.github/PSModule.yml`; +the coverage target is 80%. Important-file patterns include source, README, tests, workflow/settings files, linter settings, +and the Zensical site configuration. + +The existing `tests/Fonts.Tests.ps1` suite installs and uninstalls fonts. Run it only on a disposable runner or with the +built module's font-folder and registry boundaries redirected to test-owned temporary locations. +Isolate registry operations and font-cache refreshes as needed for the platform. Do not point local tests at your real +user or system font folders, and do not run them elevated on a normal workstation. +Preserve installed fonts and restore any test-specific mappings after the run. + +Use the [module-test guide](https://psmodule.io/Process-PSModule/guides/writing-module-tests/) for Pester discovery and +test setup. Structural checks such as `git diff --check` and `actionlint .github/workflows/Process-PSModule.yml` +do not require font installation. + +The documentation site uses `.github/zensical.toml`. The workflow stages generated command help, the README, and the icon +under `.PSModule/site/docs`, then builds the staged configuration with Zensical. +Keep generated `.PSModule/` artifacts out of commits. diff --git a/README.md b/README.md index 22e2735..684089e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ please review the [NerdFonts](https://github.com/PSModule/NerdFonts) and [Google ## Supported platforms This module supports managing fonts on Linux, macOS and Windows operating systems. +The minimum PowerShell version is 5.1, including Windows PowerShell 5.1. ## Installation @@ -72,17 +73,12 @@ This will remove the font from the `C:\Windows\Fonts` folder and update the regi Uninstall-Font -Name 'FontName' -Scope AllUsers # You can tab complete the font name ``` -## Contributing +## Documentation -Coder or not, you can contribute to the project! We welcome all contributions. +Documentation is published at [psmodule.io/Fonts](https://psmodule.io/Fonts/). +Use PowerShell help for command details and examples: -### For Users - -If you don't code, you still sit on valuable information that can make this project even better. If you experience that the -product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests. -Please see the issues tab on this project and submit a new issue that matches your needs. - -### For Developers - -If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information. -You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement. +```powershell +Get-Command -Module Fonts +Get-Help -Name Install-Font -Examples +``` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a4d3056 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security policy + +## Supported versions + +Security fixes target the latest Fonts release and the current `main` branch. +Fixes are not backported to older module versions. The module's Windows PowerShell 5.1 compatibility commitment is +documented in [CONTRIBUTING.md](CONTRIBUTING.md#powershell-51-compatibility-exception). + +## Reporting a vulnerability + +Do not disclose a suspected or confirmed vulnerability through a public issue, pull request, discussion, or other +public channel. + +Use [private vulnerability reporting](https://github.com/PSModule/Fonts/security/advisories/new) in this repository's +**Security** tab when it is available. If that option is unavailable, email +[security@psmodule.io](mailto:security@psmodule.io). + +Use the same private routes to report accidentally exposed sensitive information, credentials, secrets, and weak or +unsafe security controls or configurations. + +Include the affected version or commit, the vulnerability and its impact, steps to reproduce it, and any proof of +concept or suggested mitigation. PSModule handles reports privately, investigates them, and coordinates remediation +and disclosure with the reporter. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..c0c997b --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,18 @@ +# Support + +For help with Fonts: + +1. Read the [README](README.md), [module documentation](https://psmodule.io/Fonts/), and PowerShell command help. +2. Search [existing issues](https://github.com/PSModule/Fonts/issues) for a known answer. +3. Open an issue in this repository for a public question, bug report, or feature request. + +Include the module and PowerShell versions, operating system, expected and actual behavior, reproduction steps, +and sanitized logs. Remove credentials, personal information, and other secrets before posting. + +Private support matters go to [support@psmodule.io](mailto:support@psmodule.io). + +## Sensitive reports + +Report security vulnerabilities through the private routes in the [security policy](SECURITY.md). +Report community conduct concerns through the private route in the [code of conduct](CODE_OF_CONDUCT.md). +To propose a change, follow the [contribution guide](CONTRIBUTING.md).