@gentbajko/slopify 2.5.0 → 3.0.1

package/dist/slices/schedules/topics.js

@@ -0,0 +1,523 @@
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { liveProject } from "../admission/repo.js";
+import { defaultChannelId } from "../channels/model.js";
+import { projectChannels, scheduleChannel } from "../channels/repo.js";
+import { channelVideoTitles } from "../channels/videos.js";
+import { readSetting, writeSetting } from "../settings/repo.js";
+import { scheduleById } from "./repo.js";
+import { heldTopicEditSchema, heldTopicSchema, queueMax, topicMoveSchema, topicQueueSchema, topicTitleSchema, topicTransferSchema, } from "./schema.js";
+import { newTopics } from "./similar.js";
+import { templateKeywords, topicRowProblems } from "./topic-list.js";
+// A schedule that finds its own topics asks an LLM whenever its queue holds fewer than
+// `keepAtLeast`. Only one generation per schedule runs at a time: a lease on the schedule row
+// (`topics_generating_at`) is taken before the LLM is asked and cleared after, so a tick and a
+// "Generate topics now" press cannot both ask. A lease older than `leaseMs` belongs to a
+// generation that died with the process and is taken over.
+export const generationTimeoutMs = 10 * 60_000;
+const leaseMs = generationTimeoutMs + 5 * 60_000;
+// A failure is recorded on the schedule and the next tick after this long tries again, so a
+// signed-out CLI or a bad answer is not asked again every 15 seconds.
+export const generationRetryMs = 5 * 60_000;
+// Asked for on top of what is missing, so the duplicates dropped still leave enough.
+const spare = 5;
+const askMax = 50;
+// The prompt lists every title; this only bounds a pathological library.
+const knownMax = 5000;
+export function generationWanted(schedule) {
+    const generation = schedule.topicGeneration;
+    if (generation.mode === "off")
+        return 0;
+    const waiting = schedule.items.length + (generation.mode === "hold" ? schedule.topics.held : 0);
+    return Math.max(0, Math.min(generation.keepAtLeast, queueMax) - waiting);
+}
+// Whether a tick should start a generation for this schedule now.
+export function generationDue(schedule, now) {
+    if (schedule.deletedAt !== null || schedule.status !== "active")
+        return false;
+    if (generationWanted(schedule) === 0)
+        return false;
+    if (schedule.topics.generatingSince !== null && !stale(schedule.topics.generatingSince, now))
+        return false;
+    return (schedule.topics.failedAt === null ||
+        now.valueOf() - new Date(schedule.topics.failedAt).valueOf() >= generationRetryMs);
+}
+function stale(since, now) {
+    return now.valueOf() - new Date(since).valueOf() >= leaseMs;
+}
+// `force` is the "Generate topics now" button: it ignores the retry wait and asks for a few
+// even when the queue is full.
+export async function generateTopics(deps, scheduleId, options = {}) {
+    const now = deps.clock.now();
+    const claimed = transact(deps.db, () => {
+        const schedule = scheduleById(deps.db, scheduleId);
+        if (schedule === undefined || schedule.deletedAt !== null)
+            return { ok: false, reason: "not-found", message: "This schedule no longer exists." };
+        if (schedule.topicGeneration.mode === "off")
+            return {
+                ok: false,
+                reason: "off",
+                message: "Topic generation is off for this schedule. Turn it on under Edit → Topic generation.",
+            };
+        if (schedule.status === "canceled" || schedule.status === "completed")
+            return {
+                ok: false,
+                reason: "off",
+                message: `This schedule is ${schedule.status}, so it needs no more topics.`,
+            };
+        if (!options.force && generationWanted(schedule) === 0)
+            return { ok: false, reason: "full", message: "The queue already has enough topics." };
+        const taken = deps.db
+            .prepare(`UPDATE schedules SET topics_generating_at=?
+         WHERE id=? AND (topics_generating_at IS NULL OR topics_generating_at<=?)`)
+            .run(now.toISOString(), scheduleId, new Date(now.valueOf() - leaseMs).toISOString());
+        if (Number(taken.changes) !== 1)
+            return {
+                ok: false,
+                reason: "busy",
+                message: "Slopify is already generating topics for this schedule. Wait for it to finish.",
+            };
+        return schedule;
+    });
+    if ("ok" in claimed)
+        return claimed;
+    const schedule = claimed;
+    try {
+        return await ask(deps, schedule, options);
+    }
+    finally {
+        deps.db
+            .prepare("UPDATE schedules SET topics_generating_at=NULL WHERE id=? AND topics_generating_at=?")
+            .run(scheduleId, now.toISOString());
+    }
+}
+async function ask(deps, schedule, options) {
+    const fail = (message) => {
+        const failedAt = deps.clock.now();
+        const retry = "Slopify tries again in 5 minutes, or press Generate topics now on the Schedules screen.";
+        const text = `Couldn't generate topics: ${message} ${retry}`;
+        deps.db
+            .prepare("UPDATE schedules SET topics_failed_at=?,topics_error=? WHERE id=?")
+            .run(failedAt.toISOString(), text, schedule.id);
+        return { ok: false, reason: "failed", message: text };
+    };
+    const template = deps.template(schedule.templateId, schedule.templateVersion);
+    const llm = schedule.topicGeneration.llm ?? template?.document.form.llm;
+    if (llm === undefined)
+        return fail("the template this schedule uses was deleted, so there is no LLM to ask. Edit the schedule and choose a template, or pick an LLM under Topic generation.");
+    if (deps.topicLlm === undefined)
+        return fail("no LLM is available in this Slopify. Restart Slopify and try again.");
+    const wanted = Math.max(generationWanted(schedule), options.force ? spare : 0);
+    const known = knownTitles(deps, schedule.id);
+    const signal = AbortSignal.any([
+        AbortSignal.timeout(generationTimeoutMs),
+        ...(options.signal === undefined ? [] : [options.signal]),
+    ]);
+    let answer;
+    try {
+        const answered = await deps.topicLlm({
+            owner: { kind: "schedule", id: schedule.id },
+            purpose: "topics",
+            provider: llm.provider,
+            model: llm.model,
+            ...(llm.thinking === undefined ? {} : { thinking: llm.thinking }),
+            messages: topicMessages(withChannelBrief(deps, schedule), template?.document.form.title, known, Math.min(wanted + spare, askMax)),
+            signal,
+        });
+        answer = answered.text;
+    }
+    catch (error) {
+        if (options.signal?.aborted === true)
+            return { ok: false, reason: "failed", message: "Slopify was closing." };
+        const detail = error instanceof Error ? error.message : String(error);
+        return fail(`${llm.provider} (${llm.model}) did not answer: ${detail.trim().slice(0, 300)}. Check it in Settings → Providers, or pick another LLM under Edit → Topic generation.`);
+    }
+    const suggested = parseTopics(answer);
+    if (suggested.length === 0)
+        return fail(`${llm.provider} (${llm.model}) answered without a list of topics. Try again, or pick another LLM under Edit → Topic generation.`);
+    return transact(deps.db, () => {
+        const current = scheduleById(deps.db, schedule.id);
+        if (current === undefined || current.deletedAt !== null)
+            return { ok: false, reason: "not-found", message: "This schedule no longer exists." };
+        // Checked again against what is there now: a topic added while the LLM was thinking counts.
+        const fresh = newTopics(suggested, knownTitles(deps, schedule.id)).slice(0, Math.max(0, Math.min(wanted, queueMax - current.items.length)));
+        if (fresh.length === 0)
+            return fail("every topic the LLM suggested was already made, queued or turned down for this schedule. Add more detail to the series brief under Edit, so it has new ground to cover.");
+        const at = deps.clock.now().toISOString();
+        const mode = current.topicGeneration.mode === "hold" ? "hold" : "queue";
+        if (mode === "queue") {
+            deps.db
+                .prepare("UPDATE schedules SET items_json=?,version=version+1,updated_at=? WHERE id=? AND deleted_at IS NULL")
+                .run(JSON.stringify([...current.items, ...fresh.map((title) => ({ title, values: {} }))]), at, schedule.id);
+        }
+        else {
+            const start = nextRank(deps, schedule.id);
+            fresh.forEach((title, index) => {
+                deps.db
+                    .prepare(`INSERT INTO schedule_topics (id,schedule_id,title,state,rank,created_at)
+             VALUES (?,?,?,'held',?,?)`)
+                    .run(deps.uuid(), schedule.id, title, start + index, at);
+            });
+        }
+        deps.db
+            .prepare("UPDATE schedules SET topics_generated_at=?,topics_failed_at=NULL,topics_error=NULL WHERE id=?")
+            .run(at, schedule.id);
+        if (mode === "hold") {
+            const waiting = heldTopics(deps, schedule.id).length;
+            try {
+                deps.topicsWaiting?.({
+                    type: "schedule.topics",
+                    scheduleId: schedule.id,
+                    scheduleName: current.name,
+                    added: fresh.length,
+                    waiting,
+                });
+            }
+            catch {
+                // A notification is never a reason to lose the topics.
+            }
+        }
+        return { ok: true, added: fresh.length, mode };
+    });
+}
+function nextRank(deps, scheduleId) {
+    const row = deps.db
+        .prepare("SELECT max(rank) AS rank FROM schedule_topics WHERE schedule_id=? AND state='held'")
+        .get(scheduleId);
+    const rank = z.object({ rank: z.number().nullable() }).parse(row).rank;
+    return rank === null ? 0 : rank + 1;
+}
+// Everything this schedule has queued, held, turned down or used, the titles of the projects in
+// its channel, and the titles of the videos its channel made before Slopify (Channel page →
+// Existing videos). Another channel's videos are its own business: a sleep channel may cover a
+// subject a lore channel already did.
+export function knownTitles(deps, scheduleId) {
+    const schedule = scheduleById(deps.db, scheduleId);
+    const logged = deps.db
+        .prepare("SELECT title FROM schedule_topics WHERE schedule_id=? ORDER BY created_at DESC")
+        .all(scheduleId)
+        .map((row) => z.object({ title: z.string() }).parse(row).title);
+    const channel = scheduleChannel(deps.db, scheduleId);
+    const channels = projectChannels(deps.db);
+    const projects = deps.db
+        .prepare(`SELECT id,title FROM projects WHERE ${liveProject()} ORDER BY created_at DESC`)
+        .all()
+        .map((row) => z.object({ id: z.string(), title: z.string() }).parse(row))
+        .filter((row) => channel === undefined || (channels.get(row.id) ?? defaultChannelId) === channel.id)
+        .map((row) => row.title);
+    const existing = channel === undefined ? [] : channelVideoTitles(deps.db, channel.id);
+    return {
+        topics: [...new Set([...(schedule?.items.map((item) => item.title) ?? []), ...logged])],
+        projects: [...new Set([...projects, ...existing])],
+    };
+}
+// A schedule without a brief of its own reads its channel's series brief (the channel of the
+// template it runs); one it sets itself wins.
+export function withChannelBrief(deps, schedule) {
+    if (schedule.brief?.trim())
+        return schedule;
+    const brief = scheduleChannel(deps.db, schedule.id)?.seriesBrief.trim() ?? "";
+    return brief === "" ? schedule : { ...schedule, brief };
+}
+export function topicMessages(schedule, templateTitle, known, count) {
+    const titles = [...new Set([...known.topics, ...known.projects])].slice(0, knownMax);
+    const keyword = schedule.topicKeyword;
+    const fills = keyword !== null && templateTitle?.includes(`{{${keyword}}}`) === true
+        ? `Each topic fills {{${keyword}}} in the video title "${templateTitle}", so write only the topic itself, not a whole title.`
+        : "Each topic becomes the video's subject; write it as a short title.";
+    const brief = schedule.brief?.trim();
+    return [
+        {
+            role: "system",
+            content: "You plan the next videos for a YouTube channel. Answer with a JSON array of strings and nothing else.",
+        },
+        {
+            role: "user",
+            content: [
+                `Suggest ${String(count)} new topics for the series "${schedule.name}".`,
+                "",
+                "Series brief:",
+                brief === undefined || brief === ""
+                    ? "(none given; work out what the channel covers from the titles below)"
+                    : brief,
+                "",
+                `${fills} Keep each under 120 characters.`,
+                "Rank them most view-worthy first: the topics most likely to be watched, as the brief defines it.",
+                "",
+                titles.length === 0
+                    ? "Nothing has been made for this channel yet."
+                    : "Never repeat or rephrase any of these, which were already made, queued or turned down:",
+                ...titles.map((title) => `- ${title}`),
+            ].join("\n"),
+        },
+    ];
+}
+// A JSON array of strings, or failing that one topic per line with bullets and numbers dropped.
+export function parseTopics(answer) {
+    const start = answer.indexOf("[");
+    const end = answer.lastIndexOf("]");
+    let lines;
+    if (start !== -1 && end > start) {
+        try {
+            const parsed = JSON.parse(answer.slice(start, end + 1));
+            if (Array.isArray(parsed))
+                lines = parsed;
+        }
+        catch {
+            lines = undefined;
+        }
+    }
+    lines ??= answer.split(/\r?\n/);
+    return lines
+        .map((line) => typeof line === "string"
+        ? line
+        : typeof line === "object" && line !== null && "title" in line
+            ? String(line.title)
+            : "")
+        .map((line) => line
+        .replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "")
+        .replace(/^["'“”]+|["'“”,]+$/g, "")
+        .replace(/\s+/g, " ")
+        .trim())
+        .filter((line) => line !== "" && line !== "[" && line !== "]" && line.length <= 200);
+}
+// The keywords set on held topics, by topic id. Kept in a settings row, since a held topic's row
+// has only its title; an entry leaves when its topic is approved or turned down.
+export const heldValuesKey = "schedules.held-topic-values";
+const heldValuesSchema = z.record(z.string(), z.record(z.string(), z.string()));
+function readHeldValues(db) {
+    const raw = readSetting(db, heldValuesKey);
+    if (raw === undefined)
+        return {};
+    try {
+        const parsed = heldValuesSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : {};
+    }
+    catch {
+        return {};
+    }
+}
+// Entries of topics that are no longer held (approved, turned down, or gone with their
+// schedule) are dropped on every write.
+function writeHeldValues(db, change = (values) => values) {
+    const held = new Set(db
+        .prepare("SELECT id FROM schedule_topics WHERE state='held'")
+        .all()
+        .map((row) => String(row.id)));
+    const next = Object.fromEntries(Object.entries(change(readHeldValues(db))).filter(([id, values]) => held.has(id) && Object.keys(values).length > 0));
+    writeSetting(db, heldValuesKey, JSON.stringify(next));
+}
+export function heldTopics(deps, scheduleId) {
+    const stored = readHeldValues(deps.db);
+    return deps.db
+        .prepare(`SELECT id,title,rank,created_at FROM schedule_topics
+       WHERE schedule_id=? AND state='held' ORDER BY rank,created_at,id`)
+        .all(scheduleId)
+        .map((row) => {
+        const value = z
+            .object({ id: z.string(), title: z.string(), rank: z.number(), created_at: z.string() })
+            .parse(row);
+        return heldTopicSchema.parse({
+            id: value.id,
+            title: value.title,
+            values: stored[value.id] ?? {},
+            rank: value.rank,
+            createdAt: value.created_at,
+        });
+    });
+}
+function openSchedule(deps, scheduleId) {
+    const schedule = scheduleById(deps.db, scheduleId);
+    if (schedule === undefined || schedule.deletedAt !== null)
+        return { ok: false, reason: "not-found" };
+    if (schedule.status === "canceled" || schedule.status === "completed")
+        return { ok: false, reason: "conflict" };
+    return { ok: true, value: schedule };
+}
+// Approved topics join the end of the queue in their ranked order. `edits` renames a topic
+// as it is approved.
+export function approveHeldTopics(deps, scheduleId, ids, edits = {}) {
+    return transact(deps.db, () => {
+        const open = openSchedule(deps, scheduleId);
+        if (!open.ok)
+            return open;
+        const held = heldTopics(deps, scheduleId);
+        const chosen = ids === "all" ? held : held.filter((topic) => ids.includes(topic.id));
+        if (ids !== "all" && chosen.length !== ids.length)
+            return { ok: false, reason: "topic-not-found" };
+        const items = [];
+        for (const topic of chosen) {
+            const title = topicTitleSchema.safeParse(edits[topic.id] ?? topic.title);
+            if (!title.success)
+                return { ok: false, reason: "invalid-input" };
+            items.push({ title: title.data, values: topic.values });
+        }
+        if (open.value.items.length + items.length > queueMax)
+            return { ok: false, reason: "queue-full" };
+        const at = deps.clock.now().toISOString();
+        for (const topic of chosen)
+            deps.db.prepare("DELETE FROM schedule_topics WHERE id=?").run(topic.id);
+        deps.db
+            .prepare("UPDATE schedules SET items_json=?,version=version+1,updated_at=? WHERE id=?")
+            .run(JSON.stringify([...open.value.items, ...items]), at, scheduleId);
+        writeHeldValues(deps.db);
+        return { ok: true, value: scheduleById(deps.db, scheduleId) };
+    });
+}
+// Turned down topics stay recorded so no later generation suggests them again.
+export function rejectHeldTopic(deps, scheduleId, topicId) {
+    const changed = deps.db
+        .prepare(`UPDATE schedule_topics SET state='rejected',decided_at=?
+       WHERE id=? AND schedule_id=? AND state='held'`)
+        .run(deps.clock.now().toISOString(), topicId, scheduleId);
+    if (Number(changed.changes) !== 1)
+        return { ok: false, reason: "topic-not-found" };
+    writeHeldValues(deps.db);
+    return { ok: true, value: scheduleById(deps.db, scheduleId) };
+}
+// Edit on a held topic: its title, and the keywords it sets for its run, checked against the
+// template the way the queue's are. Without `values` the ones it had are kept; an empty value
+// is dropped, so the every-run value applies.
+export function editHeldTopic(deps, scheduleId, topicId, input) {
+    const edit = heldTopicEditSchema.safeParse(input);
+    if (!edit.success)
+        return { ok: false, reason: "invalid-input" };
+    const parsed = topicTitleSchema.safeParse(edit.data.title);
+    if (!parsed.success)
+        return { ok: false, reason: "invalid-input" };
+    const values = edit.data.values === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(edit.data.values)
+            .map(([name, value]) => [name, value.trim()])
+            .filter(([, value]) => value !== ""));
+    if (values !== undefined && Object.keys(values).length > 0) {
+        const schedule = scheduleById(deps.db, scheduleId);
+        if (schedule === undefined)
+            return { ok: false, reason: "not-found" };
+        const template = deps.template(schedule.templateId, schedule.templateVersion);
+        if (template === undefined)
+            return { ok: false, reason: "missing-template" };
+        const problems = topicRowProblems([{ title: parsed.data, values }], {
+            keywords: templateKeywords(template.document.form).filter((name) => name !== schedule.topicKeyword),
+            topicKeyword: schedule.topicKeyword,
+        });
+        if (problems.length > 0)
+            return {
+                ok: false,
+                reason: "invalid-topics",
+                message: `The topic wasn't saved. ${problems.join(" ")}`,
+            };
+    }
+    const changed = transact(deps.db, () => {
+        const row = deps.db
+            .prepare("UPDATE schedule_topics SET title=? WHERE id=? AND schedule_id=? AND state='held'")
+            .run(parsed.data, topicId, scheduleId);
+        if (Number(row.changes) !== 1)
+            return false;
+        if (values !== undefined)
+            writeHeldValues(deps.db, (stored) => ({ ...stored, [topicId]: values }));
+        return true;
+    });
+    if (!changed)
+        return { ok: false, reason: "topic-not-found" };
+    const topic = heldTopics(deps, scheduleId).find((row) => row.id === topicId);
+    return topic === undefined
+        ? { ok: false, reason: "topic-not-found" }
+        : { ok: true, value: topic };
+}
+// Moves one queued topic to another position. Each run takes the first topic, so this is
+// also what reorders the calendar.
+export function moveTopic(deps, scheduleId, input) {
+    const parsed = topicMoveSchema.safeParse(input);
+    if (!parsed.success)
+        return { ok: false, reason: "invalid-input" };
+    return transact(deps.db, () => {
+        const open = openSchedule(deps, scheduleId);
+        if (!open.ok)
+            return open;
+        const schedule = open.value;
+        if (schedule.version !== parsed.data.baseVersion)
+            return { ok: false, reason: "conflict" };
+        const { from } = parsed.data;
+        if (from >= schedule.items.length)
+            return { ok: false, reason: "invalid-input" };
+        const items = [...schedule.items];
+        const [topic] = items.splice(from, 1);
+        if (topic === undefined)
+            return { ok: false, reason: "invalid-input" };
+        items.splice(Math.min(parsed.data.to, items.length), 0, topic);
+        writeItems(deps, scheduleId, schedule.version, items);
+        return { ok: true, value: scheduleById(deps.db, scheduleId) };
+    });
+}
+// Saves the queue as sent, without touching the schedule's other settings or its next run.
+// Topics already queued are not checked again; a new or renamed one must suit the template.
+export function replaceTopics(deps, scheduleId, input) {
+    const parsed = topicQueueSchema.safeParse(input);
+    if (!parsed.success)
+        return { ok: false, reason: "invalid-input" };
+    return transact(deps.db, () => {
+        const open = openSchedule(deps, scheduleId);
+        if (!open.ok)
+            return open;
+        const schedule = open.value;
+        if (schedule.version !== parsed.data.baseVersion)
+            return { ok: false, reason: "conflict" };
+        const template = deps.template(schedule.templateId, schedule.templateVersion);
+        if (!template)
+            return { ok: false, reason: "missing-template" };
+        const problems = topicRowProblems(parsed.data.items, {
+            keywords: templateKeywords(template.document.form),
+            topicKeyword: schedule.topicKeyword,
+            kept: schedule.items,
+        });
+        if (problems.length > 0)
+            return { ok: false, reason: "invalid-topics", message: problems.slice(0, 5).join(" ") };
+        writeItems(deps, scheduleId, schedule.version, parsed.data.items);
+        return { ok: true, value: scheduleById(deps.db, scheduleId) };
+    });
+}
+// Takes one queued topic off this schedule and puts it on another's queue.
+export function transferTopic(deps, scheduleId, input) {
+    const parsed = topicTransferSchema.safeParse(input);
+    if (!parsed.success)
+        return { ok: false, reason: "invalid-input" };
+    if (parsed.data.targetId === scheduleId)
+        return { ok: false, reason: "invalid-input" };
+    return transact(deps.db, () => {
+        const source = openSchedule(deps, scheduleId);
+        if (!source.ok)
+            return source;
+        const target = openSchedule(deps, parsed.data.targetId);
+        if (!target.ok)
+            return target;
+        if (source.value.version !== parsed.data.baseVersion)
+            return { ok: false, reason: "conflict" };
+        const items = [...source.value.items];
+        const [topic] = items.splice(parsed.data.index, 1);
+        if (topic === undefined)
+            return { ok: false, reason: "invalid-input" };
+        if (target.value.items.length + 1 > queueMax)
+            return { ok: false, reason: "queue-full" };
+        const landing = [...target.value.items];
+        landing.splice(Math.min(parsed.data.position ?? landing.length, landing.length), 0, topic);
+        writeItems(deps, scheduleId, source.value.version, items);
+        writeItems(deps, target.value.id, target.value.version, landing);
+        return {
+            ok: true,
+            value: {
+                source: scheduleById(deps.db, scheduleId),
+                target: scheduleById(deps.db, target.value.id),
+            },
+        };
+    });
+}
+function writeItems(deps, scheduleId, version, items) {
+    deps.db
+        .prepare("UPDATE schedules SET items_json=?,version=version+1,updated_at=? WHERE id=? AND version=?")
+        .run(JSON.stringify(items), deps.clock.now().toISOString(), scheduleId, version);
+}
+// Boot: a generation cannot outlive the process that asked.
+export function releaseTopicLeases(deps) {
+    deps.db.prepare("UPDATE schedules SET topics_generating_at=NULL").run();
+}

