@rivus/agent 0.1.1 → 0.4.0

package/dist/cli.js

@@ -1,17 +1,520 @@
 #!/usr/bin/env node
-import { t as runRivusDaemonCli } from "./rivus-daemon-cli.js";
-import { pathToFileURL } from "node:url";
-import { resolve } from "node:path";
+import { C as resolveNodeRivusPluginModulePath, D as resolveFeishuEndpointCredentials, O as loadMergedLocalEnvFile, T as loadRivusDeploymentManifest, j as validateRivusDeploymentManifest, t as runRivusDaemonCli } from "./rivus-daemon-cli.js";
 import { Effect } from "effect";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lstat, mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+//#region src/infrastructure/project/rivus-project-doctor.ts
+const REQUIRED_FILES = Object.freeze([
+	"package.json",
+	"rivus.bootstrap.ts",
+	"rivus.config.json"
+]);
+const REQUIRED_DEPENDENCIES = Object.freeze([
+	"@rivus/agent",
+	"@earendil-works/pi-coding-agent",
+	"@larksuiteoapi/node-sdk"
+]);
+async function diagnoseRivusProject(options) {
+	const directory = resolve(options.directory);
+	const checks = [];
+	checks.push(checkNode(options.nodeVersion));
+	checks.push(await checkFiles(directory));
+	checks.push(await checkDependencies(directory));
+	const manifestResult = await checkManifest(directory);
+	checks.push(manifestResult.check);
+	const envFilePath = resolve(directory, options.envFilePath ?? ".env.local");
+	checks.push(await checkCredentials(manifestResult.manifest, envFilePath, options.env));
+	return Object.freeze({
+		checks: Object.freeze(checks),
+		directory,
+		ready: checks.every(({ status }) => status === "pass")
+	});
+}
+function checkNode(version) {
+	const [major, minor] = version.split(".").map(Number);
+	if (major === 24 && Number.isInteger(minor) && minor >= 11) return {
+		message: `Node.js ${version} satisfies the supported ^24.11 runtime`,
+		name: "node",
+		status: "pass"
+	};
+	return {
+		message: `Node.js 24.11 or newer on major 24 is required; current version is ${version}`,
+		name: "node",
+		status: "fail"
+	};
+}
+async function checkFiles(directory) {
+	const missing = await missingRegularFiles(directory, REQUIRED_FILES);
+	return missing.length === 0 ? {
+		message: "required project files are present",
+		name: "files",
+		status: "pass"
+	} : {
+		message: `required project files are missing: ${missing.join(", ")}`,
+		name: "files",
+		status: "fail"
+	};
+}
+async function checkDependencies(directory) {
+	const packageFiles = REQUIRED_DEPENDENCIES.map((name) => join("node_modules", ...name.split("/"), "package.json"));
+	const missingIndexes = new Set((await missingRegularFiles(directory, packageFiles)).map((path) => packageFiles.indexOf(path)));
+	const missing = REQUIRED_DEPENDENCIES.filter((_, index) => missingIndexes.has(index));
+	return missing.length === 0 ? {
+		message: "Rivus, Pi, and Feishu dependencies are installed",
+		name: "dependencies",
+		status: "pass"
+	} : {
+		message: `run npm install; missing local dependencies: ${missing.join(", ")}`,
+		name: "dependencies",
+		status: "fail"
+	};
+}
+async function checkManifest(directory) {
+	try {
+		const manifest = await loadRivusDeploymentManifest(join(directory, "rivus.config.json"));
+		validateRivusDeploymentManifest(manifest);
+		const missingModules = [];
+		for (const plugin of manifest.plugins) try {
+			await resolveNodeRivusPluginModulePath({
+				deploymentRoot: directory,
+				module: plugin.module,
+				pluginId: plugin.id
+			});
+		} catch {
+			missingModules.push(plugin.module);
+		}
+		if (missingModules.length > 0) return { check: {
+			message: `manifest Plugin modules are missing: ${missingModules.join(", ")}`,
+			name: "manifest",
+			status: "fail"
+		} };
+		return {
+			check: {
+				message: "deployment manifest is valid",
+				name: "manifest",
+				status: "pass"
+			},
+			manifest
+		};
+	} catch (error) {
+		return { check: {
+			message: `deployment manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+			name: "manifest",
+			status: "fail"
+		} };
+	}
+}
+async function checkCredentials(manifest, envFilePath, env) {
+	let mergedEnv;
+	try {
+		mergedEnv = await loadMergedLocalEnvFile(envFilePath, env);
+	} catch (error) {
+		return {
+			message: `required env file is unavailable at ${envFilePath}: ${error instanceof Error ? error.message : String(error)}`,
+			name: "credentials",
+			status: "fail"
+		};
+	}
+	if (!manifest) return {
+		message: "enabled Endpoint credentials cannot be checked until the deployment manifest is valid",
+		name: "credentials",
+		status: "fail"
+	};
+	try {
+		for (const endpoint of manifest.endpoints.filter(({ enabled }) => enabled)) resolveFeishuEndpointCredentials(endpoint.credentialRef, mergedEnv);
+		return {
+			message: "enabled Endpoint credential references resolve",
+			name: "credentials",
+			status: "pass"
+		};
+	} catch (error) {
+		return {
+			message: `enabled Endpoint credentials are incomplete: ${error instanceof Error ? error.message : String(error)}`,
+			name: "credentials",
+			status: "fail"
+		};
+	}
+}
+async function missingRegularFiles(directory, paths) {
+	const missing = [];
+	for (const path of paths) try {
+		if (!(await stat(resolve(directory, path))).isFile()) missing.push(path);
+	} catch (error) {
+		if (!isMissingPath$1(error)) throw error;
+		missing.push(path);
+	}
+	return missing;
+}
+function isMissingPath$1(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/infrastructure/project/rivus-project-initializer.ts
+const TEMPLATE_FILES = Object.freeze({
+	"current-weather.mjs": "current-weather.mjs",
+	"https-response-reader.mjs": "https-response-reader.mjs",
+	"rivus-agents.plugin.mjs": "rivus-starter.plugin.mjs",
+	"rivus.bootstrap.ts": "pi-feishu-deployment.bootstrap.ts"
+});
+async function initializeRivusProject(options) {
+	const directory = resolve(options.directory);
+	const manifest = await readPackageManifest(options.packageManifestPath);
+	const files = /* @__PURE__ */ new Map([
+		[".env.example", environmentTemplate()],
+		[".gitignore", ".env.local\n.rivus/\nnode_modules/\n"],
+		["deploy/launchd/com.rivus.agent.plist", launchdService(directory, options.nodeExecutable)],
+		["deploy/systemd/rivus.service", systemdService(directory, options.nodeExecutable)],
+		["package.json", projectPackageJson(directory, manifest)],
+		["rivus.config.json", deploymentManifest()]
+	]);
+	for (const [target, source] of Object.entries(TEMPLATE_FILES)) files.set(target, await readFile(join(options.templateDirectory, source), "utf8"));
+	const paths = [...files.keys()].sort();
+	await assertSafeProjectAncestors(directory, paths);
+	const conflicts = await findConflicts(directory, paths);
+	if (conflicts.length > 0) throw new Error(`Rivus project initialization refused; refusing to overwrite: ${conflicts.join(", ")}`);
+	const createdDirectories = [];
+	const createdFiles = [];
+	const writeProjectFile = options.writeProjectFile ?? writeExclusiveProjectFile;
+	try {
+		for (const path of paths) {
+			const destination = join(directory, path);
+			await ensureDirectory(dirname(destination), directory, createdDirectories);
+			await assertSafeProjectAncestors(directory, [path]);
+			await writeProjectFile(destination, files.get(path));
+			createdFiles.push(destination);
+		}
+	} catch (error) {
+		const rollbackErrors = await rollbackCreatedPaths(createdFiles, createdDirectories);
+		if (rollbackErrors.length > 0) throw new AggregateError([error, ...rollbackErrors], "Rivus project initialization failed and rollback was incomplete");
+		throw error;
+	}
+	return {
+		directory,
+		files: Object.freeze(paths)
+	};
+}
+async function writeExclusiveProjectFile(path, contents) {
+	await writeFile(path, contents, {
+		encoding: "utf8",
+		flag: "wx"
+	});
+}
+async function assertSafeProjectAncestors(directory, paths) {
+	const rootState = await lstatOrUndefined(directory);
+	if (rootState?.isSymbolicLink()) throw new Error("Rivus project initialization refused; symbolic link ancestor: .");
+	if (rootState && !rootState.isDirectory()) throw new Error("Rivus project initialization refused; project path is not a directory");
+	if (!rootState) return;
+	for (const path of paths) {
+		let current = directory;
+		for (const segment of path.split("/").slice(0, -1)) {
+			current = join(current, segment);
+			const state = await lstatOrUndefined(current);
+			if (!state) break;
+			if (state.isSymbolicLink()) throw new Error(`Rivus project initialization refused; symbolic link ancestor: ${relative(directory, current)}`);
+			if (!state.isDirectory()) throw new Error(`Rivus project initialization refused; non-directory ancestor: ${relative(directory, current)}`);
+		}
+	}
+}
+async function ensureDirectory(path, projectRoot, createdDirectories) {
+	try {
+		await mkdir(path);
+		createdDirectories.push(path);
+	} catch (error) {
+		if (isMissingPath(error)) {
+			const parent = dirname(path);
+			if (parent === path) throw error;
+			await ensureDirectory(parent, projectRoot, createdDirectories);
+			await ensureDirectory(path, projectRoot, createdDirectories);
+			return;
+		}
+		if (!isAlreadyExists(error)) throw error;
+		const state = await lstat(path);
+		if (state.isSymbolicLink()) {
+			if (isWithin(projectRoot, path)) throw new Error(`Rivus project initialization refused; symbolic link ancestor: ${relative(projectRoot, path) || "."}`);
+			if ((await stat(path)).isDirectory()) return;
+		}
+		if (!state.isDirectory()) throw new Error(`Rivus project initialization refused; non-directory ancestor: ${path}`);
+	}
+}
+async function rollbackCreatedPaths(files, directories) {
+	const errors = [];
+	for (const path of files.reverse()) try {
+		await unlink(path);
+	} catch (error) {
+		if (!isMissingPath(error)) errors.push(asError(error));
+	}
+	for (const path of directories.reverse()) try {
+		await rmdir(path);
+	} catch (error) {
+		if (!isMissingPath(error) && !isDirectoryNotEmpty(error)) errors.push(asError(error));
+	}
+	return errors;
+}
+async function lstatOrUndefined(path) {
+	try {
+		return await lstat(path);
+	} catch (error) {
+		if (isMissingPath(error)) return void 0;
+		throw error;
+	}
+}
+function isWithin(root, candidate) {
+	const child = relative(root, candidate);
+	return child === "" || !child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child);
+}
+function isAlreadyExists(error) {
+	return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isDirectoryNotEmpty(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOTEMPTY";
+}
+function asError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+async function readPackageManifest(path) {
+	const manifest = JSON.parse(await readFile(path, "utf8"));
+	if (manifest.name !== "@rivus/agent" || typeof manifest.version !== "string") throw new Error("Rivus package manifest is missing its release identity");
+	return manifest;
+}
+async function findConflicts(directory, paths) {
+	const conflicts = [];
+	for (const path of paths) try {
+		await lstat(join(directory, path));
+		conflicts.push(path);
+	} catch (error) {
+		if (!isMissingPath(error)) throw error;
+	}
+	return conflicts;
+}
+function isMissingPath(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function projectPackageJson(directory, manifest) {
+	const pi = manifest.peerDependencies?.["@earendil-works/pi-coding-agent"];
+	const lark = manifest.peerDependencies?.["@larksuiteoapi/node-sdk"];
+	const effect = manifest.dependencies?.effect;
+	if (!pi || !lark || !effect) throw new Error("Rivus package manifest is missing its Effect, Pi, or Feishu dependency range");
+	const projectName = sanitizePackageName(basename(directory));
+	return `${JSON.stringify({
+		name: projectName,
+		private: true,
+		type: "module",
+		scripts: {
+			"check-config": "rivus --manifest ./rivus.config.json --check-config",
+			doctor: "rivus doctor .",
+			start: "rivus --env-file .env.local --bootstrap ./rivus.bootstrap.ts --manifest ./rivus.config.json"
+		},
+		dependencies: {
+			"@earendil-works/pi-coding-agent": pi,
+			"@larksuiteoapi/node-sdk": lark,
+			"@rivus/agent": `^${manifest.version}`,
+			effect
+		}
+	}, null, 2)}\n`;
+}
+function sanitizePackageName(value) {
+	return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "") || "rivus-app";
+}
+function deploymentManifest() {
+	return `${JSON.stringify({
+		plugins: [{
+			id: "rivus-starter",
+			module: "./rivus-agents.plugin.mjs",
+			required: true
+		}],
+		agents: [{
+			agentId: "agent-a",
+			endpointIds: ["feishu-agent-a"],
+			pluginId: "rivus-starter",
+			profileId: "agent-a",
+			skills: { allow: [] },
+			tools: { allow: ["rivus-starter/current-weather"] }
+		}],
+		defaultAgentId: "agent-a",
+		defaultEndpointId: "feishu-agent-a",
+		endpoints: [{
+			agentId: "agent-a",
+			baseUrl: "https://open.feishu.cn",
+			credentialRef: "env:RIVUS_FEISHU",
+			enabled: true,
+			experimental: { cotMessages: false },
+			groupPolicy: "mention-only",
+			id: "feishu-agent-a",
+			required: true,
+			sessionNamespace: "rivus-starter",
+			streamMinIntervalMs: 200
+		}]
+	}, null, 2)}\n`;
+}
+function environmentTemplate() {
+	return [
+		"# Copy this file to .env.local and keep the real values untracked.",
+		"RIVUS_FEISHU_APP_ID=",
+		"RIVUS_FEISHU_APP_SECRET=",
+		"PI_MODEL=",
+		"PI_API_KEY=",
+		"# PI_BASE_URL=",
+		"RIVUS_WEATHER_DEFAULT_LOCATION=上海",
+		"# LANGFUSE_BASE_URL=https://jp.cloud.langfuse.com",
+		"# LANGFUSE_PUBLIC_KEY=",
+		"# LANGFUSE_SECRET_KEY=",
+		"# RIVUS_TELEMETRY_CONTENT=redacted",
+		""
+	].join("\n");
+}
+function systemdService(directory, nodeExecutable) {
+	const cli = join(directory, "node_modules", "@rivus", "agent", "dist", "cli.js");
+	return `[Unit]\nDescription=Rivus Agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=${systemdPath(directory)}\nExecStart=${systemdQuote(nodeExecutable)} ${systemdQuote(cli)} --env-file .env.local --bootstrap ./rivus.bootstrap.ts --manifest ./rivus.config.json\nRestart=on-failure\nRestartSec=5\nEnvironment=NODE_ENV=production\n\n[Install]\nWantedBy=default.target\n`;
+}
+function systemdPath(value) {
+	return value.replaceAll("%", "%%");
+}
+function systemdQuote(value) {
+	return `"${value.replace(/%/g, "%%").replace(/\$/g, () => "$$").replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function launchdService(directory, nodeExecutable) {
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n  <key>Label</key>\n  <string>com.rivus.agent</string>\n  <key>ProgramArguments</key>\n  <array>\n${[
+		nodeExecutable,
+		join(directory, "node_modules", "@rivus", "agent", "dist", "cli.js"),
+		"--env-file",
+		".env.local",
+		"--bootstrap",
+		"./rivus.bootstrap.ts",
+		"--manifest",
+		"./rivus.config.json"
+	].map((value) => `    <string>${xmlEscape(value)}</string>`).join("\n")}\n  </array>\n  <key>WorkingDirectory</key>\n  <string>${xmlEscape(directory)}</string>\n  <key>RunAtLoad</key>\n  <true/>\n  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\n  <key>ThrottleInterval</key>\n  <integer>5</integer>\n</dict>\n</plist>\n`;
+}
+function xmlEscape(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+//#endregion
+//#region src/composition/rivus-cli.ts
+const USAGE = `Usage:
+  rivus init [directory]
+  rivus doctor [directory] [--env-file <path>]
+  rivus --bootstrap <module> [--manifest <rivus.config.json>] [options]
+
+Commands:
+  init      Create a standalone local Rivus project without overwriting files
+  doctor    Check Node, files, dependencies, manifest, and enabled Endpoint credentials
+
+Run rivus --help for the complete daemon option list.
+`;
+function runRivusCli(options) {
+	const command = options.argv[0];
+	if (command === "init") return runInitCommand(options);
+	if (command === "doctor") return runDoctorCommand(options);
+	if (command && !command.startsWith("-")) return Effect.sync(() => {
+		options.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
+		return 1;
+	});
+	return runRivusDaemonCli(options);
+}
+function runInitCommand(options) {
+	return Effect.promise(async () => {
+		const args = options.argv.slice(1);
+		if (args.includes("--help") || args.includes("-h")) {
+			options.stdout.write("Usage: rivus init [directory]\n");
+			return 0;
+		}
+		if (args.length > 1 || args[0]?.startsWith("-")) {
+			options.stderr.write("Usage: rivus init [directory]\n");
+			return 1;
+		}
+		const directory = resolve(options.cwd, args[0] ?? ".");
+		try {
+			const result = await initializeRivusProject({
+				directory,
+				nodeExecutable: options.nodeExecutable,
+				packageManifestPath: options.packageManifestPath,
+				templateDirectory: options.templateDirectory
+			});
+			options.stdout.write(`Initialized Rivus project in ${result.directory}\n\nNext:\n  cd ${shellQuote(result.directory)}\n  npm install\n  cp .env.example .env.local\n  npm run doctor\n  npm start\n`);
+			return 0;
+		} catch (error) {
+			options.stderr.write(`${formatError(error)}\n`);
+			return 1;
+		}
+	});
+}
+function runDoctorCommand(options) {
+	return Effect.promise(async () => {
+		const parsed = parseDoctorArguments(options.argv.slice(1));
+		if (parsed.help) {
+			options.stdout.write("Usage: rivus doctor [directory] [--env-file <path>]\n");
+			return 0;
+		}
+		if (parsed.error) {
+			options.stderr.write(`${parsed.error}\nUsage: rivus doctor [directory] [--env-file <path>]\n`);
+			return 1;
+		}
+		try {
+			const report = await diagnoseRivusProject({
+				directory: resolve(options.cwd, parsed.directory ?? "."),
+				env: options.env,
+				...parsed.envFilePath ? { envFilePath: parsed.envFilePath } : {},
+				nodeVersion: options.nodeVersion
+			});
+			options.stdout.write(`Rivus doctor: ${report.directory}\n`);
+			for (const check of report.checks) options.stdout.write(`${check.status === "pass" ? "PASS" : "FAIL"} ${check.name}: ${check.message}\n`);
+			options.stdout.write(report.ready ? "Rivus project is ready\n" : "Rivus project is not ready\n");
+			return report.ready ? 0 : 1;
+		} catch (error) {
+			options.stderr.write(`${formatError(error)}\n`);
+			return 1;
+		}
+	});
+}
+function parseDoctorArguments(argv) {
+	let directory;
+	let envFilePath;
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--help" || argument === "-h") return { help: true };
+		if (argument === "--env-file") {
+			const value = argv[index + 1];
+			if (!value) return { error: "--env-file requires a path" };
+			envFilePath = value;
+			index += 1;
+			continue;
+		}
+		if (argument.startsWith("--env-file=")) {
+			envFilePath = argument.slice(11);
+			if (!envFilePath) return { error: "--env-file requires a path" };
+			continue;
+		}
+		if (argument.startsWith("-")) return { error: `Unknown doctor option: ${argument}` };
+		if (directory !== void 0) return { error: "doctor accepts at most one directory" };
+		directory = argument;
+	}
+	return {
+		...directory !== void 0 ? { directory } : {},
+		...envFilePath !== void 0 ? { envFilePath } : {}
+	};
+}
+function formatError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function shellQuote(value) {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+//#endregion
 //#region src/cli.ts
-const exitCode = await Effect.runPromise(runRivusDaemonCli({
+const packageDirectory = fileURLToPath(new URL("..", import.meta.url));
+const exitCode = await Effect.runPromise(runRivusCli({
 	argv: process.argv.slice(2),
+	cwd: process.cwd(),
 	env: process.env,
 	exitAfterSignal: (code) => process.exit(code),
 	loadBootstrap: (specifier) => import(toImportSpecifier(specifier)),
+	nodeExecutable: process.execPath,
+	nodeVersion: process.versions.node,
+	packageManifestPath: join(packageDirectory, "package.json"),
 	signalSource: process,
 	stderr: process.stderr,
-	stdout: process.stdout
+	stdout: process.stdout,
+	templateDirectory: join(packageDirectory, "examples")
 }));
 process.exitCode = exitCode;
 function toImportSpecifier(specifier) {