@lark-base-open/base-database-cli 1.1.1 → 1.3.7

package/dist/init.js

@@ -1,7 +1,13 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
+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 { starterRoot } from './assets.js';
-import { CONFIG_FILE_NAME, writeConfig } from './config.js';
+import { DATABASE_FUNCTIONS_DIRECTORY, LEGACY_DATABASE_FUNCTIONS_DIRECTORY, databaseFunctionsDirectory, } from './project-layout.js';
+import { CONFIG_FILE_NAME, readConfig, writeConfig } from './config.js';
 import { ONLINE_RUNTIME_PROFILE, resolveRuntimeProfile, } from './environment.js';
 import { responseData, runLarkCli, resolveLarkProfileEnvironment, } from './lark-cli.js';
 import { writePageTitle } from './page-title.js';
@@ -12,46 +18,6 @@ function requiredString(value, label) {
     }
     return value.trim();
 }
-function parseSchema(path) {
-    const absolutePath = resolve(path);
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(absolutePath, 'utf8'));
-    }
-    catch (error) {
-        throw new Error(`Unable to read schema ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error('Schema must be an object');
-    }
-    const tables = parsed.tables;
-    if (!Array.isArray(tables) || tables.length === 0) {
-        throw new Error('Schema must contain at least one table');
-    }
-    const names = new Set();
-    for (const [tableIndex, table] of tables.entries()) {
-        if (!table || typeof table !== 'object') {
-            throw new Error(`schema.tables[${tableIndex}] must be an object`);
-        }
-        const candidate = table;
-        const name = requiredString(candidate.name, `schema.tables[${tableIndex}].name`);
-        if (names.has(name))
-            throw new Error(`Duplicate table name: ${name}`);
-        names.add(name);
-        if (!Array.isArray(candidate.fields) || candidate.fields.length === 0) {
-            throw new Error(`schema.tables[${tableIndex}].fields must not be empty`);
-        }
-        for (const [fieldIndex, field] of candidate.fields.entries()) {
-            if (!field || typeof field !== 'object') {
-                throw new Error(`schema.tables[${tableIndex}].fields[${fieldIndex}] must be an object`);
-            }
-            const candidateField = field;
-            requiredString(candidateField.name, `schema.tables[${tableIndex}].fields[${fieldIndex}].name`);
-            requiredString(candidateField.type, `schema.tables[${tableIndex}].fields[${fieldIndex}].type`);
-        }
-    }
-    return parsed;
-}
 function tableId(response, label) {
     const data = responseData(response);
     const table = data.table;
@@ -76,6 +42,14 @@ function baseName(response) {
         ? value.trim()
         : undefined;
 }
+function baseTimeZone(response) {
+    const data = responseData(response);
+    const base = data.base;
+    const value = base?.time_zone ?? base?.timeZone ?? data.time_zone ?? data.timeZone;
+    return typeof value === 'string' && value.trim() !== ''
+        ? value.trim()
+        : undefined;
+}
 function existingTables(response) {
     const data = responseData(response);
     const value = data.tables ?? data.items;
@@ -185,29 +159,541 @@ function catalogBaseAppUrl(catalog) {
     const value = catalog.baseAppUrl;
     return typeof value === 'string' && value.trim() !== '' ? value : undefined;
 }
-export async function initializeProject(options) {
-    const runtimeProfile = resolveRuntimeProfile(options.environment, options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE);
-    const workspace = resolve(options.directory);
-    const databaseName = requiredString(options.name, '--name');
-    for (const output of [
+function validateApplication(value, token, name, description, baseTokenValue, tables, validateMetadata, validateBinding, exactBindings) {
+    if (!isRecord(value) || !isRecord(value.project))
+        throw new Error('Application readback does not contain project metadata');
+    const project = value.project;
+    if (project.token !== token)
+        throw new Error('Application token changed after initialization started');
+    if (validateMetadata &&
+        (project.name !== name || String(project.description ?? '') !== description))
+        throw new Error('Application metadata changed after initialization started');
+    if (!validateBinding)
+        return;
+    if (!Array.isArray(project.baseBindings))
+        throw new Error('Application readback does not contain Base bindings');
+    const binding = project.baseBindings.find((item) => isRecord(item) && item.baseToken === baseTokenValue);
+    if (!isRecord(binding) || !Array.isArray(binding.tableIds))
+        throw new Error('Application no longer contains the expected Base binding');
+    const actual = binding.tableIds.map(String);
+    const expected = tables.map((table) => table.tableId);
+    if (actual.length < expected.length ||
+        expected.some((id) => !actual.includes(id)) ||
+        (exactBindings &&
+            (project.baseBindings.length !== 1 || actual.length !== expected.length)))
+        throw new Error('Application Base bindings changed after initialization started');
+}
+function validateExactCatalog(value, baseTokenValue, tables) {
+    const catalog = validateCatalog(value, baseTokenValue, tables);
+    const actual = Array.isArray(catalog.tables) ? catalog.tables : [];
+    const expected = new Set(tables.map((table) => `${baseTokenValue}:${table.tableId}`));
+    if (actual.length !== expected.size ||
+        actual.some((table) => !isRecord(table) ||
+            !expected.has(`${String(table.baseToken)}:${String(table.id)}`)))
+        throw new Error('Application Catalog contains unexpected table bindings');
+}
+function recoveryBlocked(journal, phase, message) {
+    throw new InitFailureError(message, {
+        ok: false,
+        status: 'blocked',
+        phase,
+        journal: journal.path,
+        receipt: journal.receipt,
+        error: { message },
+        nextAction: 'Preserve the receipt and reconcile the reported resource or unknown outcome. No recovery write was sent.',
+    });
+}
+function existingFields(response) {
+    const data = responseData(response);
+    const value = data.fields ?? data.items;
+    if (!Array.isArray(value))
+        throw new Error('field-list response does not contain fields');
+    const fields = value.map((field, index) => {
+        if (!isRecord(field))
+            throw new Error(`field-list response fields[${index}] must be an object`);
+        return {
+            id: requiredString(field.id ?? field.field_id ?? field.fieldId, `field-list response fields[${index}] ID`),
+            name: requiredString(field.name, `field-list response fields[${index}] name`),
+            type: requiredString(field.type, `field-list response fields[${index}] type`),
+            raw: field,
+        };
+    });
+    return {
+        fields,
+        total: typeof data.total === 'number' && Number.isInteger(data.total)
+            ? data.total
+            : fields.length,
+    };
+}
+function listExistingFields(baseTokenValue, tableIdValue, env) {
+    const limit = 200;
+    const fields = [];
+    for (let offset = 0;; offset += limit) {
+        const page = existingFields(runLarkCli([
+            'base',
+            '+field-list',
+            '--base-token',
+            baseTokenValue,
+            '--table-id',
+            tableIdValue,
+            '--limit',
+            String(limit),
+            '--offset',
+            String(offset),
+        ], env));
+        fields.push(...page.fields);
+        if (fields.length >= page.total)
+            return fields;
+        if (page.fields.length === 0)
+            throw new Error('field-list returned more fields without a page');
+    }
+}
+function primaryFieldId(baseTokenValue, tableIdValue, env) {
+    const data = responseData(runLarkCli([
+        'base',
+        '+table-get',
+        '--base-token',
+        baseTokenValue,
+        '--table-id',
+        tableIdValue,
+    ], env));
+    const table = isRecord(data.table) ? data.table : {};
+    return requiredString(table.primary_field ?? table.primaryField, `table-get response primary field for ${tableIdValue}`);
+}
+function receiptTable(receipt, name) {
+    return receipt.resources.tables.find((table) => table.name === name);
+}
+function plainObject(value) {
+    return isRecord(value) ? value : {};
+}
+function normalizeStyle(type, value) {
+    const source = plainObject(value);
+    if (type === 'text')
+        return { type: source.type ?? 'plain', ...source };
+    if (type === 'number') {
+        const styleType = String(source.type ?? 'plain');
+        const defaults = {
+            plain: { precision: 2, percentage: false, thousands_separator: false },
+            currency: { precision: 2 },
+            progress: { percentage: true },
+            rating: { icon: 'star', min: 1, max: 5 },
+        };
+        return { type: styleType, ...(defaults[styleType] ?? {}), ...source };
+    }
+    if (['datetime', 'created_at', 'updated_at'].includes(type))
+        return { format: 'yyyy/MM/dd', ...source };
+    return Object.keys(source).length > 0 ? source : undefined;
+}
+function normalizeFieldConfig(source, receipt, remoteByTable) {
+    const type = String(source.type ?? '');
+    const result = {
+        name: source.name,
+        type,
+        description: source.description ?? null,
+    };
+    const style = normalizeStyle(type, source.style);
+    if (style)
+        result.style = style;
+    const supportsDefault = [
+        'text',
+        'number',
+        'select',
+        'datetime',
+        'user',
+    ].includes(type);
+    if (supportsDefault && source.dynamic_options_source === undefined)
+        result.default_value = source.default_value ?? null;
+    if (type === 'select') {
+        result.multiple = source.multiple ?? false;
+        if (Array.isArray(source.options))
+            result.options = source.options.map((value) => {
+                const option = plainObject(value);
+                return {
+                    name: option.name,
+                    hue: option.hue ?? 'Blue',
+                    lightness: option.lightness ?? 'Lighter',
+                };
+            });
+        if (isRecord(source.dynamic_options_source)) {
+            const dynamic = source.dynamic_options_source;
+            const tableReference = String(dynamic.table_id ?? '');
+            const table = receiptTable(receipt, tableReference);
+            const tableIdValue = table?.tableId ?? tableReference;
+            const remote = remoteByTable.get(tableIdValue) ?? [];
+            const fieldReference = String(dynamic.field_id ?? '');
+            const fieldIdValue = remote.find((field) => field.id === fieldReference || field.name === fieldReference)?.id ?? fieldReference;
+            result.dynamic_options_source = {
+                table_id: tableIdValue,
+                field_id: fieldIdValue,
+            };
+        }
+    }
+    if (type === 'user' || type === 'group_chat')
+        result.multiple = source.multiple ?? true;
+    if (type === 'link') {
+        const reference = String(source.link_table ?? '');
+        result.link_table = receiptTable(receipt, reference)?.tableId ?? reference;
+        result.bidirectional = source.bidirectional ?? false;
+        if (source.bidirectional_link_field_name !== undefined)
+            result.bidirectional_link_field_name =
+                source.bidirectional_link_field_name;
+    }
+    if (type === 'formula')
+        result.expression = source.expression;
+    if (type === 'lookup')
+        for (const key of ['from', 'select', 'where', 'aggregate'])
+            if (source[key] !== undefined)
+                result[key] = source[key];
+    if (type === 'auto_number' && source.style !== undefined)
+        result.style = source.style;
+    if (type === 'button')
+        result.button_config = source.button_config;
+    return result;
+}
+function configContains(actual, expected) {
+    if (Array.isArray(expected))
+        return (Array.isArray(actual) &&
+            actual.length === expected.length &&
+            expected.every((value, index) => configContains(actual[index], value)));
+    if (isRecord(expected))
+        return (isRecord(actual) &&
+            Object.entries(expected).every(([key, value]) => configContains(actual[key], value)));
+    return Object.is(actual, expected);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return value.map(stableJson);
+    if (isRecord(value))
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, stableJson(value[key])]));
+    return value;
+}
+function assertRemoteField(journal, phase, remote, expected, remoteByTable, id) {
+    if (!id)
+        recoveryBlocked(journal, phase, `Receipt does not contain a confirmed field ID for ${String(expected.name)}`);
+    const actual = remote.find((field) => field.id === id);
+    const expectedConfig = normalizeFieldConfig(expected, journal.receipt, remoteByTable);
+    const actualConfig = actual
+        ? normalizeFieldConfig(actual.raw, journal.receipt, remoteByTable)
+        : undefined;
+    if (!actual ||
+        actual.name !== expected.name ||
+        actual.type !== expected.type ||
+        !configContains(actualConfig, expectedConfig))
+        recoveryBlocked(journal, phase, `Remote field drift detected for ${String(expected.name)} (${id})`);
+}
+function validateFieldItems(journal, step, fields, remote, remoteByTable) {
+    const items = step.items;
+    if (!items || items.length !== fields.length)
+        recoveryBlocked(journal, step.id, `Receipt does not contain a complete field result map for ${step.id}`);
+    const indexes = new Set();
+    const retry = [];
+    for (const item of items) {
+        if (!Number.isInteger(item.index) ||
+            item.index < 0 ||
+            item.index >= fields.length ||
+            indexes.has(item.index))
+            recoveryBlocked(journal, step.id, `Invalid field result index in ${step.id}`);
+        indexes.add(item.index);
+        const expected = fields[item.index];
+        if (!expected)
+            recoveryBlocked(journal, step.id, `Missing field plan for ${step.id}`);
+        if (item.status === 'created') {
+            assertRemoteField(journal, step.id, remote, expected, remoteByTable, item.field?.id);
+        }
+        else if (item.status === 'failed' || item.status === 'not_attempted') {
+            if (remote.some((field) => field.name === expected.name))
+                recoveryBlocked(journal, step.id, `Remote field ${String(expected.name)} exists without a confirmed receipt ID`);
+            retry.push(item.index);
+        }
+        else {
+            recoveryBlocked(journal, step.id, `Unsupported field result in ${step.id}`);
+        }
+    }
+    return retry;
+}
+function buildInitPlan(options, schema, resources) {
+    const steps = [];
+    if (schema) {
+        schema.tables.forEach((table, i) => steps.push({
+            id: i === 0 ? 'create-base' : `create-table:${i}`,
+            kind: 'write',
+            target: { tableIndex: i, tableName: table.name },
+        }));
+        schema.tables.forEach((table, i) => {
+            if (table.fields.length > 1)
+                steps.push({
+                    id: `create-fields:${i}`,
+                    kind: 'write',
+                    target: { tableIndex: i, tableName: table.name, fieldOffset: 1 },
+                });
+        });
+    }
+    if (options.appToken)
+        steps.push({ id: 'update-app', kind: 'write' }, { id: 'bind-base', kind: 'write' });
+    else
+        steps.push({ id: 'create-app', kind: 'write' });
+    steps.push({ id: 'read-catalog', kind: 'read' }, { id: 'scaffold', kind: 'local' });
+    const planHash = createHash('sha256')
+        .update(JSON.stringify({
+        name: options.name,
+        description: options.description,
+        timeZone: options.timeZone,
+        schema,
+        baseToken: options.baseToken,
+        appToken: options.appToken,
+    }))
+        .digest('hex');
+    return {
+        steps,
+        planHash,
+        resources: {
+            ...resources,
+            baseSource: schema ? 'created' : 'existing',
+            appSource: options.appToken ? 'existing' : 'created',
+            ...(options.appToken ? { appToken: options.appToken.trim() } : {}),
+        },
+    };
+}
+function prepareResume(journal, options, schema, env) {
+    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`);
+        if (step.id === 'create-app' && step.status === 'failed')
+            recoveryBlocked(journal, step.id, 'Application creation may have produced an application before returning an error');
+        if (step.status === 'partial' && !step.id.startsWith('create-fields:'))
+            recoveryBlocked(journal, step.id, `Unsupported partial step ${step.id}`);
+        if (step.kind === 'local' &&
+            !['not_attempted', 'succeeded'].includes(step.status))
+            recoveryBlocked(journal, step.id, 'Local scaffolding may be incomplete and will not be overwritten');
+    }
+    const receipt = journal.receipt;
+    const fieldRetries = new Map();
+    let remoteTables = [];
+    const needsBaseRead = receipt.resources.baseSource === 'existing' ||
+        receipt.steps.some((step) => (step.id === 'create-base' || step.id.startsWith('create-table:')) &&
+            step.status === 'succeeded');
+    if (needsBaseRead) {
+        const token = receipt.resources.baseToken;
+        if (!token)
+            recoveryBlocked(journal, 'resume-preflight', 'Receipt has no confirmed Base token');
+        const baseResponse = runLarkCli(['base', '+base-get', '--base-token', token], env);
+        if (receipt.resources.baseSource === 'created' &&
+            (baseName(baseResponse) !== requiredString(options.name, '--name') ||
+                baseTimeZone(baseResponse) !== options.timeZone))
+            recoveryBlocked(journal, 'resume-preflight', 'Created Base name or time zone changed after initialization started');
+        remoteTables = listExistingTables(token, env);
+        for (const table of receipt.resources.tables) {
+            const actual = remoteTables.find((item) => item.tableId === table.tableId);
+            if (!actual || actual.name !== table.name)
+                recoveryBlocked(journal, 'resume-preflight', `Remote table drift detected for ${table.name} (${table.tableId})`);
+        }
+        if (receipt.resources.baseSource === 'existing' &&
+            (remoteTables.length !== receipt.resources.tables.length ||
+                remoteTables.some((table) => !receipt.resources.tables.some((saved) => saved.tableId === table.tableId && saved.name === table.name))))
+            recoveryBlocked(journal, 'resume-preflight', 'Existing Base table set changed after initialization started');
+    }
+    const remoteByTable = new Map();
+    if (schema && receipt.resources.baseToken) {
+        for (const [tableIndex, table] of schema.tables.entries()) {
+            const step = journal.step(tableIndex === 0 ? 'create-base' : `create-table:${tableIndex}`);
+            const saved = receiptTable(receipt, table.name);
+            if (step.status === 'succeeded' && saved)
+                remoteByTable.set(saved.tableId, listExistingFields(receipt.resources.baseToken, saved.tableId, env));
+        }
+    }
+    if (schema) {
+        for (const [tableIndex, table] of schema.tables.entries()) {
+            const createStep = journal.step(tableIndex === 0 ? 'create-base' : `create-table:${tableIndex}`);
+            const savedTable = receiptTable(receipt, table.name);
+            if (createStep.status === 'succeeded') {
+                if (!savedTable)
+                    recoveryBlocked(journal, createStep.id, `Receipt has no confirmed table ID for ${table.name}`);
+                const fields = remoteByTable.get(savedTable.tableId);
+                if (!fields)
+                    recoveryBlocked(journal, createStep.id, `Remote fields were not available for ${table.name}`);
+                const primary = table.fields[0];
+                if (!primary)
+                    recoveryBlocked(journal, createStep.id, `Primary field drift detected for ${table.name}`);
+                assertRemoteField(journal, createStep.id, fields, primary, remoteByTable, primaryFieldId(requiredString(receipt.resources.baseToken, 'receipt Base token'), savedTable.tableId, env));
+                const fieldStep = receipt.steps.find((step) => step.id === `create-fields:${tableIndex}`);
+                if (fieldStep && fieldStep.status !== 'not_attempted') {
+                    const planned = table.fields.slice(1);
+                    if (fieldStep.status === 'failed' &&
+                        fieldStep.error?.kind === 'api' &&
+                        !fieldStep.items) {
+                        if (planned.some((expected) => fields.some((field) => field.name === expected.name)))
+                            recoveryBlocked(journal, fieldStep.id, 'A failed field step has matching remote fields without confirmed IDs');
+                        fieldRetries.set(fieldStep.id, planned.map((_, index) => index));
+                        continue;
+                    }
+                    const retry = validateFieldItems(journal, fieldStep, planned, fields, remoteByTable);
+                    if (fieldStep.status === 'succeeded') {
+                        if (retry.length > 0)
+                            recoveryBlocked(journal, fieldStep.id, `Succeeded field step contains incomplete items: ${fieldStep.id}`);
+                    }
+                    else if (fieldStep.status === 'partial' ||
+                        fieldStep.status === 'failed') {
+                        if (retry.length === 0)
+                            journal.reconcile(fieldStep.id);
+                        else
+                            fieldRetries.set(fieldStep.id, retry);
+                    }
+                    else {
+                        recoveryBlocked(journal, fieldStep.id, `Field recovery cannot continue from ${fieldStep.status}`);
+                    }
+                }
+            }
+            else if (createStep.status === 'partial') {
+                recoveryBlocked(journal, createStep.id, `Unsupported partial step ${createStep.id}`);
+            }
+            else if (createStep.status === 'failed') {
+                if (createStep.id === 'create-base' || createStep.error?.kind !== 'api')
+                    recoveryBlocked(journal, createStep.id, `Table creation is not safely retryable for ${createStep.id}`);
+            }
+        }
+    }
+    const createApp = receipt.steps.find((step) => step.id === 'create-app');
+    const updateApp = receipt.steps.find((step) => step.id === 'update-app');
+    const bindBase = receipt.steps.find((step) => step.id === 'bind-base');
+    if (createApp?.status === 'succeeded' ||
+        updateApp?.status === 'succeeded' ||
+        bindBase?.status === 'succeeded') {
+        const token = receipt.resources.appToken;
+        const baseTokenValue = receipt.resources.baseToken;
+        if (!token || !baseTokenValue)
+            recoveryBlocked(journal, 'resume-preflight', 'Receipt has no confirmed application or Base token');
+        const projectResponse = runLarkCli([
+            'api',
+            'GET',
+            `/open-apis/base/v3/sites/${encodeURIComponent(token)}/get`,
+        ], env);
+        try {
+            validateApplication(projectResponse.data, token, requiredString(options.name, '--name'), options.description ?? '', baseTokenValue, receipt.resources.tables, createApp?.status === 'succeeded' || updateApp?.status === 'succeeded', createApp?.status === 'succeeded' || bindBase?.status === 'succeeded', createApp?.status === 'succeeded');
+            if (createApp?.status === 'succeeded' ||
+                bindBase?.status === 'succeeded') {
+                const catalog = runLarkCli([
+                    'api',
+                    'GET',
+                    `/open-apis/base/v3/sites/${encodeURIComponent(token)}/catalog`,
+                ], env);
+                if (createApp?.status === 'succeeded')
+                    validateExactCatalog(catalog.data, baseTokenValue, receipt.resources.tables);
+                else
+                    validateCatalog(catalog.data, baseTokenValue, receipt.resources.tables);
+            }
+        }
+        catch (error) {
+            recoveryBlocked(journal, 'resume-preflight', error instanceof Error ? error.message : 'Application drift detected');
+        }
+    }
+    for (const step of receipt.steps) {
+        if (step.kind === 'read') {
+            if (step.status === 'unknown')
+                recoveryBlocked(journal, step.id, `Read outcome is invalid for recovery: ${step.id}`);
+            if (step.status !== 'not_attempted')
+                journal.prepare(step.id);
+        }
+        else if (step.status === 'failed' &&
+            step.kind === 'write' &&
+            step.error?.kind === 'api' &&
+            !['create-base', 'create-app'].includes(step.id) &&
+            !step.id.startsWith('create-fields:'))
+            journal.prepare(step.id);
+    }
+    const scaffold = journal.step('scaffold');
+    const projectRoot = resolve(dirname(journal.path), '..', '..');
+    const scaffoldOutputs = [
         CONFIG_FILE_NAME,
         'catalog.json',
         'page',
         'server-functions',
-        'sql',
-    ]) {
-        if (existsSync(join(workspace, output))) {
-            throw new Error(`Refusing to overwrite ${join(workspace, output)}`);
+    ];
+    if (scaffold.status === 'succeeded') {
+        for (const output of scaffoldOutputs)
+            if (!existsSync(join(projectRoot, output)))
+                recoveryBlocked(journal, 'scaffold', `Completed scaffold output is missing: ${output}`);
+        let databaseFunctions;
+        try {
+            databaseFunctions = databaseFunctionsDirectory(projectRoot);
+        }
+        catch (error) {
+            recoveryBlocked(journal, 'scaffold', error instanceof Error
+                ? error.message
+                : 'Function source roots are invalid');
+        }
+        if (!databaseFunctions) {
+            recoveryBlocked(journal, 'scaffold', `Completed scaffold output is missing: ${DATABASE_FUNCTIONS_DIRECTORY}`);
+        }
+        const config = readConfig(projectRoot);
+        const bindings = isRecord(config.bindings) ? config.bindings : {};
+        const main = isRecord(bindings.MAIN_BASE) ? bindings.MAIN_BASE : {};
+        const configuredTables = Array.isArray(main.tableIds)
+            ? main.tableIds.map(String)
+            : [];
+        const expectedTables = receipt.resources.tables.map((table) => table.tableId);
+        if (config.appToken !== receipt.resources.appToken ||
+            (config.larkProfile ?? undefined) !==
+                (receipt.larkProfile ?? undefined) ||
+            (config.runtimeProfile ?? ONLINE_RUNTIME_PROFILE.name) !==
+                receipt.environment ||
+            main.baseToken !== receipt.resources.baseToken ||
+            configuredTables.length !== expectedTables.length ||
+            configuredTables.some((id) => !expectedTables.includes(id)))
+            recoveryBlocked(journal, 'scaffold', 'Completed project configuration does not match the receipt');
+    }
+    else if (scaffold.status === 'not_attempted' &&
+        (scaffoldOutputs.some((output) => existsSync(join(projectRoot, output))) ||
+            existsSync(join(projectRoot, DATABASE_FUNCTIONS_DIRECTORY)) ||
+            existsSync(join(projectRoot, LEGACY_DATABASE_FUNCTIONS_DIRECTORY)))) {
+        recoveryBlocked(journal, 'scaffold', 'Project outputs exist before the recorded scaffold step');
+    }
+    return { fieldRetries };
+}
+export async function initializeProject(options) {
+    const runtimeProfile = resolveRuntimeProfile(options.environment, options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE);
+    const workspace = resolve(options.directory);
+    const databaseName = requiredString(options.name, '--name');
+    if (!options.resume) {
+        for (const output of [
+            CONFIG_FILE_NAME,
+            'catalog.json',
+            'page',
+            'server-functions',
+            DATABASE_FUNCTIONS_DIRECTORY,
+            LEGACY_DATABASE_FUNCTIONS_DIRECTORY,
+        ]) {
+            if (existsSync(join(workspace, output))) {
+                throw new Error(`Refusing to overwrite ${join(workspace, output)}`);
+            }
         }
+        assertNoInitReceipt(workspace);
     }
     const schemaPath = options.schema?.trim();
     const existingBaseToken = options.baseToken?.trim();
     const existingAppToken = options.appToken?.trim();
+    if (options.appToken !== undefined && !existingAppToken)
+        throw new Error('--app-token must be a non-empty string');
     if (Boolean(schemaPath) === Boolean(existingBaseToken)) {
         throw new Error('Provide exactly one of --schema or --base-token');
     }
+    let schema;
+    try {
+        schema = schemaPath ? readInitSchema(schemaPath) : undefined;
+    }
+    catch (error) {
+        if (!(error instanceof InitSchemaError))
+            throw error;
+        throw new InitFailureError(error.message, {
+            ok: false,
+            status: 'failed',
+            phase: 'preflight',
+            error: { message: error.message, path: error.path },
+            nextAction: 'Correct the schema at the reported path. No remote resources were created.',
+        });
+    }
     const { env, larkProfile } = resolveLarkProfileEnvironment(await runtimeProfile.commandEnvironment(), options.larkProfile, undefined, runtimeProfile);
-    const attempts = runtimeProfile.initAttempts;
     let selectedBaseToken;
     let selectedBaseUrl;
     let selectedBaseName = databaseName;
@@ -215,227 +701,363 @@ export async function initializeProject(options) {
     const baseSource = existingBaseToken
         ? 'existing'
         : 'created';
-    if (existingBaseToken) {
-        selectedBaseToken = requiredString(existingBaseToken, '--base-token');
-        process.stderr.write('Reading existing Base tables...\n');
-        const existingBase = runLarkCli(['base', '+base-get', '--base-token', selectedBaseToken], env);
-        selectedBaseUrl = baseUrl(existingBase);
-        selectedBaseName = baseName(existingBase) ?? selectedBaseToken;
-        tables = listExistingTables(selectedBaseToken, env);
-    }
-    else {
-        const schema = parseSchema(requiredString(schemaPath, '--schema'));
-        const [first, ...remaining] = schema.tables;
-        if (!first)
-            throw new Error('Schema must contain at least one table');
-        process.stderr.write(`Creating Base ${databaseName}...\n`);
-        const createdBase = await retry('base-create', attempts, () => runLarkCli([
-            'base',
-            '+base-create',
-            '--name',
-            databaseName,
-            '--time-zone',
-            options.timeZone,
-            '--table-name',
-            first.name,
-            '--fields',
-            JSON.stringify(first.fields.slice(0, 1)),
-        ], env));
-        selectedBaseToken = baseToken(createdBase);
-        selectedBaseUrl = baseUrl(createdBase);
-        tables = [
-            { name: first.name, tableId: tableId(createdBase, 'base-create') },
-        ];
-        for (const table of remaining) {
-            await pause();
-            process.stderr.write(`Creating table ${table.name}...\n`);
-            const response = await retry(`table-create ${table.name}`, attempts, () => runLarkCli([
-                'base',
-                '+table-create',
-                '--base-token',
-                selectedBaseToken,
-                '--name',
-                table.name,
-                '--fields',
-                JSON.stringify(table.fields.slice(0, 1)),
-            ], env));
-            tables.push({
-                name: table.name,
-                tableId: tableId(response, 'table-create'),
+    let journal;
+    let resumePreparation;
+    try {
+        if (options.resume) {
+            const plan = buildInitPlan(options, schema, {
+                ...(existingBaseToken ? { baseToken: existingBaseToken } : {}),
+                tables: [],
             });
+            journal = InitJournal.resume(workspace, {
+                environment: options.environment,
+                ...(larkProfile ? { larkProfile } : {}),
+                planHash: plan.planHash,
+            }, plan.steps, plan.resources, env);
+            resumePreparation = prepareResume(journal, options, schema, env);
         }
-        for (const [tableIndex, table] of schema.tables.entries()) {
-            const remainingFields = table.fields.slice(1);
-            if (remainingFields.length === 0)
-                continue;
-            const createdTable = tables[tableIndex];
-            if (!createdTable) {
-                throw new Error(`Missing created table for schema table ${table.name}`);
+        if (existingBaseToken) {
+            selectedBaseToken = requiredString(existingBaseToken, '--base-token');
+            process.stderr.write('Reading existing Base tables...\n');
+            const existingBase = runLarkCli(['base', '+base-get', '--base-token', selectedBaseToken], env);
+            selectedBaseUrl = baseUrl(existingBase);
+            selectedBaseName = baseName(existingBase) ?? selectedBaseToken;
+            tables = listExistingTables(selectedBaseToken, env);
+        }
+        else {
+            if (!schema)
+                throw new Error('Schema is required');
+            const [first, ...remaining] = schema.tables;
+            journal ??= startJournal(workspace, options, larkProfile, env, schema, {
+                tables: [],
+            });
+            if (!first)
+                throw new Error('Schema must contain at least one table');
+            const baseStep = journal.step('create-base');
+            if (baseStep.status === 'succeeded') {
+                selectedBaseToken = requiredString(journal.receipt.resources.baseToken, 'receipt Base token');
+                const saved = receiptTable(journal.receipt, first.name);
+                if (!saved)
+                    recoveryBlocked(journal, baseStep.id, `Receipt has no confirmed table ID for ${first.name}`);
+                const currentBase = runLarkCli(['base', '+base-get', '--base-token', selectedBaseToken], env);
+                selectedBaseUrl = baseUrl(currentBase);
+                selectedBaseName = baseName(currentBase) ?? databaseName;
+                tables = [saved];
+            }
+            else {
+                process.stderr.write(`Creating Base ${databaseName}...\n`);
+                const createdBase = await journal.run('create-base', () => runLarkCli([
+                    'base',
+                    '+base-create',
+                    '--name',
+                    databaseName,
+                    '--time-zone',
+                    options.timeZone,
+                    '--table-name',
+                    first.name,
+                    '--fields',
+                    JSON.stringify(first.fields.slice(0, 1)),
+                ], env), (response) => {
+                    baseToken(response);
+                    tableId(response, 'base-create');
+                });
+                selectedBaseToken = baseToken(createdBase);
+                selectedBaseUrl = baseUrl(createdBase);
+                tables = [
+                    { name: first.name, tableId: tableId(createdBase, 'base-create') },
+                ];
+            }
+            for (const [index, table] of remaining.entries()) {
+                const stepId = `create-table:${index + 1}`;
+                const step = journal.step(stepId);
+                if (step.status === 'succeeded') {
+                    const saved = receiptTable(journal.receipt, table.name);
+                    if (!saved)
+                        recoveryBlocked(journal, stepId, `Receipt has no confirmed table ID for ${table.name}`);
+                    tables.push(saved);
+                    continue;
+                }
+                await pause();
+                process.stderr.write(`Creating table ${table.name}...\n`);
+                const response = await journal.run(stepId, () => runLarkCli([
+                    'base',
+                    '+table-create',
+                    '--base-token',
+                    selectedBaseToken,
+                    '--name',
+                    table.name,
+                    '--fields',
+                    JSON.stringify(table.fields.slice(0, 1)),
+                ], env), (response) => {
+                    tableId(response, 'table-create');
+                });
+                tables.push({
+                    name: table.name,
+                    tableId: tableId(response, 'table-create'),
+                });
+            }
+            for (const [tableIndex, table] of schema.tables.entries()) {
+                const remainingFields = table.fields.slice(1);
+                if (remainingFields.length === 0)
+                    continue;
+                const stepId = `create-fields:${tableIndex}`;
+                const step = journal.step(stepId);
+                if (step.status === 'succeeded')
+                    continue;
+                const createdTable = tables[tableIndex];
+                if (!createdTable) {
+                    throw new Error(`Missing created table for schema table ${table.name}`);
+                }
+                await pause();
+                process.stderr.write(`Creating remaining fields for ${table.name}\n`);
+                const retryIndexes = resumePreparation?.fieldRetries.get(stepId);
+                if (retryIndexes)
+                    journal.prepare(stepId);
+                const fieldJournal = journal;
+                await fieldJournal.run(stepId, () => createFieldsWithRetry({
+                    journal: fieldJournal,
+                    stepId,
+                    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),
+                }));
             }
             await pause();
-            process.stderr.write(`Creating remaining fields for ${table.name}\n`);
-            await retry(`field-create ${table.name}`, attempts, () => runLarkCli([
-                'base',
-                '+field-create',
-                '--base-token',
-                selectedBaseToken,
-                '--table-id',
-                createdTable.tableId,
-                '--json',
-                JSON.stringify(remainingFields),
-            ], env));
         }
-        await pause();
-    }
-    const binding = {
-        baseToken: selectedBaseToken,
-        tableIds: tables.map((table) => table.tableId),
-    };
-    let selectedAppToken;
-    const databaseSource = existingAppToken
-        ? 'existing'
-        : 'created';
-    if (existingAppToken) {
-        selectedAppToken = requiredString(existingAppToken, '--app-token');
-        process.stderr.write('Updating the existing application metadata...\n');
-        runLarkCli([
-            'api',
-            'PATCH',
-            `/open-apis/base/v3/sites/${encodeURIComponent(selectedAppToken)}/update`,
-            '--data',
-            JSON.stringify({
-                name: options.name,
-                description: options.description ?? '',
-            }),
-        ], env);
-        process.stderr.write('Binding all tables to the existing application...\n');
-        runLarkCli([
-            'api',
-            'POST',
-            `/open-apis/base/v3/sites/${encodeURIComponent(selectedAppToken)}/bind_base`,
-            '--data',
-            JSON.stringify(binding),
-        ], env);
-    }
-    else {
-        process.stderr.write('Creating application and binding all tables...\n');
-        const createdDatabase = runLarkCli([
-            'api',
-            'POST',
-            '/open-apis/base/v3/sites/create',
-            '--data',
-            JSON.stringify({
-                name: databaseName,
-                description: options.description ?? '',
-                baseBindings: [binding],
-            }),
-        ], env);
-        selectedAppToken = appToken(createdDatabase);
-    }
-    const encodedToken = encodeURIComponent(selectedAppToken);
-    const catalog = await retry('catalog', 5, () => {
-        const response = runLarkCli(['api', 'GET', `/open-apis/base/v3/sites/${encodedToken}/catalog`], env);
-        return validateCatalog(response.data, selectedBaseToken, tables);
-    });
-    mkdirSync(workspace, { recursive: true });
-    for (const directory of ['page', 'server-functions', 'sql']) {
-        cpSync(join(starterRoot, directory), join(workspace, directory), {
-            recursive: true,
+        journal ??= startJournal(workspace, options, larkProfile, env, schema, {
+            baseToken: selectedBaseToken,
+            tables,
         });
-    }
-    writePageTitle(workspace, databaseName);
-    runtimeProfile.prepareWorkspace?.(workspace);
-    const readmePath = join(workspace, 'README.md');
-    if (!existsSync(readmePath)) {
-        cpSync(join(starterRoot, 'README.md'), readmePath);
-    }
-    mergeIgnoreFile(join(workspace, '.gitignore'), join(starterRoot, 'gitignore'));
-    mergeIgnoreFile(join(workspace, '.prettierignore'), join(starterRoot, 'prettierignore'));
-    writeFileSync(join(workspace, 'catalog.json'), `${JSON.stringify(catalog, null, 2)}\n`);
-    const configPath = writeConfig(workspace, {
-        configVersion: 1,
-        ...(larkProfile ? { larkProfile } : {}),
-        name: basename(workspace),
-        ...(runtimeProfile.name === ONLINE_RUNTIME_PROFILE.name
-            ? {}
-            : { runtimeProfile: runtimeProfile.name }),
-        appToken: selectedAppToken,
-        bindings: {
-            MAIN_BASE: {
-                type: 'base',
-                baseToken: selectedBaseToken,
-                tableIds: tables.map((table) => table.tableId),
-            },
-        },
-    });
-    const base = {
-        name: selectedBaseName,
-        token: selectedBaseToken,
-        ...(selectedBaseUrl ? { url: selectedBaseUrl } : {}),
-        tables,
-    };
-    const baseAppUrl = catalogBaseAppUrl(catalog);
-    return {
-        ok: true,
-        environment: runtimeProfile.name,
-        workspace,
-        ...(larkProfile ? { larkProfile } : {}),
-        config: configPath,
-        catalog: join(workspace, 'catalog.json'),
-        baseSource,
-        databaseSource,
-        baseToken: selectedBaseToken,
-        ...(selectedBaseUrl ? { baseUrl: selectedBaseUrl } : {}),
-        tables,
-        appToken: selectedAppToken,
-        ...(baseAppUrl ? { baseAppUrl } : {}),
-        ...(baseSource === 'existing' || databaseSource === 'existing'
-            ? {
-                reused: {
-                    ...(baseSource === 'existing' ? { base } : {}),
-                    ...(databaseSource === 'existing'
-                        ? {
-                            database: {
-                                name: databaseName,
-                                token: selectedAppToken,
-                                binding,
-                            },
-                        }
-                        : {}),
-                },
+        const binding = {
+            baseToken: selectedBaseToken,
+            tableIds: tables.map((table) => table.tableId),
+        };
+        let selectedAppToken;
+        const databaseSource = existingAppToken
+            ? 'existing'
+            : 'created';
+        if (existingAppToken) {
+            selectedAppToken = requiredString(existingAppToken, '--app-token');
+            if (journal.step('update-app').status !== 'succeeded') {
+                process.stderr.write('Updating the existing application metadata...\n');
+                await journal.run('update-app', () => runLarkCli([
+                    'api',
+                    'PATCH',
+                    `/open-apis/base/v3/sites/${encodeURIComponent(selectedAppToken)}/update`,
+                    '--data',
+                    JSON.stringify({
+                        name: databaseName,
+                        description: options.description ?? '',
+                    }),
+                ], env));
             }
-            : {}),
-        created: {
-            ...(baseSource === 'created' ? { base } : {}),
-            ...(databaseSource === 'created'
-                ? {
-                    database: {
+            if (journal.step('bind-base').status !== 'succeeded') {
+                process.stderr.write('Binding all tables to the existing application...\n');
+                await journal.run('bind-base', () => runLarkCli([
+                    'api',
+                    'POST',
+                    `/open-apis/base/v3/sites/${encodeURIComponent(selectedAppToken)}/bind_base`,
+                    '--data',
+                    JSON.stringify(binding),
+                ], env));
+            }
+        }
+        else {
+            if (journal.step('create-app').status === 'succeeded') {
+                selectedAppToken = requiredString(journal.receipt.resources.appToken, 'receipt application token');
+            }
+            else {
+                process.stderr.write('Creating application and binding all tables...\n');
+                const createdDatabase = await journal.run('create-app', () => runLarkCli([
+                    'api',
+                    'POST',
+                    '/open-apis/base/v3/sites/create',
+                    '--data',
+                    JSON.stringify({
                         name: databaseName,
-                        token: selectedAppToken,
-                        binding,
+                        description: options.description ?? '',
+                        baseBindings: [binding],
+                    }),
+                ], env), (response) => {
+                    appToken(response);
+                });
+                selectedAppToken = appToken(createdDatabase);
+            }
+        }
+        const encodedToken = encodeURIComponent(selectedAppToken);
+        const catalog = await journal.run('read-catalog', () => retry('catalog', 5, () => {
+            const response = runLarkCli(['api', 'GET', `/open-apis/base/v3/sites/${encodedToken}/catalog`], env);
+            return validateCatalog(response.data, selectedBaseToken, tables);
+        }));
+        if (journal.step('scaffold').status === 'succeeded') {
+            let localCatalog;
+            try {
+                localCatalog = JSON.parse(readFileSync(join(workspace, 'catalog.json'), 'utf8'));
+            }
+            catch {
+                recoveryBlocked(journal, 'scaffold', 'Completed project Catalog is missing or invalid');
+            }
+            if (JSON.stringify(stableJson(localCatalog)) !==
+                JSON.stringify(stableJson(catalog)))
+                recoveryBlocked(journal, 'scaffold', 'Remote Catalog changed after local scaffolding completed');
+        }
+        const configPath = journal.step('scaffold').status === 'succeeded'
+            ? join(workspace, CONFIG_FILE_NAME)
+            : await journal.run('scaffold', () => {
+                mkdirSync(workspace, { recursive: true });
+                for (const directory of [
+                    'page',
+                    'server-functions',
+                    'mutations',
+                    DATABASE_FUNCTIONS_DIRECTORY,
+                ]) {
+                    cpSync(join(starterRoot, directory), join(workspace, directory), {
+                        recursive: true,
+                    });
+                }
+                writePageTitle(workspace, databaseName);
+                runtimeProfile.prepareWorkspace?.(workspace);
+                const readmePath = join(workspace, 'README.md');
+                if (!existsSync(readmePath)) {
+                    cpSync(join(starterRoot, 'README.md'), readmePath);
+                }
+                mergeIgnoreFile(join(workspace, '.gitignore'), join(starterRoot, 'gitignore'));
+                mergeIgnoreFile(join(workspace, '.prettierignore'), join(starterRoot, 'prettierignore'));
+                writeFileSync(join(workspace, 'catalog.json'), `${JSON.stringify(catalog, null, 2)}\n`);
+                return writeConfig(workspace, {
+                    configVersion: 1,
+                    ...(larkProfile ? { larkProfile } : {}),
+                    name: basename(workspace),
+                    ...(runtimeProfile.name === ONLINE_RUNTIME_PROFILE.name
+                        ? {}
+                        : { runtimeProfile: runtimeProfile.name }),
+                    appToken: selectedAppToken,
+                    bindings: {
+                        MAIN_BASE: {
+                            type: 'base',
+                            baseToken: selectedBaseToken,
+                            tableIds: tables.map((table) => table.tableId),
+                        },
+                    },
+                });
+            });
+        journal.complete();
+        const base = {
+            name: selectedBaseName,
+            token: selectedBaseToken,
+            ...(selectedBaseUrl ? { url: selectedBaseUrl } : {}),
+            tables,
+        };
+        const baseAppUrl = catalogBaseAppUrl(catalog);
+        return {
+            ok: true,
+            initialization: {
+                journal: journal.path,
+                status: 'succeeded',
+                ...(options.resume ? { resumed: true } : {}),
+            },
+            environment: runtimeProfile.name,
+            workspace,
+            ...(larkProfile ? { larkProfile } : {}),
+            config: configPath,
+            catalog: join(workspace, 'catalog.json'),
+            baseSource,
+            databaseSource,
+            baseToken: selectedBaseToken,
+            ...(selectedBaseUrl ? { baseUrl: selectedBaseUrl } : {}),
+            tables,
+            appToken: selectedAppToken,
+            ...(baseAppUrl ? { baseAppUrl } : {}),
+            ...(baseSource === 'existing' || databaseSource === 'existing'
+                ? {
+                    reused: {
+                        ...(baseSource === 'existing' ? { base } : {}),
+                        ...(databaseSource === 'existing'
+                            ? {
+                                database: {
+                                    name: databaseName,
+                                    token: selectedAppToken,
+                                    binding,
+                                },
+                            }
+                            : {}),
                     },
                 }
                 : {}),
-            project: {
-                directory: workspace,
-                config: configPath,
-                catalog: join(workspace, 'catalog.json'),
-                source: workspace,
-            },
-        },
-        nextSteps: [
-            {
-                action: 'develop',
-                workingDirectory: workspace,
-                description: 'Read catalog.json, then implement the complete Page, SQL Functions, and server-side FaaS Functions under page/, sql/, and server-functions/ in one pass.',
+            created: {
+                ...(baseSource === 'created' ? { base } : {}),
+                ...(databaseSource === 'created'
+                    ? {
+                        database: {
+                            name: databaseName,
+                            token: selectedAppToken,
+                            binding,
+                        },
+                    }
+                    : {}),
+                project: {
+                    directory: workspace,
+                    config: configPath,
+                    catalog: join(workspace, 'catalog.json'),
+                    source: workspace,
+                },
             },
-            {
-                action: 'deployPreview',
-                workingDirectory: workspace,
-                command: runtimeProfile.deployCommand,
-                description: 'Run this single command after implementation; it installs, builds, validates, uploads, publishes, and returns baseAppUrl.',
+            developmentReadiness: {
+                status: 'not_checked',
+                dependencies: 'not_prepared',
+                command: runtimeProfile.checkCommand,
+                scope: 'local',
+                sqlValidation: 'not_run',
+                description: 'Initialization scaffolds source files but does not prepare Page/FaaS dependencies or run the local project check.',
             },
-        ],
-    };
+            nextSteps: [
+                {
+                    action: 'develop',
+                    workingDirectory: workspace,
+                    description: 'Read catalog.json, then implement the complete Page, Database Functions, Mutation Functions, and server-side FaaS Functions under page/, database-functions/, mutations/, and server-functions/ in one pass.',
+                },
+                {
+                    action: 'checkLocal',
+                    workingDirectory: workspace,
+                    command: runtimeProfile.checkCommand,
+                    description: 'Run the supported local check after implementation. It regenerates Page Function input types from local metadata, may install Page/FaaS dependencies, and writes build output; it does not validate server-side Database Function queries or runtime behavior and does not deploy.',
+                },
+                {
+                    action: 'deployPreview',
+                    workingDirectory: workspace,
+                    command: runtimeProfile.deployCommand,
+                    description: 'Run this command after the local check passes; it repeats required build checks, validates server-side Database Function queries, uploads, publishes, and returns baseAppUrl.',
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof InitFailureError)
+            throw error;
+        if (journal)
+            throw journal.failure(error);
+        throw error;
+    }
+    finally {
+        journal?.close();
+    }
+}
+function startJournal(workspace, options, larkProfile, env, schema, resources) {
+    const plan = buildInitPlan(options, schema, resources);
+    return new InitJournal(workspace, {
+        environment: options.environment,
+        ...(larkProfile ? { larkProfile } : {}),
+        planHash: plan.planHash,
+    }, plan.steps, plan.resources, env);
 }
 //# sourceMappingURL=init.js.map