@lark-base-open/base-database-cli 1.6.0 → 1.7.0

package/dist/init.d.ts

@@ -1,4 +1,5 @@
 import { type RuntimeProfile } from './environment.js';
+import { type HandoffGrant, type HandoffTarget } from './bot-handoff.js';
 import type { CreatedTable } from './types.js';
 export interface InitOptions {
     larkProfile?: string;
@@ -13,15 +14,17 @@ export interface InitOptions {
     environment: string;
     resume?: boolean;
     runtimeProfile?: RuntimeProfile;
+    grantAdmin?: string;
 }
 export declare function initializeProject(options: InitOptions): Promise<{
     ok: true;
-    warnings: never[];
+    warnings: string[];
     initialization: {
         journal: string;
         status: 'succeeded';
         resumed?: boolean | undefined;
     };
+    handoff?: HandoffSummary | undefined;
     environment: string;
     workspace: string;
     larkProfile?: string | undefined;
@@ -91,5 +94,30 @@ export declare function initializeProject(options: InitOptions): Promise<{
         command: string;
         description: string;
     })[];
+} | {
+    ok: true;
+    warnings: string[];
+    initialization: {
+        journal: string;
+        status: 'succeeded';
+        resumed: boolean;
+        handoffOnly: boolean;
+    };
+    handoff: HandoffSummary;
+    environment: string;
+    workspace: string;
+    larkProfile?: string | undefined;
+    baseToken?: string | undefined;
+    appToken?: string | undefined;
 }>;
+export interface HandoffSummary {
+    identity: 'bot';
+    target?: HandoffTarget;
+    base: HandoffGrant & {
+        perm: 'full_access';
+    };
+    app: HandoffGrant & {
+        role: 'admin';
+    };
+}
 //# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAmCA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AA8S9D,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAmzBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW;;;;;gBAwgB5C,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA2CjB,SAAS;YACT,MAAM;YACN,OAAO;YACP,MAAM;;;;QAIR,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,cAAc;QAC5B,OAAO;QACP,KAAK,EAAE,MAAM;QACb,aAAa,EAAE,SAAS;QACxB,WAAW;;;;;;;;;;;;;GAuClB"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAoCA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,YAAY,CAAC;AA8S9D,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAszBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW;;;;;gBAilB5C,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA4CjB,SAAS;YACT,MAAM;YACN,OAAO;YACP,MAAM;;;;QAIR,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,cAAc;QAC5B,OAAO;QACP,KAAK,EAAE,MAAM;QACb,aAAa,EAAE,SAAS;QACxB,WAAW;;;;;;;;;;;;;;;;;QAwPb,OAAO;QACP,MAAM,EAAE,WAAW;QACnB,OAAO;QACP,WAAW;;;;;;;;GApNhB;AAiJD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,YAAY,GAAG;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,CAAC;IAC7C,GAAG,EAAE,YAAY,GAAG;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CACvC"}

package/dist/init.js

@@ -6,12 +6,13 @@ import { createHash } from 'node:crypto';
 import { InitJournal, InitFailureError, assertNoInitReceipt, } from './init-journal.js';
 import { readInitSchema, InitSchemaError } from './init-schema.js';
 import { createFieldsWithRetry } from './init-field-retry.js';
-import { isRecord } from './lark-cli-error.js';
+import { isRecord, userAuthorizationHint } from './lark-cli-error.js';
 import { starterRoot as legacyStarterRoot } from './assets.js';
 import { DATABASE_FUNCTIONS_DIRECTORY, LEGACY_DATABASE_FUNCTIONS_DIRECTORY, databaseFunctionsDirectory, } from './project-layout.js';
 import { CONFIG_FILE_NAME, LEGACY_TEMPLATE, readConfig, writeConfig, } from './config.js';
 import { ONLINE_RUNTIME_PROFILE, resolveRuntimeProfile, } from './environment.js';
