@datashow/super-visual-cli 0.1.0-rc.0 → 0.1.0-rc.2

package/bin/supervisual.mjs

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
-import { main } from "../src/main.mjs";
+import { main, stopActiveProgress } from "../src/main.mjs";
 
 main().catch((error) => {
+  stopActiveProgress();
   const json = process.argv.includes("--json");
   const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`${json ? JSON.stringify({ ok: false, error: message }) : `supervisual: ${message}`}\n`);
+  const summary = error?.summary ?? "Super Visual could not complete the command.";
+  const guidance = error?.guidance;
+  if (json) {
+    process.stderr.write(`${JSON.stringify({ ok: false, message: summary, ...(guidance ? { guidance } : {}), error: message })}\n`);
+  } else {
+    process.stderr.write(`\n${summary}\n${guidance ? `${guidance}\n` : ""}\nTechnical details: ${message}\n`);
+  }
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datashow/super-visual-cli",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.2",
   "description": "CLI for validating, compiling, packaging, verifying, and deploying Super Visual projects.",
   "type": "module",
   "bin": {
@@ -25,10 +25,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@datashow/super-visual-adapter-claude-dashboard": "0.1.0-rc.0",
-    "@datashow/super-visual-compiler": "0.1.0-rc.0",
-    "@datashow/super-visual-contracts": "0.1.0-rc.0",
-    "@datashow/super-visual-fabric": "0.1.0-rc.0",
+    "@datashow/super-visual-adapter-claude-dashboard": "0.1.0-rc.2",
+    "@datashow/super-visual-compiler": "0.1.0-rc.2",
+    "@datashow/super-visual-contracts": "0.1.0-rc.2",
+    "@datashow/super-visual-fabric": "0.1.0-rc.2",
     "@fontsource/source-serif-4": "5.3.1",
     "@nivo/bar": "0.99.0",
     "@nivo/line": "0.99.0",

package/src/main.mjs

@@ -15,7 +15,29 @@ import { resolveProjectTarget, targetUpdate, writeProjectTarget } from "./projec
 import { runSemanticPreviewTest, startSemanticPreview } from "./semantic-preview.mjs";
 
 const run = promisify(execFile);
-const VERSION = "0.1.0-rc.0";
+const VERSION = "0.1.0-rc.2";
+const FABRIC_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SPINNER_FRAMES = ["|", "/", "-", "\\"];
+let activeProgress = null;
+
+export class CliUserError extends Error {
+  constructor(message, { summary, guidance } = {}) {
+    super(message);
+    this.name = "CliUserError";
+    this.summary = summary;
+    this.guidance = guidance;
+  }
+}
+
+export function validateFabricId(value, optionName) {
+  if (value === undefined) return;
+  if (FABRIC_ID_PATTERN.test(value)) return;
+  const target = optionName === "--workspace-id" ? "workspace" : "semantic model";
+  throw new CliUserError(`${optionName} must be a 36-character GUID in 8-4-4-4-12 format; received "${value}" (${String(value).length} characters).`, {
+    summary: `Super Visual could not initialize the project because the ${target} ID is not valid.`,
+    guidance: `Copy the complete ${target} ID from Fabric and run the command again.`,
+  });
+}
 
 function projectFile(input = ".") {
   const resolved = path.resolve(input);
@@ -26,6 +48,58 @@ function output(value, json) {
   process.stdout.write(`${json ? JSON.stringify(value) : typeof value === "string" ? value : JSON.stringify(value, null, 2)}\n`);
 }
 
+export function stopActiveProgress() {
+  if (!activeProgress) return;
+  clearInterval(activeProgress.timer);
+  process.stdout.write(`\r${" ".repeat(activeProgress.width)}\r`);
+  activeProgress = null;
+}
+
+function writeInitProgress(event) {
+  if (event.status === "running" && process.stdout.isTTY) {
+    stopActiveProgress();
+    let frame = 0;
+    const render = () => {
+      const line = `${SPINNER_FRAMES[frame % SPINNER_FRAMES.length]} ${event.message}`;
+      process.stdout.write(`\r${line}`);
+      activeProgress.width = Math.max(activeProgress.width, line.length);
+      frame += 1;
+    };
+    activeProgress = { timer: null, width: event.message.length + 2 };
+    render();
+    activeProgress.timer = setInterval(render, 80);
+    return;
+  }
+  stopActiveProgress();
+  const marker = event.status === "passed" ? "✓" : "…";
+  process.stdout.write(`${marker} ${event.message}\n`);
+}
+
+function semanticInventory(model) {
+  const tables = model.tables ?? [];
+  return {
+    tables: tables.length,
+    columns: tables.reduce((total, table) => total + (table.columns?.length ?? 0), 0),
+    measures: tables.reduce((total, table) => total + (table.measures?.length ?? 0), 0),
+    hierarchies: tables.reduce((total, table) => total + (table.hierarchies?.length ?? 0), 0),
+    hierarchyLevels: tables.reduce((total, table) => total + (table.hierarchies ?? []).reduce((levels, hierarchy) => levels + (hierarchy.levels?.length ?? 0), 0), 0),
+    relationships: model.relationships?.length ?? 0,
+    parameters: model.parameters?.length ?? 0,
+  };
+}
+
+function printInitializationResult(result) {
+  process.stdout.write(`\nInitialization complete — ${result.application.title} is ready.\n`);
+  process.stdout.write(`Project: ${result.directory}\n`);
+  process.stdout.write(`Project manifest: ${result.projectFile}\n`);
+  if (result.binding) {
+    if (result.binding.workspace) process.stdout.write(`Workspace: ${result.binding.workspace.name ?? "(name not recorded)"} (${result.binding.workspace.id})\n`);
+    if (result.binding.semanticModel) process.stdout.write(`Semantic model: ${result.binding.semanticModel.name ?? "(name not recorded)"} (${result.binding.semanticModel.id})\n`);
+  }
+  process.stdout.write(`\nInitialization manifest (JSON):\n${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`\nNext:\n${result.next.map((command) => `  ${command}`).join("\n")}\n`);
+}
+
 function jsonEnabled(command) {
   return Boolean(command.optsWithGlobals().json);
 }
@@ -240,18 +314,64 @@ function createProgram() {
     .option("--report-name <name>", "target report name")
     .option("--connection-id <id>", "advanced override for the selected model's Fabric connection")
     .option("--connection-mode <mode>", "advanced Fabric connectivity override", "ShareableCloud")
+    .option("--skip-live-validation", "save the binding without checking the workspace and semantic model")
+    .option("--timeout <seconds>", "Fabric validation timeout", "900")
     .option("--force", "write into an existing empty directory")
     .action(async (directory, options, command) => {
       if ((options.workspaceName || options.semanticModelId || options.reportName || options.connectionId) && !options.workspaceId) throw new Error("--workspace-id is required when saving a Fabric binding");
-      const result = await initializeProject({ directory, template: options.template, name: options.name, title: options.title, app: options.app, force: options.force });
+      validateFabricId(options.workspaceId, "--workspace-id");
+      validateFabricId(options.semanticModelId, "--semantic-model-id");
+      const json = jsonEnabled(command);
+      if (!json) process.stdout.write(`\nSuper Visual init\n\n`);
+      let liveValidation = null;
+      if (options.workspaceId && options.semanticModelId && !options.skipLiveValidation) {
+        if (!json) writeInitProgress({ status: "running", message: "Verifying the Fabric workspace and Power BI semantic model (read-only)" });
+        let inspected;
+        try {
+          const client = new FabricHttpClient({ timeoutSeconds: Number(options.timeout) });
+          inspected = await inspectSemanticModel({ client, workspaceId: options.workspaceId, workspaceName: options.workspaceName, semanticModelId: options.semanticModelId });
+        } catch (error) {
+          throw new CliUserError(error instanceof Error ? error.message : String(error), {
+            summary: "Super Visual could not verify the Fabric workspace and semantic model.",
+            guidance: "Confirm that you are signed in, can access the workspace, and copied both IDs from the same Fabric workspace.",
+          });
+        }
+        liveValidation = {
+          ok: true,
+          status: "passed",
+          scope: "fabric-read-only",
+          workspace: inspected.workspace,
+          semanticModel: { id: inspected.semanticModel.id, displayName: inspected.semanticModel.displayName, format: inspected.semanticModel.format },
+          inventory: semanticInventory(inspected.semanticModel),
+        };
+        if (!json) writeInitProgress({ status: "passed", message: `Verified workspace ${inspected.workspace.displayName} and semantic model ${inspected.semanticModel.displayName}` });
+      } else if (!json && options.skipLiveValidation) {
+        process.stdout.write("! Live Fabric validation skipped by request\n");
+      } else if (!json) {
+        process.stdout.write("• No complete Fabric binding supplied; live validation was not run\n");
+      }
+      const result = await initializeProject({
+        directory,
+        template: options.template,
+        name: options.name,
+        title: options.title,
+        app: options.app,
+        force: options.force,
+        onProgress: json ? null : writeInitProgress,
+      });
       if (options.workspaceId) {
         const saved = await writeProjectTarget(result.directory, targetUpdate({
           ...options,
+          workspaceName: options.workspaceName ?? liveValidation?.workspace.displayName,
+          semanticModelName: liveValidation?.semanticModel.displayName,
           reportName: options.reportName ?? result.application.title,
         }));
         result.binding = { file: saved.file, ...saved.value };
+        if (!json) writeInitProgress({ status: "passed", message: `Saved Fabric binding to ${saved.file}` });
       }
-      output(result, jsonEnabled(command));
+      result.validation = { local: result.validation, live: liveValidation ?? { ok: true, status: "not-run", scope: "fabric-read-only" } };
+      if (json) output(result, true);
+      else printInitializationResult(result);
     });
 
   addJsonOption(program.command("check [project]"))

package/src/project.mjs

@@ -7,6 +7,14 @@ import { inspectClaudeDashboard } from "@datashow/super-visual-adapter-claude-da
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const templatesRoot = path.join(packageRoot, "templates");
+const initializationChecks = [
+  "project-contract",
+  "widget-broker",
+  "page-set-primitives",
+  "report-graph-bindings",
+  "report-source-policy",
+  "semantic-references",
+];
 
 async function exists(file) {
   try { await access(file); return true; } catch { return false; }
@@ -240,9 +248,10 @@ export async function syncProjectSource(projectFile) {
   return { ok: true, synced: true, files: nextFiles.length, bundlePath, pageSetPath };
 }
 
-export async function initializeProject({ directory, template = "blank", name, title, app, force = false }) {
+export async function initializeProject({ directory, template = "blank", name, title, app, force = false, onProgress = null }) {
   if (!supportedTemplates().some((candidate) => candidate.id === template)) throw new Error(`Unknown template ${template}`);
   const target = path.resolve(directory);
+  onProgress?.({ status: "running", step: "scaffold", message: `Creating ${template} project in ${target}` });
   if (await exists(target)) {
     const metadata = await stat(target);
     if (!metadata.isDirectory()) throw new Error(`Target exists and is not a directory: ${target}`);
@@ -261,6 +270,8 @@ export async function initializeProject({ directory, template = "blank", name, t
     VISUAL_NAME: visualName,
     VISUAL_GUID: visualGuid,
   });
+  onProgress?.({ status: "passed", step: "scaffold", message: `Created project files from the ${template} template` });
+  onProgress?.({ status: "passed", step: "identity", message: `Generated unique visual identity ${visualGuid}` });
   if (template === "blank") {
     const entry = blankApplication.replaceAll("{{PROJECT_TITLE}}", projectTitle);
     await writeFile(path.join(target, "source", "reportApplication.tsx"), entry);
@@ -274,7 +285,10 @@ export async function initializeProject({ directory, template = "blank", name, t
     await writeFile(bundlePath, `${JSON.stringify(bundle, null, 2)}\n`);
     await writeFile(path.join(target, "README.md"), blankReadme(projectTitle));
   }
-  if (app) await installApplication(target, app, projectTitle);
+  if (app) {
+    await installApplication(target, app, projectTitle);
+    onProgress?.({ status: "passed", step: "application", message: `Imported React application from ${path.resolve(app)}` });
+  }
   const style = await readFile(path.join(target, "source", "report-design.less"), "utf8");
   const designHash = createHash("sha256").update(style).digest("hex");
   await replaceTemplateTokens(target, { DESIGN_HASH: designHash });
@@ -283,7 +297,11 @@ export async function initializeProject({ directory, template = "blank", name, t
   bundle.designSystem.sha256 = designHash;
   await writeFile(bundlePath, `${JSON.stringify(bundle, null, 2)}\n`);
   await syncProjectSource(path.join(target, "supervisual.yaml"));
+  onProgress?.({ status: "passed", step: "source", message: "Synchronized React source and report-source contract" });
+  onProgress?.({ status: "running", step: "validation", message: "Validating generated contracts, bindings, and source policy" });
   const inspection = await inspectProject(path.join(target, "supervisual.yaml"));
   if (!inspection.ok) throw new Error(`Generated project did not validate:\n- ${inspection.diagnostics.join("\n- ")}`);
-  return { ok: true, directory: target, projectFile: path.join(target, "supervisual.yaml"), template, application: inspection.application, ...(app ? { reactApplication: path.resolve(app) } : {}), next: [`cd ${target}`, "supervisual dev", "supervisual publish"] };
+  const validation = { ok: true, status: "passed", scope: "local", checks: initializationChecks, diagnostics: inspection.diagnostics };
+  onProgress?.({ status: "passed", step: "validation", message: `${initializationChecks.length} local validation checks passed with no diagnostics` });
+  return { ok: true, status: "ready", directory: target, projectFile: path.join(target, "supervisual.yaml"), template, application: inspection.application, validation, ...(app ? { reactApplication: path.resolve(app) } : {}), next: [`cd ${target}`, "supervisual dev --open", "supervisual publish"] };
 }

package/templates/blank/package.json

@@ -10,6 +10,6 @@
     "verify": "supervisual verify ."
   },
   "devDependencies": {
-    "@datashow/super-visual-cli": "0.1.0-rc.0"
+    "@datashow/super-visual-cli": "0.1.0-rc.2"
   }
 }

package/templates/hello-world/package.json

@@ -10,6 +10,6 @@
     "verify": "supervisual verify ."
   },
   "devDependencies": {
-    "@datashow/super-visual-cli": "0.1.0-rc.0"
+    "@datashow/super-visual-cli": "0.1.0-rc.2"
   }
 }