package/dist/slices/settings/first-run.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { readinessIsUsable } from "../../kernel/ports/model.js";
+import { keyedProviders, readSetting, writeSetting } from "./repo.js";
+// What a fresh Play form picks before the user picks anything. Written once, on the first
+// launch that finds a command-line tool, and read by Play for every new draft.
+const choiceSchema = z.object({ provider: z.string().min(1), model: z.string() }).strict();
+export const providerDefaultsSchema = z
+    .object({ llm: choiceSchema.optional(), images: choiceSchema.optional() })
+    .strict();
+export const providerDefaultsKey = "provider.defaults";
+const defaultsKey = providerDefaultsKey;
+const doneKey = "first-run.done";
+// The order a text tool is preferred in when several are found.
+const textPreference = ["claude-code", "codex", "gemini"];
+export function readProviderDefaults(db) {
+    const raw = readSetting(db, defaultsKey);
+    if (raw === undefined)
+        return {};
+    try {
+        const parsed = providerDefaultsSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function dismissFirstRun(db) {
+    writeSetting(db, doneKey, "1");
+}
+// First launch: find Claude Code, Codex and Gemini, pick the found ones as Play's defaults, and
+// say a video can be made without any API key. Later launches only report what was found.
+export async function firstRunStatus(deps, statuses) {
+    const detected = statuses
+        .filter((status) => status.readiness.kind === "cli")
+        .map((status) => {
+        const readiness = status.readiness;
+        if (readiness.kind !== "cli")
+            throw new Error("Expected a command-line provider.");
+        return {
+            id: status.id,
+            displayName: status.id === "codex-image" ? "Codex CLI (images)" : status.displayName,
+            installed: readiness.installed,
+            usable: readinessIsUsable(readiness),
+            ...(readiness.version === undefined ? {} : { version: readiness.version }),
+            ...(readiness.issue === undefined ? {} : { issue: readiness.issue }),
+        };
+    });
+    const firstRun = keyedProviders(deps.db).size === 0 && readSetting(deps.db, doneKey) === undefined;
+    let defaults = readProviderDefaults(deps.db);
+    const usable = new Set(detected.filter((cli) => cli.usable).map((cli) => cli.id));
+    const text = textPreference.find((id) => usable.has(id));
+    if (firstRun &&
+        readSetting(deps.db, defaultsKey) === undefined &&
+        (text !== undefined || usable.has("codex-image"))) {
+        defaults = {
+            ...(text === undefined
+                ? {}
+                : { llm: { provider: text, model: await firstModel(deps, text, "llm") } }),
+            ...(usable.has("codex-image")
+                ? {
+                    images: {
+                        provider: "codex-image",
+                        model: await firstModel(deps, "codex-image", "image"),
+                    },
+                }
+                : {}),
+        };
+        writeSetting(deps.db, defaultsKey, JSON.stringify(defaults));
+    }
+    const names = detected
+        .filter((cli) => cli.usable && cli.id !== "codex-image")
+        .map((cli) => cli.displayName);
+    const systemVoice = statuses.some((status) => status.readiness.kind === "local" && status.readiness.available);
+    const narration = systemVoice
+        ? "Narration can use your computer's built-in voice (System voice in Settings → Voices); add an ElevenLabs or OpenAI key later for a better one."
+        : "Narration still needs a voice provider key, or turn Audio off or upload your own.";
+    return {
+        firstRun,
+        detected,
+        defaults,
+        message: !firstRun
+            ? null
+            : names.length > 0
+                ? "You can make a video now, no API keys needed."
+                : "No AI command-line tool was found on this computer.",
+        detail: !firstRun
+            ? null
+            : names.length > 0
+                ? `Slopify found ${list(names)} and picked ${names.length === 1 ? "it" : "them"} on Play. ${narration} Keys are optional extras in Settings → Providers.`
+                : "Install Claude Code, Codex or Gemini CLI and sign in once in a terminal, then reload this page. Or paste an API key in Settings → Providers.",
+    };
+}
+async function firstModel(deps, provider, family) {
+    try {
+        return (await deps.modelsFor?.(provider, family))?.[0]?.id ?? "";
+    }
+    catch {
+        // The picker shows the tool's list once it answers; the provider is still chosen.
+        return "";
+    }
+}
+function list(names) {
+    return names.length <= 1
+        ? (names[0] ?? "")
+        : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}