spur-board 0.1.0 → 0.2.0

package/dist/cli.mjs

@@ -1,26 +1,18 @@
-import { o as OPERATIONS } from "./src-CqH_W7D8.mjs";
-import { a as renderCliError, i as errorExitCode, n as requestTokenEnrollment, o as escapeTerminalControls, r as CliError, t as requestOperation } from "./client-C1hJzdYE.mjs";
-import { n as loadEnrollmentConfig, t as loadClientConfig } from "./config-DQmktVi-.mjs";
+import { F as configSchema, I as SLACK_BOT_SCOPES, s as OPERATIONS } from "./src-D3PJf7bc.mjs";
+import { a as renderCliError, i as errorExitCode, n as requestTokenEnrollment, o as escapeTerminalControls, r as CliError, t as requestOperation } from "./client-8Y8bDaQw.mjs";
+import { n as loadEnrollmentConfig, t as loadClientConfig } from "./config-xzIjNtfV.mjs";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, hostname, userInfo } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { Command, CommanderError } from "@commander-js/extra-typings";
 import { z } from "zod";
 import YAML from "yaml";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { parseEnv } from "node:util";
 import { access, cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 //#region src/manifest.ts
-const botScopes = [
-	"chat:write",
-	"chat:write.customize",
-	"groups:history",
-	"groups:read",
-	"app_mentions:read",
-	"commands",
-	"reactions:write"
-];
 function renderSlackManifest(options = {}) {
 	const appName = (options.appName ?? "spur-board").trim();
 	const command = options.command ?? "/board";
@@ -44,7 +36,7 @@ function renderSlackManifest(options = {}) {
 				should_escape: false
 			}]
 		},
-		oauth_config: { scopes: { bot: [...botScopes] } },
+		oauth_config: { scopes: { bot: [...SLACK_BOT_SCOPES] } },
 		settings: {
 			event_subscriptions: { bot_events: ["message.groups", "app_mention"] },
 			interactivity: { is_enabled: true },
@@ -53,6 +45,327 @@ function renderSlackManifest(options = {}) {
 	}, { lineWidth: 0 });
 }
 //#endregion
