@gentbajko/slopify 2.0.1 → 2.0.3

package/dist/edge/http/revision-files.js

@@ -47,7 +47,7 @@ export function revisionFolderRoutes(deps) {
             return problem(c, {
                 status: 403,
                 title: titleOf(403),
-                detail: "Open folders from Slopify itself.",
+                detail: "For your safety, folders can only be opened from the Slopify page itself. Open Slopify and try again there.",
             });
         const { id: projectId, revisionId, recordId } = c.req.valid("param");
         const result = findRevisionDownload(deps, projectId, revisionId, recordId);
@@ -61,8 +61,8 @@ function unavailable(c, reason) {
         status: 404,
         title: titleOf(404),
         detail: reason === "missing-file"
-            ? "This retained file is no longer on disk. Review the affected rebuild to recreate it."
-            : "The retained file is unavailable.",
+            ? "This file was deleted or moved from the project folder. In the Edit tab, use Rebuild affected outputs to make it again."
+            : "This file is no longer part of the project. Reload the page to see its current files.",
         extensions: { reason },
     });
 }

package/dist/edge/http/revisions.js

@@ -3,6 +3,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { projectExists } from "../../slices/admission/repo.js";
 import { previewRebuildSchema, startRebuildSchema } from "../../slices/rebuild/model.js";
+import { narrationChunkOrder } from "../../slices/rebuild/runtime-narration-text.js";
 import { previewRebuild, startRebuild } from "../../slices/rebuild/service.js";
 import { ensureBaseline, restoreRevision, saveRevision } from "../../slices/revisions/index.js";
 import { currentRevisionId, listRevisionHistory } from "../../slices/revisions/repo.js";
@@ -30,12 +31,24 @@ const statuses = {
     "cost-ack-required": 409,
     readiness: 409,
 };
