@finebi/finebi-cli 1.6.3 → 2.0.1

package/skills/finebi-cli-agent/references/dashboard-dsl-api.md

@@ -1,44 +1,44 @@
-# Dashboard DSL API
-
-这份文档只列当前文本 DSL 可以直接使用的 Dashboard API，以及各 API 的业务含义。本语句面同时是
-`dashboard dsl --id <dashboardId>` 回读命令的输出面（响应内嵌数据组件 DSL 回显，见 docs/commands/）。
-
-**回读 warnings 里出现条目级 `*_DROPPED` 留痕（`UNSUPPORTED_WIDGET_DROPPED` /
-`UNREACHABLE_WIDGET_DROPPED` / 整条目跳过的 `UNREACHABLE_IMAGE` / `UNREACHABLE_WEB` /
-`AI_SUBJECT_DROPPED` / `COMBINE_DISSOLVED` 等）时不要整板 `dashboard update`**：这些条目
-不在回读 DSL 里，整板重写会使其从板上消失，写侧防丢守卫会以 `ENTRY_LOSS_BLOCKED`
-拒绝保存。先完成与该条目无关的操作；需要处理时询问用户在 FineBI 设计器中处置
-（删除或修复该条目），不要试图绕过。
-
-**改板前先 `dashboard info --id <dashboardId>`**：板级构成摘要（条目清单 + 悬浮层 +
-板级留痕）与本文语句面的条目一一对应，先清点再按需 `dashboard dsl` 取局部 DSL，
-不必为定位条目拉全量回读；`warnings` 出现条目级 `*_DROPPED` 留痕时按上一段处置。
-只看一个条目时用单条目切片 `dashboard dsl --id <dashboardId> --entry <名>`（重名板
-改用 `--entry-id <entries[].entryId>` 消歧）：`dsl` 只含该条目语句 + 可选 `position`
-（容器成员 position 是容器局部格位），`warnings`/`widgets` 同步过滤到目标条目。
-**只改一个条目时用单条目写**：`dashboard update-entry --id <dashboardId> --file
-<fragment.js>`（fragment 与切片同文法，是条目的完整新定义——读全条 → 改 → 写回；
-重名板带 `--entry-id` 消歧）。未点名条目原样保留，不会丢；widget 引用条目只改板侧面
-（position/title），组件本体走 `widget update`。新增 / 删除条目用 `add-entry` /
-`remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
-的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
-`position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
-并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
-读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
-`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
-`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
-
-**写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
-`dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
-（场景：`basic` 经营看板 / `kpi` KPI 概览 / `filter` 筛选控件 / `style` 样式面 /
-`screen` 大屏驾驶舱 / `rich-text` 富文本与动态字段 / `linkage-jump` 联动与跳转 /
-`tree-time` 层级与时间筛选 / `blocks` 容器区块）。
-动态合法值（样式预设 id 与全局样式名）
-用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。API 面拆分为下表文件，
-按需读取当前操作涉及的文件，不一次加载全部；章节编号沿用拆分前原编号。
-
-| 文件 | 章节 | 何时读取 |
-| --- | --- | --- |
-| [dashboard-dsl-core.md](dashboard-dsl-core.md) | §1-§5 根入口、顶层 Builder、内容域（条目挂载、联动与跳转）、布局与样式域、移动端域；§7 字段写法 | 写任何仪表板前必读 |
-| [dashboard-dsl-items.md](dashboard-dsl-items.md) | §6 可构造值对象（6.1-6.14：控件、文本、图片、联动/跳转模型、自适应、移动端配置、富文本、Web、组合、Tab、冻结栏、复合过滤、AI 诊断） | 挂载或配置具体条目类型时 |
-| [dashboard-dsl-examples.md](dashboard-dsl-examples.md) | §8 推荐写法示例、§9 场景模板与设计要点 | 需要可抄写法或场景模板时 |
+# Dashboard DSL API
+
+这份文档只列当前文本 DSL 可以直接使用的 Dashboard API，以及各 API 的业务含义。本语句面同时是
+`dashboard dsl --id <dashboardId>` 回读命令的输出面（响应内嵌数据组件 DSL 回显，见 docs/commands/）。
+
+**回读 warnings 里出现条目级 `*_DROPPED` 留痕（`UNSUPPORTED_WIDGET_DROPPED` /
+`UNREACHABLE_WIDGET_DROPPED` / 整条目跳过的 `UNREACHABLE_IMAGE` / `UNREACHABLE_WEB` /
+`AI_SUBJECT_DROPPED` / `COMBINE_DISSOLVED` 等）时不要整板 `dashboard update`**：这些条目
+不在回读 DSL 里，整板重写会使其从板上消失，写侧防丢守卫会以 `ENTRY_LOSS_BLOCKED`
+拒绝保存。先完成与该条目无关的操作；需要处理时询问用户在 FineBI 设计器中处置
+（删除或修复该条目），不要试图绕过。
+
+**改板前先 `dashboard info --id <dashboardId>`**：板级构成摘要（条目清单 + 悬浮层 +
+板级留痕）与本文语句面的条目一一对应，先清点再按需 `dashboard dsl` 取局部 DSL，
+不必为定位条目拉全量回读；`warnings` 出现条目级 `*_DROPPED` 留痕时按上一段处置。
+只看一个条目时用单条目切片 `dashboard dsl --id <dashboardId> --entry <名>`（重名板
+改用 `--entry-id <entries[].entryId>` 消歧）：`dsl` 只含该条目语句 + 可选 `position`
+（容器成员 position 是容器局部格位），`warnings`/`widgets` 同步过滤到目标条目。
+**只改一个条目时用单条目写**：`dashboard update-entry --id <dashboardId> --file
+<fragment.js>`（fragment 与切片同文法，是条目的完整新定义——读全条 → 改 → 写回；
+重名板带 `--entry-id` 消歧）。未点名条目原样保留，不会丢；widget 引用条目只改板侧面
+（position/title），组件本体走 `widget update`。新增 / 删除条目用 `add-entry` /
+`remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
+的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
+`position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
+并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
+读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
+`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
+`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
+
+**写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
+`dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
+（场景：`basic` 经营看板 / `kpi` KPI 概览 / `filter` 筛选控件 / `style` 样式面 /
+`screen` 大屏驾驶舱 / `rich-text` 富文本与动态字段 / `linkage-jump` 联动与跳转 /
+`tree-time` 层级与时间筛选 / `blocks` 容器区块）。
+动态合法值（样式预设 id 与全局样式名）
+用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。API 面拆分为下表文件，
+按需读取当前操作涉及的文件，不一次加载全部；章节编号沿用拆分前原编号。
+
+| 文件 | 章节 | 何时读取 |
+| --- | --- | --- |
+| [dashboard-dsl-core.md](dashboard-dsl-core.md) | §1-§5 根入口、顶层 Builder、内容域（条目挂载、联动与跳转）、布局与样式域、移动端域；§7 字段写法 | 写任何仪表板前必读 |
+| [dashboard-dsl-items.md](dashboard-dsl-items.md) | §6 可构造值对象（6.1-6.14：控件、文本、图片、联动/跳转模型、自适应、移动端配置、富文本、Web、组合、Tab、冻结栏、复合过滤、AI 诊断） | 挂载或配置具体条目类型时 |
+| [dashboard-dsl-examples.md](dashboard-dsl-examples.md) | §8 推荐写法示例、§9 场景模板与设计要点 | 需要可抄写法或场景模板时 |

