@stackbone/cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-alpha.2] - 2026-05-12
+
+### Added
+
+- Per-stage spinners during `stackbone dev` (docker, platform/creator/rag
+  migrations, agent, emulator, tunnel) and a redesigned rounded-box Studio
+  banner that surfaces the actionable deeplink first. New global flag
+  `--verbose` (also `STACKBONE_VERBOSE=1`) restores the raw firehose of
+  docker compose stdout and pino logs for debugging.
+
+### Changed
+
+- `stackbone dev` Studio banner now prints
+  `app.stackbone.ai/app?stackbone-dev=<tunnel>` instead of the retired
+  `/studio?baseUrl=…` deeplink. The new URL is consumed in one shot by the
+  `stackboneDevBootstrapGuard` mounted on `/app`, which flips Studio to
+  local mode against the tunnel and opens the panel on Runs.
+
+### Fixed
+
+- `stackbone dev` boot banner no longer emits a leading newline or
+  duplicate `│` rail rows around the inlined Studio banner when running
+  under clack's left rail in human mode.
+
 ## [0.1.0-alpha.1] - 2026-05-12
 
 ### Changed

package/main.js

@@ -1269,7 +1269,9 @@ var createHttpAdapter = (opts) => {
 //#endregion
 //#region src/infra/logger.ts
 var createLogger = (opts) => {
-	const level = opts.level ?? process.env["STACKBONE_LOG_LEVEL"] ?? "info";
+	const envLevel = process.env["STACKBONE_LOG_LEVEL"];
+	const defaultLevel = opts.json || opts.verbose ? "info" : "warn";
+	const level = opts.level ?? envLevel ?? defaultLevel;
 	if (opts.json) return pino({ level }, pino.destination(2));
 	const stream = pretty({
 		destination: 2,
@@ -1360,7 +1362,8 @@ var parseFlags = (argv, env) => ({
 	json: detectJsonMode(argv, env),
 	yes: flagPresent(argv, "-y") || flagPresent(argv, "--yes"),
 	autoLogin: env["STACKBONE_AUTO_LOGIN"] !== "0" && !flagPresent(argv, "--no-auto-login"),
-	apiUrlOverride: flagValue(argv, "--api-url") ?? env["STACKBONE_API_URL"] ?? null
+	apiUrlOverride: flagValue(argv, "--api-url") ?? env["STACKBONE_API_URL"] ?? null,
+	verbose: flagPresent(argv, "--verbose") || env["STACKBONE_VERBOSE"] === "1"
 });
 /**
 * Builds the single `CliContext` value passed to every command.
@@ -1378,7 +1381,10 @@ var parseFlags = (argv, env) => ({
 */
 var createCliContext = async (opts) => {
 	const flags = parseFlags(opts.argv, opts.env);
-	const logger = createLogger({ json: flags.json });
+	const logger = createLogger({
+		json: flags.json,
+		verbose: flags.verbose
+	});
 	const projectConfig = createProjectConfigAdapter(opts.cwd);
 	const globalConfig = createGlobalConfigAdapter();
 	const tokenStore = createTokenStore();
@@ -1416,7 +1422,7 @@ var isVersionFlag = (rawArgs) => rawArgs.length === 1 && VERSION_FLAGS.has(rawAr
 var formatVersionOutput = (input) => `stackbone-cli ${input.cliVersion}\ncontract ${input.contractVersion}`;
 //#endregion
 //#region src/dev/contract.ts
-var STACKBONE_CLI_BUILD_VERSION = "0.1.0-alpha.1";
+var STACKBONE_CLI_BUILD_VERSION = "0.1.0-alpha.2";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`. Typed as
 * `readonly Capability[]` so the compiler refuses any string outside the
@@ -2741,22 +2747,93 @@ var createDeployCommand = (ctx) => buildStubCommand(ctx, {
 });
 //#endregion
 //#region src/dev/boot-banner.ts
-var STUDIO_CLOUD_BASE_URL = "https://app.stackbone.ai/studio";
-var BORDER = "─".repeat(72);
-var buildDeeplink = (tunnelUrl) => `${STUDIO_CLOUD_BASE_URL}?baseUrl=${encodeURIComponent(tunnelUrl)}`;
+var STUDIO_CLOUD_BASE_URL = "https://app.stackbone.ai/app";
+var ANSI = {
+	reset: "\x1B[0m",
+	bold: "\x1B[1m",
+	dim: "\x1B[2m",
+	cyan: "\x1B[36m",
+	underline: "\x1B[4m"
+};
+var ANSI_RE = /\x1b\[[0-9;]*m/g;
+var visibleLength = (s) => s.replace(ANSI_RE, "").length;
+var buildDeeplink = (tunnelUrl) => `${STUDIO_CLOUD_BASE_URL}?stackbone-dev=${encodeURIComponent(tunnelUrl)}`;
+var LABEL_WIDTH = 11;
+var renderRow = (row, colors) => {
+	const marker = colors && row.marker.trim() ? `${ANSI.cyan}${row.marker}${ANSI.reset}` : row.marker;
+	const labelText = row.label.padEnd(LABEL_WIDTH, " ");
+	return `${marker} ${colors ? `${ANSI.dim}${labelText}${ANSI.reset}` : labelText}  ${colors && row.primary ? `${ANSI.bold}${ANSI.cyan}${row.value}${ANSI.reset}` : row.value}`;
+};
+var TITLE = "stackbone studio";
 var formatBootBanner = (input) => {
-	const lines = [];
-	lines.push(BORDER);
-	lines.push("  Stackbone Studio");
-	lines.push("");
+	const colors = input.colors ?? false;
+	const rows = [];
 	if (input.tunnelUrl) {
-		lines.push(`  Tunnel:    ${input.tunnelUrl}`);
-		lines.push(`  Studio:    ${buildDeeplink(input.tunnelUrl)}`);
-		lines.push(`  Local:     ${input.localUrl}    (sin tunnel)`);
-	} else lines.push(`  Local:     ${input.localUrl}`);
-	lines.push(`  Contract version ${input.contractVersion} (capabilities: ${input.capabilityCount})`);
-	lines.push("");
-	lines.push(BORDER);
+		rows.push({
+			marker: "▸",
+			label: "Open Studio",
+			value: buildDeeplink(input.tunnelUrl),
+			primary: true
+		});
+		rows.push({
+			marker: " ",
+			label: "",
+			value: ""
+		});
+		rows.push({
+			marker: " ",
+			label: "Tunnel",
+			value: input.tunnelUrl
+		});
+		rows.push({
+			marker: " ",
+			label: "Local",
+			value: input.localUrl
+		});
+	} else rows.push({
+		marker: "▸",
+		label: "Local",
+		value: input.localUrl,
+		primary: true
+	});
+	rows.push({
+		marker: " ",
+		label: "",
+		value: ""
+	});
+	rows.push({
+		marker: " ",
+		label: "Agent",
+		value: input.agentName
+	});
+	rows.push({
+		marker: " ",
+		label: "Protocol",
+		value: `v${input.contractVersion}  ·  ${input.capabilityCount} capabilities`
+	});
+	const renderedRows = rows.map((row) => {
+		if (row.label === "" && row.value === "") return "";
+		return renderRow(row, colors);
+	});
+	const padding = 2;
+	const longestRow = renderedRows.reduce((max, line) => Math.max(max, visibleLength(line)), 0);
+	const innerWidth = Math.max(longestRow, 22);
+	const totalInner = innerWidth + padding * 2;
+	const titleSegment = ` ${TITLE} `;
+	const titleSegmentColored = colors ? ` ${ANSI.bold}${TITLE}${ANSI.reset} ` : titleSegment;
+	const dashesAfter = totalInner - 1 - titleSegment.length;
+	const top = `╭─${titleSegmentColored}${"─".repeat(Math.max(dashesAfter, 1))}╮`;
+	const bottom = `╰${"─".repeat(totalInner)}╯`;
+	const padRow = (line) => {
+		const trailing = innerWidth - visibleLength(line);
+		return `│  ${line}${" ".repeat(Math.max(trailing, 0))}  │`;
+	};
+	const lines = [];
+	lines.push(top);
+	lines.push(padRow(""));
+	for (const line of renderedRows) lines.push(padRow(line));
+	lines.push(padRow(""));
+	lines.push(bottom);
 	return lines.join("\n");
 };
 //#endregion
@@ -3477,21 +3554,34 @@ volumes:
 //#endregion
 //#region src/dev/compose.ts
 var DOCKER_BIN = process.env["STACKBONE_DOCKER_BIN"] ?? "docker";
-var runDocker = async (args, cwd, signal) => {
+var runDocker = async (args, cwd, opts = {}) => {
 	await new Promise((resolve, reject) => {
+		const captured = [];
 		const child = spawn(DOCKER_BIN, args, {
 			cwd,
-			stdio: [
+			stdio: opts.verbose ? [
 				"ignore",
 				"inherit",
 				"inherit"
+			] : [
+				"ignore",
+				"pipe",
+				"pipe"
 			],
-			signal
+			signal: opts.signal
 		});
+		if (!opts.verbose) {
+			child.stdout?.on("data", (chunk) => captured.push(chunk));
+			child.stderr?.on("data", (chunk) => captured.push(chunk));
+		}
 		child.once("error", reject);
 		child.once("close", (code) => {
-			if (code === 0) resolve();
-			else reject(new StackboneCliError({
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			if (!opts.verbose && captured.length > 0) process.stderr.write(Buffer.concat(captured));
+			reject(new StackboneCliError({
 				code: "generic",
 				message: `\`docker ${args.join(" ")}\` exited with code ${code}`,
 				suggestion: "Check Docker Desktop is running and that the embedded compose file in `.stackbone/dev/` is valid"
@@ -3519,12 +3609,13 @@ var writeComposeFiles = async (runtime) => {
 	await writeFile(join(runtime.workdir, "Dockerfile.postgres"), POSTGRES_DOCKERFILE);
 };
 var composeUp = async (runtime) => {
+	const verbose = runtime.verbose ?? false;
 	await runDocker([
 		"compose",
 		"up",
 		"-d",
 		"--wait"
-	], runtime.workdir);
+	], runtime.workdir, { verbose });
 	await runDocker([
 		"compose",
 		"--profile",
@@ -3532,11 +3623,11 @@ var composeUp = async (runtime) => {
 		"run",
 		"--rm",
 		"minio-bucket-init"
-	], runtime.workdir);
+	], runtime.workdir, { verbose });
 };
 var composeDown = async (runtime) => {
 	try {
-		await runDocker(["compose", "down"], runtime.workdir);
+		await runDocker(["compose", "down"], runtime.workdir, { verbose: runtime.verbose ?? false });
 	} catch {}
 };
 var buildComposeRuntime = (projectRoot, options) => {
@@ -7080,6 +7171,7 @@ var autoMigrationName = () => {
 	return `auto_${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/T/, "_").slice(0, 15)}`;
 };
 var startDevSession = async (input) => {
+	const onStage = input.onStage ?? (() => void 0);
 	await ensureDockerAvailable();
 	const bus = createEventBus();
 	const agentPort = await pickFreePort();
@@ -7099,13 +7191,40 @@ var startDevSession = async (input) => {
 		minioRootPassword: "stackbone-secret",
 		minioDefaultBucket: "stackbone-dev"
 	});
+	if (input.verbose) compose.verbose = true;
 	await writeComposeFiles(compose);
-	await composeUp(compose);
+	onStage({
+		stage: "docker",
+		status: "start"
+	});
+	try {
+		await composeUp(compose);
+		onStage({
+			stage: "docker",
+			status: "success",
+			detail: "postgres + minio ready"
+		});
+	} catch (err) {
+		onStage({
+			stage: "docker",
+			status: "fail",
+			detail: err instanceof Error ? err.message : String(err)
+		});
+		throw err;
+	}
 	const migrationsDir = resolve(dirname(fileURLToPath(import.meta.url)), "migrations");
+	onStage({
+		stage: "platform-migrations",
+		status: "start"
+	});
+	let platformApplied = 0;
+	let platformSkipped = 0;
 	try {
 		await applyMigrations(injection.services.postgresUrl, {
 			migrationsDir,
 			onMigration: (event) => {
+				if (event.action === "applied") platformApplied += 1;
+				else platformSkipped += 1;
 				input.ctx.logger.info({
 					migration: event.version,
 					action: event.action,
@@ -7113,7 +7232,17 @@ var startDevSession = async (input) => {
 				}, `stackbone_platform schema: ${event.action} ${String(event.version).padStart(4, "0")} in ${event.durationMs}ms`);
 			}
 		});
+		onStage({
+			stage: "platform-migrations",
+			status: "success",
+			detail: platformApplied > 0 ? `${platformApplied} applied, ${platformSkipped} skipped` : `${platformSkipped} already applied`
+		});
 	} catch (err) {
+		onStage({
+			stage: "platform-migrations",
+			status: "fail",
+			detail: err instanceof Error ? err.message : String(err)
+		});
 		await composeDown(compose);
 		throw new StackboneCliError({
 			code: "generic",
@@ -7122,39 +7251,67 @@ var startDevSession = async (input) => {
 			cause: err
 		});
 	}
+	onStage({
+		stage: "creator-migrations",
+		status: "start"
+	});
 	try {
 		await runPreBootMigrate({
 			agentRoot: input.projectRoot,
 			connectionString: injection.services.postgresUrl,
 			logger: input.ctx.logger
 		});
+		onStage({
+			stage: "creator-migrations",
+			status: "success"
+		});
 	} catch (err) {
+		onStage({
+			stage: "creator-migrations",
+			status: "fail",
+			detail: err instanceof Error ? err.message : String(err)
+		});
 		await composeDown(compose);
 		throw err;
 	}
 	const preBootRagManifest = readWatcherManifest(input.projectRoot);
-	if (preBootRagManifest !== null) try {
-		await runPreBootRag({
-			agentRoot: input.projectRoot,
-			migrationsDir: preBootRagManifest.migrations,
-			autoMigrate: preBootRagManifest.ragAutoMigrate,
-			logger: input.ctx.logger,
-			addRag,
-			runMigrateUp: () => migrateUp({
-				connectionString: injection.services.postgresUrl,
-				migrationsDir: preBootRagManifest.migrations,
-				onMigration: (event) => {
-					input.ctx.logger.info({
-						migration: event.tag,
-						action: event.action,
-						durationMs: event.durationMs
-					}, `RAG schema: ${event.action} ${event.tag}`);
-				}
-			})
+	if (preBootRagManifest !== null) {
+		onStage({
+			stage: "rag-migrations",
+			status: "start"
 		});
-	} catch (err) {
-		await composeDown(compose);
-		throw err;
+		try {
+			await runPreBootRag({
+				agentRoot: input.projectRoot,
+				migrationsDir: preBootRagManifest.migrations,
+				autoMigrate: preBootRagManifest.ragAutoMigrate,
+				logger: input.ctx.logger,
+				addRag,
+				runMigrateUp: () => migrateUp({
+					connectionString: injection.services.postgresUrl,
+					migrationsDir: preBootRagManifest.migrations,
+					onMigration: (event) => {
+						input.ctx.logger.info({
+							migration: event.tag,
+							action: event.action,
+							durationMs: event.durationMs
+						}, `RAG schema: ${event.action} ${event.tag}`);
+					}
+				})
+			});
+			onStage({
+				stage: "rag-migrations",
+				status: "success"
+			});
+		} catch (err) {
+			onStage({
+				stage: "rag-migrations",
+				status: "fail",
+				detail: err instanceof Error ? err.message : String(err)
+			});
+			await composeDown(compose);
+			throw err;
+		}
 	}
 	const invocations = createInvocationsStore({ connectionString: injection.services.postgresUrl });
 	const approvals = createApprovalsStore({
@@ -7199,6 +7356,10 @@ var startDevSession = async (input) => {
 		});
 	};
 	try {
+		onStage({
+			stage: "agent",
+			status: "start"
+		});
 		agent = startAgentProcess({
 			cwd: input.projectRoot,
 			env: input.ctx.env,
@@ -7207,6 +7368,11 @@ var startDevSession = async (input) => {
 			injection,
 			agentConfig: agentConfigEnv
 		});
+		onStage({
+			stage: "agent",
+			status: "success",
+			detail: `http://127.0.0.1:${agentPort}`
+		});
 		configWatcher = await startAgentConfigWatcher({
 			connectionString: injection.services.postgresUrl,
 			logger: input.ctx.logger,
@@ -7261,25 +7427,63 @@ var startDevSession = async (input) => {
 			envValue: input.ctx.env["STACKBONE_CORS_ALLOW_ORIGINS"],
 			fileValue: fileConfig?.studio?.corsOrigins
 		});
-		emulator = await startEmulatorServer({
-			port: input.emulatorPort,
-			bus,
-			invocations,
-			approvals,
-			injection,
-			agent: input.agent,
-			cors: corsAllowlist,
-			listen: input.listen
+		onStage({
+			stage: "emulator",
+			status: "start"
 		});
+		try {
+			emulator = await startEmulatorServer({
+				port: input.emulatorPort,
+				bus,
+				invocations,
+				approvals,
+				injection,
+				agent: input.agent,
+				cors: corsAllowlist,
+				listen: input.listen
+			});
+			onStage({
+				stage: "emulator",
+				status: "success",
+				detail: emulator.url
+			});
+		} catch (err) {
+			onStage({
+				stage: "emulator",
+				status: "fail",
+				detail: err instanceof Error ? err.message : String(err)
+			});
+			throw err;
+		}
 		if (input.listen) input.ctx.logger.warn({
 			boundTo: "0.0.0.0",
 			port: input.emulatorPort
 		}, `WARNING: emulator bound to 0.0.0.0:${input.emulatorPort} — reachable from your LAN`);
-		if (input.tunnel) tunnel = await openDevTunnel({
-			targetUrl: emulator.url,
-			ctx: input.ctx,
-			projectRoot: input.projectRoot
-		});
+		if (input.tunnel) {
+			onStage({
+				stage: "tunnel",
+				status: "start"
+			});
+			try {
+				tunnel = await openDevTunnel({
+					targetUrl: emulator.url,
+					ctx: input.ctx,
+					projectRoot: input.projectRoot
+				});
+				onStage({
+					stage: "tunnel",
+					status: "success",
+					detail: tunnel.publicUrl
+				});
+			} catch (err) {
+				onStage({
+					stage: "tunnel",
+					status: "fail",
+					detail: err instanceof Error ? err.message : String(err)
+				});
+				throw err;
+			}
+		}
 		return {
 			emulatorUrl: emulator.url,
 			agentUrl: `http://127.0.0.1:${agentPort}`,
@@ -7317,6 +7521,60 @@ var printContract = (deps = {}) => {
 };
 //#endregion
 //#region src/commands/dev/dev.command.ts
+var STAGE_LABELS = {
+	docker: {
+		start: "Starting docker services",
+		done: "Docker services ready"
+	},
+	"platform-migrations": {
+		start: "Applying platform migrations",
+		done: "Platform migrations applied"
+	},
+	"creator-migrations": {
+		start: "Applying agent migrations",
+		done: "Agent migrations applied"
+	},
+	"rag-migrations": {
+		start: "Preparing RAG schema",
+		done: "RAG schema ready"
+	},
+	agent: {
+		start: "Starting agent process",
+		done: "Agent process ready"
+	},
+	emulator: {
+		start: "Starting emulator",
+		done: "Emulator listening"
+	},
+	tunnel: {
+		start: "Opening tunnel",
+		done: "Tunnel ready"
+	}
+};
+/**
+* Wires `onStage` events from the orchestrator to a single rolling clack
+* spinner. Only one stage is in flight at a time (the orchestrator is
+* sequential), so we keep one handle and recycle it across stages.
+*/
+var createStageRenderer = () => {
+	let active = null;
+	let activeStage = null;
+	return (event) => {
+		const label = STAGE_LABELS[event.stage];
+		if (event.status === "start") {
+			active = spinner();
+			activeStage = event.stage;
+			active.start(label.start);
+			return;
+		}
+		if (active === null || activeStage !== event.stage) return;
+		const detail = event.detail ? ` (${event.detail})` : "";
+		if (event.status === "success") active.stop(`${label.done}${detail}`);
+		else active.error(`${label.start} failed${detail}`);
+		active = null;
+		activeStage = null;
+	};
+};
 var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 	const config = await innerCtx.projectConfig.read();
 	if (!config) throw new StackboneCliError({
@@ -7332,6 +7590,7 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 		message: "The agent linked to this directory no longer exists in the workspace",
 		suggestion: "Run `stackbone link --force --agent <slug>` to re-link to a different agent"
 	});
+	const renderStage = innerCtx.flags.json ? null : createStageRenderer();
 	const session = await startDevSession({
 		ctx: innerCtx,
 		projectRoot,
@@ -7341,9 +7600,11 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 		},
 		emulatorPort: flags.port,
 		tunnel: flags.tunnel,
-		listen: flags.listen
+		listen: flags.listen,
+		verbose: flags.verbose,
+		...renderStage ? { onStage: renderStage } : {}
 	});
-	emit(innerCtx.flags, () => "", {
+	if (innerCtx.flags.json) emit(innerCtx.flags, () => "", {
 		emulator_url: session.emulatorUrl,
 		agent_url: session.agentUrl,
 		public_url: session.publicUrl,
@@ -7354,15 +7615,19 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 			s3_bucket: session.injection.services.s3Bucket
 		}
 	});
-	if (!innerCtx.flags.json) {
-		log.step(`Agent:     ${session.agentUrl}`);
-		console.log(`\n${formatBootBanner({
+	else {
+		const inlineLines = formatBootBanner({
 			tunnelUrl: session.publicUrl,
 			localUrl: session.emulatorUrl,
 			contractVersion: 10,
-			capabilityCount: EMULATOR_CAPABILITIES.length
-		})}\n`);
-		log.step("Press Ctrl-C to stop.");
+			capabilityCount: EMULATOR_CAPABILITIES.length,
+			agentName: agent.name,
+			colors: process.stdout.isTTY === true
+		}).split("\n").slice(1, -1).map((line) => line.replace(/^│ {2}/, "").replace(/ {2}│$/, "").trimEnd());
+		while (inlineLines.length > 0 && inlineLines[0] === "") inlineLines.shift();
+		while (inlineLines.length > 0 && inlineLines[inlineLines.length - 1] === "") inlineLines.pop();
+		log.message(inlineLines.join("\n"));
+		log.step("Press Ctrl-C to stop");
 	}
 	const sigintHandler = () => {
 		session.stop();
@@ -7398,6 +7663,11 @@ var createDevCommand = (ctx) => defineCommand({
 			type: "boolean",
 			description: "Print the JSON contract this CLI advertises (the same payload the emulator serves at /api/contract) and exit without booting the dev session.",
 			default: false
+		},
+		verbose: {
+			type: "boolean",
+			description: "Stream every log line and docker compose output. Default UI uses per-stage spinners; --verbose switches back to the raw firehose.",
+			default: false
 		}
 	},
 	run: ({ args }) => safeRun(ctx.flags, async (a) => {
@@ -7414,7 +7684,8 @@ var createDevCommand = (ctx) => defineCommand({
 		await buildHandler$2(ctx, {
 			port,
 			tunnel: Boolean(a.tunnel),
-			listen: Boolean(a.listen)
+			listen: Boolean(a.listen),
+			verbose: Boolean(a.verbose)
 		});
 	})(args)
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {