@aibyzero/byz 0.0.0 → 0.1.1

package/dist/runtime/utils/windows-self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-self-update.js","sourceRoot":"","sources":["../../src/utils/windows-self-update.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { basename, dirname, join, relative, resolve, toNamespacedPath } from \"node:path\";\nimport { getCwdRelativePath } from \"./paths.ts\";\n\nconst QUARANTINE_DIR_NAME = \".pi-native-quarantine\";\n\nfunction normalizePath(path: string): string {\n\treturn toNamespacedPath(resolve(path));\n}\n\nfunction getQuarantineRoot(packageDir: string): string | undefined {\n\tlet current = resolve(packageDir);\n\twhile (true) {\n\t\tif (basename(current).toLowerCase() === \"node_modules\") {\n\t\t\treturn join(current, QUARANTINE_DIR_NAME);\n\t\t}\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) {\n\t\t\treturn undefined;\n\t\t}\n\t\tcurrent = parent;\n\t}\n}\n\nfunction getLoadedSharedObjectsInPackageDir(packageDir: string): string[] {\n\tconst sharedObjects = (process.report.getReport() as { sharedObjects?: unknown }).sharedObjects;\n\tif (!Array.isArray(sharedObjects)) {\n\t\treturn [];\n\t}\n\n\tconst root = normalizePath(packageDir).toLowerCase();\n\tconst seen = new Set<string>();\n\tconst loadedFiles: string[] = [];\n\tfor (const value of sharedObjects) {\n\t\tif (typeof value !== \"string\") {\n\t\t\tcontinue;\n\t\t}\n\t\tconst filePath = normalizePath(value);\n\t\tconst comparisonPath = filePath.toLowerCase();\n\t\tif (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {\n\t\t\tcontinue;\n\t\t}\n\t\tseen.add(comparisonPath);\n\t\tloadedFiles.push(filePath);\n\t}\n\treturn loadedFiles;\n}\n\nexport function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void {\n\tconst quarantineRoot = getQuarantineRoot(packageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\ttry {\n\t\trmSync(quarantineRoot, { recursive: true, force: true });\n\t} catch {\n\t\t// A previous pi process may still be exiting and holding a native addon.\n\t}\n}\n\nexport function quarantineWindowsNativeDependencies(packageDir: string): void {\n\tconst resolvedPackageDir = normalizePath(packageDir);\n\tconst quarantineRoot = getQuarantineRoot(resolvedPackageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\n\tconst loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);\n\tif (loadedFiles.length === 0) {\n\t\treturn;\n\t}\n\n\tconst quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);\n\tfor (const loadedFile of loadedFiles) {\n\t\tif (!existsSync(loadedFile)) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));\n\t\tmkdirSync(dirname(quarantinePath), { recursive: true });\n\t\trenameSync(loadedFile, quarantinePath);\n\t\tcopyFileSync(quarantinePath, loadedFile);\n\t}\n}\n"]}

package/dist/update.js

