refactor(buddy): move protocol + docs governance commands out of userland into core

.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 → 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 → 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 → 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)
   }
 

app/Commands/docs/generated-artifacts.ts → storage/framework/core/buddy/src/commands/docs/generated-artifacts.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)
     }
   }

app/Commands/docs/links.ts → storage/framework/core/buddy/src/commands/docs/links.ts

@@ -7,13 +7,13 @@
  * can reject a broken cross-reference. External links, mail/tel, and same-page
  * anchors are intentionally left alone.
  *
- * Usage: `bun app/Commands/docs/links.ts [--check]`
+ * Usage: `bun storage/framework/core/buddy/src/commands/docs/links.ts [--check]`
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const docsDir = resolve(root, 'docs')
 
 export interface BrokenDocLink {

storage/framework/core/buddy/src/commands/index.ts

@@ -13,6 +13,7 @@ export * from './create'
 export * from './deploy'
 export * from './dev'
 export * from './dns'
+export * from './docs'
 export * from './doctor'
 export * from './domains'
 export * from './email'
@@ -34,6 +35,7 @@ export * from './phone'
 export * from './ports'
 export * from './prepublish'
 export * from './projects'
+export * from './protocol'
 export * from './publish'
 export * from './queue'
 export * from './release'

app/Commands/Protocol.ts → storage/framework/core/buddy/src/commands/protocol.ts

@@ -11,107 +11,106 @@ 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/...`.
+ * Framework-repo `buddy protocol:*` commands. The governance tooling itself
+ * lives beside this file under `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`).
  */
-export default function (cli: CLI): void {
-  cli
+export function protocol(buddy: CLI): void {
+  buddy
     .command('protocol:conformance', 'Generate the Stacks protocol conformance report')
     .action(async () => {
       await runConformance()
     })
 
-  cli
+  buddy
     .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
+  buddy
     .command('protocol:check', 'Verify the vendored protocol suite is pinned + internally consistent')
     .action(async () => {
       await runTool(runSync, '--check')
     })
 
-  cli
+  buddy
     .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
+  buddy
     .command('protocol:manifest:check', 'Verify the protocol source manifest is current')
     .action(async () => {
       await runTool(runManifest, '--check')
     })
 
-  cli
+  buddy
     .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
+  buddy
     .command('protocol:release:check', 'Verify the protocol release manifest is current')
     .action(async () => {
       await runTool(runRelease, '--check')
     })
 
-  cli
+  buddy
     .command('protocol:drivers', 'Write the driver capability registry evidence')
     .action(async () => {
       await runTool(runDrivers, '--write')
     })
 
-  cli
+  buddy
     .command('protocol:drivers:check', 'Verify the driver capability registry evidence')
     .action(async () => {
       await runTool(runDrivers, '--check')
     })
 
-  cli
+  buddy
     .command('protocol:drivers:test', 'Run the driver contract suite')
     .action(async () => {
       await runTool(runDriverContracts)
     })
 
-  cli
+  buddy
     .command('protocol:desktop', 'Write the desktop support matrix evidence')
     .action(async () => {
       await runTool(runDesktop, '--write')
     })
 
-  cli
+  buddy
     .command('protocol:desktop:check', 'Verify the desktop support matrix evidence')
     .action(async () => {
       await runTool(runDesktop, '--check')
     })
 
-  cli
+  buddy
     .command('protocol:pantry', 'Write the pantry evidence')
     .action(async () => {
       await runTool(runPantry, '--write')
     })
 
-  cli
+  buddy
     .command('protocol:pantry:check', 'Verify the pantry evidence')
     .action(async () => {
       await runTool(runPantry, '--check')
     })
 
-  cli
+  buddy
     .command('protocol:craft', 'Write the Craft evidence')
     .action(async () => {
       await runTool(runCraft, '--write')
     })
 
-  cli
+  buddy
     .command('protocol:craft:check', 'Verify the Craft evidence')
     .action(async () => {
       await runTool(runCraft, '--check')

app/Commands/protocol/craft-evidence.ts → storage/framework/core/buddy/src/commands/protocol/craft-evidence.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const outputPath = resolve(root, '.github/protocol/evidence/craft.json')
 
 export const craftEvidence = {
@@ -87,7 +87,7 @@ export async function run(): Promise<void> {
     console.log(`Craft evidence pins ${craftEvidence.source.tag} at ${craftEvidence.source.revision}`)
   }
   else {
-    console.error('usage: bun app/Commands/protocol/craft-evidence.ts --write | --check')
+    console.error('usage: bun storage/framework/core/buddy/src/commands/protocol/craft-evidence.ts --write | --check')
     process.exit(2)
   }
 }

app/Commands/protocol/desktop-support.ts → storage/framework/core/buddy/src/commands/protocol/desktop-support.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { desktopSupportMatrix } from '../../../storage/framework/core/desktop/src/support'
+import { desktopSupportMatrix } from '../../../../desktop/src/support'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const outputPath = resolve(root, '.github/protocol/evidence/desktop-support.json')
 const document = {
   schemaVersion: '1.0.0',

app/Commands/protocol/desktop-workflow.test.ts → storage/framework/core/buddy/src/commands/protocol/desktop-workflow.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test'
 import { readdirSync, readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const workflow = readFileSync(resolve(root, '.github/workflows/desktop-lifecycle.yml'), 'utf8')
 const workflowDirectory = resolve(root, '.github/workflows')
 const repositoryWorkflows = readdirSync(workflowDirectory)

app/Commands/protocol/driver-registry.ts → storage/framework/core/buddy/src/commands/protocol/driver-registry.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { capabilityRegistry } from '../../../storage/framework/core/config/src/capabilities'
+import { capabilityRegistry } from '../../../../config/src/capabilities'
 
-const root = resolve(import.meta.dir, '../../..')
+const root = resolve(import.meta.dir, '../../../../../../..')
 const outputPath = resolve(root, '.github/protocol/evidence/drivers.json')
 
 function validate(): string[] {
@@ -64,7 +64,7 @@ export async function run(): Promise<void> {
     console.log(`Driver registry is current (${capabilityRegistry.length} records)`)
   }
   else {
-    console.error('usage: bun app/Commands/protocol/driver-registry.ts --write | --check')
+    console.error('usage: bun storage/framework/core/buddy/src/commands/protocol/driver-registry.ts --write | --check')
     process.exit(2)
   }
 }