Scope preflight override to owned commands - #36

Problem

registerPreflight used the bare-function form:

api.registerPreflight((ctx) => { ... });

The SDK types this as PreflightOverride | ScopedPreflightOverrideDefinition and documents the scoped form as "a preflight handler invoked only for a declared command, or globally when unscoped." So the bare form registers a global override. Every pair of globally-scoped overrides genuinely contends, and pm health reports:

extension_preflight_override_collision:project:pm-github:project:pm-gantt-chart

With all six fleet packages installed together that is 15 pairwise warnings and ok: false. None of them actually contend — each only guards its own credentials for its own commands.

Fix

Use the scoped object form, declaring the command paths pm-github owns:

api.registerPreflight({
  commands: ["github sync", "github export", "github import", "gh-issues import", "github project import", "github project sync"],
  run: (ctx) => { ... },
});

Why full command paths, not top-level names

The runtime matches a command against the commands array by exact normalized path (entry.commands.includes(baseContext.command)), not by prefix. A bare top-level name like github never matches the real command github sync, so it would silently disable the early warning while still resolving the collision. The array therefore lists the full mutating command paths pm-github's isMutatingGithubCommand already recognizes.

The authoritative credential gate stays in the command handlers; this only narrows the override's scope so it no longer contends with other packages' overrides.

Verified before/after

• Before (two globally-scoped packages installed): pm health reported ok: false with one extension_preflight_override_collision warning.
• After (both scoped): pm health reported ok: true with zero collision warnings, and the guarded command still runs.

Also tested and rejected: adding contributions.commands to the manifest does not resolve the collision — only the scoped registerPreflight form does.

Checklist

• npm run release:check exits 0
• npm run changelog:check passes
• npx pm health --strict-exit exits 0
• Coverage did not decrease
• New test asserts the override is a scoped object with the exact owned command paths

pm item

• pm-github-yhhz

Summary by Sourcery

Scope the pm-github preflight override to its own mutating command paths to avoid collisions with other extensions.

Bug Fixes:

• Prevent global preflight override collisions reported by pm health by restricting pm-github's override to its owned commands.

Enhancements:

• Document the scoped preflight behavior and rationale in the extension source comments.
• Record the fix in the changelog and pm agent history/issue tracking files.

Tests:

• Add a smoke test that asserts the preflight override is registered as a scoped object with exactly the expected command paths.

Summary by cubic

Scopes pm-github’s registerPreflight override to its own mutating command paths to eliminate global collisions. Previously the bare-function form registered a global override that made pm health report extension_preflight_override_collision; now a scoped object lists exact command paths, preserving the early warning without contending with other packages.

• Uses exact normalized paths: "github sync", "github export", "github import", "gh-issues import", "github project import", "github project sync". Matching is exact; a top-level "github" would not match and would disable the warning. Adding contributions.commands does not resolve collisions.
• Behavior is otherwise unchanged: no network calls, no hard-blocking; authoritative validation remains in handlers. Health output goes from collision warnings to none.
• Test asserts the override is scoped with the expected commands.

^{Written for commit ef107a5. Summary will update on new commits.}