@finebi/finebi-cli 1.6.0 → 1.6.2

package/skills/finebi-cli-agent/references/scenario-workflows.md

@@ -4,7 +4,7 @@
 
 仅当用户要根据业务描述创建或更新 Widget/Dashboard，且命令需要 JS DSL 文件时使用本文件。资源查询和执行边界仍遵循 `SKILL.md`、`command-workflows.md` 与 `mutation-confirmation-contract.md`；仅 `delete` 命令需要人工确认。
 
-本 Skill 负责解析语义和消费已验证 JS 制品，不生成、修改、解析或修复 DSL。
+按入口声明的职责处理 DSL：完整 Agent 在同一任务内生成、回读并修复本次 JS 制品；独立场景规划器只解析语义、消费外部已验证制品。共享流程不扩大独立规划器的文件写入权限。生成本地文件与执行 FineBI 写命令分别遵循用户请求范围。
 
 ## 2. 解析业务语义
 
@@ -12,8 +12,8 @@
 
 依赖只读命令解析：
 
-1. 遍历 `subject.search` 全部分页并用 `subject.info` 确认主题。
-2. 需要按表名解析数据集时，先用用户提供的完整名称搜索 `analysis-ds` 和 `public-ds`，遍历全部分页，并按返回的真实名称全等判断唯一精确匹配。
+1. 已知主题 ID 时直接用 `subject.info` 核验；只有名称或归属不清时才搜索主题，并在证明名称唯一前遍历全部分页。同一连续任务中前提未变化的已核实主题证据可以复用。
+2. 已知数据集 ID 时直接用 `analysis-ds.info` 核验主题、名称和所需字段；需要按表名解析数据集时，先用用户提供的完整名称搜索 `analysis-ds` 和 `public-ds`，遍历全部分页，并按返回的真实名称全等判断唯一精确匹配。
 3. 没有精确匹配时，对分析表和公共数据集执行关键词搜索，结合字段、位置、主题归属、资源类型、引擎类型和用户意图选择候选；多个候选合理时要求用户选择。
 4. 选定资源为 `public-ds` 时，将其作为来源按前置资源流程创建目标主题内的 `analysis-ds`，使用写响应中的全部实际 ID 逐一调用 `analysis-ds.info` 和必要的 `preview`；转换完成前不得构建语义交接对象，也不得继续查询数据连接。
 5. 只有数据集层没有合理候选时，才查询数据连接和物理表，并按前置资源流程创建所需数据集；不得把物理表标识当作数据集 ID。
@@ -34,13 +34,15 @@
 
 搜索命中公共数据集时，`analysis-ds.add` 属于交接所需的前置资源创建：DSL 的 `from(表原始名)` 必须引用已验证的公共数据集原始名（`public-ds search` 返回的 `id`，全局唯一），目标主题通过 `--subject-id` 传入；执行后逐一回查服务端返回的分析表实际 ID。不得在前置资源尚未创建时向交接对象填入公共数据集 ID、预期 ID 或占位 ID。
 
-## 4. 语义交接确认
+## 4. 语义记录与校验
 
-按照 `handoff-contract.md` 构建完整 JSON 交接对象并展示。语义交接确认只确认制品生成输入，不授权执行任何 CLI 写命令。用户修改任何影响制品的语义后，原交接确认及已有制品映射均失效。
+同一 Agent 连续完成生成和执行时，记录本次实际用到的主题、来源与字段、关系、图表/布局意图、组件引用和产物路径；按 `handoff-contract.md` 和 DSL 输入契约核验这些信息，不必构造或展示完整交接 JSON。跨执行体交接时使用完整 `contractVersion: "1.0"` JSON 与文件映射。
+
+业务目标明确时直接继续，不为内部语义记录或产物路径增加审批；只有业务歧义未消除或用户明确要求先审阅时才等待。用户改变影响制品的语义后，更新记录、重新生成受影响文件并废止对应旧写计划。语义审阅不代替删除计划确认；仅要求本地生成不授权 FineBI 写命令。
 
 ## 5. JS 制品映射
 
