@stringsync/splates 0.0.52 → 0.0.53

package/setup.ts

@@ -0,0 +1,233 @@
+import { dirname } from "node:path";
+import { SYSTEM_STORES } from "@stringsync/splates-server/creds";
+import { fail } from "@stringsync/splates-server/exit";
+import { splatesHome } from "@stringsync/splates-server/models";
+import { Projects } from "@stringsync/splates-server/projects";
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+import {
+	SETUP_AREAS,
+	Setup,
+	type SetupProgress,
+	type StepProgress,
+	type StepStatus,
+	setupProjectAt,
+	type UndoPlan,
+} from "@stringsync/splates-server/setup";
+import {
+	fetchWorkerBudget,
+	fetchWorkers,
+	putWorkerLimit,
+} from "@stringsync/splates-server/workers";
+import type { Logger } from "webappwiz/log";
+import { color } from "webappwiz/log";
+import type { Ps } from "webappwiz/system";
+
+/** What `splates setup` was asked for. */
+export interface SetupOptions {
+	/** A step's id, or empty for every area's progress. */
+	step: string;
+	json: boolean;
+	skip: boolean;
+	unskip: boolean;
+	/** Print what undoing the area `step` names would do. */
+	undo: boolean;
+}
+
+/**
+ * `splates setup [step]`: progress by area and the one next step, or one step's
+ * why and instructions, after skipping or unskipping it when asked.
+ */
+export async function setup(
+	deps: SplatesDeps,
+	opts: SetupOptions,
+): Promise<void> {
+	if (opts.step === "" && (opts.skip || opts.unskip || opts.undo)) {
+		fail("usage", "--skip and --unskip name a step, --undo an area", {});
+	}
+	if (opts.undo && (opts.skip || opts.unskip)) {
+		fail("usage", "--undo names an area, not a step to skip", {
+			area: opts.step,
+		});
+	}
+	if (opts.skip && opts.unskip) {
+		fail("usage", "--skip or --unskip, not both", { step: opts.step });
+	}
+	const machine = await setupOf(deps);
+	const { log } = deps;
+	if (opts.undo) {
+		const plan = await machine.undoPlan(opts.step);
+		if (opts.json) {
+			log.info(JSON.stringify(plan, null, 2));
+			return;
+		}
+		printUndo(log, plan);
+		return;
+	}
+	if (opts.step !== "") {
+		machine.step(opts.step);
+		if (opts.skip) {
+			await machine.skip(opts.step);
+		} else if (opts.unskip) {
+			await machine.unskip(opts.step);
+		}
+	}
+	const progress = await machine.read();
+	if (opts.step === "") {
+		if (opts.json) {
+			log.info(JSON.stringify(progress, null, 2));
+			return;
+		}
+		printProgress(log, progress);
+		return;
+	}
+	const step = progress.areas
+		.flatMap((area) => area.steps)
+		.find((each) => each.id === opts.step) as StepProgress;
+	if (opts.json) {
+		log.info(JSON.stringify(step, null, 2));
+		return;
+	}
+	printStep(log, step);
+}
+
+/**
+ * This machine's setup, read through `deps`, for the project `--project`
+ * names or the repository the working directory is in, if either.
+ */
+export async function setupOf(deps: SplatesDeps): Promise<Setup> {
+	const { fs, ps, secrets = SYSTEM_STORES, fetch } = deps;
+	const root =
+		deps.project === undefined
+			? await repoRoot(ps)
+			: (await Projects.ofMachine(deps).named(deps.project)).root;
+	return new Setup(
+		{
+			fs,
+			ps,
+			home: splatesHome(ps),
+			device: secrets.device,
+			fetch,
+			// Only a server this agent runs under, or is pointed at, can be asked.
+			workers: deps.ps.env("SPLATES_DEV")
+				? () => fetchWorkers({ dev: "", log: deps.log, ps: deps.ps })
+				: undefined,
+			workerBudget: deps.ps.env("SPLATES_DEV")
+				? {
+						report: () =>
+							fetchWorkerBudget({ dev: "", log: deps.log, ps: deps.ps }),
+						set: (limit, dollars) =>
+							putWorkerLimit(limit, dollars, {
+								dev: "",
+								log: deps.log,
+								ps: deps.ps,
+							}),
+					}
+				: undefined,
+			project: root === null ? undefined : setupProjectAt(root, { fs, ps }),
+		},
+		SETUP_AREAS,
+	);
+}
+
+/** The main tree of the repository the working directory is in, or null. */
+async function repoRoot(ps: Ps): Promise<string | null> {
+	const { exitCode, stdout } = await ps.spawnCapture([
+		"git",
+		"-C",
+		ps.cwd(),
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir",
+	]);
+	return exitCode === 0 ? dirname(stdout.trim()) : null;
+}
+
+const MARKS: Record<StepStatus, string> = {
+	done: color.green("✓"),
+	skipped: color.dim("-"),
+	ready: color.yellow("○"),
+	waiting: color.dim("○"),
+};
+
+function printProgress(log: Logger, progress: SetupProgress): void {
+	for (const area of progress.areas) {
+		const counts = [
+			`${area.done}/${area.steps.length} done`,
+			area.skipped > 0 ? `${area.skipped} skipped` : "",
+		].filter(Boolean);
+		log.info(`${color.bold(area.title)}  ${color.dim(counts.join(", "))}`);
+		for (const step of area.steps) {
+			const notes = [
+				step.optional ? "optional" : "",
+				step.status === "waiting" ? `after ${step.after.join(", ")}` : "",
+				step.problem ?? "",
+				step.warning === null ? "" : "to put right",
+			].filter(Boolean);
+			log.info(
+				`  ${MARKS[step.status]} ${step.id}  ${step.title}${notes.length > 0 ? color.dim(`  ${notes.join("; ")}`) : ""}`,
+			);
+		}
+	}
+	const steps = progress.areas.flatMap((area) => area.steps);
+	const next = steps.find((step) => step.id === progress.next);
+	for (const step of steps.filter((each) => each.warning !== null)) {
+		log.info(
+			`${color.yellow("put right:")} ${step.title}  ${color.dim(`splates setup ${step.id}`)}`,
+		);
+	}
+	log.info(
+		next === undefined
+			? color.green("nothing left to set up")
+			: `next: ${next.title}  ${color.dim(`splates setup ${next.id}`)}`,
+	);
+}
+
+function printStep(log: Logger, step: StepProgress): void {
+	log.info(
+		`${color.bold(step.title)}  ${color.dim(`${step.status}${step.optional ? ", optional" : ""}`)}`,
+	);
+	log.info(step.why);
+	if (step.detail !== null) {
+		log.info(step.detail);
+	}
+	if (step.warning !== null) {
+		log.info(`${color.yellow("put right:")} ${step.warning}`);
+	}
+	log.info(`you:    ${step.user}`);
+	log.info(`agent:  ${step.agent}`);
+	if (step.after.length > 0) {
+		log.info(`after:  ${step.after.join(", ")}`);
+	}
+	if (step.problem !== null) {
+		log.info(`${color.red("problem:")} ${step.problem}`);
+	}
+}
+
+function printUndo(log: Logger, plan: UndoPlan): void {
+	log.info(`${color.bold(`Undo ${plan.title}`)}  ${color.dim(plan.area)}`);
+	if (plan.refused !== null) {
+		log.info(`${color.red("refused:")} ${plan.refused}`);
+		return;
+	}
+	for (const step of plan.steps) {
+		const started = step.done ? "" : `  ${color.yellow("started")}`;
+		log.info(`  ${step.title}  ${color.dim(step.id)}${started}`);
+		for (const line of step.removes) {
+			log.info(`    removes  ${line}`);
+		}
+		for (const line of step.leaves) {
+			log.info(`    leaves   ${line}`);
+		}
+	}
+	for (const cred of plan.creds) {
+		log.info(
+			cred.keptFor === null
+				? `  forgets ${cred.name}`
+				: `  keeps   ${cred.name}  ${color.dim(`${cred.keptFor} still uses it`)}`,
+		);
+	}
+	if (plan.confirm !== null) {
+		log.info(`  the page asks for ${plan.confirm} to be typed`);
+	}
+	log.info(color.dim("the Setup page's Undo does it, after the user confirms"));
+}

