@avelonjs/cli 0.1.0

package/src/driver-scaffold.ts

@@ -0,0 +1,524 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { snake, studly, writeln, type ReeveIO } from './io'
+
+/** One contract `reeve make:driver` can scaffold. */
+export interface DriverContractSpec {
+  /** Conformance suite export from `@avelonjs/conformance/suites`. */
+  suite: string
+  /** TypeScript type imported from `@avelonjs/core`. */
+  driverType: string
+  /** Extra type imports from `@avelonjs/core`. */
+  extraTypes: readonly string[]
+  /** Literal `capabilities` object. */
+  capabilities: string
+  /** Class method implementations. */
+  methods: string
+}
+
+const CONTRACTS: Record<string, DriverContractSpec> = {
+  database: {
+    suite: 'databaseSuite',
+    driverType: 'DatabaseDriver',
+    extraTypes: ['QueryIR', 'QueryResult', 'MigrationPlan', 'MigrationStatus'],
+    capabilities: `{
+    transactions: false,
+    rowSecurity: false,
+    maxRelationDepth: 1,
+    fullTextSearch: false,
+    upsert: false,
+    returning: false,
+    windowFunctions: false,
+    jsonOperators: false,
+  }`,
+    methods: `  async execute<TRow = Record<string, unknown>>(_query: QueryIR): Promise<QueryResult<TRow>> {
+    unimplemented('execute')
+  }
+
+  async rpc<TResult = unknown>(
+    _routine: string,
+    _args: Readonly<Record<string, unknown>>,
+  ): Promise<TResult> {
+    unimplemented('rpc')
+  }
+
+  async plan(): Promise<MigrationPlan> {
+    unimplemented('plan')
+  }
+
+  async apply(): Promise<readonly MigrationStatus[]> {
+    unimplemented('apply')
+  }
+
+  async rollback(_steps?: number): Promise<readonly MigrationStatus[]> {
+    unimplemented('rollback')
+  }
+
+  async status(): Promise<readonly MigrationStatus[]> {
+    unimplemented('status')
+  }`,
+  },
+  identity: {
+    suite: 'identitySuite',
+    driverType: 'IdentityDriver',
+    extraTypes: [],
+    capabilities: `{
+    passwords: false,
+    magicLinks: false,
+    oauth: false,
+    organizations: false,
+    mfa: [] as const,
+  }`,
+    methods: `  async user(): Promise<{ readonly id: string } | null> {
+    unimplemented('user')
+  }
+
+  async session(): Promise<{ readonly id: string } | null> {
+    unimplemented('session')
+  }
+
+  async signOut(): Promise<void> {
+    unimplemented('signOut')
+  }`,
+  },
+  social: {
+    suite: 'socialSuite',
+    driverType: 'SocialDriver',
+    extraTypes: ['SocialIdentity'],
+    capabilities: `{
+    providers: [] as const,
+  }`,
+    methods: `  async redirect(_provider: string, _callbackUrl: string, _state?: string): Promise<string> {
+    unimplemented('redirect')
+  }
+
+  async callback(
+    _provider: string,
+    _params: Readonly<Record<string, string>>,
+    _callbackUrl: string,
+  ): Promise<SocialIdentity> {
+    unimplemented('callback')
+  }`,
+  },
+  tokens: {
+    suite: 'tokensSuite',
+    driverType: 'TokenDriver',
+    extraTypes: ['IssuedToken', 'TokenIssueOptions', 'TokenRecord'],
+    capabilities: `{
+    abilities: false,
+    expiration: false,
+  }`,
+    methods: `  async verify(_plainText: string): Promise<TokenRecord> {
+    unimplemented('verify')
+  }
+
+  async issue(_name: string, _options?: TokenIssueOptions): Promise<IssuedToken> {
+    unimplemented('issue')
+  }
+
+  async list(): Promise<readonly TokenRecord[]> {
+    unimplemented('list')
+  }
+
+  async revoke(_id: string): Promise<void> {
+    unimplemented('revoke')
+  }`,
+  },
+  storage: {
+    suite: 'storageSuite',
+    driverType: 'StorageDriver',
+    extraTypes: ['StorageObject'],
+    capabilities: `{
+    signedUrls: false,
+    transforms: [] as const,
+  }`,
+    methods: `  async put(
+    _path: string,
+    _contents: Uint8Array | AsyncIterable<Uint8Array>,
+    _options?: { readonly contentType?: string },
+  ): Promise<StorageObject> {
+    unimplemented('put')
+  }
+
+  async get(_path: string): Promise<Uint8Array> {
+    unimplemented('get')
+  }
+
+  async delete(_path: string): Promise<void> {
+    unimplemented('delete')
+  }
+
+  async exists(_path: string): Promise<boolean> {
+    unimplemented('exists')
+  }`,
+  },
+  queue: {
+    suite: 'queueSuite',
+    driverType: 'QueueDriver',
+    extraTypes: ['QueueJob', 'QueueReceipt'],
+    capabilities: `{
+    delayed: false,
+    retries: false,
+    deadLetter: false,
+  }`,
+    methods: `  async enqueue<TPayload>(_job: QueueJob<TPayload>): Promise<string> {
+    unimplemented('enqueue')
+  }
+
+  async drain(
+    _handler: (receipt: QueueReceipt) => Promise<void>,
+    _options?: { readonly queue?: string; readonly limit?: number },
+  ): Promise<number> {
+    unimplemented('drain')
+  }`,
+  },
+  mail: {
+    suite: 'mailSuite',
+    driverType: 'MailDriver',
+    extraTypes: ['MailMessage', 'MailReceipt'],
+    capabilities: `{
+    templates: false,
+  }`,
+    methods: `  async send(_message: MailMessage): Promise<MailReceipt> {
+    unimplemented('send')
+  }`,
+  },
+  cache: {
+    suite: 'cacheSuite',
+    driverType: 'CacheDriver',
+    extraTypes: [],
+    capabilities: `{
+    tags: false,
+    locks: false,
+  }`,
+    methods: `  async get<TValue>(_key: string): Promise<TValue | null> {
+    unimplemented('get')
+  }
+
+  async put<TValue>(_key: string, _value: TValue, _ttlSeconds?: number): Promise<void> {
+    unimplemented('put')
+  }
+
+  async forget(_key: string): Promise<void> {
+    unimplemented('forget')
+  }
+
+  async flush(): Promise<void> {
+    unimplemented('flush')
+  }`,
+  },
+  realtime: {
+    suite: 'realtimeSuite',
+    driverType: 'RealtimeDriver',
+    extraTypes: ['RealtimeMessage', 'RealtimeSubscription'],
+    capabilities: `{
+    presence: false,
+    broadcast: false,
+  }`,
+    methods: `  async subscribe<TPayload = unknown>(
+    _channel: string,
+    _handler: (message: RealtimeMessage<TPayload>) => void | Promise<void>,
+  ): Promise<RealtimeSubscription> {
+    unimplemented('subscribe')
+  }`,
+  },
+  search: {
+    suite: 'searchSuite',
+    driverType: 'SearchDriver',
+    extraTypes: ['SearchDocument', 'SearchOptions', 'SearchResult'],
+    capabilities: `{
+    facets: false,
+  }`,
+    methods: `  async index(_name: string, _documents: readonly SearchDocument[]): Promise<void> {
+    unimplemented('index')
+  }
+
+  async remove(_name: string, _ids: readonly string[]): Promise<void> {
+    unimplemented('remove')
+  }
+
+  async query<TDocument extends SearchDocument = SearchDocument>(
+    _name: string,
+    _query: string,
+    _options?: SearchOptions,
+  ): Promise<SearchResult<TDocument>> {
+    unimplemented('query')
+  }`,
+  },
+  payments: {
+    suite: 'paymentsSuite',
+    driverType: 'PaymentDriver',
+    extraTypes: ['PaymentCustomer'],
+    capabilities: `{
+    subscriptions: false,
+    checkout: false,
+    webhooks: false,
+  }`,
+    methods: `  async createCustomer(_input: {
+    readonly email?: string
+    readonly metadata?: Readonly<Record<string, string>>
+  }): Promise<PaymentCustomer> {
+    unimplemented('createCustomer')
+  }
+
+  async customer(_id: string): Promise<PaymentCustomer> {
+    unimplemented('customer')
+  }`,
+  },
+  notifications: {
+    suite: 'notificationsSuite',
+    driverType: 'NotificationDriver',
+    extraTypes: ['NotificationChannel', 'NotificationMessage', 'NotificationReceipt'],
+    capabilities: `{
+    channels: [] as const,
+  }`,
+    methods: `  async send<TData>(
+    _channel: NotificationChannel,
+    _message: NotificationMessage<TData>,
+  ): Promise<NotificationReceipt> {
+    unimplemented('send')
+  }`,
+  },
+  flags: {
+    suite: 'flagsSuite',
+    driverType: 'FlagDriver',
+    extraTypes: ['FlagContext'],
+    capabilities: `{
+    targeting: false,
+  }`,
+    methods: `  async evaluate<TValue>(
+    _key: string,
+    _defaultValue: TValue,
+    _context?: FlagContext,
+  ): Promise<TValue> {
+    unimplemented('evaluate')
+  }`,
+  },
+  logs: {
+    suite: 'logsSuite',
+    driverType: 'LogDriver',
+    extraTypes: ['LogRecord'],
+    capabilities: `{
+    traces: false,
+  }`,
+    methods: `  async write(_record: LogRecord): Promise<void> {
+    unimplemented('write')
+  }`,
+  },
+  ratelimit: {
+    suite: 'ratelimitSuite',
+    driverType: 'RateLimitDriver',
+    extraTypes: ['RateLimitDecision', 'RateLimitPolicy'],
+    capabilities: `{
+    algorithms: [] as const,
+  }`,
+    methods: `  async consume(
+    _key: string,
+    _policy: RateLimitPolicy,
+    _cost?: number,
+  ): Promise<RateLimitDecision> {
+    unimplemented('consume')
+  }
+
+  async reset(_key: string): Promise<void> {
+    unimplemented('reset')
+  }`,
+  },
+  ai: {
+    suite: 'aiSuite',
+    driverType: 'AiDriver',
+    extraTypes: [],
+    capabilities: `{
+    modes: [] as const,
+    streaming: false,
+  }`,
+    methods: '',
+  },
+}
+
+/** Contract names `reeve make:driver` accepts. */
+export const DRIVER_CONTRACTS = Object.keys(CONTRACTS).sort()
+
+function unimplementedHelper(): string {
+  return `/** Throws until you implement the method. Never throw a NotSupportedError; omit the method and declare the capability false instead. */
+function unimplemented(method: string): never {
+  throw new Error(\`\${method} is unimplemented\`)
+}
+`
+}
+
+function driverSource(contract: string, slug: string, spec: DriverContractSpec): string {
+  const className = `${studly(slug)}${studly(contract)}`
+  const types = [spec.driverType, ...spec.extraTypes]
+  const typeImport = types.join(', ')
+  const methods = spec.methods.length > 0 ? `\n${spec.methods}\n` : '\n'
+  return `import type { ${typeImport} } from '@avelonjs/core'
+
+const capabilities = ${spec.capabilities} as const
+
+${unimplementedHelper()}
+/** ${studly(slug)} ${contract} driver. Capabilities start false; flip a key only when the method exists and conformance is green. */
+export class ${className} implements ${spec.driverType}<typeof capabilities, null> {
+  readonly name = '${snake(slug).replace(/_/g, '-')}'
+  readonly instance: string
+  readonly capabilities = capabilities
+
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  raw(): null {
+    return null
+  }
+${methods}}
+
+/** Constructs a ${contract} driver named ${slug}. */
+export function create${className}(instance = 'default'): ${className} {
+  return new ${className}(instance)
+}
+`
+}
+
+function indexSource(contract: string, slug: string): string {
+  const className = `${studly(slug)}${studly(contract)}`
+  return `export { create${className}, ${className} } from './driver'
+`
+}
+
+function testSource(contract: string, slug: string, spec: DriverContractSpec): string {
+  const className = `${studly(slug)}${studly(contract)}`
+  const factory = `create${className}`
+  return `import { ${spec.suite} } from '@avelonjs/conformance/suites'
+import { ${factory} } from '../src/index'
+
+${spec.suite}({
+  name: '${snake(slug).replace(/_/g, '-')} ${contract}',
+  create: () => ${factory}(),
+})
+`
+}
+
+function packageJson(slug: string): string {
+  const name = snake(slug).replace(/_/g, '-')
+  return `${JSON.stringify(
+    {
+      name: `@avelonjs/${name}`,
+      version: '0.0.0',
+      private: true,
+      type: 'module',
+      exports: { '.': './src/index.ts' },
+      scripts: { test: 'bun test', typecheck: 'tsc --noEmit' },
+      dependencies: { '@avelonjs/core': 'workspace:*' },
+      devDependencies: {
+        '@avelonjs/conformance': 'workspace:*',
+        '@types/bun': '1.3.14',
+        typescript: '5.9.3',
+      },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+function tsconfig(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'Preserve',
+        moduleResolution: 'bundler',
+        lib: ['ES2023'],
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        verbatimModuleSyntax: true,
+        isolatedModules: true,
+        skipLibCheck: true,
+        noEmit: true,
+        types: ['bun'],
+      },
+      include: ['src', 'tests'],
+    },
+    null,
+    2,
+  )}\n`
+}
+
+async function writeText(io: ReeveIO, relative: string, contents: string): Promise<void> {
+  const file = join(io.cwd, relative)
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, contents)
+  writeln(io, relative)
+}
+
+function readmeSource(contract: string, slug: string, spec: DriverContractSpec): string {
+  const className = `${studly(slug)}${studly(contract)}`
+  const factory = `create${className}`
+  const pkg = snake(slug).replace(/_/g, '-')
+  return `# @avelonjs/${pkg}
+
+${className} is a ${contract} driver. You certify it by running the shared \`${spec.suite}\` from \`@avelonjs/conformance\`. Reach for this package when application code needs ${contract} without importing a vendor SDK.
+
+## Installation
+
+\`\`\`sh
+bun add @avelonjs/${pkg}
+\`\`\`
+
+Wire it only in \`avelon.config.ts\`. Application folders never import a vendor client.
+
+## Basic Usage
+
+\`\`\`ts
+import { ${factory} } from '@avelonjs/${pkg}'
+
+export function makeDriver() {
+  return ${factory}('default')
+}
+\`\`\`
+
+## Capabilities
+
+Declare capabilities as a \`const\` object. Start every key \`false\` or empty. Flip a key to \`true\` only when the method exists and \`${spec.suite}\` is green. Implementing a method while leaving the capability \`false\` is a certification failure: someone will call it, and it will break when the driver is swapped. Never throw a \`NotSupportedError\`; omit the method instead.
+
+## Method Reference
+
+| Method / export | Signature | Description |
+|---|---|---|
+| \`${factory}\` | \`(instance?: string) => ${className}\` | Constructs the ${contract} driver. |
+| \`${className}\` | \`class ${className}\` | ${studly(slug)} ${contract} implementation. Capabilities start unavailable. |
+
+## Testing
+
+Run the shared suite. It is written from the contract, not from this package.
+
+\`\`\`ts
+import { ${spec.suite} } from '@avelonjs/conformance/suites'
+import { ${factory} } from '@avelonjs/${pkg}'
+
+${spec.suite}({
+  name: '${pkg} ${contract}',
+  create: () => ${factory}(),
+})
+\`\`\`
+
+\`\`\`sh
+bun test
+bun run typecheck
+reeve docs:check
+\`\`\`
+`
+}
+export async function makeDriver(io: ReeveIO, contract: string, slug: string): Promise<void> {
+  const spec = CONTRACTS[contract]
+  if (spec === undefined) {
+    throw new Error(`Unknown contract '${contract}'. Contracts: ${DRIVER_CONTRACTS.join(', ')}`)
+  }
+  const dir = `packages/${snake(slug)}`
+  await writeText(io, `${dir}/README.md`, readmeSource(contract, slug, spec))
+  await writeText(io, `${dir}/package.json`, packageJson(slug))
+  await writeText(io, `${dir}/tsconfig.json`, tsconfig())
+  await writeText(io, `${dir}/src/driver.ts`, driverSource(contract, slug, spec))
+  await writeText(io, `${dir}/src/index.ts`, indexSource(contract, slug))
+  await writeText(io, `${dir}/tests/${contract}.test.ts`, testSource(contract, slug, spec))
+}