-仅接收调用方、用户或实际可用生成工作流提供的完整 `artifact key -> absolute JS file path` 映射。每个路径必须：
+有 DSL 生成职责的执行体自行安排当前任务隔离目录中的唯一绝对路径，或使用用户指定路径；按实际涉及的 API 生成并回读自检后，记录完整 `artifact key -> absolute JS file path` 映射。独立场景规划器仅接收调用方、用户或可用生成工作流提供的现有制品映射，不自行生成或修复 DSL。冻结远端写计划前，每个路径必须：
 
 - 是现有 `.js` 文件的绝对路径；
 - 由用户明确提供，或位于为当前任务创建的隔离临时目录；不得根据当前工作目录猜测 `cli/` 或其他项目路径；
@@ -48,7 +50,7 @@
 - 与其他 artifact key 的规范路径不同；
 - 在冻结写计划时记录 SHA-256。
 
-缺少 key、路径不存在、路径重复或文件被修改时进入 `BLOCKED` 或废止当前写计划，不在本 Skill 中修复文件。
+缺少 key、路径不存在、路径重复或文件被修改时，不执行旧写计划。具有生成职责时先补齐或修复本次文件并重新校验；独立规划器报告缺失制品并等待提供。无法满足边界时进入 `BLOCKED`。
 
 ## 6. 创建 Widget
 
@@ -72,4 +74,4 @@
 
 以下情况进入 `BLOCKED`：运行时缺少所需命令；资源/字段/引用存在歧义；主题或数据集归属不匹配；JS 映射不完整或文件无效；无法证明 Dashboard 引用组件唯一；运行时 schema 与冻结计划不一致。
 
-只是在等待语义确认、删除计划确认或包含删除的清理计划确认时，状态应为 `AWAITING_CONFIRMATION`，不是 `BLOCKED`。
+等待用户明确要求的语义审阅、删除计划确认或包含删除的清理计划确认时，状态为 `AWAITING_CONFIRMATION`。明确任务中的内部语义记录不经过该状态。

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

@@ -2,12 +2,18 @@
 
 用户要求生成动态页面、HTML看板或FineBI Web应用时，先选择同一CLI安装的本地 `app create`，再按生成项目AGENTS.md开发。创建模板不需要连接；读取/绑定FineBI资源才检查认证和实时命令help。
 
-1. `finebi-cli app create --name <name> --path <parent>` 创建工程，不安装/运行/发布。
-2. 用dashboard search/info/data确认唯一来源、板内entryId、结果字段dId、真实控件filterName；样本仅用于理解和测试。
-3. 在public/app-config.json填写非敏感绑定。图表库和UI组件库按页面需求选择，默认实现及替换约定见生成项目的docs/design.md。请求、认证、解析复用模板src/finebi；业务代码按项目指南开发。
-4. `finebi-cli app inspect --path <project>`只校验本地配置，不能证明字段/权限在远端存在。按项目README配置开发身份，再安装、启动、测试与构建。
-5. 浏览器验收实际请求、空/错误/权限状态、图表与刷新；生产部署必须用访问者Cookie，不携带开发身份。
+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 成功不能替代这一步；优先复用已有会话，不重复索要可用身份的密码。
+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，不携带开发身份。
 
-内置CLI同样通过 `node "<skill-dir>/scripts/finebi-cli/src/index.js" app ...` 调用，不走动态业务runner。生产页面不调用CLI。禁止将开发时查到的业务数据或token写入HTML/JS/config；无筛选控件不能伪造服务端过滤。pageLimit不是分页，hasNext和warnings必须呈现。v1不提供发布上传/目录来源/服务端续页，先说明缺口，不发明命令。
+内置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 子进程后端。
+
+retail 的 examples/retail.config.json 提供零售场景占位绑定，字段与口径须按同一来源核实；展示格式见生成项目 docs/design.md。不要根据原组件标题猜指标含义，也不要把记录数自动称为去重门店数。真实业务响应和分析结论不进入分发模板。
+
+分组表 BIGROUP 可绑定为 type: "table"，使用 main 数据集与结果字段 dId；保留父级分组、小计、总计及 UNKNOWN 行，不将汇总和明细混加。日期/数值分组键只保证展示语义，不能按显示文本恢复原值。交叉表 BICROSS 可用 table 展示当前矩阵，通常省略 tableFieldIds/localFilterFieldIds；cross:row、cross:0 等为本次查询槽位，不是 FineBI dId，不能用于 dimensionIds 或固定跨查询图形/KPI 绑定。保留原生行列路径、汇总标记与双轴分页警告，不把当前矩阵宣称为全量。复用模板的行、列指标标题去重（保留真实同名分组层级与原始 path）、DATA 行内部“合计”节点隐藏和 NULL 展示规则，不把真实空值当作不可用或补零；详细判定与范围见生成项目 docs/data-contract.md。
 
 模板内置文本、单选/多选、数值选择、日期及日期区间、年月季度、年月区间和已配置时间标签；草稿统一应用，恢复默认与筛选空值分开。配置、状态、请求编码和代理校验共用 src/finebi/filters.js。数值范围、滑块、树/级联和动态候选项暂不支持，不得换成其他类型绕过检查。绑定前核实源控件类型和作用范围，候选项不得冒充完整数据。通用约定、完整支持矩阵、值格式及扩展步骤见生成项目 docs/filters.md。

