@gentbajko/slopify 2.0.2 → 2.1.0

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/open-folder.js

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { lstat, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { readState, receiptSchema } from "../edge/docker-projects/state.js";
+import { HostFolderRefused } from "../kernel/ports/host-cli.js";
+import { hasCode } from "./paths.js";
+const again = "run the Docker launcher again (npx @gentbajko/slopify@latest --docker)";
+/** Starts the desktop's opener and returns once it is running; the file manager is not awaited. */
+export function launchXdgOpen(directory) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("xdg-open", [directory], {
+            detached: true,
+            shell: false,
+            stdio: "ignore",
+        });
+        child.once("error", (error) => {
+            reject(new Error(hasCode(error, "ENOENT")
+                ? "xdg-open isn't installed on this machine, so the Slopify host helper can't open a file manager. Install xdg-utils (for example sudo pacman -S xdg-utils or sudo apt install xdg-utils), then use Open folder again."
+                : `The Slopify host helper could not start xdg-open to open ${directory}. Check that you are signed in to this computer's desktop, then use Open folder again.`));
+        });
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+/** Only folders inside a launcher receipt's project folder, reached through real folders you own, are opened. */
+export function createHostFolderOpener(deps) {
+    async function receipts() {
+        const found = [];
+        let entries;
+        try {
+            const root = await lstat(deps.root);
+            if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== deps.uid)
+                return [];
+            entries = await readdir(deps.root, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                const receipt = await readState(join(deps.root, entry.name, "receipt.json"), receiptSchema, deps.uid);
+                if (receipt)
+                    found.push(receipt);
+            }
+            catch {
+                // An unreadable or damaged receipt grants nothing; the others still count.
+            }
+        }
+        return found;
+    }
+    async function verify(projects, identity, r) {
+        const root = await lstat(projects, { bigint: true }).catch(() => undefined);
+        if (!root?.isDirectory() ||
+            root.isSymbolicLink() ||
+            root.uid !== BigInt(deps.uid) ||
+            String(root.dev) !== identity.dev ||
+            String(root.ino) !== identity.ino)
+            throw new HostFolderRefused(`The Slopify host helper did not open this folder because the project folder ${projects} was moved or replaced since the Docker launcher set it up. Put the original folder back, or ${again}.`);
+        let current = projects;
+        for (const part of r === "" ? [] : r.split(sep)) {
+            current = join(current, part);
+            const s = await lstat(current).catch(() => undefined);
+            if (!s?.isDirectory() || s.isSymbolicLink() || s.uid !== deps.uid)
+                throw new HostFolderRefused(`The Slopify host helper did not open ${current} because it is missing, a link or a file, or isn't owned by you. Use Re-run section on the project page to make the file again, or copy the path into your file manager.`);
+        }
+    }
+    return async (path) => {
+        if (!isAbsolute(path) || /[\p{Cc}]/u.test(path))
+            throw new HostFolderRefused(`The Slopify host helper did not open this folder because Slopify sent a path it can't use. Update Slopify: ${again}.`);
+        let refusal;
+        for (const receipt of await receipts()) {
+            const r = relative(receipt.projects, path);
+            if (r === ".." || r.startsWith(`..${sep}`) || isAbsolute(r))
+                continue;
+            try {
+                await verify(receipt.projects, receipt.directoryIdentity, r);
+            }
+            catch (error) {
+                if (!(error instanceof HostFolderRefused))
+                    throw error;
+                refusal = error;
+                continue;
+            }
+            // Open the normalised path that was checked, never the caller's spelling of it.
+            await deps.launch(join(receipt.projects, r));
+            return;
+        }
+        throw (refusal ??
+            new HostFolderRefused(`The Slopify host helper did not open ${path} because it isn't inside a project folder set up by the Docker launcher. Copy the path into your file manager, or if you moved your project folder, ${again}.`));
+    };
+}

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/runtime.js

@@ -9,6 +9,7 @@ import { nodeCodexModels } from "../adapters/llm/codex-models.js";
 import { geminiLlm } from "../adapters/llm/gemini.js";
 import { nodeGeminiModels } from "../adapters/llm/gemini-models.js";
 import { providerError } from "../kernel/ports/model.js";
+import { createHostFolderOpener } from "./open-folder.js";
 import { createHostStatus } from "./status.js";
 export function createHostRuntime(deps) {
     const status = createHostStatus(deps);
@@ -32,6 +33,7 @@ export function createHostRuntime(deps) {
     };
     return {
         status,
+        ...(deps.folders === undefined ? {} : { openFolder: createHostFolderOpener(deps.folders) }),
         llm: (id) => ({
             id,
             capabilities: { streams: true, reportsUsage: true, webSearch: true },

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,16 +12,32 @@ 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];
         if (version === undefined || applied.has(version)) {
             continue;
         }
+        const sql = readFileSync(new URL(file, migrationsDir), "utf8");
+        // A migration that rebuilds a table other tables reference must run with enforcement
+        // off: dropping the old table would otherwise cascade into every row that points at it.
+        // SQLite ignores this pragma inside a transaction, so it is set around one, and every
+        // reference is checked before the rebuild commits.
+        const rebuild = sql.split("\n", 1)[0]?.trim() === foreignKeysOff;
+        const enforced = rebuild && foreignKeysOn(db);
+        if (enforced)
+            db.exec("PRAGMA foreign_keys = OFF");
         db.exec("BEGIN");
         try {
-            db.exec(readFileSync(new URL(file, migrationsDir), "utf8"));
+            db.exec(sql);
+            if (rebuild) {
+                const broken = db.prepare("PRAGMA foreign_key_check").all();
+                if (broken.length > 0) {
+                    throw new Error(`Slopify couldn't upgrade its database: migration ${file} would leave ${broken.length} broken links between saved records, so it was undone and your data was not changed. Go back to the previous version of Slopify (npx @gentbajko/slopify@<previous version>) and report this on GitHub with the Download diagnostics file from Settings.`);
+                }
+            }
             db.prepare("INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)").run(version, clock.now().toISOString());
             db.exec("COMMIT");
         }
@@ -29,8 +45,17 @@ export function migrate(db, clock) {
             db.exec("ROLLBACK");
             throw error;
         }
+        finally {
+            if (enforced)
+                db.exec("PRAGMA foreign_keys = ON");
+        }
     }
 }
+// The first line of such a migration, compared without its line ending.
+const foreignKeysOff = "-- foreign-keys: off";
+function foreignKeysOn(db) {
+    return db.prepare("PRAGMA foreign_keys").get()?.foreign_keys === 1;
+}
 function versionOf(file) {
     const version = Number(file.slice(0, 4));
     if (!Number.isInteger(version) || version < 1) {

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));