Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions .github/skills/create-launcher-plugin/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
name: create-launcher-plugin
description: Use when creating or scaffolding a new LANCommander.Community launcher plugin, including source-pinned host integration, projects, packaging, loader tests and registry integration.
---

# Create a launcher plugin

Create one launcher component using verified host contracts. Shared requirements
come from [CONTRIBUTING.md](../../../CONTRIBUTING.md),
[plugin maintenance](../plugin-maintenance/SKILL.md) and
[RELEASES.md](../../../RELEASES.md); the existing
[MQTT README](../../../plugins/Launcher.MQTT/README.md) is evidence for launcher
packaging/storage, not a requirement to add MQTT or Home Assistant.

## Establish identity and host evidence

1. Inspect remote/status, fetch canonical
`LANCommander/LANCommander.Community` main, and use a separate feature branch
based on current main (an existing clean isolated task branch is sufficient).
Preserve unrelated changes; stop if the base/worktree conflicts with the
task. Use app branch tooling in an app-managed worktree.
2. Read [eng/plugins.json](../../../eng/plugins.json),
[root defaults](../../../Directory.Build.props),
[central packages](../../../Directory.Packages.props) and the
[MQTT entry project](../../../plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT/LANCommander.Community.Launcher.MQTT.csproj).
Check published package availability and inspect actual APIs before choosing
dependencies. Current launcher service contracts are source-coupled: use
[eng/lancommander-source.json](../../../eng/lancommander-source.json) and
`eng\Prepare-LANCommanderSource.ps1`, preserving `LANCOMMANDER_SOURCE_ROOT`
and the explicit `LANCommanderSourceRoot` override. Never substitute a
mutable checkout or fabricate NuGet adapters for missing contracts.
3. Choose key `Launcher.<Name>` and root
`LANCommander.Community.Launcher.<Name>`. Under `plugins\Launcher.<Name>`,
use `src\<root>\<root>.csproj`; directory, project basename, explicit
`PackageId`, `AssemblyName`, `RootNamespace` all equal the root with exact
casing and **no `.Plugin` suffix**. Put host-independent logic and transports
in suffixed helper projects only when needed; keep helpers/tests non-packable.
4. Follow MQTT's component `Directory.Build.props` import/version-file pattern.
Use central dependency versions, initial independent full SemVer, matching
non-empty changelog, README and required license/third-party notices.

## Implement the launcher boundary

- Inspect the
[entry point](../../../plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT/HomeAssistantLauncherPlugin.cs)
and pinned host lifecycle/DI/settings APIs. Implement `IPlugin` and the
assembly `LANCommanderPlugin` attribute with `PluginHost.Launcher`, a unique
stable semantic ID (matching `IPlugin.Id`) and informational version reporting.
Source-coupled MQTT has exact min/max host bounds; do not claim a wider range
for a new adapter without evidence and loader tests.
- Separate GUI-only behavior from other host modes and clean up background work
on host shutdown. Keep service scopes alive across asynchronous operations;
use the authenticated user's visible resources and normal host services, not
direct database changes or bypasses of host action/install checks. UI must
remain usable when config is missing/invalid; fail operations visibly.
- Store writable settings/journals in the host-preserved `Data` directory under
the plugin directory (or the verified context data API), never at package
root. Ship only blank examples; mask credentials in UI and never log secrets.
Preserve semantic IDs, data/config keys and external protocol/entity IDs for
existing behavior. A new package ID is **not** an in-place upgrade: document
stopped-host backup, removal of old entry DLLs and explicit transfer of `Data`.
Same-ID updates preserve only `Data`; uninstall deletes it too.
- Declare `LANCommander.Plugin;LANCommander.Plugin.Launcher` package types plus
tags. Reference host projects with `Private="false"` and `PrivateAssets="all"`
as in MQTT, retaining exclusions for host-provided runtime/native payloads.
Stage only verified private assemblies, `.deps.json` and blank examples under
`lib/net10.0` for the current target. Suppress NuGet dependencies: the installer
does not restore them. Do not package a ZIP wrapper or the host build output.

## Register and validate the deliverable

Add the solution entry, registry project/tests/identities/host bounds/version and
independent tag prefix, artifact format and explicit feed eligibility. Update
all explicit allowlists/counts in `eng\PluginRelease.psm1`,
`eng\Build-Plugin.ps1`, `eng\Validate-Plugin.ps1`, `eng\Test-NuGetPackage.ps1`,
repository/selection/destination/publication tests, and CI/release matrices,
dispatch options, tag filters and component jobs. Update root navigation and
release documentation. Do not copy MQTT-specific HA/template validation into a
generic launcher component.

Add focused host-independent tests and source-pinned host-loader tests. Adapt
[Test-LauncherPackage.ps1](../../../eng/Test-LauncherPackage.ps1) and
[package tests](../../../plugins/Launcher.MQTT/tests/LANCommander.Community.Launcher.MQTT.HostLoader.Tests/PluginPackageTests.cs)
for the new component, not by weakening MQTT's checks. Validate the actual
extracted nupkg: correct-host discovery, wrong-host/version rejection, entry
assembly/private dependencies and shared host type identity, installation and
same-ID update preservation of `Data`. Wire this into component validation.

Run the repository checks from RELEASES.md and, after adding the new selection:

```powershell
pwsh .\eng\Validate-Plugin.ps1 -Plugin Launcher.<Name> -OutputDirectory .\artifacts\new-launcher-validation
```

Use fresh output. Install extra test dependencies only if that component needs
them. Report untested real GUI/installation/integration behavior separately from
automated loader tests. Stop for unavailable source/packages, unknown storage
or auth contracts, or unverified compatibility. Creation is not authorization
to open a PR, publish packages, push release tags, change credentials/permissions
or migrate installed identities.
96 changes: 96 additions & 0 deletions .github/skills/create-server-plugin/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
name: create-server-plugin
description: Use when creating or scaffolding a new LANCommander.Community server plugin, including its projects, host contracts, packaging, tests and registry integration.
---

# Create a server plugin

Create one installable server component, not a new host or an independent release
pipeline. Follow [CONTRIBUTING.md](../../../CONTRIBUTING.md),
[plugin maintenance](../plugin-maintenance/SKILL.md) and
[RELEASES.md](../../../RELEASES.md) for shared conventions.

## Establish the component

1. Inspect remote/status and fetch current canonical `main` from
`LANCommander/LANCommander.Community`. Start on a separate feature branch
based on that main; an existing clean, isolated task branch is sufficient.
Never discard unrelated changes or rebase a dirty/unrelated branch silently.
In an app-managed worktree, use the app's branch tooling.
2. Read [eng/plugins.json](../../../eng/plugins.json),
[root build defaults](../../../Directory.Build.props),
[central packages](../../../Directory.Packages.props), and the
[Quake3 project](../../../plugins/Server.Quake3/LANCommander.Community.Server.Quake3/LANCommander.Community.Server.Quake3.csproj)
and [entry point](../../../plugins/Server.Quake3/LANCommander.Community.Server.Quake3/Quake3Plugin.cs).
Inspect the actual published SDK/Server.Plugins/UI APIs for the chosen
baseline and verify package availability before adding references.
Source evidence can be obtained from the immutable
[host pin](../../../eng/lancommander-source.json) using
`eng\Prepare-LANCommanderSource.ps1`; do not assume unreleased APIs exist.
3. Use component key `Server.<Name>` and root
`LANCommander.Community.Server.<Name>` with exact casing. Put the entry
project below `plugins\Server.<Name>` (a `src` directory is optional, as
existing components demonstrate). Its directory, `.csproj` basename,
explicit `PackageId`, `AssemblyName` and `RootNamespace` must all equal that
root: **no `.Plugin` suffix**. Helpers/tests append descriptive suffixes
to the same root and remain non-packable.
4. Add component `Directory.Build.props` importing the root defaults and
reading `version.txt` for `Version`/`PackageVersion`, following Quake3.
Keep dependencies centrally versioned; only the entry project is packable.
Add a README, license/notices where required, initial full SemVer and a
non-empty changelog section for that exact version.

## Implement the server boundary

- Implement the verified `IPlugin` lifecycle and assembly
`LANCommanderPlugin` attribute with `PluginHost.Server`, deliberate compatible
host bounds, a unique stable semantic ID and informational version reporting.
Keep the attribute and `IPlugin.Id` consistent. IDs are not package names:
preserve semantic IDs, data IDs, config keys and protocols when replacing or
extracting existing behavior. A package rename requires a new version/feed
identity and explicit replacement instructions, never an overwritten package.
- Reuse host DI contracts for game/import/storage behavior; do not write host
database rows through guessed schemas. Keep mutable plugin state in
`PluginContext.DataDirectory`, not shipped output. Do not copy secrets into
examples or log credentials.
- For UI, use verified route/navigation extensions and server UI controls.
Inspect [Quake3](../../../plugins/Server.Quake3/README.md) and
[RecompCatalog](../../../plugins/Server.RecompCatalog/README.md) for relevant
patterns. Navigation visibility is not authorization: enforce page
`PluginAccess` and endpoint/service authorization on the server. Test denied
access as well as allowed behavior. Register host services with appropriate
lifetimes and report initialization/operation failures explicitly.
- Declare `LANCommander.Plugin;LANCommander.Plugin.Server` package types and
supplemental tags. Host package references use `ExcludeAssets="runtime"`
and `PrivateAssets="all"`; never bundle SDK, Server.Plugins, Server.UI or
host UI binaries. Bundle the complete private dependency payload under the
target `lib` folder; suppress NuGet dependencies because the installer does
not restore them. Follow existing package targets, not `dotnet publish` output.

