@rivus/agent 0.1.1 → 0.3.1

package/README.md

@@ -14,7 +14,7 @@ The first milestone is intentionally narrow: make the agent loop and agent harne
 - Host-issued invocation authority and a call-time Tool Broker that checks exact grants, pinned versions, online revocation, stable operation IDs, durable side-effect fencing, and one-time approval receipts bound to canonical input digests. The Pi Tool Proxy and Feishu Human Interaction gateway are wired in the deployment example.
 - Multi-agent Host primitives with trusted Endpoint bindings, stable Runtime Generation/Instance identities, lazy per-instance Runtime pooling, isolated active-run gates, and restart restoration from persisted registry records.
 - Scoped Agent Memory with a single-writer append-only JSONL adapter, explicit Profile/Deployment grants, Host-bound tenant/subject/conversation/audience identity, and a provider-neutral `rivus_memory` Tool wired into the Pi manifest Runtime. Agent-private proposals survive process replacement; group invocations fail closed to their current Conversation scope, and Shared Profile reads expose only confirmed records. Automatic Recall, durable confirmation UX, typed Shared Profile fields, full provenance/retention metadata, and durable Compaction are still separate work.
-- Manifest-driven daily Agent Automations with stable Mandate/Tick identity, per-template Tool grant narrowing, isolated Runtime and invocation authority, a durable single-writer JSON Tick adapter that records the actual Agent Run, generated-before-delivery recovery, and idempotent proactive Feishu Markdown delivery. Revisioned Plugin State and the general Delivery Outbox remain composable domain primitives.
+- Manifest-driven daily Agent Automations with stable Mandate/Tick identity, per-template Tool grant narrowing, isolated Runtime and invocation authority, a durable single-writer JSON Tick adapter that records the actual Agent Run, generated-before-delivery recovery, and idempotent proactive Feishu interactive-card delivery. The first Markdown heading becomes the card title while the remaining Markdown stays scannable in the card body. Revisioned Plugin State and the general Delivery Outbox remain composable domain primitives.
 - Peer Delegation and Subagent coordination primitives with explicit edges, hop/budget limits, monotonic ToolGrantSet intersection, isolated child authority, denied ambient sender/private-memory/Shell capabilities, and parent cancellation cascading.
 - `@rivus/agent/testing` Conformance TestKit with a reusable Fake Plugin and checks for registration/reference failures, ToolGrantSet expansion, and lifecycle disposal leaks.
 - Effect-based `AgentHarness` use case with result-oriented `prompt()`, turn-oriented `promptTurn()`, event-oriented `stream()`, text-oriented `streamText()`, event-handling `promptWithEvents()`, active-run/run/session state and transcript lookup APIs, and a default runtime factory.
@@ -34,7 +34,7 @@ The first milestone is intentionally narrow: make the agent loop and agent harne
 - A small Feishu agent runtime factory that assembles the harness, queue, worker, and event handlers.
 - A Feishu WebSocket daemon adapter that starts an official-SDK-shaped `WSClient` with the runtime handlers.
 - A background Feishu worker loop that drains accepted messages outside the WebSocket acknowledgement callback.
-- A small `rivus` CLI runner that loads typed config, imports a bootstrap module, starts the composed daemon, and installs `SIGINT`/`SIGTERM` shutdown.
+- A small `rivus` CLI with conflict-safe project initialization, side-effect-free local readiness diagnostics, bootstrap loading, daemon startup, and `SIGINT`/`SIGTERM` shutdown.
 - A configured daemon bootstrap helper that wires Feishu WebSocket, CardKit target preparation, CardKit publishing, event logging, history replay, worker draining, and managed process lifecycle.
 - A daemon status reporter that combines active harness run details, process/transport/worker/queue state, and restored run/session history.
 - A small CardKit OpenAPI client for streaming text updates and replacing the card with completed, failed, or cancelled terminal projections.
