showpane 0.4.4 → 0.4.6

package/bundle/meta/scaffold-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-04-09T13:24:17.013Z",
-  "scaffoldVersion": "0.2.1",
+  "generatedAt": "2026-04-09T14:26:32.270Z",
+  "scaffoldVersion": "0.2.3",
   "files": {
     ".env.example": "0dd692f1c7e6bcabdf5dbdfe9abb73797d79d8e90da150d6098b63ddc695dc29",
     ".gitignore": "998e5f43865ea56ac79a05acfd5d4b0d696f310bd5325a1ed458c3d40154d437",
-    "VERSION": "71015c979ccb0fc8a0be7ca0ae83046ab045cdc2c8faa09fb2f0f7e440f9b4a6",
+    "VERSION": "3ab94c04d24986f3af288ba1cda2c0bbddbc5a89dff097182805f54578e1ea75",
     "docker-compose.yml": "420fd123da019c22f03662933537e24779b4c2c91f90c23abfec5965cd0f35ce",
     "docker/Caddyfile": "d9c58086986795f5b3e42ff9b5942e60b8df946a1a0c40351381616c0b4d2bed",
     "docker/Dockerfile": "340470e3735ea53b2c03003a13a91361652291add33c40a2bf13e6af2a8cb73a",
@@ -47,7 +47,7 @@
     "src/app/api/health/route.ts": "78fff55707372ce0cd6e9e49ef4f049622bc43cc42916d3f83e0162409d678b1",
     "src/app/globals.css": "28dcda76006d0e6af01b6dcf1a315dc5b5b6931c880fc53fd6565ff09d5dd13a",
     "src/app/layout.tsx": "c17aabeb2b486f023e777230343ace6cc06840f641a10b9dd9f65e092018f82f",
-    "src/app/page.tsx": "1c48a37632621373db7730756aacde708e29d6f1bd14062b63736fe8057ce842",
+    "src/app/page.tsx": "732ea54f313386b65bce1170785379b27bb26b5da26b833b1e50c3713b87be1a",
     "src/components/copy-button.tsx": "2f3d1d8a6a0a570c8d78e19c3c15519c44af17b5d8893ae5a5f57db5ecce7077",
     "src/components/portal-login.tsx": "8b0d91bb28674e1102fd2e5b5ddcc3a93755dd806fbd3d1b2dbea2646cffca5e",
     "src/components/portal-shell.tsx": "a4e16e118ef93f79e71fb69e80f1fac6e6fff90f0fbdacdf8deb821a57656877",

package/bundle/scaffold/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.3

package/bundle/scaffold/src/app/page.tsx

@@ -4,6 +4,7 @@ import { prisma } from "@/lib/db";
 import { getRuntimeState, isRuntimeSnapshotMode } from "@/lib/runtime-state";
 import { ArrowUpRight, BookOpen, Command, MessageSquareQuote } from "lucide-react";
 import Link from "next/link";
+import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -16,9 +17,22 @@ const PROMPT_EXAMPLES = [
 export default async function Home() {
   let portalCount = 0;
   const showpaneBinDir = path.join(os.homedir(), ".showpane", "bin");
-  const resumeCommand = (process.env.PATH ?? "").split(path.delimiter).includes(showpaneBinDir)
-    ? "showpane claude"
-    : "npx showpane claude";
+  const configPath = path.join(os.homedir(), ".showpane", "config.json");
+  const configShellPathConfigured = existsSync(configPath)
+    ? (() => {
+        try {
+          const raw = readFileSync(configPath, "utf8");
+          return Boolean((JSON.parse(raw) as { shellPathConfigured?: boolean }).shellPathConfigured);
+        } catch {
+          return false;
+        }
+      })()
+    : false;
+  const prefersCanonicalCommand =
+    configShellPathConfigured ||
+    (process.env.PATH ?? "").split(path.delimiter).includes(showpaneBinDir);
+  const primaryCommand = "showpane claude";
+  const fallbackCommand = "npx showpane claude";
   try {
     if (isRuntimeSnapshotMode()) {
       const state = await getRuntimeState();
@@ -46,7 +60,7 @@ export default async function Home() {
             Your Showpane workspace is ready
           </h1>
           <p className="mt-4 max-w-2xl text-base leading-7 text-white/82 sm:text-lg">
-            Open Claude in your Showpane workspace and create your first client portal.
+            Open a new terminal window, run Showpane with Claude, and create your first client portal.
           </p>
         </div>
       </div>
@@ -61,15 +75,21 @@ export default async function Home() {
                   Start with Claude
                 </div>
                 <p className="mt-3 text-sm leading-6 text-white/72">
-                  This opens Claude in the right Showpane workspace so you can start creating portals immediately.
+                  Open a new terminal window and run this command there. Your current terminal is running the local app, so this command belongs in a fresh one.
                 </p>
+                {!prefersCanonicalCommand && (
+                  <p className="mt-2 text-xs leading-5 text-white/60">
+                    If <code className="font-mono text-white">{primaryCommand}</code> isn&apos;t available in your shell yet, use{" "}
+                    <code className="font-mono text-white">{fallbackCommand}</code>.
+                  </p>
+                )}
               </div>
-              <CopyButton text={resumeCommand} invert />
+              <CopyButton text={primaryCommand} invert />
             </div>
 
             <div className="mt-5 rounded-2xl border border-white/10 bg-white/5 p-4">
               <code className="block overflow-x-auto font-mono text-sm text-white sm:text-[15px]">
-                {resumeCommand}
+                {primaryCommand}
               </code>
             </div>
           </section>

package/bundle/toolchain/VERSION

@@ -1 +1 @@
-1.1.1 (requires app >= 0.2.1)
+1.1.3 (requires app >= 0.2.3)

package/dist/index.js

@@ -243,35 +243,146 @@ function getResumeCommand() {
 function getResumeHint() {
   return isShowpaneShimOnPath() ? null : `Optional: add ${SHOWPANE_BIN_DIR} to your PATH to use ${BOLD}showpane${RESET} directly.`;
 }
+function shellPathExportLine() {
+  return `export PATH="$HOME/.showpane/bin:$PATH"`;
+}
+function detectShellProfile() {
+  if (process.platform === "win32") {
+    return null;
+  }
+  const shell = basename(process.env.SHELL || "");
+  if (shell === "zsh") {
+    return join(homedir(), ".zshrc");
+  }
+  if (shell === "bash") {
+    return process.platform === "darwin" ? join(homedir(), ".bash_profile") : join(homedir(), ".bashrc");
+  }
+  if (shell === "fish") {
+    return join(homedir(), ".config", "fish", "config.fish");
+  }
+  return null;
+}
+function ensureShellPathEntry(profilePath) {
+  ensureDir(dirname(profilePath));
+  const exportLine = shellPathExportLine();
+  const contents = existsSync(profilePath) ? readFileSync(profilePath, "utf8") : "";
+  if (contents.includes(exportLine) || contents.includes(SHOWPANE_BIN_DIR)) {
+    return false;
+  }
+  const prefix = contents.length > 0 && !contents.endsWith("\n") ? "\n" : "";
+  writeFileSync(profilePath, `${contents}${prefix}${exportLine}
+`);
+  return true;
+}
+async function maybeConfigureShellPath(config, options) {
+  const configuredProfile = typeof config.shellPathConfiguredProfile === "string" ? config.shellPathConfiguredProfile : null;
+  if (isShowpaneShimOnPath()) {
+    config.shellPathConfigured = true;
+    config.shellPathPrompted = true;
+    return {
+      command: "showpane claude",
+      configured: true,
+      profilePath: configuredProfile
+    };
+  }
+  if (config.shellPathConfigured) {
+    return {
+      command: "showpane claude",
+      configured: true,
+      profilePath: configuredProfile
+    };
+  }
+  if (options.yes || !process.stdin.isTTY || !process.stdout.isTTY) {
+    config.shellPathPrompted = true;
+    config.shellPathConfigured = false;
+    return {
+      command: "npx showpane claude",
+      configured: false,
+      profilePath: configuredProfile
+    };
+  }
+  const profilePath = detectShellProfile();
+  if (!profilePath) {
+    config.shellPathPrompted = true;
+    config.shellPathConfigured = false;
+    return {
+      command: "npx showpane claude",
+      configured: false,
+      profilePath: null
+    };
+  }
+  const answer = await ask(
+    `  ${BOLD}Add Showpane to your PATH so 'showpane' works in future terminals?${RESET} ${DIM}(recommended) [Y/n]${RESET} `
+  );
+  if (answer && !["y", "yes"].includes(answer.toLowerCase())) {
+    config.shellPathPrompted = true;
+    config.shellPathConfigured = false;
+    config.shellPathConfiguredProfile = profilePath;
+    return {
+      command: "npx showpane claude",
+      configured: false,
+      profilePath
+    };
+  }
+  ensureShellPathEntry(profilePath);
+  config.shellPathPrompted = true;
+  config.shellPathConfigured = true;
+  config.shellPathConfiguredProfile = profilePath;
+  console.log();
+  green(`Added Showpane to your PATH in ${DIM}${profilePath}${RESET}`);
+  return {
+    command: "showpane claude",
+    configured: true,
+    profilePath
+  };
+}
 function getCommandOutput(errorLike) {
   const error2 = errorLike;
   const stdout = typeof error2?.stdout === "string" ? error2.stdout : error2?.stdout?.toString() ?? "";
   const stderr = typeof error2?.stderr === "string" ? error2.stderr : error2?.stderr?.toString() ?? "";
   return [stdout, stderr].filter(Boolean).join("\n").trim();
 }
-function runQuiet(command2, cwd, env) {
-  try {
-    execSync(command2, {
-      cwd,
-      env: env ? { ...process.env, ...env } : process.env,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-      maxBuffer: 20 * 1024 * 1024
+async function runQuietAsync(command2, cwd, env) {
+  const child = spawn(command2, {
+    cwd,
+    env: env ? { ...process.env, ...env } : process.env,
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let output = "";
+  const appendOutput = (chunk) => {
+    output += chunk.toString();
+    if (output.length > 20 * 1024 * 1024) {
+      output = output.slice(-20 * 1024 * 1024);
+    }
+  };
+  child.stdout?.on("data", appendOutput);
+  child.stderr?.on("data", appendOutput);
+  await new Promise((resolvePromise, rejectPromise) => {
+    child.on("error", (errorLike) => {
+      rejectPromise(
+        new StepCommandError(
+          errorLike instanceof Error ? errorLike.message : String(errorLike),
+          output.trim()
+        )
+      );
     });
-  } catch (errorLike) {
-    const output = getCommandOutput(errorLike);
-    throw new StepCommandError(
-      errorLike instanceof Error ? errorLike.message : String(errorLike),
-      output
-    );
-  }
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      const reason = signal ? `Command terminated with signal ${signal}` : `Command exited with code ${code ?? "unknown"}`;
+      rejectPromise(new StepCommandError(reason, output.trim()));
+    });
+  });
 }
-function runInstallerCommand(command2, cwd, env, verbose) {
+async function runInstallerCommand(command2, cwd, env, verbose) {
   if (verbose) {
     run(command2, cwd, env);
     return;
   }
-  runQuiet(command2, cwd, env);
+  await runQuietAsync(command2, cwd, env);
 }
 var activeSpinner = null;
 function renderSpinner(label, frame, startedAt) {
@@ -331,6 +442,18 @@ function stepFailure(label, errorLike, hint) {
   }
   process.exit(1);
 }
+function shouldUseSpinner(verbose) {
+  return process.stdout.isTTY && !verbose;
+}
+function stepStartForCreate(label, options) {
+  stepStart(label, shouldUseSpinner(options.verbose));
+}
+function stepSuccessForCreate(label) {
+  stepSuccess(label);
+}
+function stepFailureForCreate(label, errorLike, hint) {
+  stepFailure(label, errorLike, hint);
+}
 function attachSpinnerCleanup() {
   const cleanup = () => stopSpinner();
   process.on("exit", cleanup);
@@ -679,39 +802,39 @@ function applyUpgradePlan(projectRoot, scaffoldSource, plan) {
     cpSync(sourcePath, targetPath);
   }
 }
-function installDependencies(projectRoot, verbose) {
+async function installDependencies(projectRoot, verbose) {
   if (existsSync(join(projectRoot, "package-lock.json"))) {
     if (verbose === void 0) {
       run("npm ci", projectRoot, getInstallerEnv());
     } else {
-      runInstallerCommand("npm ci", projectRoot, getInstallerEnv(), verbose);
+      await runInstallerCommand("npm ci", projectRoot, getInstallerEnv(), verbose);
     }
   } else {
     if (verbose === void 0) {
       run("npm install", projectRoot, getInstallerEnv());
     } else {
-      runInstallerCommand("npm install", projectRoot, getInstallerEnv(), verbose);
+      await runInstallerCommand("npm install", projectRoot, getInstallerEnv(), verbose);
     }
   }
 }
-function generateLocalDatabase(projectRoot, databaseUrl, verbose) {
+async function generateLocalDatabase(projectRoot, databaseUrl, verbose) {
   const env = getInstallerEnv({
     DATABASE_URL: databaseUrl
   });
   if (verbose === void 0) {
     run("npm run prisma:db-push", projectRoot, env);
   } else {
-    runInstallerCommand("npm run prisma:db-push", projectRoot, env, verbose);
+    await runInstallerCommand("npm run prisma:db-push", projectRoot, env, verbose);
   }
 }
-function seedProject(projectRoot, databaseUrl, verbose) {
+async function seedProject(projectRoot, databaseUrl, verbose) {
   const env = getInstallerEnv({
     DATABASE_URL: databaseUrl
   });
   if (verbose === void 0) {
     run("npx tsx prisma/seed.ts", projectRoot, env);
   } else {
-    runInstallerCommand("npx tsx prisma/seed.ts", projectRoot, env, verbose);
+    await runInstallerCommand("npx tsx prisma/seed.ts", projectRoot, env, verbose);
   }
 }
 function maybeRunPostUpgradeSteps(projectRoot, changedPaths) {
@@ -782,9 +905,8 @@ function installSharedSkillProjection(toolchainRoot) {
     process.platform === "win32" ? "junction" : "dir"
   );
 }
-function printCreateSuccessCard(projectRoot, url) {
-  const resumeCommand = getResumeCommand();
-  const resumeHint = getResumeHint();
+function printCreateSuccessCard(projectRoot, url, pathSetup) {
+  const resumeCommand = pathSetup.command;
   console.log();
   console.log(`  ${GREEN}Showpane is ready${RESET}`);
   console.log();
@@ -792,14 +914,20 @@ function printCreateSuccessCard(projectRoot, url) {
   console.log(`  ${BOLD}App:${RESET}     ${url}`);
   console.log(`  ${BOLD}Demo:${RESET}    example / demo-only-password`);
   console.log();
-  console.log(`  ${BOLD}Next:${RESET}`);
+  console.log(`  ${BOLD}Next (in a new terminal window):${RESET}`);
   console.log(`    ${DIM}${resumeCommand}${RESET}`);
   console.log();
+  if (pathSetup.configured && pathSetup.profilePath) {
+    console.log(`  ${DIM}Your current terminal is running the local app logs. Open a fresh terminal so ${BOLD}showpane${RESET}${DIM} is available from ${pathSetup.profilePath}.${RESET}`);
+  } else {
+    console.log(`  ${DIM}Your current terminal is running the local app logs, so open a fresh terminal before you run that command.${RESET}`);
+  }
+  console.log();
   console.log(`  ${BOLD}Try:${RESET}`);
   console.log(`    ${DIM}Create a portal for my call with Acme Health${RESET}`);
-  if (resumeHint) {
+  if (!pathSetup.configured) {
     console.log();
-    console.log(`  ${DIM}${resumeHint}${RESET}`);
+    console.log(`  ${DIM}${getResumeHint()}${RESET}`);
   }
   console.log();
 }
@@ -1031,6 +1159,8 @@ async function createProject(args) {
   }
   printBanner();
   ensureShowpaneShim();
+  const config = readShowpaneConfig();
+  const pathSetup = await maybeConfigureShellPath(config, options);
   const companyName = options.companyName ?? await ask(`  ${BOLD}What's your company name?${RESET} `);
   if (!companyName) {
     error("Company name is required.");
@@ -1046,20 +1176,20 @@ async function createProject(args) {
   console.log();
   blue(`Setting up ${BOLD}${companyName}${RESET} portal as ${DIM}${dirName}/${RESET}`);
   console.log();
-  stepStart("Create project");
+  stepStartForCreate("Creating project", options);
   try {
     copyScaffoldFiles(join(bundleRoot, "scaffold"), projectRoot, scaffoldManifest);
-    stepSuccess("Project created");
+    stepSuccessForCreate("Project created");
   } catch (errorLike) {
-    stepFailure("Create project", errorLike);
+    stepFailureForCreate("Creating project", errorLike);
   }
-  stepStart("Install dependencies");
+  stepStartForCreate("Installing dependencies", options);
   try {
-    installDependencies(projectRoot, options.verbose);
-    stepSuccess("Dependencies installed");
+    await installDependencies(projectRoot, options.verbose);
+    stepSuccessForCreate("Dependencies installed");
   } catch (errorLike) {
-    stepFailure(
-      "Install dependencies",
+    stepFailureForCreate(
+      "Installing dependencies",
       errorLike,
       "Check your Node.js version and network connection, then try again."
     );
@@ -1072,23 +1202,22 @@ async function createProject(args) {
 AUTH_SECRET="${authSecret}"
 `
   );
-  stepStart("Configure database");
+  stepStartForCreate("Configuring database", options);
   try {
-    generateLocalDatabase(projectRoot, databaseUrl, options.verbose);
-    seedProject(projectRoot, databaseUrl, options.verbose);
-    stepSuccess("Database configured");
+    await generateLocalDatabase(projectRoot, databaseUrl, options.verbose);
+    await seedProject(projectRoot, databaseUrl, options.verbose);
+    stepSuccessForCreate("Database configured");
   } catch (errorLike) {
-    stepFailure(
-      "Configure database",
+    stepFailureForCreate(
+      "Configuring database",
       errorLike,
       "Check Prisma setup and the generated .env file, then retry the install."
     );
   }
-  stepStart("Install Claude skills");
+  stepStartForCreate("Installing Claude skills", options);
   let toolchainInfo;
   try {
     toolchainInfo = syncToolchain(bundleRoot, showpaneVersion, false);
-    const config = readShowpaneConfig();
     updateWorkspaceFromConfig(config, projectRoot, {
       name: dirName,
       deployMode: "local",
@@ -1102,15 +1231,15 @@ AUTH_SECRET="${authSecret}"
       toolchainInfo.toolchainVersion
     );
     tryInitializeGitRepo(projectRoot, false);
-    stepSuccess("Claude skills installed");
+    stepSuccessForCreate("Claude skills installed");
   } catch (errorLike) {
-    stepFailure(
-      "Install Claude skills",
+    stepFailureForCreate(
+      "Installing Claude skills",
       errorLike,
       "Check permissions for ~/.showpane and ~/.claude/skills, then try again."
     );
   }
-  stepStart("Start app");
+  stepStartForCreate("Starting app", options);
   let serverStart;
   try {
     serverStart = await startDevServer(
@@ -1120,13 +1249,13 @@ AUTH_SECRET="${authSecret}"
       options.verbose
     );
   } catch (errorLike) {
-    stepFailure(
-      "Start app",
+    stepFailureForCreate(
+      "Starting app",
       errorLike,
       `Run ${BOLD}cd ${dirName} && npm run dev${RESET} for more detail.`
     );
   }
-  printCreateSuccessCard(projectRoot, serverStart.url);
+  printCreateSuccessCard(projectRoot, serverStart.url, pathSetup);
   serverStart.devServer.on("close", (code) => {
     if (code !== 0) {
       error(`Dev server exited with code ${code}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showpane",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "CLI for Showpane — AI-generated client portals",
   "type": "module",
   "bin": {