+const details = {
+    "no-project": "This project no longer exists. Go back to Projects to pick another.",
+    "no-revision": "This saved version of the project no longer exists. Reload the page, then try again.",
+    conflict: "This project changed while you were editing. Reload the page to see the latest, then make your change again.",
+    "idempotency-conflict": "This change was already sent with different details. Reload the page, then try again.",
+    "invalid-edit": "Some of your changes are not valid. Fix the highlighted fields and save again.",
+    "stale-preview": "What needs rebuilding changed since you opened this review. Cancel it and open Rebuild affected outputs again to see the latest.",
+    "invalid-selection": "Some of the outputs you picked can no longer be rebuilt. Reload the page and choose again.",
+    "review-required": 'This rebuild touches content you supplied yourself. Tick "Keep the provided content" for each item in the review, then choose Start rebuild.',
+    "cost-ack-required": "Some costs for this rebuild are unknown. Tick the box confirming you understand, then choose Start rebuild.",
+    readiness: "Slopify cannot run this rebuild yet. Fix the problems listed, then try again.",
+};
 function refused(c, deps, projectId, value) {
     const status = statuses[value.reason];
     return problem(c, {
         status,
         title: titleOf(status),
-        detail: value.reason.replaceAll("-", " "),
+        detail: details[value.reason],
         extensions: {
             reason: value.reason,
             currentRevisionId: currentRevisionId(deps.db, projectId) ?? null,
@@ -47,11 +60,11 @@ function unavailable(c) {
     return problem(c, {
         status: 503,
         title: titleOf(503),
-        detail: "Rebuild services are unavailable.",
+        detail: "Rebuilding is not ready yet because Slopify is still starting. Wait a moment, reload the page and try again.",
     });
 }
 export function revisionRoutes(deps) {
-    return new Hono()
+    return (new Hono()
         .post("/:id/revisions/prepare", zValidator("param", projectParam, onInvalid), async (c) => {
         const projectId = c.req.valid("param").id;
         const result = await ensureBaseline(deps, projectId);
@@ -69,6 +82,19 @@ export function revisionRoutes(deps) {
         return view === undefined
             ? refused(c, deps, projectId, { reason: "no-revision" })
             : c.json({ view });
+    })
+        // Chunk keys in spoken order, so the Narration editor numbers chunks the way a subtitle
+        // error names them. Building the plan is the costly part, so it has its own request.
+        .get("/:id/revisions/:revisionId/narration-chunks", zValidator("param", revisionParam, onInvalid), (c) => {
+        const { id: projectId, revisionId } = c.req.valid("param");
+        let chunks;
+        try {
+            chunks = narrationChunkOrder(deps, projectId, revisionId);
+        }
+        catch {
+            chunks = undefined;
+        }
+        return c.json({ chunks: chunks ?? null });
     })
         .post("/:id/revisions", zValidator("param", projectParam, onInvalid), zValidator("json", saveBody, onInvalid), async (c) => {
         const projectId = c.req.valid("param").id;
@@ -99,5 +125,5 @@ export function revisionRoutes(deps) {
         const projectId = c.req.valid("param").id;
         const result = await startRebuild(deps.rebuild, { projectId, ...c.req.valid("json") });
         return result.ok ? c.json(result, 202) : refused(c, deps, projectId, result);
-    });
+    }));
 }

package/dist/edge/http/schedules.js

@@ -13,15 +13,15 @@ function refused(c, result) {
             ? 409
             : 400;
     const detail = {
-        "invalid-input": "Check the schedule fields and try again.",
-        "not-found": "The schedule was not found.",
-        conflict: "The schedule changed elsewhere. Reload it before trying again.",
-        "cancel-required": "Cancel this schedule before deleting it. Completed schedules can be deleted directly.",
-        "missing-template": "The selected template version is no longer available.",
-        "unsupported-media": "This template contains provided media and cannot run unattended.",
-        "not-due": "Choose a future one-off time.",
-        "spend-limit": "The estimate exceeds the schedule spend limit or contains unknown pricing.",
-        readiness: "Provider or local readiness checks refused this scheduled run.",
+        "invalid-input": "Some schedule settings are not valid. Check each field and save again.",
+        "not-found": "This schedule no longer exists; it may have been deleted. Reload the page to see your schedules.",
+        conflict: "This schedule changed while you were editing, possibly because a run just started. Reload the page to see the latest, then make your change again.",
+        "cancel-required": "This schedule is still active. Cancel it first, then delete it. Completed schedules can be deleted straight away.",
+        "missing-template": "The template you picked was deleted or changed. Choose a template again, then save.",
+        "unsupported-media": "This template uses audio, images or a thumbnail you supplied, so it cannot run on a schedule. Pick a template that generates these instead.",
+        "not-due": "This one-off time has already passed. Choose a time in the future.",
+        "spend-limit": "The estimated cost is above this schedule's spend limit, or some prices are unknown. Raise the spend limit or choose models with known prices.",
+        readiness: "A provider this template needs is not ready, for example a missing API key, model or voice. Check Settings → Providers, then try again.",
     };
     return problem(c, {
         status,

package/dist/edge/http/settings.js

@@ -30,7 +30,7 @@ export function settingsRoutes(deps) {
             return problem(c, {
                 status: 400,
                 title: titleOf(400),
-                detail: "These settings cannot be saved; the listed fields need attention.",
+                detail: "These settings cannot be saved yet. Fix the highlighted fields and try again.",
                 extensions: { fields: result.fields },
             });
         }
@@ -46,12 +46,12 @@ export function settingsRoutes(deps) {
                 ? problem(c, {
                     status: 409,
                     title: titleOf(409),
-                    detail: "This voice ID is already listed for this provider.",
+                    detail: "This voice ID is already saved for this provider. Use the existing voice, or enter a different voice ID.",
                 })
                 : problem(c, {
                     status: 400,
                     title: titleOf(400),
-                    detail: "This voice cannot be added; the listed fields need attention.",
+                    detail: "This voice cannot be added yet. Fix the highlighted field and try again.",
                     extensions: { fields: [fieldOf(result.reason)] },
                 });
         }
@@ -62,7 +62,7 @@ export function settingsRoutes(deps) {
             return problem(c, {
                 status: 404,
                 title: titleOf(404),
-                detail: "No voice has that id.",
+                detail: "This voice no longer exists; it may have been deleted already. Reload the page to see your voices.",
             });
         }
         return c.body(null, 204);
@@ -71,20 +71,26 @@ export function settingsRoutes(deps) {
 function fieldOf(reason) {
     switch (reason) {
         case "blank-name":
-            return { field: "name", message: "A voice name is required." };
+            return { field: "name", message: "Enter a name for this voice." };
         case "name-too-long":
             return {
                 field: "name",
-                message: `A voice name is at most ${String(voiceNameMax)} characters.`,
+                message: `Keep the voice name to ${String(voiceNameMax)} characters or fewer.`,
             };
         case "blank-voice-id":
-            return { field: "voiceId", message: "A voice ID is required." };
+            return {
+                field: "voiceId",
+                message: "Enter the voice ID from your provider's voice library.",
+            };
         case "voice-id-too-long":
             return {
                 field: "voiceId",
-                message: `A voice ID is at most ${String(voiceIdMax)} characters.`,
+                message: `A voice ID is at most ${String(voiceIdMax)} characters. Check you copied only the ID.`,
             };
         case "not-a-tts-provider":
-            return { field: "provider", message: "Pick a text-to-speech provider." };
+            return {
+                field: "provider",
+                message: "Choose a text-to-speech provider, such as Inworld or Cartesia.",
+            };
     }
 }

package/dist/edge/http/staging.js

@@ -34,7 +34,7 @@ export function stagingRoutes(deps) {
             return problem(c, {
                 status: 400,
                 title: titleOf(400),
-                detail: "The request carried no file part.",
+                detail: "No file arrived with the upload. Choose the file again and retry.",
             });
         }
         if (!result.ok) {
@@ -49,8 +49,8 @@ export function stagingRoutes(deps) {
                 status: result.reason === "in-use" ? 409 : 404,
                 title: titleOf(result.reason === "in-use" ? 409 : 404),
                 detail: result.reason === "in-use"
-                    ? "This file is used by a saved draft."
-                    : "No staged file has that id.",
+                    ? "This file is still attached to a draft in Play. Remove it from the draft first."
+                    : "This uploaded file no longer exists; it may have been removed already. Reload the page.",
             });
         }
         return c.body(null, 204);
@@ -58,6 +58,6 @@ export function stagingRoutes(deps) {
 }
 function detailOf(reason) {
     return reason === "empty-file"
-        ? "The uploaded file is empty."
-        : "The file name may not be empty or contain a path separator.";
+        ? "This file is empty (0 bytes). Choose a file that has content."
+        : "This file's name is empty or contains a slash. Rename the file on your computer, then upload it again.";
 }

package/dist/edge/http/storage.js

@@ -23,7 +23,7 @@ export function storageRoutes(deps) {
             return problem(c, {
                 status: 500,
                 title: titleOf(500),
-                detail: "The backup could not be created.",
+                detail: "Slopify could not create the backup. Check there is free disk space and try again; if it keeps failing, use Download diagnostics in Settings and report it.",
             });
         }
     })
@@ -33,14 +33,14 @@ export function storageRoutes(deps) {
             return problem(c, {
                 status: 415,
                 title: titleOf(415),
-                detail: "Upload a Slopify backup ZIP.",
+                detail: "Choose a Slopify backup file (.zip) made with Backup & storage in Settings.",
             });
         const upload = await readPortableUpload(c.req.raw);
         if (!upload.ok)
             return problem(c, {
                 status: 413,
                 title: titleOf(413),
-                detail: "The backup must be between 1 byte and 100 MB.",
+                detail: "This backup file is empty or larger than 100 MB. Choose a Slopify backup file under 100 MB.",
             });
         try {
             const imported = importPortable({
@@ -55,7 +55,7 @@ export function storageRoutes(deps) {
             return problem(c, {
                 status: 400,
                 title: titleOf(400),
-                detail: "The backup is invalid or incomplete.",
+                detail: "This file is not a complete Slopify backup; it may be damaged or a different kind of ZIP. Choose a backup made with Backup & storage in Settings.",
             });
         }
     })

package/dist/edge/http/subtitles.js

@@ -16,7 +16,7 @@ function revisionRequired(c) {
     return problem(c, {
         status: 409,
         title: titleOf(409),
-        detail: "Open Edit project to save changes, then review the affected rebuild.",
+        detail: "This change is now made from the Edit tab. Choose Edit project, save your change, then use Rebuild affected outputs.",
         extensions: { reason: "revision-required" },
     });
 }

package/dist/edge/http/tutorial.js

@@ -13,8 +13,8 @@ export function tutorialRoutes(deps) {
                 status: 409,
                 title: titleOf(409),
                 detail: result.reason === "unreadable"
-                    ? "Saved tutorial progress cannot be read. Choose Restart tutorial to reset it."
-                    : "Tutorial progress changed. Reload the saved progress before trying again.",
+                    ? "Your saved tutorial progress could not be read. Choose Restart tutorial to start it again."
+                    : "Your tutorial progress changed in another tab or window. Reload the page, then try again.",
                 extensions: { reason: result.reason },
             });
         return c.json(result.value);

package/dist/edge/http/update.js

@@ -8,7 +8,7 @@ export function updateRoutes(deps) {
         busy: false,
         canUpdate: false,
         status: "idle",
-        blockedReason: "In-app updates are unavailable for this server.",
+        blockedReason: "This copy of Slopify cannot update itself from the app. Update it the way you installed it, for example by running the launcher again.",
     };
     return new Hono()
         .get("/ready", (c) => {
@@ -38,7 +38,7 @@ export function updateRoutes(deps) {
             return problem(c, {
                 status: 403,
                 title: titleOf(403),
-                detail: "Start updates from the Slopify page on this server.",
+                detail: "For your safety, updates can only be started from the Slopify page itself. Open Slopify and try again there.",
             });
         if (deps.updater === undefined)
             return problem(c, { status: 409, title: titleOf(409), detail: unavailable.blockedReason });
@@ -51,7 +51,7 @@ export function updateRoutes(deps) {
             title: titleOf(status),
             detail: result.info.blockedReason ??
                 result.info.error ??
-                "No newer published update is available.",
+                "You already have the latest version of Slopify.",
         });
     });
 }

package/dist/host-cli/install.js

@@ -1,19 +1,41 @@
 import { execFile } from "node:child_process";
 import { access, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { z } from "zod";
 import { isStableVersion, updatePackage } from "../updater/model.js";
 import { installArgs, npmCommand } from "../updater/plan.js";
 import { hasCode } from "./paths.js";
 export const nodeHostSetupRunner = {
     exec: (file, args, signal) => new Promise((resolve, reject) => {
-        execFile(file, [...args], { signal, timeout: 15 * 60_000, maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout) => {
+        execFile(file, [...args], { signal, timeout: 15 * 60_000, maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
             if (error && typeof error.code !== "number")
-                return reject(new Error("Host setup command could not finish. Check Docker, Node and the systemd user service."));
-            resolve({ code: typeof error?.code === "number" ? error.code : 0, stdout });
+                return reject(new Error(setupCommandFailure(file, args, error)));
+            resolve({ code: typeof error?.code === "number" ? error.code : 0, stdout, stderr });
         });
     }),
 };
+// Says which program could not run and what to do about it; Node's own error only names the
+// errno, and the person running the launcher needs the fix.
+function setupCommandFailure(file, args, error) {
+    const name = basename(file);
+    const step = `"${[name, ...args.slice(0, 2)].join(" ")}"`;
+    if (error.code === "ENOENT") {
+        if (name === "docker")
+            return "Docker is not installed, or the docker command is not on your PATH. Install Docker Engine (https://docs.docker.com/engine/install/), check that docker info works, and run the launcher again.";
+        if (name === "systemctl" || name === "loginctl")
+            return `${name} was not found. Using this machine's AI CLIs from Docker needs systemd; start with --host-cli=off to use API keys only.`;
+        if (name === "npm" || name === "npm.cmd")
+            return "npm was not found. Install Node.js with npm (https://nodejs.org) and run the launcher again.";
+        return `${name} was not found on your PATH. Install it and run the launcher again.`;
+    }
+    if (error.code === "EACCES")
+        return `${file} could not be run (permission denied). Check that your user may run it, then try again.`;
+    if (error.code === "ABORT_ERR" || error.name === "AbortError")
+        return `${step} was stopped before it finished. Run the launcher again; Slopify will finish or undo the half-done step.`;
+    if (error.killed)
+        return `${step} took too long and was stopped. Check your internet connection and that Docker is running (docker info), then run the launcher again.`;
+    return `${step} could not finish (${error.message}). Check that Docker, Node.js and systemd user services work on this machine, then run the launcher again.`;
+}
 async function entryAt(directory, version) {
     const path = join(directory, "node_modules", "@gentbajko", "slopify");
     z.object({ name: z.literal(updatePackage), version: z.literal(version) }).parse(JSON.parse(await readFile(join(path, "package.json"), "utf8")));
@@ -34,7 +56,7 @@ export async function installHostPackage(options) {
     }
     catch (error) {
         if (!hasCode(error, "ENOENT"))
-            throw new Error("Existing host helper install is invalid. No service was changed.");
+            throw new Error(`The installed host helper in ${directory} is damaged. Delete that folder and run the launcher again. Nothing else was changed.`);
     }
     await mkdir(versions, { recursive: true, mode: 0o700 });
     const staging = await mkdtemp(join(versions, `.install-${version}-`));
@@ -50,7 +72,7 @@ export async function installHostPackage(options) {
             options.packageSource ?? `${updatePackage}@${version}`,
         ], signal);
         if (result.code !== 0)
-            throw new Error("npm could not install the host helper. The existing container was not changed.");
+            throw new Error("npm could not install the Slopify host helper. Check your internet connection (npm must reach registry.npmjs.org) and run the launcher again. Your existing container was not changed.");
         await entryAt(staging, version);
         await rename(staging, directory);
         return { entry: await entryAt(directory, version) };

package/dist/host-cli/paths.js

@@ -4,12 +4,12 @@ import { chmod, lstat, mkdir, open } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 export async function prepareHostPaths(root) {
     if (!isAbsolute(root) || /[\p{Cc}]/u.test(root))
-        throw new Error("Unsafe host helper directory.");
+        throw new Error(`Unsafe host helper directory ${JSON.stringify(root)}: it must be a full path. Check XDG_DATA_HOME and HOME, then run the launcher again.`);
     const normalized = resolve(root);
     const share = join(normalized, "share");
     const socket = join(share, "cli.sock");
     if (Buffer.byteLength(socket) > 100)
-        throw new Error("Use a shorter XDG_DATA_HOME for the host helper socket (at most 100 bytes).");
+        throw new Error(`The host helper path ${socket} is too long for this system (over 100 bytes). Set a shorter XDG_DATA_HOME, for example XDG_DATA_HOME=~/.local/share, and run the launcher again.`);
     await mkdir(normalized, { recursive: true, mode: 0o700 });
     await ownedDirectory(normalized, true);
     await chmod(normalized, 0o700);
@@ -24,19 +24,19 @@ async function ownedDirectory(path, privateRoot = false) {
         entry.isSymbolicLink() ||
         (privateRoot && (entry.mode & 0o077) !== 0) ||
         (process.getuid && entry.uid !== process.getuid()))
-        throw new Error("Unsafe host helper directory.");
+        throw new Error(`Unsafe host helper directory ${path}: it must be a real folder owned by you${privateRoot ? " that only you can read" : ""}. Fix its owner and permissions (chmod ${privateRoot ? "700" : "755"} ${path}) or delete it, then run the launcher again.`);
 }
 export async function readBridgeToken(path) {
     const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
         const entry = await file.stat();
         if (!entry.isFile() || entry.size !== 64 || (entry.mode & 0o022) !== 0)
-            throw new Error("Invalid host helper token file.");
+            throw new Error(`The host helper token file ${path} is damaged. Delete it and run the launcher again.`);
         const buffer = Buffer.alloc(65);
         const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
         const value = buffer.subarray(0, bytesRead).toString("utf8");
         if (!/^[a-f0-9]{64}$/.test(value))
-            throw new Error("Invalid host helper token file.");
+            throw new Error(`The host helper token file ${path} is damaged. Delete it and run the launcher again.`);
         return value;
     }
     finally {
@@ -60,7 +60,7 @@ export async function ensureBridgeToken(path) {
     }
     const entry = await lstat(path);
     if (entry.isSymbolicLink() || (process.getuid && entry.uid !== process.getuid()))
-        throw new Error("Unsafe host helper token file.");
+        throw new Error(`The host helper token file ${path} is a link or belongs to another user. Delete it and run the launcher again.`);
     return readBridgeToken(path);
 }
 export function hasCode(error, code) {

package/dist/host-cli/server.js

@@ -19,7 +19,7 @@ export async function startHostServer(options) {
         if (!existing.isSocket() || (process.getuid && existing.uid !== process.getuid()))
             throw new Error("Unsafe host helper socket.");
         if (await listening(socket))
-            throw new Error("A host helper is already listening.");
+            throw new Error(`A Slopify host helper is already listening on ${socket}. Stop it first (systemctl --user stop slopify-cli-bridge.service).`);
         await unlink(socket);
     }
     catch (error) {

package/dist/host-cli/service.js

@@ -39,11 +39,11 @@ export async function privateRead(path, uid) {
         try {
             const stat = await file.stat();
             if (!stat.isFile() || stat.uid !== uid || stat.size > 64 * 1024 || (stat.mode & 0o022) !== 0)
-                throw new Error("Unsafe host helper configuration.");
+                throw new Error(`${path} must be a regular file owned by you that others can't write to. Fix it (chmod 600 ${path}) or delete it, then run the launcher again.`);
             const buffer = Buffer.alloc(64 * 1024 + 1);
             const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
             if (bytesRead > 64 * 1024)
-                throw new Error("Host configuration too large.");
+                throw new Error(`${path} is too large to be a Slopify file. Delete it and run the launcher again.`);
             return buffer.subarray(0, bytesRead).toString("utf8");
         }
         finally {
@@ -106,35 +106,35 @@ async function waitHealth(options, accepting) {
             return health;
         await delay(100, undefined, { signal: options.signal });
     }
-    throw new Error("Host helper did not become ready within 30 seconds.");
+    throw new Error(`The Slopify host helper did not start within 30 seconds. See why with: systemctl --user status ${hostUnit}`);
 }
 export async function ensureHostService(options) {
     const { root, env, runner, signal, uid } = options;
     const environment = JSON.stringify(hostEnvironment(env));
     const directory = join(env.XDG_CONFIG_HOME ?? join(env.HOME ?? "", ".config"), "systemd/user");
     if (!isAbsolute(directory))
-        throw new Error("Host configuration directory must be absolute.");
+        throw new Error("Could not find your systemd user folder because HOME (or XDG_CONFIG_HOME) is not a full path. Set it and run the launcher again.");
     const unitPath = join(directory, hostUnit);
     const configPath = join(root, "host-environment.json");
     const previous = await privateRead(unitPath, uid);
     const previousConfig = await privateRead(configPath, uid);
     if (previous !== undefined && !previous.startsWith(`${marker}\n`))
-        throw new Error("An existing host helper service is not owned by Slopify. It was not changed.");
+        throw new Error(`A service file ${unitPath} already exists and is not owned by Slopify, so it was left alone. Rename or remove it, or start with --host-cli=off to use API keys only.`);
     const unit = serviceUnit(options.node, options.entry, root);
     const run = async (file, args, required = true, commandSignal = signal) => {
         const result = await runner.exec(file, args, commandSignal);
         if (required && result.code !== 0)
-            throw new Error(`Host helper setup failed (${file}). The existing container was not changed.`);
+            throw new Error(`Host helper setup failed at "${[file, ...args.slice(0, 2)].join(" ")}"${result.stderr?.trim() ? ` (${result.stderr.trim().split("\n").at(-1)?.slice(0, 300)})` : ""}. Check that systemd user services work (systemctl --user status), or start with --host-cli=off to use API keys only. Your existing container was not changed.`);
         return result;
     };
     const fragment = (await run("systemctl", ["--user", "show", hostUnit, "--property=FragmentPath", "--value"])).stdout.trim();
     if (fragment && fragment !== unitPath)
-        throw new Error("An existing host helper service is not owned by this Slopify installation.");
+        throw new Error(`A ${hostUnit} service from somewhere else (${fragment}) is already installed and is not owned by this Slopify, so it was left alone. Remove it, or start with --host-cli=off to use API keys only.`);
     const active = (await run("systemctl", ["--user", "is-active", "--quiet", hostUnit], false)).code === 0;
     const wasEnabled = (await run("systemctl", ["--user", "is-enabled", "--quiet", hostUnit], false)).code === 0;
     const current = await helperHealth(root, signal);
     if (active && (!previous || !current))
-        throw new Error("The running host helper cannot be verified. Check its service before updating; no work was interrupted.");
+        throw new Error(`The Slopify host helper is running but not answering, so it was not replaced. Restart it (systemctl --user restart ${hostUnit}) and run the launcher again; no work was interrupted.`);
     const linger = (await run("loginctl", ["show-user", String(uid), "-p", "Linger", "--value"])).stdout.trim();
     if (linger !== "yes")
         await run("loginctl", ["enable-linger", String(uid)]);
@@ -152,12 +152,12 @@ export async function ensureHostService(options) {
             paused = true;
             await run("systemctl", ["--user", "kill", "--kill-whom=main", "--signal=SIGHUP", hostUnit]);
             if ((await waitHealth(options, false)).active !== 0)
-                throw new Error("The host helper is doing work. Wait for it to finish before updating.");
+                throw new Error("The host helper is doing work for Slopify right now. Wait for running projects to finish, then run the launcher again.");
         }
         await mkdir(directory, { recursive: true, mode: 0o700 });
         const directoryStat = await lstat(directory);
         if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || directoryStat.uid !== uid)
-            throw new Error("Unsafe user service directory.");
+            throw new Error(`${directory} is not a normal folder owned by your user, so Slopify can't add its service there. Fix its owner and run the launcher again.`);
         replaced = true;
         await privateWrite(configPath, environment);
         await privateWrite(unitPath, unit);
@@ -193,7 +193,7 @@ export async function ensureHostService(options) {
                 await restore(["--user", "kill", "--kill-whom=main", "--signal=SIGUSR2", hostUnit]);
         }
         catch {
-            throw new Error("Host helper setup failed and rollback needs attention. Check slopify-cli-bridge.service; the Docker container was not changed.");
+            throw new Error(`Host helper setup failed and Slopify could not fully undo it. Check the service with systemctl --user status ${hostUnit}; your Docker container was not changed.`);
         }
         throw error;
     }

package/dist/host-cli/status.js

@@ -24,7 +24,9 @@ export async function resolveHostCommand(id, env) {
                 throw error;
         }
     }
-    throw Object.assign(new Error("The CLI was not found on the host PATH."), { code: "ENOENT" });
+    throw Object.assign(new Error(`${hostCommandName(id)} was not found on this machine's PATH.`), {
+        code: "ENOENT",
+    });
 }
 const authSchema = z.object({ loggedIn: z.boolean() });
 export function parseHostLogin(id, stdout, stderr) {
@@ -72,7 +74,9 @@ export function createHostStatus(deps) {
                 installed: false,
                 login: "unknown",
                 issueKind: isCode(error, "ENOENT") ? "missing" : "bridge",
-                issue: "The CLI could not be found on the host. Check its installation, then rerun the Docker launcher.",
+                issue: isCode(error, "ENOENT")
+                    ? `${hostCommandName(id)} was not found on this machine. Install it and sign in there, then run the launcher again: npx @gentbajko/slopify --docker`
+                    : `Slopify could not check for ${hostCommandName(id)} on this machine (${error instanceof Error ? error.message : String(error)}). Fix the problem, then run the launcher again: npx @gentbajko/slopify --docker`,
             };
         }
         const readiness = readinessFromProbe(await deps.probe(command, ["--version"], cliProbeTimeoutMs), {
@@ -96,7 +100,7 @@ export function createHostStatus(deps) {
                 ...base,
                 login: "unknown",
                 issueKind: "missing",
-                issue: "The host CLI did not answer. Check its installation and rerun the Docker launcher.",
+                issue: `${command} is installed but did not answer "${hostCommandName(id)} --version". Reinstall or update it on this machine, then run the launcher again: npx @gentbajko/slopify --docker`,
             };
         if (readiness.issue)
             return { ...base, login: "unknown", issueKind: "version", issue: readiness.issue };

package/dist/kernel/config/index.js

@@ -7,19 +7,21 @@ export function configFrom(flags, env) {
     const host = flags.host ?? env.SLOPIFY_HOST ?? defaultHost;
     const dataDir = flags["data-dir"] ?? env.SLOPIFY_DATA_DIR ?? join(homedir(), ".slopify");
     if (host.trim() === "") {
-        throw new Error("host must not be empty");
+        throw new Error(`The host setting is empty (from ${flags.host !== undefined ? "--host" : "SLOPIFY_HOST"}). Leave it out to use 127.0.0.1, or give an address such as --host 127.0.0.1.`);
     }
     return {
-        port: port === undefined ? defaultPort : parsePort(port),
+        port: port === undefined
+            ? defaultPort
+            : parsePort(port, flags.port !== undefined ? "--port" : "SLOPIFY_PORT"),
         host,
         dataDir: resolve(dataDir),
         open: flags["no-open"] === true ? false : !isTruthy(env.SLOPIFY_NO_OPEN),
     };
 }
-function parsePort(value) {
+function parsePort(value, source) {
     const port = Number(value.trim());
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`invalid port ${JSON.stringify(value)}: expected an integer between 1 and 65535`);
+        throw new Error(`Invalid port ${JSON.stringify(value)} (from ${source}): use a whole number between 1 and 65535, for example --port 7070.`);
     }
     return port;
 }

package/dist/kernel/db/migrate.js

@@ -12,7 +12,8 @@ export function migrate(db, clock) {
     const newest = Math.max(0, ...applied);
     const newestKnown = Math.max(0, ...known);
     if (newest > newestKnown) {
-        throw new Error(`database schema ${newest} is newer than this app knows (${newestKnown})`);
+        throw new Error(`Your Slopify database was last used by a newer version of Slopify (database schema ${newest} is newer than this app knows (${newestKnown})). ` +
+            "Update Slopify and start it again: npx @gentbajko/slopify@latest (or pull the latest Docker image). Your data was not changed.");
     }
     for (const [index, file] of files.entries()) {
         const version = known[index];

package/dist/kernel/db/migrations/0013-schedule-topic-queue.sql

@@ -0,0 +1,4 @@
+-- A schedule's items became a queue of topics: each run fills one template keyword with the
+-- first topic and the rest of the keywords with fixed values.
+ALTER TABLE schedules ADD COLUMN topic_keyword TEXT;
+ALTER TABLE schedules ADD COLUMN values_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(values_json));

package/dist/kernel/errors.js

@@ -0,0 +1,12 @@
+// A failure's own sentence and every cause it wraps, for the log. The page shows only the
+// sentence; the chain is the only place a "download interrupted" says the server closed the
+// stream.
+export function causedBy(error) {
+    const chain = [error instanceof Error ? error.message : String(error)];
+    let cause = error instanceof Error ? error.cause : undefined;
+    while (cause !== undefined && cause !== null && chain.length < 6) {
+        chain.push(cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause));
+        cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return chain.join(" <- ");
+}

package/dist/kernel/lock.js

@@ -6,14 +6,15 @@ export function acquireInstanceLock(lockPath) {
     if (!claim(lockPath, pid)) {
         const holder = holderOf(lockPath);
         if (holder !== undefined && holds(holder, pid)) {
-            throw new Error(`another Slopify instance is already running on this data directory (pid ${holder.pid}). ` +
-                `Stop it, or delete ${lockPath} if it is stale.`);
+            throw new Error(`Slopify is already running on this data directory (process ${holder.pid}). ` +
+                "Use the copy that is already open, or stop it (Ctrl+C in its terminal) and start again. " +
+                `If no Slopify is running, delete ${lockPath} and try again.`);
         }
         // The recorded process is gone, or the file says nothing usable. Reclaiming it here
         // is what keeps a crash from bricking the data directory until a file is deleted by hand.
         discard(lockPath);
         if (!claim(lockPath, pid)) {
-            throw new Error(`could not take the instance lock at ${lockPath}: another process was faster`);
+            throw new Error(`Another Slopify started on this data directory at the same moment (lock file ${lockPath}). Close the extra copy and start Slopify again.`);
         }
     }
     return {