superlore-cli 0.1.2 → 0.2.0

package/README.md

@@ -40,11 +40,17 @@ curl -fsSL https://superlore.vercel.app/install.sh | sh    # or: npm i -g superl
 ```
 
 ```bash
-superlore init my-kb   # scaffold — 2 questions → superlore.json + starter pages
+superlore init my-kb   # scaffold — 2 questions → superlore.json + starter pages, then sets up your editor
+superlore connect      # detect VS Code / Cursor / Windsurf and install the live-preview extension
 superlore dev          # live preview at localhost:3000
 superlore build        # production build, deploy anywhere
 ```
 
+`init` ends by offering to run `connect` for you, so one command takes you from nothing to a
+scaffolded KB with the editor extension installed — then it points you at wiring the MCP to your
+agent. `connect` detects each editor via its CLI or standard install path (macOS / Linux / Windows)
+and is safe to re-run.
+
 `superlore deploy` is reserved for managed **superlore Cloud**
 ([waitlisted](https://superlore.vercel.app/cloud)) — self-host free with `superlore build`.
 

package/dist/index.d.ts

@@ -83,7 +83,7 @@ declare function serializeSuperloreJson(config: SuperloreJson): string;
 declare function resolveMcpPath(config: SuperloreJson): string | undefined;
 
 /** The CLI version, kept in sync with package.json at build time. */
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.2.0";
 /** Build the argument parser. Exported for tests; `run()` wires it to argv. */
 declare function buildCli(argv?: readonly string[]): cac.CAC;
 /** Parse argv and dispatch. Reports unknown commands and unexpected errors cleanly. */

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { fileURLToPath as fileURLToPath2 } from "url";
-import process2 from "process";
+import process3 from "process";
 import { cac } from "cac";
 
 // src/lib/log.ts
@@ -253,6 +253,194 @@ async function buildCommand() {
   process.exit(code);
 }
 
+// src/lib/editors.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync2, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { join as join2 } from "path";
+import process2 from "process";
+var EXTENSION_ID = "superlore.superlore-preview";
+var DEFAULT_VSIX_URL = "https://superlore.vercel.app/superlore-preview.vsix";
+async function downloadVsix(url = DEFAULT_VSIX_URL) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`couldn't fetch the extension (${res.status} ${res.statusText})`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const path = join2(tmpdir(), "superlore-preview.vsix");
+  writeFileSync(path, bytes);
+  return path;
+}
+var EDITORS = [
+  { id: "vscode", label: "VS Code", bin: "code" },
+  { id: "cursor", label: "Cursor", bin: "cursor" },
+  { id: "windsurf", label: "Windsurf", bin: "windsurf" }
+];
+function onPath(bin) {
+  const probe = process2.platform === "win32" ? "where" : "which";
+  try {
+    execFileSync(probe, [bin], { stdio: "ignore", shell: process2.platform === "win32" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function fallbackPaths(editor) {
+  const home = homedir();
+  if (process2.platform === "darwin") {
+    const app = {
+      vscode: "Visual Studio Code.app",
+      cursor: "Cursor.app",
+      windsurf: "Windsurf.app"
+    };
+    const rel = `Contents/Resources/app/bin/${editor.bin}`;
+    return [
+      join2("/Applications", app[editor.id], rel),
+      join2(home, "Applications", app[editor.id], rel)
+    ];
+  }
+  if (process2.platform === "win32") {
+    const local = process2.env.LOCALAPPDATA ?? join2(home, "AppData", "Local");
+    const programs = join2(local, "Programs");
+    const dir = {
+      vscode: "Microsoft VS Code",
+      cursor: "cursor",
+      windsurf: "Windsurf"
+    };
+    const exe = `bin\\${editor.bin}.cmd`;
+    return [
+      join2(programs, dir[editor.id], exe),
+      join2(process2.env.ProgramFiles ?? "C:\\Program Files", dir[editor.id], exe)
+    ];
+  }
+  return [
+    join2("/usr/share", editor.bin, "bin", editor.bin),
+    join2("/usr/bin", editor.bin),
+    join2("/snap/bin", editor.bin),
+    join2(home, ".local", "bin", editor.bin)
+  ];
+}
+function resolveEditorCommand(editor) {
+  if (onPath(editor.bin)) return editor.bin;
+  for (const candidate of fallbackPaths(editor)) {
+    if (existsSync2(candidate)) return candidate;
+  }
+  return void 0;
+}
+function detectEditors() {
+  const found = [];
+  for (const editor of EDITORS) {
+    const command = resolveEditorCommand(editor);
+    if (command) found.push({ ...editor, command });
+  }
+  return found;
+}
+var execRunner = (command, args) => execFileSync(command, [...args], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+  // Editor CLIs on Windows are .cmd shims; a shell is needed to invoke them.
+  shell: process2.platform === "win32",
+  timeout: 6e4
+}).trim();
+function classifyInstallOutput(editor, output) {
+  return /already installed/i.test(output) ? { editor, status: "already-installed" } : { editor, status: "installed" };
+}
+function installInto(editor, options = {}) {
+  const run2 = options.run ?? execRunner;
+  const target = options.vsix ?? EXTENSION_ID;
+  try {
+    const output = run2(editor.command, ["--install-extension", target, "--force"]);
+    return classifyInstallOutput(editor, output);
+  } catch (error) {
+    return { editor, status: "failed", error: failureReason(error) };
+  }
+}
+function failureReason(error) {
+  if (error instanceof Error) {
+    const stderr = error.stderr;
+    const text2 = typeof stderr === "string" ? stderr : Buffer.isBuffer(stderr) ? stderr.toString() : "";
+    const lines = text2.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !/^\(node:/.test(l) && !/^\(Use /.test(l));
+    const meaningful = lines.find((l) => /(not found|error|fail|denied)/i.test(l)) ?? lines[0];
+    if (meaningful) return meaningful;
+    return error.message.replace(/^Command failed:.*/s, "the editor CLI returned an error").trim();
+  }
+  return String(error);
+}
+
+// src/commands/connect.ts
+async function connectCommand(flags = {}) {
+  log.blank();
+  log.info(`${accent("superlore connect")} ${dim("\u2014 set up your editor")}`);
+  log.blank();
+  const detected = detectEditors();
+  if (detected.length === 0) {
+    log.warn("No supported editor detected (looked for VS Code, Cursor, and Windsurf).");
+    log.blank();
+    log.info(`${dim("Install one, then re-run")} ${cyan("superlore connect")}${dim(".")}`);
+    log.info(
+      `${dim("If an editor is installed but its CLI isn't on PATH, open it and run")} ${cyan(`"Shell Command: Install '<editor>' command in PATH"`)}${dim(".")}`
+    );
+    printMcpNextStep();
+    process.exit(0);
+  }
+  const labels = detected.map((e) => bold(e.label)).join(", ");
+  log.step(`Found ${labels}. Installing the superlore Preview extension\u2026`);
+  log.blank();
+  let vsix;
+  try {
+    vsix = flags.vsix ?? await downloadVsix();
+  } catch (error) {
+    log.error(
+      `Couldn't fetch the extension: ${error instanceof Error ? error.message : String(error)}`
+    );
+    printManualInstall();
+    process.exit(flags.optional ? 0 : 1);
+  }
+  const results = detected.map((editor) => report(installInto(editor, { vsix })));
+  log.blank();
+  const failed = results.filter((r) => r.status === "failed");
+  if (failed.length > 0 && failed.length === results.length) {
+    log.error("Couldn't install the extension into any editor. See the errors above.");
+    printManualInstall();
+    process.exit(flags.optional ? 0 : 1);
+  }
+  log.success(
+    `superlore Preview is ready. Open a ${cyan(".mdx")} file and run ${cyan("superlore: Open Preview")} ${dim("(Cmd/Ctrl+K V)")}.`
+  );
+  printMcpNextStep();
+}
+function report(result) {
+  switch (result.status) {
+    case "installed":
+      log.success(`${bold(result.editor.label)} ${dim("\u2014 extension installed.")}`);
+      break;
+    case "already-installed":
+      log.info(`${accent("\u203A")} ${bold(result.editor.label)} ${dim("\u2014 already installed, up to date.")}`);
+      break;
+    case "failed":
+      log.error(`${bold(result.editor.label)} ${dim("\u2014 install failed:")} ${result.error}`);
+      break;
+  }
+  return result;
+}
+function printManualInstall() {
+  log.blank();
+  log.info(
+    `${dim("Install it by hand: download")} ${cyan("superlore.vercel.app/superlore-preview.vsix")}${dim(",")}`
+  );
+  log.info(
+    `${dim("then run")} ${cyan('"Extensions: Install from VSIX\u2026"')} ${dim("in your editor (or")} ${cyan("code --install-extension <file>.vsix")}${dim(").")}`
+  );
+}
+function printMcpNextStep() {
+  log.blank();
+  log.info(bold("Next: connect the MCP"));
+  log.info(
+    `  ${dim("Let your agent read the same corpus. Ask Claude")} ${cyan('"connect my superlore MCP"')}${dim(",")}`
+  );
+  log.info(
+    `  ${dim("or register it yourself:")} ${cyan("claude mcp add --transport http -s user superlore <url>/api/mcp")}`
+  );
+}
+
 // src/commands/deploy.ts
 import { spawn as spawn2 } from "child_process";
 
@@ -332,34 +520,34 @@ async function devCommand(flags) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { basename, resolve as resolve3 } from "path";
 import { cancel, confirm, intro, isCancel, outro, select, text } from "@clack/prompts";
 
 // src/lib/scaffold.ts
-import { cpSync, existsSync as existsSync2, mkdirSync, readdirSync, writeFileSync } from "fs";
+import { cpSync, existsSync as existsSync3, mkdirSync, readdirSync, writeFileSync as writeFileSync2 } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "path";
 var here = dirname2(fileURLToPath(import.meta.url));
 function findStarterTemplate() {
   let dir = here;
   for (; ; ) {
-    const candidate = join2(dir, "templates", "starter");
-    if (existsSync2(candidate)) return candidate;
-    const bundled = join2(dir, "template");
-    if (existsSync2(bundled)) return bundled;
+    const candidate = join3(dir, "templates", "starter");
+    if (existsSync3(candidate)) return candidate;
+    const bundled = join3(dir, "template");
+    if (existsSync3(bundled)) return bundled;
     const parent = dirname2(dir);
     if (parent === dir) return void 0;
     dir = parent;
   }
 }
 function isUsableTemplate(dir) {
-  if (!existsSync2(dir)) return false;
+  if (!existsSync3(dir)) return false;
   const entries = readdirSync(dir).filter((name) => name !== "README.md" && !name.startsWith("."));
   return entries.length > 0;
 }
 function isEmptyDir(dir) {
-  if (!existsSync2(dir)) return true;
+  if (!existsSync3(dir)) return true;
   return readdirSync(dir).filter((n) => !n.startsWith(".")).length === 0;
 }
 function scaffold(options) {
@@ -374,7 +562,7 @@ function scaffold(options) {
     writeSkeleton(root, options.config);
     source = "skeleton";
   }
-  writeFileSync(join2(root, "superlore.json"), serializeSuperloreJson(options.config), "utf8");
+  writeFileSync2(join3(root, "superlore.json"), serializeSuperloreJson(options.config), "utf8");
   return { root, source };
 }
 function writeSkeleton(root, config) {
@@ -382,9 +570,9 @@ function writeSkeleton(root, config) {
   const mcpEnabled = config.mcp?.enabled ?? true;
   const slug = config.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "superlore-kb";
   const write = (rel, body) => {
-    const file = join2(root, rel);
+    const file = join3(root, rel);
     mkdirSync(dirname2(file), { recursive: true });
-    writeFileSync(file, body, "utf8");
+    writeFileSync2(file, body, "utf8");
   };
   write(
     "package.json",
@@ -792,7 +980,7 @@ ${result.issues.map((i) => `  - ${i.path} ${i.message}`).join("\n")}`
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const targetName = dir ?? (slug || "superlore-kb");
   const targetDir = resolve3(process.cwd(), targetName);
-  if (existsSync3(targetDir) && !isEmptyDir(targetDir)) {
+  if (existsSync4(targetDir) && !isEmptyDir(targetDir)) {
     if (interactive) {
       const proceed = await confirm({
         message: `${cyan(targetDir)} is not empty. Scaffold into it anyway?`,
@@ -812,6 +1000,33 @@ ${result.issues.map((i) => `  - ${i.path} ${i.message}`).join("\n")}`
     );
   }
   printNextSteps(root, config);
+  await maybeConnectEditor(flags, interactive);
+}
+async function maybeConnectEditor(flags, interactive) {
+  if (flags.connect === false) return;
+  const editors = detectEditors();
+  if (editors.length === 0) {
+    log.blank();
+    log.info(`${dim("Editor preview:")} install VS Code, Cursor, or Windsurf, then ${cyan("superlore connect")}.`);
+    return;
+  }
+  const names = editors.map((e) => e.label).join(", ");
+  if (flags.connect !== true && !interactive) {
+    log.blank();
+    log.info(`${dim(`Detected ${names}.`)} Run ${cyan("superlore connect")} to install the live-preview extension.`);
+    return;
+  }
+  if (flags.connect !== true) {
+    const proceed = await confirm({
+      message: `Install the superlore Preview extension into ${names}?`,
+      initialValue: true
+    });
+    if (isCancel(proceed) || !proceed) {
+      log.info(`${dim("Skipped \u2014 run")} ${cyan("superlore connect")} ${dim("any time.")}`);
+      return;
+    }
+  }
+  await connectCommand({ optional: true });
 }
 function printNextSteps(root, config) {
   const rel = basename(root);
@@ -829,14 +1044,17 @@ function printNextSteps(root, config) {
 }
 
 // src/index.ts
-var VERSION = "0.1.2";
-function buildCli(argv = process2.argv) {
+var VERSION = "0.2.0";
+function buildCli(argv = process3.argv) {
   const cli = cac("superlore");
-  cli.command("init [dir]", "Scaffold a new superlore knowledge base").option("--name <name>", "KB name").option("--type <type>", "KB type: company-kb | product-docs").option("--auth", "Enable the Google SSO auth gate").option("--no-auth", "Disable the auth gate").option("--allowed-domain <domain>", "Restrict SSO to one email domain (implies --auth)").option("--accent <color>", "Brand accent colour (any CSS colour)").option("--no-mcp", "Disable the MCP endpoint (on by default)").option("-y, --yes", "Skip prompts; use flags + defaults").example("superlore init my-kb --type product-docs").example("superlore init acme --type company-kb --auth --allowed-domain acme.com").action(
+  cli.command("init [dir]", "Scaffold a new superlore knowledge base").option("--name <name>", "KB name").option("--type <type>", "KB type: company-kb | product-docs").option("--auth", "Enable the Google SSO auth gate").option("--no-auth", "Disable the auth gate").option("--allowed-domain <domain>", "Restrict SSO to one email domain (implies --auth)").option("--accent <color>", "Brand accent colour (any CSS colour)").option("--no-mcp", "Disable the MCP endpoint (on by default)").option("--connect", "Install the editor extension after scaffolding (skip the prompt)").option("--no-connect", "Don't set up the editor extension").option("-y, --yes", "Skip prompts; use flags + defaults").example("superlore init my-kb --type product-docs").example("superlore init acme --type company-kb --auth --allowed-domain acme.com").action(
     async (dir, flags) => {
       const authExplicit = argv.includes("--auth");
       const noAuthExplicit = argv.includes("--no-auth");
       const auth = authExplicit ? true : noAuthExplicit ? false : void 0;
+      const connectExplicit = argv.includes("--connect");
+      const noConnectExplicit = argv.includes("--no-connect");
+      const connect = connectExplicit ? true : noConnectExplicit ? false : void 0;
       await initCommand(dir, {
         name: flags.name,
         type: flags.type,
@@ -845,6 +1063,7 @@ function buildCli(argv = process2.argv) {
         accent: flags.accent,
         // `--no-mcp` flips this to false; default true is the intended behaviour.
         mcp: flags.mcp,
+        connect,
         yes: flags.yes
       });
     }
@@ -855,6 +1074,9 @@ function buildCli(argv = process2.argv) {
   cli.command("build", "Production build of the KB").action(async () => {
     await buildCommand();
   });
+  cli.command("connect", "Install the superlore editor extension (VS Code \xB7 Cursor \xB7 Windsurf)").option("--vsix <path>", "Install from a local .vsix instead of the Marketplace").example("superlore connect").action(async (flags) => {
+    await connectCommand({ vsix: flags.vsix });
+  });
   cli.command("deploy", "Managed deploy (superlore Cloud) \u2014 private beta, joins the waitlist").option("--open", "Open the waitlist URL in your browser").action(async (flags) => {
     await deployCommand({ open: flags.open });
   });
@@ -862,7 +1084,7 @@ function buildCli(argv = process2.argv) {
   cli.version(VERSION);
   return cli;
 }
-async function run(argv = process2.argv) {
+async function run(argv = process3.argv) {
   const cli = buildCli(argv);
   const tokens = argv.slice(2);
   const hasCommand = tokens.some((t) => !t.startsWith("-"));
@@ -878,10 +1100,10 @@ async function run(argv = process2.argv) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     log.error(message);
-    process2.exit(1);
+    process3.exit(1);
   }
 }
-var isEntrypoint = Boolean(process2.argv[1]) && fileURLToPath2(import.meta.url) === process2.argv[1];
+var isEntrypoint = Boolean(process3.argv[1]) && fileURLToPath2(import.meta.url) === process3.argv[1];
 if (isEntrypoint) {
   void run();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlore-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The superlore CLI — scaffold, run, and build an agent-native knowledge base. One corpus. Humans and agents.",
   "license": "Apache-2.0",
   "author": "Krishnan S G",