@downcity/city 0.2.17

package/bin/service/instruction.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 模块说明文档协议。
+ *
+ * 负责定义 City / Service / InstallableService 可共享的 instruction 能力，
+ * 以及 City 聚合输出时使用的格式化工具。
+ */
+import type { EnvRequirement, RouteAuth } from "./service.js";
+/**
+ * 模块说明生成时可访问的只读上下文。
+ */
+export interface InstructionContext {
+    /**
+     * 当前模块 ID。
+     */
+    id: string;
+    /**
+     * 当前模块展示名。
+     */
+    name: string;
+    /**
+     * 当前模块声明的环境变量要求。
+     */
+    env?: EnvRequirement[];
+    /**
+     * 当前模块暴露的动作列表。
+     */
+    actions: InstructionActionDefinition[];
+}
+/**
+ * City 聚合时看到的动作定义。
+ */
+export interface InstructionActionDefinition {
+    /**
+     * Action ID。
+     */
+    id: string;
+    /**
+     * HTTP 方法。
+     */
+    method: "GET" | "POST";
+    /**
+     * 鉴权要求。
+     */
+    auth: RouteAuth;
+}
+/**
+ * 模块可以提供的说明文档能力。
+ */
+export type InstructionDefinition = string | ((ctx: InstructionContext) => string | Promise<string>);
+/**
+ * 可选实现 instruction 的模块接口。
+ */
+export interface InstructionCapable {
+    /**
+     * 当前模块的说明文档。
+     */
+    instruction?: InstructionDefinition;
+}
+/**
+ * City 聚合输出的模块说明条目。
+ */
+export interface InstructionSection {
+    /**
+     * 模块 ID。
+     */
+    id: string;
+    /**
+     * 模块展示名。
+     */
+    name: string;
+    /**
+     * 模块分类。
+     */
+    kind: "service";
+    /**
+     * 动作定义。
+     */
+    actions: InstructionActionDefinition[];
+    /**
+     * 环境变量要求。
+     */
+    env?: EnvRequirement[];
+    /**
+     * 模块补充说明正文。
+     */
+    body?: string;
+}
+/**
+ * 解析模块 instruction。
+ */
+export declare function resolveInstruction(instruction: InstructionDefinition | undefined, ctx: InstructionContext): Promise<string | undefined>;
+/**
+ * 将动作鉴权配置格式化为可读文本。
+ */
+export declare function formatRouteAuth(auth: RouteAuth): string;
+/**
+ * 将模块说明聚合成纯文本。
+ */
+export declare function formatInstructionDocument(input: {
+    base: {
+        builtin_services: string[];
+        loaded_modules: string[];
+    };
+    sections: InstructionSection[];
+}): string;
+//# sourceMappingURL=instruction.d.ts.map

package/bin/service/instruction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction.d.ts","sourceRoot":"","sources":["../../src/service/instruction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAW,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,cAAc,EAAE,CAAC;IAEvB;;OAEG;IACH,OAAO,EAAE,2BAA2B,EAAE,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAEvB;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,CAAC,CAAC,GAAG,EAAE,kBAAkB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC;IAEhB;;OAEG;IACH,OAAO,EAAE,2BAA2B,EAAE,CAAC;IAEvC;;OAEG;IACH,GAAG,CAAC,EAAE,cAAc,EAAE,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,qBAAqB,GAAG,SAAS,EAC9C,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,IAAI,EAAE;QACJ,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC,GAAG,MAAM,CA2CT"}

package/bin/service/instruction.js