@@ -0,0 +1,134 @@
+import { spawn } from "node:child_process";
+import { gt, valid } from "semver";
+import { getSelfUpdateCommand, getSelfUpdateManualCommand, VERSION } from "./runtime/bundle/index.js";
+
+export const BYZ_PACKAGE_NAME = "@aibyzero/byz";
+const BYZ_LATEST_URL = "https://registry.npmjs.org/@aibyzero%2fbyz/latest";
+const BYZ_NPM_REGISTRY_ARG = "--@aibyzero:registry=https://registry.npmjs.org/";
+const UPDATE_TIMEOUT_MS = 10_000;
+
+export async function getLatestByzRelease(currentVersion, options = {}) {
+	const fetchRelease = options.fetch ?? globalThis.fetch;
+	const signal = options.signal ?? AbortSignal.timeout(UPDATE_TIMEOUT_MS);
+	const response = await fetchRelease(BYZ_LATEST_URL, {
+		headers: {
+			accept: "application/json",
+			"User-Agent": `byz/${currentVersion}`,
+		},
+		redirect: "error",
+		signal,
+	});
+	if (!response.ok) {
+		throw new Error(`Could not determine latest BYZ version (HTTP ${response.status}).`);
+	}
+	const data = await response.json();
+	if (data?.name !== BYZ_PACKAGE_NAME || typeof data.version !== "string" || valid(data.version) !== data.version) {
+		throw new Error("The npm registry returned invalid BYZ release metadata.");
+	}
+	return { name: BYZ_PACKAGE_NAME, version: data.version };
+}
+
+export function planByzUpdate(currentVersion, latestVersion, options = {}) {
+	if (valid(currentVersion) !== currentVersion || valid(latestVersion) !== latestVersion) {
+		throw new Error("BYZ update metadata contains an invalid semantic version.");
+	}
+	if (gt(currentVersion, latestVersion)) return { action: "ahead", version: latestVersion };
+	if (!options.force && !gt(latestVersion, currentVersion)) return { action: "current", version: latestVersion };
+	return { action: "update", version: latestVersion };
+}
+
+async function runSelfUpdateCommand(command, spawnProcess = spawn) {
+	for (const step of command.steps ?? [command]) {
+		await new Promise((resolveRun, rejectRun) => {
+			const child = spawnProcess(step.command, step.args, { shell: false, stdio: "inherit" });
+			child.once("error", rejectRun);
+			child.once("close", (code, signal) => {
+				if (code === 0) resolveRun();
+				else if (signal) rejectRun(new Error(`${step.display} terminated by signal ${signal}.`));
+				else rejectRun(new Error(`${step.display} exited with code ${code ?? "unknown"}.`));
+			});
+		});
+	}
+}
+
+function formatCommand(command, args) {
+	return [command, ...args].map((arg) => (/\s/.test(arg) ? `"${arg}"` : arg)).join(" ");
+}
+
+export function getByzUpdateCommand(installSpec, getUpdateCommand = getSelfUpdateCommand) {
+	const command = getUpdateCommand(BYZ_PACKAGE_NAME, undefined, {
+		packageName: BYZ_PACKAGE_NAME,
+		installSpec,
+	});
+	if (!command || command.command !== "npm" || command.steps?.some((step) => step.command !== "npm")) {
+		return undefined;
+	}
+	const secureStep = (step) => {
+		const args = [BYZ_NPM_REGISTRY_ARG, ...step.args];
+		return { ...step, args, display: formatCommand(step.command, args) };
+	};
+	const secured = secureStep(command);
+	if (!command.steps) return secured;
+	const steps = command.steps.map(secureStep);
+	return { ...secured, display: steps.map((step) => step.display).join(" && "), steps };
+}
+
+export function getByzManualUpdateCommand(installSpec, getUpdateCommand = getSelfUpdateManualCommand) {
+	return getByzUpdateCommand(installSpec, getUpdateCommand);
+}
+
+export async function handleByzUpdate(args, dependencies = {}) {
+	if (args[0] !== "update") return false;
+	const options = args.slice(1);
+	const stderr = dependencies.stderr ?? console.error;
+	const stdout = dependencies.stdout ?? console.log;
+	if (options.includes("--help") || options.includes("-h")) {
+		stdout("Usage: byz update [--force]");
+		stdout("Updates only an npm-managed global @aibyzero/byz installation.");
+		return true;
+	}
+	const invalid = options.filter((option) => option !== "--force");
+	if (invalid.length > 0 || options.filter((option) => option === "--force").length > 1) {
+		stderr("Invalid BYZ update arguments. Expected only --force or --help.");
+		process.exitCode = 1;
+		return true;
+	}
+
+	const currentVersion = dependencies.currentVersion ?? VERSION;
+	const getLatestRelease = dependencies.getLatestRelease ?? getLatestByzRelease;
+	const latest = await getLatestRelease(currentVersion);
+	if (latest.name !== BYZ_PACKAGE_NAME) {
+		throw new Error("The release source attempted to substitute the BYZ package identity.");
+	}
+	const plan = planByzUpdate(currentVersion, latest.version, { force: options.includes("--force") });
+	if (plan.action === "current") {
+		stdout(`BYZ is already up to date (v${currentVersion}).`);
+		return true;
+	}
+	if (plan.action === "ahead") {
+		stdout(
+			`BYZ v${currentVersion} is newer than the latest published version v${plan.version}; no downgrade performed.`,
+		);
+		return true;
+	}
+
+	const installSpec = `${BYZ_PACKAGE_NAME}@${plan.version}`;
+	const command = getByzUpdateCommand(installSpec, dependencies.getUpdateCommand);
+	if (!command) {
+		const manualCommand = getByzManualUpdateCommand(installSpec, dependencies.getManualUpdateCommand);
+		stderr("BYZ can update only a writable npm-managed global installation.");
+		stderr(
+			manualCommand
+				? `Update this installation manually with: ${manualCommand.display}`
+				: "Update BYZ with the package manager, wrapper, or source checkout that provides this installation.",
+		);
+		process.exitCode = 2;
+		return true;
+	}
+
+	stdout(`Updating BYZ with ${command.display}...`);
+	const runCommand = dependencies.runCommand ?? runSelfUpdateCommand;
+	await runCommand(command);
+	stdout(`Updated BYZ from ${currentVersion} to ${plan.version}. Restart BYZ to use the new version.`);
+	return true;
+}

