feat: add support for a template registry

Author: beeman

src/registry/registry.ts

@@ -0,0 +1,14 @@
+import { Registry, validateRegistry } from './validate-registry'
+
+export const defaultIndex = `https://raw.githubusercontent.com/solana-developers/solana-templates/refs/heads/main/index.json`
+export const solanaTemplatesIndex = process.env.SOLANA_TEMPLATES_INDEX ?? defaultIndex
+
+export async function getRegistry(): Promise<Registry> {
+  const result = await fetch(solanaTemplatesIndex)
+
+  if (!result.ok) {
+    throw new Error(`Failed to fetch registry index file: ${solanaTemplatesIndex}`)
+  }
+
+  return validateRegistry(await result.json())
+}

src/registry/validate-registry.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+// Template schema
+const registryTemplateSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  repository: z.string(),
+})
+
+// Group schema
+const registryGroupSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  templates: z.array(registryTemplateSchema),
+})
+
+// Section schema (default/legacy)
+const registrySectionSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  groups: z.array(registryGroupSchema),
+})
+
+// Main schema: requires 'default' and allows additional sections
+const registrySchema = z
+  .object({
+    default: registrySectionSchema, // 'default' is required
+  })
+  .catchall(registrySectionSchema) // Any other key is optional and must match registrySectionSchema
+
+// Type inference
+export type Registry = z.infer<typeof registrySchema>
+export type RegistrySection = z.infer<typeof registrySectionSchema>
+export type RegistryGroup = z.infer<typeof registryGroupSchema>
+export type RegistryTemplate = z.infer<typeof registryTemplateSchema>
+
+export async function validateRegistry(resultJson: unknown): Promise<Registry> {
+  return registrySchema.parse(resultJson)
+}

src/utils/get-args.ts

@@ -1,5 +1,8 @@
 import { intro, log, outro } from '@clack/prompts'
 import { program } from 'commander'
+import pico from 'picocolors'
+import { getRegistry } from '../registry/registry'
+import { Registry, RegistrySection } from '../registry/validate-registry'
 import { findTemplate, listTemplates, Template } from '../templates/templates'
 import { AppInfo } from './get-app-info'
 import { GetArgsResult } from './get-args-result'
@@ -20,6 +23,7 @@ export async function getArgs(argv: string[], app: AppInfo, pm: PackageManager =
     .option('-d, --dry-run', help('Dry run (default: false)'))
     .option('-t, --template <template-name>', help('Use a template'))
     .option('--list-templates', help('List available templates'))
+    .option('--list-registry', help('List the templates in the registry'))
     .option('--list-versions', help('Verify your versions of Anchor, AVM, Rust, and Solana'))
     .option('--skip-git', help('Skip git initialization'))
     .option('--skip-init', help('Skip running the init script'))
@@ -43,10 +47,16 @@ Examples:
   // Get the options from the command line
   const result = input.opts()
 
+  const registry = await getRegistry()
+
   if (result.listVersions) {
     listVersions()
     process.exit(0)
   }
+  if (result.listRegistry) {
+    listRegistry(registry)
+    process.exit(0)
+  }
   if (result.listTemplates) {
     listTemplates()
     outro(
@@ -121,3 +131,35 @@ function help(text: string) {
 
   ${text}`
 }
+
+function listRegistry(registry: Registry) {
+  const { default: defaultRegistry, ...otherRegistries } = registry
+
+  printRegistrySection(defaultRegistry)
+
+  const others = Object.keys(otherRegistries)
+
+  for (const key of others) {
+    printRegistrySection(otherRegistries[key])
+  }
+}
+
+function printRegistrySection(section: RegistrySection) {
+  console.log(` === ${section.id} === `)
+  console.log(`Name: ${section.name}`)
+  // console.log(`Description: ${section.description}`) // TODO: add description to index.json and the validation
+  console.log(`Groups: ${section.groups.length}`)
+
+  for (const group of section.groups) {
+    console.log(`  === ${group.id} === `)
+    console.log(`Name: ${group.name}`)
+    console.log(pico.gray(`Description: ${group.description}`))
+    console.log(pico.gray(`Templates: ${group.templates.length}`))
+
+    for (const template of group.templates) {
+      console.log(`    ${template.name}`)
+      console.log(pico.gray(`    Description: ${template.description}`))
+      console.log(pico.gray(`    Repository: ${template.repository}`))
+    }
+  }
+}