@gentbajko/slopify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gent Bajko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Slopify
+
+A prompt and a few keywords in. A narrated slideshow video out. Your keys, your machine, free.
+
+```sh
+npx @gentbajko/slopify@latest
+```
+
+That opens a browser at `http://127.0.0.1:4242`. Nothing to configure first; add
+provider keys on the Settings screen when you want a stage to generate rather than
+take what you paste in.
+
+Six stages run as a graph: research, article, narration, images, thumbnail, video.
+Generate any of them, or provide the output yourself and that stage is skipped. The
+video is a slideshow with alternating zoom over the narration, rendered with ffmpeg.
+
+## Options
+
+| Flag | Environment variable | Default |
+|---|---|---|
+| `--port` | `SLOPIFY_PORT` | `4242` |
+| `--host` | `SLOPIFY_HOST` | `127.0.0.1` |
+| `--data-dir` | `SLOPIFY_DATA_DIR` | `~/.slopify` |
+| `--no-open` | `SLOPIFY_NO_OPEN` | the browser opens |
+| — | `SLOPIFY_FFMPEG` | the bundled binary |
+
+There is no login. Binding to anything but `127.0.0.1` hands the app and every key in
+it to whoever reaches the port, and the CLI says so on startup.
+
+Everything lives in one SQLite file and one directory tree under the data directory:
+`slopify.db`, `projects/`, `staging/`, `logs/`. Delete it and nothing of yours remains.
+
+## ffmpeg and the GPL
+
+Slopify renders video with ffmpeg. The `ffmpeg-static` dependency downloads a
+prebuilt binary to `node_modules/ffmpeg-static/` at install time.
+
+That binary is a separate program, run as a child process with an argument array. It
+is licensed under the **GPL-3.0-or-later**. Slopify does not link against it, does not
+embed it, and does not distribute it inside this package; its licence text and the
+location of its corresponding source ship beside it in `ffmpeg-static`. Slopify's own
+code is MIT and stays MIT. Anyone redistributing the downloaded binary takes on the
+GPL's obligations for it, including offering that corresponding source.
+
+Point `SLOPIFY_FFMPEG` at your own build to use that instead.
+
+## Telemetry
+
+Slopify sends anonymous counters to a collector: installs, projects created, stages
+completed, images and videos made, audio seconds, provider and model names, token
+counts, and the time each of those happened. Every event carries a random id of its
+own and this machine's random id, and nothing else.
+
+Never your keys, prompts, keywords, titles, article text, filenames, or anything about
+your machine. A notice says all of this the first time you run it, before the machine
+id exists, and the Usage screen shows you your own numbers at any time.
+
+## Licence
+
+MIT. The ffmpeg binary fetched at install time is a separate GPL-3.0-or-later program,
+as described above.
+
+Source, issues and the full guide: <https://github.com/GentBajko/slopify>

package/dist/adapter-registry.js

