@gentbajko/slopify 2.0.2 → 2.1.0

package/dist/catalog/registry.js

@@ -7,7 +7,7 @@ export function curateRegistry(registry, catalogue) {
         if (!model)
             throw providerError({
                 kind: "unsupported",
-                message: `${provider}: this model is not enabled in the current catalogue. Choose a supported model in Run settings.`,
+                message: `The chosen ${provider} model is no longer in Slopify's model list. In the Edit tab, choose Edit project and change it under Providers, then use Resume.`,
             });
         return model;
     };
@@ -21,7 +21,10 @@ export function curateRegistry(registry, catalogue) {
                     models: () => port.models(),
                     complete: async function* (request) {
                         if (request.model.trim() === "")
-                            throw providerError({ kind: "unsupported", message: "Choose a model ID." });
+                            throw providerError({
+                                kind: "unsupported",
+                                message: "No model is chosen for this step. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
+                            });
                         let models;
                         try {
                             models = await port.models();
@@ -34,19 +37,19 @@ export function curateRegistry(registry, catalogue) {
                         if (models !== undefined && selected === undefined)
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This model is not available in the installed CLI.",
+                                message: "The chosen model is not available in the AI command-line tool on your computer. Update the tool, or pick another model: in the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                             });
                         if (request.thinking !== undefined &&
                             selected !== undefined &&
                             !selected.thinkingModes?.includes(request.thinking))
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This model does not support the selected thinking setting.",
+                                message: "The chosen model does not support this thinking setting. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                             });
                         if (request.webSearch && !port.capabilities.webSearch)
                             throw providerError({
                                 kind: "unsupported",
-                                message: "This CLI does not support research web search.",
+                                message: "This command-line tool cannot search the web for research. Choose another text provider or turn Research off in the Edit tab under Edit project, then use Resume.",
                             });
                         const thinkingConfig = id === "codex" && request.thinking !== undefined
                             ? { effort: request.thinking === "off" ? "none" : request.thinking }
@@ -75,13 +78,13 @@ export function curateRegistry(registry, catalogue) {
                     if (request.webSearch && !model.llm.webSearch)
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support research web search.",
+                            message: "The chosen model cannot search the web for research. Choose another model or turn Research off in the Edit tab under Edit project, then use Resume.",
                         });
                     const thinkingConfig = request.thinking === undefined ? undefined : model.llm.thinking?.[request.thinking];
                     if (request.thinking !== undefined && !thinkingConfig)
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support the selected thinking setting. Choose an available setting.",
+                            message: "The chosen model does not support this thinking setting. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                         });
                     yield* port.complete({
                         ...request,
@@ -100,7 +103,7 @@ export function curateRegistry(registry, catalogue) {
                         if (!(await port.models()).some((model) => model.id === request.model))
                             throw providerError({
                                 kind: "unsupported",
-                                message: "The Codex image capability is unavailable.",
+                                message: "Image generation is not available in the Codex CLI on your computer. Update Codex CLI, or choose another image provider in the Edit tab under Edit project, then use Resume.",
                             });
                         return port.generate(request);
                     },
@@ -114,7 +117,7 @@ export function curateRegistry(registry, catalogue) {
                     if (!("image" in model) || !model.image.aspectRatios.includes(request.aspect))
                         throw providerError({
                             kind: "unsupported",
-                            message: "This model does not support the selected video shape.",
+                            message: "The chosen image model cannot make images in this video's shape. In the Edit tab, choose Edit project and change it under Providers, then use Resume.",
                         });
                     return port.generate(request);
                 },
@@ -135,7 +138,7 @@ export function curateRegistry(registry, catalogue) {
                     if (request.text.length > model.tts.maxCharacters)
                         throw providerError({
                             kind: "unsupported",
-                            message: `${id}: this physical narration request exceeds the current ${model.tts.maxCharacters}-character limit. Rebuild narration to split it using the new limit.`,
+                            message: `A piece of narration is longer than this voice model's ${model.tts.maxCharacters}-character limit. Use Re-run section on Audio so Slopify splits it into shorter pieces.`,
                         });
                     return port.synthesize({ ...request, model: model.id });
                 },

package/dist/catalog/store.js

@@ -40,7 +40,7 @@ export function createCatalogueStore(deps) {
         }
         catch {
             warning =
-                "Your models.yaml is unavailable or invalid. The last valid catalogue is still in use.";
+                "Your models.yaml file is missing or has a mistake, so Slopify is still using the last working model list. Fix the file, or use Refresh published catalogue in Settings → Models to replace it.";
         }
         return current;
     }

package/dist/catalog/validate.js

@@ -1,4 +1,4 @@
-import { usesNarrationPreparation } from "../slices/admission/rules.js";
+import { usesNarrationPreparation, usesYoutubeDescription, } from "../slices/admission/rules.js";
 import { isLocalCliProvider } from "../slices/settings/model.js";
 export function modelFields(draft, catalogue) {
     if (!catalogue)
@@ -9,7 +9,8 @@ export function modelFields(draft, catalogue) {
         draft.sources.thumbnail === "prompt_by_llm" ||
         draft.intro?.mode === "llm" ||
         draft.outro?.mode === "llm" ||
-        usesNarrationPreparation(draft);
+        usesNarrationPreparation(draft) ||
+        usesYoutubeDescription(draft);
     const checks = [
         { field: "llm", family: "llm", choice: draft.llm, needed: needLlm },
         {
@@ -31,16 +32,25 @@ export function modelFields(draft, catalogue) {
             continue;
         const model = catalogue.models(choice.provider, family).find((m) => m.id === choice.model);
         if (!model)
-            fields.push({ field, message: "Choose an enabled model from the current catalogue." });
+            fields.push({
+                field,
+                message: "This model is no longer in Slopify's model list. Choose another model.",
+            });
         else if ("llm" in model && choice.thinking && !model.llm.thinking?.[choice.thinking])
-            fields.push({ field, message: "Choose a supported thinking setting for this model." });
+            fields.push({
+                field,
+                message: "This model does not support that thinking setting. Choose another.",
+            });
         else if ("llm" in model && draft.sources.research === "generate" && !model.llm.webSearch)
             fields.push({
                 field,
-                message: "This model cannot perform web research. Choose another or turn Research off.",
+                message: "This model cannot search the web for research. Choose another model or turn Research off.",
             });
         else if ("image" in model && !model.image.aspectRatios.includes(draft.format))
-            fields.push({ field, message: "This image model does not support the selected shape." });
+            fields.push({
+                field,
+                message: "This image model cannot make images in this video's shape. Choose another model.",
+            });
     }
     return fields;
 }

package/dist/edge/cli.js

@@ -23,17 +23,18 @@ const { values } = parseArgs({
         "accept-host-cli": { type: "boolean" },
     },
 });
+let config;
 try {
     if (values["projects-dir"] !== undefined && !values.docker)
-        throw new Error("--projects-dir requires --docker; native installs use --data-dir.");
+        throw new Error("--projects-dir only works together with --docker. Without Docker, choose where Slopify keeps its files with --data-dir <folder>.");
     if ((values["host-cli"] !== undefined || values["accept-host-cli"] !== undefined) &&
         !values.docker)
-        throw new Error("Host CLI options require --docker.");
+        throw new Error("--host-cli and --accept-host-cli only work together with --docker. Add --docker, or remove those options.");
     if (values["host-cli"] !== undefined && values["host-cli"] !== "off")
-        throw new Error("The --host-cli override supports only off (API-only Docker).");
+        throw new Error(`--host-cli=${values["host-cli"]} is not supported. The only value is --host-cli=off, which starts Docker using API keys only; leave the option out to use the AI CLIs installed on this machine.`);
     if (values.docker) {
         if (values.host !== undefined || values["data-dir"] !== undefined)
-            throw new Error("Docker keeps private data in its named volume and binds to localhost. Use --projects-dir for project files and --port for the port.");
+            throw new Error("--host and --data-dir can't be used with --docker: the Docker version always listens on localhost and keeps its data in a Docker volume. Use --projects-dir <folder> for project files and --port <number> for the port.");
         const docker = await import("./docker.js");
         docker.assertManagedDockerHost(process.platform, process.getuid?.(), process.getgid?.());
         const { prepareDockerHostCli } = docker;
@@ -73,10 +74,10 @@ try {
             },
         });
         if (result.error)
-            throw result.error;
+            throw new Error(`Could not start the Docker launcher script (${result.error.message}). Make sure bash is installed and on your PATH, then try again.`);
         process.exit(result.status ?? 1);
     }
-    const config = configFrom(values, process.env);
+    config = configFrom(values, process.env);
     const forwarded = await forwardManagedUpdate(config.dataDir, readVersion(), process.argv.slice(2));
     if (forwarded !== undefined)
         process.exit(forwarded);
@@ -103,6 +104,31 @@ try {
     });
 }
 catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(explainStartupError(error, config));
     process.exit(1);
 }
+// Node's own wording for a failed listen or file operation ("listen EADDRINUSE: address already
+// in use") names the symptom but not the fix, so the common startup failures are restated here.
+function explainStartupError(error, config) {
+    if (!(error instanceof Error))
+        return String(error);
+    const code = "code" in error && typeof error.code === "string" ? error.code : undefined;
+    const syscall = "syscall" in error && typeof error.syscall === "string" ? error.syscall : "";
+    if (config !== undefined && syscall === "listen") {
+        const other = config.port === 7070 ? 7071 : 7070;
+        if (code === "EADDRINUSE")
+            return `Port ${config.port} is already in use by another program (maybe another Slopify). Stop that program, or start Slopify on another port: npx @gentbajko/slopify --port ${other}`;
+        if (code === "EACCES" || code === "EPERM")
+            return `Slopify is not allowed to use port ${config.port}${config.port < 1024 ? " (ports below 1024 need administrator rights)" : ""}. Start it on another port: npx @gentbajko/slopify --port ${other}`;
+        if (code === "EADDRNOTAVAIL" || code === "ENOTFOUND" || code === "EAI_AGAIN")
+            return `Slopify can't listen on ${config.host} because that address doesn't belong to this machine. Leave out --host (and SLOPIFY_HOST) to use 127.0.0.1, or use an address this machine owns.`;
+    }
+    const path = "path" in error && typeof error.path === "string" ? error.path : undefined;
+    if (config !== undefined &&
+        path?.startsWith(config.dataDir) &&
+        (code === "EACCES" || code === "EPERM" || code === "EROFS"))
+        return `Slopify can't write to its data folder ${config.dataDir} (${error.message}). Make sure your user owns that folder and can write to it, or choose another one: npx @gentbajko/slopify --data-dir <folder>`;
+    if (code === "ENOSPC")
+        return `The disk is full (${error.message}). Free up some space and start Slopify again.`;
+    return error.message;
+}

package/dist/edge/docker-launch.js

@@ -15,7 +15,7 @@ async function main() {
     const gid = process.getgid?.();
     assertManagedDockerHost(process.platform, uid, gid);
     if (gid === undefined)
-        throw new Error("Missing host group.");
+        throw new Error("Could not read your user's group. Run the --docker launcher as your normal logged-in user.");
     const c = dockerConfig(process.env, homedir(), process.cwd(), uid, gid);
     await privateDirectory(c.root, uid);
     if (process.argv[2] !== "--locked") {
@@ -24,7 +24,7 @@ async function main() {
         try {
             const s = await fd.stat();
             if (!s.isFile() || s.nlink !== 1 || s.uid !== uid || (s.mode & 0o077) !== 0)
-                throw new Error("Unsafe Docker setup lock.");
+                throw new Error(`The launcher's lock file ${path} has the wrong owner or permissions. Delete it and run the launcher again.`);
             const child = spawn("flock", [
                 "--nonblock",
                 "--no-fork",
@@ -36,13 +36,13 @@ async function main() {
                 "--locked",
             ], { stdio: "inherit" });
             const code = await new Promise((resolve, reject) => {
-                child.once("error", () => reject(new Error("Install util-linux (flock) before using the managed Docker launcher.")));
+                child.once("error", () => reject(new Error("The --docker launcher needs the flock command, which isn't installed. Install util-linux (for example sudo apt install util-linux, or sudo pacman -S util-linux) and try again.")));
                 child.once("exit", (status, signal) => signal
-                    ? reject(new Error("Docker setup was interrupted; rerun to recover."))
+                    ? reject(new Error("Docker setup was interrupted before it finished. Run the same command again; Slopify will finish or undo the half-done step."))
                     : resolve(status ?? 1));
             });
             if (code === 73)
-                throw new Error("Another managed Docker installation is changing storage. Wait for it to finish and rerun.");
+                throw new Error("Another Slopify --docker launcher is already running and changing your installation. Wait for it to finish, then run the command again.");
             process.exitCode = code;
             return;
         }
@@ -51,7 +51,7 @@ async function main() {
         }
     }
     const controller = new AbortController();
-    const abort = () => controller.abort(new Error("Docker setup interrupted."));
+    const abort = () => controller.abort(new Error("Docker setup was stopped before it finished. Run the same command again; Slopify will finish or undo the half-done step."));
     process.once("SIGINT", abort);
     process.once("SIGTERM", abort);
     try {

package/dist/edge/docker-projects/engine.js

@@ -4,12 +4,27 @@ import { setTimeout as delay } from "node:timers/promises";
 import { z } from "zod";
 import { containerSchema, digestSchema, } from "./state.js";
 import { contains } from "./tree.js";
+// Docker's exit code alone says nothing, so its last error line decides the advice: the daemon
+// being stopped and the socket being off-limits are by far the most common first-run failures.
+export function dockerFailure(args, result) {
+    const detail = (result.stderr ?? "").trim();
+    if (/permission denied[^\n]*docker\.sock|docker\.sock[^\n]*permission denied/i.test(detail))
+        return "Your user isn't allowed to use Docker. Give it access with sudo usermod -aG docker $USER, then log out and back in (or run newgrp docker) and try again.";
+    if (/cannot connect to the docker daemon|is the docker daemon running|error during connect/i.test(detail))
+        return "Docker is installed but not running. Start it (sudo systemctl start docker, or systemctl --user start docker for rootless Docker) and try again.";
+    if (/port is already allocated|address already in use/i.test(detail))
+        return "The port Slopify wants is already in use by another program. Stop that program, or start Slopify on another port: npx @gentbajko/slopify --docker --port 7070";
+    if (/no space left on device/i.test(detail))
+        return "The disk Docker uses is full. Free up space (for example docker system prune) and try again.";
+    const last = detail.split("\n").at(-1)?.trim().slice(0, 300);
+    return `Docker command "docker ${args[0] ?? ""}" failed (exit code ${result.code}${last ? `: ${last}` : ""}). Check that Docker works (docker info) and run the launcher again. Nothing was deleted, and any backup Slopify made is kept.`;
+}
 export function dockerEngine(runner, signal, env) {
     const run = (args, localSignal = signal) => runner.exec("docker", args, localSignal);
     async function command(args, localSignal = signal) {
         const r = await run(args, localSignal);
         if (r.code !== 0)
-            throw new Error(`Docker ${args[0] ?? "command"} failed; recovery material is retained.`);
+            throw new Error(dockerFailure(args, r));
         return r.stdout.trim();
     }
     const mount = (type, source, target, readonly = false) => [
@@ -48,14 +63,14 @@ export function dockerEngine(runner, signal, env) {
             "{{.ID}}",
         ]);
         if (present.code !== 0)
-            throw new Error("Docker container inventory failed.");
+            throw new Error(dockerFailure(["container", "ls"], present));
         if (!present.stdout.trim() && !/^[a-f0-9]{12,64}$/.test(name))
             return null;
         const result = await run(["inspect", name]);
         if (result.code !== 0) {
             if (!present.stdout.trim())
                 return null;
-            throw new Error("Docker inspect failed.");
+            throw new Error(dockerFailure(["inspect", name], result));
         }
         const schema = z.array(z.object({
             Id: z.string(),
@@ -105,11 +120,11 @@ export function dockerEngine(runner, signal, env) {
         for (const id of ids) {
             const c = await inspect(id);
             if (!c)
-                throw new Error("Cannot verify volume claims; an inventoried container is missing.");
+                throw new Error("Cannot verify volume claims: a Docker container disappeared while Slopify was checking. Run the launcher again.");
             if (!permitted.includes(c.id) &&
                 !spared(c) &&
                 c.mounts.some((m) => m.type === "volume" && m.name === volume))
-                throw new Error(`Another container claims installation volume ${volume}: ${c.name}.`);
+                throw new Error(`The Docker volume ${volume} that holds Slopify's data is also used by the container ${c.name}. Remove that container if you no longer need it (docker rm ${c.name}), or give this Slopify its own volume with SLOPIFY_DOCKER_VOLUME=<name>, then try again.`);
         }
     }
     async function writers(volume, paths, permitted) {
@@ -122,7 +137,7 @@ export function dockerEngine(runner, signal, env) {
                 (m.name === volume ||
                     (m.type === "bind" &&
                         paths.some((p) => contains(p, m.source) || contains(m.source, p))))))
-                throw new Error(`Another running container writes installation storage: ${c.name}. Stop it before retrying.`);
+                throw new Error(`Another running container (${c.name}) is writing to Slopify's data or project folder. Stop it (docker stop ${c.name}) and try again.`);
         }
     }
     async function recoveryLabel(j) {
@@ -154,7 +169,13 @@ export function dockerEngine(runner, signal, env) {
                     .parse(raw)[0]?.Endpoints.docker.Host;
             }
             if (!endpoint?.startsWith("unix://"))
-                throw new Error("Managed folders require a local Linux Docker unix socket; remote daemons are unsupported.");
+                throw new Error(`The --docker launcher only works with Docker running on this machine, not a remote Docker (${endpoint ?? "unknown endpoint"}). Switch to the local one (unset DOCKER_HOST, or docker context use default) and try again.`);
+            const rawInfo = JSON.parse(await command(["info", "--format", "{{json .}}"]));
+            // Some Docker versions print the daemon's absence inside the JSON instead of failing.
+            const serverErrors = z.object({ ServerErrors: z.array(z.string()) }).safeParse(rawInfo)
+                .data?.ServerErrors;
+            if (serverErrors !== undefined && serverErrors.length > 0)
+                throw new Error(dockerFailure(["info"], { code: 1, stderr: serverErrors.join("\n") }));
             const info = z
                 .object({
                 ID: z.string(),
@@ -162,12 +183,12 @@ export function dockerEngine(runner, signal, env) {
                 OperatingSystem: z.string(),
                 SecurityOptions: z.array(z.string()),
             })
-                .parse(JSON.parse(await command(["info", "--format", "{{json .}}"])));
+                .parse(rawInfo);
             if (/docker desktop/i.test(info.OperatingSystem))
-                throw new Error("Docker Desktop is unsupported by managed project folders. Use a native Linux Docker daemon or native Slopify.");
+                throw new Error("Docker Desktop isn't supported by the --docker launcher because it can't give your project folder the right owner. Use Docker Engine on Linux (docker context use default), or run Slopify without Docker: npx @gentbajko/slopify");
             const rootless = info.SecurityOptions.includes("name=rootless");
             if (!rootless && info.SecurityOptions.some((s) => s.startsWith("name=userns")))
-                throw new Error("Docker userns-remap is unsupported by managed project folders. Use a supported rootless daemon or native Slopify; do not disable isolation.");
+                throw new Error("Your Docker uses userns-remap, which the --docker launcher doesn't support. Use rootless Docker or a standard Docker Engine setup, or run Slopify without Docker: npx @gentbajko/slopify. Don't turn off Docker's isolation to get around this.");
             return { daemon: info.ID, user: rootless ? "0:0" : `${uid}:${gid}` };
         },
         image: async (ref) => {
@@ -214,7 +235,7 @@ export function dockerEngine(runner, signal, env) {
             })
                 .parse(JSON.parse(await command(["volume", "inspect", "--format", "{{json .}}", name])));
             if (v.Name !== name || (v.Options && Object.keys(v.Options).length > 0))
-                throw new Error("Managed projects require an ordinary local named volume; remote/custom volume drivers are unsupported.");
+                throw new Error(`The Docker volume ${name} uses a custom driver or options, which Slopify doesn't support. Give Slopify a plain local volume with SLOPIFY_DOCKER_VOLUME=<new name> and try again.`);
             return JSON.stringify([v.Name, v.CreatedAt, v.Driver]);
         },
         probe: async (c, image, user, destination) => {
@@ -228,7 +249,7 @@ export function dockerEngine(runner, signal, env) {
                     s.gid !== c.gid ||
                     (s.mode & 0o077) !== 0 ||
                     (await readFile(join(probe, "container"), "utf8")) !== "slopify ownership probe")
-                    throw new Error("Docker cannot create private files as this host user; ownership mapping is unsupported.");
+                    throw new Error("Docker can't create files in your project folder as your user, so the files would end up with the wrong owner. Use a standard Docker Engine or rootless Docker setup, or run Slopify without Docker: npx @gentbajko/slopify");
                 await writeFile(join(probe, "container"), "host can write", { flag: "a" });
             }
             finally {
@@ -378,7 +399,7 @@ export function dockerEngine(runner, signal, env) {
                 }
                 await delay(Math.min(250, Math.max(0, deadline - Date.now())), undefined, { signal });
             }
-            throw new Error("Replacement did not become healthy within 120 seconds.");
+            throw new Error(`The new Slopify container did not start up within 2 minutes. See why with: docker logs ${id}`);
         },
     };
 }

package/dist/edge/docker-projects/install.js

@@ -17,10 +17,10 @@ export async function installProjects(c, e, recovery) {
     const currentVolume = await e.volume(c.volume);
     if ((receipt && receipt.volumeIdentity !== currentVolume) ||
         (previousJournal?.volumeIdentity && previousJournal.volumeIdentity !== currentVolume))
-        throw new Error("Remembered data volume is missing or was replaced; restore the original volume before retrying.");
+        throw new Error(`Remembered data volume ${c.volume} is missing or was replaced since Slopify was installed. Restore the original volume (see docker volume ls) and run the launcher again. Nothing was changed.`);
     if ((receipt && receipt.daemon !== context.daemon) ||
         (previousJournal && previousJournal.daemon !== context.daemon))
-        throw new Error("Docker daemon differs from saved installation; select the original daemon.");
+        throw new Error("This is not the Docker that Slopify was installed with (a different Docker context or DOCKER_HOST is active). Switch back to the original one (docker context use <name>, or unset DOCKER_HOST) and try again.");
     await assertVolumeClaims(c, e, context.daemon, currentVolume, await e.inspect(c.name));
     if (previousJournal && previousJournal.phase !== "rolled-back")
         previousJournal = await recoverInstallation(c, previousJournal, receipt, recovery());
@@ -42,7 +42,7 @@ export async function installProjects(c, e, recovery) {
             continue;
         const other = await readState(join(c.root, name, "receipt.json"), receiptSchema, c.uid);
         if (other?.daemon === context.daemon && other.volume === c.volume)
-            throw new Error(`Named volume belongs to installation ${other.name}; select a separate volume.`);
+            throw new Error(`The Docker volume ${c.volume} already belongs to another Slopify installation (${other.name}). Give this one its own volume with SLOPIFY_DOCKER_VOLUME=<name> and try again.`);
     }
     let reuse = null;
     if (previousJournal?.phase === "rolled-back" &&
@@ -66,7 +66,7 @@ export async function installProjects(c, e, recovery) {
     const image = await e.image(c.image);
     const expectedVersion = await e.version(image);
     if (expectedVersion !== readVersion())
-        throw new Error("Docker image and installed launcher versions differ. Refresh the default release image or select the matching custom image before retrying; the existing container is unchanged.");
+        throw new Error(`The Docker image is Slopify ${expectedVersion} but this launcher is ${readVersion()}. Run the latest of both (npx @gentbajko/slopify@latest --docker), or if you set SLOPIFY_DOCKER_IMAGE, point it at version ${readVersion()}. Your existing container was not changed.`);
     const signature = createHash("sha256")
         .update(JSON.stringify([image, c.volume, c.port, c.bridge, projects, context.user]))
         .digest("hex");
@@ -228,19 +228,19 @@ export async function installProjects(c, e, recovery) {
         await save({ phase: "committed" });
         const ready = await e.inspect(candidate);
         if (!ready?.port)
-            throw new Error("Committed container has no localhost port; rerun the launcher.");
+            throw new Error("Slopify started but Docker did not report which port it is on. Run the same command again to finish.");
         return { url: `http://${ready.port}`, projects, recovery: j.backup };
     }
     catch (cause) {
         const current = await readState(receiptPath, receiptSchema, c.uid);
         if (current?.transaction === j.id)
-            throw new Error(`Installation committed at ${projects}; rerun the launcher to finish activation. Recovery volume: ${j.backup}`, { cause });
+            throw new Error(`Slopify was installed (project files at ${projects}) but the last step did not finish. Run the same command again to complete it. Backup volume: ${j.backup}`, { cause });
         try {
             await recoverInstallation(c, j, current, recovery());
         }
         catch (failure) {
-            throw new Error(`Recovery incomplete. Leave container/data stopped; recovery volume ${j.backup}, journal ${journalPath}, project folder ${projects}. ${failure instanceof Error ? failure.message : "Recovery operation failed."}`, { cause });
+            throw new Error(`Recovery incomplete: the install failed and Slopify could not fully undo it. Leave the Slopify container stopped and don't delete anything: backup volume ${j.backup}, progress file ${journalPath}, project folder ${projects}. Fix the problem below, then run the same command again. ${failure instanceof Error ? failure.message : "The undo step failed."}`, { cause });
         }
-        throw new Error(`Previous installation restored${old?.running ? " and restarted" : " without starting it"}. Recovery: ${j.backup}; project copy: ${projects}. ${cause instanceof Error ? cause.message : "Installation failed."}`, { cause });
+        throw new Error(`Install failed. Previous installation restored${old?.running ? " and restarted" : " (not started)"}, so nothing was lost. Backup volume: ${j.backup}; project copy: ${projects}. Reason: ${cause instanceof Error ? cause.message : "Installation failed."}`, { cause });
     }
 }

package/dist/edge/docker-projects/state.js

@@ -104,15 +104,19 @@ export const journalSchema = z
     token: z.string().regex(/^[a-f0-9]{64}$/),
 })
     .strict();
+/** Where the Docker launcher keeps one folder (and receipt) per installation. */
+export function dockerRoot(env, home) {
+    return join(absolute.parse(env.XDG_DATA_HOME || join(home, ".local/share")), "slopify/docker");
+}
 export function dockerConfig(env, home, cwd, uid, gid) {
     const name = identifier.parse(env.SLOPIFY_DOCKER_NAME || "slopify");
     const volume = identifier.parse(env.SLOPIFY_DOCKER_VOLUME || "slopify-data");
-    const root = join(absolute.parse(env.XDG_DATA_HOME || join(home, ".local/share")), "slopify/docker");
+    const root = dockerRoot(env, home);
     const raw = env.SLOPIFY_DOCKER_PROJECTS_DIR || null;
     const projectsOverride = raw === null ? null : resolve(cwd, raw.startsWith("~/") ? join(home, raw.slice(2)) : raw);
     const portText = env.SLOPIFY_DOCKER_HOST_PORT || "6969";
     if (!/^\d{1,5}$/.test(portText) || Number(portText) > 65535)
-        throw new Error("Docker host port must be from 0 to 65535.");
+        throw new Error(`Invalid port ${JSON.stringify(portText)}: use a whole number between 1 and 65535, for example --port 7070.`);
     return {
         home,
         uid,
@@ -144,11 +148,11 @@ export async function privateDirectory(path, uid) {
         if (!s.isDirectory() ||
             s.isSymbolicLink() ||
             ((s.mode & 0o022) !== 0 && (s.mode & 0o1000) === 0))
-            throw new Error("Unsafe private state ancestor.");
+            throw new Error(`${current} is not a normal folder, or other users can write to it, so Slopify won't keep its Docker settings under it. Fix its permissions (chmod go-w ${current}) or set XDG_DATA_HOME to another folder, then try again.`);
     }
     const s = await lstat(path);
     if (s.uid !== uid || (s.mode & 0o077) !== 0)
-        throw new Error("Installation state must be private and owned by the installing user.");
+        throw new Error(`${path} must belong to you and be private. Fix it with chmod 700 ${path} (and chown it to your user if needed), then try again.`);
 }
 export async function readState(path, schema, uid) {
     const s = await lstat(path).catch((error) => {
@@ -186,7 +190,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
             throw new Error("Receipt selects a different installation or volume.");
         await safePath(receipt.projects, c.home, c.root, false);
         await assertIdentity(receipt.projects, receipt.directoryIdentity).catch((cause) => {
-            throw new Error(`Remembered project folder is missing or replaced: ${receipt.projects}`, {
+            throw new Error(`Remembered project folder ${receipt.projects} is missing or was replaced. Put the original folder back where it was and run the launcher again.`, {
                 cause,
             });
         });
@@ -202,7 +206,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
     await safePath(chosen, c.home, c.root, true);
     const source = receipt?.projects ?? bind?.source;
     if (source && source !== chosen && (contains(source, chosen) || contains(chosen, source)))
-        throw new Error("Source and destination project folders cannot contain each other.");
+        throw new Error(`The new project folder ${chosen} and the current one ${source} are inside each other. Choose a separate folder with --projects-dir <folder>.`);
     if (chosen !== source) {
         const entries = await readdir(chosen).catch((error) => {
             if (isMissing(error))
@@ -211,7 +215,7 @@ export async function selectProjects(c, receipt, old, retry = null) {
         });
         if (entries.length > 0) {
             if (retry?.destination !== chosen || !retry.publishedIdentity || !retry.sourceDigest)
-                throw new Error(`Unrelated populated destination: ${chosen}`);
+                throw new Error(`The project folder ${chosen} already has files in it that Slopify didn't put there. Choose an empty or new folder with --projects-dir <folder>, or move those files away, then try again.`);
             await assertIdentity(chosen, retry.publishedIdentity);
             if ((await treeDigest(chosen)).hash !== retry.sourceDigest.hash)
                 throw new Error(`Published retry destination changed: ${chosen}`);

package/dist/edge/docker-projects/tree.js

@@ -19,7 +19,7 @@ export function contains(root, path) {
 }
 export async function safePath(path, home, stateRoot, createParents) {
     if (!isAbsolute(path) || resolve(path) !== path || /[\p{Cc},]/u.test(path))
-        throw new Error("Project directory must be a normal absolute path without commas/control characters.");
+        throw new Error(`The project folder ${JSON.stringify(path)} can't be used: give a full path without commas, for example --projects-dir ~/Slopify/Projects.`);
     const forbidden = [
         "/",
         "/home",
@@ -36,7 +36,7 @@ export async function safePath(path, home, stateRoot, createParents) {
         contains(stateRoot, path) ||
         contains(path, stateRoot) ||
         ["/proc", "/sys", "/dev", "/etc", "/usr", "/bin", "/sbin", "/lib", "/var/lib/docker"].some((p) => contains(p, path)))
-        throw new Error("Unsafe broad or private project directory.");
+        throw new Error(`${path} can't be the project folder because it is a system or shared folder (or holds Slopify's own settings). Choose a dedicated folder, for example --projects-dir ~/Slopify/Projects.`);
     const parts = path.split(sep).filter(Boolean);
     let current = sep;
     for (const [i, part] of parts.entries()) {
@@ -53,11 +53,11 @@ export async function safePath(path, home, stateRoot, createParents) {
         if (s === undefined)
             continue;
         if (!s.isDirectory() || s.isSymbolicLink())
-            throw new Error(`Unsafe path component: ${current}`);
+            throw new Error(`${current} is a file or a link, not a folder, so it can't be part of the project folder path. Choose another folder with --projects-dir <folder>.`);
         if (i === parts.length - 1 && (s.uid !== process.getuid?.() || (s.mode & 0o022) !== 0))
-            throw new Error("Project directory must belong to the installing user and must not be publicly writable.");
+            throw new Error(`The project folder ${path} must belong to you and must not be writable by other users. Fix it (chmod go-w ${path}) or choose another folder with --projects-dir <folder>.`);
         if (i < parts.length - 1 && (s.mode & 0o022) !== 0 && (s.mode & 0o1000) === 0)
-            throw new Error(`Writable project ancestor: ${current}`);
+            throw new Error(`Other users can write to ${current}, which contains the project folder. Choose a project folder inside your home folder with --projects-dir <folder>, or fix it with chmod go-w ${current}.`);
     }
 }
 export function isMissing(error) {
@@ -137,7 +137,7 @@ export async function assertWritableTree(root, uid) {
         (s.isFile() && s.nlink !== 1) ||
         s.uid !== uid ||
         (s.mode & (s.isDirectory() ? 0o700 : 0o600)) !== (s.isDirectory() ? 0o700 : 0o600))
-        throw new Error(`Existing project permissions are incompatible with this host user: ${root}`);
+        throw new Error(`${root} in your project files doesn't have permissions your user can fully use. Make it yours and writable (chown -R $USER ${root}; chmod -R u+rwX ${root}), then try again.`);
     if (s.isDirectory())
         for (const name of await readdir(root))
             await assertWritableTree(join(root, name), uid);