@@ -0,0 +1,70 @@
+/**
+ * 模块说明文档协议。
+ *
+ * 负责定义 City / Service / InstallableService 可共享的 instruction 能力，
+ * 以及 City 聚合输出时使用的格式化工具。
+ */
+/**
+ * 解析模块 instruction。
+ */
+export async function resolveInstruction(instruction, ctx) {
+    if (!instruction)
+        return undefined;
+    const content = typeof instruction === "function"
+        ? await instruction(ctx)
+        : instruction;
+    const normalized = String(content ?? "").trim();
+    return normalized || undefined;
+}
+/**
+ * 将动作鉴权配置格式化为可读文本。
+ */
+export function formatRouteAuth(auth) {
+    if (auth.length === 0)
+        return "guest | user | admin";
+    const levels = new Set(auth);
+    levels.add("admin");
+    return [...levels].join(" | ");
+}
+/**
+ * 将模块说明聚合成纯文本。
+ */
+export function formatInstructionDocument(input) {
+    const lines = [];
+    lines.push("# Downcity City Instruction");
+    lines.push("");
+    lines.push("## City");
+    lines.push("City 是 Downcity 的基础设施运行容器，负责挂载 Service、初始化内置 env/studios 能力、统一处理 /v1/* HTTP 路由，以及校验 user_token 与 admin_secret_key。");
+    lines.push("");
+    lines.push("基础使用：");
+    lines.push("1. 创建 City 实例。");
+    lines.push("2. 通过 city.use(...) 注册业务 Service、AIService 或带 install(ctx) 生命周期的服务。");
+    lines.push("3. 先调用 await city.health() 完成初始化。");
+    lines.push("4. 通过 city.router().fetch 或 city.handleRequest(...) 对外提供请求处理。");
+    lines.push("");
+    lines.push(`内置服务：${input.base.builtin_services.join(", ")}`);
+    lines.push(`当前已加载模块：${input.base.loaded_modules.join(", ")}`);
+    for (const section of input.sections) {
+        lines.push("");
+        lines.push(`## ${section.name} (${section.id})`);
+        lines.push(`类型：${section.kind}`);
+        if (section.env && section.env.length > 0) {
+            lines.push("环境变量：");
+            for (const item of section.env) {
+                lines.push(`- ${item.key} | ${item.required ? "required" : "optional"} | ${item.description}`);
+            }
+        }
+        if (section.actions.length > 0) {
+            lines.push("动作与路由：");
+            for (const action of section.actions) {
+                lines.push(`- ${action.method} /v1/${section.id}/${action.id} | auth: ${formatRouteAuth(action.auth)}`);
+            }
+        }
+        if (section.body) {
+            lines.push("说明：");
+            lines.push(section.body);
+        }
+    }
+    return lines.join("\n").trim();
+}
+//# sourceMappingURL=instruction.js.map

package/bin/service/instruction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction.js","sourceRoot":"","sources":["../../src/service/instruction.ts"],"names":[],"mappings":"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"}