@@ -0,0 +1,68 @@
+import { falImage } from "./adapters/image/fal.js";
+import { openAiImage } from "./adapters/image/openai.js";
+import { replicateImage } from "./adapters/image/replicate.js";
+import { claudeCodeLlm } from "./adapters/llm/claude-code.js";
+import { codexLlm } from "./adapters/llm/codex.js";
+import { openRouterLlm } from "./adapters/llm/openrouter.js";
+import { cartesiaTts } from "./adapters/tts/cartesia.js";
+import { elevenLabsTts } from "./adapters/tts/elevenlabs.js";
+import { openAiTts } from "./adapters/tts/openai.js";
+import { keyForAttempt } from "./slices/settings/keys.js";
+import { providerStatuses } from "./slices/settings/readiness.js";
+export function buildRegistry(deps) {
+    // `logic/02` §Q16: read per request, never held, so an attempt in flight finishes on
+    // the key it started with and the next one picks up a key saved since. The closure is
+    // handed to the one adapter that provider belongs to and to nothing else (§Q18).
+    const keyOf = (provider) => () => {
+        const found = keyForAttempt({ db: deps.db, clock: deps.clock }, provider);
+        return found.ok ? found.key : undefined;
+    };
+    const llms = new Map([
+        ["openrouter", openRouterLlm({ fetch: deps.fetch, key: keyOf("openrouter") })],
+        // No key: both CLIs authenticate with their own login (`logic/02` §Q135).
+        ["claude-code", claudeCodeLlm({ run: deps.spawn })],
+        ["codex", codexLlm({ run: deps.spawn })],
+    ]);
+    // One key per provider (`logic/02` invariant), so each adapter is handed the reader for
+    // its own row and no other. OpenAI keeps two rows because it ships an adapter in two
+    // families and a user may key one without the other (`slices/settings/model.ts`).
+    const ttses = new Map([
+        ["elevenlabs", elevenLabsTts({ fetch: deps.fetch, key: keyOf("elevenlabs") })],
+        ["openai-tts", openAiTts({ fetch: deps.fetch, key: keyOf("openai-tts") })],
+        ["cartesia", cartesiaTts({ fetch: deps.fetch, key: keyOf("cartesia") })],
+    ]);
+    // `logic/09` and `logic/02` §Q15: three image providers behind one port, each handed
+    // the reader for its own key row. Replicate also takes the clock: `Prefer: wait` gives
+    // up after 60 s and the prediction has to be polled, and the wait is spent on the
+    // app's clock so a test never sits through one.
+    const images = new Map([
+        ["fal", falImage({ fetch: deps.fetch, key: keyOf("fal") })],
+        [
+            "replicate",
+            replicateImage({ fetch: deps.fetch, key: keyOf("replicate"), clock: deps.clock }),
+        ],
+        ["openai-image", openAiImage({ fetch: deps.fetch, key: keyOf("openai-image") })],
+    ]);
+    return {
+        llm: (id) => resolve(llms, "llm", id),
+        tts: (id) => resolve(ttses, "tts", id),
+        image: (id) => resolve(images, "image", id),
+        // `logic/02` step 5: every supported provider, keyed or not, found or not, so Play
+        // can grey one out with a reason instead of hiding it.
+        list: async () => (await providerStatuses({ db: deps.db, probe: deps.probe })).map((status) => ({
+            family: status.family,
+            id: status.id,
+            name: status.displayName,
+            readiness: status.readiness,
+        })),
+    };
+}
+// The Registry contract: an id the catalogue does not carry is a bug in admission, not a
+// user error, so it throws rather than answering undefined.
+function resolve(ports, family, id) {
+    const port = ports.get(id);
+    if (port === undefined) {
+        throw new Error(`no ${family} adapter is registered for ${id}`);
+    }
+    return port;
+}

package/dist/adapters/image/bytes.js

