diff --git a/.all-contributorsrc b/.all-contributorsrc index bf2e668c..53f76239 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -3569,6 +3569,15 @@ "contributions": [ "content" ] + }, + { + "login": "thesurenk", + "name": "Suren K", + "avatar_url": "https://avatars.githubusercontent.com/u/902972?v=4", + "profile": "https://surenk.com", + "contributions": [ + "doc" + ] } ] } diff --git a/README.md b/README.md index c3c5e4c1..9c735c9f 100644 --- a/README.md +++ b/README.md @@ -535,6 +535,7 @@ Thanks goes to these wonderful people ([emoji key](./CONTRIBUTING.md#contributor
Lovy Jain
kimtth
Akash Dwivedi +
Suren K diff --git a/agents/workshop-ta.agent.md b/agents/workshop-ta.agent.md index 03738c6a..9dbaead7 100644 --- a/agents/workshop-ta.agent.md +++ b/agents/workshop-ta.agent.md @@ -106,14 +106,23 @@ Use `signal-write` when something needs the operator's attention: ### Viewing signals -If the Workshop's canvas extension (🪨 Cairn) is installed — it -ships bundled with the-workshop plugin — the operator can open a -live dashboard showing every desk's signals, score bars, and -escalations. The canvas reads `desks/*/.signals/` for the latest -signal JSON per desk. +The Workshop has a canvas extension — **🪨 Cairn** — that shows a live dashboard +of every desk's signals, score bars, and escalations. It reads +`desks/*/.signals/` for the latest signal JSON per desk. -Without the canvas, you can still read signals by scanning the -`.signals/` directories directly and summarizing for the operator. +The canvas does **not** auto-load when the plugin is installed. To see the live +board, install and register the `signals-dashboard` extension separately. If the +operator asks you to "run cairn" / "open the dashboard" and it isn't already +showing: + +1. Install the `signals-dashboard` canvas extension. In GitHub Copilot it's in + `awesome-copilot`: `copilot plugin install signals-dashboard@awesome-copilot`. + (It also ships in the the-workshop repo at + `.github/extensions/signals-dashboard/` for other setups.) +2. Open the **🪨 Cairn** canvas once it's registered. + +Without the canvas, you can still read signals by scanning the `.signals/` +directories directly and summarizing for the operator. ### Partnership signals diff --git a/cookbook/cookbook.yml b/cookbook/cookbook.yml index 0134ebb7..cc1542d9 100644 --- a/cookbook/cookbook.yml +++ b/cookbook/cookbook.yml @@ -103,3 +103,17 @@ cookbooks: - copilot-sdk - web-app - community + - id: copilot-sdk-java-examples + name: Copilot SDK Java Examples + description: A web-based chat application built with the GitHub Copilot Java SDK, Jetty, with auth status, JSON API, chat, and CLI connectivity examples + external: true + url: https://github.com/thesurenk/github-copilot-java-examples + author: + name: thesurenk + url: https://github.com/thesurenk + tags: + - java + - copilot-sdk + - web-app + - cli + - community diff --git a/docs/README.skills.md b/docs/README.skills.md index b7dcac28..3f7f8cad 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -40,6 +40,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [ai-prompt-engineering-safety-review](../skills/ai-prompt-engineering-safety-review/SKILL.md)
`gh skills install github/awesome-copilot ai-prompt-engineering-safety-review` | Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content. | None | | [ai-ready](../skills/ai-ready/SKILL.md)
`gh skills install github/awesome-copilot ai-ready` | Make any repo AI-ready — analyzes your codebase and generates AGENTS.md, copilot-instructions.md, CI workflows, issue templates, and more. Mines your PR review patterns and creates files customized to your stack. USE THIS SKILL when the user asks to "make this repo ai-ready", "set up AI config", or "prepare this repo for AI contributions". | None | | [ai-team-orchestration](../skills/ai-team-orchestration/SKILL.md)
`gh skills install github/awesome-copilot ai-team-orchestration` | Bootstrap and run a multi-agent AI development team. Use when: starting a new software project with AI agents, setting up parallel dev/QA teams, creating sprint plans, writing brainstorm prompts with distinct agent voices, recovering a project workflow, or planning sprints. | `references/anti-patterns.md`
`references/brainstorm-format.md`
`references/project-brief-template.md`
`references/sprint-plan-template.md` | +| [anti-ui-slop](../skills/anti-ui-slop/SKILL.md)
`gh skills install github/awesome-copilot anti-ui-slop` | Stop Codex, GitHub Copilot, Claude Code, and Cursor from shipping generic UI. Use UIZZE’s public catalogue of 800,000+ real web and iOS screens to extract product-specific design decisions and enforce a hard finish gate for web and iOS interfaces. | None | | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md)
`gh skills install github/awesome-copilot appinsights-instrumentation` | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`
`examples`
`references/ASPNETCORE.md`
`references/AUTO.md`
`references/NODEJS.md`
`references/PYTHON.md`
`scripts/appinsights.ps1` | | [apple-appstore-reviewer](../skills/apple-appstore-reviewer/SKILL.md)
`gh skills install github/awesome-copilot apple-appstore-reviewer` | Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons. | None | | [arch-linux-triage](../skills/arch-linux-triage/SKILL.md)
`gh skills install github/awesome-copilot arch-linux-triage` | Triage and resolve Arch Linux issues with pacman, systemd, and rolling-release best practices. | None | @@ -92,6 +93,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [cloud-design-patterns](../skills/cloud-design-patterns/SKILL.md)
`gh skills install github/awesome-copilot cloud-design-patterns` | Cloud design patterns for distributed systems architecture covering 42 industry-standard patterns across reliability, performance, messaging, security, and deployment categories. Use when designing, reviewing, or implementing distributed system architectures. | `references/architecture-design.md`
`references/azure-service-mappings.md`
`references/best-practices.md`
`references/deployment-operational.md`
`references/event-driven.md`
`references/messaging-integration.md`
`references/performance.md`
`references/reliability-resilience.md`
`references/security.md` | | [code-exemplars-blueprint-generator](../skills/code-exemplars-blueprint-generator/SKILL.md)
`gh skills install github/awesome-copilot code-exemplars-blueprint-generator` | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | None | | [code-tour](../skills/code-tour/SKILL.md)
`gh skills install github/awesome-copilot code-tour` | Use this skill to create CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: "create a tour", "make a code tour", "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour", "architecture tour", "explain how X works", "vibe check", "PR review tour", "contributor guide", "help someone ramp up", or any request for a structured walkthrough through code. Supports 20 developer personas (new joiner, bug fixer, architect, PR reviewer, vibecoder, security reviewer, and more), all CodeTour step types (file/line, selection, pattern, uri, commands, view), and tour-level fields (ref, isPrimary, nextTour). Works with any repository in any language. | `references/codetour-schema.json`
`references/examples.md`
`scripts/generate_from_docs.py`
`scripts/validate_tour.py` | +| [codebase-memory-mcp](../skills/codebase-memory-mcp/SKILL.md)
`gh skills install github/awesome-copilot codebase-memory-mcp` | Use when a configured codebase-memory-mcp server can assist with graph-backed code discovery, architecture orientation, symbol lookup, callers and callees, dependency or data-flow tracing, impact analysis, unfamiliar modules, or an explicit Codebase Memory request. | None | | [codeql](../skills/codeql/SKILL.md)
`gh skills install github/awesome-copilot codeql` | Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis. | `references/alert-management.md`
`references/cli-commands.md`
`references/compiled-languages.md`
`references/sarif-output.md`
`references/troubleshooting.md`
`references/workflow-configuration.md` | | [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md)
`gh skills install github/awesome-copilot comment-code-generate-a-tutorial` | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None | | [commit-message-storyteller](../skills/commit-message-storyteller/SKILL.md)
`gh skills install github/awesome-copilot commit-message-storyteller` | Analyzes git diffs or staged changes and generates narrative commit messages that explain WHY a change was made, not just what changed — following Conventional Commits format. Use when asked to "write a commit message", "generate a commit", "describe my changes", "what should I commit this as", "commit this", "summarize my diff", or "help me commit". Works with git diff output, staged files, or plain descriptions of changes. | `references/conventional-commits-guide.md` | @@ -226,6 +228,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [issue-fields-migration](../skills/issue-fields-migration/SKILL.md)
`gh skills install github/awesome-copilot issue-fields-migration` | Bulk-migrate metadata to GitHub issue fields from two sources: repo labels (e.g. priority labels to a Priority field) and Project V2 fields. Use when users say "migrate my labels to issue fields", "migrate project fields to issue fields", "convert labels to issue fields", "copy project field values to issue fields", or ask about adopting issue fields. Issue fields are org-level typed metadata (single select, text, number, date) that replace label-based workarounds with structured, searchable, cross-repo fields. | `references/issue-fields-api.md`
`references/labels-api.md`
`references/projects-api.md` | | [java-add-graalvm-native-image-support](../skills/java-add-graalvm-native-image-support/SKILL.md)
`gh skills install github/awesome-copilot java-add-graalvm-native-image-support` | GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best practices. | None | | [java-docs](../skills/java-docs/SKILL.md)
`gh skills install github/awesome-copilot java-docs` | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. | None | +| [java-helidon](../skills/java-helidon/SKILL.md)
`gh skills install github/awesome-copilot java-helidon` | Get best practices for developing applications with Helidon 4 (SE and MP). Use when working with Helidon SE or Helidon MP, HttpService routing, Helidon DB Client, MicroProfile Config, Helidon Security, or Helidon testing in Java 21+ projects. | None | | [java-junit](../skills/java-junit/SKILL.md)
`gh skills install github/awesome-copilot java-junit` | Get best practices for JUnit 5 unit testing, including data-driven tests | None | | [java-mcp-server-generator](../skills/java-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot java-mcp-server-generator` | Generate a complete Model Context Protocol server project in Java using the official MCP Java SDK with reactive streams and optional Spring Boot integration. | None | | [java-refactoring-extract-method](../skills/java-refactoring-extract-method/SKILL.md)
`gh skills install github/awesome-copilot java-refactoring-extract-method` | Refactoring using Extract Methods in Java Language | None | @@ -240,6 +243,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [lsp-setup](../skills/lsp-setup/SKILL.md)
`gh skills install github/awesome-copilot lsp-setup` | Enable code intelligence (go-to-definition, find-references, hover, type info) for any programming language by installing and configuring an LSP server for Copilot CLI. Detects the OS, installs the right server, and generates the JSON configuration (user-level or repo-level). Use when you need deeper code understanding and no LSP server is configured, or when the user asks to set up, install, or configure an LSP server. | `references/lsp-servers.md` | | [make-repo-contribution](../skills/make-repo-contribution/SKILL.md)
`gh skills install github/awesome-copilot make-repo-contribution` | All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. | `assets/issue-template.md`
`assets/pr-template.md` | | [markdown-to-html](../skills/markdown-to-html/SKILL.md)
`gh skills install github/awesome-copilot markdown-to-html` | Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors. | `references/basic-markdown-to-html.md`
`references/basic-markdown.md`
`references/code-blocks-to-html.md`
`references/code-blocks.md`
`references/collapsed-sections-to-html.md`
`references/collapsed-sections.md`
`references/gomarkdown.md`
`references/hugo.md`
`references/jekyll.md`
`references/marked.md`
`references/pandoc.md`
`references/tables-to-html.md`
`references/tables.md`
`references/writing-mathematical-expressions-to-html.md`
`references/writing-mathematical-expressions.md` | +| [markstream-install](../skills/markstream-install/SKILL.md)
`gh skills install github/awesome-copilot markstream-install` | Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, and Vue 2 applications. Use for package selection, minimal peer dependencies, CSS order, SSR boundaries, streaming mode, and renderer setup. | `references/scenarios.md` | | [mcp-cli](../skills/mcp-cli/SKILL.md)
`gh skills install github/awesome-copilot mcp-cli` | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None | | [mcp-copilot-studio-server-generator](../skills/mcp-copilot-studio-server-generator/SKILL.md)
`gh skills install github/awesome-copilot mcp-copilot-studio-server-generator` | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support | None | | [mcp-create-adaptive-cards](../skills/mcp-create-adaptive-cards/SKILL.md)
`gh skills install github/awesome-copilot mcp-create-adaptive-cards` | Skill converted from mcp-create-adaptive-cards.prompt.md | None | @@ -397,6 +401,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md)
`gh skills install github/awesome-copilot update-markdown-file-index` | Update a markdown file section with an index/table of files from a specified folder. | None | | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | +| [vcpkg](../skills/vcpkg/SKILL.md)
`gh skills install github/awesome-copilot vcpkg` | Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md). | `references/ci.md`
`references/registries.md`
`references/troubleshooting.md` | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-commands` | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-localization` | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | diff --git a/skills/anti-ui-slop/SKILL.md b/skills/anti-ui-slop/SKILL.md new file mode 100644 index 00000000..fa73c462 --- /dev/null +++ b/skills/anti-ui-slop/SKILL.md @@ -0,0 +1,107 @@ +--- +name: anti-ui-slop +description: 'Stop Codex, GitHub Copilot, Claude Code, and Cursor from shipping generic UI. Use UIZZE’s public catalogue of 800,000+ real web and iOS screens to extract product-specific design decisions and enforce a hard finish gate for web and iOS interfaces.' +--- + +# Anti UI Slop + +Use this skill when building, refactoring, or reviewing a web or iOS interface. The goal is not to make a generic layout prettier. The goal is to make the interface visibly belong to this product, support its real user job, and behave correctly in every important state. + +The workflow is instruction-only. It does not execute third-party code or require credentials. + +## 1. Inspect the Product Before Designing + +Read the repository and identify: + +- the primary user and the job this screen must complete; +- the single primary action and the information needed before taking it; +- the existing component library, design tokens, typography, and layout conventions; +- real product nouns, workflows, constraints, and data already present in the codebase; +- required loading, empty, error, partial, success, disabled, and permission states; +- relevant mobile, tablet, desktop, keyboard, and assistive-technology behavior. + +Do not invent product requirements, analytics, user research, or hidden states. + +## 2. Collect Real Interface Evidence + +Search the public catalogue at https://uizze.com and select three to five relevant web or iOS screens. Prefer references that match the target workflow, information density, navigation model, or interaction pattern—not merely its industry or color palette. + +For each reference, record: + +1. the screen or flow and its source link; +2. the structural decision worth transferring; +3. why that decision fits this product; +4. what must not be copied. + +Transfer hierarchy, workflow shape, density, navigation, control behavior, responsive treatment, and state handling. Never copy another product’s branding, proprietary text, imagery, or exact layout. + +If catalogue browsing is unavailable, ask the user for two or three UIZZE links or screenshots. If they cannot provide them, continue from repository evidence and label the missing reference evidence explicitly. + +## 3. Write a Design Contract + +Before changing code, write a short contract with these fields: + +| Field | Decision | +| --- | --- | +| Screen job | The one outcome this screen enables | +| Primary user and action | Who acts, and what they do | +| Content hierarchy | What must be understood first, second, and third | +| Navigation and controls | Product-specific structure and interaction model | +| Visual language | Type, spacing, density, surfaces, imagery, and motion rules | +| Required states | Loading, empty, error, partial, success, disabled, permission | +| Responsive behavior | What changes across supported widths and input modes | +| Evidence used | Reference links and transferable decisions | +| Forbidden defaults | Generic patterns that would erase product specificity | +| Acceptance criteria | Observable conditions required before shipping | + +The contract must name concrete choices. “Clean,” “modern,” “intuitive,” and “premium” are not design decisions. + +## 4. Build in the Product’s Language + +- Reuse the repository’s components and semantic tokens before adding new ones. +- Make the primary action visually and structurally obvious. +- Use product-specific labels and information rather than placeholder metrics or generic copy. +- Keep repeated cards only when the content is genuinely a repeated collection. +- Add decoration, motion, badges, or elevation only when they communicate state or hierarchy. +- Implement every required interaction and state; do not leave convincing-looking inert controls. +- Preserve accessibility semantics, focus order, contrast, touch targets, and reduced-motion behavior. + +## 5. Run the Finish Gate + +Render the result at every supported breakpoint and block completion when any item fails: + +### Product specificity + +- Could this interface belong to an unrelated product after changing the logo? +- Does the hierarchy reflect the real user job and product data? +- Are there interchangeable dashboard cards, filler metrics, vague headings, or generic calls to action? + +### Interaction completeness + +- Do all visible controls have a real outcome? +- Are loading, empty, error, success, disabled, and permission states implemented where applicable? +- Are destructive, irreversible, or sensitive actions confirmed appropriately? + +### Responsive and accessible behavior + +- Does the layout remain usable without merely stacking every region vertically? +- Do keyboard navigation, focus visibility, semantics, contrast, and touch targets pass inspection? +- Does content remain readable at zoom and with longer real-world text? + +### Design-system integrity + +- Are local tokens and components used consistently? +- Is every new visual rule justified by the design contract? +- Is borrowed evidence transformed into this product’s own visual language? + +Fix every blocking failure and re-run the gate before declaring the UI complete. + +## 6. Handoff Format + +Report the finished work in this order: + +1. **Evidence:** the references and decisions that influenced the result. +2. **Contract:** the final product-specific design rules. +3. **Implementation:** the meaningful interface and behavior changes. +4. **Verification:** breakpoints, interaction states, and accessibility checks performed. +5. **Remaining risks:** anything that could not be verified, without overstating completion. diff --git a/skills/codebase-memory-mcp/SKILL.md b/skills/codebase-memory-mcp/SKILL.md new file mode 100644 index 00000000..4ad3a7e1 --- /dev/null +++ b/skills/codebase-memory-mcp/SKILL.md @@ -0,0 +1,27 @@ +--- +name: codebase-memory-mcp +description: 'Use when a configured codebase-memory-mcp server can assist with graph-backed code discovery, architecture orientation, symbol lookup, callers and callees, dependency or data-flow tracing, impact analysis, unfamiliar modules, or an explicit Codebase Memory request.' +--- + +# Codebase Memory MCP + +Use the configured Codebase Memory graph as a discovery accelerator, not as the sole source of truth. Confirm graph-derived conclusions with source snippets or local files before editing code or making strong claims. + +## Workflow + +1. Discover the Codebase Memory tools exposed by the current MCP client; clients may prefix or rename tool namespaces. +2. Call `list_projects` when available and use the exact indexed project name. If the repository is not indexed, continue with local exploration or ask before calling `index_repository` when graph access is important. +3. Before branch-sensitive or edit-sensitive conclusions, use `index_status` or `detect_changes` when available. After a branch switch, assume the index may be stale until checked. If freshness cannot be established, disclose that limitation and verify locally. +4. Use `get_architecture` once for orientation in an unfamiliar repository or subsystem. Do not repeat it for narrow follow-up questions. +5. Use `search_graph` for definitions, implementations, routes, classes, interfaces, callers, and related symbols. Prefer a natural-language query for discovery and a name or qualified-name pattern for known symbols. Narrow by label or path, set a result limit, and paginate or reduce scope when the response reports more results. +6. Use `search_code` or normal repository search for literal strings, configuration keys, test identifiers, error messages, and non-code files. Do not turn a precise text lookup into a broad graph query. +7. After graph search, use `get_code_snippet` with the returned qualified name. If source snippets are unavailable, open the local file before relying on the result. +8. Use `trace_path` for callers, callees, dependency paths, data flow, cross-service paths, and impact analysis. Include tests only when test coverage is part of the question. +9. Use `get_graph_schema` before `query_graph`. Reserve custom queries for multi-hop or aggregate questions that simpler tools cannot answer, and apply `LIMIT` or the tool's row limit. +10. When graph and checked-out source disagree, treat source as current and report likely index drift. + +## Safety and Fallbacks + +- Do not install Codebase Memory or another third-party skill from this workflow. +- Do not call `delete_project`, ingest traces, update ADRs, or index a repository unless the user explicitly requested or approved the action; announce it before execution. +- Fall back to normal repository exploration when the MCP server, project, index, or required capability is unavailable; do not invent tool results or stop a task that can be completed safely without the graph. diff --git a/skills/java-helidon/SKILL.md b/skills/java-helidon/SKILL.md new file mode 100644 index 00000000..0b654dac --- /dev/null +++ b/skills/java-helidon/SKILL.md @@ -0,0 +1,435 @@ +--- +name: java-helidon +description: 'Get best practices for developing applications with Helidon 4 (SE and MP). Use when working with Helidon SE or Helidon MP, HttpService routing, Helidon DB Client, MicroProfile Config, Helidon Security, or Helidon testing in Java 21+ projects.' +--- + +# Helidon Best Practices + +Your goal is to help me write high-quality Helidon applications by following established best practices. + +## Helidon 3 → 4 API changes + +Helidon 4 renamed or resignatured APIs that appear widely in their Helidon 3 form. +The left column does not compile on Helidon 4. Check generated code against this table +before returning it. + +| Do not use (Helidon 3) | Use (Helidon 4) | +| ---------------------------------------------------------- | ------------------------------------------------------------------ | +| `io.helidon.common.http.Http.Status` | `io.helidon.http.Status` | +| `io.helidon.webserver.Service` | `io.helidon.webserver.http.HttpService` | +| `Routing.Rules`, `update(Routing.Rules)` | `HttpRules`, `routing(HttpRules)` | +| `request.path().param("id")` | `request.path().pathParameters().get("id")` | +| `String s = column.as(String.class)` | `column.getString()` or `column.get(String.class)` | +| `dbClient.execute(exec -> ...)` returning `Single`/`Multi` | `dbClient.execute()` returning `Optional` / `Stream` | +| `javax.*` | `jakarta.*` | +| `helidon-microprofile-tests-junit5` | `helidon-microprofile-testing-junit5` | + +`Value.as(Class)` in Helidon 4 returns `OptionalValue`, not `T`. This is the single +most common Helidon 4 compile error in generated code. + +## Project Setup & Structure + +- **Programming Model:** Determine whether the project uses Helidon SE or Helidon MP before generating code. Do not mix the two programming models unless explicitly required. +- **Java Version:** Use Java 21 or later for Helidon 4 applications. +- **Build Tool:** Use Maven (`pom.xml`) or Gradle (`build.gradle`) for dependency management. +- **Dependency Management:** Use the Helidon BOM or platform to keep Helidon module versions aligned. +- **Package Structure:** Organize code by feature or domain, such as `com.example.app.order` and `com.example.app.customer`, rather than only by technical layer. + +## Helidon SE + +- **Explicit Composition:** Construct services and dependencies explicitly in the application bootstrap layer. +- **Constructor Injection:** Pass required dependencies through constructors and declare dependency fields as `private final`. +- **HTTP Services:** Group related routes in focused `HttpService` implementations. +- **Business Logic:** Keep business logic outside route handlers. +- **Virtual Threads:** Prefer straightforward blocking code with Helidon 4 virtual-thread-based request handling. Do not introduce reactive complexity without a clear reason. Helidon 4 is not reactive; do not generate `Single`, `Multi`, or `CompletionStage` chains. + +## Helidon MP + +- **Jakarta and MicroProfile:** Prefer standard Jakarta EE and Eclipse MicroProfile APIs when available. +- **Dependency Injection:** Use CDI with constructor injection for required dependencies. +- **Bean Scopes:** Use CDI scopes such as `@ApplicationScoped` and `@RequestScoped` intentionally. +- **Normal-Scoped Beans:** Add a non-private no-argument constructor to normal-scoped beans that use constructor injection, so the CDI client proxy can be created portably. +- **Business Logic:** Keep Jakarta REST resource classes thin and delegate business operations to service classes. +- **Portability:** Prefer portable Jakarta and MicroProfile APIs over Helidon-specific APIs when portability is important. + +## Configuration + +- **Externalized Configuration:** Store non-secret configuration in `application.yaml` or `application.properties`. +- **Helidon SE Configuration:** Use Helidon Config and pass configuration values or typed configuration objects to components. +- **Helidon MP Configuration:** Use MicroProfile Config for injected application settings. +- **Environment Overrides:** Use environment variables or deployment-specific configuration sources for environment-dependent values. +- **Secrets Management:** Never hardcode credentials, API keys, tokens, or private certificates. + +## Web Layer + +- **DTOs:** Use dedicated request and response models. Do not expose persistence entities directly through APIs. +- **Validation:** Validate path parameters, query parameters, headers, and request bodies before invoking business logic. +- **Status Codes:** Return appropriate HTTP status codes for successful, invalid, unauthorized, forbidden, missing, and failed requests. On `PUT` and `DELETE`, return 404 when the target does not exist rather than succeeding unconditionally. +- **Error Handling:** Use centralized error handling in Helidon SE and Jakarta REST `ExceptionMapper` implementations in Helidon MP. +- **Sensitive Information:** Do not expose stack traces, database details, filesystem paths, or internal exception messages to clients. + +### Helidon SE Example + +Use an `HttpService` to register routes programmatically. Keep request handlers small and delegate business logic to a service. + +```java +import io.helidon.http.Status; +import io.helidon.webserver.http.HttpRules; +import io.helidon.webserver.http.HttpService; +import io.helidon.webserver.http.ServerRequest; +import io.helidon.webserver.http.ServerResponse; + +public final class CustomerHttpService implements HttpService { + + private final CustomerService customerService; + + public CustomerHttpService(CustomerService customerService) { + this.customerService = customerService; + } + + @Override + public void routing(HttpRules rules) { + rules.get("/{id}", this::findById); + } + + private void findById(ServerRequest request, ServerResponse response) { + var id = request.path().pathParameters().get("id"); + + customerService.findById(id) + .ifPresentOrElse( + response::send, + () -> response.status(Status.NOT_FOUND_404).send() + ); + } +} +``` + +Register the HTTP service when constructing the server: + +```java +import io.helidon.webserver.WebServer; + +WebServer server = WebServer.builder() + .routing(routing -> routing.register("/customers", customerHttpService)) + .build() + .start(); +``` + +### Helidon MP Example + +Use Jakarta REST annotations for endpoints and CDI for dependency injection. + +```java +import jakarta.enterprise.context.RequestScoped; +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; + +@Path("/customers") +@RequestScoped +@Produces(MediaType.APPLICATION_JSON) +public class CustomerResource { + + private final CustomerService customerService; + + protected CustomerResource() { + this.customerService = null; + } + + @Inject + public CustomerResource(CustomerService customerService) { + this.customerService = customerService; + } + + @GET + @Path("/{id}") + public Response findById(@PathParam("id") String id) { + return customerService.findById(id) + .map(customer -> Response.ok(customer).build()) + .orElseGet(() -> Response.status(Response.Status.NOT_FOUND).build()); + } +} +``` + +## Service Layer + +- **Transactions:** Define transaction boundaries around complete business operations. +- **Entity Mapping:** Map persistence entities to API models at the service boundary so that service method signatures expose only API models. A service returning `Optional` where the caller expects `Optional` is a common generated-code compile error. +- **Concurrency:** Avoid mutable shared state in application-scoped components unless access is properly coordinated. + +### Helidon SE Example + +Helidon SE services are normally plain Java classes with explicitly supplied dependencies. + +```java +public final class CustomerService { + + private final CustomerRepository customerRepository; + + public CustomerService(CustomerRepository customerRepository) { + this.customerRepository = customerRepository; + } + + public Optional findById(String id) { + if (id == null || id.isBlank()) { + throw new IllegalArgumentException("Customer ID is required"); + } + + return customerRepository.findById(id); + } + + public Customer create(CreateCustomerRequest request) { + if (request.name() == null || request.name().isBlank()) { + throw new IllegalArgumentException("Customer name is required"); + } + + var customer = new Customer(request.id(), request.name().trim()); + + customerRepository.save(customer); + return customer; + } +} +``` + +Construct the dependency graph explicitly: + +```java +var repository = new DbCustomerRepository(dbClient); +var service = new CustomerService(repository); +var httpService = new CustomerHttpService(service); +``` + +### Helidon MP Example + +Use CDI scopes and constructor injection. Apply transactions at the service layer when a business operation changes persistent state. Map the persistence entity to the API model here, so the service never leaks `CustomerEntity` to callers. + +```java +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; +import jakarta.transaction.Transactional; + +@ApplicationScoped +public class CustomerService { + + private final JpaCustomerRepository customerRepository; + + protected CustomerService() { + this.customerRepository = null; + } + + @Inject + public CustomerService(JpaCustomerRepository customerRepository) { + this.customerRepository = customerRepository; + } + + public Optional findById(String id) { + if (id == null || id.isBlank()) { + throw new IllegalArgumentException("Customer ID is required"); + } + + return customerRepository.findById(id) + .map(Customer::fromEntity); + } + + @Transactional + public Customer create(CreateCustomerRequest request) { + if (request.name() == null || request.name().isBlank()) { + throw new IllegalArgumentException("Customer name is required"); + } + + var entity = new CustomerEntity(request.id(), request.name().trim()); + + customerRepository.save(entity); + return Customer.fromEntity(entity); + } +} +``` + +## Data Layer + +- **Database Access:** Use Helidon DB Client, Jakarta Persistence, or another persistence mechanism already established by the project. +- **Parameterized Queries:** Always use parameter binding or prepared statements. Never concatenate untrusted input into SQL. +- **Column Accessors:** Read a typed column value with `column("name").getString()` (or `getInt()`, `getLong()`, and so on) or with `column("name").get(String.class)`. `DbColumn.as(String.class)` returns an `OptionalValue` in Helidon 4, not a `String`. +- **Nullable Columns:** Read nullable columns through `asOptional()` or another optional-aware accessor. Direct `getString()` and similar accessors throw when the column value is null. +- **Row Mapping:** For whole-row mapping, `DbRow.as(Customer.class)` returns the mapped instance directly, but requires a `DbMapper` registered through a `DbMapperProvider` service-loader entry. Prefer explicit column reads for a small number of simple repositories, and introduce a `DbMapper` when the same row shape is mapped in several places. +- **Migrations:** Use a database migration tool for schema changes rather than automatic destructive schema updates. +- **Entity Separation:** Do not expose database entities directly as API contracts. + +### Helidon SE Example + +Use Helidon DB Client with parameterized statements. Map database rows into application models inside the repository. + +```java +import io.helidon.dbclient.DbClient; + +public final class DbCustomerRepository implements CustomerRepository { + + private static final String FIND_BY_ID = + "SELECT id, name FROM customers WHERE id = :id"; + + private static final String INSERT = + "INSERT INTO customers (id, name) VALUES (:id, :name)"; + + private final DbClient dbClient; + + public DbCustomerRepository(DbClient dbClient) { + this.dbClient = dbClient; + } + + @Override + public Optional findById(String id) { + return dbClient.execute() + .createGet(FIND_BY_ID) + .addParam("id", id) + .execute() + .map(row -> new Customer( + row.column("id").getString(), + row.column("name").getString() + )); + } + + @Override + public void save(Customer customer) { + dbClient.execute() + .createInsert(INSERT) + .addParam("id", customer.id()) + .addParam("name", customer.name()) + .execute(); + } +} +``` + +Named statements can also be stored in configuration instead of embedding SQL in Java: + +```yaml +db: + source: "jdbc" + connection: + url: "jdbc:postgresql://localhost:5432/customers" + username: ${DB_USERNAME} + password: ${DB_PASSWORD} + statements: + find-customer-by-id: > + SELECT id, name + FROM customers + WHERE id = :id +``` + +Reference the named statement by name instead of passing SQL text: + +```java +return dbClient.execute() + .createNamedGet("find-customer-by-id") + .addParam("id", id) + .execute() + .map(row -> new Customer( + row.column("id").getString(), + row.column("name").getString() + )); +``` + +### Helidon MP Example + +Use Jakarta Persistence in a CDI-managed repository. Keep transaction boundaries in the service layer. The repository works in entities; the service maps them to API models. + +```java +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.persistence.EntityManager; +import jakarta.persistence.PersistenceContext; + +@ApplicationScoped +public class JpaCustomerRepository { + + @PersistenceContext + private EntityManager entityManager; + + public Optional findById(String id) { + return Optional.ofNullable(entityManager.find(CustomerEntity.class, id)); + } + + public void save(CustomerEntity customer) { + entityManager.persist(customer); + } +} +``` + +Define the persistence entity separately from the public API model: + +```java +import jakarta.persistence.Column; +import jakarta.persistence.Entity; +import jakarta.persistence.Id; +import jakarta.persistence.Table; + +@Entity +@Table(name = "customers") +public class CustomerEntity { + + @Id + private String id; + + @Column(nullable = false) + private String name; + + protected CustomerEntity() { + } + + public CustomerEntity(String id, String name) { + this.id = id; + this.name = name; + } + + public String id() { + return id; + } + + public String name() { + return name; + } +} +``` + +The API model stays free of persistence annotations and owns the mapping: + +```java +public record Customer(String id, String name) { + + public static Customer fromEntity(CustomerEntity entity) { + return new Customer(entity.id(), entity.name()); + } +} +``` + +## Observability + +- **Health:** Use Helidon Health in SE or MicroProfile Health in MP for liveness and readiness checks. +- **Metrics:** Use Helidon Metrics or MicroProfile Metrics for operational and business measurements. +- **Tracing:** Propagate tracing context across inbound and outbound service calls. +- **Cardinality:** Avoid user IDs, request IDs, email addresses, and raw URLs as metric tags. + +## Logging + +- **Logging API:** Use the logging API and implementation configured by the project. +- **Sensitive Information:** Never log passwords, access tokens, authorization headers, cookies, or complete sensitive request bodies. Do not place secrets or personal information in metrics or trace attributes either. + +## Testing + +- **Unit Tests:** Write unit tests for business services using JUnit 5. +- **Helidon SE Tests:** Use `helidon-webserver-testing-junit5` with `@ServerTest` for full server tests and `@RoutingTest` for routing-only tests. These start the server on a dynamically selected port and inject a `Http1Client` bound to it. Never hardcode a port. +- **Helidon MP Tests:** Use `helidon-microprofile-testing-junit5` with `@HelidonTest`, which starts the CDI container and server for the test class. Confirm the artifact coordinates against the Helidon version in use, since this module was renamed across 4.x releases. +- **Testcontainers:** Consider Testcontainers for integration tests using real databases, message brokers, or other infrastructure. +- **Failure Paths:** Test validation failures, missing resources, external-service failures, and authorization failures. + +## Security + +- **Helidon Security:** Use Helidon Security or supported Jakarta and MicroProfile security APIs for authentication and authorization. +- **Authorization:** Enforce permissions at a clear application boundary and deny protected operations by default. +- **JWT and OIDC:** Validate token signatures, issuers, audiences, and expiration times. +- **TLS:** Use TLS for production traffic and verify certificates for outbound connections. +- **CORS:** Configure allowed origins explicitly. Do not combine wildcard origins with credentials. +- **Secrets:** Store secrets in protected environment configuration or a dedicated secret-management system. +- **Outbound Requests:** Validate outbound destinations to reduce server-side request forgery risks. diff --git a/skills/markstream-install/SKILL.md b/skills/markstream-install/SKILL.md new file mode 100644 index 00000000..ffc5d84e --- /dev/null +++ b/skills/markstream-install/SKILL.md @@ -0,0 +1,144 @@ +--- +name: markstream-install +description: 'Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, and Vue 2 applications. Use for package selection, minimal peer dependencies, CSS order, SSR boundaries, streaming mode, and renderer setup.' +license: MIT +compatibility: 'JavaScript or TypeScript frontend project using Vue 3, Nuxt 3/4, Vue 2.6/2.7, React 18+, Next.js, Angular 20+, or Svelte 5.' +metadata: + source: https://github.com/Simon-He95/markstream-vue + documentation: https://markstream.simonhe.me/ +--- + +# Markstream Install + +Integrate the appropriate [Markstream](https://github.com/Simon-He95/markstream-vue) package into an existing application without installing unnecessary optional dependencies or weakening its security defaults. + +Read [references/scenarios.md](references/scenarios.md) before choosing packages or peers. + +## When to Use + +Use this skill when the user asks to: + +- add streaming Markdown rendering to an AI chat or document interface; +- install Markstream in Vue, Nuxt, React, Next.js, Svelte, Angular, or Vue 2; +- repair a broken Markstream installation, missing styles, or SSR failure; +- replace another Markdown renderer with Markstream; +- choose between static, smooth-streaming, and externally parsed AST input. + +## Workflow + +### 1. Inspect the host application + +Before changing dependencies, inspect: + +- the framework and version in `package.json`; +- the package manager lockfile; +- whether the application uses SSR; +- reset, Tailwind, UnoCSS, or design-system styles; +- required optional features: code highlighting, enhanced File/Diff surfaces, Monaco, Mermaid, D2, infographic blocks, or KaTeX. + +Do not assume the Vue package is correct merely because the source repository is named `markstream-vue`. Select the framework-specific package from the scenario table. + +### 2. Install the smallest dependency set + +Install exactly one framework package. Add optional peers only when the requested UI uses their feature. + +Examples: + +```bash +npm install markstream-vue +npm install markstream-react +npm install markstream-svelte +npm install markstream-angular +npm install markstream-vue2 +``` + +Preserve the repository's existing package manager. Do not install every optional peer preemptively. + +### 3. Wire styles in the correct order + +Import application resets before Markstream styles. Import package CSS explicitly; do not rely on component imports to inject it. + +For Tailwind or UnoCSS, use the relevant package subpath in a component layer: + +```css +@import 'markstream-vue/index.css' layer(components); +``` + +Use the matching package name for React, Svelte, Angular, or Vue 2. If math rendering is enabled, also import: + +```css +@import 'katex/dist/katex.min.css'; +``` + +Vue CLI 4 and other Webpack 4-based Vue 2 applications cannot resolve package export maps. In those projects, import the published file directly: + +```ts +import 'markstream-vue2/dist/index.css' +``` + +### 4. Add the smallest working renderer + +Prefer `content` for static documents and most streaming chat interfaces. Markstream's built-in smooth streaming can pace irregular token delivery without requiring the host to maintain an AST. + +For Vue 3 chat surfaces, start with: + +```vue + +``` + +For completed chat history, keep the same renderer mode and switch pacing off: + +```vue + +``` + +In React, Svelte, and Angular, use the equivalent camelCase or framework binding syntax. Keep `smoothStreaming="auto"`, `fade=false`, and `typewriter=true` while streaming; use `smoothStreaming=false` and `typewriter=false` for completed history. + +Use `nodes` plus `final` only when a worker, shared AST store, custom transform, or another application layer already owns parsing. + +### 5. Handle framework-specific boundaries + +- In Nuxt, keep browser-only optional peers behind client boundaries. +- In Next.js, use the root `markstream-react` entry inside a `'use client'` component for live SSE or WebSocket streams. Use `markstream-react/next` for SSR-first HTML with hydration, or `markstream-react/server` for server-only rendering. +- Use `markstream-svelte` only with Svelte 5. +- Confirm the Angular application meets the current `markstream-angular` version requirement. +- In Vue 3, use `mode="chat"` for AI chat, `mode="docs"` for rich documents, and `mode="minimal"` for lightweight non-chat surfaces. +- For long Vue 3 conversations or an existing message virtualizer, consult the Markstream performance guide before adding a second virtualizer. + +### 6. Preserve safe defaults + +HTML policy defaults to `safe`, and Mermaid uses strict mode. Do not broaden either setting unless the user explicitly identifies a trusted legacy surface that requires it. Scope any exception to that surface. + +### 7. Validate + +Run the smallest relevant build, typecheck, or test command. Confirm: + +1. the selected package matches the framework; +2. only requested optional peers were added; +3. styles load after resets; +4. SSR pages do not evaluate browser-only peers on the server; +5. static content and at least one incremental update render correctly. + +Report the selected package, added peers, CSS location, streaming input choice, and validation command. + +## Official References + +- [Installation](https://markstream.simonhe.me/guide/installation) +- [AI chat and streaming](https://markstream.simonhe.me/guide/ai-chat-streaming) +- [Performance](https://markstream.simonhe.me/guide/performance) +- [Troubleshooting](https://markstream.simonhe.me/guide/troubleshooting) +- [Component overrides](https://markstream.simonhe.me/guide/component-overrides) diff --git a/skills/markstream-install/references/scenarios.md b/skills/markstream-install/references/scenarios.md new file mode 100644 index 00000000..aa228594 --- /dev/null +++ b/skills/markstream-install/references/scenarios.md @@ -0,0 +1,42 @@ +# Install Scenarios + +## Package selection + +| Host app | Package | +|----------|---------| +| Vue 3 / Nuxt 3 or 4 | `markstream-vue` | +| Vue 2.6 | `markstream-vue2` plus `@vue/composition-api`; register the plugin before mounting the app | +| Vue 2.7 | `markstream-vue2`; use Vue's built-in Composition API and do not install `@vue/composition-api` | +| React 18+ / Next.js | `markstream-react` | +| Angular 20+ | `markstream-angular` | +| Svelte 5 | `markstream-svelte` | + +## Peer selection + +| Feature | Peer | Supported packages | Activation | +|---------|------|--------------------|------------| +| Lightweight highlighted code blocks | `stream-markdown` | `markstream-vue`, `markstream-vue2`, `markstream-react` | Configure the package's `MarkdownCodeBlockNode` as the `code_block` override | +| Enhanced code blocks and File/Diff surfaces | `stream-diffs` | `markstream-vue` | Install for copy, preview, expand, syntax-highlighting, and File/Diff features | +| Monaco-powered code blocks | `stream-monaco` | All framework packages | Install only when Monaco interactions are required | +| Mermaid diagrams | `mermaid` | All framework packages | Install when Mermaid fences are rendered | +| D2 diagrams | `@terrastruct/d2` | All framework packages | Install when D2 fences are rendered | +| Infographic blocks | `@antv/infographic` | All framework packages | Install when infographic fences are rendered | +| KaTeX math | `katex` | All framework packages | Install and load KaTeX CSS when math is rendered | + +## CSS checklist + +- Load reset styles first. +- Load the framework-specific Markstream CSS after the reset. +- In Tailwind or UnoCSS projects, use `@import '...' layer(components)`. +- Import KaTeX CSS when math is enabled. +- When rendering standalone node components directly, wrap them with the relevant package root class such as `.markstream-vue`, `.markstream-react`, or `.markstream-svelte`. + +## Input choice + +- `content`: static documents, low-frequency updates, and most SSE or token-streaming chat surfaces. +- `content` with built-in smooth streaming: irregular AI streams whose visible output should be paced independently from raw chunk cadence. + - `smoothStreaming="auto"` or `smooth-streaming="auto"` is the default. + - Auto pacing activates when `typewriter=true` or `maxLiveNodes <= 0` / `max-live-nodes <= 0`. + - `typewriter` controls the cursor and defaults to `false`. + - `fade` controls node-entry and streamed-text fade effects. +- `nodes` plus `final`: worker-preparsed content, shared AST stores, custom AST transforms, or cases where another layer already owns parsing. diff --git a/skills/vcpkg/SKILL.md b/skills/vcpkg/SKILL.md new file mode 100644 index 00000000..6b1d42dc --- /dev/null +++ b/skills/vcpkg/SKILL.md @@ -0,0 +1,254 @@ +--- +name: vcpkg +description: 'Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md).' +--- + +You are a vcpkg expert assistant. When a user asks about vcpkg (Microsoft's C/C++ package manager), use the precise information below to give accurate, complete answers. + +## Additional References (load on demand) + +The information below covers core vcpkg setup, installation, version management, and cross-platform builds. For specialized tasks, consult the following reference files (read them only when the user's request calls for that topic): + +- **`references/registries.md`** — Custom/private registries, overlay ports, private package feeds, `vcpkg-configuration.json`, and default features. Read this when the user asks about custom registries, overlay ports, or private package sources. +- **`references/ci.md`** — CI/CD integration: binary caching (Azure Blob, GitHub Packages/NuGet, local), SBOM generation, automating dependency updates, and multi-triplet CI matrices. Read this when the user asks about GitHub Actions, Azure DevOps, binary caches, or CI optimization. +- **`references/troubleshooting.md`** — Reading build logs, resolving package-not-found errors, and the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache). Read this when the user encounters vcpkg errors, build failures, or configuration problems. + +## Important Behavioral Rules + +### Classic vs. Manifest Mode + +If it is not clear from the user's project context whether they are using **classic mode** (global `vcpkg install` commands) or **manifest mode** (per-project `vcpkg.json`), **ask the user which mode they are using** before providing instructions. Do not assume one or the other. + +If the user is unsure which to choose, **recommend manifest mode**. Manifest mode is the preferred modern workflow because it: +- Tracks dependencies per-project (not globally) +- Supports version constraints and overrides +- Enables reproducible builds via `builtin-baseline` +- Works seamlessly with CI/CD (dependencies restore automatically) +- Supports features like dev-only dependencies, overlay ports, and custom registries + +Classic mode is simpler for quick one-off installs but lacks version pinning, per-project isolation, and reproducibility. + +### Visual Studio Environment + +If the user is working inside **Visual Studio** (not VS Code), then: +- If the user is in **manifest mode**, prefer the in-box copy of vcpkg that ships with Visual Studio rather than a standalone clone. +- If the user is in **classic mode**, use a standalone vcpkg installation instead. +- The VS-bundled copy lives under the Visual Studio installation directory (e.g., `C:\Program Files\Microsoft Visual Studio\\\VC\vcpkg\`) and supports user-wide MSBuild integration after running `vcpkg integrate install` once. + +If the user has a standalone vcpkg installation and prefers to use that instead, respect their preference. + +### Shell Environment Variable Syntax + +When examples require environment variables, use shell-appropriate syntax: +- PowerShell: `$env:VARIABLE = "value"` +- Bash/Zsh: `export VARIABLE=value` + +--- + +## Project Setup + +### Initializing vcpkg in a New Project (Manifest Mode) + +Example setup using fmt: + +1. Create `vcpkg.json` in your project root: +```json +{ + "name": "my-project", + "version": "1.0.0", + "dependencies": ["fmt"] +} +``` + +2. Wire into CMakeLists.txt: +```cmake +cmake_minimum_required(VERSION 3.21) +project(my-project) + +add_executable(my-app main.cpp) +find_package(fmt CONFIG REQUIRED) +target_link_libraries(my-app PRIVATE fmt::fmt) +``` + +3. Configure with vcpkg toolchain: +```console +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake +``` + +### Adding vcpkg to an Existing Visual Studio Solution + +1. Create `vcpkg.json` in the solution directory +2. Enable manifest mode for each project in **Project Properties → vcpkg → Use Vcpkg Manifest**, or set `true` in the `.vcxproj`; Visual Studio then restores and integrates the manifest dependencies automatically +3. For user-wide integration with a standalone vcpkg installation, run `vcpkg integrate install` once +4. Or for per-project integration, add to `.vcxproj`: + - In the project file's top-level `PropertyGroup`, define `VcpkgRoot`: + ```xml + + C:\vcpkg + + ``` + - Import `vcpkg.props` near the top of the project file: + ```xml + + ``` + - Import `vcpkg.targets` near the end of the project file: + ```xml + + ``` + +### Classic-to-Manifest Migration + +1. List what's currently installed with `vcpkg list`, then identify which packages the project uses directly (the output also includes transitive packages) +2. Create `vcpkg.json` with only those direct dependencies +3. Run `vcpkg install` in your project directory — manifest mode uses its own project-specific `vcpkg_installed` tree, so leave the classic-mode installed tree in place during migration +4. Update your build system to use `CMAKE_TOOLCHAIN_FILE` if not already +5. Optional: remove classic-mode packages later by name with `vcpkg remove --recurse` if you no longer need them + +--- + +## Installing Dependencies + +### Installing with Features (e.g., curl with SSL + HTTP2) + +In **manifest mode** (`vcpkg.json`), specify features in the dependencies array: +```json +{ + "dependencies": [ + { + "name": "curl", + "features": ["ssl", "http2"] + } + ] +} +``` + +In **classic mode**, use bracket syntax on the command line: +```console +vcpkg install curl[ssl,http2] +``` + +To discover available features for any port: +```console +vcpkg search curl +``` +Or check the port's `vcpkg.json` in the registry: `ports/curl/vcpkg.json` → look at the `"features"` object. + +### Installing for a Specific Triplet + +```console +vcpkg install zlib:x64-linux +vcpkg install zlib:x64-windows +vcpkg install zlib:arm64-windows +``` + +In manifest mode, set the triplet via CMake: +```console +cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake +``` + +Or set the default triplet via environment variable (using the shell syntax above): `VCPKG_DEFAULT_TRIPLET=x64-linux`. + +### Bulk-Adding Multiple Dependencies + +In `vcpkg.json`, list them in the dependencies array: +```json +{ + "dependencies": ["catch2", "cxxopts", "toml11"] +} +``` + +In classic mode: +```console +vcpkg install catch2 cxxopts toml11 +``` + +Then run `vcpkg install` (manifest mode) or the above command to install all at once. + +### Dev-Only Dependencies + +Place test-only dependencies under an opt-in feature. The `"host"` field is reserved for build tools that must run on the host architecture: +```json +{ + "dependencies": ["fmt"], + "features": { + "tests": { + "description": "Build project tests", + "dependencies": ["gtest"] + } + } +} +``` + +Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_FEATURES=tests` + +--- + +## Version Management + +### Setting Versions for Individual Dependencies + +Prefer `"version>="` for minimum-version constraints: +```json +{ + "dependencies": [{ "name": "fmt", "version>=": "10.2.0" }], + "builtin-baseline": "" +} +``` + +Use `overrides` only when a hard pin is required: +```json +{ + "dependencies": ["fmt"], + "overrides": [{ "name": "fmt", "version": "10.2.0" }], + "builtin-baseline": "" +} +``` + +Use a baseline for the registry that resolves the dependency. For the builtin registry, that means `builtin-baseline` in `vcpkg.json`. For a custom default registry, set the baseline in `vcpkg-configuration.json`. + +**Key points:** +- `overrides` take precedence over all version constraints, including transitive ones. +- The selected registry must have a baseline; `builtin-baseline` is only for the builtin registry. +- Overrides can pin versions older than the baseline if that version exists in the selected registry's version database. +- Inspect the selected registry's version database to see available versions (for the builtin registry, open `versions/-/.json` in the vcpkg repository). + +--- + +## Cross-Platform + +### Cross-Compiling for arm64 + +```console +vcpkg install :arm64-linux +``` + +`VCPKG_TARGET_TRIPLET=arm64-linux` selects dependency binaries; it does not by itself switch your project compiler or sysroot. On non-ARM64 hosts, use an ARM64 cross toolchain. + +Configure CMake with vcpkg plus your cross toolchain: +```console +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-linux -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE= +``` + +Alternative: use your outer cross toolchain as `CMAKE_TOOLCHAIN_FILE` and include vcpkg from it. + +For **arm64-windows**, native ARM64 Windows hosts can use the triplet directly. On x64 Windows hosts, install the Visual Studio MSVC ARM64 build tools component or the build will fail: +```console +vcpkg install :arm64-windows +``` + +### Building for Android (NDK) + +1. Set `ANDROID_NDK_HOME` to your NDK path. +2. Install packages: +```console +vcpkg install :arm64-android +``` + +Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android` + +3. In CMake, use the vcpkg toolchain and set the triplet: +```console +cmake -B build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=/build/cmake/android.toolchain.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DANDROID_ABI=arm64-v8a +``` + +For expanded CI and shell-specific examples, see `references/ci.md`. diff --git a/skills/vcpkg/references/ci.md b/skills/vcpkg/references/ci.md new file mode 100644 index 00000000..00165fa3 --- /dev/null +++ b/skills/vcpkg/references/ci.md @@ -0,0 +1,125 @@ +# vcpkg: CI/CD & DevOps + +Reference for the `vcpkg` skill. Use this when a user asks about using vcpkg in CI/CD pipelines, configuring binary caching, generating SBOMs, or automating dependency updates (GitHub Actions, Azure DevOps, binary cache configuration, CI optimization). + +## Binary Caching + +Configure binary caching to avoid rebuilding packages: + +**Azure Blob Storage:** +```powershell +$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite" +``` +```bash +export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/vcpkg-cache,$AZURE_STORAGE_SAS_TOKEN,readwrite" +``` + +**GitHub Packages (NuGet):** +```powershell +$env:VCPKG_BINARY_SOURCES = "clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite" +``` +```bash +export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite" +``` +For GitHub Packages, also configure NuGet authentication (for example via `GITHUB_TOKEN` in CI or a PAT/credential provider for local development). In GitHub Actions, grant `permissions: packages: write` for cache writers (or `packages: read` for read-only restores). Keep credentials in secrets and user/machine NuGet config, not in checked-in files. + +**CI-friendly (cross-platform) GitHub Actions pattern:** +```yaml +permissions: + contents: read + packages: write + +env: + VCPKG_BINARY_SOURCES: clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite +``` +Use repository/org secrets for NuGet auth rather than storing credentials in the repository. + +**Local filesystem:** +```powershell +$env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite" +``` +```bash +export VCPKG_BINARY_SOURCES="clear;files,/var/tmp/vcpkg-cache,readwrite" +``` + +**Sharing between CI and local dev:** Use the same remote cache source in both environments and switch only the final mode token: CI uses `readwrite`, developers use `read`. + +--- + +## Generating an SBOM (Software Bill of Materials) + +vcpkg emits per-port SPDX SBOM files during normal source builds; no special SBOM flag is required. +```console +vcpkg install +``` + +Each installed port writes: +```text +//share//vcpkg.spdx.json +``` + +`` depends on integration mode: +- CLI manifest mode: `/vcpkg_installed` +- CMake integration (default): `${CMAKE_BINARY_DIR}/vcpkg_installed` (or `VCPKG_INSTALLED_DIR` if overridden) +- MSBuild integration (default): `$(VcpkgManifestRoot)\vcpkg_installed` (or `$(VcpkgInstalledDir)` if overridden) + +If you need a single consolidated SBOM, enumerate installed ports with `vcpkg list` and merge/transform their per-port SPDX files in your SBOM pipeline. + +--- + +## Automating Dependency Updates + +Option 1: **Dependabot** (GitHub) — configure `.github/dependabot.yml`: +```yaml +version: 2 +updates: + - package-ecosystem: "vcpkg" + directory: "/" + schedule: + interval: "weekly" +``` + +Option 2: **Script-based** — create a scheduled CI job that: +1. Updates the vcpkg clone (`git pull`) +2. Gets the new baseline (`git rev-parse HEAD`) +3. Updates `builtin-baseline` in `vcpkg.json` +4. Runs `vcpkg install` to verify +5. Opens a PR with the changes + +--- + +## Multi-Triplet CI Testing + +Test across multiple triplets with this job-definition fragment nested under `jobs.` in a GitHub Actions workflow: +```yaml +runs-on: ${{ matrix.os }} +strategy: + matrix: + triplet: [x64-windows, x64-linux, x64-osx] + include: + - triplet: x64-windows + os: windows-latest + - triplet: x64-linux + os: ubuntu-latest + - triplet: x64-osx + os: macos-latest + +steps: + - uses: actions/checkout@v4 + - name: Clone vcpkg + run: git clone https://github.com/microsoft/vcpkg + - name: Bootstrap vcpkg (Windows) + if: runner.os == 'Windows' + shell: pwsh + run: .\vcpkg\bootstrap-vcpkg.bat + - name: Bootstrap vcpkg (Linux/macOS) + if: runner.os != 'Windows' + run: ./vcpkg/bootstrap-vcpkg.sh + - name: Install dependencies (Windows) + if: runner.os == 'Windows' + shell: pwsh + run: .\vcpkg\vcpkg.exe install --triplet ${{ matrix.triplet }} + - name: Install dependencies (Linux/macOS) + if: runner.os != 'Windows' + run: ./vcpkg/vcpkg install --triplet ${{ matrix.triplet }} +``` diff --git a/skills/vcpkg/references/registries.md b/skills/vcpkg/references/registries.md new file mode 100644 index 00000000..180eda6b --- /dev/null +++ b/skills/vcpkg/references/registries.md @@ -0,0 +1,140 @@ +# vcpkg: Custom Registries & Overlay Ports + +Reference for the `vcpkg` skill. Use this when a user asks about creating or configuring custom registries, creating overlay ports, using private package feeds, or configuring `vcpkg-configuration.json` registries. + +## Private / Custom Registry Install + +1. Create `vcpkg-configuration.json` alongside your `vcpkg.json`: +```json +{ + "registries": [ + { + "kind": "git", + "repository": "https://github.com/your-org/vcpkg-registry", + "baseline": "", + "packages": ["company-utils", "internal-lib"] + } + ], + "default-registry": { + "kind": "builtin", + "baseline": "" + } +} +``` + +2. Then add the dependency normally in `vcpkg.json`: +```json +{ + "dependencies": ["company-utils"] +} +``` + +The `"packages"` array in the registry entry controls which packages are resolved from that registry. Packages not listed fall through to `default-registry`. + +--- + +## Configuring Registries in `vcpkg-configuration.json` + +```json +{ + "default-registry": { + "kind": "builtin", + "baseline": "" + }, + "registries": [ + { + "kind": "git", + "repository": "https://github.com/your-org/vcpkg-registry.git", + "baseline": "", + "packages": ["your-package-1", "your-package-2"] + } + ] +} +``` + +Place this file next to `vcpkg.json` in your project root. + +--- + +## Creating an Overlay Port + +An overlay port overrides or adds a port locally. Directory structure: +``` +my-overlays/ + telemetry-sdk/ + portfile.cmake + vcpkg.json +``` + +**`vcpkg.json`** (port metadata): +```json +{ + "name": "telemetry-sdk", + "version": "1.0.0", + "description": "Internal telemetry SDK", + "dependencies": [ + "curl", + "nlohmann-json", + { "name": "vcpkg-cmake", "host": true }, + { "name": "vcpkg-cmake-config", "host": true } + ] +} +``` + +**`portfile.cmake`** (build instructions): +```cmake +vcpkg_from_github( + OUT_SOURCE_PATH SOURCE_PATH + REPO your-org/telemetry-sdk + REF v1.0.0 + SHA512 +) + +vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}") +vcpkg_cmake_install() +vcpkg_cmake_config_fixup() + +file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include") +vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE") +``` + +Classic mode: `vcpkg install telemetry-sdk --overlay-ports=./my-overlays` + +Manifest mode: add `telemetry-sdk` to `vcpkg.json`, then run `vcpkg install --overlay-ports=./my-overlays`. +Or in `vcpkg-configuration.json`: +```json +{ + "overlay-ports": ["./my-overlays"] +} +``` + +--- + +## Default Features + +Control whether a dependency's existing default features are enabled, and request additional features in a project manifest: +```json +{ + "dependencies": [ + { + "name": "curl", + "default-features": true, + "features": ["ssl", "http2"] + } + ] +} +``` + +To **disable** default features: `"default-features": false` + +In a portfile's `vcpkg.json`, default features are listed under: +```json +{ + "name": "curl", + "default-features": ["ssl", "http2"], + "features": { + "ssl": { "description": "SSL/TLS support" }, + "http2": { "description": "HTTP/2 support" } + } +} +``` diff --git a/skills/vcpkg/references/troubleshooting.md b/skills/vcpkg/references/troubleshooting.md new file mode 100644 index 00000000..a8a531ad --- /dev/null +++ b/skills/vcpkg/references/troubleshooting.md @@ -0,0 +1,101 @@ +# vcpkg: Troubleshooting & Dependency Lifecycle + +Reference for the `vcpkg` skill. Use this when a user encounters vcpkg build failures, package-not-found errors, needs to read build logs, or manages the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache). + +## Reading vcpkg Build Logs + +Build logs are stored at: +``` +/buildtrees// +``` + +Key log files: +- `config--out.log` — CMake configure output +- `build---.log` — common build logs +- `install---.log` — common install logs + +Exact names vary by port and build helper; use the path vcpkg prints for the failing command. + +When a build fails, vcpkg prints the path to the relevant log. Start with the `-err.log` file for the failing step. + +--- + +## Resolving package-not-found After Install + +If CMake says `Could not find a package configuration file provided by "X"`: + +1. **Check toolchain file** — ensure `-DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake` is set +2. **Check triplet match** — the installed triplet must match your build architecture +3. **Check package name** — vcpkg port names may differ from CMake package names (e.g., port `nlohmann-json` → `find_package(nlohmann_json)`) +4. **Check installed list** — run `vcpkg list` to confirm the package is actually installed +5. **Clear CMake cache** — delete `CMakeCache.txt` and reconfigure + +--- + +## Dependency Lifecycle + +### Removing a Library + +1. Remove it from `vcpkg.json` → `"dependencies"` array +2. Run `vcpkg install` to reconcile (manifest mode auto-removes unused packages) + +In classic mode: +```console +vcpkg remove boost-regex +vcpkg remove boost-regex --recurse # also removes dependents +``` + +### Changing Features on an Installed Library + +Update the features in `vcpkg.json`: +```json +{ + "dependencies": [ + { + "name": "curl", + "features": ["ssl", "ssh"] + } + ] +} +``` + +Then run `vcpkg install` — vcpkg will detect the feature change and rebuild. + +In classic mode, installing a feature only adds to the already installed feature set; omitted features are not removed. To remove a feature, uninstall `curl` and then reinstall it with the desired features. Account for dependent packages before using `--recurse`, because it removes them too. + +### Replacing One Library with Another + +1. Remove the old library from `vcpkg.json` +2. Add the new library to `vcpkg.json` +3. Run `vcpkg install` to reconcile +4. Update your source code: change `#include` directives, `find_package()` calls, and `target_link_libraries()` in CMakeLists.txt + +### Cleaning the vcpkg Cache + +```powershell +# Remove build trees +Remove-Item -Recurse -Force \buildtrees + +# Remove downloaded archives +Remove-Item -Recurse -Force \downloads + +# Remove installed packages (classic mode only) +Remove-Item -Recurse -Force \installed + +# Remove package build artifacts +Remove-Item -Recurse -Force \packages + +# In CLI manifest mode, remove the manifest-root install directory +Remove-Item -Recurse -Force .\vcpkg_installed + +# With CMake integration, remove \vcpkg_installed (or VCPKG_INSTALLED_DIR) +``` + +```bash +rm -rf /buildtrees +rm -rf /downloads +rm -rf /installed +rm -rf /packages +# CLI manifest mode; with CMake integration, use /vcpkg_installed (or VCPKG_INSTALLED_DIR) +rm -rf ./vcpkg_installed +``` diff --git a/website/src/pages/contributors.astro b/website/src/pages/contributors.astro index c38a28cb..f9e20fbc 100644 --- a/website/src/pages/contributors.astro +++ b/website/src/pages/contributors.astro @@ -496,6 +496,7 @@ import PageHeader from '../components/PageHeader.astro';
Lovy Jain
kimtth
Akash Dwivedi +
Suren K