package/dist/workflows.js

@@ -0,0 +1,391 @@
+import { execFileSync } from "node:child_process";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	DefaultPackageManager,
+	getAgentDir,
+	loadSkillsFromDir,
+	parseGitUrl,
+	SettingsManager,
+} from "./runtime/bundle/index.js";
+
+const lockPath = fileURLToPath(new URL("../workflows.lock.json", import.meta.url));
+const packageDir = dirname(lockPath);
+let workflowsPromise;
+
+async function loadWorkflows() {
+	workflowsPromise ??= readFile(lockPath, "utf8").then((content) => {
+		const lock = JSON.parse(content);
+		if (lock.schemaVersion !== 1 || !lock.workflows) {
+			throw new Error("Unsupported BYZ workflow lock format.");
+		}
+		return Object.entries(lock.workflows).map(([id, workflow]) => ({ id, ...workflow }));
+	});
+	return workflowsPromise;
+}
+
+async function getWorkflow(id) {
+	const workflow = (await loadWorkflows()).find((candidate) => candidate.id === id);
+	if (!workflow) {
+		throw new Error(`Unknown workflow: ${id ?? "<missing>"}. Expected cm, cm-plugin, or none.`);
+	}
+	return workflow;
+}
+
+async function resolveConfiguredRoot(workflow) {
+	const configured = process.env[workflow.envRoot];
+	if (!configured) return undefined;
+	return { root: await realpath(resolve(configured)), source: "local" };
+}
+
+async function resolveBundledRoot(workflow) {
+	if (!workflow.bundled || !workflow.bundledPath) return undefined;
+	try {
+		return { root: await realpath(resolve(packageDir, workflow.bundledPath)), source: "bundled" };
+	} catch {
+		return undefined;
+	}
+}
+
+async function resolveManagedRoot(workflow) {
+	const cwd = process.cwd();
+	const agentDir = getAgentDir();
+	const settingsManager = SettingsManager.create(cwd, agentDir);
+	const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+
+	for (const configured of packageManager.listConfiguredPackages()) {
+		if (!configured.installedPath) continue;
+		try {
+			const packageJson = JSON.parse(await readFile(resolve(configured.installedPath, "package.json"), "utf8"));
+			if (packageJson.name === workflow.packageName) {
+				const settings =
+					configured.scope === "user" ? settingsManager.getGlobalSettings() : settingsManager.getProjectSettings();
+				const packageConfig = (settings.packages ?? []).find(
+					(candidate) => (typeof candidate === "string" ? candidate : candidate.source) === configured.source,
+				);
+				const autoloadDisabled =
+					typeof packageConfig === "object" &&
+					packageConfig.autoload === false &&
+					["extensions", "skills", "prompts", "themes"].every(
+						(resourceType) => !packageConfig[resourceType] || packageConfig[resourceType].length === 0,
+					);
+				return {
+					root: await realpath(configured.installedPath),
+					source: "managed",
+					configuredSource: configured.source,
+					autoloadDisabled,
+				};
+			}
+		} catch {
+			// Ignore unrelated or incomplete configured packages.
+		}
+	}
+	return undefined;
+}
+
+async function resolveWorkflowRoot(workflow) {
+	return (
+		(await resolveConfiguredRoot(workflow)) ??
+		(await resolveBundledRoot(workflow)) ??
+		(await resolveManagedRoot(workflow))
+	);
+}
+
+async function assertDistinctRoots() {
+	const roots = [];
+	for (const workflow of await loadWorkflows()) {
+		const resolved = await resolveWorkflowRoot(workflow);
+		if (resolved) roots.push({ id: workflow.id, root: resolved.root });
+	}
+
+	for (let index = 0; index < roots.length; index++) {
+		for (let otherIndex = index + 1; otherIndex < roots.length; otherIndex++) {
+			const leftToRight = relative(roots[index].root, roots[otherIndex].root);
+			const rightToLeft = relative(roots[otherIndex].root, roots[index].root);
+			const contains = (candidate) =>
+				candidate === "" || (!candidate.startsWith(`..${sep}`) && candidate !== ".." && !isAbsolute(candidate));
+			if (contains(leftToRight) || contains(rightToLeft)) {
+				throw new Error(
+					`Workflow isolation violation: ${roots[index].id} and ${roots[otherIndex].id} roots overlap.`,
+				);
+			}
+		}
+	}
+}
+
+async function readWorkflowVersion(root) {
+	try {
+		const packageJson = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
+		if (packageJson.version) return packageJson.version;
+	} catch {
+		// Local development roots may not have package metadata yet.
+	}
+	try {
+		return (await readFile(resolve(root, "VERSION"), "utf8")).trim();
+	} catch {
+		return "unknown";
+	}
+}
+
+async function getWorkflowStatus(workflow) {
+	const resolved = await resolveWorkflowRoot(workflow);
+	if (!resolved) {
+		return { ...workflow, available: false, source: "unavailable" };
+	}
+	return {
+		...workflow,
+		available: true,
+		...resolved,
+		resolvedVersion: await readWorkflowVersion(resolved.root),
+	};
+}
+
+function extractPinnedGitCommit(source) {
+	const parsed = source ? parseGitUrl(source) : null;
+	return parsed?.ref && /^[0-9a-f]{40}$/i.test(parsed.ref) ? parsed.ref.toLowerCase() : undefined;
+}
+
+function readGitHead(root) {
+	try {
+		return execFileSync("git", ["-C", root, "rev-parse", "HEAD"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		})
+			.trim()
+			.toLowerCase();
+	} catch {
+		return undefined;
+	}
+}
+
+async function validateRequiredFile(root, relativePath, missingFiles) {
+	try {
+		if (!(await stat(resolve(root, relativePath))).isFile()) missingFiles.push(relativePath);
+	} catch {
+		missingFiles.push(relativePath);
+	}
+}
+
+async function validateWorkflowResources(status) {
+	const invalidSkills = [];
+	for (const skillPath of status.skillsPaths) {
+		const result = loadSkillsFromDir({ dir: resolve(status.root, skillPath), source: `byz:${status.id}` });
+		if (result.skills.length === 0) invalidSkills.push(skillPath);
+	}
+
+	let hasPrompt = false;
+	try {
+		const entries = await readdir(resolve(status.root, status.promptsPath), { withFileTypes: true });
+		hasPrompt = entries.some((entry) => entry.isFile() && entry.name.endsWith(".md"));
+	} catch {
+		// Report the prompt path below.
+	}
+
+	if (invalidSkills.length > 0 || !hasPrompt) {
+		const issues = [];
+		if (invalidSkills.length > 0) issues.push(`skills with no valid SKILL.md: ${invalidSkills.join(", ")}`);
+		if (!hasPrompt) issues.push(`prompt directory with no top-level Markdown: ${status.promptsPath}`);
+		throw new Error(`${status.name} has no Pi-loadable resources. ${issues.join("; ")}`);
+	}
+}
+
+async function validatePackageManifest(status) {
+	if (status.source === "local") return;
+	const packageJson = JSON.parse(await readFile(resolve(status.root, "package.json"), "utf8"));
+	if (packageJson.name !== status.packageName) {
+		throw new Error(`${status.name} package mismatch: expected ${status.packageName}, found ${packageJson.name}.`);
+	}
+	const normalize = (entries = []) => entries.map((entry) => entry.replace(/^\.\//, "")).sort();
+	if (
+		JSON.stringify(normalize(packageJson.pi?.skills)) !== JSON.stringify(normalize(status.skillsPaths)) ||
+		JSON.stringify(normalize(packageJson.pi?.prompts)) !== JSON.stringify(normalize([status.promptsPath]))
+	) {
+		throw new Error(`${status.name} Pi manifest does not match the BYZ workflow lock.`);
+	}
+}
+
+async function checkWorkflow(workflow) {
+	await assertDistinctRoots();
+	const status = await getWorkflowStatus(workflow);
+	if (!status.available) {
+		const installHint = workflow.private
+			? ` Run "byz workflow install ${workflow.id}" with repository access.`
+			: " Reinstall BYZ or set its local development override.";
+		throw new Error(`${workflow.name} is unavailable.${installHint}`);
+	}
+
+	const missingFiles = [];
+	for (const relativePath of workflow.requiredFiles) {
+		await validateRequiredFile(status.root, relativePath, missingFiles);
+	}
+	if (missingFiles.length > 0) {
+		throw new Error(`${workflow.name} is incomplete. Missing: ${missingFiles.join(", ")}`);
+	}
+	if (status.source !== "local" && status.resolvedVersion !== workflow.version) {
+		throw new Error(
+			`${workflow.name} version mismatch: expected ${workflow.version}, found ${status.resolvedVersion}.`,
+		);
+	}
+	await validateWorkflowResources(status);
+	await validatePackageManifest(status);
+	if (status.source === "managed") {
+		if (!status.autoloadDisabled) {
+			throw new Error(`${workflow.name} must be installed with Pi package autoload disabled.`);
+		}
+		const pinnedCommit = extractPinnedGitCommit(status.configuredSource);
+		if (!pinnedCommit) {
+			throw new Error(`${workflow.name} managed source must be pinned to a full Git commit SHA.`);
+		}
+		const installedCommit = readGitHead(status.root);
+		if (installedCommit !== pinnedCommit) {
+			throw new Error(
+				`${workflow.name} source mismatch: configured ${pinnedCommit}, installed ${installedCommit ?? "unknown"}.`,
+			);
+		}
+	}
+	return status;
+}
+
+function printStatus(status) {
+	console.log(`${status.id}: ${status.available ? "available" : "unavailable"}`);
+	console.log(`  package: ${status.packageName}`);
+	console.log(`  source: ${status.source}`);
+	console.log(`  expected: ${status.version}`);
+	if (status.resolvedVersion) console.log(`  version: ${status.resolvedVersion}`);
+	if (status.root) console.log(`  root: ${status.root}`);
+}
+
+export async function getWorkflowInstallRequest(args) {
+	if (args[0] !== "workflow" || args[1] !== "install") return undefined;
+	const workflow = await getWorkflow(args[2]);
+	if (workflow.bundled) {
+		throw new Error(`${workflow.name} is bundled with BYZ and does not need installation.`);
+	}
+	const source = process.env[workflow.sourceEnv];
+	if (!source) {
+		throw new Error(
+			`${workflow.sourceEnv} must contain the authorized private Git source pinned to a full commit SHA.`,
+		);
+	}
+	if (!extractPinnedGitCommit(source)) {
+		throw new Error(`${workflow.sourceEnv} must be a Git source pinned to a full 40-character commit SHA.`);
+	}
+	return { id: workflow.id, source };
+}
+
+export async function installWorkflowPackage(request) {
+	const workflow = await getWorkflow(request.id);
+	const cwd = process.cwd();
+	const agentDir = getAgentDir();
+	const settingsManager = SettingsManager.create(cwd, agentDir);
+	const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+	await packageManager.installAndPersist(request.source);
+
+	const packages = settingsManager.getGlobalSettings().packages ?? [];
+	let updated = false;
+	const disabledPackages = packages.map((configured) => {
+		const source = typeof configured === "string" ? configured : configured.source;
+		if (source !== request.source) return configured;
+		updated = true;
+		return { source, autoload: false };
+	});
+	if (!updated) throw new Error(`Installed ${workflow.name}, but its BYZ package setting was not found.`);
+	settingsManager.setPackages(disabledPackages);
+	await settingsManager.flush();
+	console.log(`Installed ${workflow.name} with package autoload disabled.`);
+}
+
+export function parseWorkflowOption(args) {
+	const forwardedArgs = [];
+	let selected;
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index];
+		if (arg === "--") {
+			forwardedArgs.push(...args.slice(index));
+			break;
+		}
+		if (arg === "--workflow") {
+			if (selected !== undefined) throw new Error("--workflow may only be specified once.");
+			const value = args[++index];
+			if (!value || value.startsWith("-")) throw new Error("--workflow requires cm, cm-plugin, or none.");
+			selected = value;
+			continue;
+		}
+		if (arg.startsWith("--workflow=")) {
+			if (selected !== undefined) throw new Error("--workflow may only be specified once.");
+			selected = arg.slice("--workflow=".length);
+			continue;
+		}
+		forwardedArgs.push(arg);
+	}
+	const workflowId = selected ?? process.env.BYZ_WORKFLOW ?? "cm";
+	if (!["cm", "cm-plugin", "none"].includes(workflowId)) {
+		throw new Error(`Unknown workflow: ${workflowId}. Expected cm, cm-plugin, or none.`);
+	}
+	return { forwardedArgs, workflowId };
+}
+
+export async function prepareWorkflowRuntimeArgs(args, options = {}) {
+	const { forwardedArgs, workflowId } = parseWorkflowOption(args);
+	if (options.load === false || workflowId === "none") {
+		return { args: forwardedArgs, workflowId };
+	}
+
+	const status = await checkWorkflow(await getWorkflow(workflowId));
+	const terminatorIndex = forwardedArgs.indexOf("--");
+	const optionArgs = forwardedArgs.slice(0, terminatorIndex === -1 ? forwardedArgs.length : terminatorIndex);
+	const noSkills = optionArgs.some((arg) => arg === "--no-skills" || arg === "-ns");
+	const noPrompts = optionArgs.some((arg) => arg === "--no-prompt-templates" || arg === "-np");
+	const workflowArgs = [];
+	if (!noSkills) {
+		workflowArgs.push(...status.skillsPaths.flatMap((skillPath) => ["--skill", resolve(status.root, skillPath)]));
+	}
+	if (!noPrompts) {
+		workflowArgs.push("--prompt-template", resolve(status.root, status.promptsPath));
+	}
+	return {
+		workflowId,
+		args: [...workflowArgs, ...forwardedArgs],
+	};
+}
+
+export async function handleWorkflowCommand(args) {
+	if (args[0] !== "workflow") return false;
+
+	try {
+		const command = args[1] ?? "list";
+		if (command === "list") {
+			await assertDistinctRoots();
+			for (const workflow of await loadWorkflows()) {
+				printStatus(await getWorkflowStatus(workflow));
+			}
+			return true;
+		}
+
+		if (command === "status") {
+			await assertDistinctRoots();
+			printStatus(await getWorkflowStatus(await getWorkflow(args[2])));
+			return true;
+		}
+
+		if (command === "check") {
+			const status = await checkWorkflow(await getWorkflow(args[2]));
+			console.log(`${status.id}: check passed`);
+			console.log(`  source: ${status.source}`);
+			console.log(`  version: ${status.resolvedVersion}`);
+			console.log(`  root: ${status.root}`);
+			return true;
+		}
+
+		if (command === "install") {
+			throw new Error("Workflow installation could not be delegated to the BYZ package manager.");
+		}
+
+		throw new Error(`Unknown workflow command: ${command}. Expected list, status, check, or install.`);
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+		return true;
+	}
+}