@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/admin/extensions.controller.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import type { KernelConfig } from "../config/schema.js";
+import type { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import type { ExtensionAdmin } from "../extensions/admin-view.js";
+import type { DeploymentConfigView, ExtensionDeploymentConfigService } from "../extensions/deployment-config.js";
+import type { ExtensionInstalls, PackageReview } from "../extensions/installs.js";
+import type { AdminExtensionView } from "../extensions/permission-view.js";
+import { type Principal } from "../identity/principal.js";
+declare const ApproveBody: z.ZodObject<{
+    sha256: z.ZodNullable<z.ZodString>;
+    reviewHash: z.ZodString;
+}, z.core.$strip>;
+declare const InstallBody: z.ZodObject<{
+    sha256: z.ZodString;
+}, z.core.$strip>;
+declare const ConfigBody: z.ZodObject<{
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+declare const NpmBody: z.ZodObject<{
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Deployment-level extension management (`/api/v1/admin/extensions/*`, enterprise admins): package
+ * import (upload / npm, returns the review), the extension list and detail, web permission approval
+ * (D8), install / enable / disable / uninstall (only writes the desired state and publishes
+ * `kernel.plugins.changed`; every replica reconciles, no restart; replicas may still be converging
+ * when the call returns).
+ */
+export declare class AdminExtensionsController {
+    private readonly installs;
+    private readonly admin;
+    private readonly ops;
+    private readonly deploymentConfigs;
+    private readonly kernelConfig;
+    constructor(installs: ExtensionInstalls, admin: ExtensionAdmin, ops: ExtensionAdminOps, deploymentConfigs: ExtensionDeploymentConfigService, kernelConfig: () => KernelConfig);
+    /**
+     * 部署上的全部插件（内置、配置声明、安装记录）及其状态、权限与快照；`drainSeconds` 为停用 / 升级时
+     * 在途工具调用最多等待的秒数（`extensionHost.drainSeconds`，界面提示用）。
+     */
+    list(): Promise<{
+        extensions: AdminExtensionView[];
+        drainSeconds: number;
+    }>;
+    /** A single extension; unknown -> 404 `extension.not_found`. */
+    get(name: string): Promise<AdminExtensionView>;
+    /**
+     * Deployment config (D8 / C10): each field's source (read-only from file / Nacos / env), the
+     * effective value (secrets only say whether they are set), the JSON Schema and the validation
+     * result. Unknown -> 404 `extension.not_found`.
+     */
+    config(name: string): Promise<DeploymentConfigView>;
+    /**
+     * Saves the deployment config (`values` keyed by field dot path; `null` clears, omitted keeps).
+     * A field present in the startup config -> 409 `extension.config_readonly`; unknown or invalid
+     * -> 400 `extension.config_invalid` (values not echoed). A problem in a read-only field itself
+     * (a value from the startup config) does not block the PUT: it saves anyway, the extension stays
+     * pending configuration and the startup config has to change. Every replica re-reads after saving:
+     * hot fields are replaced in place, other fields reload the extension, and a pending extension
+     * loads (no restart).
+     */
+    putConfig(principal: Principal, name: string, body: z.infer<typeof ConfigBody>): Promise<DeploymentConfigView>;
+    /**
+     * Web approval: writes the snapshot (source web), audits `extension.permissions_approved` and
+     * publishes `kernel.plugins.changed`. Package or
+     * permissions changed after the review -> 409 `extension.approval_stale`; nothing to approve ->
+     * 409 `extension.not_pending`.
+     */
+    approve(principal: Principal, name: string, body: z.infer<typeof ApproveBody>): Promise<AdminExtensionView>;
+    /**
+     * New install or version change (upgrade / downgrade): the install record points at `sha256` in the
+     * package store; the desired state is unchanged (a new install is disabled).
+     * Config-declared -> 409 `extension.config_declared`; package
+     * missing -> 404 `extension.package_not_found`; extension name in the package differs -> 409
+     * `extension.name_mismatch`; an extension of the same name comes from another npm package -> 409
+     * `extension.name_conflict`; downgrade to a version with unrun migrations -> 409
+     * `extension.downgrade_unsupported`.
+     */
+    install(principal: Principal, name: string, body: z.infer<typeof InstallBody>): Promise<AdminExtensionView>;
+    /** Enable on the deployment; not installed -> 404 `extension.not_found`; config-declared -> 409. */
+    enable(principal: Principal, name: string): Promise<AdminExtensionView>;
+    /**
+     * 部署上停用（各副本排空在途调用后卸下）；未安装 → 404；配置声明 → 409；必需的引导插件 → 409
+     * `extension.required`。
+     */
+    disable(principal: Principal, name: string): Promise<AdminExtensionView>;
+    /** Uninstall (must be disabled first, otherwise 409 `extension.not_disabled`); data is kept. */
+    uninstall(principal: Principal, name: string): Promise<void>;
+    /**
+     * Uploads an extension package (the body is the raw tgz bytes, `application/octet-stream`, limit
+     * `packages.maxBytes`). Invalid package -> 400 `extension.package_invalid` (details list each
+     * problem); over the limit -> 413; same name as a config-declared extension -> 409.
+     */
+    uploadFile(principal: Principal, req: {
+        body?: unknown;
+    }): Promise<PackageReview>;
+    /** 从配置的 npm registry 拉取（`version` 可以是版本、dist-tag 或范围，缺省 latest）。下载失败 → 502。 */
+    fromNpm(principal: Principal, body: z.infer<typeof NpmBody>): Promise<PackageReview>;
+}
+export {};

package/dist/admin/extensions.controller.js

@@ -0,0 +1,226 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { EXTENSION_ADMIN, EXTENSION_ADMIN_OPS, EXTENSION_DEPLOYMENT_CONFIGS, EXTENSION_INSTALLS, KERNEL_CONFIG, } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+const ApproveBody = z.object({
+    /** 安装记录的包（审阅时的 sha256）；配置声明的插件为 null。 */
+    sha256: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .nullable(),
+    reviewHash: z.string().regex(/^[0-9a-f]{16}$/),
+});
+const InstallBody = z.object({
+    /** 包存储里的包（上传 / npm 导入返回的 sha256）。 */
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+const ConfigBody = z.object({
+    /** 字段点路径 → 新值（`null` 清除）。 */
+    values: z.record(z.string().min(1).max(256), z.unknown()),
+});
+const NpmBody = z.object({
+    package: z.string().min(1).max(214),
+    version: z.string().min(1).max(256).optional(),
+});
+/**
+ * Deployment-level extension management (`/api/v1/admin/extensions/*`, enterprise admins): package
+ * import (upload / npm, returns the review), the extension list and detail, web permission approval
+ * (D8), install / enable / disable / uninstall (only writes the desired state and publishes
+ * `kernel.plugins.changed`; every replica reconciles, no restart; replicas may still be converging
+ * when the call returns).
+ */
+let AdminExtensionsController = class AdminExtensionsController {
+    installs;
+    admin;
+    ops;
+    deploymentConfigs;
+    kernelConfig;
+    constructor(installs, admin, ops, deploymentConfigs, 
+    // 字段名不能与路由方法同名（如 `config`）：实例字段会遮住原型上的处理函数
+    kernelConfig) {
+        this.installs = installs;
+        this.admin = admin;
+        this.ops = ops;
+        this.deploymentConfigs = deploymentConfigs;
+        this.kernelConfig = kernelConfig;
+    }
+    /**
+     * 部署上的全部插件（内置、配置声明、安装记录）及其状态、权限与快照；`drainSeconds` 为停用 / 升级时
+     * 在途工具调用最多等待的秒数（`extensionHost.drainSeconds`，界面提示用）。
+     */
+    async list() {
+        return {
+            extensions: await this.admin.list(),
+            drainSeconds: this.kernelConfig().extensionHost.drainSeconds,
+        };
+    }
+    /** A single extension; unknown -> 404 `extension.not_found`. */
+    get(name) {
+        return this.admin.get(name);
+    }
+    /**
+     * Deployment config (D8 / C10): each field's source (read-only from file / Nacos / env), the
+     * effective value (secrets only say whether they are set), the JSON Schema and the validation
+     * result. Unknown -> 404 `extension.not_found`.
+     */
+    config(name) {
+        return this.deploymentConfigs.view(name);
+    }
+    /**
+     * Saves the deployment config (`values` keyed by field dot path; `null` clears, omitted keeps).
+     * A field present in the startup config -> 409 `extension.config_readonly`; unknown or invalid
+     * -> 400 `extension.config_invalid` (values not echoed). A problem in a read-only field itself
+     * (a value from the startup config) does not block the PUT: it saves anyway, the extension stays
+     * pending configuration and the startup config has to change. Every replica re-reads after saving:
+     * hot fields are replaced in place, other fields reload the extension, and a pending extension
+     * loads (no restart).
+     */
+    putConfig(principal, name, body) {
+        const actor = requireUser(principal);
+        return this.deploymentConfigs.put(name, body.values, actor.account.id, patTokenId(actor));
+    }
+    /**
+     * Web approval: writes the snapshot (source web), audits `extension.permissions_approved` and
+     * publishes `kernel.plugins.changed`. Package or
+     * permissions changed after the review -> 409 `extension.approval_stale`; nothing to approve ->
+     * 409 `extension.not_pending`.
+     */
+    async approve(principal, name, body) {
+        const actor = requireUser(principal);
+        const tokenId = patTokenId(actor);
+        return this.admin.approve(actor.account.id, name, body, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+    }
+    /**
+     * New install or version change (upgrade / downgrade): the install record points at `sha256` in the
+     * package store; the desired state is unchanged (a new install is disabled).
+     * Config-declared -> 409 `extension.config_declared`; package
+     * missing -> 404 `extension.package_not_found`; extension name in the package differs -> 409
+     * `extension.name_mismatch`; an extension of the same name comes from another npm package -> 409
+     * `extension.name_conflict`; downgrade to a version with unrun migrations -> 409
+     * `extension.downgrade_unsupported`.
+     */
+    install(principal, name, body) {
+        const actor = requireUser(principal);
+        return this.ops.install(name, body.sha256, actor.account.id, patTokenId(actor));
+    }
+    /** Enable on the deployment; not installed -> 404 `extension.not_found`; config-declared -> 409. */
+    enable(principal, name) {
+        const actor = requireUser(principal);
+        return this.ops.enable(name, actor.account.id, patTokenId(actor));
+    }
+    /**
+     * 部署上停用（各副本排空在途调用后卸下）；未安装 → 404；配置声明 → 409；必需的引导插件 → 409
+     * `extension.required`。
+     */
+    disable(principal, name) {
+        const actor = requireUser(principal);
+        return this.ops.disable(name, actor.account.id, patTokenId(actor));
+    }
+    /** Uninstall (must be disabled first, otherwise 409 `extension.not_disabled`); data is kept. */
+    async uninstall(principal, name) {
+        const actor = requireUser(principal);
+        await this.ops.uninstall(name, actor.account.id, patTokenId(actor));
+    }
+    /**
+     * Uploads an extension package (the body is the raw tgz bytes, `application/octet-stream`, limit
+     * `packages.maxBytes`). Invalid package -> 400 `extension.package_invalid` (details list each
+     * problem); over the limit -> 413; same name as a config-declared extension -> 409.
+     */
+    async uploadFile(principal, req) {
+        const actor = requireUser(principal);
+        const body = req.body;
+        if (!Buffer.isBuffer(body) || body.byteLength === 0) {
+            throw new ApiError("unsupported_media_type", "Send the extension package (.tgz) as the request body with content-type application/octet-stream");
+        }
+        const tokenId = patTokenId(actor);
+        return this.installs.ingestFile(actor.account.id, new Uint8Array(body.buffer, body.byteOffset, body.byteLength), tokenId !== undefined ? { actorTokenId: tokenId } : {});
+    }
+    /** 从配置的 npm registry 拉取（`version` 可以是版本、dist-tag 或范围，缺省 latest）。下载失败 → 502。 */
+    async fromNpm(principal, body) {
+        const actor = requireUser(principal);
+        const tokenId = patTokenId(actor);
+        return this.installs.ingestNpm(actor.account.id, { package: body.package, ...(body.version !== undefined && { version: body.version }) }, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+    }
+};
+__decorate([
+    Get()
+], AdminExtensionsController.prototype, "list", null);
+__decorate([
+    Get(":name"),
+    __param(0, Param("name"))
+], AdminExtensionsController.prototype, "get", null);
+__decorate([
+    Get(":name/config"),
+    __param(0, Param("name"))
+], AdminExtensionsController.prototype, "config", null);
+__decorate([
+    Put(":name/config"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name")),
+    __param(2, Body(new ZodPipe(ConfigBody)))
+], AdminExtensionsController.prototype, "putConfig", null);
+__decorate([
+    Post(":name/approve"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name")),
+    __param(2, Body(new ZodPipe(ApproveBody)))
+], AdminExtensionsController.prototype, "approve", null);
+__decorate([
+    Post(":name/install"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name")),
+    __param(2, Body(new ZodPipe(InstallBody)))
+], AdminExtensionsController.prototype, "install", null);
+__decorate([
+    Post(":name/enable"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name"))
+], AdminExtensionsController.prototype, "enable", null);
+__decorate([
+    Post(":name/disable"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name"))
+], AdminExtensionsController.prototype, "disable", null);
+__decorate([
+    Delete(":name"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("name"))
+], AdminExtensionsController.prototype, "uninstall", null);
+__decorate([
+    Post("packages/file"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Req())
+], AdminExtensionsController.prototype, "uploadFile", null);
+__decorate([
+    Post("packages/npm"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(NpmBody)))
+], AdminExtensionsController.prototype, "fromNpm", null);
+AdminExtensionsController = __decorate([
+    Controller("api/v1/admin/extensions"),
+    EnterpriseAdmin(),
+    __param(0, Inject(EXTENSION_INSTALLS)),
+    __param(1, Inject(EXTENSION_ADMIN)),
+    __param(2, Inject(EXTENSION_ADMIN_OPS)),
+    __param(3, Inject(EXTENSION_DEPLOYMENT_CONFIGS)),
+    __param(4, Inject(KERNEL_CONFIG))
+], AdminExtensionsController);
+export { AdminExtensionsController };

package/dist/admin/setup.controller.d.ts

@@ -0,0 +1,36 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import type { KernelConfig } from "../config/schema.js";
+import type { Account } from "../identity/accounts.js";
+import type { LoginRateLimiter } from "../identity/rate-limit.js";
+import type { SessionService } from "../identity/sessions.js";
+import type { Org } from "../orgs/orgs.service.js";
+import type { SetupService } from "./setup.service.js";
+declare const SetupBody: z.ZodObject<{
+    login: z.ZodString;
+    password: z.ZodString;
+    displayName: z.ZodString;
+    orgName: z.ZodOptional<z.ZodString>;
+    setupToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** 初始化向导（`/api/v1/setup`，均为公开路由）。 */
+export declare class SetupController {
+    private readonly setup;
+    private readonly sessions;
+    private readonly config;
+    private readonly limiter;
+    constructor(setup: SetupService, sessions: SessionService, config: () => KernelConfig, limiter: LoginRateLimiter);
+    status(): Promise<{
+        needsSetup: boolean;
+    }>;
+    /**
+     * 建首个企业管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
+     * 配置了 `auth.setupToken` 时 body 中的 `setupToken` 必须与之相等，否则 `setup.token_invalid`；
+     * 核对前先占用限流额度，超限 → 429 `auth.rate_limited`，核对通过后退还。
+     */
+    complete(body: z.infer<typeof SetupBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        account: Account;
+        org?: Org;
+    }>;
+}
+export {};

package/dist/admin/setup.controller.js

@@ -0,0 +1,106 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash, timingSafeEqual } from "node:crypto";
+import { Body, Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { KERNEL_CONFIG, RATE_LIMITER, SESSIONS, SETUP } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { clientMeta } from "../identity/auth.controller.js";
+import { setSessionCookies } from "../identity/cookies.js";
+import { MAX_PASSWORD_LENGTH } from "../identity/login.js";
+import { Public } from "../identity/principal.js";
+const SetupBody = z.object({
+    login: z.string().min(1).max(64),
+    password: z.string().min(1).max(MAX_PASSWORD_LENGTH),
+    displayName: z.string().trim().min(1).max(100),
+    orgName: z.string().max(100).optional(),
+    setupToken: z.string().max(1024).optional(),
+});
+/**
+ * 初始化令牌的限流（scope `setup`）：同一客户端 IP 10 次、全部署合计 100 次 / 900s
+ * （合计上限防换 IP 爆破；令牌本身应足够长，正常情况下打不满）。
+ */
+const SETUP_TOKEN_LIMIT_TOTAL = 100;
+const SETUP_TOKEN_LIMIT_PER_IP = 10;
+const sha256 = (s) => createHash("sha256").update(s, "utf8").digest();
+/** 常数时间比较：两边先取 SHA-256，长度恒等，不因长度不同提前返回或抛错。 */
+function tokenMatches(given, expected) {
+    return timingSafeEqual(sha256(given ?? ""), sha256(expected)) && given !== undefined;
+}
+/** 初始化向导（`/api/v1/setup`，均为公开路由）。 */
+let SetupController = class SetupController {
+    setup;
+    sessions;
+    config;
+    limiter;
+    constructor(setup, sessions, config, limiter) {
+        this.setup = setup;
+        this.sessions = sessions;
+        this.config = config;
+        this.limiter = limiter;
+    }
+    async status() {
+        return this.setup.status();
+    }
+    /**
+     * 建首个企业管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
+     * 配置了 `auth.setupToken` 时 body 中的 `setupToken` 必须与之相等，否则 `setup.token_invalid`；
+     * 核对前先占用限流额度，超限 → 429 `auth.rate_limited`，核对通过后退还。
+     */
+    async complete(body, req, reply) {
+        const cfg = this.config();
+        const expected = cfg.auth.setupToken;
+        if (expected !== undefined) {
+            const { ip } = clientMeta(req);
+            const rl = await this.limiter.reserveScoped("setup", "token", ip, SETUP_TOKEN_LIMIT_TOTAL, SETUP_TOKEN_LIMIT_PER_IP);
+            if (!rl.allowed) {
+                reply.header("retry-after", String(rl.retryAfterSeconds));
+                throw new ApiError("auth.rate_limited", "Too many setup attempts; try again later");
+            }
+            if (!tokenMatches(body.setupToken, expected)) {
+                throw new ApiError("setup.token_invalid", "Setup token is missing or invalid");
+            }
+            await this.limiter.succeededScoped("setup", "token", ip);
+        }
+        // 会话行与账号 / 组织在同一事务里写入；Cookie 在提交之后才设置
+        const meta = clientMeta(req);
+        const { extra: session, ...result } = await this.setup.complete({
+            login: body.login,
+            password: body.password,
+            displayName: body.displayName,
+            orgName: body.orgName,
+        }, (trx, account) => this.sessions.create(account.id, meta, trx));
+        if (!session)
+            throw new Error("setup completed without a session");
+        setSessionCookies(reply, session, cfg);
+        return result;
+    }
+};
+__decorate([
+    Get(),
+    Public()
+], SetupController.prototype, "status", null);
+__decorate([
+    Post(),
+    Public(),
+    HttpCode(201),
+    __param(0, Body(new ZodPipe(SetupBody))),
+    __param(1, Req()),
+    __param(2, Res({ passthrough: true }))
+], SetupController.prototype, "complete", null);
+SetupController = __decorate([
+    Controller("api/v1/setup"),
+    __param(0, Inject(SETUP)),
+    __param(1, Inject(SESSIONS)),
+    __param(2, Inject(KERNEL_CONFIG)),
+    __param(3, Inject(RATE_LIMITER))
+], SetupController);
+export { SetupController };

package/dist/admin/setup.service.d.ts

@@ -0,0 +1,47 @@
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { Account, AccountsService } from "../identity/accounts.js";
+import type { Org, OrgsService } from "../orgs/orgs.service.js";
+/** 初始化向导与 CLI 建企业管理员。框架无关，由调用方注入依赖。 */
+export declare class SetupService {
+    private readonly db;
+    private readonly accounts;
+    private readonly orgs;
+    constructor(db: KernelDb, accounts: AccountsService, orgs: OrgsService);
+    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    status(): Promise<{
+        needsSetup: boolean;
+    }>;
+    /**
+     * 完成初始化：单个事务内先取咨询锁串行化并发的初始化请求，锁内再确认没有活跃企业管理员，
+     * 然后建企业管理员账号、（给了 `orgName` 时）建组织并以其为 owner。任一步失败整体回滚。
+     * 给了 `inTx` 时在同一事务的最后调用它（初始化向导用它建会话），结果放在 `extra`；它失败同样整体回滚。
+     */
+    complete<T = undefined>(input: {
+        login: string;
+        password: string;
+        displayName: string;
+        orgName?: string | undefined;
+    }, inTx?: (trx: Transaction<KernelDatabase>, account: Account) => Promise<T>): Promise<{
+        account: Account;
+        org?: Org;
+        extra: T | undefined;
+    }>;
+    /** CLI 用：直接建企业管理员，不检查是否已初始化；登录名已存在 → `account.login_taken`。 */
+    createEnterpriseAdmin(input: EnterpriseAdminInput): Promise<Account>;
+    /**
+     * CLI `admin create --if-none`: create an enterprise admin only when no active one exists. The
+     * check and the insert run in one transaction under the same advisory lock as {@link complete},
+     * so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined when an
+     * active enterprise admin already exists; a taken login still throws `account.login_taken`.
+     */
+    createEnterpriseAdminIfNone(input: EnterpriseAdminInput): Promise<Account | undefined>;
+    private insertEnterpriseAdmin;
+}
+/** Input of the CLI enterprise admin creation. */
+export interface EnterpriseAdminInput {
+    login: string;
+    password: string;
+    displayName: string;
+    email?: string | undefined;
+}

package/dist/admin/setup.service.js

@@ -0,0 +1,90 @@
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+const alreadyCompleted = () => new ApiError("setup.already_completed", "Deployment is already set up");
+/** 初始化向导与 CLI 建企业管理员。框架无关，由调用方注入依赖。 */
+export class SetupService {
+    db;
+    accounts;
+    orgs;
+    constructor(db, accounts, orgs) {
+        this.db = db;
+        this.accounts = accounts;
+        this.orgs = orgs;
+    }
+    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    async status() {
+        return { needsSetup: (await this.accounts.countEnterpriseAdmins()) === 0 };
+    }
+    /**
+     * 完成初始化：单个事务内先取咨询锁串行化并发的初始化请求，锁内再确认没有活跃企业管理员，
+     * 然后建企业管理员账号、（给了 `orgName` 时）建组织并以其为 owner。任一步失败整体回滚。
+     * 给了 `inTx` 时在同一事务的最后调用它（初始化向导用它建会话），结果放在 `extra`；它失败同样整体回滚。
+     */
+    async complete(input, inTx) {
+        // 先做一次廉价的预检查（已初始化的部署不白跑 scrypt），再在 BEGIN 之前算好哈希：
+        // 不在持有咨询锁的事务里跑 scrypt；锁内仍会复核
+        if ((await this.accounts.countEnterpriseAdmins()) > 0)
+            throw alreadyCompleted();
+        const passwordHash = await this.accounts.hashNewPassword(input.password);
+        return this.db.transaction().execute(async (trx) => {
+            await sql `SELECT pg_advisory_xact_lock(hashtext('capybara.setup'))`.execute(trx);
+            if ((await this.accounts.countEnterpriseAdmins(trx)) > 0)
+                throw alreadyCompleted();
+            const account = await this.accounts.createLocal({
+                login: input.login,
+                password: input.password,
+                displayName: input.displayName,
+                enterpriseAdmin: true,
+            }, trx, passwordHash);
+            const org = input.orgName !== undefined
+                ? await this.orgs.create({ name: input.orgName }, account, { trx })
+                : undefined;
+            await audit(trx, {
+                actorAccountId: account.id,
+                action: "deployment.setup_completed",
+                target: account.id,
+                ...(org && { orgId: org.id, detail: { orgId: org.id } }),
+            });
+            const extra = inTx ? await inTx(trx, account) : undefined;
+            return { account, ...(org && { org }), extra };
+        });
+    }
+    /** CLI 用：直接建企业管理员，不检查是否已初始化；登录名已存在 → `account.login_taken`。 */
+    async createEnterpriseAdmin(input) {
+        const passwordHash = await this.accounts.hashNewPassword(input.password);
+        return this.db
+            .transaction()
+            .execute((trx) => this.insertEnterpriseAdmin(trx, input, passwordHash));
+    }
+    /**
+     * CLI `admin create --if-none`: create an enterprise admin only when no active one exists. The
+     * check and the insert run in one transaction under the same advisory lock as {@link complete},
+     * so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined when an
+     * active enterprise admin already exists; a taken login still throws `account.login_taken`.
+     */
+    async createEnterpriseAdminIfNone(input) {
+        const passwordHash = await this.accounts.hashNewPassword(input.password);
+        return this.db.transaction().execute(async (trx) => {
+            await sql `SELECT pg_advisory_xact_lock(hashtext('capybara.setup'))`.execute(trx);
+            if ((await this.accounts.countEnterpriseAdmins(trx)) > 0)
+                return undefined;
+            return this.insertEnterpriseAdmin(trx, input, passwordHash);
+        });
+    }
+    async insertEnterpriseAdmin(trx, input, passwordHash) {
+        const account = await this.accounts.createLocal({
+            login: input.login,
+            password: input.password,
+            displayName: input.displayName,
+            enterpriseAdmin: true,
+            ...(input.email !== undefined && { email: input.email }),
+        }, trx, passwordHash);
+        await audit(trx, {
+            action: "account.created",
+            target: account.id,
+            detail: { enterpriseAdmin: true, via: "cli" },
+        });
+        return account;
+    }
+}