package/skills/finebi-cli-agent/references/web-app.md

@@ -4,10 +4,13 @@
 
 1. `finebi-cli app create --name <name> --path <parent> [--layout retail]` 创建工程，不安装/运行/发布。米白横向经营简报可选 retail，绿色驾驶舱可选 cockpit；默认 overview，另有 workbench。
 2. 用dashboard search/info/data确认唯一来源、板内entryId、结果字段dId、真实控件filterName；按生成项目 docs/acceptance.md 记录指标口径、单位/时区、筛选范围和数据完整性。样本仅用于理解和测试。
-3. 按生成项目 AGENTS.md 的“阅读路径”分阶段读取文档，不要求开场通读全部说明。先按 docs/acceptance.md 的“最小真实查询”只配置一个真实组件，按 README 安装依赖、配置开发身份并启动实际页面，验证开发代理查询与页面值。CLI 成功不能替代这一步；优先复用已有会话，不重复索要可用身份的密码。
+3. 按生成项目 AGENTS.md 的“阅读路径”分阶段读取文档，不要求开场通读全部说明。先检查开发身份：优先复用目标环境的有效会话或已有登录配置；只有 CLI Access Key 不算开发身份。缺少可用身份且需要用户补充凭据或完成授权时，立即说明阻断点并请求最小补充，按项目 docs/auth-and-deploy.md 配置；不要等整页做完才询问，也不重复索要可用身份的密码。
+   身份具备后，按 docs/acceptance.md 的“最小真实查询”只配置一个真实组件，按 README 安装依赖并启动实际页面。留下目标环境、组件请求参数、真实业务响应和页面值的脱敏证据，核对一致后才进入下一阶段；CLI 成功、HTTP 200 或合成测试通过均不能替代这一步。
 4. 最小真实查询及适用的代表性图表、筛选链路通过后，再扩展整页绑定。按 docs/design.md 对应章节确定首屏、导航、图表分组和风格差异；请求、认证、解析复用模板src/finebi，图表库和UI组件库按页面需求选择。需要查看绑定摘要时可运行 `finebi-cli app inspect --path <project>`，默认不校验模板字段或展示格式，也不证明应用可用。只有需要检查与 CLI 内置模板的兼容性时才显式使用 `--strict`；定制应用无需通过该检查，不要为消除 strict 报错而删除自定义能力或反复修改应用。验收以项目自身测试、构建和真实浏览器验证为准。
 5. 按生成项目 docs/acceptance.md 分别完成自动测试、构建、test:browser 合成数据验收和真实页面验收，检查整页及窄屏，记录 CLI、开发身份、生产 Cookie 各自的已验证与未验证项。生产部署必须用访问者Cookie，不携带开发身份。
 
