@lark-base-open/base-database-cli 1.4.0 → 1.4.5

package/dist/function-input-types.js

@@ -1,138 +1,14 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { namedSQLParamSchema } from './function-schema.js';
+import { PARAMETER_NAME_PATTERN } from './function-params.js';
+import { readConfig } from './config.js';
+import { requiresSDKCodegen, runSDKCodegen } from './sdk-codegen.js';
+import { projectLayout } from './project-layout.js';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { readDatabaseFunctionInputContracts } from './archive.js';
 const GENERATED_INPUT_TYPES = join('page', 'src', 'lib', 'database-function-inputs.generated.ts');
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function literalType(value) {
-    if (value === null)
-        return 'null';
-    if (typeof value === 'string' || typeof value === 'boolean') {
-        return JSON.stringify(value);
-    }
-    if (typeof value === 'number' && Number.isFinite(value)) {
-        return Object.is(value, -0) ? '-0' : String(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(literalType).join(', ')}]`;
-    }
-    if (isRecord(value)) {
-        return `{ ${Object.entries(value)
-            .map(([key, child]) => `${JSON.stringify(key)}: ${literalType(child)}`)
-            .join('; ')} }`;
-    }
-    return 'never';
-}
-function enumValueMatchesType(value, type) {
-    switch (type) {
-        case 'string':
-            return typeof value === 'string';
-        case 'integer':
-            return typeof value === 'number' && Number.isInteger(value);
-        case 'number':
-            return typeof value === 'number' && Number.isFinite(value);
-        case 'boolean':
-            return typeof value === 'boolean';
-        case 'null':
-            return value === null;
-        case 'array':
-            return Array.isArray(value);
-        case 'object':
-            return isRecord(value);
-        default:
-            return false;
-    }
-}
-function schemaTypes(schema) {
-    if (typeof schema.type === 'string')
-        return [schema.type];
-    if (Array.isArray(schema.type)) {
-        return schema.type.filter((type) => typeof type === 'string');
-    }
-    return [];
-}
-function schemaTypeFor(schema, type) {
-    switch (type) {
-        case 'string':
-            return 'string';
-        case 'integer':
-        case 'number':
-            return 'number';
-        case 'boolean':
-            return 'boolean';
-        case 'null':
-            return 'null';
-        case 'array': {
-            const rawPrefixItems = schema.prefixItems;
-            const hasPrefixItems = Array.isArray(rawPrefixItems);
-            const prefixItems = hasPrefixItems ? rawPrefixItems.filter(isRecord) : [];
-            if (hasPrefixItems &&
-                schema.minItems === prefixItems.length &&
-                schema.maxItems === prefixItems.length) {
-                return `[${prefixItems.map(schemaType).join(', ')}]`;
-            }
-            const itemType = isRecord(schema.items)
-                ? schemaType(schema.items)
-                : 'unknown';
-            if (prefixItems.length === 0)
-                return `Array<${itemType}>`;
-            const tupleItems = prefixItems.map((item) => `${schemaType(item)}?`);
-            return `[${[...tupleItems, `...Array<${itemType}>`].join(', ')}]`;
-        }
-        case 'object': {
-            const properties = isRecord(schema.properties) ? schema.properties : {};
-            const required = new Set(Array.isArray(schema.required)
-                ? schema.required.filter((value) => typeof value === 'string')
-                : []);
-            const propertyEntries = Object.entries(properties).filter((entry) => isRecord(entry[1]));
-            const propertyNames = new Set(propertyEntries.map(([key]) => key));
-            const missingRequired = [...required].filter((key) => !propertyNames.has(key));
-            if (missingRequired.length > 0 && schema.additionalProperties === false) {
-                return 'never';
-            }
-            const members = propertyEntries.map(([key, child]) => `${JSON.stringify(key)}${required.has(key) ? '' : '?'}: ${schemaType(child)}`);
-            members.push(...missingRequired.map((key) => `${JSON.stringify(key)}: unknown`));
-            const objectType = `{ ${members.join('; ')} }`;
-            if (schema.additionalProperties === false) {
-                return members.length === 0 ? 'Record<string, never>' : objectType;
-            }
-            return `${objectType} & Record<string, unknown>`;
-        }
-        default:
-            return 'unknown';
-    }
-}
-function schemaType(schema) {
-    const types = schemaTypes(schema);
-    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
-        const compatible = schema.enum.filter((value) => types.some((type) => enumValueMatchesType(value, type)));
-        if (compatible.length === 0)
-            return 'never';
-        return compatible.map(literalType).join(' | ');
-    }
-    const rendered = [
-        ...new Set(types.map((type) => schemaTypeFor(schema, type))),
-    ];
-    return rendered.length === 0 ? 'unknown' : rendered.join(' | ');
-}
-export function renderDatabaseFunctionInputTypes(contracts) {
-    const members = [...contracts]
-        .sort((left, right) => left.functionId < right.functionId
-        ? -1
-        : left.functionId > right.functionId
-            ? 1
-            : 0)
-        .map((contract) => `  ${JSON.stringify(contract.functionId)}: ${schemaType(contract.inputSchema)}`);
-    return [
-        '/* Generated by base-database-cli from Function metadata. Do not edit. */',
-        '// prettier-ignore',
-        'export type DatabaseFunctionInputMap = {',
-        ...members,
-        '}',
-        '',
-    ].join('\n');
-}
+import { renderDatabaseFunctionInputTypes } from './legacy-function-input-renderer.js';
+export { renderDatabaseFunctionInputTypes } from './legacy-function-input-renderer.js';
 function writeIfChanged(path, content) {
     try {
         if (readFileSync(path, 'utf8') === content)
@@ -146,10 +22,96 @@ function writeIfChanged(path, content) {
     writeFileSync(temporary, content);
     renameSync(temporary, path);
 }
+/** Public layout/declaration contract; never inspect Page source or SDK installation. */
+export function resolveFunctionInputMode(workspace, consumer = 'page') {
+    const config = readConfig(workspace);
+    if (consumer === 'sdk-client' || config.template?.version === 2)
+        return 'named';
+    return config.functionInputs ?? 'positional';
+}
+export function namedInputSchema(contract) {
+    if (contract.functionType === 2)
+        return contract.inputSchema;
+    const properties = Object.create(null);
+    const required = [];
+    for (const [index, param] of (contract.parameters ?? []).entries()) {
+        const name = param.name;
+        if (typeof name !== 'string' ||
+            !PARAMETER_NAME_PATTERN.test(name) ||
+            Object.hasOwn(properties, name)) {
+            throw new Error(`${contract.functionId}: parameter ${index + 1} needs a unique explicit name matching the frozen server declaration; do not infer names from SQL`);
+        }
+        let schema;
+        if (contract.functionType === 1) {
+            schema = namedSQLParamSchema(param, index);
+        }
+        else {
+            const kind = param.kind;
+            const type = kind === 'BOOL'
+                ? 'boolean'
+                : ['INT', 'DOUBLE', 'DURATION'].includes(String(kind))
+                    ? 'number'
+                    : kind === 'ATTACHMENT'
+                        ? 'object'
+                        : kind === 'TIMESTAMP'
+                            ? ['string', 'number']
+                            : 'string';
+            schema = {
+                type,
+                ...(Array.isArray(param.enum) ? { enum: param.enum } : {}),
+            };
+            if (param.list === true)
+                schema = {
+                    type: 'array',
+                    items: schema,
+                    minItems: 0,
+                    maxItems: param.maxItems ?? 200,
+                };
+            if (typeof param.description === 'string')
+                schema.description = param.description;
+            if (param.required === false)
+                schema = { anyOf: [schema, { type: 'null' }] };
+        }
+        if (typeof param.description === 'string')
+            schema.description = param.description;
+        properties[name] = schema;
+        if (contract.functionType === 1 || param.required !== false)
+            required.push(name);
+    }
+    return { type: 'object', properties, required, additionalProperties: false };
+}
 export function syncDatabaseFunctionInputTypes(workspace) {
-    const contracts = readDatabaseFunctionInputContracts(workspace);
-    const path = join(workspace, GENERATED_INPUT_TYPES);
-    writeIfChanged(path, renderDatabaseFunctionInputTypes(contracts));
+    const contracts = readDatabaseFunctionInputContracts(workspace, {
+        enforceDescriptions: false,
+    });
+    const version = projectLayout(workspace).version;
+    const obsolete = join(workspace, 'page/src/generated/function-inputs.d.ts');
+    if (version === 2 &&
+        existsSync(obsolete) &&
+        !readFileSync(obsolete, 'utf8').startsWith('/* Generated by base-database-cli from Function metadata. Do not edit. */'))
+        throw new Error('FUNCTION_INPUT_MODULE_CONFLICT: unrecognized function-inputs.d.ts; review it before regenerating');
+    const path = join(workspace, version === 2
+        ? 'page/src/generated/function-inputs.ts'
+        : GENERATED_INPUT_TYPES);
+    const inputs = resolveFunctionInputMode(workspace) === 'named'
+        ? contracts.map((c) => ({ ...c, inputSchema: namedInputSchema(c) }))
+        : contracts;
+    if (requiresSDKCodegen(workspace)) {
+        for (const file of runSDKCodegen(workspace, {
+            contractFormatVersion: 1,
+            layout: version === 2 ? 'workspace' : 'classic',
+            schemaHash: '',
+            functions: [],
+            inputs,
+            client: false,
+            augmentation: 'none',
+        }))
+            writeIfChanged(join(workspace, file.path), file.content);
+    }
+    else
+        writeIfChanged(path, renderDatabaseFunctionInputTypes(inputs));
+    if (version === 2 && existsSync(obsolete))
+        unlinkSync(obsolete);
     return {
         sql: contracts.filter((contract) => contract.functionType === 1).length,
         faas: contracts.filter((contract) => contract.functionType === 2).length,

package/dist/function-input-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"function-input-types.js","sourceRoot":"","sources":["../src/function-input-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,kCAAkC,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,qBAAqB,GAAG,IAAI,CAChC,MAAM,EACN,KAAK,EACL,KAAK,EACL,uCAAuC,CACxC,CAAC;AAEF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAClD,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;aACtE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc,EAAE,IAAY;IACxD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;QACnC,KAAK,SAAS;YACZ,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC9D,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7D,KAAK,SAAS;YACZ,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;QACpC,KAAK,MAAM;YACT,OAAO,KAAK,KAAK,IAAI,CAAC;QACxB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzB;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAA+B;IAClD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CACvB,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,aAAa,CAAC,MAA+B,EAAE,IAAY;IAClE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO,EAAE,CAAC;YACb,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC;YAC1C,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;YACrD,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,IACE,cAAc;gBACd,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,MAAM;gBACtC,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,MAAM,EACtC,CAAC;gBACD,OAAO,IAAI,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YACvD,CAAC;YACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;gBACrC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC1B,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,SAAS,QAAQ,GAAG,CAAC;YAE1D,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,GAAG,UAAU,EAAE,YAAY,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACpE,CAAC;QACD,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;gBAC5B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CACpB,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CACtD;gBACH,CAAC,CAAC,EAAE,CACP,CAAC;YACF,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CACvD,CAAC,KAAK,EAA8C,EAAE,CACpD,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACrB,CAAC;YACF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACnE,MAAM,eAAe,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,CAC1C,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CACjC,CAAC;YACF,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,oBAAoB,KAAK,KAAK,EAAE,CAAC;gBACxE,OAAO,OAAO,CAAC;YACjB,CAAC;YACD,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CACjC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACf,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,UAAU,CAAC,KAAK,CAAC,EAAE,CAChF,CAAC;YACF,OAAO,CAAC,IAAI,CACV,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CACnE,CAAC;YACF,MAAM,UAAU,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAC/C,IAAI,MAAM,CAAC,oBAAoB,KAAK,KAAK,EAAE,CAAC;gBAC1C,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,UAAU,CAAC;YACrE,CAAC;YACD,OAAO,GAAG,UAAU,4BAA4B,CAAC;QACnD,CAAC;QACD;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,MAA+B;IACjD,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAC9C,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CACxD,CAAC;QACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC;QAC5C,OAAO,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,QAAQ,GAAG;QACf,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;KAC7D,CAAC;IACF,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,SAGE;IAEF,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC;SAC3B,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACpB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;QAChC,CAAC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;YAClC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CACR;SACA,GAAG,CACF,CAAC,QAAQ,EAAE,EAAE,CACX,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAClF,CAAC;IACJ,OAAO;QACL,2EAA2E;QAC3E,oBAAoB;QACpB,0CAA0C;QAC1C,GAAG,OAAO;QACV,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,OAAe;IACnD,IAAI,CAAC;QACH,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO;YAAE,OAAO;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;IACvD,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,SAAiB;IAC9D,MAAM,SAAS,GAAG,kCAAkC,CAAC,SAAS,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;IACpD,cAAc,CAAC,IAAI,EAAE,gCAAgC,CAAC,SAAS,CAAC,CAAC,CAAC;IAClE,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM;QACvE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM;QACxE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,CAAC;aAClE,MAAM;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"function-input-types.js","sourceRoot":"","sources":["../src/function-input-types.ts"],"names":[],"mappings":"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"}

package/dist/function-params.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Author-declared parameter contract shared by Database Function `meta.params[]`
+ * and Mutation `spec.params[]`. The service renders the Agent-facing inputSchema
+ * from these declarations; the CLI only checks the same deterministic rules
+ * before upload and reports soft hints without blocking.
+ */
+export declare const AGENT_TOOL_DESIGN_REFERENCE = "references/agent-tool-design.md in the lark-base-database Skill";
+export declare const PARAMETER_NAME_PATTERN: RegExp;
+export declare const MAX_PARAMETER_DESCRIPTION = 500;
+export declare const SHORT_DESCRIPTION_THRESHOLD = 8;
+export type FunctionHintKind = 'short_description' | 'binding' | 'enum_unchecked' | 'function_description';
+/** One non-blocking authoring hint; local hints and service `results[].hints[]` share this shape. */
+export interface FunctionHint {
+    functionId?: string;
+    /** JSON Pointer inside the declaration, prefixed by the source file for local hints. */
+    path: string;
+    kind: string;
+    message: string;
+}
+export type EnumValueType = 'string' | 'integer' | 'number' | 'boolean';
+export interface DeclaredParameterResult {
+    problems: string[];
+    hints: FunctionHint[];
+}
+export declare function shortDescriptionHint(path: string, subject: string): FunctionHint;
+/**
+ * Check `description` of one declared parameter or FaaS property.
+ * Missing/blank/too long is a problem; shorter than the threshold is only a hint.
+ */
+export declare function checkParameterDescription(description: unknown, label: string, path: string, result: DeclaredParameterResult): void;
+/**
+ * Validate `name`, `description` and optional `enum` of a declared parameter list.
+ * `enumType` maps one parameter to the JSON type its enum values (or array
+ * elements) must use; `undefined` means the kind does not accept enum.
+ */
+export declare function checkDeclaredParameters(params: readonly unknown[], options: {
+    /** Label prefix such as `meta.params` or `spec.params`. */
+    label: string;
+    /** JSON Pointer prefix such as `/meta/params`. */
+    pointer: string;
+    /** Source file used to prefix hint paths. */
+    file: string;
+    enumType: (param: Record<string, unknown>) => EnumValueType | undefined;
+}): DeclaredParameterResult;
+/** SQL `meta.params[].kind` → enum value type; `TEXT[]` constrains elements. */
+export declare function sqlEnumType(param: Record<string, unknown>): EnumValueType | undefined;
+/** Mutation `spec.params[].kind` → enum value type; `list:true` constrains elements. */
+export declare function mutationEnumType(param: Record<string, unknown>): EnumValueType | undefined;
+/** Format collected hints for one-line human output. */
+export declare function formatFunctionHint(hint: FunctionHint): string;
+/** Read `results[].hints[]` from a PUT/validate response without failing on absent hints. */
+export declare function responseFunctionHints(data: Record<string, unknown>, functionIds?: readonly string[]): FunctionHint[];
+//# sourceMappingURL=function-params.d.ts.map

package/dist/function-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-params.d.ts","sourceRoot":"","sources":["../src/function-params.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,2BAA2B,oEAC2B,CAAC;AAEpE,eAAO,MAAM,sBAAsB,QAAiC,CAAC;AACrE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAI7C,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,SAAS,GACT,gBAAgB,GAChB,sBAAsB,CAAC;AAE3B,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAuBD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,YAAY,CAMd;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,uBAAuB,GAC9B,IAAI,CAgBN;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,OAAO,EAAE;IACP,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,aAAa,GAAG,SAAS,CAAC;CACzE,GACA,uBAAuB,CAiFzB;AASD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,aAAa,GAAG,SAAS,CAM3B;AAYD,wFAAwF;AACxF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,aAAa,GAAG,SAAS,CAI3B;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAG7D;AAED,6FAA6F;AAC7F,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,YAAY,EAAE,CAsBhB"}

package/dist/function-params.js

@@ -0,0 +1,184 @@
+/**
+ * Author-declared parameter contract shared by Database Function `meta.params[]`
+ * and Mutation `spec.params[]`. The service renders the Agent-facing inputSchema
+ * from these declarations; the CLI only checks the same deterministic rules
+ * before upload and reports soft hints without blocking.
+ */
+export const AGENT_TOOL_DESIGN_REFERENCE = 'references/agent-tool-design.md in the lark-base-database Skill';
+export const PARAMETER_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+export const MAX_PARAMETER_DESCRIPTION = 500;
+export const SHORT_DESCRIPTION_THRESHOLD = 8;
+const MAX_ENUM_ITEMS = 100;
+const MAX_ENUM_ITEM_LENGTH = 255;
+function codePoints(value) {
+    return [...value].length;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function enumValueMatches(value, type) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'integer':
+            return typeof value === 'number' && Number.isSafeInteger(value);
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+    }
+}
+export function shortDescriptionHint(path, subject) {
+    return {
+        path,
+        kind: 'short_description',
+        message: `${subject} description is shorter than ${SHORT_DESCRIPTION_THRESHOLD} characters; state the business meaning, unit and how the caller obtains the value. See ${AGENT_TOOL_DESIGN_REFERENCE}.`,
+    };
+}
+/**
+ * Check `description` of one declared parameter or FaaS property.
+ * Missing/blank/too long is a problem; shorter than the threshold is only a hint.
+ */
+export function checkParameterDescription(description, label, path, result) {
+    if (typeof description !== 'string' || description.trim() === '') {
+        result.problems.push(`${label}.description is required and must be a non-blank string`);
+        return;
+    }
+    if (codePoints(description) > MAX_PARAMETER_DESCRIPTION) {
+        result.problems.push(`${label}.description must contain at most ${MAX_PARAMETER_DESCRIPTION} Unicode characters`);
+        return;
+    }
+    if (codePoints(description.trim()) < SHORT_DESCRIPTION_THRESHOLD) {
+        result.hints.push(shortDescriptionHint(path, label));
+    }
+}
+/**
+ * Validate `name`, `description` and optional `enum` of a declared parameter list.
+ * `enumType` maps one parameter to the JSON type its enum values (or array
+ * elements) must use; `undefined` means the kind does not accept enum.
+ */
+export function checkDeclaredParameters(params, options) {
+    const result = { problems: [], hints: [] };
+    const names = new Set();
+    params.forEach((param, index) => {
+        const label = `${options.label}[${index}]`;
+        const pointer = `${options.pointer}/${index}`;
+        if (!isRecord(param)) {
+            result.problems.push(`${label} must be an object`);
+            return;
+        }
+        const { name } = param;
+        if (typeof name !== 'string' || name === '') {
+            result.problems.push(`${label}.name is required; give every parameter a stable name such as "periodId"`);
+        }
+        else if (!PARAMETER_NAME_PATTERN.test(name)) {
+            result.problems.push(`${label}.name must match ${PARAMETER_NAME_PATTERN.source}`);
+        }
+        else if (names.has(name)) {
+            result.problems.push(`${label}.name duplicates ${JSON.stringify(name)}; names must be unique within one Function`);
+        }
+        else {
+            names.add(name);
+        }
+        checkParameterDescription(param.description, label, `${options.file}#${pointer}/description`, result);
+        if (param.enum === undefined)
+            return;
+        const values = param.enum;
+        if (!Array.isArray(values) || values.length === 0) {
+            result.problems.push(`${label}.enum must be a non-empty array`);
+            return;
+        }
+        const type = options.enumType(param);
+        if (!type) {
+            result.problems.push(`${label}.enum is only supported for string, integer, number or boolean kinds (kind ${JSON.stringify(param.kind)})`);
+            return;
+        }
+        if (values.length > MAX_ENUM_ITEMS) {
+            result.problems.push(`${label}.enum must contain at most ${MAX_ENUM_ITEMS} values`);
+        }
+        const seen = new Set();
+        values.forEach((value, valueIndex) => {
+            const valueLabel = `${label}.enum[${valueIndex}]`;
+            if (value === null) {
+                result.problems.push(`${valueLabel} must not be null; nullable parameters keep their null branch without listing null in enum`);
+                return;
+            }
+            if (!enumValueMatches(value, type)) {
+                result.problems.push(`${valueLabel} must be a JSON ${type} to match kind ${JSON.stringify(param.kind)}`);
+                return;
+            }
+            if (typeof value === 'string' &&
+                codePoints(value) > MAX_ENUM_ITEM_LENGTH) {
+                result.problems.push(`${valueLabel} must contain at most ${MAX_ENUM_ITEM_LENGTH} Unicode characters`);
+            }
+            const key = JSON.stringify(value);
+            if (seen.has(key)) {
+                result.problems.push(`${valueLabel} duplicates ${key}`);
+            }
+            seen.add(key);
+        });
+    });
+    return result;
+}
+const SQL_ENUM_TYPES = {
+    TEXT: 'string',
+    INT: 'integer',
+    DOUBLE: 'number',
+    BOOL: 'boolean',
+};
+/** SQL `meta.params[].kind` → enum value type; `TEXT[]` constrains elements. */
+export function sqlEnumType(param) {
+    if (typeof param.kind !== 'string')
+        return undefined;
+    const scalar = param.kind.endsWith('[]')
+        ? param.kind.slice(0, -2)
+        : param.kind;
+    return SQL_ENUM_TYPES[scalar];
+}
+const MUTATION_ENUM_TYPES = {
+    TEXT: 'string',
+    USER_ID: 'string',
+    GROUP_ID: 'string',
+    RECORD_ID: 'string',
+    INT: 'integer',
+    DOUBLE: 'number',
+    BOOL: 'boolean',
+};
+/** Mutation `spec.params[].kind` → enum value type; `list:true` constrains elements. */
+export function mutationEnumType(param) {
+    return typeof param.kind === 'string'
+        ? MUTATION_ENUM_TYPES[param.kind]
+        : undefined;
+}
+/** Format collected hints for one-line human output. */
+export function formatFunctionHint(hint) {
+    const prefix = hint.functionId ? `${hint.functionId}: ` : '';
+    return `${prefix}${hint.path}: ${hint.message}`;
+}
+/** Read `results[].hints[]` from a PUT/validate response without failing on absent hints. */
+export function responseFunctionHints(data, functionIds = []) {
+    if (!Array.isArray(data.results))
+        return [];
+    return data.results.flatMap((item, index) => {
+        if (!isRecord(item) || !Array.isArray(item.hints))
+            return [];
+        const functionId = typeof item.functionId === 'string'
+            ? item.functionId
+            : typeof item.function_key === 'string'
+                ? item.function_key
+                : functionIds[index];
+        return item.hints.flatMap((hint) => {
+            if (!isRecord(hint) || typeof hint.message !== 'string')
+                return [];
+            return [
+                {
+                    ...(functionId ? { functionId } : {}),
+                    path: typeof hint.path === 'string' ? hint.path : '',
+                    kind: typeof hint.kind === 'string' ? hint.kind : 'hint',
+                    message: hint.message,
+                },
+            ];
+        });
+    });
+}
+//# sourceMappingURL=function-params.js.map

