@lark-base-open/base-database-cli 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [1.0.0] - 2026-09-08
+
+### Added
+
+- 首次发布 Base Database CLI 与配套 Agent Skill。
+
+## 历史版本
+
+- [0.x 版本归档](changelog/CHANGELOG-0.x.md)

package/README.md

@@ -0,0 +1,169 @@
+# Base Database CLI
+
+`@lark-base-open/base-database-cli` 为 Coding Agent 提供 `lark-base-database`
+Skill 和配套 CLI，用于基于飞书多维表格创建、开发并发布数据库应用。CLI
+负责初始化 Base 与应用、生成项目、校验和构建 Functions，以及发布 Preview
+和正式版本。
+
+## 安装 Agent Skill
+
+首次安装到 Codex：
+
+```bash
+npx --yes @lark-base-open/base-database-cli@latest skill install --target codex
+```
+
+升级已安装的 Skill：
+
+```bash
+npx --yes @lark-base-open/base-database-cli@latest skill install --target codex --force
+```
+
+安装后，在 Codex 中描述要搭建的业务系统；Agent 会读取 Skill，并通过 CLI
+完成数据模型、页面和 Functions 的开发与发布。
+
+## 创建、恢复并发布数据库应用
+
+### 新建数据库应用
+
+新建工程时，`init` 支持两种 Base 来源。需要从零建数据模型时，Agent 根据 Skill 写出完整 `base-schema.json`，再用一条命令创建 Base、全部 table、应用与 binding，并生成 hello-world 工程和 Catalog：
+
+```bash
+npx @lark-base-open/base-database-cli init ./todo-database \
+  --schema ./base-schema.json \
+  --name 'Todo 管理' \
+  --env online
+```
+
+已有 Base 时，不创建或修改 Base。CLI 会读取其中的全部 table，直接创建绑定该 Base 的新应用，获取 Catalog，并生成同样的工程：
+
+```bash
+npx @lark-base-open/base-database-cli init ./todo-database \
+  --base-token basxxxxxxxx \
+  --name 'Todo 管理' \
+  --env online
+```
+
+`--schema` 与 `--base-token` 必须且只能选择一个。宿主已经创建目标应用时，额外传入 `--app-token`；CLI 会把选中的 Base 绑定到该应用，而不会再调用应用创建接口：
+
+```bash
+npx @lark-base-open/base-database-cli init ./todo-database \
+  --schema ./base-schema.json \
+  --app-token PrjExistingToken \
+  --name 'Todo 管理' \
+  --description '供个人集中创建、跟踪和完成日常任务'
+```
+
+成功结果通过 `baseSource`、`databaseSource` 分别列出 Base 与应用来源，通过 `baseToken`、`appToken` 返回对应 token；新建或复用的应用信息位于 `created.database` 或 `reused.database`。结果同时列出数据表、binding、生成的工程目录、配置文件和 `catalog.json`，并在 `nextSteps` 中给出开发目录与 Preview 发布命令。
+
+生成项目的 `page/`、`server-functions/`、`sql/` 直接位于项目根目录；`base-database.jsonc` 和 `catalog.json` 也保留在根目录。`server-functions/` 是服务端 FaaS Functions 的源码与构建工作区。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 `.base-database-cli/state/`。
+
+### 恢复并修改已有数据库应用
+
+已有数据库应用存在源码制品时，使用 `pull` 恢复可编辑工程，不要重新执行 `init`。目标目录必须为空；CLI 会下载当前 `page/`、`server-functions/` 和 `sql/` 源码，读取应用 Catalog，并重建 `base-database.jsonc` 与 `catalog.json`，不会创建或修改 Base、应用元信息和 binding：
+
+```bash
+npx @lark-base-open/base-database-cli pull ./todo-database \
+  --app-token PrjExistingToken \
+  --env online
+```
+
+恢复完成后，先读取现有配置、Catalog 和源码，只修改本次需求涉及的内容，再使用 `deploy` 发布新的 Preview。
+
+### 发布 Preview 和正式版本
+
+新建流程是 `init → deploy`；修改已有数据库应用时是 `pull → 修改 → deploy`。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、SQL 和 FaaS 后发布 Preview：
+
+```bash
+cd todo-database
+npx @lark-base-open/base-database-cli deploy
+```
+
+部署结果只返回当前环境用户可访问的顶层 `baseAppUrl`。Agent 把链接交给用户后停止；用户体验并明确回复“部署正式版”后，把同一制品发布到 Prod：
+
+```bash
+npx @lark-base-open/base-database-cli deploy --production --yes
+```
+
+Preview 回执会记录生成该制品时的工作区输入指纹。Preview 之后只要源码、配置或
+文件结构发生变化，Production 发布就会在任何远端请求前停止，并要求重新运行
+普通 `deploy` 生成和验证新的 Preview；旧版回执缺少输入指纹时同样不会放行。
+
+### 部署后的应用能力 Skill
+
+每次部署成功后，CLI 自动将该应用的专属 Skill 安装或更新到当前用户的 `$CODEX_HOME/skills`，未配置时使用 `~/.codex/skills`。部署结果的 `agentGuide.skill` 包含安装状态、名称和路径；后续可直接让 Agent 查询或操作这个应用的数据，或输入 `$<skill.name>`。客户端若未刷新技能列表，开启新会话即可。
+
+Skill 按需读取正式版的 Function 和参数 Schema，不依赖应用工程目录。Preview 发布也会更新 Skill，但不会把 Preview 当成正式版。安装不授予额外权限，也不会自动执行业务动作。
+
+需要单独修复安装或指定其他 Agent 的用户技能目录时：
+
+```bash
+npx @lark-base-open/base-database-cli database-skill install --app-token <app-token> --title '<应用名称>' --dir <skills-root>
+```
+
+只更新本工具管理的该应用 `SKILL.md`，不删除其他文件；安装失败会单独返回，不影响已经成功的应用发布。
+
+能力 Skill 使用 `base-database-<hash>` 名称，通过 `database-skill` 命令安装和使用。
+同一应用和环境使用固定目录，每次部署更新本工具管理的 `SKILL.md`，保留附加文件。
+目标目录不受本工具管理或存在符号链接冲突时报告错误，不自动覆盖。
+
+## 环境
+
+CLI 只支持 `online`，`--env` 默认且仅接受 `online`。保留该参数是为了兼容现有自动化命令；传入其他值会直接失败。所有 lark-cli、OpenAPI、Accounts、应用管理后台和 Page 运行时请求都直接使用线上域名，不启动代理、不改写域名，也不向项目配置写入环境路由。
+
+需要登录或诊断时：
+
+```bash
+npx @lark-base-open/base-database-cli auth login --env online
+npx @lark-base-open/base-database-cli doctor --env online
+```
+
+`auth login` 使用默认 lark-cli 配置；首次使用时自动启动 `config init --new`，配置完成后继续申请 Base 用户权限。
+
+Base Database CLI 会按 `PATH` 顺序探测全部 `lark-cli`，读取各自的 `--version`，并跳过版本号中带构建 hash 的定制版本，默认使用第一个不带构建 hash 的 release 版本。如果没有可用的 release 版本，命令会明确失败而不会回退到定制版本。需要显式覆盖自动选择时，可将 `BASE_DATABASE_LARK_CLI_PATH` 设置为目标可执行文件的绝对路径；显式设置不会应用版本过滤。
+
+## 项目配置
+
+线上项目的最小配置：
+
+```jsonc
+{
+  "configVersion": 1,
+  "name": "todo-database",
+  "appToken": "Prjxxxxxxxx",
+  "bindings": {
+    "MAIN_BASE": {
+      "type": "base",
+      "baseToken": "basxxxxxxxx",
+      "tableIds": ["tbl_tasks"],
+    },
+  },
+}
+```
+
+`deploy` 会在发布前应用合法的 Base binding。目前只支持一个 Base；多个不同 `baseToken` 会停止发布并提示删除多余 binding。无法解析或暂不支持类型的单个 binding 会输出警告并建议修正 `base-database.jsonc`。
+
+## CLI 命令
+
+```text
+npx @lark-base-open/base-database-cli skill install
+npx @lark-base-open/base-database-cli auth login|logout|whoami
+npx @lark-base-open/base-database-cli doctor
+npx @lark-base-open/base-database-cli init
+npx @lark-base-open/base-database-cli pull
+npx @lark-base-open/base-database-cli deploy
+npx @lark-base-open/base-database-cli deployments status
+npx @lark-base-open/base-database-cli lark-cli -- <arguments...>
+```
+
+`deploy` 在一次调用内先生成 Function metadata 并完成全部 SQL validate，通过后再检查依赖指纹、执行必要的依赖安装、Page/FaaS build、archive、Functions sync、Artifact upload、Preview publish 和状态轮询。CLI 会汇总全部未通过的 SQL Function 后一次性报错；存在任一 SQL 校验失败时不会安装依赖或执行 build。依赖指纹未变化且对应 `node_modules` 仍存在时，默认跳过该子项目的 `npm ci`；`--force-install` 强制重装，`--no-install` 无条件跳过安装。build 仍会在每次 Preview deploy 中执行。正常应用开发不单独运行这些步骤；FaaS 子项目仍保留 `npm run build`，因为平台镜像打包器直接调用它。
+
+初始化结果保留所绑定多维表格的 `baseUrl`。发布完成后，CLI 只读取成功态 `publish_status` 返回的 `result.baseAppUrl`，不再使用 `catalog.json` 或 OpenAPI GetProject 兜底；成功态缺少该字段时会明确报错。Preview 发布返回的顶层 `baseAppUrl` 会保留原有查询参数并设置 `mode=edit`，Production 发布返回的顶层 `baseAppUrl` 会移除 `mode`。命令结果不再包含应用管理后台 URL、旧 Preview URL、`preview`/`production` URL 对象或静态资源 `appUrl`/`staticUrl`；静态资源地址只保存在内部 Preview 回执。
+
+`lark-cli` 子命令仅用于调试。先进入包含 `base-database.jsonc` 的项目根目录；命令只读取当前目录，不接受额外项目路径，并在线上环境直接透传参数。正常初始化和发布无需调用：
+
+```bash
+npx @lark-base-open/base-database-cli lark-cli -- \
+  api GET /open-apis/base/v3/sites/list \
+  --params '{"pageSize":1}' --json
+```