-import { responseData, runLarkCli, resolveLarkProfileEnvironment, } from './lark-cli.js';
+import { currentCliUserOpenId, responseData, runLarkCli, resolveLarkIdentity, resolveLarkProfileEnvironment, } from './lark-cli.js';
+import { grantBaseAdmin, grantAppAdmin, resolveHandoffTarget, validateGrantAdmin, } from './bot-handoff.js';
 import { writePageTitle } from './page-title.js';
 const WRITE_INTERVAL_MS = 2_000;
 function requiredString(value, label) {
@@ -485,7 +486,7 @@ function buildInitPlan(options, schema, resources) {
         },
     };
 }
-function prepareResume(journal, options, schema, env) {
+function prepareResume(journal, options, schema, env, beforeRemote) {
     for (const step of journal.receipt.steps) {
         if (step.kind === 'write' && ['running', 'unknown'].includes(step.status))
             recoveryBlocked(journal, step.id, `Write outcome is unknown for ${step.id}; recovery cannot continue`);
@@ -497,6 +498,8 @@ function prepareResume(journal, options, schema, env) {
             !['not_attempted', 'succeeded'].includes(step.status))
             recoveryBlocked(journal, step.id, 'Local scaffolding may be incomplete and will not be overwritten');
     }
+    // 以上都是纯本地门禁；通过后、首个远端读取前解析并校验建站身份。
+    beforeRemote();
     const receipt = journal.receipt;
     const fieldRetries = new Map();
     let remoteTables = [];
@@ -737,6 +740,7 @@ export async function initializeProject(options) {
         throw new Error('--table-ids requires --base-token');
     }
     const planOptions = { ...options, tableIds: selectedTableIds };
+    const grantAdmin = validateGrantAdmin(options.grantAdmin);
     let schema;
     try {
         schema = schemaPath ? readInitSchema(schemaPath) : undefined;
@@ -753,6 +757,15 @@ export async function initializeProject(options) {
         });
     }
     const { env, larkProfile } = resolveLarkProfileEnvironment(await runtimeProfile.commandEnvironment(), options.larkProfile, undefined, runtimeProfile);
+    // 建站身份由 resolveLarkIdentity 统一解析（显式 --as > lark-cli 声明 > user），进程内只解析一次；
+    // 续跑在取得执行锁之后才解析，被本地门禁拦截的请求不调用 lark-cli。
+    const buildIdentity = () => {
+        const resolved = resolveLarkIdentity(env);
+        if (grantAdmin && resolved !== 'bot')
+            throw new Error('--grant-admin only applies when building as bot (--as bot); a user build already owns the created Base and app');
+        return resolved;
+    };
+    let identity;
     let selectedBaseToken;
     let selectedBaseUrl;
     let selectedBaseName = databaseName;
@@ -773,7 +786,37 @@ export async function initializeProject(options) {
                 ...(larkProfile ? { larkProfile } : {}),
                 planHash: plan.planHash,
             }, plan.steps, plan.resources, env);