package/slots.ts

@@ -0,0 +1,65 @@
+import { type Held, Slots } from "@stringsync/splates-server/ports";
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+import { cli } from "webappwiz/cmd";
+import { z } from "zod";
+
+/** `splates slots`, which the root cli mounts after `splates tunnel`. */
+export const splatesSlots = cli<SplatesDeps>("slots").description(
+	"the words `splates server --slot` hands out on this machine, each held by the tree that claimed it: a task's worktree holds its word until the task merges or is removed, which stops its server and gives the word back",
+);
+
+splatesSlots
+	.command("list")
+	.description(
+		"print each claimed word, the tree holding it, its server's pid while one runs, and whether it is orphaned: its tree gone, or a splates repository's main tree, which every agent shares",
+	)
+	.option("json", z.boolean(), { default: false, description: "emit JSON" })
+	.action(async (opts, ctx) => {
+		const held = await Slots.ofMachine(ctx).status();
+		if (opts.json) {
+			ctx.log.info(
+				JSON.stringify(
+					held.map(({ slot, tree, pid, orphaned }) => ({
+						word: slot.word,
+						tree,
+						pid,
+						orphaned,
+					})),
+				),
+			);
+			return;
+		}
+		if (held.length === 0) {
+			ctx.log.info("no slot is claimed");
+			return;
+		}
+		ctx.log.info(held.map(heldLine).join("\n"));
+	});
+
+splatesSlots
+	.command("prune")
+	.description(
+		"free every orphaned word, stopping its server, so another tree can claim it; the slots a task's worktree holds are that task's, and left alone. The way to free a slot: never kill another tree's server or edit ~/.splates/slots.json",
+	)
+	.action(async (_opts, ctx) => {
+		const freed = await Slots.ofMachine(ctx).prune();
+		if (freed.length === 0) {
+			ctx.log.info(
+				"nothing to prune: each claimed word is held by a task's worktree",
+			);
+			return;
+		}
+		ctx.log.info(
+			freed
+				.map(
+					({ slot, tree, pid }) =>
+						`freed ${slot.word} ${slot.emoji} from ${tree}${pid === null ? "" : `, its server (pid ${pid}) stopped`}`,
+				)
+				.join("\n"),
+		);
+	});
+
+function heldLine({ slot, tree, pid, orphaned }: Held): string {
+	const server = pid === null ? "no server" : `server pid ${pid}`;
+	return `${slot.word} ${slot.emoji}  ${tree}  ${server}${orphaned ? "  orphaned: `splates slots prune` frees it" : ""}`;
+}