package/changelog/CHANGELOG-0.x.md

@@ -0,0 +1,103 @@
+# Changelog — 0.x
+
+## [0.3.8] - 2026-09-04
+
+### Added
+
+- 新增 `install` 与 `update` 命令，可持久安装稳定版 CLI 和同版本 Building Skill，并检查、升级或暂缓 npm 新版本。
+
+### Changed
+
+- 建站和修改任务改用持久的 `base-site` 命令；每个任务首次执行 CLI 前检查更新，结果缓存 24 小时，发现新版时先征求用户确认。
+
+## [0.3.7] - 2026-09-03
+
+### Fixed
+
+- 修正多份 `lark-cli` 共存时的入口选择：自动跳过版本号含构建 hash 的定制版本，选择 `PATH` 中首个可识别的 release 版本；也可通过 `BASE_SITE_LARK_CLI_PATH` 指定绝对路径。
+
+## [0.3.6] - 2026-09-03
+
+### Removed
+
+- 移除建站和修改任务开始前的公开 CLI 自动版本检查与升级询问，安装 Skill 后直接进入任务流程。
+
+### Fixed
+
+- 修正 Base SQL 条件聚合指导，使用浮点数分支生成 `SUM` / `AVG`，避免整数分支导致聚合类型校验失败。
+
+## [0.3.5] - 2026-09-02
+
+### Added
+
+- 本地建站和修改任务会在开始前检查公开 CLI 版本；发现新版时先征求升级同意，并在 24 小时内复用处理结果，避免重复查询和询问。
+
+### Fixed
+
+- 修正 Base SQL 聚合、子查询和窗口函数指导，避免生成聚合派生表 JOIN、表达式标量子查询及当前不支持的窗口函数。
+- 修正 Base SQL 表达式和字段筛选指导，避免生成 `COALESCE`、`SPLIT`、文本日期范围比较及空选项比较等当前不支持的写法。
+
+## [0.3.4] - 2026-08-27
+
+### Security
+
+- Page 的记录创建、更新和删除统一通过 FaaS 执行；starter 不再提供直接记录写入 helper，避免 Page 运行时直接传递 Base token。
+
+## [0.3.3] - 2026-08-27
+
+### Added
+
+- Page 可批量创建、更新和删除已绑定 Base 记录，普通记录写入无需额外创建 FaaS Function。
+- 建站时会明确站点准入、数据可见范围和操作权限。
+
+### Changed
+
+- 修改已有 Site 时，新增 Table 可通过增量追加 binding 并刷新 Catalog，无需重新执行 `init` 或 `pull`。
+- 从零建站在交付 Preview 前写入真实示例数据，并通过页面 SQL Function 回读验证。
+
+## [0.3.2] - 2026-08-26
+
+### Changed
+
+- 新生成站点把当前用户、所属组织和退出登录入口移入站点自身导航；右下角悬浮控件只保留编辑站点与 Chatbot 入口。
+
+## [0.3.1] - 2026-08-26
+
+### Fixed
+
+- 修正 Base SQL 条件分支指导，明确使用 searched CASE（`CASE WHEN ... THEN ... END`），避免生成不受支持的 Simple CASE。
+
+## [0.3.0] - 2026-08-25
+
+### Added
+
+- 新增 `pull` 命令，可从已有 Site 的源码制品恢复 Page、FaaS、SQL、项目配置和 Catalog，并在不重建 Base、Site 或 binding 的前提下继续增量开发。
+- `init` 新增 `--site-token`，可将新建或已有 Base 绑定到宿主预先创建的 Site，避免托管建站流程额外创建 Site。
+- 新生成的 Site 工程提供站内对话面板、当前用户与组织操作，以及面向 Site 成员的用户选择能力。
+
+### Changed
+
+- **Breaking:** 调整 CLI 发布结果和 Site 访问入口契约，统一使用顶层 `baseAppUrl`。
+- **Breaking:** 调整 Preview 到 Production 的发布契约；工作区发生变化或使用旧版 Preview 回执时，需要重新发布 Preview。
+- 更新 Site starter 的站内交互体验，并使 Skill 与当前 Base 写入、Base SQL 和 Site Runtime 能力保持一致。
+
+## [0.2.7] - 2026-08-06
+
+### Changed
+
+- 原生 workflow 通知按明确的入口策略配置：与 Site 业务对象关联的通知默认进入对应站内对象，纯展示或进入多维表格仅在用户明确要求时使用。
+
+### Fixed
+
+- 新建 Site 通知 workflow 会在 Preview 发布成功后使用最终 Site 链接直接创建；入口配置或回读失败时立即禁用，避免错误通知继续生效。
+
+## [0.2.6] - 2026-08-04
+
+### Added
+
+- 初始化 Site 工程时生成页面标题，并在发布前校验标题配置。
+
+### Changed
+
+- 明确 Base SQL Function 的支持边界和不支持能力。
+- 原生 workflow 的 Site 通知入口会随 Preview 和正式发布地址切换。

