refactor(buddy): move protocol + docs governance commands from userland into core (#2192)

The protocol-conformance and docs-freshness tooling lived under
app/Commands/{protocol,docs} (userland), but these are framework-repo core
commands, not app code. Move them into storage/framework/core/buddy/src/commands/
and register them through the core lazy-command loader + barrel, like every other
built-in command.

- git-mv the 27 tooling + test files, preserving history
- Protocol.ts/Docs.ts become named-export core registrars (protocol()/docs())
- 22 protocol:* / docs:* entries added to lazy-commands.ts; commands barrel updated
- fix repo-root path depth (import.meta.dir) + cross-package imports for the new
  location; update CI workflow + generated-doc paths
- app/Commands.ts drops the protocol/docs registrations (keeps the inspire example)
- fix 6 latent strict-null type errors the looser app/ tsconfig had hidden
  (regex-group / buffer-index access) so the tooling passes framework typecheck

Verified: framework typecheck clean in the moved files, lint clean, 48/48 moved
tests pass, buddy protocol:* / docs:* wire + run correctly.

protocol-conformance CI stays red on the pre-existing #2179 governance-evidence
drift (orphaned bf1245e pin), unrelated to this move.

Author: glennmichael123

.github/workflows/ci.yml

@@ -174,8 +174,8 @@ jobs:
         env:
           PROTOCOL_REPORT_DIR: .github/protocol/reports
         run: |
-          bun test ./app/Commands/protocol/run-conformance.test.ts
-          bun test ./app/Commands/protocol/craft-evidence.test.ts ./app/Commands/protocol/desktop-lifecycle-report.test.ts
+          bun test ./storage/framework/core/buddy/src/commands/protocol/run-conformance.test.ts
+          bun test ./storage/framework/core/buddy/src/commands/protocol/craft-evidence.test.ts ./storage/framework/core/buddy/src/commands/protocol/desktop-lifecycle-report.test.ts
           bun test ./.github/scripts/deploy/resolve-target.test.ts
           bun run protocol:drivers:test
           bun run protocol:conformance

.github/workflows/desktop-lifecycle.yml

@@ -5,16 +5,16 @@ on:
     branches: [main]
     paths:
       - storage/framework/core/desktop/**
-      - app/Commands/protocol/craft-evidence.ts
-      - app/Commands/protocol/desktop-lifecycle-report.ts
+      - storage/framework/core/buddy/src/commands/protocol/craft-evidence.ts
+      - storage/framework/core/buddy/src/commands/protocol/desktop-lifecycle-report.ts
       - .github/protocol/evidence/craft.json
       - .github/workflows/desktop-lifecycle.yml
   pull_request:
     branches: [main]
     paths:
       - storage/framework/core/desktop/**
-      - app/Commands/protocol/craft-evidence.ts
-      - app/Commands/protocol/desktop-lifecycle-report.ts
+      - storage/framework/core/buddy/src/commands/protocol/craft-evidence.ts
+      - storage/framework/core/buddy/src/commands/protocol/desktop-lifecycle-report.ts
       - .github/protocol/evidence/craft.json
       - .github/workflows/desktop-lifecycle.yml
   workflow_dispatch:
@@ -123,7 +123,7 @@ jobs:
 
       - name: Validate and attest lifecycle report
         run: >-
-          bun app/Commands/protocol/desktop-lifecycle-report.ts
+          bun storage/framework/core/buddy/src/commands/protocol/desktop-lifecycle-report.ts
           --report .craft-contract/artifacts/native-lifecycle/${{ matrix.name }}/report.json
           --output .github/protocol/reports/desktop/${{ matrix.name }}/attestation.json
           --revision "$CRAFT_SOURCE_REVISION"

app/Commands.ts

@@ -28,6 +28,4 @@ export type CommandRegistry = Record<string, string | CommandConfig>
  */
 export default {
   'inspire': 'Inspire',
-  'protocol': 'Protocol',
-  'docs': 'Docs',
 } satisfies CommandRegistry

docs/guide/buddy/commands.md

@@ -2,7 +2,7 @@
 title: Buddy Command Reference
 description: Generated reference for every Buddy command, argument, option, alias, default, and example.
 ---
-<!-- Generated by app/Commands/docs/buddy-commands.ts. Do not edit by hand. -->
+<!-- Generated by storage/framework/core/buddy/src/commands/docs/buddy-commands.ts. Do not edit by hand. -->
 
 # Buddy Command Reference
 

app/Commands/Docs.ts …ramework/core/buddy/src/commands/docs.tsapp/Commands/Docs.ts renamed to storage/framework/core/buddy/src/commands/docs.ts app/Commands/Docs.ts renamed to storage/framework/core/buddy/src/commands/docs.ts

@@ -5,42 +5,42 @@ import { run as runLinks } from './docs/links'
 import { runTool } from './run-tool'
 
 /**
- * Repo-scoped `buddy docs:*` commands wrapping the documentation-freshness
- * tooling under `app/Commands/docs/`: the generated buddy command reference,
+ * Framework-repo `buddy docs:*` commands wrapping the documentation-freshness
+ * tooling under `commands/docs/`: the generated buddy command reference,
  * generated API artifacts (OpenAPI + types), and internal link checking.
  */
-export default function (cli: CLI): void {
-  cli
+export function docs(buddy: CLI): void {
+  buddy
     .command('docs:buddy', 'Regenerate the buddy command reference doc')
     .action(async () => {
       await runTool(runBuddyDocs, '--write')
     })
 
-  cli
+  buddy
     .command('docs:buddy:check', 'Verify the buddy command reference doc is current')
     .action(async () => {
       await runTool(runBuddyDocs, '--check')
     })
 
-  cli
+  buddy
     .command('docs:artifacts', 'Regenerate the generated API artifacts (OpenAPI + types)')
     .action(async () => {
       await runTool(runArtifacts, '--write')
     })
 
-  cli
+  buddy
     .command('docs:artifacts:check', 'Verify the generated API artifacts are current')
     .action(async () => {
       await runTool(runArtifacts, '--check')
     })
 
-  cli
+  buddy
     .command('docs:links', 'Report internal documentation links')
     .action(async () => {
       await runTool(runLinks)
     })
 
-  cli
+  buddy
     .command('docs:links:check', 'Verify internal documentation links resolve')
     .action(async () => {
       await runTool(runLinks, '--check')

app/Commands/docs/buddy-commands.test.ts …src/commands/docs/buddy-commands.test.tsapp/Commands/docs/buddy-commands.test.ts renamed to storage/framework/core/buddy/src/commands/docs/buddy-commands.test.ts app/Commands/docs/buddy-commands.test.ts renamed to storage/framework/core/buddy/src/commands/docs/buddy-commands.test.ts

@@ -1,4 +1,4 @@
-import type { BuddyCommandInventoryEntry } from '../../../storage/framework/core/buddy/src/commands/list'
+import type { BuddyCommandInventoryEntry } from '../list'
 import { describe, expect, it } from 'bun:test'
 import { renderBuddyCommandReference } from './buddy-commands'
 

app/Commands/docs/buddy-commands.ts …uddy/src/commands/docs/buddy-commands.tsapp/Commands/docs/buddy-commands.ts renamed to storage/framework/core/buddy/src/commands/docs/buddy-commands.ts app/Commands/docs/buddy-commands.ts renamed to storage/framework/core/buddy/src/commands/docs/buddy-commands.ts

@@ -1,4 +1,4 @@
-import type { BuddyCommandInventoryEntry, BuddyCommandInventoryOption } from '../../../storage/framework/core/buddy/src/commands/list'
+import type { BuddyCommandInventoryEntry, BuddyCommandInventoryOption } from '../list'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 
@@ -7,7 +7,7 @@ interface BuddyInventory {
   total: number
 }
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const outputPath = resolve(root, 'docs/guide/buddy/commands.md')
 const cliPath = resolve(root, 'storage/framework/core/buddy/src/cli.ts')
 
@@ -89,7 +89,7 @@ export function renderBuddyCommandReference(inventory: BuddyInventory): string {
     'title: Buddy Command Reference',
     'description: Generated reference for every Buddy command, argument, option, alias, default, and example.',
     '---',
-    '<!-- Generated by app/Commands/docs/buddy-commands.ts. Do not edit by hand. -->',
+    '<!-- Generated by storage/framework/core/buddy/src/commands/docs/buddy-commands.ts. Do not edit by hand. -->',
     '',
     '# Buddy Command Reference',
     '',
@@ -128,7 +128,7 @@ export function loadBuddyInventory(): BuddyInventory {
 export async function run(): Promise<void> {
   const mode = process.argv.includes('--write') ? 'write' : process.argv.includes('--check') ? 'check' : null
   if (!mode) {
-    console.error('usage: bun app/Commands/docs/buddy-commands.ts --write | --check')
+    console.error('usage: bun storage/framework/core/buddy/src/commands/docs/buddy-commands.ts --write | --check')
     process.exit(2)
   }
 

…ommands/docs/generated-artifacts.test.ts …ommands/docs/generated-artifacts.test.tsapp/Commands/docs/generated-artifacts.test.ts renamed to storage/framework/core/buddy/src/commands/docs/generated-artifacts.test.ts app/Commands/docs/generated-artifacts.test.ts renamed to storage/framework/core/buddy/src/commands/docs/generated-artifacts.test.ts

@@ -1,9 +1,9 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { generateOpenApi } from '../../../storage/framework/core/api/src/generate-openapi'
-import { type OpenApiDocument, renderOpenApiTypes } from '../../../storage/framework/core/api/src/generate-types'
+import { generateOpenApi } from '../../../../api/src/generate-openapi'
+import { type OpenApiDocument, renderOpenApiTypes } from '../../../../api/src/generate-types'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const openApiPath = resolve(root, 'storage/framework/api/openapi.json')
 const apiTypesPath = resolve(root, 'storage/framework/api/api-types.ts')
 
@@ -56,7 +56,7 @@ export async function run(): Promise<void> {
     if (process.argv.includes('--write')) await write()
     else if (process.argv.includes('--check')) await check()
     else {
-      console.error('usage: bun app/Commands/docs/generated-artifacts.ts --write | --check')
+      console.error('usage: bun storage/framework/core/buddy/src/commands/docs/generated-artifacts.ts --write | --check')
       process.exit(2)
     }
   }