@rivus/agent 0.13.2 → 0.14.0

package/dist/cli.js

@@ -1,10 +1,130 @@
 #!/usr/bin/env node
-import { $ as resolveFeishuEndpointCredentials, D as loadRivusDeploymentManifest, T as resolveNodeRivusPluginModulePath, et as loadMergedLocalEnvFile, rt as validateRivusDeploymentManifest, t as runRivusDaemonCli } from "./rivus-daemon-cli.js";
-import { Effect } from "effect";
-import { lstat, mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { T as loadRivusDeploymentManifest, V as resolveFeishuEndpointCredentials, W as loadMergedLocalEnvFile, d as validateTrustedModulePath, f as isPathWithin, j as validateRivusDeploymentManifest, p as findTrustedPackageRoot, t as runRivusDaemonCli, u as resolveNodeRivusPluginModulePath } from "./chunks/rivus-daemon-cli.js";
+import { Effect, Either } from "effect";
+import { lstat, mkdir, readFile, realpath, rmdir, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
-//#region src/infrastructure/project/rivus-project-doctor.ts
+//#region src/adapters/deployment/inspection/rivus-home-deployment-inspector.ts
+const DEFAULT_BOOTSTRAP_PEERS = Object.freeze(["@earendil-works/pi-coding-agent", "@larksuiteoapi/node-sdk"]);
+function createRivusHomeDeploymentInspector(options = {}) {
+	const resolveModule = options.resolveModule ?? ((specifier) => defaultResolveModule(specifier, options.packageManifestPath));
+	const resolvePluginModule = options.resolvePluginModule ?? ((request) => resolveNodeRivusPluginModulePath(request, options.packageManifestPath ? { packageManifestPath: options.packageManifestPath } : {}));
+	return { inspect: (input) => Effect.gen(function* () {
+		const manifestResult = yield* checkManifest$1(input.home);
+		const credentials = yield* checkCredentials$1(input.home, manifestResult.manifest, input.env, input.envFilePath);
+		const modules = yield* checkModules(input.home, manifestResult.manifest, resolveModule, resolvePluginModule);
+		return {
+			credentials,
+			manifest: manifestResult.check,
+			modules
+		};
+	}) };
+}
+function checkManifest$1(home) {
+	return loadRivusDeploymentManifest(home.manifestPath).pipe(Effect.map((manifest) => {
+		validateRivusDeploymentManifest(manifest);
+		return {
+			check: {
+				message: "deployment manifest is valid",
+				name: "manifest",
+				status: "pass"
+			},
+			manifest
+		};
+	}), Effect.catchAll((error) => Effect.succeed({ check: {
+		message: `deployment manifest is invalid: ${formatError$1(error)}`,
+		name: "manifest",
+		status: "fail"
+	} })));
+}
+function checkModules(home, manifest, resolveModule, resolvePluginModule) {
+	if (!manifest) return Effect.succeed({
+		message: "modules cannot be checked until manifest is valid",
+		name: "modules",
+		status: "fail"
+	});
+	const specifiers = [home.bootstrap, ...home.bootstrap === "@rivus/agent/bootstrap/pi-feishu" ? DEFAULT_BOOTSTRAP_PEERS : []];
+	return Effect.gen(function* () {
+		const missing = [];
+		for (const specifier of specifiers) {
+			const result = yield* toEffect(() => resolveModule(specifier)).pipe(Effect.either);
+			if (result._tag === "Left") missing.push(`${specifier} (${formatError$1(result.left)})`);
+		}
+		for (const plugin of manifest.plugins) {
+			const result = yield* toEffect(() => resolvePluginModule({
+				deploymentRoot: home.directory,
+				module: plugin.module,
+				pluginId: plugin.id
+			})).pipe(Effect.either);
+			if (result._tag === "Left") missing.push(`${plugin.module} (${formatError$1(result.left)})`);
+		}
+		return missing.length === 0 ? {
+			message: "Bootstrap, Plugin, Pi, and Feishu modules resolve from the global installation",
+			name: "modules",
+			status: "pass"
+		} : {
+			message: `global npm modules are unavailable: ${missing.join(", ")}`,
+			name: "modules",
+			status: "fail"
+		};
+	});
+}
+function toEffect(read) {
+	return Effect.suspend(() => {
+		try {
+			const value = read();
+			if (Effect.isEffect(value)) return value;
+			return Effect.tryPromise({
+				try: () => Promise.resolve(value),
+				catch: toError$1
+			});
+		} catch (error) {
+			return Effect.fail(toError$1(error));
+		}
+	});
+}
+function checkCredentials$1(home, manifest, env, envFilePath) {
+	if (!manifest) return Effect.succeed({
+		message: "credentials cannot be checked until manifest is valid",
+		name: "credentials",
+		status: "fail"
+	});
+	return Effect.tryPromise({
+		try: async () => {
+			const merged = await loadMergedLocalEnvFile(envFilePath ? resolve(home.directory, envFilePath) : home.envFilePath, env);
+			for (const endpoint of manifest.endpoints.filter(({ enabled }) => enabled)) resolveFeishuEndpointCredentials(endpoint.credentialRef, merged);
+			return {
+				message: "enabled Endpoint credential references resolve",
+				name: "credentials",
+				status: "pass"
+			};
+		},
+		catch: toError$1
+	}).pipe(Effect.catchAll((error) => Effect.succeed({
+		message: `enabled Endpoint credentials are incomplete: ${formatError$1(error)}`,
+		name: "credentials",
+		status: "fail"
+	})));
+}
+function defaultResolveModule(specifier, packageManifestPath) {
+	if (!packageManifestPath) return Effect.fail(/* @__PURE__ */ new Error("Rivus package manifest path is required for trusted module resolution"));
+	return Effect.gen(function* () {
+		const resolvedRealpath = yield* Effect.tryPromise({
+			try: () => realpath(fileURLToPath(import.meta.resolve(specifier))),
+			catch: toError$1
+		});
+		return yield* validateTrustedModulePath(yield* findTrustedPackageRoot(packageManifestPath), resolvedRealpath, `module ${specifier}`);
+	});
+}
+function toError$1(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+function formatError$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/adapters/deployment/inspection/rivus-project-doctor.ts
 const REQUIRED_FILES = Object.freeze([
 	"package.json",
 	"rivus.bootstrap.ts",
@@ -15,23 +135,33 @@ const REQUIRED_DEPENDENCIES = Object.freeze([
 	"@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 diagnoseRivusProject(options) {
+	return Effect.gen(function* () {
+		const directory = resolve(options.directory);
+		const checks = [checkNode$1(options.nodeVersion)];
+		checks.push(yield* Effect.tryPromise({
+			try: () => checkFiles(directory),
+			catch: toError
+		}));
+		checks.push(yield* Effect.tryPromise({
+			try: () => checkDependencies(directory),
+			catch: toError
+		}));
+		const manifestResult = yield* checkManifest(directory);
+		checks.push(manifestResult.check);
+		const envFilePath = resolve(directory, options.envFilePath ?? ".env.local");
+		checks.push(yield* Effect.tryPromise({
+			try: () => checkCredentials(manifestResult.manifest, envFilePath, options.env),
+			catch: toError
+		}));
+		return Object.freeze({
+			checks: Object.freeze(checks),
+			directory,
+			ready: checks.every(({ status }) => status === "pass")
+		});
 	});
 }
-function checkNode(version) {
+function checkNode$1(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`,
@@ -70,19 +200,17 @@ async function checkDependencies(directory) {
 		status: "fail"
 	};
 }
-async function checkManifest(directory) {
-	try {
-		const manifest = await loadRivusDeploymentManifest(join(directory, "rivus.config.json"));
+function checkManifest(directory) {
+	return loadRivusDeploymentManifest(join(directory, "rivus.config.json")).pipe(Effect.flatMap((manifest) => Effect.gen(function* () {
 		validateRivusDeploymentManifest(manifest);
 		const missingModules = [];
-		for (const plugin of manifest.plugins) try {
-			await resolveNodeRivusPluginModulePath({
+		for (const plugin of manifest.plugins) {
+			const result = yield* resolveNodeRivusPluginModulePath({
 				deploymentRoot: directory,
 				module: plugin.module,
 				pluginId: plugin.id
-			});
-		} catch {
-			missingModules.push(plugin.module);
+			}).pipe(Effect.either);
+			if (Either.isLeft(result)) missingModules.push(plugin.module);
 		}
 		if (missingModules.length > 0) return { check: {
 			message: `manifest Plugin modules are missing: ${missingModules.join(", ")}`,
@@ -97,13 +225,11 @@ async function checkManifest(directory) {
 			},
 			manifest
 		};
-	} catch (error) {
-		return { check: {
-			message: `deployment manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
-			name: "manifest",
-			status: "fail"
-		} };
-	}
+	})), Effect.catchAll((error) => Effect.succeed({ check: {
+		message: `deployment manifest is invalid: ${error.message}`,
+		name: "manifest",
+		status: "fail"
+	} })));
 }
 async function checkCredentials(manifest, envFilePath, env) {
 	let mergedEnv;
@@ -149,8 +275,11 @@ async function missingRegularFiles(directory, paths) {
 function isMissingPath$1(error) {
 	return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
 //#endregion
-//#region src/infrastructure/project/rivus-project-initializer.ts
+//#region src/platform/project/setup/rivus-project-initializer.ts
 const TEMPLATE_FILES = Object.freeze({
 	"current-weather.mjs": "current-weather.mjs",
 	"https-response-reader.mjs": "https-response-reader.mjs",
@@ -161,12 +290,12 @@ async function initializeRivusProject(options) {
 	const directory = resolve(options.directory);
 	const manifest = await readPackageManifest(options.packageManifestPath);
 	const files = /* @__PURE__ */ new Map([
-		[".env.example", environmentTemplate()],
+		[".env.example", environmentTemplate$1()],
 		[".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()]
+		["rivus.config.json", deploymentManifest$1()]
 	]);
 	for (const [target, source] of Object.entries(TEMPLATE_FILES)) files.set(target, await readFile(join(options.templateDirectory, source), "utf8"));
 	const paths = [...files.keys()].sort();
@@ -231,7 +360,7 @@ async function ensureDirectory(path, projectRoot, createdDirectories) {
 		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 (isPathWithin(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}`);
@@ -242,12 +371,12 @@ async function rollbackCreatedPaths(files, directories) {
 	for (const path of files.reverse()) try {
 		await unlink(path);
 	} catch (error) {
-		if (!isMissingPath(error)) errors.push(asError(error));
+		if (!isMissingPath(error)) errors.push(asError$1(error));
 	}
 	for (const path of directories.reverse()) try {
 		await rmdir(path);
 	} catch (error) {
-		if (!isMissingPath(error) && !isDirectoryNotEmpty(error)) errors.push(asError(error));
+		if (!isMissingPath(error) && !isDirectoryNotEmpty(error)) errors.push(asError$1(error));
 	}
 	return errors;
 }
@@ -259,17 +388,13 @@ async function lstatOrUndefined(path) {
 		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) {
+function asError$1(error) {
 	return error instanceof Error ? error : new Error(String(error));
 }
 async function readPackageManifest(path) {
@@ -316,7 +441,7 @@ function projectPackageJson(directory, manifest) {
 function sanitizePackageName(value) {
 	return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "") || "rivus-app";
 }
-function deploymentManifest() {
+function deploymentManifest$1() {
 	return `${JSON.stringify({
 		plugins: [{
 			id: "rivus-starter",
@@ -349,7 +474,7 @@ function deploymentManifest() {
 		}]
 	}, null, 2)}\n`;
 }
-function environmentTemplate() {
+function environmentTemplate$1() {
 	return [
 		"# Copy this file to .env.local and keep the real values untracked.",
 		"RIVUS_FEISHU_APP_ID=",
@@ -393,18 +518,31 @@ function xmlEscape(value) {
 //#endregion
 //#region src/composition/rivus-cli.ts
 const USAGE = `Usage:
+  rivus setup [directory]
+  rivus start
+  rivus status
+  rivus check-config
   rivus init [directory]
   rivus doctor [directory] [--env-file <path>]
   rivus --bootstrap <module> [--manifest <rivus.config.json>] [options]
 
 Commands:
+  setup     Create Rivus Home (default ~/.rivus-agent) without overwriting files
+  start     Start the Rivus Home deployment in the foreground
+  status    Print Rivus Home deployment status without activating Endpoints
+  check-config
+            Validate and print the redacted Rivus Home manifest
   init      Create a standalone local Rivus project without overwriting files
-  doctor    Check Node, files, dependencies, manifest, and enabled Endpoint credentials
+  doctor    Check Rivus Home by default, or an explicit standalone project directory
 
 Run rivus --help for the complete daemon option list.
 `;
 function runRivusCli(options) {
 	const command = options.argv[0];
+	if (command === "setup") return runSetupCommand(options);
+	if (command === "start") return runHomeDaemonCommand(options, []);
+	if (command === "status") return runHomeDaemonCommand(options, ["--status"]);
+	if (command === "check-config") return runHomeDaemonCommand(options, ["--check-config"]);
 	if (command === "init") return runInitCommand(options);
 	if (command === "doctor") return runDoctorCommand(options);
 	if (command && !command.startsWith("-")) return Effect.sync(() => {
@@ -413,60 +551,107 @@ function runRivusCli(options) {
 	});
 	return runRivusDaemonCli(options);
 }
+function runSetupCommand(options) {
+	return withOptionalDirectoryArgument(options, "setup", (argument) => resolveHomeDirectoryEffect(options, argument).pipe(Effect.flatMap((directory) => options.homeApi.setup(directory).pipe(Effect.tap(() => Effect.sync(() => options.stdout.write(`Initialized Rivus Home in ${directory}\n\nNext:\n  cp ${shellQuote(`${directory}/.env.example`)} ${shellQuote(`${directory}/.env`)}\n  rivus doctor\n  rivus start\n`))), Effect.as(0))), Effect.catchAll((error) => writeError(options, error))));
+}
+function runHomeDaemonCommand(options, daemonArgs) {
+	if (options.argv.length > 1) return Effect.sync(() => {
+		options.stderr.write(`Usage: rivus ${options.argv[0]}\n`);
+		return 1;
+	});
+	return resolveHomeDirectoryEffect(options).pipe(Effect.flatMap((directory) => options.homeApi.load(directory)), Effect.tap((home) => Effect.sync(() => options.changeWorkingDirectory(home.workspaceDirectory))), Effect.flatMap((home) => runRivusDaemonCli({
+		...options,
+		argv: [
+			"--env-file",
+			home.envFilePath,
+			"--bootstrap",
+			home.bootstrap,
+			"--manifest",
+			home.manifestPath,
+			...daemonArgs
+		],
+		env: {
+			...options.env,
+			RIVUS_DEPLOYMENT_STATE_DIR: home.stateDirectory,
+			RIVUS_HOME: home.directory
+		},
+		pluginPackageManifestPath: options.packageManifestPath
+	})), Effect.catchAll((error) => writeError(options, error)));
+}
 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({
+	return withOptionalDirectoryArgument(options, "init", (argument) => {
+		const directory = resolve(options.cwd, argument ?? ".");
+		return Effect.tryPromise({
+			try: () => 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;
-		}
+			}),
+			catch: (error) => error
+		}).pipe(Effect.tap((result) => Effect.sync(() => 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`))), Effect.as(0), Effect.catchAll((error) => writeError(options, error)));
 	});
 }
+function withOptionalDirectoryArgument(options, command, run) {
+	const args = options.argv.slice(1);
+	const usage = `Usage: rivus ${command} [directory]\n`;
+	if (args.includes("--help") || args.includes("-h")) return Effect.sync(() => {
+		options.stdout.write(usage);
+		return 0;
+	});
+	if (args.length > 1 || args[0]?.startsWith("-")) return Effect.sync(() => {
+		options.stderr.write(usage);
+		return 1;
+	});
+	return run(args[0]);
+}
 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;
-		}
+	const parsed = parseDoctorArguments(options.argv.slice(1));
+	if (parsed.help) return Effect.sync(() => {
+		options.stdout.write("Usage: rivus doctor [directory] [--env-file <path>]\n");
+		return 0;
+	});
+	if (parsed.error) return Effect.sync(() => {
+		options.stderr.write(`${parsed.error}\nUsage: rivus doctor [directory] [--env-file <path>]\n`);
+		return 1;
 	});
+	if (parsed.directory === void 0) return resolveHomeDirectoryEffect(options).pipe(Effect.flatMap((directory) => options.homeApi.diagnose({
+		directory,
+		env: options.env,
+		...parsed.envFilePath ? { envFilePath: parsed.envFilePath } : {},
+		nodeVersion: options.nodeVersion
+	})), Effect.map((report) => writeDoctorReport(options.stdout, report, "Home")), Effect.catchAll((error) => writeError(options, error)));
+	const projectDirectory = parsed.directory;
+	return diagnoseRivusProject({
+		directory: resolve(options.cwd, projectDirectory),
+		env: options.env,
+		...parsed.envFilePath ? { envFilePath: parsed.envFilePath } : {},
+		nodeVersion: options.nodeVersion
+	}).pipe(Effect.map((report) => writeDoctorReport(options.stdout, report, "project")), Effect.catchAll((error) => writeError(options, error)));
+}
+function resolveHomeDirectoryEffect(options, argument) {
+	return Effect.try({
+		try: () => {
+			if (argument) return resolve(options.cwd, argument);
+			const configured = options.env.RIVUS_HOME?.trim();
+			if (!configured) return resolve(options.homeDirectory, ".rivus-agent");
+			if (!isAbsolute(configured)) throw new Error("RIVUS_HOME must be an absolute path");
+			return resolve(configured);
+		},
+		catch: (error) => error instanceof Error ? error : new Error(String(error))
+	});
+}
+function writeError(options, error) {
+	return Effect.sync(() => {
+		options.stderr.write(`${formatError(error)}\n`);
+		return 1;
+	});
+}
+function writeDoctorReport(stdout, report, owner) {
+	stdout.write(`Rivus doctor: ${report.directory}\n`);
+	for (const check of report.checks) stdout.write(`${check.status === "pass" ? "PASS" : "FAIL"} ${check.name}: ${check.message}\n`);
+	stdout.write(report.ready ? `Rivus ${owner} is ready\n` : `Rivus ${owner} is not ready\n`);
+	return report.ready ? 0 : 1;
 }
 function parseDoctorArguments(argv) {
 	let directory;
@@ -502,14 +687,338 @@ function shellQuote(value) {
 	return `'${value.replaceAll("'", "'\\''")}'`;
 }
 //#endregion
+//#region src/platform/home/config/rivus-home-config.ts
+/** Loads and validates the operator-owned Home config file. */
+function loadRivusHome(directoryPath) {
+	const directory = resolve(directoryPath);
+	const configPath = resolve(directory, "config.json");
+	return Effect.tryPromise({
+		try: async () => {
+			const config = parseRivusHomeConfig(JSON.parse(await readFile(configPath, "utf8")));
+			return {
+				bootstrap: resolveBootstrap(directory, config.bootstrap),
+				config,
+				configPath,
+				directory,
+				envFilePath: resolveHomePath(directory, config.envFile, "envFile"),
+				logsDirectory: resolveHomePath(directory, config.logs, "logs"),
+				manifestPath: resolveHomePath(directory, config.manifest, "manifest"),
+				stateDirectory: resolveHomePath(directory, config.state, "state"),
+				workspaceDirectory: resolveHomePath(directory, config.workspace, "workspace")
+			};
+		},
+		catch: asError
+	});
+}
+function parseRivusHomeConfig(value) {
+	const config = record(value, "Rivus Home config");
+	if (config.version !== 1) throw new Error("Rivus Home config version must be 1");
+	return {
+		bootstrap: nonEmptyString(config.bootstrap, "bootstrap"),
+		envFile: relativePath(config.envFile, "envFile"),
+		logs: relativePath(config.logs, "logs"),
+		manifest: relativePath(config.manifest, "manifest"),
+		state: relativePath(config.state, "state"),
+		version: 1,
+		workspace: relativePath(config.workspace, "workspace")
+	};
+}
+function resolveBootstrap(directory, value) {
+	if (value.startsWith("./") || value.startsWith("../")) return resolveHomePath(directory, value, "bootstrap");
+	if (isAbsolute(value)) throw new Error("Rivus Home bootstrap must be a package specifier or a relative path inside Rivus Home");
+	return value;
+}
+function resolveHomePath(directory, value, owner) {
+	const candidate = resolve(directory, value);
+	const relation = relative(directory, candidate);
+	if (relation === "" || !relation.startsWith(`..${sep}`) && relation !== ".." && !isAbsolute(relation)) return candidate;
+	throw new Error(`Rivus Home ${owner} escapes the Home directory`);
+}
+function relativePath(value, owner) {
+	const path = nonEmptyString(value, owner);
+	if (isAbsolute(path)) throw new Error(`Rivus Home ${owner} must be a relative path`);
+	return path;
+}
+function nonEmptyString(value, owner) {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`Rivus Home ${owner} must be a non-empty string`);
+	return value;
+}
+function record(value, owner) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${owner} must be an object`);
+	return value;
+}
+function asError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+//#endregion
+//#region src/platform/home/doctor/rivus-home-doctor.ts
+function diagnoseRivusHome(input, options) {
+	return Effect.gen(function* () {
+		const checks = [checkNode(input.nodeVersion)];
+		const loaded = yield* options.load(input.directory).pipe(Effect.either);
+		if (Either.isLeft(loaded)) {
+			checks.push({
+				message: `Rivus Home is invalid: ${loaded.left.message}`,
+				name: "home",
+				status: "fail"
+			}, blockedCheck("workspace", "Workspace"), blockedCheck("manifest", "manifest"), blockedCheck("modules", "modules"), blockedCheck("credentials", "credentials"));
+			return report(input.directory, checks);
+		}
+		const home = loaded.right;
+		checks.push({
+			message: "config.json is valid and contained in Rivus Home",
+			name: "home",
+			status: "pass"
+		});
+		checks.push(yield* checkWorkspace(home, options.findMissingWorkspacePaths));
+		const deployment = yield* options.deploymentInspector.inspect({
+			env: input.env,
+			...input.envFilePath ? { envFilePath: input.envFilePath } : {},
+			home
+		});
+		checks.push(deployment.manifest, deployment.modules, deployment.credentials);
+		return report(input.directory, checks);
+	});
+}
+function checkNode(version) {
+	const [major, minor] = version.split(".").map(Number);
+	return major === 24 && Number.isInteger(minor) && minor >= 11 ? {
+		message: `Node.js ${version} satisfies the supported ^24.11 runtime`,
+		name: "node",
+		status: "pass"
+	} : {
+		message: `Node.js 24.11 or newer on major 24 is required; current version is ${version}`,
+		name: "node",
+		status: "fail"
+	};
+}
+function checkWorkspace(home, findMissingWorkspacePaths) {
+	return findMissingWorkspacePaths(home).pipe(Effect.map((missing) => missing.length === 0 ? {
+		message: "Workspace instructions, Memory, Skills, and work directories are present",
+		name: "workspace",
+		status: "pass"
+	} : {
+		message: `Workspace paths are missing: ${missing.join(", ")}`,
+		name: "workspace",
+		status: "fail"
+	}));
+}
+function blockedCheck(name, owner) {
+	return {
+		message: `${owner} cannot be checked until config.json is valid`,
+		name,
+		status: "fail"
+	};
+}
+function report(directory, checks) {
+	return {
+		checks,
+		directory,
+		ready: checks.every(({ status }) => status === "pass")
+	};
+}
+//#endregion
+//#region src/platform/home/setup/rivus-home-layout.ts
+const HOME_DIRECTORIES = Object.freeze([
+	"logs",
+	"plugins",
+	"state",
+	"workspace/memory",
+	"workspace/skills",
+	"workspace/work/artifacts",
+	"workspace/work/drafts",
+	"workspace/work/inbox",
+	"workspace/work/tmp"
+]);
+function createRivusHomeLayout() {
+	return {
+		directories: HOME_DIRECTORIES,
+		files: /* @__PURE__ */ new Map([
+			[".env.example", environmentTemplate()],
+			[".gitignore", ".DS_Store\n.env\nlogs/\nstate/\nworkspace/work/tmp/\n"],
+			["config.json", homeConfig()],
+			["rivus.config.json", deploymentManifest()],
+			["workspace/AGENTS.md", agentsTemplate()],
+			["workspace/IDENTITY.md", "# Identity\n\nName: Rivus\n\nRole: Personal agent\n"],
+			["workspace/MEMORY.md", "# Curated Memory\n\nStore confirmed, durable facts and decisions here.\n"],
+			["workspace/SOUL.md", "# Character\n\nBe direct, thoughtful, and evidence-led.\n"],
+			["workspace/USER.md", "# User\n\nRecord stable user preferences here.\n"],
+			["plugins/.gitkeep", ""],
+			["workspace/memory/.gitkeep", ""],
+			["workspace/skills/.gitkeep", ""],
+			["workspace/work/artifacts/.gitkeep", ""],
+			["workspace/work/drafts/.gitkeep", ""],
+			["workspace/work/inbox/.gitkeep", ""]
+		])
+	};
+}
+function homeConfig() {
+	return `${JSON.stringify({
+		bootstrap: "@rivus/agent/bootstrap/pi-feishu",
+		envFile: ".env",
+		logs: "logs",
+		manifest: "rivus.config.json",
+		state: "state",
+		version: 1,
+		workspace: "workspace"
+	}, null, 2)}\n`;
+}
+function deploymentManifest() {
+	return `${JSON.stringify({
+		agents: [{
+			agentId: "personal",
+			endpointIds: ["personal-feishu"],
+			memory: {
+				scopes: ["agent-private"],
+				tool: true
+			},
+			pluginId: "rivus-starter",
+			profileId: "agent-a",
+			projectSpaceId: "personal-home",
+			runtimeTools: { allow: [
+				"read",
+				"bash",
+				"edit",
+				"write",
+				"grep",
+				"find",
+				"ls"
+			] },
+			skills: { allow: [] },
+			tools: { allow: ["rivus-starter/current-weather"] }
+		}],
+		defaultAgentId: "personal",
+		defaultEndpointId: "personal-feishu",
+		endpoints: [{
+			agentId: "personal",
+			baseUrl: "https://open.feishu.cn",
+			cardStreamLeaseMs: 51e4,
+			credentialRef: "env:RIVUS_FEISHU",
+			enabled: true,
+			experimental: { cotMessages: false },
+			groupPolicy: "mention-only",
+			id: "personal-feishu",
+			progressDisplay: "collapsed",
+			required: true,
+			sessionNamespace: "rivus-home-v1",
+			streamMinIntervalMs: 200
+		}],
+		plugins: [{
+			id: "rivus-starter",
+			module: "@rivus/agent/plugin/starter",
+			required: true
+		}],
+		projectSpaces: [{
+			id: "personal-home",
+			root: "workspace",
+			skills: { sources: ["skills"] },
+			workingDirectory: "."
+		}]
+	}, null, 2)}\n`;
+}
+function environmentTemplate() {
+	return [
+		"# Copy this file to .env 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=上海",
+		""
+	].join("\n");
+}
+function agentsTemplate() {
+	return [
+		"# Personal Workspace",
+		"",
+		"Use this directory as the default home for personal work.",
+		"",
+		"- Read `SOUL.md` and `IDENTITY.md` when identity or tone matters.",
+		"- Read `USER.md` when stable user preferences affect the task.",
+		"- Search `MEMORY.md` and dated files under `memory/` when prior facts or decisions matter.",
+		"- Read the selected `skills/<name>/SKILL.md` before following a Workspace Skill.",
+		"- Put incoming material in `work/inbox/`, drafts in `work/drafts/`, and durable general outputs in `work/artifacts/`.",
+		"- Put disposable files in `work/tmp/`.",
+		"- Store only confirmed durable facts in Memory; keep credentials and raw private transcripts out of tracked files.",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/platform/home/setup/rivus-home-initializer.ts
+function initializeRivusHome(directoryPath) {
+	const directory = resolve(directoryPath);
+	const { directories, files } = createRivusHomeLayout();
+	const paths = [...files.keys()].sort();
+	return Effect.tryPromise({
+		try: async () => {
+			for (const path of [...directories].sort()) await mkdir(join(directory, path), { recursive: true });
+			for (const path of paths) {
+				const destination = join(directory, path);
+				await mkdir(dirname(destination), { recursive: true });
+				await writeFile(destination, files.get(path), {
+					encoding: "utf8",
+					flag: "wx"
+				});
+			}
+			return {
+				directory,
+				files: paths
+			};
+		},
+		catch: (error) => error instanceof Error ? error : new Error(String(error))
+	});
+}
+//#endregion
+//#region src/platform/home/workspace/rivus-home-workspace.ts
+function findMissingRivusHomeWorkspacePaths(home) {
+	const required = [
+		home.workspaceDirectory,
+		resolve(home.workspaceDirectory, "AGENTS.md"),
+		resolve(home.workspaceDirectory, "MEMORY.md"),
+		resolve(home.workspaceDirectory, "memory"),
+		resolve(home.workspaceDirectory, "skills"),
+		resolve(home.workspaceDirectory, "work")
+	];
+	return Effect.tryPromise({
+		try: async () => {
+			const missing = [];
+			for (const path of required) try {
+				await stat(path);
+			} catch (error) {
+				if (error instanceof Error && "code" in error && error.code === "ENOENT") missing.push(path);
+				else throw error;
+			}
+			return missing;
+		},
+		catch: (error) => error instanceof Error ? error : new Error(String(error))
+	});
+}
+//#endregion
+//#region src/platform/home/node/node-rivus-home.ts
+function createNodeRivusHome(options) {
+	return {
+		diagnose: (input) => diagnoseRivusHome(input, {
+			deploymentInspector: options.deploymentInspector,
+			findMissingWorkspacePaths: findMissingRivusHomeWorkspacePaths,
+			load: loadRivusHome
+		}),
+		load: loadRivusHome,
+		setup: initializeRivusHome
+	};
+}
+//#endregion
 //#region src/cli.ts
 const packageDirectory = fileURLToPath(new URL("..", import.meta.url));
 const exitCode = await Effect.runPromise(runRivusCli({
 	argv: process.argv.slice(2),
+	changeWorkingDirectory: (directory) => process.chdir(directory),
 	cwd: process.cwd(),
 	env: process.env,
 	exitAfterSignal: (code) => process.exit(code),
+	homeApi: createNodeRivusHome({ deploymentInspector: createRivusHomeDeploymentInspector({ packageManifestPath: join(packageDirectory, "package.json") }) }),
 	loadBootstrap: (specifier) => import(toImportSpecifier(specifier)),
+	homeDirectory: homedir(),
 	nodeExecutable: process.execPath,
 	nodeVersion: process.versions.node,
 	packageManifestPath: join(packageDirectory, "package.json"),