+阶段阻断时只继续不依赖真实数据的设计或测试，暂停扩展整页绑定。不得自行将开发代理切到 mock、历史响应回放或静态数据来交付或启动预览；注明“回放”或“真实查询未验证”也不等于完成动态应用。用户明确要求离线演示时才单独提供，并说明其不通过真实查询阶段；恢复动态应用开发仍须先完成上述验证。
+
 内置CLI同样通过 `node "<skill-dir>/scripts/finebi-cli/src/index.js" app ...` 调用，不走动态业务runner。生产页面不调用CLI。禁止将开发时查到的业务数据或token写入HTML/JS/config；无筛选控件不能伪造服务端过滤。pageLimit不是分页，hasNext和warnings必须呈现。不提供发布上传或服务端续页。目录来源显式配置 directoryEntryId，由原生 reportEntryId 透传；目标平台需支持 HTTP 目录权限预检与 MOUNT 查询，不能失败后回退“我的分析”。
 
 cockpit 的 examples/cockpit.config.json 仅包含占位绑定，必须替换成真实资源和结果 fieldId；多模型显式 datasetId。布局含可配置 KPI、多系列趋势、分类对比、通栏表格及可选观察/口径。年月为自定义十二月/年份网格面板，选中只改 YYYY-MM 草稿。表格搜索、精确排序、筛选、分页、CSV 只处理已加载结果；观察不内置销售公式。widgets[].filterNames 来自真实映射，[] 表示不传覆盖，省略由源看板决定，不宣称未知映射为全局联动。请求/认证仍复用 src/finebi，不能复制个人 CLI 子进程后端。

package/skills/finebi-cli-agent/scripts/finebi-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.6.3",
+  "version": "2.0.1",
   "private": true,
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",

package/skills/finebi-cli-agent/scripts/finebi-cli/src/app.js