package/dist/function-params.js.map

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

package/dist/function-schema.d.ts

@@ -1,3 +1,17 @@
+import { type DeclaredParameterResult } from './function-params.js';
 export declare function normalizeFunctionInputSchema(value: unknown, source: string): string;
+/** Named-route declaration projection; mirrors the server's nullable/range/enum semantics. */
+export declare function namedSQLParamSchema(param: Record<string, unknown>, index: number): Record<string, unknown>;
+/**
+ * Local Page input contract for the positional `invoke_function` route.
+ * It is never uploaded: the service renders the Agent-facing named-object
+ * inputSchema from `meta.params` itself.
+ */
 export declare function deriveSQLInputSchema(meta: Record<string, unknown>, sql: string): string;
+/**
+ * FaaS discovery contract on top of the Schema subset: the root is an object and
+ * every top-level business property (its key is the parameter name) carries a
+ * non-blank description. Short descriptions are hints only.
+ */
+export declare function checkFaaSInputSchemaContract(value: unknown, file: string): DeclaredParameterResult;
 //# sourceMappingURL=function-schema.d.ts.map

package/dist/function-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"function-schema.d.ts","sourceRoot":"","sources":["../src/function-schema.ts"],"names":[],"mappings":"AAwPA,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAOR;AAiJD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAmCR"}
+{"version":3,"file":"function-schema.d.ts","sourceRoot":"","sources":["../src/function-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAqR9B,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAOR;AAmFD,8FAA8F;AAC9F,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AA0ED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAkCR;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,uBAAuB,CAiBzB"}