package/bin/service/service.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Service — SDK 核心单元。
+ *
+ * 每个 Service = 一组 Action + 数据库表 + hook。
+ * Action 是 Service 的一等能力单元，可独立被 client 调用。
+ * Service 需要的基础设施（DB、Auth、Env）由 City 直接设为属性。
+ */
+import type { AnySQLiteTable } from "drizzle-orm/sqlite-core";
+import type { AnyPgTable } from "drizzle-orm/pg-core";
+import { Hook } from "./hook.js";
+import { Action, type ActionFn } from "./action.js";
+import type { CityTableApi } from "../store/table-api.js";
+import type { Database, DbClient } from "../store/db.js";
+import type { RuntimeUser } from "../core/auth/types.js";
+import type { Authenticator } from "../core/auth/authenticator.js";
+import type { EnvProvider } from "../core/runtime.js";
+import type { StudioStore } from "./studios/studio-store.js";
+import type { InstructionActionDefinition, InstructionCapable, InstructionDefinition } from "./instruction.js";
+/** 当前请求最终解析出的身份。 */
+export type RouteIdentity = "guest" | "user" | "admin";
+/** Action 可声明的可访问身份。空数组表示免登录。 */
+export type RouteAuth = Array<Exclude<RouteIdentity, "guest">>;
+export interface Context {
+    /** 请求参数（来自 client 的 input） */
+    input: Record<string, unknown>;
+    /** 本次请求在 hook / action 之间共享的临时上下文 */
+    locals: Record<string, unknown>;
+    /** 原始 HTTP Request，服务 webhook 等需要读取 header 时使用 */
+    request?: Request;
+    /** 原始请求 body 文本，服务 webhook 等需要验签时使用 */
+    raw_body?: string;
+    /** Action 执行结果（after 阶段可用） */
+    output?: unknown;
+    /** 当前用户（user_token 解析成功时可用） */
+    user?: RuntimeUser;
+    /** 当前请求身份 */
+    identity?: {
+        kind: RouteIdentity;
+    };
+    /** 所属 studio */
+    studio?: {
+        studio_id: string;
+        status: string;
+    };
+    /** 当前解析的 variant（如 AI model、翻译语言对等）。由 Service 自行注入 */
+    variant?: {
+        id: string;
+        name: string;
+        meta?: Record<string, unknown>;
+    };
+    /** Action 开始时间（框架自动填充） */
+    started_at?: Date;
+    /** Action 结束时间（框架自动填充） */
+    ended_at?: Date;
+    /** 异常对象（onError hook 可用，框架自动填充） */
+    error?: Error;
+    /** 当前 Service */
+    service?: {
+        id: string;
+        name: string;
+    };
+    /** 当前 Action */
+    action?: {
+        id: string;
+    };
+    /** 数据表（框架注入） */
+    db: Record<string, CityTableApi>;
+    /** 读环境变量（框架注入） */
+    env(key: string): string | undefined;
+}
+export interface EnvRequirement {
+    key: string;
+    description: string;
+    required: boolean;
+}
+export interface ActionOptions {
+    /** HTTP 方法，默认 POST */
+    method?: "GET" | "POST";
+    /** 允许访问该 action 的身份集合；默认 `["user"]`，传 `[]` 表示免登录 */
+    auth?: RouteAuth;
+}
+/**
+ * 归一化 action 鉴权配置。
+ *
+ * 关键说明（中文）
+ * - 默认值仍然是 `["user"]`
+ * - `[]` 表示 guest / user / admin 都可访问
+ * - 返回值会去重，方便 City 在路由层统一处理
+ */
+export declare function normalizeRouteAuth(auth?: RouteAuth): RouteAuth;
+export declare class Service {
+    readonly id: string;
+    readonly name: string;
+    /** Service 级 hook，该 Service 下所有 Action 共享 */
+    readonly hook: Hook;
+    readonly tables?: Record<string, AnySQLiteTable | AnyPgTable>;
+    readonly env?: EnvRequirement[];
+    /** 当前模块可选的说明文档。 */
+    instruction?: InstructionDefinition;
+    /** Action 注册表 */
+    private actionMap;
+    _db?: Database;
+    _client?: {
+        $client: DbClient;
+    };
+    _authenticator?: Authenticator;
+    _env?: EnvProvider;
+    _studioStore?: StudioStore;
+    /** 原始数据库实例（better-sqlite3 / D1 等） */
+    _raw?: unknown;
+    /** 服务公网 URL */
+    _baseURL?: string;
+    constructor(options: {
+        id: string;
+        name?: string;
+        tables?: Record<string, AnySQLiteTable | AnyPgTable>;
+        env?: EnvRequirement[];
+    });
+    _onInit(): Promise<void>;
+    /**
+     * 注册一个 Action（默认 POST，auth=["user"]）。
+     */
+    action(id: string, fn: ActionFn, opts?: ActionOptions): Action;
+    /** 获取已注册的 Action */
+    get(id: string): Action | undefined;
+    /** 列出所有已注册的 Action */
+    list(): Action[];
+    /** 列出 Action 及其元数据（City 内部使用） */
+    _listActionDefs(): Array<{
+        action: Action;
+        method: "GET" | "POST";
+        auth: RouteAuth;
+    }>;
+    /**
+     * 返回 instruction 聚合时使用的动作定义。
+     */
+    _listInstructionActions(): InstructionActionDefinition[];
+}
+export type InstructionService = Service & InstructionCapable;
+//# sourceMappingURL=service.d.ts.map

package/bin/service/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service/service.ts"],"names":[],"mappings":"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"}

package/bin/service/service.js