package/config-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Base Database CLI configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["configVersion", "appToken"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "configVersion": {
+      "const": 1
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "runtimeProfile": {
+      "type": "string",
+      "minLength": 1
+    },
+    "appToken": {
+      "type": "string",
+      "minLength": 1
+    },
+    "bindings": {}
+  }
+}

package/dist/agent-guide.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeProfile } from './environment.js';
+export declare function deploymentAgentGuide(appToken: string, target: 'preview' | 'prod', options: {
+    workspace: string;
+    profile: RuntimeProfile;
+}): {
+    target: 'prod';
+    availability: string;
+    skill: {
+        status: "installed" | "updated";
+        name: string;
+        path: string;
+    } | {
+        status: 'failed';
+        error: string;
+    };
+    message: string;
+};
+//# sourceMappingURL=agent-guide.d.ts.map

package/dist/agent-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../src/agent-guide.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,GAAG,MAAM,EAC1B,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE;YAgB7C,MAAM;;;;;;;gBALJ,QAAQ;;;;EAgBrB"}

package/dist/agent-guide.js

@@ -0,0 +1,30 @@
+import { validatePageTitle } from './page-title.js';
+import { installDatabaseSkill } from './database-skill.js';
+// Runs only after successful publication; never discovers or invokes Functions.
+export function deploymentAgentGuide(appToken, target, options) {
+    let skill;
+    try {
+        skill = installDatabaseSkill({
+            appToken,
+            title: validatePageTitle(options.workspace),
+            profile: options.profile,
+        });
+    }
+    catch (error) {
+        skill = {
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        target: 'prod',
+        availability: target === 'prod'
+            ? '正式版发布成功；实际发现结果以服务端接口及开关状态为准，尚未自动验证。'
+            : '本次仅发布预览版；Skill 只读取正式版，不代表本次预览可被发现。不执行发现或调用，先等待用户确认。',
+        skill,
+        message: skill.status === 'failed'
+            ? '应用发布成功，但专属 Skill 安装失败；向用户报告原因，不要重新发布应用来修复安装。'
+            : `已${skill.status === 'installed' ? '安装' : '更新'}本应用 Skill。请告知用户可直接让 Agent 使用本应用能力，或使用 $${skill.name}；当前客户端若未自动刷新 Skill 列表，请开启新会话。安装不代表业务操作授权。`,
+    };
+}
+//# sourceMappingURL=agent-guide.js.map

package/dist/agent-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../src/agent-guide.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,MAA0B,EAC1B,OAAuD;IAEvD,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QACH,KAAK,GAAG,oBAAoB,CAAC;YAC3B,QAAQ;YACR,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC;YAC3C,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,GAAG;YACN,MAAM,EAAE,QAAiB;YACzB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAe;QACvB,YAAY,EACV,MAAM,KAAK,MAAM;YACf,CAAC,CAAC,qCAAqC;YACvC,CAAC,CAAC,qDAAqD;QAC3D,KAAK;QACL,OAAO,EACL,KAAK,CAAC,MAAM,KAAK,QAAQ;YACvB,CAAC,CAAC,8CAA8C;YAChD,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,0CAA0C,KAAK,CAAC,IAAI,2CAA2C;KACpJ,CAAC;AACJ,CAAC"}

package/dist/archive.d.ts

@@ -0,0 +1,16 @@
+export interface SQLValidationArtifact {
+    functionId: string;
+    path: string;
+}
+export interface DatabaseMetadataArtifacts {
+    metaList: string;
+    sqlValidation: SQLValidationArtifact[];
+}
+export declare function prepareDatabaseMetadata(workspace: string): DatabaseMetadataArtifacts;
+export declare function archiveDatabase(workspace: string, metadata?: DatabaseMetadataArtifacts): Promise<{
+    archive: string;
+    metaList: string;
+    sqlValidation: SQLValidationArtifact[];
+    displayArchive: string;
+}>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAmKD,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB,yBAAyB,CAK3B;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,yBAA8D;;;;;GAazE"}

package/dist/archive.js

@@ -0,0 +1,162 @@
+import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { ZipArchive } from 'archiver';
+import { deriveSQLInputSchema, normalizeFunctionInputSchema, } from './function-schema.js';
+const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const MAX_FUNCTIONS = 200;
+function findMetaFiles(directory) {
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        if (!entry.isDirectory())
+            return [];
+        const path = join(directory, entry.name, 'meta.json');
+        return existsSync(path) && statSync(path).isFile() ? [path] : [];
+    });
+}
+function readMetaItem(type, path) {
+    const manifest = JSON.parse(readFileSync(path, 'utf8'));
+    const functionId = basename(dirname(path));
+    if (functionId.length > 64 ||
+        functionId.length < 1 ||
+        !FUNCTION_ID_PATTERN.test(functionId)) {
+        throw new Error(`Invalid Function ID: ${functionId}`);
+    }
+    if (typeof manifest.name !== 'string' || manifest.name === '') {
+        throw new Error(`Function name must be a non-empty string: ${path}`);
+    }
+    if (manifest.description !== undefined &&
+        typeof manifest.description !== 'string') {
+        throw new Error(`Function description must be a string: ${path}`);
+    }
+    const item = {
+        functionId,
+        functionType: type === 'sql' ? 1 : 2,
+        name: manifest.name,
+        description: manifest.description ?? '',
+        sourceCode: '',
+    };
+    if (type === 'sql') {
+        if (manifest.inputSchema !== undefined) {
+            throw new Error(`SQL inputSchema is derived from meta.params and must not be set: ${path}`);
+        }
+        let meta = manifest.meta;
+        if (meta === undefined) {
+            meta = { params: [] };
+        }
+        else if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {
+            throw new Error(`SQL meta must be an object: ${path}`);
+        }
+        else if (!Object.hasOwn(meta, 'params')) {
+            meta = { ...meta, params: [] };
+        }
+        else if (!Array.isArray(meta.params)) {
+            throw new Error(`SQL meta.params must be an array: ${path}`);
+        }
+        const sql = readFileSync(join(dirname(path), 'main.sql'), 'utf8');
+        item.sourceCode = JSON.stringify({
+            sql,
+            meta,
+            inputSchema: JSON.parse(deriveSQLInputSchema(meta, sql)),
+        });
+    }
+    else {
+        if (manifest.inputSchema === undefined) {
+            throw new Error(`FaaS inputSchema is required: ${path}`);
+        }
+        item.sourceCode = JSON.stringify({
+            inputSchema: JSON.parse(normalizeFunctionInputSchema(manifest.inputSchema, path)),
+        });
+    }
+    return item;
+}
+function writeMetadata(workspace, output) {
+    const files = [
+        ...findMetaFiles(join(workspace, 'server-functions/functions')).map((path) => ({
+            type: 'faas',
+            path,
+        })),
+        ...findMetaFiles(join(workspace, 'sql')).map((path) => ({
+            type: 'sql',
+            path,
+        })),
+    ];
+    if (files.length > MAX_FUNCTIONS) {
+        throw new Error(`Functions cannot exceed ${MAX_FUNCTIONS}`);
+    }
+    const ids = new Set();
+    const items = files.map(({ type, path }) => {
+        const item = readMetaItem(type, path);
+        if (ids.has(item.functionId)) {
+            throw new Error(`Duplicate Function ID: ${item.functionId}`);
+        }
+        ids.add(item.functionId);
+        return item;
+    });
+    const validations = join(output, 'sql-validation');
+    mkdirSync(output, { recursive: true });
+    rmSync(validations, { recursive: true, force: true });
+    mkdirSync(validations, { recursive: true });
+    const metaList = join(output, 'meta-list.json');
+    writeFileSync(metaList, `${JSON.stringify({ functions: items }, null, 2)}\n`);
+    const sqlValidation = items.flatMap((item) => {
+        if (item.functionType !== 1)
+            return [];
+        const path = join(validations, `${item.functionId}.json`);
+        writeFileSync(path, `${JSON.stringify({ sourceCode: item.sourceCode }, null, 2)}\n`);
+        return [{ functionId: item.functionId, path }];
+    });
+    return { metaList, sqlValidation };
+}
+function createArchive(workspace, destination) {
+    return new Promise((resolvePromise, reject) => {
+        const output = createWriteStream(destination);
+        const zip = new ZipArchive({ zlib: { level: 9 } });
+        output.once('finish', resolvePromise);
+        output.once('error', reject);
+        zip.once('warning', reject);
+        zip.once('error', reject);
+        zip.pipe(output);
+        zip.glob('{page,server-functions,sql}/**/*', {
+            cwd: workspace,
+            dot: true,
+            ignore: [
+                '**/node_modules/**',
+                '**/dist/**',
+                '**/.DS_Store',
+                '**/.env',
+                '**/.env.*',
+            ],
+        });
+        void zip.finalize();
+    });
+}
+function databaseProject(workspace) {
+    const project = resolve(workspace);
+    for (const directory of ['page', 'server-functions', 'sql']) {
+        if (!existsSync(join(project, directory))) {
+            throw new Error(`application source not found: ${join(project, directory)}`);
+        }
+    }
+    return project;
+}
+export function prepareDatabaseMetadata(workspace) {
+    const project = databaseProject(workspace);
+    const artifacts = join(project, '.base-database-cli/state/artifacts');
+    mkdirSync(artifacts, { recursive: true });
+    return writeMetadata(project, artifacts);
+}
+export async function archiveDatabase(workspace, metadata = prepareDatabaseMetadata(workspace)) {
+    const project = databaseProject(workspace);
+    const artifacts = join(project, '.base-database-cli/state/artifacts');
+    mkdirSync(artifacts, { recursive: true });
+    const archive = join(artifacts, 'site.zip');
+    await createArchive(project, archive);
+    return {
+        archive,
+        metaList: metadata.metaList,
+        sqlValidation: metadata.sqlValidation,
+        displayArchive: relative(project, archive),
+    };
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

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

package/dist/assets.d.ts

@@ -0,0 +1,4 @@
+export declare const packageRoot: string;
+export declare const skillRoot: string;
+export declare const starterRoot: string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,QAGvB,CAAC;AACF,eAAO,MAAM,SAAS,QAAiD,CAAC;AACxE,eAAO,MAAM,WAAW,QAAkD,CAAC"}

package/dist/assets.js

@@ -0,0 +1,6 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const skillRoot = join(packageRoot, 'skills/lark-base-database');
+export const starterRoot = join(packageRoot, 'templates/database-starter');
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAChC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,IAAI,CACL,CAAC;AACF,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,2BAA2B,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC"}

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+import { type RuntimeProfile } from './environment.js';
+import { runCommand } from './process.js';
+export declare function ensureConfiguration(env: NodeJS.ProcessEnv, runner?: typeof runCommand): void;
+export declare function login(profile?: RuntimeProfile): Promise<void>;
+export declare function logout(profile?: RuntimeProfile): Promise<void>;
+export declare function whoami(profile?: RuntimeProfile): Promise<import("./types.js").CommandResult>;
+export declare function doctor(profile?: RuntimeProfile): Promise<{
+    ok: true;
+    environment: string;
+    node: string;
+    user: {
+        status: unknown;
+        available: unknown;
+        verified: unknown;
+    };
+}>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,MAAM,oBAAa,GAClB,IAAI,CAWN;AAED,wBAAsB,KAAK,CACzB,OAAO,GAAE,cAAuC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,MAAM,CAC1B,OAAO,GAAE,cAAuC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,MAAM,CAAC,OAAO,GAAE,cAAuC,+CAG5E;AAED,wBAAsB,MAAM,CAAC,OAAO,GAAE,cAAuC;;;;;QA4BvE,MAAM;QACN,SAAS;QACT,QAAQ;;GAGb"}