@miao-vision/cli 0.1.2 → 0.1.6

package/dist/cli.cjs

@@ -40685,10 +40685,20 @@ function coerceCell(value) {
 }
 
 // src/data-profiler.ts
-function profileDataset(dataset) {
-  const columns = dataset.columns.map((col) => profileColumn(col, dataset.rows));
+function profileSummary(dataset) {
+  const allCols = dataset.columns.map((name) => {
+    const values = dataset.rows.map((r) => r[name]).filter((v) => v !== null && v !== void 0 && v !== "");
+    const type = inferColumnType(values);
+    return { name, type };
+  });
+  return { file: dataset.file, rows: dataset.rows.length, sheet: dataset.sheet, columns: allCols };
+}
+function profileDataset(dataset, options = {}) {
+  const targetCols = options.columns ? dataset.columns.filter((c) => options.columns.includes(c)) : dataset.columns;
+  const columns = targetCols.map((col) => profileColumn(col, dataset.rows, options.reliableOnly));
   const numericNames = columns.filter((c) => c.type === "number").map((c) => c.name);
-  const correlations = numericNames.length >= 2 ? computeCorrelations(numericNames, dataset.rows) : void 0;
+  const rawCorrelations = numericNames.length >= 2 ? computeCorrelations(numericNames, dataset.rows) : void 0;
+  const correlations = options.reliableOnly ? rawCorrelations?.filter((c) => c.reliable) : rawCorrelations;
   const hints = generateHints(columns, correlations ?? []);
   const quality = computeDataQuality(columns, dataset.rows.length);
   const insights = generateProfileInsights(columns, quality, correlations ?? [], dataset.rows.length);
@@ -40703,7 +40713,7 @@ function profileDataset(dataset) {
     insights: insights.length > 0 ? insights : void 0
   };
 }
-function profileColumn(name, rows) {
+function profileColumn(name, rows, reliableOnly = false) {
   const values = rows.map((row) => row[name]);
   const nonNull = values.filter((v) => v !== null && v !== void 0 && v !== "");
   const type = inferColumnType(nonNull);
@@ -40729,7 +40739,7 @@ function profileColumn(name, rows) {
       const sorted = [...nums].sort((a, b) => a - b);
       profile.min = sorted[0];
       profile.max = sorted[sorted.length - 1];
-      Object.assign(profile, computeNumericStats(nums, sorted));
+      Object.assign(profile, computeNumericStats(nums, sorted, rows.length, reliableOnly));
     }
   }
   if (type === "string") {
@@ -40752,7 +40762,7 @@ function profileColumn(name, rows) {
   profile.role = inferColumnRole(profile);
   return profile;
 }
-function computeNumericStats(values, sorted) {
+function computeNumericStats(values, sorted, totalRows, reliableOnly) {
   const n = values.length;
   const sum = values.reduce((s, v) => s + v, 0);
   const mean = sum / n;
@@ -40764,18 +40774,31 @@ function computeNumericStats(values, sorted) {
   const skewness = stddev < 1e-10 ? 0 : round(3 * (mean - median) / stddev);
   const iqr = p75 - p25;
   const outlierCount = values.filter((v) => v < p25 - 1.5 * iqr || v > p75 + 1.5 * iqr).length;
-  return {
+  const skewnessReliable = totalRows >= 30;
+  const outlierReliable = totalRows >= 20;
+  const histogramReliable = totalRows >= 20;
+  const result = {
     sum: round(sum),
     mean: round(mean),
     median: round(median),
     p25: round(p25),
     p75: round(p75),
     stddev: round(stddev),
-    skewness,
-    coefficientOfVariation: Math.abs(mean) < 1e-10 ? void 0 : round(stddev / Math.abs(mean)),
-    outlierCount,
-    histogram: computeHistogram(values, sorted[0], sorted[n - 1])
+    coefficientOfVariation: Math.abs(mean) < 1e-10 ? void 0 : round(stddev / Math.abs(mean))
   };
+  if (!reliableOnly || skewnessReliable) {
+    result.skewness = skewness;
+    result.skewnessReliable = skewnessReliable;
+  }
+  if (!reliableOnly || outlierReliable) {
+    result.outlierCount = outlierCount;
+    result.outlierReliable = outlierReliable;
+  }
+  if (!reliableOnly || histogramReliable) {
+    result.histogram = computeHistogram(values, sorted[0], sorted[n - 1]);
+    result.histogramReliable = histogramReliable;
+  }
+  return result;
 }
 function percentile(sorted, p) {
   if (sorted.length === 0) return 0;
@@ -40862,7 +40885,7 @@ function computeCorrelations(numericNames, rows) {
       const pairs = rows.map((row) => [Number(row[a]), Number(row[b])]).filter(([x, y]) => Number.isFinite(x) && Number.isFinite(y));
       if (pairs.length < 3) continue;
       const r = pearsonR(pairs);
-      if (Math.abs(r) >= 0.3) result.push({ a, b, r: round(r) });
+      if (Math.abs(r) >= 0.3) result.push({ a, b, r: round(r), n: pairs.length, reliable: pairs.length >= 10 });
     }
   }
   return result.sort((x, y) => Math.abs(y.r) - Math.abs(x.r));
@@ -40953,14 +40976,6 @@ function generateProfileInsights(columns, quality, correlations, rowCount) {
     });
   }
   for (const col of columns) {
-    if (col.role === "dimension" && col.distinctCount >= 2 && col.distinctCount <= 12 && col.topSharePct && col.topSharePct >= 0.5) {
-      insights.push({
-        type: "suggestion",
-        title: `Dominant category in ${col.name}`,
-        description: `${String(col.topValue)} accounts for ${Math.round(col.topSharePct * 100)}% of non-empty values; annotate this imbalance in share or ranking charts.`,
-        fields: [col.name]
-      });
-    }
     if (col.role === "measure" && col.coefficientOfVariation !== void 0 && col.coefficientOfVariation >= 1) {
       insights.push({
         type: "trend",
@@ -41024,6 +41039,153 @@ function round(value) {
   return Math.round(value * 1e4) / 1e4;
 }
 
+// src/data-query.ts
+var SUPPORTED_OPS = ["sum", "count", "avg", "min", "max"];
+function queryDataset(rows, options) {
+  const groupByCols = options.groupby ? options.groupby.split(",").map((c) => c.trim()).filter(Boolean) : [];
+  const measuresResult = options.measure ? parseMeasures(options.measure) : [];
+  if (isAgentError(measuresResult)) return measuresResult;
+  const measures = measuresResult;
+  let current;
+  if (options.filter) {
+    const filterResult = applyFilter(rows, options.filter);
+    if (!filterResult.ok) return filterResult.error;
+    current = filterResult.rows;
+  } else {
+    current = [...rows];
+  }
+  if (groupByCols.length > 0 || measures.length > 0) {
+    current = aggregateQuery(current, groupByCols, measures);
+  }
+  if (options.orderby) {
+    const ordered = applyOrderBy(current, options.orderby);
+    if (isAgentError(ordered)) return ordered;
+    current = ordered;
+  }
+  if (options.limit != null && options.limit > 0) {
+    current = current.slice(0, options.limit);
+  }
+  return {
+    rows: current,
+    sql: buildSql(groupByCols, measures, options.filter, options.orderby, options.limit),
+    rowCount: current.length
+  };
+}
+function parseMeasures(measure) {
+  const parts = measure.split(",").map((s) => s.trim()).filter(Boolean);
+  const results = [];
+  for (const part of parts) {
+    const match = part.match(/^(\w+)\(([^)]+)\)(?:\s+as\s+(\w+))?$/i);
+    if (!match) {
+      return agentError(
+        "QUERY_INVALID_MEASURE",
+        `Cannot parse measure: "${part}". Use "fn(col) as alias". Supported functions: ${SUPPORTED_OPS.join(", ")}.`
+      );
+    }
+    const [, fnRaw, rawField, aliasRaw] = match;
+    const fn = fnRaw.toLowerCase();
+    if (!SUPPORTED_OPS.includes(fn)) {
+      return agentError(
+        "QUERY_UNSUPPORTED_FUNCTION",
+        `Unsupported aggregate function: "${fn}". Supported: ${SUPPORTED_OPS.join(", ")}.`
+      );
+    }
+    const field = rawField.trim();
+    const alias = aliasRaw ?? `${fn}_${field.replace("*", "all")}`;
+    results.push({ fn, field, alias });
+  }
+  return results;
+}
+function applyFilter(rows, filter) {
+  const match = filter.match(/^(\w+)\s*=\s*(.+)$/);
+  if (!match) {
+    return {
+      ok: false,
+      error: agentError(
+        "QUERY_INVALID_FILTER",
+        `Cannot parse filter: "${filter}". Use "column=value" (simple equality only).`
+      )
+    };
+  }
+  const [, col, rawVal] = match;
+  const val = rawVal.trim();
+  const numVal = Number(val);
+  const filtered = rows.filter((row) => {
+    const cell = row[col];
+    if (Number.isFinite(numVal) && Number.isFinite(Number(cell))) {
+      return Number(cell) === numVal;
+    }
+    return String(cell ?? "") === val;
+  });
+  return { ok: true, rows: filtered };
+}
+function aggregateQuery(rows, groupByCols, measures) {
+  if (groupByCols.length === 0) {
+    const out = {};
+    for (const m of measures) {
+      out[m.alias] = computeAggregate(rows, m);
+    }
+    return [out];
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = JSON.stringify(groupByCols.map((c) => row[c]));
+    const existing = groups.get(key) ?? [];
+    existing.push(row);
+    groups.set(key, existing);
+  }
+  return Array.from(groups.values()).map((groupRows) => {
+    const first = groupRows[0];
+    const out = {};
+    for (const col of groupByCols) {
+      out[col] = first[col];
+    }
+    for (const m of measures) {
+      out[m.alias] = computeAggregate(groupRows, m);
+    }
+    return out;
+  });
+}
+function computeAggregate(rows, measure) {
+  if (measure.fn === "count") return rows.length;
+  const values = rows.map((r) => Number(r[measure.field])).filter((v) => Number.isFinite(v));
+  if (values.length === 0) return 0;
+  if (measure.fn === "avg") return values.reduce((s, v) => s + v, 0) / values.length;
+  if (measure.fn === "min") return Math.min(...values);
+  if (measure.fn === "max") return Math.max(...values);
+  return values.reduce((s, v) => s + v, 0);
+}
+function applyOrderBy(rows, orderby) {
+  const parts = orderby.trim().split(/\s+/);
+  const col = parts[0];
+  const dir = (parts[1] ?? "desc").toLowerCase();
+  if (dir !== "asc" && dir !== "desc") {
+    return agentError("QUERY_INVALID_ORDERBY", `Invalid sort direction: "${dir}". Use "asc" or "desc".`);
+  }
+  const sign = dir === "asc" ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const aNum = Number(a[col]);
+    const bNum = Number(b[col]);
+    if (Number.isFinite(aNum) && Number.isFinite(bNum)) return (aNum - bNum) * sign;
+    return String(a[col] ?? "").localeCompare(String(b[col] ?? "")) * sign;
+  });
+}
+function buildSql(groupByCols, measures, filter, orderby, limit) {
+  const selectParts = [
+    ...groupByCols,
+    ...measures.map((m) => `${m.fn.toUpperCase()}(${m.field}) AS ${m.alias}`)
+  ];
+  let sql = `SELECT ${selectParts.length > 0 ? selectParts.join(", ") : "*"} FROM data`;
+  if (filter) {
+    const [col, val] = filter.split("=", 2);
+    sql += ` WHERE ${col.trim()} = ${val.trim()}`;
+  }
+  if (groupByCols.length > 0) sql += ` GROUP BY ${groupByCols.join(", ")}`;
+  if (orderby) sql += ` ORDER BY ${orderby}`;
+  if (limit != null) sql += ` LIMIT ${limit}`;
+  return sql;
+}
+
 // src/data-transform.ts
 function prepareChartData(rows, chart) {
   let current = [...rows];
@@ -56251,56 +56413,6 @@ function collectDerivedFields(chart) {
   return fields;
 }
 
-// src/deck-schema.ts
-var SLIDE_LAYOUTS = [
-  "cover",
-  "title-only",
-  "text-points",
-  "text-chart",
-  "metrics-chart",
-  "chart-full",
-  "table-full",
-  "ending"
-];
-var metricTransformSchema = external_exports.object({
-  type: external_exports.enum(["derive-month", "aggregate", "sort", "limit", "filter"]),
-  field: external_exports.string().optional(),
-  as: external_exports.string().optional(),
-  groupBy: external_exports.array(external_exports.string()).optional(),
-  measures: external_exports.array(external_exports.object({
-    field: external_exports.string(),
-    op: external_exports.enum(["sum", "avg", "count", "min", "max"]),
-    as: external_exports.string()
-  })).optional(),
-  order: external_exports.enum(["asc", "desc"]).optional(),
-  value: external_exports.unknown().optional()
-});
-var slideMetricSchema = external_exports.object({
-  label: external_exports.string().min(1),
-  value: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
-  format: external_exports.string().optional(),
-  data: external_exports.object({
-    transform: external_exports.array(metricTransformSchema).optional()
-  }).optional()
-});
-var slideSpecSchema = external_exports.object({
-  layout: external_exports.enum(SLIDE_LAYOUTS),
-  eyebrow: external_exports.string().optional(),
-  title: external_exports.string().optional(),
-  claim: external_exports.string().optional(),
-  bullets: external_exports.array(external_exports.string()).optional(),
-  callout: external_exports.string().optional(),
-  annotation: external_exports.string().optional(),
-  metrics: external_exports.array(slideMetricSchema).optional(),
-  charts: external_exports.array(chartSpecSchema).optional()
-});
-var deckSpecSchema = external_exports.object({
-  title: external_exports.string().optional(),
-  description: external_exports.string().optional(),
-  theme: external_exports.enum(["default", "editorial", "dark", "minimal"]).optional(),
-  slides: external_exports.array(slideSpecSchema).min(1, "Deck must have at least one slide")
-});
-
 // src/deck-layouts.ts
 function withSize(chart, width, height) {
   return { ...chart, style: { ...chart.style, width, height } };
@@ -56648,9 +56760,235 @@ function renderDeckHtml(spec, rows, themeOverride) {
 </html>`;
 }
 
+// src/deck-schema.ts
+var SLIDE_LAYOUTS = [
+  "cover",
+  "title-only",
+  "text-points",
+  "text-chart",
+  "metrics-chart",
+  "chart-full",
+  "table-full",
+  "ending"
+];
+var metricTransformSchema = external_exports.object({
+  type: external_exports.enum(["derive-month", "aggregate", "sort", "limit", "filter"]),
+  field: external_exports.string().optional(),
+  as: external_exports.string().optional(),
+  groupBy: external_exports.array(external_exports.string()).optional(),
+  measures: external_exports.array(external_exports.object({
+    field: external_exports.string(),
+    op: external_exports.enum(["sum", "avg", "count", "min", "max"]),
+    as: external_exports.string()
+  })).optional(),
+  order: external_exports.enum(["asc", "desc"]).optional(),
+  value: external_exports.unknown().optional()
+});
+var slideMetricSchema = external_exports.object({
+  label: external_exports.string().min(1),
+  value: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+  format: external_exports.string().optional(),
+  data: external_exports.object({
+    transform: external_exports.array(metricTransformSchema).optional()
+  }).optional()
+});
+var slideSpecSchema = external_exports.object({
+  layout: external_exports.enum(SLIDE_LAYOUTS),
+  eyebrow: external_exports.string().optional(),
+  title: external_exports.string().optional(),
+  claim: external_exports.string().optional(),
+  bullets: external_exports.array(external_exports.string()).optional(),
+  callout: external_exports.string().optional(),
+  annotation: external_exports.string().optional(),
+  metrics: external_exports.array(slideMetricSchema).optional(),
+  charts: external_exports.array(chartSpecSchema).optional()
+});
+var deckSpecSchema = external_exports.object({
+  title: external_exports.string().optional(),
+  description: external_exports.string().optional(),
+  theme: external_exports.enum(["default", "editorial", "dark", "minimal"]).optional(),
+  slides: external_exports.array(slideSpecSchema).min(1, "Deck must have at least one slide")
+});
+
+// src/deck-validator.ts
+var REQUIRED_ENCODINGS2 = {
+  bar: ["x", "y"],
+  line: ["x", "y"],
+  area: ["x", "y"],
+  pie: ["label", "value"],
+  scatter: ["x", "y"],
+  histogram: ["x"],
+  heatmap: ["x", "y", "value"],
+  table: [],
+  bigvalue: ["value"]
+};
+function parseDeckSpec(spec) {
+  const parsed = deckSpecSchema.safeParse(spec);
+  if (!parsed.success) {
+    const errors = formatDeckSpecIssues(parsed.error);
+    return agentError("INVALID_DECK_SPEC", errors[0]?.message ?? "DeckSpec is invalid.", { errors });
+  }
+  const semanticErrors = validateDeckSpecSemantics(parsed.data);
+  if (semanticErrors.length > 0) {
+    return agentError("INVALID_DECK_SPEC", semanticErrors[0].message, { errors: semanticErrors });
+  }
+  return ok(parsed.data);
+}
+function validateDeckSpecSemantics(spec) {
+  const errors = [];
+  spec.slides.forEach((slide, index) => {
+    if (["text-chart", "metrics-chart", "chart-full"].includes(slide.layout) && !slide.charts?.length) {
+      const path = `slides[${index}].charts`;
+      errors.push({
+        path,
+        message: `${path}: Layout '${slide.layout}' requires at least one chart.`,
+        hint: hintForIssue(path, "requires at least one chart")
+      });
+    }
+    if (slide.layout === "metrics-chart" && !slide.metrics?.length) {
+      const path = `slides[${index}].metrics`;
+      errors.push({
+        path,
+        message: `${path}: Layout 'metrics-chart' requires at least one metric.`,
+        hint: hintForIssue(path, "requires at least one metric")
+      });
+    }
+    if ((slide.metrics?.length ?? 0) > 4) {
+      const path = `slides[${index}].metrics`;
+      errors.push({
+        path,
+        message: `${path}: A slide can include at most 4 metrics.`,
+        hint: hintForIssue(path, "at most 4 metrics")
+      });
+    }
+    if (slide.layout === "table-full" && slide.charts?.[0] && slide.charts[0].type !== "table") {
+      const path = `slides[${index}].charts[0].type`;
+      errors.push({
+        path,
+        message: `${path}: Layout 'table-full' only accepts a table chart.`,
+        hint: hintForIssue(path, "only accepts a table chart")
+      });
+    }
+  });
+  return errors;
+}
+function validateDeckFields(spec, profile) {
+  const sourceFields = new Set(profile.columns.map((column) => column.name));
+  for (let slideIndex = 0; slideIndex < spec.slides.length; slideIndex += 1) {
+    const slide = spec.slides[slideIndex];
+    for (let chartIndex = 0; chartIndex < (slide.charts ?? []).length; chartIndex += 1) {
+      const result = validateChartFields(slide.charts[chartIndex], sourceFields, `slides[${slideIndex}].charts[${chartIndex}]`);
+      if (isAgentError(result)) return result;
+    }
+    for (let metricIndex = 0; metricIndex < (slide.metrics ?? []).length; metricIndex += 1) {
+      const metric = slide.metrics[metricIndex];
+      const result = validateMetricFields(metric, sourceFields, `slides[${slideIndex}].metrics[${metricIndex}]`);
+      if (isAgentError(result)) return result;
+    }
+  }
+  return ok(spec);
+}
+function formatDeckSpecIssues(error51) {
+  return error51.issues.map((issue2) => {
+    const path = issue2.path.length ? formatPath(issue2.path) : "deck";
+    return {
+      path,
+      message: `${path}: ${issue2.message}`,
+      hint: hintForIssue(path, issue2.message)
+    };
+  });
+}
+function validateChartFields(chart, sourceFields, path) {
+  if (!MVP_CHART_TYPES.includes(chart.type)) {
+    return deckFieldError(path, chart.type, `Chart type '${chart.type}' is not supported.`);
+  }
+  for (const encoding of REQUIRED_ENCODINGS2[chart.type] ?? []) {
+    if (!chart.encoding[encoding]?.field) {
+      return deckFieldError(`${path}.encoding.${encoding}`, encoding, `Chart type '${chart.type}' requires encoding '${encoding}'.`);
+    }
+  }
+  const available = applyTransforms(chart.data?.transform ?? [], sourceFields, path);
+  if (isAgentError(available)) return available;
+  for (const [encoding, spec] of Object.entries(chart.encoding)) {
+    if (spec?.field && !available.value.has(spec.field)) {
+      return deckFieldError(`${path}.encoding.${encoding}.field`, spec.field, `Field '${spec.field}' is not available for this chart encoding.`);
+    }
+  }
+  return ok(chart);
+}
+function validateMetricFields(metric, sourceFields, path) {
+  const available = applyTransforms(metric.data?.transform ?? [], sourceFields, path);
+  if (isAgentError(available)) return available;
+  return ok(metric);
+}
+function applyTransforms(transforms, sourceFields, path) {
+  let available = new Set(sourceFields);
+  for (let index = 0; index < transforms.length; index += 1) {
+    const transform2 = transforms[index];
+    const transformPath = `${path}.data.transform[${index}]`;
+    if (transform2.field && !available.has(transform2.field)) {
+      return deckFieldError(`${transformPath}.field`, transform2.field, `Field '${transform2.field}' was not found before transform '${transform2.type}'.`);
+    }
+    for (const field of transform2.groupBy ?? []) {
+      if (!available.has(field)) {
+        return deckFieldError(`${transformPath}.groupBy`, field, `Group field '${field}' was not found before transform '${transform2.type}'.`);
+      }
+    }
+    for (const measure of transform2.measures ?? []) {
+      if (!available.has(measure.field)) {
+        return deckFieldError(`${transformPath}.measures.${measure.as}`, measure.field, `Measure field '${measure.field}' was not found before transform '${transform2.type}'.`);
+      }
+    }
+    available = nextAvailableFields(available, transform2);
+  }
+  return ok(available);
+}
+function nextAvailableFields(current, transform2) {
+  if (transform2.type === "derive-month" && transform2.as) {
+    return /* @__PURE__ */ new Set([...current, transform2.as]);
+  }
+  if (transform2.type === "aggregate") {
+    return /* @__PURE__ */ new Set([
+      ...transform2.groupBy ?? [],
+      ...(transform2.measures ?? []).map((measure) => measure.as)
+    ]);
+  }
+  return current;
+}
+function deckFieldError(path, field, message) {
+  return agentError("DECK_FIELD_NOT_FOUND", message, {
+    path,
+    field,
+    hint: `Check ${path} and use a field from the input data or a field created by an earlier transform.`
+  });
+}
+function formatPath(path) {
+  return path.reduce((result, item) => {
+    if (typeof item === "number") return `${result}[${item}]`;
+    const segment = String(item);
+    return result ? `${result}.${segment}` : segment;
+  }, "");
+}
+function hintForIssue(path, message) {
+  if (message.includes("requires at least one chart")) return `Add a chart under ${path}.`;
+  if (message.includes("requires at least one metric")) return `Add one to four metrics under ${path}.`;
+  if (message.includes("at most 4 metrics")) return `Reduce ${path} to four metrics or split them across multiple slides.`;
+  if (message.includes("only accepts a table chart")) return `Change ${path} to 'table' or use a chart-focused layout.`;
+  return `Check ${path} in the DeckSpec.`;
+}
+
 // src/cli.ts
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["h", "help", "summary", "reliable-only"]);
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.command === "--help" || args.command === "-h" || args.command === "help" || !args.command) {
+    printHelp();
+    return;
+  }
+  if (args.flags["help"] === true || args.flags["h"] === true) {
+    printHelp(args.command);
+    return;
+  }
   try {
     if (args.command === "profile") {
       printJson(runProfile(args));
@@ -56672,8 +57010,12 @@ async function main() {
       printJson(runDeck(args));
       return;
     }
+    if (args.command === "query") {
+      printJson(runQuery(args));
+      return;
+    }
     printJson(agentError("UNKNOWN_COMMAND", `Unknown command: ${args.command ?? "(none)"}`, {
-      commands: ["profile", "validate", "catalog", "render", "deck"]
+      commands: ["profile", "validate", "catalog", "render", "deck", "query"]
     }));
     process.exitCode = 1;
   } catch (error51) {
@@ -56683,13 +57025,19 @@ async function main() {
 }
 function runProfile(args) {
   const file2 = args.positional[0];
-  if (!file2) return fail(agentError("MISSING_INPUT", "Usage: miao-viz profile <file> [--sheet <name>] [--limit <rows>]"));
+  if (!file2) return fail(agentError("MISSING_INPUT", "Usage: miao-viz profile <file> [--summary] [--columns col1,col2] [--reliable-only] [--sheet <name>] [--limit <rows>]"));
   const dataset = loadDataset(file2, {
     sheet: stringFlag(args, "sheet"),
     limit: numberFlag(args, "limit")
   });
   if (isAgentError(dataset)) return fail(dataset);
-  return { ok: true, value: profileDataset(dataset.value) };
+  if (args.flags["summary"] === true) {
+    return { ok: true, value: profileSummary(dataset.value) };
+  }
+  const columnsFlag = stringFlag(args, "columns");
+  const columns = columnsFlag ? columnsFlag.split(",").map((c) => c.trim()).filter(Boolean) : void 0;
+  const reliableOnly = args.flags["reliable-only"] === true;
+  return { ok: true, value: profileDataset(dataset.value, { columns, reliableOnly }) };
 }
 function runValidate(args) {
   const specPath = requiredFlag(args, "spec");
@@ -56759,14 +57107,30 @@ function runDeck(args) {
   });
   if (isAgentError(dataset)) return fail(dataset);
   const raw = readSpec(specPath);
-  const parsed = deckSpecSchema.safeParse(raw);
-  if (!parsed.success) {
-    return fail(agentError("INVALID_DECK_SPEC", parsed.error.issues.map((i) => i.message).join("; ")));
-  }
+  const parsed = parseDeckSpec(raw);
+  if (isAgentError(parsed)) return fail(parsed);
+  const profile = profileDataset(dataset.value);
+  const validation = validateDeckFields(parsed.value, profile);
+  if (isAgentError(validation)) return fail(validation);
   const themeFlag = stringFlag(args, "theme");
-  const html = renderDeckHtml(parsed.data, dataset.value.rows, themeFlag);
+  const html = renderDeckHtml(validation.value, dataset.value.rows, themeFlag);
   writeOutput(output, html);
-  return { ok: true, value: { output, slides: parsed.data.slides.length } };
+  return { ok: true, value: { output, slides: validation.value.slides.length } };
+}
+function runQuery(args) {
+  const file2 = args.positional[0];
+  if (!file2) return fail(agentError("MISSING_INPUT", 'Usage: miao-viz query <file> [--groupby cols] [--measure "fn(col) as alias"] [--filter col=val] [--orderby "col desc"] [--limit n]'));
+  const dataset = loadDataset(file2, { sheet: stringFlag(args, "sheet") });
+  if (isAgentError(dataset)) return fail(dataset);
+  const result = queryDataset(dataset.value.rows, {
+    groupby: stringFlag(args, "groupby"),
+    measure: stringFlag(args, "measure"),
+    filter: stringFlag(args, "filter"),
+    orderby: stringFlag(args, "orderby"),
+    limit: numberFlag(args, "limit")
+  });
+  if (isAgentError(result)) return fail(result);
+  return { ok: true, value: result };
 }
 function normalizeSpec(spec) {
   const parsed = singleOrReportSpecSchema.safeParse(spec);
@@ -56805,6 +57169,10 @@ function parseArgs(argv) {
     const value = rest[i];
     if (value.startsWith("--")) {
       const key = value.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) {
+        flags[key] = true;
+        continue;
+      }
       const next = rest[i + 1];
       if (!next || next.startsWith("--")) {
         flags[key] = true;
@@ -56850,6 +57218,101 @@ function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
 }
+var COMMAND_HELP = {
+  profile: `Usage: miao-viz profile <file> [options]
+
+Profile a data file and output column statistics.
+
+Arguments:
+  file                  Path to CSV, Excel (.xlsx/.xls), or JSON file
+
+Options:
+  --summary             Return only file, row count, and column names+types (~200 tokens)
+  --columns col1,col2   Deep-profile only the specified columns (comma-separated)
+  --reliable-only       Suppress statistics where sample size is too small to be reliable
+  --sheet <name>        Sheet name (Excel only)
+  --limit <n>           Max rows to read
+
+Reliability thresholds:
+  skewness              rows >= 30
+  correlation           n  >= 10 (paired non-null values)
+  outlierCount          rows >= 20
+  histogram             rows >= 20
+`,
+  validate: `Usage: miao-viz validate --spec <file> --profile <file>
+
+Validate a vizspec against a data profile.
+
+Options:
+  --spec <file>     Path to vizspec YAML/JSON
+  --profile <file>  Path to profile JSON (output of "profile")
+`,
+  catalog: `Usage: miao-viz catalog
+
+List all available chart types and their required fields.
+`,
+  render: `Usage: miao-viz render --input <file> --spec <file> --output <file> [options]
+
+Render a vizspec to HTML or SVG.
+
+Options:
+  --input <file>    Path to data file
+  --spec <file>     Path to vizspec YAML/JSON
+  --output <file>   Output file path
+  --format <fmt>    Output format: html, svg (default: html)
+  --theme <name>    Theme: default, editorial, dark, minimal
+  --sheet <name>    Sheet name (Excel only)
+  --limit <n>       Max rows to read
+`,
+  deck: `Usage: miao-viz deck --input <file> --spec <file> --output <file> [options]
+
+Render a deck spec to HTML slides.
+
+Options:
+  --input <file>    Path to data file
+  --spec <file>     Path to deck spec YAML/JSON
+  --output <file>   Output file path
+  --theme <name>    Theme: default, editorial, dark, minimal
+  --sheet <name>    Sheet name (Excel only)
+  --limit <n>       Max rows to read
+`,
+  query: `Usage: miao-viz query <file> [options]
+
+Run an aggregation query against a data file and return JSON results.
+Use this to get real computed values before writing chart insights.
+
+Supported aggregate functions: sum, count, avg, min, max
+
+Options:
+  --groupby <cols>      Comma-separated column names to group by
+  --measure <exprs>     Aggregate expressions, e.g. "sum(sales) as total, count(*) as cnt"
+  --filter <col=val>    Simple equality filter (one condition only)
+  --orderby <col dir>   Sort column and direction, e.g. "total_sales desc"
+  --limit <n>           Max rows to return
+  --sheet <name>        Sheet name (Excel only)
+`
+};
+function printHelp(command) {
+  if (command && COMMAND_HELP[command]) {
+    process.stdout.write(COMMAND_HELP[command]);
+    return;
+  }
+  process.stdout.write(`miao-viz \u2014 local data visualization CLI
+
+Usage:
+  miao-viz <command> [options]
+
+Commands:
+  profile   Profile a data file (CSV, Excel, JSON)
+  query     Run an aggregation query to get real computed values
+  validate  Validate a vizspec against a data profile
+  catalog   List all available chart types
+  render    Render a vizspec to HTML or SVG
+  deck      Render a deck spec to HTML slides
+
+Run "miao-viz <command> --help" for command-specific options.
+`);
+}
 main();
 /*! Bundled license information:
 

package/dist/types.ts

@@ -90,9 +90,12 @@ export interface ColumnProfile {
   p75?: number
   stddev?: number
   skewness?: number
+  skewnessReliable?: boolean      // rows >= 30
   coefficientOfVariation?: number
   outlierCount?: number
+  outlierReliable?: boolean       // rows >= 20
   histogram?: HistogramBucket[]
+  histogramReliable?: boolean     // rows >= 20
   // string
   topValue?: unknown
   topSharePct?: number
@@ -131,7 +134,7 @@ export interface DataProfile {
   columns: ColumnProfile[]
   sheet?: string
   quality?: DataQualityProfile
-  correlations?: Array<{ a: string; b: string; r: number }>
+  correlations?: Array<{ a: string; b: string; r: number; n: number; reliable: boolean }>
   hints?: ProfileHint[]
   insights?: ProfileInsight[]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miao-vision/cli",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "description": "Miao Vision local data visualization CLI for agent workflows",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/guming/miao-vision.git",
+    "url": "https://github.com/miaoshou-dev/miao-vision.git",
     "directory": "packages/miao-viz-cli"
   },
   "publishConfig": {