refactor: migrate protocol + docs tooling into buddy commands

.github/workflows/ci.yml

@@ -174,8 +174,8 @@ jobs:
         env:
           PROTOCOL_REPORT_DIR: .github/protocol/reports
         run: |
-          bun test ./.github/scripts/protocol/run-conformance.test.ts
-          bun test ./.github/scripts/protocol/craft-evidence.test.ts ./.github/scripts/protocol/desktop-lifecycle-report.test.ts
+          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 ./.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/**
-      - .github/scripts/protocol/craft-evidence.ts
-      - .github/scripts/protocol/desktop-lifecycle-report.ts
+      - app/Commands/protocol/craft-evidence.ts
+      - app/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/**
-      - .github/scripts/protocol/craft-evidence.ts
-      - .github/scripts/protocol/desktop-lifecycle-report.ts
+      - app/Commands/protocol/craft-evidence.ts
+      - app/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 .github/scripts/protocol/desktop-lifecycle-report.ts
+          bun app/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,4 +28,6 @@ export type CommandRegistry = Record<string, string | CommandConfig>
  */
 export default {
   'inspire': 'Inspire',
+  'protocol': 'Protocol',
+  'docs': 'Docs',
 } satisfies CommandRegistry

app/Commands/Docs.ts

@@ -0,0 +1,48 @@
+import type { CLI } from '@stacksjs/types'
+import { run as runArtifacts } from './docs/generated-artifacts'
+import { run as runBuddyDocs } from './docs/buddy-commands'
+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,
+ * generated API artifacts (OpenAPI + types), and internal link checking.
+ */
+export default function (cli: CLI): void {
+  cli
+    .command('docs:buddy', 'Regenerate the buddy command reference doc')
+    .action(async () => {
+      await runTool(runBuddyDocs, '--write')
+    })
+
+  cli
+    .command('docs:buddy:check', 'Verify the buddy command reference doc is current')
+    .action(async () => {
+      await runTool(runBuddyDocs, '--check')
+    })
+
+  cli
+    .command('docs:artifacts', 'Regenerate the generated API artifacts (OpenAPI + types)')
+    .action(async () => {
+      await runTool(runArtifacts, '--write')
+    })
+
+  cli
+    .command('docs:artifacts:check', 'Verify the generated API artifacts are current')
+    .action(async () => {
+      await runTool(runArtifacts, '--check')
+    })
+
+  cli
+    .command('docs:links', 'Report internal documentation links')
+    .action(async () => {
+      await runTool(runLinks)
+    })
+
+  cli
+    .command('docs:links:check', 'Verify internal documentation links resolve')
+    .action(async () => {
+      await runTool(runLinks, '--check')
+    })
+}

app/Commands/Protocol.ts

@@ -0,0 +1,119 @@
+import type { CLI } from '@stacksjs/types'
+import { run as runConformance } from './protocol/run-conformance'
+import { run as runCraft } from './protocol/craft-evidence'
+import { run as runDesktop } from './protocol/desktop-support'
+import { run as runDrivers } from './protocol/driver-registry'
+import { run as runDriverContracts } from './protocol/run-driver-contracts'
+import { run as runPantry } from './protocol/pantry-evidence'
+import { run as runRelease } from './protocol/release-manifest'
+import { run as runManifest } from './protocol/source-manifest'
+import { run as runSync } from './protocol/sync-suite'
+import { runTool } from './run-tool'
+
+/**
+ * Repo-scoped `buddy protocol:*` commands. The governance tooling itself lives
+ * beside this file under `app/Commands/protocol/`; the protocol suite + evidence
+ * DATA stays under `.github/protocol/`. These wrap the tooling so it is
+ * discoverable via the CLI (`buddy protocol:conformance`) instead of a bare
+ * `bun app/Commands/protocol/...`.
+ */
+export default function (cli: CLI): void {
+  cli
+    .command('protocol:conformance', 'Generate the Stacks protocol conformance report')
+    .action(async () => {
+      await runConformance()
+    })
+
+  cli
+    .command('protocol:sync', 'Sync the vendored protocol suite from stacksjs/rfcs')
+    .option('--source <path>', 'Path to a local rfcs checkout', { default: undefined })
+    .action(async (options: { source?: string }) => {
+      await runTool(runSync, '--write', ...(options.source ? ['--source', options.source] : []))
+    })
+
+  cli
+    .command('protocol:check', 'Verify the vendored protocol suite is pinned + internally consistent')
+    .action(async () => {
+      await runTool(runSync, '--check')
+    })
+
+  cli
+    .command('protocol:manifest', 'Write the protocol source manifest')
+    .option('--revision <ref>', 'Source revision to pin (default HEAD)', { default: undefined })
+    .action(async (options: { revision?: string }) => {
+      await runTool(runManifest, '--write', ...(options.revision ? ['--revision', options.revision] : []))
+    })
+
+  cli
+    .command('protocol:manifest:check', 'Verify the protocol source manifest is current')
+    .action(async () => {
+      await runTool(runManifest, '--check')
+    })
+
+  cli
+    .command('protocol:release', 'Write the protocol release manifest')
+    .option('--tag <tag>', 'Release tag', { default: undefined })
+    .action(async (options: { tag?: string }) => {
+      await runTool(runRelease, '--write', ...(options.tag ? ['--tag', options.tag] : []))
+    })
+
+  cli
+    .command('protocol:release:check', 'Verify the protocol release manifest is current')
+    .action(async () => {
+      await runTool(runRelease, '--check')
+    })
+
+  cli
+    .command('protocol:drivers', 'Write the driver capability registry evidence')
+    .action(async () => {
+      await runTool(runDrivers, '--write')
+    })
+
+  cli
+    .command('protocol:drivers:check', 'Verify the driver capability registry evidence')
+    .action(async () => {
+      await runTool(runDrivers, '--check')
+    })
+
+  cli
+    .command('protocol:drivers:test', 'Run the driver contract suite')
+    .action(async () => {
+      await runTool(runDriverContracts)
+    })
+
+  cli
+    .command('protocol:desktop', 'Write the desktop support matrix evidence')
+    .action(async () => {
+      await runTool(runDesktop, '--write')
+    })
+
+  cli
+    .command('protocol:desktop:check', 'Verify the desktop support matrix evidence')
+    .action(async () => {
+      await runTool(runDesktop, '--check')
+    })
+
+  cli
+    .command('protocol:pantry', 'Write the pantry evidence')
+    .action(async () => {
+      await runTool(runPantry, '--write')
+    })
+
+  cli
+    .command('protocol:pantry:check', 'Verify the pantry evidence')
+    .action(async () => {
+      await runTool(runPantry, '--check')
+    })
+
+  cli
+    .command('protocol:craft', 'Write the Craft evidence')
+    .action(async () => {
+      await runTool(runCraft, '--write')
+    })
+
+  cli
+    .command('protocol:craft:check', 'Verify the Craft evidence')
+    .action(async () => {
+      await runTool(runCraft, '--check')
+    })
+}