@@ -0,0 +1,64 @@
+import { providerError } from "../../kernel/ports/model.js";
+// Two of the three image providers answer with a link rather than with bytes, so fetching
+// that link is part of the provider call and belongs inside the attempt with it: a URL
+// that 404s or hands back an HTML error page is a failed attempt, not a corrupt file on
+// disk. It sits beside the adapters, as `retry-after.ts` does, because the rule is the
+// port's - `GeneratedImage` is a PNG or a JPEG and nothing else - rather than any one
+// vendor's. Nothing else is shared between the three adapters.
+const png = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const jpeg = [0xff, 0xd8, 0xff];
+// Not a format the port carries, but the likeliest wrong answer: it is what most
+// diffusion models return by default, so naming it turns a puzzling failure into one
+// sentence the user can act on.
+const riff = [0x52, 0x49, 0x46, 0x46];
+const webp = [0x57, 0x45, 0x42, 0x50];
+// The bytes decide, never the Content-Type header. A CDN in front of an expired link
+// serves `image/png` over an HTML error page often enough to be worth not trusting, and
+// the mime is stored with the file and becomes its extension (`logic/09` step 3).
+export function sniffImage(bytes) {
+    if (startsWith(bytes, png, 0)) {
+        return "image/png";
+    }
+    return startsWith(bytes, jpeg, 0) ? "image/jpeg" : undefined;
+}
+// What to call what arrived when it is not an image, without echoing bytes that may be a
+// signed URL, a key quoted back, or a megabyte of HTML.
+export function describeBytes(bytes) {
+    if (bytes.length === 0) {
+        return "an empty body";
+    }
+    if (startsWith(bytes, riff, 0) && startsWith(bytes, webp, 8)) {
+        return "a WebP image";
+    }
+    return `${String(bytes.length)} bytes beginning ${hex(bytes)}`;
+}
+export async function downloadImage(download) {
+    const response = await download.fetch(download.url, { signal: download.signal });
+    if (!response.ok) {
+        // `other`, so the attempt wrapper retries it: a link that is not ready yet or a CDN
+        // hiccup is exactly the transient failure the retry policy exists for. The URL is not
+        // quoted back - a fal or Replicate delivery link carries its own signature.
+        throw providerError({
+            kind: "other",
+            message: `${download.provider} answered ${String(response.status)} for the image it said it had made`,
+        });
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const mime = sniffImage(bytes);
+    if (mime === undefined) {
+        throw providerError({
+            kind: "other",
+            message: `${download.provider}'s image link answered with ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+        });
+    }
+    return { bytes, mime };
+}
+function startsWith(bytes, magic, at) {
+    if (bytes.length < at + magic.length) {
+        return false;
+    }
+    return magic.every((byte, index) => bytes[at + index] === byte);
+}
+function hex(bytes) {
+    return [...bytes.slice(0, 4)].map((byte) => byte.toString(16).padStart(2, "0")).join(" ");
+}

package/dist/adapters/image/fal.js

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { redact } from "../../kernel/log.js";
+import { providerError } from "../../kernel/ports/model.js";
+import { retryAfter } from "../retry-after.js";
+import { downloadImage } from "./bytes.js";
+// The HTTP gateway adapter for fal.ai (01-architecture Module boundaries). `fetch` and
+// the downloader beside this file, no SDK: `@fal-ai/client` exists and would buy the
+// queue polling this endpoint does not need, so 05-dependencies' rung 3 - the platform's
+// own `fetch` - already covers the whole call. The synchronous host runs the model on the
+// open connection, which is what the attempt wrapper's 300 s is measuring.
+export const falBase = "https://fal.run";
+// `logic/02` §Q15: the model dropdown is filled from what the provider offers, and fal has
+// no endpoint that lists only its text-to-image models, so the list is this adapter's own
+// data. Adding next month's model is a line here and no code change anywhere else.
+// Every entry takes the same input shape: `image_size` as an enum, `num_images`, and
+// `output_format`. ceiling: a fal model that spells its aspect `aspect_ratio` instead -
+// `xai/grok-imagine-image` does - cannot be added to this list without a per-model input
+// map, which is the upgrade when one is wanted.
+export const falModels = [
+    { id: "fal-ai/flux-2", name: "FLUX.2" },
+    { id: "fal-ai/flux/dev", name: "FLUX.1 [dev]" },
+    { id: "fal-ai/flux/schnell", name: "FLUX.1 [schnell]" },
+];
+// `logic/09` step 1: the closest supported size to the run's aspect. fal names the two
+// 16:9 frames from the orientation, so the portrait one is "portrait_16_9" and is 9:16.
+const sizes = {
+    "16:9": "landscape_16_9",
+    "9:16": "portrait_16_9",
+};
+// A wire payload is narrowed, never cast: everything unlisted is dropped at the seam so
+// no vendor shape can leak past this file (01-architecture §Q10, §Q33).
+const generated = z.object({
+    images: z.array(z.object({ url: z.string() })),
+    // The safety checker's verdict, one flag per image. It is how fal says it declined:
+    // the request is a 200 and the image that comes back is blank.
+    has_nsfw_concepts: z.array(z.boolean()).nullish(),
+});
+// fal answers a rejected request with FastAPI's own envelope: an object per failed field
+// for a validation error, a bare string for everything else.
+const errorBody = z.object({
+    detail: z.union([
+        z.string(),
+        z.array(z.object({ msg: z.string(), type: z.string().optional() })),
+    ]),
+});
+export function falImage(deps) {
+    return {
+        id: "fal",
+        models: () => Promise.resolve(falModels),
+        generate: async (req) => {
+            const response = await deps.fetch(`${falBase}/${req.model}`, {
+                method: "POST",
+                signal: req.signal,
+                headers: { Authorization: `Key ${keyOf(deps)}`, "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    prompt: req.prompt,
+                    image_size: sizes[req.aspect],
+                    // `logic/09` step 2 sends Number as that many independent calls, each its own
+                    // resumable piece, so one image per request is what the stage asks for.
+                    num_images: 1,
+                    // The port stores a PNG or a JPEG; fal's own default is WebP on some models and
+                    // the download would refuse it. Nothing else about quality or style is set:
+                    // step 2 asks for the provider's defaults.
+                    output_format: "png",
+                }),
+            });
+            if (!response.ok) {
+                throw await failure(response);
+            }
+            const answer = parse(await response.text());
+            refused(answer, req.prompt);
+            const first = answer.images[0];
+            if (first === undefined) {
+                throw providerError({ kind: "other", message: "fal answered with no image" });
+            }
+            // The download is inside the attempt with the call that produced the link, so a
+            // link that 404s is a failed attempt rather than a broken file on the project.
+            return await downloadImage({
+                fetch: deps.fetch,
+                provider: "fal",
+                url: first.url,
+                signal: req.signal,
+            });
+        },
+    };
+}
+function keyOf(deps) {
+    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
+    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    const key = deps.key();
+    if (key === undefined || key === "") {
+        throw providerError({ kind: "missing_key", message: "no fal key is stored" });
+    }
+    return key;
+}
+// `logic/09` §Q74: a content-policy refusal is the provider's final answer, so it is named
+// here and the wrapper makes it terminal. fal declines inside a 200: the safety checker
+// flags the image and hands back a blank one. There is no sentence to quote, so this is
+// the one refusal in the app whose words are the app's; fal's own verdict is the flag.
+function refused(answer, prompt) {
+    const flags = answer.has_nsfw_concepts ?? [];
+    if (flags.length > 0 && flags.every((flagged) => flagged)) {
+        throw providerError({
+            kind: "refusal",
+            message: `fal's safety checker rejected every image for this prompt: ${redact(prompt)}`,
+        });
+    }
+}
+// Only the adapter can read a vendor's status code, so only the adapter names the kind;
+// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+function kindOf(status) {
+    if (status === 401 || status === 403) {
+        return "auth";
+    }
+    if (status === 429) {
+        return "rate_limit";
+    }
+    // ceiling: everything else is `other` and is retried, so a 422 naming an input this
+    // model does not take fails the same way four times over. A terminal kind for "this
+    // request will never work" would have to be added to the port's error contract first,
+    // which is not this adapter's to widen.
+    return "other";
+}
+async function failure(response) {
+    const text = await response.text().catch(() => "");
+    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
+    // error body is free to quote the key back and this is the first place it is held.
+    const message = redact(detailOf(text) || response.statusText);
+    const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+    return providerError({
+        kind: kindOf(response.status),
+        message: `fal answered ${String(response.status)}: ${message}`,
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    });
+}
+function detailOf(text) {
+    const parsed = errorBody.safeParse(safeJson(text));
+    if (!parsed.success) {
+        return text.trim();
+    }
+    const { detail } = parsed.data;
+    if (typeof detail === "string") {
+        return detail;
+    }
+    return detail.map((one) => one.msg).join("; ");
+}
+function parse(text) {
+    const parsed = generated.safeParse(safeJson(text));
+    if (!parsed.success) {
+        throw providerError({
+            kind: "other",
+            message: "fal's answer was not in the shape this app can read",
+        });
+    }
+    return parsed.data;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/image/openai.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { redact } from "../../kernel/log.js";
+import { providerError } from "../../kernel/ports/model.js";
+import { retryAfter } from "../retry-after.js";
+import { describeBytes, sniffImage } from "./bytes.js";
+// The HTTP gateway adapter for OpenAI's images endpoint (01-architecture Module
+// boundaries). `fetch` and nothing else: 05-dependencies records global `fetch` at rung 3
+// and the whole call is one request. Unlike fal and Replicate this one hands back the
+// image itself - a GPT image model always answers with base64 and never with a URL - so
+// there is no link to follow.
+export const openAiImagesBase = "https://api.openai.com/v1";
+// `logic/02` §Q15: the dropdown is filled from what the provider offers, and `/v1/models`
+// lists every model on the account, chat and embeddings among them, so the image
+// shortlist is this adapter's own data. These are the four GPT image models OpenAI
+// documents; adding the next one is a line here and no code change anywhere else.
+export const openAiImageModels = [
+    { id: "gpt-image-2", name: "GPT Image 2" },
+    { id: "gpt-image-1.5", name: "GPT Image 1.5" },
+    { id: "gpt-image-1", name: "GPT Image 1" },
+    { id: "gpt-image-1-mini", name: "GPT Image 1 mini" },
+];
+// `logic/09` step 1: "the provider's closest supported size to the run's aspect". The
+// standard GPT image sizes are 3:2 and 2:3, so 16:9 is asked for as 1536×1024 and the
+// remaining sliver is cropped by the render (`logic/11` step 4).
+const standard = {
+    "16:9": "1536x1024",
+    "9:16": "1024x1536",
+};
+// gpt-image-2 takes an arbitrary WIDTH×HEIGHT whose sides divide by 16, between 1:3 and
+// 3:1, so on that model the closest supported size is the aspect exactly and the render
+// crops nothing.
+const exact = {
+    "16:9": "1536x864",
+    "9:16": "864x1536",
+};
+const arbitrarySizes = /^gpt-image-2/;
+// A wire payload is narrowed, never cast (01-architecture §Q10, §Q33).
+const generated = z.object({ data: z.array(z.object({ b64_json: z.string().nullish() })) });
+const errorBody = z.object({
+    error: z.object({
+        message: z.string(),
+        type: z.string().nullish(),
+        code: z.string().nullish(),
+    }),
+});
+// `logic/09` §Q74: a content-policy refusal is the provider's final answer and is never
+// retried. OpenAI names it in the body rather than in the status, so the code is what
+// tells a declined prompt from a malformed request that shares its 400.
+const refusalCodes = ["moderation_blocked", "content_policy_violation"];
+export function sizeFor(model, aspect) {
+    return arbitrarySizes.test(model) ? exact[aspect] : standard[aspect];
+}
+export function openAiImage(deps) {
+    return {
+        id: "openai-image",
+        models: () => Promise.resolve(openAiImageModels),
+        generate: async (req) => {
+            const response = await deps.fetch(`${openAiImagesBase}/images/generations`, {
+                method: "POST",
+                signal: req.signal,
+                headers: { Authorization: `Bearer ${keyOf(deps)}`, "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    model: req.model,
+                    prompt: req.prompt,
+                    // `logic/09` step 2 sends Number as that many independent calls, each its own
+                    // resumable piece, so one image per request is what the stage asks for.
+                    n: 1,
+                    size: sizeFor(req.model, req.aspect),
+                    // No `quality` and no `background`: step 2 asks for the provider's default
+                    // quality and style, which is what leaving them off means.
+                }),
+            });
+            if (!response.ok) {
+                throw await failure(response);
+            }
+            const first = parse(await response.text()).data[0]?.b64_json;
+            if (first === undefined || first === null || first === "") {
+                throw providerError({ kind: "other", message: "OpenAI answered with no image" });
+            }
+            return decode(first);
+        },
+    };
+}
+// A GPT image model always answers with base64, so the bytes arrive with the call and
+// there is no link to follow. They are still sniffed: what the port stores is a PNG or a
+// JPEG, and a truncated payload that decodes to something else must not reach the disk.
+function decode(b64) {
+    const bytes = new Uint8Array(Buffer.from(b64, "base64"));
+    const mime = sniffImage(bytes);
+    if (mime === undefined) {
+        throw providerError({
+            kind: "other",
+            message: `OpenAI's image decoded to ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+        });
+    }
+    return { bytes, mime };
+}
+function keyOf(deps) {
+    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
+    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    const key = deps.key();
+    if (key === undefined || key === "") {
+        throw providerError({ kind: "missing_key", message: "no OpenAI image key is stored" });
+    }
+    return key;
+}
+// Only the adapter can read a vendor's status code, so only the adapter names the kind;
+// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+function kindOf(status, code) {
+    if (code !== undefined && code !== null && refusalCodes.includes(code)) {
+        return "refusal";
+    }
+    if (status === 401 || status === 403) {
+        return "auth";
+    }
+    if (status === 429) {
+        return "rate_limit";
+    }
+    // ceiling: everything else is `other` and is retried, so a prompt past the model's
+    // length limit fails the same way four times over. A terminal kind for "this request
+    // will never work" would have to be added to the port's error contract first, which is
+    // not this adapter's to widen.
+    return "other";
+}
+async function failure(response) {
+    const text = await response.text().catch(() => "");
+    const parsed = errorBody.safeParse(safeJson(text));
+    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
+    // error body is free to quote the key back and this is the first place it is held.
+    const message = redact(parsed.success ? parsed.data.error.message : text.trim() || response.statusText);
+    const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+    return providerError({
+        kind: kindOf(response.status, parsed.success ? parsed.data.error.code : undefined),
+        message: `OpenAI answered ${String(response.status)}: ${message}`,
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    });
+}
+function parse(text) {
+    const parsed = generated.safeParse(safeJson(text));
+    if (!parsed.success) {
+        throw providerError({
+            kind: "other",
+            message: "OpenAI's answer was not in the shape this app can read",
+        });
+    }
+    return parsed.data;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}