Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (63 loc) · 4.43 KB

AGENTS.md

File metadata and controls

91 lines (63 loc) · 4.43 KB

Agent instructions for winapp

This file provides focused, actionable information to help an AI coding agent be immediately productive in this repo.

Big picture

Two main components:

  • src/winapp-CLI (C#/.NET): The native CLI implemented with System.CommandLine. Key files: Program.cs, Commands/*.cs (e.g., InitCommand.cs, PackageCommand.cs). Build with scripts/build-cli.ps1.
  • src/winapp-npm (Node): A thin Node wrapper/SDK and CLI (cli.js) that forwards most commands to the native CLI. Key helpers: winapp-cli-utils.js, msix-utils.js, cpp-addon-utils.js. Install with npm install inside src/winapp-npm.

Developer workflows

# Build everything and generate autogenerated files
# You can pass -SkipTests, -SkipMsix, and/or -SkipNpm to speed up the build when those pieces are not needed
.\scripts\build-cli.ps1

# Or build directly with dotnet
dotnet build src/winapp-CLI/winapp.sln -c Debug

# Run native CLI in-tree
dotnet run --project src/winapp-CLI/WinApp.Cli/WinApp.Cli.csproj -- <args>

# Update npm package after CLI changes
cd src/winapp-npm && npm run build              # builds C# CLI + copies to npm bin
cd src/winapp-npm && npm run build-copy-only    # copies already-built Release binaries

# Node package development
cd src/winapp-npm && npm install
node cli.js help

# Always call the build script at the end to ensure everything builds and all autogenerated docs are generated
.\scripts\build-cli.ps1

Always update documentation and samples

When adding or changing public facing features, ensure all documentation is also updated. Places to update (but not limited to):

  • docs\usage.md
  • docs\guides\
  • samples\
  • docs\fragments\skills\
  • README.md
  • .github\plugin\agents\

(.github\plugin\skills are autogenerated from docs\fragments\skills)

If a feature is big enough and requires its own docs page, add it under docs\

Where to look first

Area Key files
CLI commands src/winapp-CLI/WinApp.Cli/Commands/*.cs
Services src/winapp-CLI/WinApp.Cli/Services/*.cs
Node CLI src/winapp-npm/cli.js, winapp-cli-utils.js
Config example winapp.example.yaml
CLI schema docs/cli-schema.json
Agent skill templates docs/fragments/skills/winapp-cli/
Copilot plugin .github/plugin/
Samples samples/ (electron, cpp-app, dotnet-app, etc.)

CLI command semantics

Look at the docs\cli-schema.json for the full schema to know what the cli can do

Quick change checklist

  • Adding a new CLI command: Implement in C# under Commands/, register in HostBuilderExtensions.cs, inject into WinAppRootCommand, update src/winapp-npm/cli.js if needed.
  • Changing command descriptions: Edit the description string in the command's constructor.
  • Changing CLI commands/workflows: Update the hand-written skill template in docs/fragments/skills/ if the workflow, examples, or troubleshooting for that command changed. Run scripts/build-cli.ps1 at the end to regenerate all skills.
  • After C# CLI changes: Run cd src/winapp-npm && npm run build to update npm package binaries.
  • Updating package versions: Edit winapp.example.yaml.

Integration points

  • NuGet: Packages downloaded to NuGet global cache. Local .winapp folder contains generated headers and libs only.
  • Build Tools: makeappx.exe, signtool.exe, makepri.exe, etc. Auto-downloaded by the tool command or when commands that need them are invoked.
  • CppWinRT: Generated headers in .winapp/generated/include. Response file at .cppwinrt.rsp.

Auto-generation pipeline

The following files are auto-generated from cli-schema.json via scripts/generate-llm-docs.ps1. Do not run this script directly and run via the build-cli.ps1 script. Do not edit these files directly — your changes will be overwritten:

  • docs/cli-schema.json — machine-readable schema
  • .github/plugin/skills/winapp-cli/*/SKILL.md — Copilot CLI plugin skills

To edit skill content, modify the hand-written templates in docs/fragments/skills/winapp-cli/. Each template file (e.g., package.md, manifest.md) contains the workflow docs, examples, and troubleshooting content. The auto-generation script appends command reference tables from the CLI schema. Running scripts/build-cli.ps1 triggers regeneration automatically.

Skill descriptions (used for Copilot skill matching) are defined in the $SkillDescriptions hashtable in scripts/generate-llm-docs.ps1.