@@ -1,160 +1,160 @@
-import {cp, mkdir, readdir, readFile, stat, writeFile} from "node:fs/promises";
-import {dirname, resolve} from "node:path";
-import {fileURLToPath} from "node:url";
-
-import {cliError} from "./errors.js";
-import {failure, success} from "./output.js";
-
-const TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates", "web-app");
-const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
-const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
-
-export async function handleApp(args, context = {}) {
-  const action = args[0];
-  if (action === "create") return createApp(args.slice(1), context);
-  if (action === "inspect") return inspectApp(args.slice(1));
-  return invalid("app", "App command is required.", ["finebi-cli app create --name <name> --path <parent>", "finebi-cli app inspect --path <project>"]);
-}
-
-export async function createApp(args, context = {}) {
-  const options = parseOptions(args, "app.create");
-  if (!options.ok) return options.error;
-  const {name, path: parentPath} = options.value;
-  if (!name || name.length > 214 || !NAME_PATTERN.test(name) || WINDOWS_DEVICE_NAME.test(name)) {
-    return invalid("app.create", "name must be a simple lowercase npm name (letters, digits, and single hyphens).", ["finebi-cli app create --name sales-dashboard --path <parent>"]);
-  }
-  if (!parentPath) {
-    return invalid("app.create", "path must be an existing parent directory.");
-  }
-  if (options.value.layout && !['overview','workbench','cockpit','retail'].includes(options.value.layout)) return invalid('app.create','layout must be overview, workbench, cockpit or retail.');
-  const parent = resolve(parentPath);
-  const destination = resolve(parent, name);
-  if (dirname(destination) !== parent) {
-    return invalid("app.create", "name must stay inside the selected parent directory.");
-  }
-  try {
-    if (!(await stat(parent)).isDirectory()) return invalid("app.create", "path must point to a directory.");
-  } catch (error) {
-    return invalid("app.create", error.code === "ENOENT" ? `Parent directory does not exist: ${parent}` : `Cannot inspect parent directory: ${error.message}`);
-  }
-  try {
-    const templateRoot = context.templateRoot ? resolve(context.templateRoot) : TEMPLATE_ROOT;
-    const templatePackage = JSON.parse(await readFile(resolve(templateRoot, "package.json"), "utf8"));
-    const gitignore = await readFile(resolve(templateRoot, "gitignore.template"), "utf8");
-    const templateConfigPath = resolve(templateRoot, "public", "app-config.json");
-    let config = {schemaVersion: "1", title: name, basePath: "/webroot/decision", layout: "overview", dashboardId: "", maxRows: 1000, pageSize: 8, widgets: [], filters: []};
-    try {
-      config = JSON.parse(await readFile(templateConfigPath, "utf8"));
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    try {
-      await mkdir(destination, {recursive: false});
-    } catch (error) {
-      return invalid("app.create", error.code === "EEXIST" ? `Destination already exists: ${destination}` : `Cannot create destination: ${error.message}`);
-    }
-    await copyTemplateContents(templateRoot, destination);
-    await writeFile(resolve(destination, ".gitignore"), gitignore, "utf8");
-    if(options.value.layout) config.layout=options.value.layout;
-    if(config.layout==='cockpit') config.insights=true;
-    await mkdir(resolve(destination, "public"), {recursive: true});
-    await writeFile(resolve(destination, "package.json"), `${JSON.stringify({...templatePackage, name}, null, 2)}\n`, "utf8");
-    await writeFile(resolve(destination, "public", "app-config.json"), `${JSON.stringify({...config, templateVersion: templatePackage.version}, null, 2)}\n`, "utf8");
-    const lockPath = resolve(destination, "package-lock.json");
-    try {
-      const lock = JSON.parse(await readFile(lockPath, "utf8"));
-      lock.name = name;
-      if (lock.packages?.[""]) lock.packages[""].name = name;
-      await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    return success("app.create", {name, path: destination, templateVersion: templatePackage.version});
-  } catch (error) {
-    return invalid("app.create", `Could not create project: ${error.message}`);
-  }
-}
-
-async function copyTemplateContents(sourceRoot, destinationRoot, relativeDirectory = "") {
-  const sourceDirectory = resolve(sourceRoot, relativeDirectory);
-  const destinationDirectory = resolve(destinationRoot, relativeDirectory);
-  for (const entry of (await readdir(sourceDirectory, {withFileTypes: true})).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
-    const relativePath = `${relativeDirectory}/${entry.name}`.replace(/^\//u, "");
-    if (relativePath === ".gitignore" || relativePath === "gitignore.template") continue;
-    if (!templatePathAllowed(relativePath)) continue;
-    const sourcePath = resolve(sourceDirectory, entry.name);
-    const destinationPath = resolve(destinationDirectory, entry.name);
-    if (entry.isDirectory()) {
-      await mkdir(destinationPath, {recursive: false});
-      await copyTemplateContents(sourceRoot, destinationRoot, relativePath);
-    } else if (entry.isFile()) {
-      await cp(sourcePath, destinationPath, {force: false, errorOnExist: true});
-    } else {
-      throw new Error(`Unsupported template entry: ${relativePath}`);
-    }
-  }
-}
-
-function templatePathAllowed(relative) {
-  const relativePath = relative.replaceAll("\\", "/");
-  const parts = relativePath.split("/").filter(Boolean);
-  const basename = parts.at(-1) || "";
-  return !parts.some(part => ["node_modules", "dist", "temp", ".git"].includes(part))
-    && basename !== ".env"
-    && (!basename.startsWith(".env.") || basename === ".env.example");
-}
-
-async function inspectApp(args) {
-  const options = parseOptions(args, "app.inspect");
-  if (!options.ok) return options.error;
-  const projectPath = options.value.path;
-  if (!projectPath) return invalid("app.inspect", "path must be a project directory.");
-  const project = resolve(projectPath);
-  try {
-    if (!(await stat(project)).isDirectory()) return invalid("app.inspect", "path must point to a project directory.");
-    const configPath = resolve(project, "public", "app-config.json");
-    const config = JSON.parse(await readFile(configPath, "utf8"));
-    if (!config || typeof config !== "object" || Array.isArray(config)) return invalid("app.inspect", "app-config.json must contain a JSON object.");
-    if (options.value.strict) {
-      const {configErrors}=await import('../templates/web-app/src/finebi/config.js');
-      const errors = configErrors(config);
-      if (errors.length) return failure("app.inspect", cliError("INVALID_ARGUMENT", {path: "public/app-config.json", message: errors.join(" ")}));
-    }
-    return success("app.inspect", {
-      path: project,
-      dashboardId: config.dashboardId ?? null,
-      layout: config.layout ?? null,
-      directoryEntryId: config.directoryEntryId || null,
-      widgets: Array.isArray(config.widgets) ? config.widgets.length : null,
-      templateVersion: config.templateVersion || null,
-      configValidated: options.value.strict === true,
-      remoteValidated: false,
-    });
-  } catch (error) {
-    return invalid("app.inspect", `Cannot read project configuration: ${error.message}`);
-  }
-}
-
-function parseOptions(args, command) {
-  const value = {};
-  for (let index = 0; index < args.length; index++) {
-    const option = args[index];
-    if (option === "--json") continue;
-    if (option === "--strict" && command === "app.inspect") {
-      if (value.strict) return {ok: false, error: invalid(command, "--strict must only be supplied once.")};
-      value.strict = true;
-      continue;
-    }
-    if (!["--name","--path",...(command==='app.create'?['--layout']:[])].includes(option)) return {ok: false, error: invalid(command, `Unsupported option: ${option}`)};
-    const key = option.slice(2);
-    const next = args[++index];
-    if (!next || next.startsWith("--")) return {ok: false, error: invalid(command, `${option} requires a value.`)};
-    if (value[key]) return {ok: false, error: invalid(command, `${option} must only be supplied once.`)};
-    value[key] = next;
-  }
-  return {ok: true, value};
-}
-
-function invalid(command, message, nextActions = []) {
-  return failure(command, cliError("INVALID_ARGUMENT", {path: command, message, nextActions}));
-}
+import {cp, mkdir, readdir, readFile, stat, writeFile} from "node:fs/promises";
+import {dirname, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+
+import {cliError} from "./errors.js";
+import {failure, success} from "./output.js";
+
+const TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates", "web-app");
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
+
+export async function handleApp(args, context = {}) {
+  const action = args[0];
+  if (action === "create") return createApp(args.slice(1), context);
+  if (action === "inspect") return inspectApp(args.slice(1));
+  return invalid("app", "App command is required.", ["finebi-cli app create --name <name> --path <parent>", "finebi-cli app inspect --path <project>"]);
+}
+
+export async function createApp(args, context = {}) {
+  const options = parseOptions(args, "app.create");
+  if (!options.ok) return options.error;
+  const {name, path: parentPath} = options.value;
+  if (!name || name.length > 214 || !NAME_PATTERN.test(name) || WINDOWS_DEVICE_NAME.test(name)) {
+    return invalid("app.create", "name must be a simple lowercase npm name (letters, digits, and single hyphens).", ["finebi-cli app create --name sales-dashboard --path <parent>"]);
+  }
+  if (!parentPath) {
+    return invalid("app.create", "path must be an existing parent directory.");
+  }
+  if (options.value.layout && !['overview','workbench','cockpit','retail'].includes(options.value.layout)) return invalid('app.create','layout must be overview, workbench, cockpit or retail.');
+  const parent = resolve(parentPath);
+  const destination = resolve(parent, name);
+  if (dirname(destination) !== parent) {
+    return invalid("app.create", "name must stay inside the selected parent directory.");
+  }
+  try {
+    if (!(await stat(parent)).isDirectory()) return invalid("app.create", "path must point to a directory.");
+  } catch (error) {
+    return invalid("app.create", error.code === "ENOENT" ? `Parent directory does not exist: ${parent}` : `Cannot inspect parent directory: ${error.message}`);
+  }
+  try {
+    const templateRoot = context.templateRoot ? resolve(context.templateRoot) : TEMPLATE_ROOT;
+    const templatePackage = JSON.parse(await readFile(resolve(templateRoot, "package.json"), "utf8"));
+    const gitignore = await readFile(resolve(templateRoot, "gitignore.template"), "utf8");
+    const templateConfigPath = resolve(templateRoot, "public", "app-config.json");
+    let config = {schemaVersion: "1", title: name, basePath: "/webroot/decision", layout: "overview", dashboardId: "", maxRows: 1000, pageSize: 8, widgets: [], filters: []};
+    try {
+      config = JSON.parse(await readFile(templateConfigPath, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    try {
+      await mkdir(destination, {recursive: false});
+    } catch (error) {
+      return invalid("app.create", error.code === "EEXIST" ? `Destination already exists: ${destination}` : `Cannot create destination: ${error.message}`);
+    }
+    await copyTemplateContents(templateRoot, destination);
+    await writeFile(resolve(destination, ".gitignore"), gitignore, "utf8");
+    if(options.value.layout) config.layout=options.value.layout;
+    if(config.layout==='cockpit') config.insights=true;
+    await mkdir(resolve(destination, "public"), {recursive: true});
+    await writeFile(resolve(destination, "package.json"), `${JSON.stringify({...templatePackage, name}, null, 2)}\n`, "utf8");
+    await writeFile(resolve(destination, "public", "app-config.json"), `${JSON.stringify({...config, templateVersion: templatePackage.version}, null, 2)}\n`, "utf8");
+    const lockPath = resolve(destination, "package-lock.json");
+    try {
+      const lock = JSON.parse(await readFile(lockPath, "utf8"));
+      lock.name = name;
+      if (lock.packages?.[""]) lock.packages[""].name = name;
+      await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    return success("app.create", {name, path: destination, templateVersion: templatePackage.version});
+  } catch (error) {
+    return invalid("app.create", `Could not create project: ${error.message}`);
+  }
+}
+
+async function copyTemplateContents(sourceRoot, destinationRoot, relativeDirectory = "") {
+  const sourceDirectory = resolve(sourceRoot, relativeDirectory);
+  const destinationDirectory = resolve(destinationRoot, relativeDirectory);
+  for (const entry of (await readdir(sourceDirectory, {withFileTypes: true})).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+    const relativePath = `${relativeDirectory}/${entry.name}`.replace(/^\//u, "");
+    if (relativePath === ".gitignore" || relativePath === "gitignore.template") continue;
+    if (!templatePathAllowed(relativePath)) continue;
+    const sourcePath = resolve(sourceDirectory, entry.name);
+    const destinationPath = resolve(destinationDirectory, entry.name);
+    if (entry.isDirectory()) {
+      await mkdir(destinationPath, {recursive: false});
+      await copyTemplateContents(sourceRoot, destinationRoot, relativePath);
+    } else if (entry.isFile()) {
+      await cp(sourcePath, destinationPath, {force: false, errorOnExist: true});
+    } else {
+      throw new Error(`Unsupported template entry: ${relativePath}`);
+    }
+  }
+}
+
+function templatePathAllowed(relative) {
+  const relativePath = relative.replaceAll("\\", "/");
+  const parts = relativePath.split("/").filter(Boolean);
+  const basename = parts.at(-1) || "";
+  return !parts.some(part => ["node_modules", "dist", "temp", ".git"].includes(part))
+    && basename !== ".env"
+    && (!basename.startsWith(".env.") || basename === ".env.example");
+}
+
+async function inspectApp(args) {
+  const options = parseOptions(args, "app.inspect");
+  if (!options.ok) return options.error;
+  const projectPath = options.value.path;
+  if (!projectPath) return invalid("app.inspect", "path must be a project directory.");
+  const project = resolve(projectPath);
+  try {
+    if (!(await stat(project)).isDirectory()) return invalid("app.inspect", "path must point to a project directory.");
+    const configPath = resolve(project, "public", "app-config.json");
+    const config = JSON.parse(await readFile(configPath, "utf8"));
+    if (!config || typeof config !== "object" || Array.isArray(config)) return invalid("app.inspect", "app-config.json must contain a JSON object.");
+    if (options.value.strict) {
+      const {configErrors}=await import('../templates/web-app/src/finebi/config.js');
+      const errors = configErrors(config);
+      if (errors.length) return failure("app.inspect", cliError("INVALID_ARGUMENT", {path: "public/app-config.json", message: errors.join(" ")}));
+    }
+    return success("app.inspect", {
+      path: project,
+      dashboardId: config.dashboardId ?? null,
+      layout: config.layout ?? null,
+      directoryEntryId: config.directoryEntryId || null,
+      widgets: Array.isArray(config.widgets) ? config.widgets.length : null,
+      templateVersion: config.templateVersion || null,
+      configValidated: options.value.strict === true,
+      remoteValidated: false,
+    });
+  } catch (error) {
+    return invalid("app.inspect", `Cannot read project configuration: ${error.message}`);
+  }
+}
+
+function parseOptions(args, command) {
+  const value = {};
+  for (let index = 0; index < args.length; index++) {
+    const option = args[index];
+    if (option === "--json") continue;
+    if (option === "--strict" && command === "app.inspect") {
+      if (value.strict) return {ok: false, error: invalid(command, "--strict must only be supplied once.")};
+      value.strict = true;
+      continue;
+    }
+    if (!["--name","--path",...(command==='app.create'?['--layout']:[])].includes(option)) return {ok: false, error: invalid(command, `Unsupported option: ${option}`)};
+    const key = option.slice(2);
+    const next = args[++index];
+    if (!next || next.startsWith("--")) return {ok: false, error: invalid(command, `${option} requires a value.`)};
+    if (value[key]) return {ok: false, error: invalid(command, `${option} must only be supplied once.`)};
+    value[key] = next;
+  }
+  return {ok: true, value};
+}
+
+function invalid(command, message, nextActions = []) {
+  return failure(command, cliError("INVALID_ARGUMENT", {path: command, message, nextActions}));
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/config.js

@@ -56,23 +56,23 @@ export function writeConfigAtomically(path, config, options = {}) {
   }
 }
 
-export function resolveConfig(flags = {}, env = process.env, fileConfig = readConfig()) {
-  const baseUrl = firstNonEmpty(flags.baseUrl, env.FINEBI_BASE_URL, fileConfig.baseUrl);
-  const sameServer = sameBaseUrl(baseUrl, fileConfig.baseUrl);
-  const explicitToken = firstNonEmpty(flags.token, env.FINEBI_AUTH_TOKEN);
-  const savedAuth = sameServer ? fileConfig.auth : undefined;
-  const token = firstNonEmpty(explicitToken, savedAuth?.token, sameServer ? fileConfig.token : undefined);
+export function resolveConfig(flags = {}, env = process.env, fileConfig = readConfig()) {
+  const baseUrl = firstNonEmpty(flags.baseUrl, env.FINEBI_BASE_URL, fileConfig.baseUrl);
+  const sameServer = sameBaseUrl(baseUrl, fileConfig.baseUrl);
+  const explicitToken = firstNonEmpty(flags.token, env.FINEBI_AUTH_TOKEN);
+  const savedAuth = sameServer ? fileConfig.auth : undefined;
+  const token = firstNonEmpty(explicitToken, savedAuth?.token, sameServer ? fileConfig.token : undefined);
   return normalizeConfig({
     ...fileConfig,
-    baseUrl,
+    baseUrl,
     timeoutMs: parsePositiveInt(firstNonEmpty(flags.timeoutMs, env.FINEBI_TIMEOUT_MS), fileConfig.timeoutMs),
     capabilityTtlMs: parsePositiveInt(
       firstNonEmpty(flags.capabilityTtlMs, env.FINEBI_CAPABILITY_TTL_MS),
       fileConfig.capabilityTtlMs,
     ),
     auth: {
-      ...(explicitToken ? {} : savedAuth),
-      token,
+      ...(explicitToken ? {} : savedAuth),
+      token,
     },
   });
 }
@@ -81,10 +81,10 @@ export function updateConfigValue(config, key, value, now = () => new Date().toI
   const next = normalizeConfig(config);
   switch (key) {
     case "base-url":
-      if (next.baseUrl !== value) {
-        next.capabilityCacheInvalidatedAt = now();
-        delete next.auth;
-        delete next.token;
+      if (next.baseUrl !== value) {
+        next.capabilityCacheInvalidatedAt = now();
+        delete next.auth;
+        delete next.token;
       }
       next.baseUrl = value;
       return next;
@@ -128,7 +128,7 @@ function defaultConfig() {
   };
 }
 
-export function normalizeConfig(config) {
+export function normalizeConfig(config) {
   return {
     ...config,
     timeoutMs: parsePositiveInt(config.timeoutMs, DEFAULT_TIMEOUT_MS),
@@ -136,14 +136,14 @@ export function normalizeConfig(config) {
   };
 }
 
-function sanitizeConfig(config) {
-  if (config.schemaVersion === 2) {
-    return {
-      schemaVersion: 2,
-      currentProfile: config.currentProfile,
-      profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [name, sanitizeConfig(normalizeConfig(profile))])),
-    };
-  }
+function sanitizeConfig(config) {
+  if (config.schemaVersion === 2) {
+    return {
+      schemaVersion: 2,
+      currentProfile: config.currentProfile,
+      profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [name, sanitizeConfig(normalizeConfig(profile))])),
+    };
+  }
   const { token: _legacyToken, ...rest } = config;
   const auth = config.auth
     ? {
@@ -166,11 +166,11 @@ function sanitizeConfig(config) {
     ...rest,
     auth,
   };
-}
-
-export function sameBaseUrl(left, right) {
-  return (left || "").replace(/\/+$/, "") === (right || "").replace(/\/+$/, "");
-}
+}
+
+export function sameBaseUrl(left, right) {
+  return (left || "").replace(/\/+$/, "") === (right || "").replace(/\/+$/, "");
+}
 
 function firstNonEmpty(...values) {
   return values.find((value) => typeof value === "string" && value.trim().length > 0)?.trim();