-            resumePreparation = prepareResume(journal, planOptions, schema, env);
+            const resumed = journal;
+            const resolveResumeIdentity = () => {
+                identity = buildIdentity();
+                assertResumeIdentity(resumed, identity);
+            };
+            // 已完成的初始化只在交接未完成时允许续跑，且只补授权、不发任何建站写入。
+            if (journal.receipt.status === 'succeeded') {
+                if (!handoffPending(journal.receipt))
+                    throw new InitFailureError('Initialization is already complete; recovery is not needed', {
+                        ok: false,
+                        status: 'blocked',
+                        phase: 'resume-preflight',
+                        journal: journal.path,
+                        error: {
+                            message: 'Initialization is already complete; recovery is not needed',
+                        },
+                        nextAction: 'Nothing to resume: the initialization and its admin handoff are complete. Continue with the next development step.',
+                    });
+                resolveResumeIdentity();
+                return resumeHandoffOnly(journal, identity, grantAdmin, env, {
+                    environment: runtimeProfile.name,
+                    workspace,
+                    larkProfile,
+                });
+            }
+            resumePreparation = prepareResume(journal, planOptions, schema, env, resolveResumeIdentity);
+        }
+        else {
+            identity = buildIdentity();
+            if (!existingBaseToken || !existingAppToken)
+                assertHandoffTarget(identity, grantAdmin, env);
         }
         if (existingBaseToken) {
             selectedBaseToken = requiredString(existingBaseToken, '--base-token');
@@ -787,7 +830,7 @@ export async function initializeProject(options) {
             if (!schema)
                 throw new Error('Schema is required');
             const [first, ...remaining] = schema.tables;
-            journal ??= startJournal(workspace, planOptions, larkProfile, env, schema, {
+            journal ??= startJournal(workspace, planOptions, larkProfile, env, identity, schema, {
                 tables: [],
             });
             if (!first)
@@ -802,6 +845,7 @@ export async function initializeProject(options) {
                 selectedBaseUrl = baseUrl(currentBase);
                 selectedBaseName = baseName(currentBase) ?? databaseName;
                 tables = [saved];
+                ensureHandoff(journal, 'base', identity, grantAdmin, env);
             }
             else {
                 process.stderr.write(`Creating Base ${databaseName}...\n`);
@@ -824,6 +868,8 @@ export async function initializeProject(options) {
                 tables = [
                     { name: first.name, tableId: tableId(createdBase, 'base-create') },
                 ];
+                // 新建后立即交接：后续步骤失败时，接手的人也已能打开 Base 核对或续跑。
+                ensureHandoff(journal, 'base', identity, grantAdmin, env, createdBase);
             }
             for (const [index, table] of remaining.entries()) {
                 const stepId = `create-table:${index + 1}`;
@@ -878,21 +924,26 @@ export async function initializeProject(options) {
                     fields: remainingFields,
                     initialIndexes: retryIndexes ?? remainingFields.map((_, index) => index),
                     env,
-                    execute: (indexes) => runLarkCli([
-                        'base',
-                        '+field-create',
-                        '--base-token',
-                        selectedBaseToken,
-                        '--table-id',
-                        createdTable.tableId,
-                        '--json',
-                        JSON.stringify(indexes.map((index) => remainingFields[index])),
-                    ], env),
+                    execute: (indexes) => {
+                        const batch = indexes.map((index) => remainingFields[index]);
+                        const needsGuide = batch.some((field) => field?.type === 'formula' || field?.type === 'lookup');
+                        return runLarkCli([
+                            'base',
+                            '+field-create',
+                            '--base-token',
+                            selectedBaseToken,
+                            '--table-id',
+                            createdTable.tableId,
+                            '--json',
+                            JSON.stringify(batch),
+                            ...(needsGuide ? ['--i-have-read-guide'] : []),
+                        ], env);
+                    },
                 }));
             }
             await pause();
         }
-        journal ??= startJournal(workspace, planOptions, larkProfile, env, schema, {
+        journal ??= startJournal(workspace, planOptions, larkProfile, env, identity, schema, {
             baseToken: selectedBaseToken,
             tables,
         });
@@ -933,6 +984,7 @@ export async function initializeProject(options) {
         else {
             if (journal.step('create-app').status === 'succeeded') {
                 selectedAppToken = requiredString(journal.receipt.resources.appToken, 'receipt application token');
+                ensureHandoff(journal, 'app', identity, grantAdmin, env);
             }
             else {
                 process.stderr.write(`Creating application and binding ${selectedTableIds ? 'selected' : 'all'} tables...\n`);
@@ -954,6 +1006,7 @@ export async function initializeProject(options) {
                     appToken(response);
                 });
                 selectedAppToken = appToken(createdDatabase);
+                ensureHandoff(journal, 'app', identity, grantAdmin, env);
             }
         }
         const encodedToken = encodeURIComponent(selectedAppToken);
@@ -1072,14 +1125,16 @@ export async function initializeProject(options) {
             tables,
         };
         const baseAppUrl = catalogBaseAppUrl(catalog);
+        const handoff = handoffSummary(journal.receipt, identity);
         return {
             ok: true,
-            warnings: [],
+            warnings: handoff ? handoffWarnings(handoff) : [],
             initialization: {
                 journal: journal.path,
                 status: 'succeeded',
                 ...(options.resume ? { resumed: true } : {}),
             },
+            ...(handoff ? { handoff } : {}),
             environment: runtimeProfile.name,
             workspace,
             ...(larkProfile ? { larkProfile } : {}),
@@ -1144,7 +1199,7 @@ export async function initializeProject(options) {
                     action: 'generateContracts',
                     workingDirectory: workspace,
                     command: `${runtimeProfile.checkCommand.split(' ')[0]} contracts generate`,
-                    description: 'After installing the root workspace dependencies, generate contracts before check. The published SDK and a single root package-lock.json are required.',
+                    description: 'Generate contracts before check; this command prepares locked dependencies as needed. The published SDK and a single root package-lock.json are required.',
                 },
                 {
                     action: 'check',
@@ -1172,12 +1227,139 @@ export async function initializeProject(options) {
         journal?.close();
     }
 }
-function startJournal(workspace, options, larkProfile, env, schema, resources) {
+function startJournal(workspace, options, larkProfile, env, identity, schema, resources) {
     const plan = buildInitPlan(options, schema, resources);
     return new InitJournal(workspace, {
         environment: options.environment,
         ...(larkProfile ? { larkProfile } : {}),
         planHash: plan.planHash,
+        identity,
     }, plan.steps, plan.resources, env);
 }
+// 续跑必须沿用建站身份：中途换身份会让后续写入与已建资源的属主/授权不一致。
+function assertResumeIdentity(journal, identity) {
+    // 未记录身份的 receipt 来自引入身份记录之前，当时一律以 user 建站。
+    const recorded = journal.receipt.identity ?? 'user';
+    if (recorded !== identity)
+        recoveryBlocked(journal, 'resume-preflight', `This initialization was started with the ${recorded} identity; resume it with --as ${recorded}`);
+}
+// handoffPending：只有以 bot 建站、且本次新建的资源尚未完成授权时，已完成的初始化才需要续跑。
+function handoffPending(receipt) {
+    const { resources, handoff } = receipt;
+    return (receipt.identity === 'bot' &&
+        ((resources.baseSource === 'created' && pendingGrant(handoff?.base)) ||
+            (resources.appSource === 'created' && pendingGrant(handoff?.app))));
+}
+// bot 新建的资源属主是机器人：没有授权对象时建出来无人能打开，必须在任何写入前拦截。
+// 人用场景只引导登录（open_id 按应用区分，用户无从得知）；--grant-admin 留给持有发起人 open_id 的宿主。
+function assertHandoffTarget(identity, grantAdmin, env) {
+    if (identity !== 'bot' || grantAdmin || currentCliUserOpenId(env))
+        return;
+    const message = 'Building as bot needs someone to receive admin on the new Base and app, but no lark-cli user is logged in';
+    const login = userAuthorizationHint(env) ?? 'Log in with: lark-cli auth login';
+    throw new InitFailureError(message, {
+        ok: false,
+        status: 'blocked',
+        phase: 'preflight',
+        error: { message },
+        nextAction: `${login}\nThen rerun the same init command. Do not ask the user for an open_id. No remote resources were created.`,
+    });
+}
+function pendingGrant(grant) {
+    return (!grant || (grant.status !== 'granted' && grant.status !== 'not_applicable'));
+}
+// handoffTarget 确定授权对象：显式 --grant-admin 优先，其次沿用 receipt 已记录的对象，最后才读当前
+// lark-cli 用户。已有授权成功后不允许换人，避免同一批资源交给两个人。
+function handoffTarget(journal, grantAdmin, env) {
+    const { handoff } = journal.receipt;
+    const target = grantAdmin
+        ? { openId: grantAdmin, source: 'grant_admin' }
+        : (handoff?.target ?? resolveHandoffTarget(env, undefined));
+    const granted = [handoff?.base, handoff?.app].find((grant) => grant?.status === 'granted' && grant.userOpenId)?.userOpenId;
+    if (target && granted && granted !== target.openId)
+        recoveryBlocked(journal, 'handoff', `Admin was already granted to ${granted}; resume with the same grantee instead of ${target.openId}`);
+    if (target &&
+        (handoff?.target?.openId !== target.openId ||
+            handoff.target.source !== target.source))
+        journal.recordHandoff({ target });
+    return target;
+}
+function recordGrant(journal, resource, grant) {
+    // 重试只覆盖本次结果；首次建 Base 时 lark-cli 已授权的其他用户仍需保留在报告中。
+    const alsoGrantedOpenId = journal.receipt.handoff?.[resource]?.alsoGrantedOpenId;
+    journal.recordHandoff({
+        [resource]: {
+            ...(alsoGrantedOpenId ? { alsoGrantedOpenId } : {}),
+            ...grant,
+        },
+    });
+}
+// ensureHandoff：只在 bot 建站且资源由本次 init 新建时授权；非致命，结果记入 receipt，已授权的不重复执行。
+function ensureHandoff(journal, resource, identity, grantAdmin, env, createResponse) {
+    const { resources, handoff } = journal.receipt;
+    const isBase = resource === 'base';
+    const source = isBase ? resources.baseSource : resources.appSource;
+    const token = isBase ? resources.baseToken : resources.appToken;
+    if (identity !== 'bot' || source !== 'created' || !token)
+        return;
+    if (!pendingGrant(handoff?.[resource]))
+        return;
+    const target = handoffTarget(journal, grantAdmin, env);
+    recordGrant(journal, resource, isBase
+        ? grantBaseAdmin(token, target, env, createResponse)
+        : grantAppAdmin(token, target, env));
+}
+function handoffSummary(receipt, identity) {
+    if (identity !== 'bot')
+        return undefined;
+    const grant = (created, recorded) => {
+        if (!created)
+            return { status: 'not_applicable' };
+        if (!recorded)
+            return {
+                status: 'failed',
+                hint: 'Admin handoff was not attempted; rerun the same init command with --resume.',
+            };
+        return recorded;
+    };
+    return {
+        identity: 'bot',
+        ...(receipt.handoff?.target ? { target: receipt.handoff.target } : {}),
+        base: {
+            ...grant(receipt.resources.baseSource === 'created', receipt.handoff?.base),
+            perm: 'full_access',
+        },
+        app: {
+            ...grant(receipt.resources.appSource === 'created', receipt.handoff?.app),
+            role: 'admin',
+        },
+    };
+}
+function handoffWarnings(handoff) {
+    return [handoff.base, handoff.app].flatMap((grant) => grant.status === 'granted' || grant.status === 'not_applicable'
+        ? []
+        : [grant.hint ?? `Admin handoff ${grant.status}`]);
+}
+function resumeHandoffOnly(journal, identity, grantAdmin, env, context) {
+    const { resources } = journal.receipt;
+    ensureHandoff(journal, 'base', identity, grantAdmin, env);
+    ensureHandoff(journal, 'app', identity, grantAdmin, env);
+    const handoff = handoffSummary(journal.receipt, identity);
+    return {
+        ok: true,
+        warnings: handoffWarnings(handoff),
+        initialization: {
+            journal: journal.path,
+            status: 'succeeded',
+            resumed: true,
+            handoffOnly: true,
+        },
+        handoff,
+        environment: context.environment,
+        workspace: context.workspace,
+        ...(context.larkProfile ? { larkProfile: context.larkProfile } : {}),
+        ...(resources.baseToken ? { baseToken: resources.baseToken } : {}),
+        ...(resources.appToken ? { appToken: resources.appToken } : {}),
+    };
+}
 //# sourceMappingURL=init.js.map