package/skills/finebi-cli-agent/references/widget-dsl-core.md

@@ -273,6 +273,12 @@ warning 留痕。
 - `QuickCalculationType.YEAR_ON_YEAR_*`：同比
 - `QuickCalculationType.MONTH_ON_MONTH_*`：环比
 
+快速计算作用于指标引用，可用于 `metric`、`value`、`angle`、`text` 指标槽位，不能用于维度。
+`secondaryCalculation` 只允许用户可切换二次计算的类型显式传入；这类类型省略时默认开启，固定策略类型必须省略该参数。
+内置同比、环比要求组件分析区域存在兼容的显示日期维度。
+完整的组件写法见[快速计算二次开关示例](widget-dsl-api-examples.md#1022-快速计算二次开关)。
+`widget info` 的结构化回读与文本 DSL 是不同输出面，不能用回读字段的枚举范围替代文本 DSL 的能力范围。
+
 ### 2.5 主题共享钻取目录
 
 主题共享钻取目录使用独立命令 `drill-directory update --subject-id <id> --file <directory.js>`：

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

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

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

@@ -1,189 +1,157 @@
-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.");
-  }
-  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 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 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 (!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"));
-    const errors = await validateConfig(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,
-      widgets: config.widgets.length,
-      templateVersion: config.templateVersion || null,
-      remoteValidated: false,
-    });
-  } catch (error) {
-    return invalid("app.inspect", `Cannot read project configuration: ${error.message}`);
-  }
-}
-
-async function validateConfig(config) {
-  const errors = [];
-  if (!config || typeof config !== "object" || Array.isArray(config)) return ["configuration must be a JSON object."];
-  const allowedConfigFields = new Set(["schemaVersion", "title", "basePath", "layout", "dashboardId", "maxRows", "pageSize", "widgets", "filters", "templateVersion"]);
-  for (const field of Object.keys(config)) if (!allowedConfigFields.has(field)) errors.push(`unsupported config field: ${field}.`);
-  if (config.schemaVersion !== "1") errors.push("schemaVersion must be \"1\".");
-  if (!nonEmptyString(config.title)) errors.push("title is required.");
-  if (!nonEmptyString(config.basePath) || !/^\/(?!\/)[\w/-]+$/.test(config.basePath)) errors.push("basePath must be a same-origin path.");
-  if (!["overview", "workbench"].includes(config.layout)) errors.push("layout must be overview or workbench.");
-  if (!Number.isInteger(config.maxRows) || config.maxRows < 1 || config.maxRows > 10000) errors.push("maxRows must be an integer from 1 to 10000.");
-  if (!Number.isInteger(config.pageSize) || config.pageSize < 1 || config.pageSize > 100) errors.push("pageSize must be an integer from 1 to 100.");
-  if (typeof config.dashboardId !== "string" || !config.dashboardId.trim()) {
-    if (Array.isArray(config.widgets) && config.widgets.length === 0) return ["project is not bound: dashboardId and widgets must be configured."];
-    errors.push("dashboardId is required.");
-  }
-  if (!Array.isArray(config.widgets) || config.widgets.length === 0) {
-    errors.push("widgets must be a non-empty array.");
-    return errors;
-  }
-  for (const [index, widget] of config.widgets.entries()) {
-    if (!widget || typeof widget !== "object") {
-      errors.push(`widgets[${index}] must be an object.`);
-      continue;
-    }
-    const allowedWidgetFields = new Set(["entryId", "name", "type", "datasetId", "categoryFieldId", "valueFieldId"]);
-    for (const field of Object.keys(widget)) if (!allowedWidgetFields.has(field)) errors.push(`widgets[${index}].${field} is unsupported.`);
-    for (const field of ["entryId", "name", "type"]) {
-      if (typeof widget[field] !== "string" || !widget[field].trim()) errors.push(`widgets[${index}].${field} is required.`);
-    }
-    if (!["table", "bar", "line", "pie", "kpi"].includes(widget.type)) errors.push(`widgets[${index}].type is unsupported.`);
-    if (widget.type && widget.type !== "table" && !nonEmptyString(widget.valueFieldId)) errors.push(`widgets[${index}].valueFieldId is required for ${widget.type}.`);
-    if (widget.type && !["table", "kpi"].includes(widget.type) && !nonEmptyString(widget.categoryFieldId)) errors.push(`widgets[${index}].categoryFieldId is required for ${widget.type}.`);
-    for (const field of ["datasetId", "categoryFieldId", "valueFieldId"]) {
-      if (widget[field] !== undefined && !nonEmptyString(widget[field])) errors.push(`widgets[${index}].${field} must be a non-empty string.`);
-    }
-  }
-  try {
-    const {validateFilterBindings} = await import("../templates/web-app/src/finebi/filters.js");
-    validateFilterBindings(config.filters);
-  } catch (error) {errors.push(error.message);}
-  return errors;
-}
-
-function nonEmptyString(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function parseOptions(args, command) {
-  const value = {};
-  for (let index = 0; index < args.length; index++) {
-    const option = args[index];
-    if (option === "--json") continue;
-    if (option !== "--name" && option !== "--path") 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 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);
+    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 (!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/browser-auth.js

@@ -160,9 +160,8 @@ function abortedAuthorization() {
 function validateBaseUrl(value) {
   try {
     const url = new URL(value);
-    const localHttp = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]", "::1"].includes(url.hostname.toLowerCase());
-    if (url.protocol !== "https:" && !localHttp) {
-      throw new Error("Browser authorization requires HTTPS, except for localhost development.");
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+      throw new Error("Browser authorization requires an HTTP or HTTPS URL.");
     }
     if (url.username || url.password || url.search || url.hash) {
       throw new Error("Browser authorization base URL must not contain credentials, a query, or a fragment.");
@@ -172,7 +171,7 @@ function validateBaseUrl(value) {
     return failure("auth.login", cliError("BROWSER_AUTH_URL_INVALID", {
       path: "baseUrl",
       message: error instanceof Error ? error.message : String(error),
-      nextActions: ["finebi-cli config set base-url <https-url>"],
+      nextActions: ["finebi-cli config set base-url <http-or-https-url>"],
     }));
   }
 }

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

@@ -8,7 +8,7 @@ import {CLI_CONFIG_DIRECTORY} from "./branding.js";
 import {maskSecret} from "./output.js";
 
 export const DEFAULT_TIMEOUT_MS = 30000;
-export const DEFAULT_CAPABILITY_TTL_MS = 600000;
+export const DEFAULT_CAPABILITY_TTL_MS = 20 * 60 * 60 * 1000;
 
 export function defaultConfigPath(env = process.env) {
   const home = env.USERPROFILE || env.HOME || homedir();
@@ -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();

package/skills/finebi-cli-agent/scripts/finebi-cli/src/error-catalog.js

@@ -19,8 +19,8 @@ export const ERROR_CATALOG = [
         recoverableByAgent: true,
         defaultRetryable: false,
         pathSemantics: "Browser authorization base URL",
-        canonicalNextActions: ["finebi-cli config set base-url <https-url>"],
-        expectedAgentBehaviors: ["configure an HTTPS URL or localhost HTTP URL", "rerun browser login"],
+        canonicalNextActions: ["finebi-cli config set base-url <http-or-https-url>"],
+        expectedAgentBehaviors: ["configure an HTTP or HTTPS URL", "rerun browser login"],
         benchmarkTags: ["auth", "browser", "url-validation"],
     },
     {