@@ -53,6 +53,21 @@ npm install @rivus/agent
 npx rivus --help
 ```
 
+Create a standalone one-Agent project without cloning this repository:
+
+```bash
+npm install --global @rivus/agent
+rivus init my-rivus-agent
+cd my-rivus-agent
+npm install
+cp .env.example .env.local
+# Fill the Feishu and model-provider values in .env.local.
+npm run doctor
+npm start
+```
+
+`init` refuses to overwrite any generated path. `doctor` checks Node, project files, local dependencies, the deployment manifest, and enabled Endpoint credentials without importing Plugin code or contacting external services. See the [local deployment runbook](docs/en/operations/local-deployment.md) for foreground verification and the generated systemd/launchd templates.
+
 The Pi plus Feishu example is application-edge code: install `@earendil-works/pi-coding-agent` and `@larksuiteoapi/node-sdk` in the daemon app that uses it. The `@rivus/agent` core package keeps those SDKs out of its runtime dependency graph.
 
 ```bash
@@ -884,7 +899,7 @@ const daemon = createFeishuAgentDaemon({
 });
 ```
 
-The daemon converts Feishu text messages into prompt commands, consumes harness `AgentRunUpdate` values, and emits `update_text`, `finish`, `fail`, or `cancel` actions from projected run state. It also accepts `/cancel <runId>` as a daemon command; the intake attaches the message's stable `sessionKey`, and the daemon calls `harness.forSession(sessionKey).cancelRun(runId, "Feishu cancel command")` so a cancel message from another chat cannot cancel the active run. `/cancel` without an exact run id is rejected at intake instead of being sent to the model. `card.action.trigger` can cancel through the same exact path or resolve a persisted Human Interaction using only the trusted Feishu operator identity. Card-action tokens are process-locally deduplicated. Interaction decisions are persisted before the callback returns a toast and updated raw card; resolved cards contain no stale buttons. `prepareRun` is called on `agent_run_accepted`, before any stream action is published, so adapters can create a card and bind `runId` to `{ cardId, elementId }`. Publish effects are awaited in update order, and terminal publication replaces the entire card with a completed, failed, or cancelled projection. When daemon-level `dedupe` is enabled, a failed run releases its message-id marker so a retried delivery can run again; runtime-level queues treat `AgentRunCancelled` as terminal and do not retry cancelled messages.
+The daemon converts Feishu text and rich-text Post messages into prompt commands, preferring Post `content_v2` and flattening its textual paragraphs. It consumes harness `AgentRunUpdate` values and emits `update_text`, `finish`, `fail`, or `cancel` actions from projected run state. It also accepts `/cancel <runId>` as a daemon command; the intake attaches the message's stable `sessionKey`, and the daemon calls `harness.forSession(sessionKey).cancelRun(runId, "Feishu cancel command")` so a cancel message from another chat cannot cancel the active run. `/cancel` without an exact run id is rejected at intake instead of being sent to the model. `card.action.trigger` can cancel through the same exact path or resolve a persisted Human Interaction using only the trusted Feishu operator identity. Card-action tokens are process-locally deduplicated. Interaction decisions are persisted before the callback returns a toast and updated raw card; resolved cards contain no stale buttons. `prepareRun` is called on `agent_run_accepted`, before any stream action is published, so adapters can create a card and bind `runId` to `{ cardId, elementId }`. Publish effects are awaited in update order, and terminal publication replaces the entire card with a completed, failed, or cancelled projection. When daemon-level `dedupe` is enabled, a failed run releases its message-id marker so a retried delivery can run again; runtime-level queues treat `AgentRunCancelled` as terminal and do not retry cancelled messages.
 
 For Feishu's 3-second event handling requirement, put a queue in front of the daemon:
 

package/dist/cli.js

@@ -1,17 +1,516 @@
 #!/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 { fileURLToPath, pathToFileURL } from "node:url";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Effect } from "effect";
+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",
+	"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=${systemdQuote(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 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) {