## Integrate and verify

Update the root solution and registry with project/test paths, canonical
identities, independent version/tag prefix, host bounds, artifact format and
explicit feed eligibility. Inspect and update **all** explicit allowlists/counts:
`eng\PluginRelease.psm1`, `eng\Build-Plugin.ps1`, `eng\Validate-Plugin.ps1`,
`eng\Test-NuGetPackage.ps1`, selection/repository/destination/publication tests,
and CI/release workflow matrices, dispatch options, tag filters and component
jobs. Update README navigation and the release table; adding a project alone
does not make it selectable or releasable.

Add focused behavior/auth tests and a private-only package inventory check,
plus isolated loading of the **actual packaged entry assembly** with shared host
contract/UI identity (see Quake3's package and host-loader tests). Wire those
checks into `Build-Plugin.ps1`/`Validate-Plugin.ps1`.
Run the repository checks listed in RELEASES.md, then:

```powershell
pwsh .\eng\Validate-Plugin.ps1 -Plugin Server.<Name> -OutputDirectory .\artifacts\new-server-validation
```

Use a fresh output directory. Verify emitted nuspec ID/version/types/repository,
assembly names, payload and loadability, not just filenames. Report live-host
behavior not exercised. Stop for unavailable contracts/packages, uncertain
authorization/data semantics or incompatible host bounds rather than inventing
adapters. Creation does not authorize pushing release tags, publishing packages,
changing feed permissions, opening a PR or migrating installed identities.
11 changes: 7 additions & 4 deletions .github/skills/plugin-maintenance/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ support it.

- Canonical component metadata is in `eng/plugins.json`; release versions live
in each component's `version.txt` and changelog.
- Use `LANCommander.Community.Server.Mcp`,
`LANCommander.Community.Server.RecompCatalog.*`, and
`LANCommander.Community.Launcher.MQTT.*` for project names, paths, and C#
namespaces. Use exact `LANCommander` casing for source-owned names.
- Use `LANCommander.Community.<Server|Launcher>.<Name>` for the installable
project, package, assembly and root namespace, with no `.Plugin` suffix.
Helpers/tests append suffixes to that root and stay non-packable. Use exact
`LANCommander` casing for source-owned names.
- Set each owned `AssemblyName` and `PackageId` to the exact current project
name with `LANCommander` casing; do not keep legacy pre-monorepo names as
active build or package outputs. Preserve semantic plugin IDs, persisted/config
Expand Down Expand Up @@ -69,3 +69,6 @@ support it.
For release preparation and automatic GitHub Release behavior, follow
[`RELEASES.md`](../../../RELEASES.md) and the
[`plugin-release` skill](../plugin-release/SKILL.md).

For new components, start with [server creation](../create-server-plugin/SKILL.md)
or [launcher creation](../create-launcher-plugin/SKILL.md).
11 changes: 11 additions & 0 deletions .github/skills/repository-skill-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,17 @@ Create focused, discoverable guidance for a recurring repository task. Keep
the repository's canonical docs and scripts as the source of truth; a skill
should route an agent to them, not copy a long procedure that will drift.

## Existing task boundaries

- [Server plugin creation](../create-server-plugin/SKILL.md): new server components.
- [Launcher plugin creation](../create-launcher-plugin/SKILL.md): new launcher components.
- [Plugin maintenance](../plugin-maintenance/SKILL.md): changes to existing components.
- [Plugin release preparation](../plugin-release/SKILL.md): validation and release gates.

Skills are discovered from `.github/skills/<name>/SKILL.md`; there is no separate
skill registry. Link new skills from the relevant guides and
[CONTRIBUTING.md](../../../CONTRIBUTING.md).

## Authoring workflow

1. Choose one task boundary and a short kebab-case directory name under
Expand Down
21 changes: 15 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,31 @@
# Contributing

Use the component-focused project and namespace hierarchy:
Use `LANCommander.Community.<Server|Launcher>.<Name>` for every installable
entry project, `PackageId`, `AssemblyName` and root namespace, with exact
`LANCommander` casing and no `.Plugin` suffix. Helpers/tests may append
`.Core`, `.Infrastructure`, `.Providers`, `.Transport` or `.Tests` (including
more focused test suffixes) to that component root and must remain non-packable.
Current component roots are:

- `LANCommander.Community.Server.Mcp`
- `LANCommander.Community.Server.RecompCatalog.*`
- `LANCommander.Community.Server.RecompCatalog`
- `LANCommander.Community.Server.Quake3` and its `.Core` / test projects
- `LANCommander.Community.Launcher.MQTT.*`
- `LANCommander.Community.Launcher.MQTT`

Keep the historical deployed package/assembly/plugin/configuration identities
stable unless a separately reviewed migration is explicitly authorized. Keep
Keep semantic plugin IDs, data IDs, configuration keys and protocol identities
stable. A package/assembly rename is a new feed identity and needs a new version
and explicit replacement instructions; never rewrite published versions. Keep
Home Assistant discovery as the HA-specific integration layer; Launcher.MQTT's
command/state protocol is usable by other MQTT clients too.

Before submitting changes, run the repository checks and the validation
command(s) for affected components from the root [README](README.md#build-and-validate).
See [Plugin releases](RELEASES.md) for versioning, packaging, and release
procedures. Repository-local agent guidance is under
[`.github/skills`](.github/skills/): plugin maintenance,
[`.github/skills`](.github/skills/):
[creating server plugins](.github/skills/create-server-plugin/SKILL.md),
[creating launcher plugins](.github/skills/create-launcher-plugin/SKILL.md),
[plugin maintenance](.github/skills/plugin-maintenance/SKILL.md),
[release preparation](.github/skills/plugin-release/SKILL.md), and
[authoring more skills](.github/skills/repository-skill-authoring/SKILL.md).

Expand Down
2 changes: 1 addition & 1 deletion Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
<Deterministic>true</Deterministic>
<ContinuousIntegrationBuild Condition="'$(CI)' == 'true'">true</ContinuousIntegrationBuild>
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
<RepositoryUrl>https://github.com/aaronpowell/LANCommander.Community</RepositoryUrl>
<RepositoryUrl>https://github.com/LANCommander/LANCommander.Community</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<Authors Condition="'$(Authors)' == ''">LANCommander Community contributors</Authors>
<IsPackable Condition="'$(IsPackable)' == ''">false</IsPackable>
Expand Down
4 changes: 2 additions & 2 deletions LANCommander.Community.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@
<Project Path="plugins/Server.Mcp/tests/LANCommander.Community.Server.Mcp.Tests/LANCommander.Community.Server.Mcp.Tests.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.Core/LANCommander.Community.Server.RecompCatalog.Core.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.Infrastructure/LANCommander.Community.Server.RecompCatalog.Infrastructure.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.Plugin/LANCommander.Community.Server.RecompCatalog.Plugin.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.Providers/LANCommander.Community.Server.RecompCatalog.Providers.csproj" />
<Project Path="plugins/Server.RecompCatalog/LANCommander.Community.Server.RecompCatalog.Tests/LANCommander.Community.Server.RecompCatalog.Tests.csproj" />
<Project Path="plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT.Core/LANCommander.Community.Launcher.MQTT.Core.csproj" />
<Project Path="plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT.Transport/LANCommander.Community.Launcher.MQTT.Transport.csproj" />
<Project Path="plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT.Plugin/LANCommander.Community.Launcher.MQTT.Plugin.csproj" />
<Project Path="plugins/Launcher.MQTT/src/LANCommander.Community.Launcher.MQTT/LANCommander.Community.Launcher.MQTT.csproj" />
<Project Path="plugins/Launcher.MQTT/tests/LANCommander.Community.Launcher.MQTT.Core.Tests/LANCommander.Community.Launcher.MQTT.Core.Tests.csproj" />
<Project Path="plugins/Launcher.MQTT/tests/LANCommander.Community.Launcher.MQTT.HostLoader.Tests/LANCommander.Community.Launcher.MQTT.HostLoader.Tests.csproj" />
</Solution>
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ focused build, test, and installation instructions.
- [Plugin release procedure](RELEASES.md) — versioning, validation, and
component release workflow.
- [Repository agent skills](.github/skills/) — focused `SKILL.md` guidance for
[creating server plugins](.github/skills/create-server-plugin/SKILL.md),
[creating launcher plugins](.github/skills/create-launcher-plugin/SKILL.md),
plugin maintenance, release preparation, and authoring more skills.

The community repository is independent and is not an official LANCommander
Expand Down
Loading
Loading