package/splates.test.ts

@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { basename, join } from "node:path";
+import { SERVING } from "@stringsync/splates-server/server";
+import { Testing } from "@stringsync/splates-server/testing";
+import { splates } from "./splates";
+
+/**
+ * The cli in this process, run with fakes: the same commands `e2e.test.ts`
+ * spawns, minus the subprocess. What it proves is the wiring, that every
+ * dependency an action uses arrives through `run`.
+ */
+describe("splates cli", () => {
+	let env: Testing;
+	let deps: Parameters<typeof splates.run>[0];
+
+	beforeEach(async () => {
+		env = await Testing.open();
+		env.ps.cd(env.root);
+		deps = {
+			log: env.log,
+			fs: env.fs,
+			ps: env.ps,
+			assets: env.assets,
+			secrets: env.secrets,
+			fetch: Object.assign(
+				() => Promise.reject(new Error("no network in a test")),
+				{ preconnect: () => {} },
+			),
+		};
+	});
+
+	afterEach(() => env.disposeAsync());
+
+	it("prints nothing successfully when there is no notes directory", async () => {
+		await splates.run(deps, ["notes"]);
+		expect(env.out()).toBe("");
+		expect(env.proc.lastExit()).toBeUndefined();
+	});
+
+	it("prints only note descriptions and does not record consulting them", async () => {
+		await env.fs.mkdir(join(env.root, "notes"));
+		await env.fs.write(
+			join(env.root, "notes/a.md"),
+			"---\ndescription: Project conventions\n---\nBody",
+		);
+		await env.fs.write(
+			join(env.root, "notes/b.md"),
+			"---\ndescription: Client agreement\n---\nBody",
+		);
+		const before = await env.journal.tail(10);
+		await splates.run(deps, ["notes"]);
+		expect(env.log.entries.map((entry) => entry.message)).toEqual([
+			"Project conventions",
+			"Client agreement",
+		]);
+		expect(await env.journal.tail(10)).toEqual(before);
+	});
+
+	it("reads the current worktree's notes and configuration from a subdirectory", async () => {
+		await splates.run(deps, ["add", "alpha", "--goal", "land it"]);
+		const { path } = await env.service.find("alpha");
+		await env.fs.mkdir(join(path, "context"));
+		await env.fs.mkdir(join(env.root, "notes"));
+		await env.fs.write(
+			join(path, "splates.config.ts"),
+			'export default { notesDir: "context" };\n',
+		);
+		await env.fs.write(
+			join(path, "context/a.md"),
+			"---\ndescription: Worktree convention\n---\n",
+		);
+		await env.fs.write(
+			join(env.root, "notes/a.md"),
+			"---\ndescription: Main convention\n---\n",
+		);
+		env.ps.cd(join(path, "context"));
+		const count = env.log.entries.length;
+		await splates.run(deps, ["notes"]);
+		expect(env.log.entries.slice(count).map((entry) => entry.message)).toEqual([
+			"Worktree convention",
+		]);
+	});
+
+	it("runs its commands against the dependencies it is given", async () => {
+		await splates.run(deps, ["add", "alpha", "--goal", "land it"]);
+		await splates.run(deps, ["list", "--json"]);
+
+		const rows = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(rows).toMatchObject([{ task: "alpha", status: "working" }]);
+		expect(
+			await env.fs.exists(join(`${env.root}-splates.noindex`, "alpha")),
+		).toBe(true);
+	});
+
+	it("prints the roster from outside any repository", async () => {
+		const away = join(env.splatesHome, "..");
+		await env.fs.mkdir(away);
+		env.ps.cd(away);
+		await splates.run(deps, ["agents", "--json"]);
+
+		const roster = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(roster.map((agent: { id: string }) => agent.id)).toEqual([
+			"claude",
+			"codex",
+		]);
+		expect(await env.fs.exists(join(env.splatesHome, "agents.json"))).toBe(
+			true,
+		);
+	});
+
+	it("prints setup's progress and skips a step from outside any repository", async () => {
+		const away = join(env.splatesHome, "..");
+		await env.fs.mkdir(away);
+		env.ps.cd(away);
+		await splates.run(deps, ["setup", "dictation", "--skip"]);
+		await splates.run(deps, ["setup", "--json"]);
+
+		const progress = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(progress.next).toBe("opencode-install");
+		expect(
+			progress.areas.find((area: { id: string }) => area.id === "dictation")
+				.skipped,
+		).toBe(1);
+	});
+
+	it("prints what undoing an area would forget, and undoes nothing", async () => {
+		await env.secrets.device.set("OPENAI_API_KEY", "sk-test");
+
+		await splates.run(deps, ["setup", "dictation", "--undo", "--json"]);
+
+		const plan = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(plan).toMatchObject({
+			area: "dictation",
+			creds: [{ name: "OPENAI_API_KEY", keptFor: null }],
+			refused: null,
+		});
+		expect(await env.secrets.device.get("OPENAI_API_KEY")).toBe("sk-test");
+	});
+
+	// scry-ignore simple-test-setup: the started task is what numbers the queued task after it, which this case checks.
+	it("edits the queued tasks added beside a started one", async () => {
+		await splates.run(deps, ["add", "alpha", "--goal", "land it"]);
+		await env.fs.write(join(env.root, "a.png"), "a");
+		await splates.run(deps, [
+			"task",
+			"add",
+			"write docs",
+			"the CLI first",
+			"--slug",
+			"cli-docs",
+			"--file",
+			"a.png",
+		]);
+		// Task alpha took number 1, so the queued task is numbered after it.
+		const [queued] = await env.tasks.all();
+		const id = queued?.id ?? 0;
+		expect(id).toBe(2);
+		const [attached = ""] = queued?.files ?? [];
+		await splates.run(deps, [
+			"task",
+			"update",
+			String(id),
+			"--subject",
+			"write the docs",
+			"--slug",
+			"docs",
+			"--position",
+			"1",
+			"--remove-file",
+			basename(attached),
+		]);
+		expect((await env.tasks.find(id)).state).toMatchObject({
+			subject: "write the docs",
+			slug: "docs",
+			text: "the CLI first",
+			position: 1,
+			files: [],
+		});
+
+		await splates.run(deps, ["log", "--json"]);
+		const entries = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(entries.map((entry: { action: string }) => entry.action)).toContain(
+			"task update",
+		);
+	});
+
+	it("reports a refusal as a reason, a message and an exit code", async () => {
+		await splates.run(deps, ["claim", "nope"]);
+
+		expect(env.out()).toContain('"reason":"not_found"');
+		expect(env.proc.lastExit()).toBe(8);
+	});
+
+	it("refuses a task with no Goal, and writes the one it is given into its plan", async () => {
+		await splates.run(deps, ["add", "alpha"]);
+
+		expect(env.out()).toContain('"reason":"usage"');
+		expect(env.out()).toContain("--goal");
+		expect((await env.service.find("alpha")).gone).toBe(true);
+
+		await splates.run(deps, [
+			"add",
+			"alpha",
+			"--goal",
+			"Stop the 413 retries.",
+		]);
+		const { path } = await env.service.find("alpha");
+		expect(await env.fs.read(join(path, "SPLATES.md"))).toContain(
+			"## Goal\n\nStop the 413 retries.",
+		);
+		expect((await env.journal.tail(1))[0]).toMatchObject({
+			action: "add",
+			goal: "Stop the 413 retries.",
+		});
+	});
+
+	it("logs the task it queues, with where it went", async () => {
+		await splates.run(deps, ["task", "add", "first", "--slug", "first"]);
+		await splates.run(deps, [
+			"task",
+			"add",
+			"Upload retries forever on a 413",
+			"--slug",
+			"upload-413",
+			"--position",
+			"1",
+			"--lane",
+			"new",
+		]);
+
+		expect((await env.journal.tail(1))[0]).toMatchObject({
+			action: "task add",
+			reason: null,
+			number: 2,
+			subject: "Upload retries forever on a 413",
+			lane: 1,
+			position: 1,
+		});
+	});
+
+	it("lists the thinking levels an agent offers, starts a task on one, and refuses any other", async () => {
+		await env.fs.write(
+			join(env.splatesHome, "offered.json"),
+			JSON.stringify({
+				format: 1,
+				agents: {
+					claude: [
+						{
+							id: "effort",
+							name: "Effort",
+							type: "select",
+							category: "thought_level",
+							current: "default",
+							options: ["default", "low", "high"].map((value) => ({
+								value,
+								name: value,
+								description: null,
+							})),
+						},
+					],
+				},
+			}),
+		);
+		await splates.run(deps, ["agents"]);
+		expect(env.out()).toContain("THINKING  default, low, high");
+
+		await splates.run(deps, [
+			"add",
+			"alpha",
+			"--goal",
+			"Style it.",
+			"--agent",
+			"claude",
+			"--effort",
+			"max",
+		]);
+		expect(env.proc.lastExit()).toBe(1);
+		expect(env.out()).toContain("use one of default, low, high");
+
+		await splates.run(deps, [
+			"add",
+			"alpha",
+			"--goal",
+			"Style it.",
+			"--agent",
+			"claude",
+			"--effort",
+			"High",
+		]);
+		expect((await env.service.find("alpha")).state?.dispatch).toMatchObject({
+			agent: "claude",
+			effort: "high",
+		});
+
+		await splates.run(deps, [
+			"task",
+			"add",
+			"Restyle the header",
+			"--slug",
+			"header-style",
+			"--agent",
+			"claude",
+			"--effort",
+			"low",
+		]);
+		expect((await env.tasks.all()).at(-1)?.state.assignee).toEqual({
+			agent: "claude",
+			effort: "low",
+		});
+	});
+
+	it("refuses a port that cannot exist rather than trying to listen", async () => {
+		// As the supervisor runs it.
+		env.proc.env[SERVING] = "1";
+		await splates.run(deps, ["server", "--port", "99999"]);
+
+		expect(env.out()).not.toContain("  reply ");
+		expect(env.proc.lastExit()).toBe(1);
+	});
+
+	it("says no tunnel is saved, and requests the token a setup needs", async () => {
+		await splates.run(deps, ["tunnel", "status"]);
+		expect(env.out()).toContain("no tunnel saved");
+
+		await splates.run(deps, [
+			"tunnel",
+			"setup",
+			"splates.example.com",
+			"--email",
+			"me@example.com",
+		]);
+		expect(env.out()).toContain("requested on the Creds page");
+		expect(env.proc.lastExit()).toBe(25);
+		expect(await env.creds.requests()).toMatchObject([
+			{ name: "SPLATES_CLOUDFLARE_API_TOKEN", scope: "device", status: "open" },
+		]);
+	});
+});