@gajae-gateway/cli 0.1.8 → 0.2.0

package/src/services.ts

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { homeLayout } from "@gajae-gateway/home";
 import { parseRuntimeConfig, type RuntimeConfig, RuntimeConfigError } from "@gajae-gateway/protocol";
 
 const CONFIG_SCHEMA_VERSION = 1;
@@ -34,6 +35,10 @@ export interface InstallServicesOptions {
 	/** Service manager to generate for; defaults to the running platform. */
 	readonly platform?: ServicePlatform;
 	readonly env?: NodeJS.ProcessEnv;
+	/** Render adapter units only when their adapter-<platform>.json exists. */
+	readonly configuredAdaptersOnly?: boolean;
+	/** Leave unchanged unit files untouched. */
+	readonly compareAndWrite?: boolean;
 	/** Test seam for the `${SHELL} -lc` invocation used by the default path. */
 	readonly loginPathRunner?: LoginPathRunner;
 	/** Test seam for counting or inspecting the definition writes. */
@@ -55,9 +60,17 @@ interface ServiceSpec {
 	readonly dependsOnGateway: boolean;
 }
 
+export const BROKER_UNIT = "gajaeway-broker.service";
 export const GATEWAY_UNIT = "gajaeway-gateway.service";
 
 const SERVICE_SPECS: readonly ServiceSpec[] = [
+	{
+		id: "broker",
+		label: "dev.gajaeway.broker",
+		binary: "gajaeway-gateway",
+		args: ["broker"],
+		dependsOnGateway: false,
+	},
 	{
 		id: "gateway",
 		label: "dev.gajaeway.gateway",
@@ -79,6 +92,13 @@ const SERVICE_SPECS: readonly ServiceSpec[] = [
 		args: [],
 		dependsOnGateway: true,
 	},
+	{
+		id: "adapter-telegram",
+		label: "dev.gajaeway.adapter-telegram",
+		binary: "gajaeway-telegram",
+		args: [],
+		dependsOnGateway: true,
+	},
 	{ id: "admin", label: "dev.gajaeway.admin", binary: "gajaeway-admin", args: ["serve"], dependsOnGateway: true },
 ];
 
@@ -203,35 +223,50 @@ export function systemdUnitName(spec: ServiceSpec): string {
 	return `gajaeway-${spec.id}.service`;
 }
 
+/**
+ * `EnvironmentFile=` and `ConditionPathExists=` take one literal absolute path:
+ * systemd does not unquote them, so a quoted value is "not absolute" and the
+ * directive is silently ignored. Only `%` specifiers need escaping.
+ */
+function unitPath(path: string): string {
+	if (!path.startsWith("/") || /[\n\r\0]/.test(path))
+		throw new Error(`unit path must be absolute and single-line: ${path}`);
+	return path.replaceAll("%", "%%");
+}
+
+function unitEnvironmentFile(path: string): string {
+	return `EnvironmentFile=-${unitPath(path)}`;
+}
+
 export function renderSystemdUnit(spec: ServiceSpec, binDir: string, home: string, path: string): string {
 	const execStart = [join(binDir, spec.binary), ...spec.args].join(" ");
 	const unit = [
 		"[Unit]",
 		`Description=gajaeway ${spec.id}`,
-		// BindsTo restarts and stops this unit with the gateway; PartOf propagates a
-		// gateway restart even when this unit is started on its own; After orders
-		// the boot so the adapter connects to a listening socket.
-		...(spec.dependsOnGateway ? [`BindsTo=${GATEWAY_UNIT}`, `After=${GATEWAY_UNIT}`, `PartOf=${GATEWAY_UNIT}`] : []),
+		...(spec.id === "broker"
+			? [`ConditionPathExists=${unitPath(homeLayout(home).brokerProvisionManifest)}`]
+			: spec.id === "gateway"
+				? [`Wants=${BROKER_UNIT}`, `After=${BROKER_UNIT}`]
+				: spec.dependsOnGateway
+					? [`BindsTo=${GATEWAY_UNIT}`, `After=${GATEWAY_UNIT}`, `PartOf=${GATEWAY_UNIT}`]
+					: []),
 		"",
 		"[Service]",
 		`ExecStart=${execStart}`,
 		`WorkingDirectory=${binDir}`,
 		unitEnvironment("GAJAEWAY_HOME", home),
 		unitEnvironment("PATH", path),
+		...(spec.id === "broker" ? [unitEnvironmentFile(join(home, "broker.env"))] : []),
 		"Restart=always",
-		"RestartSec=2",
-		// Only the gateway: SIGTERM its main process for an ordered shutdown, then
-		// kill whatever is left in its cgroup so no child outlives the unit and
-		// gets re-adopted by the next start (#183). The gateway exits on its own
-		// inside 25s (SHUTDOWN_DEADLINE_MS in the gateway main); the unit's stop
-		// window is pinned so that ceiling always fits (#225). The gateway moves a GJC broker
-		// it autostarted into a scope of its own, so this never reaches the shared
-		// broker or its session hosts.
-		...(spec.dependsOnGateway ? [] : ["KillMode=mixed", "TimeoutStopSec=30s"]),
+		spec.id === "broker" ? "RestartSec=2s" : "RestartSec=2",
+		...(spec.id === "broker"
+			? // The host propagates `gjc sdk broker run`'s exit code: 143 is its clean SIGTERM stop.
+				["KillMode=control-group", "TimeoutStopSec=30s", "SuccessExitStatus=143"]
+			: spec.id === "gateway"
+				? ["KillMode=mixed", "TimeoutStopSec=30s"]
+				: []),
 		"",
 		"[Install]",
-		// Enabling the gateway pulls the whole stack in; a dependent is never
-		// wanted by default.target on its own, because it cannot run without one.
 		`WantedBy=${spec.dependsOnGateway ? GATEWAY_UNIT : "default.target"}`,
 		"",
 	];
@@ -256,14 +291,16 @@ export function systemdUnitPath(spec: ServiceSpec, unitDir: string): string {
 /**
  * The ordered commands that realign the whole stack.
  *
- * systemd expresses the dependency itself, so one restart of the gateway unit
- * is the entire operation. launchd has no BindsTo/PartOf equivalent and
- * `WatchPaths` does not restart an already-running job, so the ordering is
- * explicit here instead — and `bootout` never appears, because removing a job
- * leaves it with no automatic recovery.
+ * systemd restarts the broker before the gateway; gateway dependencies restart
+ * their adapters. launchd has no dependency propagation, so every job is
+ * kicked explicitly in the same order.
  */
 export function restartStackCommands(platform: ServicePlatform, uid?: number): readonly (readonly string[])[] {
-	if (platform === "linux") return [["systemctl", "--user", "restart", GATEWAY_UNIT]];
+	if (platform === "linux")
+		return [
+			["systemctl", "--user", "restart", BROKER_UNIT],
+			["systemctl", "--user", "restart", GATEWAY_UNIT],
+		];
 	if (platform === "darwin") {
 		const target = uid ?? process.getuid?.() ?? 0;
 		return restartOrder().map((spec) => ["launchctl", "kickstart", "-k", `gui/${target}/${spec.label}`]);
@@ -271,7 +308,7 @@ export function restartStackCommands(platform: ServicePlatform, uid?: number): r
 	throw new Error(`unsupported service platform: ${platform}`);
 }
 
-/** The gateway first, then every job that holds a connection to it. */
+/** Broker, gateway, then every job that holds a connection to the gateway. */
 export function restartOrder(): readonly ServiceSpec[] {
 	return [
 		...SERVICE_SPECS.filter((spec) => !spec.dependsOnGateway),
@@ -336,7 +373,15 @@ export async function installServices(options: InstallServicesOptions): Promise<
 		loginPathRunner: options.loginPathRunner,
 	});
 	await mkdir(targetDir, { recursive: true, mode: 0o700 });
-	const definitions = SERVICE_SPECS.map((spec) =>
+	const specs: ServiceSpec[] = [];
+	for (const spec of SERVICE_SPECS) {
+		if (options.configuredAdaptersOnly && spec.id.startsWith("adapter-")) {
+			const adapter = spec.id.slice("adapter-".length);
+			if (!(await Bun.file(join(home, `adapter-${adapter}.json`)).exists())) continue;
+		}
+		specs.push(spec);
+	}
+	const definitions = specs.map((spec) =>
 		platform === "darwin"
 			? {
 					path: join(targetDir, `dev.gajaeway.${spec.id}.plist`),
@@ -346,6 +391,13 @@ export async function installServices(options: InstallServicesOptions): Promise<
 	);
 	const write = options.writeFile;
 	for (const definition of definitions) {
+		if (options.compareAndWrite) {
+			try {
+				if ((await readFile(definition.path, "utf8")) === definition.contents) continue;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			}
+		}
 		if (write) await write(definition.path, definition.contents);
 		else {
 			await writeFile(definition.path, definition.contents, { encoding: "utf8", mode: 0o600 });

package/src/setup.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { chmod, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { printDiscordBotReady, printDiscordSetupGuide } from "./discord-setup";
 
 /**
  * `gajaeway setup`: guided credential setup for the platform adapters.
@@ -30,7 +31,7 @@ export const SETUP_ENV = {
 } as const;
 
 export const SETUP_USAGE =
-	"usage: gajaeway setup [--from-env] [--adapters discord,slack,telegram] [--owner ID[,ID...]] [--discord-app-id ID] | setup --status";
+	"usage: gajaeway setup [--from-env] [--adapters discord,slack,telegram] [--owner ID[,ID...]] [--discord-app-id ID] | setup --status | setup --broker-agent [--from DIR]";
 
 /** Secret file names under `$GAJAEWAY_HOME/secrets`, matching docs/deployment.md. */
 export const SECRET_FILES = {
@@ -59,16 +60,19 @@ export function redact(text: string, secrets: Iterable<string>): string {
 }
 
 export interface ParsedSetupArgs {
-	readonly mode: "setup" | "status";
+	readonly mode: "setup" | "status" | "broker-agent";
 	readonly fromEnv: boolean;
 	readonly adapters?: readonly SetupPlatform[];
 	readonly owners: readonly string[];
 	readonly discordAppId?: string;
+	readonly from?: string;
 }
 
 export function parseSetupArgs(args: readonly string[]): ParsedSetupArgs {
 	let fromEnv = false;
 	let status = false;
+	let brokerAgent = false;
+	let from: string | undefined;
 	let adapters: SetupPlatform[] | undefined;
 	const owners: string[] = [];
 	let discordAppId: string | undefined;
@@ -76,7 +80,13 @@ export function parseSetupArgs(args: readonly string[]): ParsedSetupArgs {
 		const flag = args[i] as string;
 		if (flag === "--from-env") fromEnv = true;
 		else if (flag === "--status") status = true;
-		else if (flag === "--adapters" || flag === "--owner" || flag === "--discord-app-id") {
+		else if (flag === "--broker-agent") brokerAgent = true;
+		else if (flag === "--from") {
+			const value = args[++i];
+			if (value === undefined || value.trim() === "" || value.startsWith("--"))
+				throw new SetupError(`${flag} expects a value\n${SETUP_USAGE}`);
+			from = value;
+		} else if (flag === "--adapters" || flag === "--owner" || flag === "--discord-app-id") {
 			const value = args[++i];
 			if (value === undefined || value.trim() === "" || value.startsWith("--"))
 				throw new SetupError(`${flag} expects a value\n${SETUP_USAGE}`);
@@ -89,14 +99,20 @@ export function parseSetupArgs(args: readonly string[]): ParsedSetupArgs {
 			);
 		} else throw new SetupError(`unknown option: ${flag.split("=")[0]}\n${SETUP_USAGE}`);
 	}
-	if (status && (fromEnv || adapters || owners.length > 0 || discordAppId))
+	if (status && (fromEnv || brokerAgent || from !== undefined || adapters || owners.length > 0 || discordAppId))
 		throw new SetupError(`--status takes no other options\n${SETUP_USAGE}`);
+	if (brokerAgent && (fromEnv || adapters || owners.length > 0 || discordAppId))
+		throw new SetupError(
+			`--broker-agent is standalone and cannot be combined with adapter setup options\n${SETUP_USAGE}`,
+		);
+	if (from !== undefined && !brokerAgent) throw new SetupError(`--from requires --broker-agent\n${SETUP_USAGE}`);
 	return {
-		mode: status ? "status" : "setup",
+		mode: status ? "status" : brokerAgent ? "broker-agent" : "setup",
 		fromEnv,
 		...(adapters ? { adapters } : {}),
 		owners,
 		...(discordAppId ? { discordAppId } : {}),
+		...(from === undefined ? {} : { from }),
 	};
 }
 
@@ -182,6 +198,8 @@ export interface ValidatedIdentity {
 	readonly summary: string;
 	/** A user id the platform names as the app owner, when it names one. */
 	readonly ownerId?: string;
+	/** Application ID (Discord only). */
+	readonly appId?: string;
 }
 
 async function requestJson(
@@ -241,7 +259,8 @@ export async function validateDiscord(
 	const ownerId = !hasTeam && typeof owner?.id === "string" ? owner.id : undefined;
 	return {
 		platform: "discord",
-		summary: `bot ${String(me.body.username ?? "?")} (${String(me.body.id ?? "?")}) of application ${appId}`,
+		summary: `bot named ${String(me.body.username ?? "?")} (${String(me.body.id ?? "?")}) of application ${appId}`,
+		appId,
 		...(ownerId ? { ownerId } : {}),
 	};
 }
@@ -472,13 +491,16 @@ async function askRequiredSecret(prompter: Prompter, question: string): Promise<
 export async function tokensFromPrompts(
 	prompter: Prompter,
 	parsed: ParsedSetupArgs,
+	log?: (line: string) => void,
 ): Promise<{ tokens: SetupTokens; owners: string[] }> {
 	const wanted = parsed.adapters ?? [];
 	const enable = async (platform: SetupPlatform, label: string) =>
 		parsed.adapters ? wanted.includes(platform) : await askYes(prompter, `Enable ${label}?`);
 	const tokens: { -readonly [K in keyof SetupTokens]: SetupTokens[K] } = {};
 	if (await enable("discord", "Discord")) {
-		const token = await askRequiredSecret(prompter, "Discord bot token (input hidden): ");
+		const logger = log ?? (() => {});
+		printDiscordSetupGuide(logger);
+		const token = await askRequiredSecret(prompter, "Paste your Discord bot token here (input hidden): ");
 		const appId = parsed.discordAppId ?? (await prompter.ask("Discord application id (optional): ")).trim();
 		tokens.discord = { token, ...(appId ? { appId } : {}) };
 	}
@@ -554,12 +576,40 @@ export function terminalPrompter(): Prompter {
 	};
 }
 
+export interface BrokerAgentRunResult {
+	readonly exitCode: number;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+export type BrokerAgentRunner = (command: readonly string[]) => Promise<BrokerAgentRunResult>;
+
+async function defaultBrokerAgentRunner(command: readonly string[]): Promise<BrokerAgentRunResult> {
+	const child = Bun.spawn([...command], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	]);
+	return { exitCode, stdout, stderr };
+}
+
+async function setupBinDir(options: RunSetupOptions): Promise<string> {
+	if (options.binDir !== undefined) return options.binDir;
+	const env = options.env ?? process.env;
+	if (env.GAJAEWAY_BIN_DIR) return env.GAJAEWAY_BIN_DIR;
+	const executable = await realpath(process.execPath).catch(() => undefined);
+	if (executable !== undefined && basename(executable).startsWith("gajaeway")) return dirname(executable);
+	throw new SetupError("setup --broker-agent requires the installed gajaeway binary or an explicit bin directory");
+}
 export interface RunSetupOptions {
 	readonly home: string;
+	readonly binDir?: string;
 	readonly env?: NodeJS.ProcessEnv;
 	readonly fetch?: FetchLike;
 	readonly prompter?: () => Prompter;
 	readonly log?: (line: string) => void;
+	readonly runBrokerAgent?: BrokerAgentRunner;
 }
 
 /** The whole command. Returns the lines it printed so tests can assert nothing secret escaped. */
@@ -570,6 +620,23 @@ export async function runSetup(args: readonly string[], options: RunSetupOptions
 		log((await enabledAdapters(options.home)).join(","));
 		return;
 	}
+	if (parsed.mode === "broker-agent") {
+		const command = [
+			join(await setupBinDir(options), "gajaeway-gateway"),
+			"broker-agent",
+			"provision",
+			"--mode",
+			"force",
+			...(parsed.from === undefined ? [] : ["--from", parsed.from]),
+		];
+		const result = await (options.runBrokerAgent ?? defaultBrokerAgentRunner)(command);
+		if (result.stdout.length > 0) process.stdout.write(result.stdout);
+		if (result.stderr.length > 0) process.stderr.write(result.stderr);
+		if (result.exitCode === 1 && /lease_held name=broker/.test(`${result.stdout}\n${result.stderr}`))
+			log("broker lease is held; stop it with: systemctl --user stop gajaeway-broker");
+		process.exitCode = result.exitCode;
+		return;
+	}
 	let tokens: SetupTokens;
 	let owners: string[];
 	if (parsed.fromEnv) {
@@ -578,7 +645,7 @@ export async function runSetup(args: readonly string[], options: RunSetupOptions
 	} else {
 		const prompter = (options.prompter ?? terminalPrompter)();
 		try {
-			({ tokens, owners } = await tokensFromPrompts(prompter, parsed));
+			({ tokens, owners } = await tokensFromPrompts(prompter, parsed, log));
 		} finally {
 			prompter.close();
 		}
@@ -587,6 +654,14 @@ export async function runSetup(args: readonly string[], options: RunSetupOptions
 	try {
 		const identities = await validateAll(tokens, options.fetch ?? ((input, init) => fetch(input, init)));
 		for (const identity of identities) log(`${identity.platform}: token valid — ${identity.summary}`);
+
+		// Print Discord invite URL after successful validation
+		const discordIdentity = identities.find((i) => i.platform === "discord");
+		if (discordIdentity && tokens.discord && discordIdentity.appId) {
+			const botName = (discordIdentity.summary.match(/named (\S+)/) ?? [])[1];
+			printDiscordBotReady(log, discordIdentity.appId, botName);
+		}
+
 		for (const identity of identities)
 			if (identity.ownerId && owners.length === 0) {
 				owners.push(identity.ownerId);

package/src/up.ts

@@ -0,0 +1,133 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { GajaewayClient } from "@gajae-gateway/sdk";
+import type { RunSetupOptions } from "./setup";
+import { enabledAdapters, runSetup } from "./setup";
+
+export interface UpOptions extends Omit<RunSetupOptions, "home"> {
+	readonly home: string;
+	readonly socket?: string;
+	/** Skip the setup check and assume config exists. */
+	readonly skipSetup?: boolean;
+	/** Spawn runner for tests; defaults to Bun.spawn */
+	readonly spawn?: (cmd: string, args: string[], opts?: { cwd?: string }) => unknown;
+}
+
+/**
+ * `gajaeway up`: One-command setup and start for first-time users.
+ *
+ * Checks for existing config.json; if missing, runs interactive setup.
+ * Then starts the gateway daemon and enabled adapters in the background.
+ * Reports the gateway status and how to stop it.
+ */
+export async function runUp(options: UpOptions): Promise<void> {
+	const log = options.log ?? ((line: string) => console.log(line));
+	const configPath = join(options.home, "config.json");
+
+	// Check if setup is needed
+	if (!options.skipSetup) {
+		let exists = false;
+		try {
+			await access(configPath);
+			exists = true;
+		} catch {
+			// File does not exist
+		}
+
+		if (!exists) {
+			log("No configuration found. Running setup...\n");
+			try {
+				// Run setup in default (interactive) mode
+				await runSetup([], {
+					home: options.home,
+					env: options.env,
+					fetch: options.fetch,
+					prompter: options.prompter,
+					log,
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				log(`Setup failed: ${message}`);
+				throw error;
+			}
+
+			log("\n✓ Configuration saved.\n");
+		}
+	}
+
+	// Check gateway status
+	const socket = options.socket ?? `${options.home}/gateway.sock`;
+	let isRunning = false;
+
+	try {
+		const client = await GajaewayClient.connectSocket(socket);
+		try {
+			await client.status();
+			isRunning = true;
+		} finally {
+			await client.close();
+		}
+	} catch {
+		// Gateway is not running; we'll try to start it
+	}
+
+	if (isRunning) {
+		log("✓ Gateway is already running.");
+		const adapters = await enabledAdapters(options.home);
+		log(`✓ Enabled adapters: ${adapters.join(", ")}`);
+		log("\nYou can now:");
+		log("  • Send a message to your bot on Discord/Slack/Telegram");
+		log("  • View status: gajaeway ops cycle");
+		log("  • Search memory: gajaeway memory search <query>");
+		log("\nStop with: gajaeway shutdown");
+	} else {
+		// Try to start the gateway and adapters
+		log("Starting gateway and adapters...");
+
+		// Detect if we're in the source checkout (has dist/gajaeway-gateway)
+		// vs. running from installed binaries
+		const isSourceCheckout = await access(join(options.home, "..", "..", "dist", "gajaeway-gateway"))
+			.then(() => true)
+			.catch(() => false);
+
+		const spawn = options.spawn ?? ((cmd: string, args: string[]) => Bun.spawn([cmd, ...args]));
+
+		try {
+			// Start gateway daemon
+			// Use bun packages/gateway/src/main.ts if in source checkout, else use binary
+			const gatewayCmd = isSourceCheckout ? "bun" : "gajaeway-gateway";
+			const gatewayArgs = isSourceCheckout ? ["packages/gateway/src/main.ts", "daemon"] : ["daemon"];
+
+			const gatewayProcess = spawn(gatewayCmd, gatewayArgs, { cwd: process.cwd() });
+
+			// Give gateway a moment to start
+			await new Promise((resolve) => setTimeout(resolve, 2000));
+
+			// Start enabled adapters
+			const adapters = await enabledAdapters(options.home);
+			for (const adapter of adapters) {
+				const adapterCmd = isSourceCheckout ? "dist/gajaeway-" + adapter : "gajaeway-" + adapter;
+				const adapterProcess = spawn(adapterCmd, [], { cwd: process.cwd() });
+				// Don't wait for adapter; let it run in background
+			}
+
+			log("\n✓ Gateway started.");
+			if (adapters.length > 0) {
+				log(`✓ Adapters started: ${adapters.join(", ")}`);
+			}
+
+			log("\nYou can now:");
+			log("  • Send a message to your bot on Discord/Slack/Telegram");
+			log("  • View status: gajaeway ops cycle");
+			log("  • Search memory: gajaeway memory search <query>");
+			log("\nStop with: gajaeway shutdown");
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			log(`Failed to start services: ${message}`);
+			log("\nAlternative: start manually in separate terminals:");
+			log("  Terminal 1: bun packages/gateway/src/main.ts daemon");
+			log("  Terminal 2: dist/gajaeway-discord");
+			throw error;
+		}
+	}
+}