@@ -0,0 +1,94 @@
+/**
+ * Service — SDK 核心单元。
+ *
+ * 每个 Service = 一组 Action + 数据库表 + hook。
+ * Action 是 Service 的一等能力单元，可独立被 client 调用。
+ * Service 需要的基础设施（DB、Auth、Env）由 City 直接设为属性。
+ */
+import { Hook } from "./hook.js";
+import { Action } from "./action.js";
+/**
+ * 归一化 action 鉴权配置。
+ *
+ * 关键说明（中文）
+ * - 默认值仍然是 `["user"]`
+ * - `[]` 表示 guest / user / admin 都可访问
+ * - 返回值会去重，方便 City 在路由层统一处理
+ */
+export function normalizeRouteAuth(auth) {
+    if (auth === undefined)
+        return ["user"];
+    return [...new Set(auth)];
+}
+// ===========================================================================
+// Service
+// ===========================================================================
+export class Service {
+    id;
+    name;
+    /** Service 级 hook，该 Service 下所有 Action 共享 */
+    hook = new Hook();
+    tables;
+    env;
+    /** 当前模块可选的说明文档。 */
+    instruction;
+    /** Action 注册表 */
+    actionMap = new Map();
+    // ========== City 注入 ==========
+    _db;
+    _client;
+    _authenticator;
+    _env;
+    _studioStore;
+    /** 原始数据库实例（better-sqlite3 / D1 等） */
+    _raw;
+    /** 服务公网 URL */
+    _baseURL;
+    constructor(options) {
+        this.id = options.id;
+        this.name = options.name ?? options.id;
+        this.tables = options.tables;
+        this.env = options.env;
+    }
+    // ========== 生命周期 ==========
+    async _onInit() { }
+    // ========== Action 注册 ==========
+    /**
+     * 注册一个 Action（默认 POST，auth=["user"]）。
+     */
+    action(id, fn, opts) {
+        if (this.actionMap.has(id)) {
+            throw new Error(`Duplicate action: ${this.id}.${id}`);
+        }
+        const action = new Action(id, fn);
+        this.actionMap.set(id, {
+            action,
+            method: opts?.method ?? "POST",
+            auth: normalizeRouteAuth(opts?.auth),
+        });
+        return action;
+    }
+    /** 获取已注册的 Action */
+    get(id) {
+        return this.actionMap.get(id)?.action;
+    }
+    /** 列出所有已注册的 Action */
+    list() {
+        return [...this.actionMap.values()].map((e) => e.action);
+    }
+    /** 列出 Action 及其元数据（City 内部使用） */
+    _listActionDefs() {
+        return [...this.actionMap.values()];
+    }
+    /**
+     * 返回 instruction 聚合时使用的动作定义。
+     */
+    _listInstructionActions() {
+        return this._listActionDefs().map((item) => ({
+            id: item.action.id,
+            method: item.method,
+            auth: item.auth,
+        }));
+    }
+}
+//# sourceMappingURL=service.js.map

package/bin/service/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service/service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AA8EpD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,OAAO,OAAO;IACT,EAAE,CAAS;IACX,IAAI,CAAS;IACtB,6CAA6C;IACpC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IAClB,MAAM,CAA+C;IACrD,GAAG,CAAoB;IAChC,mBAAmB;IACnB,WAAW,CAAyB;IAEpC,iBAAiB;IACT,SAAS,GAAG,IAAI,GAAG,EAAuE,CAAC;IAEnG,gCAAgC;IAEhC,GAAG,CAAY;IACf,OAAO,CAAyB;IAChC,cAAc,CAAiB;IAC/B,IAAI,CAAe;IACnB,YAAY,CAAe;IAE3B,qCAAqC;IACrC,IAAI,CAAW;IAEf,eAAe;IACf,QAAQ,CAAU;IAElB,YAAY,OAKX;QACC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACzB,CAAC;IAED,6BAA6B;IAE7B,KAAK,CAAC,OAAO,KAAmB,CAAC;IAEjC,kCAAkC;IAElC;;OAEG;IACH,MAAM,CAAC,EAAU,EAAE,EAAY,EAAE,IAAoB;QACnD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE;YACrB,MAAM;YACN,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,MAAM;YAC9B,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC;SACrC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,oBAAoB;IACpB,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACxC,CAAC;IAED,sBAAsB;IACtB,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED,iCAAiC;IACjC,eAAe;QACb,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,uBAAuB;QACrB,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC3C,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE;YAClB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/bin/service/studios/schema.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Studio 数据库 schema 模块。
+ *
+ * 定义 Downcity 内置的 Studio 表结构（SQLite + Postgres）。
+ * Studio 是 City 多租户隔离的基本单位。
+ */
+/**
+ * 默认 SQLite Studio 表。
+ */
+export declare const sqliteStudios: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "studios";
+    schema: undefined;
+    columns: {
+        studio_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "studio_id";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "name";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        updated_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * 默认 Postgres Studio 表。
+ */
+export declare const pgStudios: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "studios";
+    schema: undefined;
+    columns: {
+        studio_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "studio_id";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        created_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updated_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "studios";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/bin/service/studios/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/service/studios/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBpB,CAAC"}