create-nextdevtpl 2.6.0

package/template/src/core/modules/contract.ts

@@ -0,0 +1,225 @@
+export const MODULE_IDS = [
+  "admin",
+  "analytics",
+  "auth",
+  "blog",
+  "credits",
+  "dashboard",
+  "mail",
+  "marketing",
+  "payment",
+  "pseo",
+  "settings",
+  "shared",
+  "storage",
+  "subscription",
+  "support",
+] as const;
+
+export type ModuleId = (typeof MODULE_IDS)[number];
+export type ModuleKind = "core" | "optional";
+export type ModuleNavigationArea = "dashboard" | "admin";
+export type ModuleNavigationIcon =
+  | "coins"
+  | "dashboard"
+  | "headset"
+  | "settings"
+  | "ticket"
+  | "users";
+export type ModuleSchemaGroup =
+  | "auth"
+  | "credits"
+  | "mail"
+  | "subscription"
+  | "support";
+
+export interface ModuleNavigationItem {
+  area: ModuleNavigationArea;
+  group: string;
+  groupTranslationKey: string;
+  translationKey: string;
+  href: string;
+  icon: ModuleNavigationIcon;
+  order: number;
+}
+
+export interface ModuleRoute {
+  path: string;
+  source: string;
+}
+
+export interface ModuleManifest {
+  id: ModuleId;
+  name: string;
+  description: string;
+  kind: ModuleKind;
+  dependencies: readonly ModuleId[];
+  routes: readonly ModuleRoute[];
+  navigation: readonly ModuleNavigationItem[];
+  translations: readonly string[];
+  schema: readonly ModuleSchemaGroup[];
+}
+
+export interface ModuleRegistry {
+  manifests: readonly ModuleManifest[];
+  byId: ReadonlyMap<ModuleId, ModuleManifest>;
+}
+
+export function defineModule<const T extends ModuleManifest>(manifest: T): T {
+  return manifest;
+}
+
+export function validateModuleManifests(
+  manifests: readonly ModuleManifest[]
+): string[] {
+  const errors: string[] = [];
+  const byId = new Map<ModuleId, ModuleManifest>();
+  const routeOwners = new Map<string, ModuleId>();
+  const routeSourceOwners = new Map<string, ModuleId>();
+  const navigationOwners = new Map<string, ModuleId>();
+  const schemaOwners = new Map<ModuleSchemaGroup, ModuleId>();
+  const translationOwners = new Map<string, ModuleId>();
+
+  for (const manifest of manifests) {
+    if (byId.has(manifest.id)) {
+      errors.push(`模块 ID 重复：${manifest.id}`);
+      continue;
+    }
+    byId.set(manifest.id, manifest);
+
+    for (const route of manifest.routes) {
+      const owner = routeOwners.get(route.path);
+      if (owner) {
+        errors.push(`路由 ${route.path} 同时属于 ${owner} 和 ${manifest.id}`);
+      } else {
+        routeOwners.set(route.path, manifest.id);
+      }
+
+      const sourceOwner = routeSourceOwners.get(route.source);
+      if (sourceOwner) {
+        errors.push(
+          `路由文件 ${route.source} 同时属于 ${sourceOwner} 和 ${manifest.id}`
+        );
+      } else {
+        routeSourceOwners.set(route.source, manifest.id);
+      }
+    }
+
+    for (const item of manifest.navigation) {
+      const key = `${item.area}:${item.href}`;
+      const owner = navigationOwners.get(key);
+      if (owner) {
+        errors.push(`菜单 ${key} 同时属于 ${owner} 和 ${manifest.id}`);
+      } else {
+        navigationOwners.set(key, manifest.id);
+      }
+    }
+
+    for (const group of manifest.schema) {
+      const owner = schemaOwners.get(group);
+      if (owner) {
+        errors.push(`Schema ${group} 同时属于 ${owner} 和 ${manifest.id}`);
+      } else {
+        schemaOwners.set(group, manifest.id);
+      }
+    }
+
+    for (const namespace of manifest.translations) {
+      const owner = translationOwners.get(namespace);
+      if (owner) {
+        errors.push(
+          `翻译命名空间 ${namespace} 同时属于 ${owner} 和 ${manifest.id}`
+        );
+      } else {
+        translationOwners.set(namespace, manifest.id);
+      }
+    }
+  }
+
+  for (const manifest of manifests) {
+    for (const dependency of manifest.dependencies) {
+      if (dependency === manifest.id) {
+        errors.push(`模块 ${manifest.id} 不能依赖自身`);
+      } else if (!byId.has(dependency)) {
+        errors.push(`模块 ${manifest.id} 依赖未注册模块 ${dependency}`);
+      } else if (
+        manifest.kind === "core" &&
+        byId.get(dependency)?.kind === "optional"
+      ) {
+        errors.push(`核心模块 ${manifest.id} 不能依赖可选模块 ${dependency}`);
+      }
+    }
+  }
+
+  const visiting = new Set<ModuleId>();
+  const visited = new Set<ModuleId>();
+
+  const visit = (id: ModuleId, path: readonly ModuleId[]) => {
+    if (visiting.has(id)) {
+      errors.push(`模块依赖存在循环：${[...path, id].join(" -> ")}`);
+      return;
+    }
+    if (visited.has(id)) {
+      return;
+    }
+
+    const manifest = byId.get(id);
+    if (!manifest) {
+      return;
+    }
+
+    visiting.add(id);
+    for (const dependency of manifest.dependencies) {
+      visit(dependency, [...path, id]);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  };
+
+  for (const id of byId.keys()) {
+    visit(id, []);
+  }
+
+  return errors;
+}
+
+export function createModuleRegistry(
+  manifests: readonly ModuleManifest[]
+): ModuleRegistry {
+  const errors = validateModuleManifests(manifests);
+  if (errors.length > 0) {
+    throw new Error(`模块注册失败：\n${errors.join("\n")}`);
+  }
+
+  return {
+    manifests,
+    byId: new Map(manifests.map((manifest) => [manifest.id, manifest])),
+  };
+}
+
+export function resolveModuleClosure(
+  registry: ModuleRegistry,
+  selectedIds: readonly ModuleId[]
+): ModuleId[] {
+  const resolved = new Set<ModuleId>();
+
+  const add = (id: ModuleId) => {
+    if (resolved.has(id)) {
+      return;
+    }
+    const manifest = registry.byId.get(id);
+    if (!manifest) {
+      throw new Error(`模块未注册：${id}`);
+    }
+    for (const dependency of manifest.dependencies) {
+      add(dependency);
+    }
+    resolved.add(id);
+  };
+
+  for (const id of selectedIds) {
+    add(id);
+  }
+
+  return [...resolved];
+}

package/template/src/core/modules/index.ts

@@ -0,0 +1 @@
+export * from "./contract";

package/template/src/core/services/ai.ts

@@ -0,0 +1,31 @@
+import type { AdapterDescriptor } from "./common";
+
+export type AIProviderName = "anthropic" | "openai-compatible" | "workers-ai";
+
+export interface AICapabilities {
+  jsonOutput: boolean;
+  streaming: boolean;
+  toolCalling: boolean;
+}
+
+export interface AIMessage {
+  content: string;
+  role: "assistant" | "system" | "user";
+}
+
+export interface AICompletionInput {
+  jsonMode?: boolean;
+  maxTokens?: number;
+  messages: readonly AIMessage[];
+  temperature?: number;
+}
+
+export interface AICompletionResult {
+  content: string;
+  model: string;
+}
+
+export interface AIAdapter
+  extends AdapterDescriptor<AIProviderName, AICapabilities> {
+  complete(input: AICompletionInput): Promise<AICompletionResult>;
+}

package/template/src/core/services/common.ts

@@ -0,0 +1,112 @@
+export type AdapterErrorCode =
+  | "authentication"
+  | "configuration"
+  | "invalid_request"
+  | "not_found"
+  | "rate_limited"
+  | "remote_failure"
+  | "signature_invalid"
+  | "unsupported";
+
+export interface AdapterDescriptor<
+  Provider extends string,
+  Capabilities extends object,
+> {
+  provider: Provider;
+  capabilities: Readonly<Capabilities>;
+}
+
+export class AdapterError extends Error {
+  readonly code: AdapterErrorCode;
+  readonly provider: string;
+  readonly retryable: boolean;
+
+  constructor(params: {
+    code: AdapterErrorCode;
+    message: string;
+    provider: string;
+    retryable?: boolean;
+    cause?: unknown;
+  }) {
+    super(
+      params.message,
+      params.cause === undefined ? undefined : { cause: params.cause }
+    );
+    this.name = "AdapterError";
+    this.code = params.code;
+    this.provider = params.provider;
+    this.retryable = params.retryable ?? false;
+  }
+}
+
+export function sanitizeAdapterMessage(
+  message: string,
+  secrets: readonly (string | undefined)[]
+): string {
+  return secrets.reduce<string>(
+    (sanitized, secret) =>
+      secret ? sanitized.replaceAll(secret, "[REDACTED]") : sanitized,
+    message
+  );
+}
+
+export function toAdapterError(params: {
+  code?: AdapterErrorCode;
+  error: unknown;
+  fallbackMessage: string;
+  provider: string;
+  retryable?: boolean;
+  secrets?: readonly (string | undefined)[];
+}): AdapterError {
+  if (params.error instanceof AdapterError) {
+    return params.error;
+  }
+
+  const rawMessage =
+    params.error instanceof Error
+      ? params.error.message
+      : params.fallbackMessage;
+  const message = sanitizeAdapterMessage(rawMessage, params.secrets ?? []);
+
+  const errorParams = {
+    code: params.code ?? "remote_failure",
+    message: message || params.fallbackMessage,
+    provider: params.provider,
+    cause: params.error,
+  };
+
+  return new AdapterError(
+    params.retryable === undefined
+      ? errorParams
+      : { ...errorParams, retryable: params.retryable }
+  );
+}
+
+export async function executeAdapterOperation<T>(params: {
+  operation: () => Promise<T>;
+  provider: string;
+  fallbackMessage: string;
+  retryable?: boolean;
+  secrets?: readonly (string | undefined)[];
+}): Promise<T> {
+  try {
+    return await params.operation();
+  } catch (error) {
+    throw toAdapterError({
+      error,
+      fallbackMessage: params.fallbackMessage,
+      provider: params.provider,
+      ...(params.retryable === undefined
+        ? {}
+        : { retryable: params.retryable }),
+      ...(params.secrets ? { secrets: params.secrets } : {}),
+    });
+  }
+}
+
+export type JsonPrimitive = boolean | number | string | null;
+export type JsonValue =
+  | JsonPrimitive
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+export type JsonObject = { readonly [key: string]: JsonValue };

package/template/src/core/services/index.ts

@@ -0,0 +1,8 @@
+export * from "./ai";
+export * from "./common";
+export * from "./jobs";
+export * from "./mail";
+export * from "./manifest";
+export * from "./payment";
+export * from "./rate-limit";
+export * from "./storage";

package/template/src/core/services/jobs.ts

@@ -0,0 +1,24 @@
+import type { AdapterDescriptor, JsonObject } from "./common";
+
+export type JobProvider = "cloudflare-workflows" | "inngest";
+
+export interface JobCapabilities {
+  durableSteps: boolean;
+  events: boolean;
+  scheduling: boolean;
+}
+
+export interface DispatchJobInput {
+  id?: string;
+  name: string;
+  payload: JsonObject;
+}
+
+export interface DispatchJobResult {
+  id: string;
+}
+
+export interface JobAdapter
+  extends AdapterDescriptor<JobProvider, JobCapabilities> {
+  dispatch(input: DispatchJobInput): Promise<DispatchJobResult>;
+}

package/template/src/core/services/mail.ts

@@ -0,0 +1,35 @@
+import type { AdapterDescriptor } from "./common";
+
+export type MailProvider = "cloudflare-email" | "disabled" | "resend" | "smtp";
+
+export interface MailCapabilities {
+  attachments: boolean;
+  batch: boolean;
+  transactional: boolean;
+}
+
+export interface MailAddress {
+  email: string;
+  name?: string;
+}
+
+export interface MailMessage {
+  bcc?: readonly string[];
+  cc?: readonly string[];
+  from: MailAddress;
+  html: string;
+  replyTo?: readonly string[];
+  subject: string;
+  text: string;
+  to: readonly string[];
+}
+
+export interface MailSendResult {
+  id?: string;
+  queued: boolean;
+}
+
+export interface MailAdapter
+  extends AdapterDescriptor<MailProvider, MailCapabilities> {
+  send(message: MailMessage): Promise<MailSendResult>;
+}

package/template/src/core/services/manifest.ts

@@ -0,0 +1,51 @@
+export const SERVICE_KINDS = [
+  "ai",
+  "jobs",
+  "mail",
+  "payment",
+  "rate-limit",
+  "storage",
+] as const;
+
+export type ServiceKind = (typeof SERVICE_KINDS)[number];
+export type AdapterRuntime = "node" | "universal" | "worker";
+
+export interface ServiceAdapterManifest {
+  bindings: readonly string[];
+  env: readonly string[];
+  id: string;
+  packages: readonly string[];
+  runtime: AdapterRuntime;
+  service: ServiceKind;
+  source: string;
+}
+
+export function defineServiceAdapter<const T extends ServiceAdapterManifest>(
+  manifest: T
+): T {
+  return manifest;
+}
+
+export function validateServiceAdapterManifests(
+  manifests: readonly ServiceAdapterManifest[]
+): string[] {
+  const errors: string[] = [];
+  const ids = new Set<string>();
+  const sources = new Set<string>();
+
+  for (const manifest of manifests) {
+    if (ids.has(manifest.id)) {
+      errors.push(`适配器 ID 重复：${manifest.id}`);
+    }
+    if (sources.has(manifest.source)) {
+      errors.push(`适配器源码重复登记：${manifest.source}`);
+    }
+    if (!manifest.id.startsWith(`${manifest.service}:`)) {
+      errors.push(`适配器 ${manifest.id} 必须使用 ${manifest.service}: 前缀`);
+    }
+    ids.add(manifest.id);
+    sources.add(manifest.source);
+  }
+
+  return errors;
+}

package/template/src/core/services/payment.ts

@@ -0,0 +1,92 @@
+import type { AdapterDescriptor, JsonObject } from "./common";
+
+export type PaymentProvider = "creem" | "stripe";
+export type PaymentStatus =
+  | "active"
+  | "canceled"
+  | "incomplete"
+  | "past_due"
+  | "paused"
+  | "trialing"
+  | "unpaid";
+export type PaymentWebhookType =
+  | "checkout.completed"
+  | "subscription.active"
+  | "subscription.canceled"
+  | "subscription.expired"
+  | "subscription.paid"
+  | "subscription.past_due"
+  | "subscription.paused"
+  | "subscription.renewed";
+
+export interface PaymentCapabilities {
+  customerPortal: boolean;
+  oneTimePayments: boolean;
+  subscriptions: boolean;
+  webhooks: boolean;
+}
+
+export interface PaymentCustomer {
+  id: string;
+  email?: string;
+  name?: string;
+}
+
+export interface PaymentSubscription {
+  id: string;
+  status: PaymentStatus;
+  productId: string;
+  customerId: string;
+  currentPeriodStart: Date | null;
+  currentPeriodEnd: Date | null;
+  cancelAtPeriodEnd: boolean;
+  metadata: Readonly<Record<string, string>>;
+}
+
+export interface PaymentCheckout {
+  id: string;
+  mode: "one-time" | "subscription";
+  productId: string;
+  customer: PaymentCustomer;
+  status: string;
+  subscription: PaymentSubscription | null;
+  metadata: Readonly<Record<string, string>>;
+}
+
+export interface CreateCheckoutInput {
+  cancelUrl?: string;
+  mode?: "one-time" | "subscription";
+  productId: string;
+  successUrl: string;
+  requestId?: string;
+  metadata?: Readonly<Record<string, string>>;
+}
+
+export interface CreateCheckoutResult {
+  id: string;
+  status: string;
+  url: string;
+}
+
+export interface VerifyPaymentWebhookInput {
+  payload: string;
+  signature: string;
+  secret?: string;
+}
+
+export interface PaymentWebhookEvent {
+  id: string;
+  type: PaymentWebhookType;
+  createdAt: Date;
+  checkout: PaymentCheckout | null;
+  subscription: PaymentSubscription | null;
+  rawMetadata: JsonObject;
+}
+
+export interface PaymentAdapter
+  extends AdapterDescriptor<PaymentProvider, PaymentCapabilities> {
+  createCheckout(input: CreateCheckoutInput): Promise<CreateCheckoutResult>;
+  getSubscription(id: string): Promise<PaymentSubscription>;
+  cancelSubscription(id: string): Promise<PaymentSubscription>;
+  verifyWebhook(input: VerifyPaymentWebhookInput): Promise<PaymentWebhookEvent>;
+}

package/template/src/core/services/rate-limit.ts

@@ -0,0 +1,47 @@
+import type { AdapterDescriptor } from "./common";
+
+export type RateLimitProvider = "cloudflare-rate-limit" | "noop" | "upstash";
+
+export interface RateLimitCapabilities {
+  dynamicRules: boolean;
+  preciseMetadata: boolean;
+}
+
+export interface RateLimitInput {
+  identifier: string;
+  limit: number;
+  namespace: string;
+  window: `${number}${"d" | "h" | "m" | "s"}`;
+}
+
+export interface RateLimitDecision {
+  limit: number | null;
+  remaining: number | null;
+  reset: number | null;
+  skipped: boolean;
+  success: boolean;
+}
+
+export interface RateLimitAdapter
+  extends AdapterDescriptor<RateLimitProvider, RateLimitCapabilities> {
+  limit(input: RateLimitInput): Promise<RateLimitDecision>;
+}
+
+export interface UsageQuotaInput {
+  identifier: string;
+  limit: number;
+  namespace: string;
+  windowSeconds: number;
+}
+
+export interface UsageQuotaDecision {
+  allowed: boolean;
+  remaining: number;
+  reset: number | null;
+}
+
+export interface UsageQuotaAdapter {
+  check(input: UsageQuotaInput): Promise<UsageQuotaDecision>;
+  increment(input: UsageQuotaInput): Promise<number>;
+  remaining(input: UsageQuotaInput): Promise<number>;
+}

package/template/src/core/services/storage.ts

@@ -0,0 +1,42 @@
+import type { AdapterDescriptor } from "./common";
+
+export type StorageProviderName = "r2-binding" | "s3-compatible";
+
+export interface StorageCapabilities {
+  directRead: boolean;
+  directWrite: boolean;
+  signedDownloadUrls: boolean;
+  signedUploadUrls: boolean;
+}
+
+export interface StorageObject {
+  body: Uint8Array;
+  contentType?: string;
+  etag?: string;
+}
+
+export interface StorageWriteInput {
+  body: ArrayBuffer | Blob | ReadableStream<Uint8Array> | Uint8Array | string;
+  bucket: string;
+  contentType?: string;
+  key: string;
+}
+
+export interface StorageUrlInput {
+  bucket: string;
+  expiresIn: number;
+  key: string;
+}
+
+export interface StorageUploadUrlInput extends StorageUrlInput {
+  contentType: string;
+}
+
+export interface StorageAdapter
+  extends AdapterDescriptor<StorageProviderName, StorageCapabilities> {
+  createDownloadUrl(input: StorageUrlInput): Promise<string>;
+  createUploadUrl(input: StorageUploadUrlInput): Promise<string>;
+  deleteObject(bucket: string, key: string): Promise<void>;
+  readObject(bucket: string, key: string): Promise<StorageObject | null>;
+  writeObject(input: StorageWriteInput): Promise<void>;
+}