.github/scripts/docs/buddy-commands.ts → app/Commands/docs/buddy-commands.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 .github/scripts/docs/buddy-commands.ts. Do not edit by hand. -->',
+    '<!-- Generated by app/Commands/docs/buddy-commands.ts. Do not edit by hand. -->',
     '',
     '# Buddy Command Reference',
     '',
@@ -125,10 +125,10 @@ export function loadBuddyInventory(): BuddyInventory {
   return inventory
 }
 
-if (import.meta.main) {
+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 .github/scripts/docs/buddy-commands.ts --write | --check')
+    console.error('usage: bun app/Commands/docs/buddy-commands.ts --write | --check')
     process.exit(2)
   }
 
@@ -145,3 +145,6 @@ if (import.meta.main) {
     console.log('Buddy command reference matches the runtime registry')
   }
 }
+
+if (import.meta.main)
+  await run()

.github/scripts/docs/generated-artifacts.ts → app/Commands/docs/generated-artifacts.ts

@@ -51,12 +51,12 @@ async function check(): Promise<void> {
   console.log(`Generated API artifacts are current (${Object.keys(JSON.parse(expected.openApi).paths).length} paths)`)
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   try {
     if (process.argv.includes('--write')) await write()
     else if (process.argv.includes('--check')) await check()
     else {
-      console.error('usage: bun .github/scripts/docs/generated-artifacts.ts --write | --check')
+      console.error('usage: bun app/Commands/docs/generated-artifacts.ts --write | --check')
       process.exit(2)
     }
   }
@@ -65,3 +65,6 @@ if (import.meta.main) {
     process.exit(1)
   }
 }
+
+if (import.meta.main)
+  await run()

.github/scripts/docs/links.ts → app/Commands/docs/links.ts

@@ -7,7 +7,7 @@
  * can reject a broken cross-reference. External links, mail/tel, and same-page
  * anchors are intentionally left alone.
  *
- * Usage: `bun .github/scripts/docs/links.ts [--check]`
+ * Usage: `bun app/Commands/docs/links.ts [--check]`
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
@@ -127,7 +127,7 @@ export function checkDocsLinks(docsRoot = docsDir): BrokenDocLink[] {
   return broken
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   const broken = checkDocsLinks()
   if (broken.length === 0) {
     console.log('✓ All internal documentation links resolve.')
@@ -140,3 +140,6 @@ if (import.meta.main) {
       process.exit(1)
   }
 }
+
+if (import.meta.main)
+  await run()

.github/scripts/protocol/craft-evidence.ts → app/Commands/protocol/craft-evidence.ts

@@ -73,7 +73,7 @@ function serializedEvidence(): string {
   return `${JSON.stringify(craftEvidence, null, 2)}\n`
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   const errors = validateCraftEvidence(craftEvidence)
   if (process.argv.includes('--write')) {
     if (errors.length) throw new Error(errors.join('\n'))
@@ -87,7 +87,10 @@ if (import.meta.main) {
     console.log(`Craft evidence pins ${craftEvidence.source.tag} at ${craftEvidence.source.revision}`)
   }
   else {
-    console.error('usage: bun .github/scripts/protocol/craft-evidence.ts --write | --check')
+    console.error('usage: bun app/Commands/protocol/craft-evidence.ts --write | --check')
     process.exit(2)
   }
 }
+
+if (import.meta.main)
+  await run()

.github/scripts/protocol/desktop-lifecycle-report.ts → app/Commands/protocol/desktop-lifecycle-report.ts

@@ -37,7 +37,7 @@ export function validateLifecycleReport(report: LifecycleReport, expected: {
   return errors
 }
 
-if (import.meta.main) {
+export async function run(): Promise<void> {
   const value = (name: string): string => {
     const index = process.argv.indexOf(name)
     const result = index === -1 ? undefined : process.argv[index + 1]
@@ -68,3 +68,6 @@ if (import.meta.main) {
   writeFileSync(outputPath, `${JSON.stringify(attestation, null, 2)}\n`)
   console.log(`Validated Craft lifecycle for ${expected.platform}/${expected.architecture}`)
 }
+
+if (import.meta.main)
+  await run()