+//#region src/doctor.ts
+function systemRun(command, args, env) {
+	const result = spawnSync(command, [...args], {
+		encoding: "utf8",
+		timeout: 5e3,
+		...env === void 0 ? {} : { env }
+	});
+	return {
+		exitCode: result.status ?? 1,
+		stdout: result.stdout
+	};
+}
+function environmentOf(pid) {
+	try {
+		const content = readFileSync(`/proc/${pid}/environ`, "utf8");
+		return Object.fromEntries(content.split("\0").filter(Boolean).map((entry) => {
+			const split = entry.indexOf("=");
+			return [entry.slice(0, split), entry.slice(split + 1)];
+		}));
+	} catch {
+		return null;
+	}
+}
+function liveSessions() {
+	const sessions = [];
+	let pids;
+	try {
+		pids = readdirSync("/proc").filter((entry) => /^\d+$/.test(entry));
+	} catch {
+		return sessions;
+	}
+	for (const pid of pids) {
+		const env = environmentOf(pid);
+		if (!env?.["SPUR_SESSION"] || !env["PATH"]) continue;
+		const started = systemRun("ps", [
+			"-o",
+			"etimes=",
+			"-p",
+			pid
+		]);
+		const elapsedSeconds = Number(started.stdout.trim());
+		const startAt = started.exitCode === 0 && Number.isFinite(elapsedSeconds) && elapsedSeconds >= 0 ? Date.now() - elapsedSeconds * 1e3 : NaN;
+		let cwd;
+		try {
+			cwd = readlinkSync(`/proc/${pid}/cwd`);
+		} catch {}
+		sessions.push({
+			id: env["SPUR_SESSION"],
+			...env["SPUR_PROJECT"] ? { project: env["SPUR_PROJECT"] } : {},
+			path: env["PATH"],
+			...env["CODEX_HOME"] ? { codexHome: env["CODEX_HOME"] } : {},
+			...cwd ? { cwd } : {},
+			...Number.isFinite(startAt) ? { startAt } : {}
+		});
+	}
+	return sessions;
+}
+const defaultPorts = {
+	readText: (path) => readFileSync(path, "utf8"),
+	secretFile: (path) => {
+		const resolved = realpathSync(path);
+		const stat = statSync(resolved);
+		return {
+			path: resolved,
+			isFile: stat.isFile(),
+			mode: stat.mode & 511
+		};
+	},
+	listDir: readdirSync,
+	exists: existsSync,
+	run: systemRun,
+	sessions: liveSessions,
+	fetcher: fetch,
+	productVersion: () => {
+		const value = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+		if (value && typeof value === "object" && "version" in value && typeof value.version === "string") return value.version;
+		throw new Error("Invalid package version");
+	}
+};
+function result(id, ok, fix) {
+	return {
+		id,
+		status: ok ? "pass" : "fail",
+		blocking: !ok,
+		fix: ok ? null : fix
+	};
+}
+function warning(id, fix) {
+	return {
+		id,
+		status: "warning",
+		blocking: false,
+		fix
+	};
+}
+function configFile(env, home) {
+	const boardHome = env["BOARD_HOME"];
+	if (boardHome) return join(resolve(boardHome), "config.yaml");
+	const xdg = env["XDG_CONFIG_HOME"];
+	return join(xdg && isAbsolute(xdg) ? xdg : join(home, ".config"), "spur-board", "config.yaml");
+}
+function unitFile(env, home) {
+	const xdg = env["XDG_CONFIG_HOME"];
+	return join(xdg && isAbsolute(xdg) ? xdg : join(home, ".config"), "systemd", "user", "spur-board.service");
+}
+function localSecrets(config, path, ports) {
+	let file;
+	try {
+		file = ports.secretFile(path);
+	} catch {
+		let candidate;
+		try {
+			candidate = ports.listDir(dirname(path)).find((name) => {
+				if (name === "secrets.env" || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.env$/.test(name)) return false;
+				try {
+					return ports.secretFile(join(dirname(path), name)).isFile;
+				} catch {
+					return false;
+				}
+			});
+		} catch {}
+		return {
+			...result("secrets", false, candidate ? `Create secrets.env with mode 0600; rename ${candidate} to secrets.env if it contains the intended tokens.` : "Create secrets.env as a regular file with mode 0600."),
+			present: []
+		};
+	}
+	if (!file.isFile) return result("secrets", false, "Make secrets.env a regular file with mode 0600.");
+	if (file.mode !== 384) return result("secrets", false, "Set secrets.env mode to 0600 with chmod 600.");
+	let names;
+	try {
+		names = parseEnv(ports.readText(file.path));
+	} catch {
+		names = {};
+	}
+	const slackConfigured = Boolean(config.slack.channels.feed || config.slack.channels.orchestrators);
+	const required = [
+		"GITHUB_TOKEN",
+		...config.projects.some((project) => project.tracker.type === "jira") ? ["JIRA_EMAIL", "JIRA_API_TOKEN"] : [],
+		...slackConfigured ? ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"] : []
+	];
+	const missing = required.filter((name) => !names[name]);
+	return {
+		...result("secrets", missing.length === 0, `Add ${missing.join(", ")} to the private secrets.env file.`),
+		present: required.filter((name) => Boolean(names[name]))
+	};
+}
+function stamp(ports, path) {
+	try {
+		const value = JSON.parse(ports.readText(path));
+		if (value && typeof value === "object" && "version" in value && typeof value.version === "string" && "installedAt" in value && typeof value.installedAt === "string") {
+			const installedAt = Date.parse(value.installedAt);
+			if (Number.isFinite(installedAt)) return {
+				version: value.version,
+				installedAt
+			};
+		}
+	} catch {}
+	return null;
+}
+function nodeFromUnit(unit) {
+	const line = /^ExecStart=(.*)$/m.exec(unit)?.[1];
+	if (!line?.startsWith("\"")) return null;
+	let path = "";
+	for (let index = 1; index < line.length; index++) {
+		const char = line[index];
+		if (char === "\"") return line[index + 1] === " " ? path : null;
+		if (char === "\\") {
+			const escaped = line[++index];
+			if (escaped !== "\\" && escaped !== "\"") return null;
+			path += escaped;
+		} else if (char === "%") {
+			if (line[++index] !== "%") return null;
+			path += "%";
+		} else {
+			if (char === void 0) return null;
+			path += char;
+		}
+	}
+	return null;
+}
+const remoteBaseIds = [
+	"secrets",
+	"jira.credentials",
+	"github.credentials",
+	"spur.api",
+	"operator.path"
+];
+const remoteSlackIds = [
+	"slack.auth",
+	"slack.orchestrators_member",
+	"slack.feed_member",
+	"slack.command"
+];
+const remoteIds = [
+	...remoteBaseIds,
+	...remoteSlackIds,
+	"slack.configured"
+];
+function remoteIdSet(slackConfigured) {
+	return [...remoteBaseIds, ...slackConfigured ? remoteSlackIds : ["slack.configured"]];
+}
+function remoteChecks(value) {
+	if (!value || typeof value !== "object" || !("version" in value) || !("checks" in value)) return null;
+	if (typeof value.version !== "string" || !Array.isArray(value.checks)) return null;
+	const checks = [];
+	for (const entry of value.checks) {
+		if (entry === null || typeof entry !== "object" || !("id" in entry) || !("status" in entry) || !("blocking" in entry) || !("fix" in entry) || typeof entry.id !== "string" || !remoteIds.some((id) => id === entry.id) || typeof entry.status !== "string" || ![
+			"pass",
+			"fail",
+			"warning"
+		].includes(entry.status) || typeof entry.blocking !== "boolean" || entry.fix !== null && typeof entry.fix !== "string") return null;
+		checks.push({
+			id: entry.id,
+			status: entry.status,
+			blocking: entry.blocking,
+			fix: entry.fix
+		});
+	}
+	const ids = new Set(checks.map((entry) => entry.id));
+	if (![true, false].some((slackConfigured) => {
+		const expected = remoteIdSet(slackConfigured);
+		return checks.length === expected.length && expected.every((id) => ids.has(id));
+	})) return null;
+	return {
+		version: value.version,
+		checks
+	};
+}
+/** Local preflight remains useful even when the daemon is stopped. */
+async function runDoctor(options = {}) {
+	const env = options.env ?? process.env;
+	const home = options.home ?? homedir();
+	const ports = {
+		...defaultPorts,
+		...options.ports
+	};
+	const checks = [];
+	let config;
+	try {
+		const parsed = YAML.parseDocument(ports.readText(configFile(env, home)));
+		if (parsed.errors.length > 0) throw new Error("Invalid YAML");
+		const validated = configSchema.safeParse(parsed.toJS());
+		if (!validated.success) {
+			const path = validated.error.issues[0]?.path.map(String).join(".") || "root";
+			checks.push(result("config", false, `Correct ${path} in config.yaml using the configuration schema.`));
+			return checks;
+		}
+		config = validated.data;
+		checks.push(result("config", true, "Correct config.yaml."));
+	} catch {
+		checks.push(result("config", false, "Create or correct config.yaml using the configuration schema."));
+		return checks;
+	}
+	if (options.offline) return checks;
+	const unitPath = unitFile(env, home);
+	let unit = null;
+	try {
+		unit = ports.readText(unitPath);
+	} catch {}
+	checks.push(result("service.installed", unit !== null, "Run board service install."));
+	const node = unit === null ? null : nodeFromUnit(unit);
+	checks.push(result("service.node", node !== null && ports.exists(node), "Reinstall the service with a valid Node executable path."));
+	checks.push(result("service.running", ports.run("systemctl", [
+		"--user",
+		"is-active",
+		"spur-board.service"
+	]).exitCode === 0, "Start or restart the user service and inspect its journal."));
+	checks.push(result("flock", ports.run("flock", ["--version"]).exitCode === 0, "Install flock from util-linux."));
+	const currentBoard = ports.run("board", ["--version"]);
+	checks.push(result("path.current", currentBoard.exitCode === 0, "Install board into the current PATH."));
+	const sessions = ports.sessions();
+	const live = sessions[0];
+	const spurBoard = live === void 0 ? null : ports.run("board", ["--version"], {
+		HOME: home,
+		PATH: live.path
+	});
+	checks.push(live === void 0 ? warning("path.spur", "Start a Spur session, then rerun board doctor.") : result("path.spur", spurBoard?.exitCode === 0, "Install board into the live Spur session PATH."));
+	const configured = new Set(config.projects.flatMap((project) => project.spurProjects.map((spur) => spur.name)));
+	const codexSessions = sessions.filter((session) => session.codexHome && session.project && configured.has(session.project));
+	checks.push(codexSessions.length === 0 ? warning("skills.codex_visibility", "Start a Codex session in a configured Spur project to verify skill visibility.") : result("skills.codex_visibility", codexSessions.some((session) => session.cwd !== void 0 && ports.exists(join(session.cwd, ".agents", "skills", "spur-board", "SKILL.md")) || session.codexHome !== void 0 && ports.exists(join(session.codexHome, "skills", "spur-board", "SKILL.md"))), "Add .agents/skills/spur-board to the Spur project's symlinks in its config and start a new session."));
+	const version = ports.productVersion();
+	const stamps = [".claude", ".codex"].flatMap((agent) => ["spur-board", "spur-board-setup"].map((skill) => stamp(ports, join(home, agent, "skills", skill, ".spur-board-install.json"))));
+	const latestInstall = Math.max(...stamps.flatMap((entry) => entry === null ? [] : [entry.installedAt]));
+	const stale = sessions.filter((session) => session.startAt !== void 0 && session.startAt < latestInstall);
+	const unknownStarts = sessions.some((session) => session.startAt === void 0);
+	const staleIds = stale.map((session) => session.id).filter((id) => /^[a-zA-Z0-9_-]+$/.test(id)).slice(0, 10);
+	checks.push(stale.length > 0 || unknownStarts ? warning("sessions.stale", `Restart sessions started before the last skill install${staleIds.length ? `: ${staleIds.join(", ")}` : ""}; verify sessions whose start time is unavailable.`) : result("sessions.stale", true, "Restart older sessions."));
+	let remote = null;
+	try {
+		const base = env["BOARD_DAEMON_URL"] || `http://127.0.0.1:${String(config.http.port)}`;
+		const response = await ports.fetcher(new URL("/v1/doctor", base), { signal: AbortSignal.timeout(8e3) });
+		if (response.ok) remote = remoteChecks(await response.json());
+	} catch {}
+	checks.push(result("daemon.available", remote !== null, "Start or restart the user service."));
+	const secrets = localSecrets(config, join(dirname(configFile(env, home)), "secrets.env"), ports);
+	const daemonSecrets = remote?.checks.find((check) => check.id === "secrets");
+	checks.push(secrets.status === "pass" && daemonSecrets?.status === "fail" ? {
+		...secrets,
+		status: "fail",
+		blocking: true,
+		fix: daemonSecrets.fix ?? "Add the missing required keys to secrets.env and restart the daemon."
+	} : secrets);
+	if (remote === null) checks.push(...remoteIdSet(Boolean(config.slack.channels.feed || config.slack.channels.orchestrators)).filter((id) => id !== "secrets").map((id) => warning(id, id === "slack.configured" ? "Slack is not configured: questions addressed to you are only visible through board inbox. Run the spur-board-setup skill to configure slack.channels." : "Start the daemon, then rerun board doctor to complete this check.")));
+	else checks.push(...remote.checks.filter((check) => check.id !== "secrets"));
+	const availableVersions = [
+		...currentBoard.exitCode === 0 ? [currentBoard.stdout.trim()] : [],
+		...spurBoard?.exitCode === 0 ? [spurBoard.stdout.trim()] : [],
+		...remote === null ? [] : [remote.version],
+		...stamps.flatMap((entry) => entry === null ? [] : [entry.version])
+	];
+	checks.push(result("versions", availableVersions.every((available) => available === version), "Install matching CLI and skills versions, then restart the daemon."));
+	return checks;
+}
+function renderDoctor(checks, json) {
+	if (json) return JSON.stringify(checks);
+	return checks.map((check) => {
+		const present = check.present === void 0 ? "" : ` (present: ${check.present.join(", ") || "none"})`;
+		return `${check.status.toUpperCase()} ${check.id}${present}${check.fix === null ? "" : `: ${check.fix}`}`;
+	}).join("\n");
+}
+//#endregion
 //#region src/service.ts
 const serviceName = "spur-board.service";
 function configHome(env, home) {
@@ -633,6 +946,21 @@ function registerSetupCommands(program, options, io, env) {
 			throw error;
 		}
 	};
