@finebi/finebi-cli 1.5.0 → 1.6.0

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/proxy.test.mjs

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {createServer} from 'node:http';
+import {createDevMiddleware} from '../scripts/dev-proxy.mjs';
+
+test('development identity stays on server and cross-site or out-of-scope requests are rejected', async () => {
+  const upstream = [];
+  const middleware = createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000}, {FINEBI_DEV_BASE_URL:'http://bi.example/webroot/decision',FINEBI_DEV_USERNAME:'tester',FINEBI_DEV_PASSWORD:'dev-secret'}, async (url,init) => {
+    upstream.push({url,init});
+    return new Response(JSON.stringify(url.endsWith('/login') ? {data:{accessToken:'session-secret'}} : {success:true,data:{w:{previewResult:{resultType:'DETAIL'}}}}));
+  });
+  const server=createServer((req,res)=>middleware(req,res,()=>{res.writeHead(404);res.end();}));
+  await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const base=`http://127.0.0.1:${server.address().port}`;
+  const path='/webroot/decision/v5/api/dashboard/report/r/widgets/query';
+  const request=(body,headers={})=>fetch(base+path,{method:'POST',headers:{'Content-Type':'application/json','X-Requested-With':'XMLHttpRequest',...headers},body:JSON.stringify(body)});
+  try {
+    const valid={widgetIds:['w'],pageLimit:1000};
+    assert.equal((await request(valid,{Origin:'https://evil.example'})).status,403);
+    assert.equal((await request({...valid,widgetIds:['other']})).status,400);
+    assert.equal((await request({...valid,pageLimit:10001})).status,400);
+    assert.equal((await request({...valid,refer:{'未配置的控件':['x']}})).status,400);
+    assert.equal(upstream.length,0);
+    const result=await request(valid,{Origin:base});
+    assert.equal(result.status,200);
+    assert.doesNotMatch(await result.text(),/secret/);
+    assert.equal(upstream.length,2);
+    assert.equal(upstream[1].init.headers.Cookie,'fine_auth_token=session-secret');
+    assert.equal(upstream[1].init.redirect,'manual');
+    assert.equal((await fetch(base+'/webroot/decision/login',{method:'POST'})).status,403);
+    assert.equal((await request(valid)).status,200);
+    assert.equal(upstream.length,3,'reuse only the in-memory development session');
+  } finally {await new Promise(r=>server.close(r));}
+});
+test('HTML login response clears expired development session and explicit retry logs in again', async()=>{
+  let logins=0, queries=0;
+  const middleware=createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],filters:[],maxRows:1000},{FINEBI_DEV_BASE_URL:'http://bi.example/webroot/decision',FINEBI_DEV_USERNAME:'tester',FINEBI_DEV_PASSWORD:'secret'},async url=>{
+    if(url.endsWith('/login')){logins++;return new Response(JSON.stringify({data:{accessToken:'token-'+logins}}));}
+    if(++queries===1)return new Response('<html>登录</html>',{headers:{'content-type':'text/html'}});
+    return new Response(JSON.stringify({success:true,data:{w:{previewResult:{resultType:'DETAIL'}}}}));
+  });
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=()=>fetch(`http://127.0.0.1:${server.address().port}/webroot/decision/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10})});
+  try{const expired=await send();assert.equal(expired.status,401);assert.equal((await expired.json()).errorCode,'AUTH_REQUIRED');assert.equal((await send()).status,200);assert.equal(logins,2);}finally{await new Promise(r=>server.close(r));}
+});
+test('missing credentials gives an explicit auth error without upstream access',async()=>{
+  const middleware=createDevMiddleware({basePath:'/webroot/decision',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000},{},()=>{throw Error('must not fetch');});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));
+  await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  try {
+    const r=await fetch(`http://127.0.0.1:${server.address().port}/webroot/decision/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10})});
+    assert.equal(r.status,401);assert.equal((await r.json()).errorCode,'AUTH_REQUIRED');
+  }finally{await new Promise(r=>server.close(r));}
+});
+test('date proxy accepts real dates without an option allowlist and rejects malformed overrides',async()=>{
+  const calls=[];
+  const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000,filters:[{name:'日期',label:'日期',type:'date'},{name:'产品',label:'产品',options:[{label:'橡皮',value:'橡皮'}]}]},
+    {FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async (_url,init)=>{calls.push(JSON.parse(init.body));return new Response(JSON.stringify({success:true,data:{}}));});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=refer=>fetch(`http://127.0.0.1:${server.address().port}/bi/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:1000,refer})});
+  try {
+    for(const refer of [{'日期':['2023-02-29']},{'日期':['2024-02-30']},{'日期':['0000-01-01']},{'日期':['2024-2-01']},{'日期':['']},{'日期':['2024-01-01','2024-02-01']},{'日期':[42]},{'未知':['2024-01-01']},{'产品':['未知']}]) assert.equal((await send(refer)).status,400);
+    assert.equal(calls.length,0);
+    const refer={'日期':['2024-02-29'],'产品':['橡皮']};assert.equal((await send(refer)).status,200);assert.deepEqual(calls[0].refer,refer);
+    assert.equal((await send({})).status,200);assert.deepEqual(calls[1].refer,{});
+  }finally{await new Promise(r=>server.close(r));}
+});
+
+test('proxy applies the same typed contract to ranges, multi-select, null and unsupported raw values',async()=>{
+  const calls=[];
+  const middleware=createDevMiddleware({basePath:'/bi',dashboardId:'r',widgets:[{entryId:'w'}],maxRows:1000,filters:[
+    {name:'产品',label:'产品',type:'multi-select',allowNull:true,options:[{label:'A',value:'A'},{label:'B',value:'B'}]},
+    {name:'日期',label:'日期',type:'date-range'}, {name:'金额',label:'金额',type:'number'},
+  ]},{FINEBI_DEV_BASE_URL:'http://bi.example/bi',FINEBI_DEV_TOKEN:'secret'},async (_url,init)=>{calls.push(JSON.parse(init.body));return new Response(JSON.stringify({success:true,data:{}}));});
+  const server=createServer((req,res)=>middleware(req,res,()=>{}));await new Promise(r=>server.listen(0,'127.0.0.1',r));
+  const send=refer=>fetch(`http://127.0.0.1:${server.address().port}/bi/v5/api/dashboard/report/r/widgets/query`,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:JSON.stringify({widgetIds:['w'],pageLimit:10,refer})});
+  try {
+    for(const refer of [{'产品':['A','B']},{'产品':['A,C']},{'产品':['A,A']},{'产品':['A,']},{'日期_s':['2024-03-01'],'日期_e':['2024-02-29']},{'日期':['2024-01-01']},{'金额':['10,20']},null]) assert.equal((await send(refer)).status,400);
+    assert.equal(calls.length,0);
+    for(const refer of [{'产品':['A,B'],'日期_s':['2024-02-29'],'金额':['-0.25']},{'产品':['null']},{}]) {
+      assert.equal((await send(refer)).status,200);assert.deepEqual(calls.at(-1).refer,refer);
+    }
+  }finally{await new Promise(r=>server.close(r));}
+});

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tests/runtime.test.mjs

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict';
+import {after, test} from 'node:test';
+import {createServer} from 'vite';
+const server = await createServer({configFile: false, cacheDir: 'temp/vite-tests', server: {middlewareMode: true, hmr: false}});
+after(() => server.close());
+const {normalize} = await server.ssrLoadModule('/src/finebi/normalize.ts');
+const {queryWidgets, FineBIError} = await server.ssrLoadModule('/src/finebi/client.ts');
+const {chartValues, selectDataset} = await server.ssrLoadModule('/src/services/view-data.ts');
+const detail = () => ({previewResult: {resultType: 'DETAIL', header: [
+  {dId: 'd', text: '重复名'}, {dId: 'n', text: '重复名'}, {dId: 't', text: '日期'}
+], items: [[{value: 'A', text: 'A', authority: true}, {value: '1234.50', formatText: '1,234.50元', authority: true}, {value: '1349020800000', formatText: '2012-10-01', authority: true}]], row: 1000, size: 1, hasNext: true}, widgetBean: {dimensions: {d: {type: 1}, n: {type: 2}, t: {type: 3}}}});
+test('detail preserves field identity, display, decimal and date values with honest range', () => {
+  const r = normalize(detail());
+  assert.equal(r.schemaVersion, '1');
+  assert.equal(r.normalization, 'COMPLETE');
+  assert.deepEqual(r.datasets[0].columns.map(c => c.key), ['c0','c1','c2']);
+  assert.deepEqual(r.datasets[0].rows[0].cells.map(c => c.value), ['A','1234.50','1349020800000']);
+  assert.equal(r.datasets[0].rows[0].cells[1].display, '1,234.50元');
+  assert.equal(r.range.total.value, 1000);
+  assert.ok(r.warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+});
+test('restricted, display-only, missing, unknown and invalid dates cannot become computable values', () => {
+  const source = detail();
+  source.previewResult.items = [[{value: 'secret', text: '***', authority: false}, {value: null, text: '20%', authority: true}, {value: '9223372036854775808', authority: true}], []];
+  const r = normalize(source);
+  assert.equal(r.normalization, 'PARTIAL');
+  const cells = r.datasets[0].rows[0].cells;
+  assert.equal(cells[0].state, 'RESTRICTED');
+  assert.equal(cells[0].value, null);
+  assert.equal(cells[1].state, 'UNAVAILABLE');
+  assert.equal(cells[2].reason, 'INVALID_TIMESTAMP_VALUE');
+  delete source.widgetBean;
+  assert.equal(normalize(source).datasets[0].rows[0].cells[1].value, null);
+});
+test('full-looking page does not discard native hasNext; empty is different from unsupported', () => {
+  const source = detail(); source.previewResult.row = 1;
+  assert.ok(normalize(source).warnings.includes('NEXT_PAGE_UNSUPPORTED'));
+  source.previewResult.items = []; source.previewResult.row = 0; source.previewResult.hasNext = false;
+  assert.equal(normalize(source).datasets[0].returnedRowCount, 0);
+  assert.equal(normalize({previewResult: {resultType: 'BICROSS'}}).normalization, 'UNSUPPORTED');
+});
+test('chart permission placeholders and all supported detail date metadata preserve their semantics', () => {
+  const r=normalize({previewResult:{resultType:'CHART',geoms:[{dataModel:{fields:[{id:'n',name:'指标',fieldType:'MEASURE'}],colData:[['***']],rowCount:1}}]}});
+  assert.equal(r.datasets[0].rows[0].cells[0].state,'RESTRICTED');
+  for(const type of [3,13,15,20]) {const s=detail();s.widgetBean.dimensions.t.type=type;assert.equal(normalize(s).datasets[0].columns[2].type,'DATE');}
+});
+test('chart preserves multiple models, rejects formatted numeric strings and mismatched columns', () => {
+  const model = {fields: [{id:'x',name:'地区',fieldType:'DIMENSION'}, {id:'y',name:'金额',fieldType:'MEASURE'}], colData: [['East','West'], [12,'1,234']],rowCount:2};
+  const r = normalize({previewResult:{resultType:'CHART',geoms:[{dataModel:model},{dataModel:{...model,colData:[['A'],[]],rowCount:1}}]}});
+  assert.equal(r.datasets.length,2);
+  assert.equal(r.datasets[0].rows[0].cells[1].value,'12');
+  assert.equal(r.datasets[0].rows[1].cells[1].state,'UNAVAILABLE');
+  assert.equal(r.normalization,'PARTIAL');
+});
+const config = {schemaVersion:'1',basePath:'/webroot/decision',dashboardId:'report',maxRows:1000,widgets:[{entryId:'table',type:'table',name:'明细'}],filters:[{name:'地区',label:'地区',options:[{label:'西部',value:'West'}]}]};
+test('query sends scoped refer, cookie credentials and bounded pageLimit without browser token storage', async () => {
+  let sent;
+  const r = await queryWidgets(config, {'地区':'West'}, undefined, async (url, init) => {
+    sent = {url, ...init};
+    return new Response(JSON.stringify({success:true,data:{table:detail()}}));
+  });
+  assert.equal(sent.credentials,'include');
+  assert.equal(sent.headers['X-Requested-With'],'XMLHttpRequest');
+  assert.deepEqual(JSON.parse(sent.body).refer, {'地区':['West']});
+  assert.equal(JSON.parse(sent.body).pageLimit,1000);
+  assert.equal(sent.headers.Authorization,undefined);
+  assert.equal(r.table.datasets[0].returnedRowCount,1);
+  await assert.rejects(queryWidgets({...config,maxRows:10001},{},undefined,()=>{throw new Error('must not fetch');}), /maxRows/);
+  await assert.rejects(queryWidgets(config,{'未知':'x'}), /筛选/);
+});
+test('auth expiry, permission denial, login HTML and missing widget stay distinct from empty data', async () => {
+  for (const [response, code] of [[new Response('',{status:302,headers:{Location:'/login'}}),'AUTH_REQUIRED'],[new Response('',{status:401}),'AUTH_REQUIRED'],[new Response('',{status:403}),'PERMISSION_DENIED'],[new Response(JSON.stringify({errorCode:'TIME_OUT'})),'AUTH_REQUIRED'],[new Response('<html>login</html>',{headers:{'content-type':'text/html'}}),'AUTH_REQUIRED'],[new Response(JSON.stringify({success:true,data:{}})),'INVALID_RESPONSE']]) {
+    await assert.rejects(queryWidgets(config,{},undefined,async()=>response), e=>e instanceof FineBIError && e.code===code);
+  }
+});
+test('view binding requires exact fields and an explicit model for multi-model results', () => {
+  const source = {previewResult:{resultType:'CHART',geoms:[{dataModel:{fields:[{id:'x',name:'地区',fieldType:'DIMENSION'},{id:'y',name:'金额',fieldType:'MEASURE'}],colData:[['East','West'],[12,5]],rowCount:2}}]}};
+  const r=normalize(source);
+  assert.deepEqual(chartValues(selectDataset(r),{categoryFieldId:'x',valueFieldId:'y'}),[{name:'East',value:12},{name:'West',value:5}]);
+  assert.throws(()=>chartValues(selectDataset(r),{categoryFieldId:'x',valueFieldId:'missing'}),/字段/);
+  r.datasets.push({...r.datasets[0],id:'model1'});
+  assert.throws(()=>selectDataset(r),/模型/);
+  assert.equal(selectDataset(r,'model1').id,'model1');
+});
+test('date filters accept calendar dates without options and omit cleared dates', async () => {
+  const dateConfig = {...config, filters:[{name:'日期',label:'日期',type:'date'},...config.filters]};
+  let sent;
+  const fetchImpl=async (_url,init)=>{sent=JSON.parse(init.body);return new Response(JSON.stringify({success:true,data:{table:detail()}}));};
+  for (const value of ['2012-10-02','2024-02-29','0001-01-01','9999-12-31']) {
+    await queryWidgets(dateConfig,{'日期':value},undefined,fetchImpl);
+    assert.deepEqual(sent.refer,{'日期':[value]});
+  }
+  await queryWidgets(dateConfig,{'日期':''},undefined,fetchImpl);
+  assert.deepEqual(sent.refer,{});
+  for (const value of ['2023-02-29','2024-02-30','2024-04-31','0000-01-01','10000-01-01','2024-13-01','2024-1-01','2024-01-01T00:00:00Z']) {
+    await assert.rejects(queryWidgets(dateConfig,{'日期':value},undefined,()=>{assert.fail('invalid date must not be sent');}),/筛选/);
+  }
+  for (const filter of [{name:'日期',label:'日期',type:'date',options:[]},{name:'日期',label:'日期',type:'unknown'}]) {
+    await assert.rejects(queryWidgets({...config,filters:[filter]},{},undefined,()=>{assert.fail('invalid configuration must not be sent');}),/筛选/);
+  }
+});
+
+test('typed filters encode native multi-value, null and open date ranges without guessing', async () => {
+  const filters=[
+    {name:'文本',label:'文本',type:'text',allowNull:true},
+    {name:'多选',label:'多选',type:'multi-select',options:[{label:'东',value:'East'},{label:'西',value:'West'}]},
+    {name:'数值',label:'数值',type:'number'},
+    {name:'区间',label:'区间',type:'date-range'},
+    {name:'月份',label:'月份',type:'month-range'},
+    {name:'年',label:'年',type:'year'}, {name:'季',label:'季',type:'quarter'},
+    {name:'标签',label:'标签',type:'time-label',options:[{label:'本月',value:'本月,动态'}]},
+  ];
+  let sent;
+  const send=values=>queryWidgets({...config,filters},values,undefined,async (_url,init)=>{
+    sent=JSON.parse(init.body);return new Response(JSON.stringify({success:true,data:{table:detail()}}));
+  });
+  await send({'文本':' North ','多选':['East','West'],'数值':'12345678901234567890.25','区间':{start:'2024-02-29',end:'2024-03-01'},'月份':{start:'2024-01',end:''},'年':'2024','季':'2024-3','标签':'本月,动态'});
+  assert.deepEqual(sent.refer,{'文本':[' North '],'多选':['East,West'],'数值':['12345678901234567890.25'],'区间_s':['2024-02-29'],'区间_e':['2024-03-01'],'月份_s':['2024-01'],'年':['2024'],'季':['2024-3'],'标签':['本月,动态']});
+  await send({'文本':null,'多选':[],'区间':{start:'',end:''}});
+  assert.deepEqual(sent.refer,{'文本':['null']});
+  await send({}); assert.deepEqual(sent.refer,{});
+  for(const values of [{'文本':'A,B'},{'文本':'null'},{'多选':['East,West']},{'多选':['East','East']},{'多选':[null]},{'数值':'1e3'},{'区间':{start:'2024-03-02',end:'2024-03-01'}},{'区间':{start:'2024-02-30',end:''}},{'月份':{start:'2024-13',end:''}},{'年':'0000'},{'季':'2024-5'},{'标签':'未知'},{'区间':null},{'未知':''}]) {
+    await assert.rejects(send(values),/筛选/);
+  }
+});
+
+test('filter configuration rejects ambiguous native keys and unrepresentable choices before fetching',async()=>{
+  for(const filters of [
+    [{name:'范围',label:'范围',type:'date-range'},{name:'范围_s',label:'起始',type:'date'}],
+    [{name:'重复',label:'A',type:'text'},{name:'重复',label:'B',type:'date'}],
+    [{name:'x',label:'x',options:[{label:'逗号',value:'A,B'}]}],
+    [{name:'x',label:'x',options:[{label:'字面空值',value:'null'}]}],
+    [{name:'x',label:'x',type:'number-range'}],
+    [{name:'x',label:'x',type:'date',allowNull:true}],
+  ]) await assert.rejects(queryWidgets({...config,filters},{},undefined,()=>assert.fail('invalid config must not fetch')),/筛选/);
+});

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "compilerOptions": {"target":"ES2020","lib":["ES2020","DOM","DOM.Iterable"],"module":"ESNext","moduleResolution":"Bundler","jsx":"react-jsx","strict":true,"skipLibCheck":true,"esModuleInterop":true,"resolveJsonModule":true,"isolatedModules":true,"noEmit":true},
+  "include":["src","vite.config.ts"]
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/vite.config.ts

@@ -0,0 +1,13 @@
+import {readFileSync} from 'node:fs';
+import {defineConfig, loadEnv} from 'vite';
+// @ts-expect-error The development-only Node module is tested directly with node:test.
+import {createDevMiddleware} from './scripts/dev-proxy.mjs';
+export default defineConfig(({mode}) => ({
+  base: './',
+  server: {host:'127.0.0.1',port:4173,strictPort:true},
+  plugins:[{name:'finebi-development-session',apply:'serve',configureServer(server) {
+    const config=JSON.parse(readFileSync(new URL('./public/app-config.json',import.meta.url),'utf8'));
+    const env={...loadEnv(mode,process.cwd(),'FINEBI_DEV_'),...process.env};
+    server.middlewares.use(createDevMiddleware(config,env));
+  }}],
+}));

package/skills/finebi-cli-agent/scripts/finebi-cli-runner.mjs

@@ -10,10 +10,10 @@ const scriptDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCliEntry = resolve(scriptDirectory, "finebi-cli", "src", "index.js");
 
 export async function run(argv = process.argv.slice(2), options = {}) {
-  const env = {...(options.env ?? process.env)};
-  if (!env.FINEBI_CLI_PATH?.trim() && existsSync(bundledCliEntry)) {
-    env.FINEBI_CLI_PATH = bundledCliEntry;
-  }
+  const env = {...(options.env ?? process.env)};
+  if (!env.FINEBI_CLI_PATH?.trim() && existsSync(bundledCliEntry)) {
+    env.FINEBI_CLI_PATH = bundledCliEntry;
+  }
   return runCore(argv, {...options, env});
 }
 

package/src/app.js

@@ -0,0 +1,189 @@
+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}));
+}

package/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();