scenri 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.1](https://github.com/tonygorb/scenri/compare/v0.3.0...v0.3.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* calm boot failures and stop the silent hang on a busy port ([d04946f](https://github.com/tonygorb/scenri/commit/d04946f011b204c230473f5338f0a32f8870a1d0))
+* friendly first-run errors and the install guide ([b1782ad](https://github.com/tonygorb/scenri/commit/b1782adb4fc48807e384a208ee8894022d62d615))
+
 ## [0.3.0](https://github.com/tonygorb/scenri/compare/v0.2.3...v0.3.0) (2026-08-20)
 
 

package/README.md

@@ -19,6 +19,8 @@ Define a client's brand once. Then generate, branch, and art-direct on-brand ima
 npx scenri
 ```
 
+<sub>Needs [Node.js](https://nodejs.org) 22 or newer. New to any of this? The [install guide](docs/INSTALL.md) walks through every step.</sub>
+
 <img src="https://raw.githubusercontent.com/tonygorb/scenri/main/docs/media/demo.gif" alt="The Scenri composer: a dollar sign opens a product picker and Selvedge Trucker is chosen, an at sign picks the presenter Maren, a slash picks the Editorial Walk scene, a line of written direction is typed after the three chips, the shot renders as a card in the wall, and it opens to show the picture beside the brief that made it" width="820">
 
 <sub>Pick a product, pick a presenter, pick a scene, then write the direction. That is the brief.</sub>
@@ -55,15 +57,17 @@ The brand kit sits one gesture away in Settings and is the part that keeps outpu
 
 ## Run it
 
+Scenri runs on [Node.js](https://nodejs.org), version 22 or newer. If you are not sure you have it, or terminals are not part of your day, the **[install guide](docs/INSTALL.md)** covers every step for macOS, Windows and Linux. With Node in place:
+
 ```bash
 npx scenri
 ```
 
-That is the whole install. It opens `http://127.0.0.1:4747`.
+That is the whole install. npm asks once whether to proceed, downloads the current release, and opens `http://127.0.0.1:4747`. Keep the terminal window open while you work; closing it stops Scenri. Tomorrow the same command opens it again, with everything where you left it.
 
 Generation runs on **Codex CLI**, an official helper from OpenAI that draws on your own ChatGPT plan. No API key to paste, and Scenri never charges you. Each image draws on your plan's Codex usage. You do not have to set it up by hand: if it is missing, Scenri offers to install it and to sign you in, both from the app. No ChatGPT plan? Add your own key from an image provider in Settings instead, see [Engines](#engines).
 
-Requires **Node 22 or newer**. Two dependencies (`better-sqlite3` and `sharp`) ship native binaries, so on recent npm you may be asked to approve their install scripts once.
+Two dependencies (`better-sqlite3` and `sharp`) ship native binaries, so on recent npm you may be asked to approve their install scripts once. Something not starting? See [troubleshooting](docs/INSTALL.md#troubleshooting).
 
 <details>
 <summary>Run from source</summary>

package/dist/chunk-WGIZJXNE.js

@@ -0,0 +1,36 @@
+// src/bootError.ts
+var INSTALL_GUIDE = "https://github.com/tonygorb/scenri/blob/main/docs/INSTALL.md";
+var NATIVE_MARKERS = ["NODE_MODULE_VERSION", "Could not locate the bindings file", "ERR_DLOPEN_FAILED"];
+function portBusyLines(port) {
+  const next = port + 1;
+  return [
+    `Port ${port} is in use by another app.`,
+    "Start Scenri on a different port:",
+    `  macOS or Linux:      SCENRI_PORT=${next} npx scenri`,
+    `  Windows PowerShell:  $env:SCENRI_PORT=${next}; npx scenri`
+  ];
+}
+function bootErrorLines(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const first = raw.split("\n")[0];
+  const code = err?.code;
+  const haystack = `${typeof code === "string" ? code : ""} ${raw}`;
+  if (NATIVE_MARKERS.some((marker) => haystack.includes(marker))) {
+    return [
+      "Scenri could not start: a native component failed to load.",
+      `(${first})`,
+      "This usually means Node changed since this copy of Scenri was installed.",
+      "Fix: install the current Node LTS from https://nodejs.org, then run npx scenri@latest."
+    ];
+  }
+  return [
+    `Scenri could not start: ${first}`,
+    "If this keeps happening, run npx scenri@latest, or see the install guide:",
+    INSTALL_GUIDE,
+    "Set SCENRI_DEBUG=1 to see the full error."
+  ];
+}
+
+export { bootErrorLines, portBusyLines };
+//# sourceMappingURL=chunk-WGIZJXNE.js.map
+//# sourceMappingURL=chunk-WGIZJXNE.js.map

package/dist/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { bootErrorLines } from './chunk-WGIZJXNE.js';
+
 // src/args.ts
 function parseArgs(argv) {
   const [first, ...rest] = argv;
@@ -41,43 +43,51 @@ SCENRI_CONTENT_URL.
 
 // src/index.ts
 var command = parseArgs(process.argv.slice(2));
-switch (command.cmd) {
-  case "version": {
-    const { readMeta } = await import('./meta-MPQPBPBK.js');
-    console.log(readMeta().version);
-    break;
-  }
-  case "help":
-    console.log(helpText());
-    break;
-  case "error":
-    console.error(command.message);
-    process.exit(2);
-    break;
-  case "verify":
-    await (await import('./serve.js')).verify();
-    break;
-  case "serve":
-    await (await import('./serve.js')).serve();
-    break;
-  case "update": {
-    const { runUpdateCommand } = await import('./cli-GQLRYYGU.js');
-    process.exit(await runUpdateCommand(command));
-    break;
-  }
-  case "launch": {
-    const ownEntry = process.argv[1] ?? "";
-    if (!/[\\/]dist[\\/]/.test(ownEntry)) {
+try {
+  switch (command.cmd) {
+    case "version": {
+      const { readMeta } = await import('./meta-MPQPBPBK.js');
+      console.log(readMeta().version);
+      break;
+    }
+    case "help":
+      console.log(helpText());
+      break;
+    case "error":
+      console.error(command.message);
+      process.exit(2);
+      break;
+    case "verify":
+      await (await import('./serve.js')).verify();
+      break;
+    case "serve":
       await (await import('./serve.js')).serve();
       break;
+    case "update": {
+      const { runUpdateCommand } = await import('./cli-GQLRYYGU.js');
+      process.exit(await runUpdateCommand(command));
+      break;
+    }
+    case "launch": {
+      const ownEntry = process.argv[1] ?? "";
+      if (!/[\\/]dist[\\/]/.test(ownEntry)) {
+        await (await import('./serve.js')).serve();
+        break;
+      }
+      const { runLauncher } = await import('./launcher-RETYUGSR.js');
+      const { readMeta } = await import('./meta-MPQPBPBK.js');
+      const { defaultHome } = await import('./versionsDir-ILQ4CI7B.js');
+      const meta = readMeta();
+      process.exit(await runLauncher({ home: defaultHome(), pkg: meta.name, ownVersion: meta.version, ownEntry }));
+      break;
     }
-    const { runLauncher } = await import('./launcher-RETYUGSR.js');
-    const { readMeta } = await import('./meta-MPQPBPBK.js');
-    const { defaultHome } = await import('./versionsDir-ILQ4CI7B.js');
-    const meta = readMeta();
-    process.exit(await runLauncher({ home: defaultHome(), pkg: meta.name, ownVersion: meta.version, ownEntry }));
-    break;
   }
+} catch (err) {
+  if (process.env.SCENRI_DEBUG === "1") throw err;
+  console.error("");
+  for (const line of bootErrorLines(err)) console.error(`  ${line}`);
+  console.error("");
+  process.exit(1);
 }
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/serve.js

@@ -1,3 +1,4 @@
+import { portBusyLines } from './chunk-WGIZJXNE.js';
 import { createUpdateChecker, classify, stageVersion, findNpm } from './chunk-GA7P7K2M.js';
 import { readMeta, repoSlug } from './chunk-Y3ZPBPLP.js';
 import { newestStaged, compareSemver } from './chunk-4MAFHYAD.js';
@@ -6514,6 +6515,16 @@ function registerImageRoutes(app, deps) {
 
 // src/release/notes.data.ts
 var RELEASES = [
+  {
+    version: "0.3.1",
+    date: "2026-08-20",
+    sections: [
+      {
+        heading: "Fixes",
+        body: "Starting Scenri is calmer when something is wrong. A busy port or a failed start now explains itself in plain words instead of a stack trace, and the terminal says to keep its window open while Scenri runs."
+      }
+    ]
+  },
   {
     version: "0.3.0",
     date: "2026-08-20",
@@ -7515,7 +7526,9 @@ async function run() {
           continue;
         }
         try {
-          const res = await fetch(`http://127.0.0.1:${PORT}/api/version`);
+          const res = await fetch(`http://127.0.0.1:${PORT}/api/version`, {
+            signal: AbortSignal.timeout(2e3)
+          });
           const info = await res.json();
           if (info.name === readMeta().name) {
             const url = `http://127.0.0.1:${PORT}`;
@@ -7533,6 +7546,10 @@ async function run() {
           }
         } catch {
         }
+        console.error("");
+        for (const line of portBusyLines(PORT)) console.error(`  ${line}`);
+        console.error("");
+        process.exit(1);
       }
       throw err;
     }
@@ -7555,8 +7572,8 @@ async function run() {
   console.log(`
   Scenri Studio \u2192 ${localUrl}`);
   for (const ip of reachableAt) console.log(`  on your network \u2192 http://${ip}:${PORT}${query}`);
-  console.log(`  data dir        \u2192 ${core.home}
-`);
+  console.log(`  data dir        \u2192 ${core.home}`);
+  console.log("  Keep this window open while Scenri is running.\n");
   if (!studioDist) console.log("  (studio UI not built, API only. Run: pnpm build)\n");
   if (token) {
     console.log("  Warning: the studio is reachable from your network.");
@@ -7566,10 +7583,22 @@ async function run() {
     console.log("  For this machine only, unset SCENRI_HOST.\n");
   }
   if (process.env.SCENRI_NO_OPEN !== "1") {
+    let told = false;
+    const tellUrl = () => {
+      if (told) return;
+      told = true;
+      console.log(`  Open ${localUrl} in your browser.
+`);
+    };
     try {
       const { default: open } = await import('open');
-      await open(localUrl);
+      const child = await open(localUrl);
+      child.once("error", tellUrl);
+      child.once("exit", (openExit) => {
+        if (openExit !== null && openExit !== 0) tellUrl();
+      });
     } catch {
+      tellUrl();
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenri",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": "Tony Gorb <hello@scenri.co>",
   "license": "AGPL-3.0-only",
   "type": "module",