+	const doctor = commandFor(program, "doctor");
+	doctor.description("Check whether the installation is ready and show exact fixes.");
+	doctor.option("--offline", "Validate config only, without network or process checks.");
+	doctor.option("--json", "Print the check list as JSON.");
+	doctor.action(async () => {
+		const checks = await runDoctor({
+			env,
+			...options.home === void 0 ? {} : { home: options.home },
+			...doctor.opts()["offline"] ? { offline: true } : {},
+			...options.doctor === void 0 ? {} : { ports: options.doctor }
+		});
+		const json = Boolean(doctor.opts()["json"] || program.opts()["json"]);
+		io.stdout(`${renderDoctor(checks, json)}\n`);
+		if (checks.some((check) => check.blocking)) throw new CommanderError(1, "board.error", "Doctor found blocking failures.");
+	});
 	commandFor(program, "skills install").description("Install bundled skills for Claude Code and Codex.").action(async () => {
 		print(await runSetup(() => installSkills(options.setup)));
 	});
@@ -796,4 +1124,4 @@ async function runCli(argv, options = {}) {
 	}
 }
 //#endregion
-export { createProgram, runCli };
+export { createProgram, exampleCommand, runCli };

package/dist/{client-C1hJzdYE.mjs → client-8Y8bDaQw.mjs}

@@ -1,4 +1,4 @@
-import { A as errorEnvelopeSchema, O as ERRORS, c as renderJsonError, j as successEnvelopeSchema, k as errorContextSchema } from "./src-CqH_W7D8.mjs";
+import { M as errorContextSchema, N as errorEnvelopeSchema, P as successEnvelopeSchema, j as ERRORS, l as renderJsonError } from "./src-D3PJf7bc.mjs";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { request } from "node:http";

package/dist/client.mjs

@@ -1,2 +1,2 @@
-import { n as requestTokenEnrollment, t as requestOperation } from "./client-C1hJzdYE.mjs";
+import { n as requestTokenEnrollment, t as requestOperation } from "./client-8Y8bDaQw.mjs";
 export { requestOperation, requestTokenEnrollment };

package/dist/{config-DQmktVi-.mjs → config-xzIjNtfV.mjs}

@@ -1,4 +1,4 @@
-import { r as CliError } from "./client-C1hJzdYE.mjs";
+import { r as CliError } from "./client-8Y8bDaQw.mjs";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";