@stackbone/cli 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-06
+
+### Added
+
+- **`stackbone dev` links a project that arrived without a link.** `.stackbone/`
+  is gitignored — by the very block `init` and `link` write — so a project
+  cloned from someone else's repository has none, and there was no clean way to
+  get one: `dev` refused and pointed at `stackbone init`, which registers a
+  _new_ agent and scaffolds its own `package.json` over the project you were
+  handed, or at `stackbone link`, which registers an already-deployed box and so
+  requires its URL, HMAC secret and image tag. Neither describes "I was given
+  this project and want to run it".
+
+  Now `dev` lists the agents your organization owns, lets you pick one or create
+  a new one named after the folder, writes the link, gitignores it, and carries
+  on booting. Non-interactive runs (`--json`, `--yes`, CI, no terminal) still
+  fail rather than guessing, with a message naming the options that apply.
+
+## [0.3.0] - 2026-08-06
+
+### Added
+
+- **`stackbone package` turns a project into a folder someone else can run.**
+  It compiles the workspace and writes a two-line Dockerfile over the published
+  Stackbone runtime base, a `docker-compose.yml` that also brings up a Postgres
+  and a Redis, an `.env` carrying a freshly generated `STACKBONE_SECRET_KEY`,
+  and a README written for whoever receives it. On the far end it is two
+  commands: `docker compose up -d`, then a health check. Building the image is
+  one `COPY` over a base that already carries the server and its dependencies,
+  so it takes seconds and needs neither the Stackbone monorepo nor an install.
+
+  The command always compiles rather than packaging whatever is sitting in
+  `dist/`: the folder gets run by someone else, days later, and there is nobody
+  left to notice it was built from yesterday's code.
+
+  `--offline` also saves the image into the folder (around 150 MB) for a
+  network that cannot reach a registry. That variant emits no build
+  instructions, since the image arrives by loading the archive.
+
+  Two things the generated files say that nothing said before: **the database
+  needs the `pgvector` extension** — without it the first boot applies most of
+  the schema and then stops, which reads like a bug in the agent rather than a
+  missing extension — and the agent serves on **8080** unless `PORT` says
+  otherwise, with `/live` as the health check a managed host should use.
+
+### Changed
+
+- **`stackbone build` no longer has to be followed by hand-written deployment
+  files.** It still emits just the workspace bundle, for anyone who already
+  owns their image and their deployment; `stackbone package` is now the route
+  to take when you do not.
+
 ## [0.2.10] - 2026-08-02
 
 ### Added

package/main.js

@@ -10576,7 +10576,7 @@ var createBoxAuthGate = (options) => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/contract.ts
 init_src$13();
-var STACKBONE_CLI_BUILD_VERSION = "0.3.0";
+var STACKBONE_CLI_BUILD_VERSION = "0.3.1";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -53652,6 +53652,175 @@ var assertSdkCompatible = async (ctx, opts) => {
 	return result;
 };
 //#endregion
+//#region src/services/project.service.ts
+var GITIGNORE_MARKER_BEGIN$1 = "# >>> stackbone >>>";
+var GITIGNORE_BLOCK = [
+	GITIGNORE_MARKER_BEGIN$1,
+	".stackbone/",
+	"node_modules/",
+	"dist/",
+	"# <<< stackbone <<<",
+	""
+].join("\n");
+var exists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch (err) {
+		if (isENOENT(err)) return false;
+		throw err;
+	}
+};
+var writeProjectConfig = async (ctx, agent, input, extras = {}) => {
+	const config = {
+		schemaVersion: 1,
+		organizationId: agent.organizationId,
+		agentId: agent.id,
+		controlPlaneUrl: ctx.apiUrl,
+		...extras.localDevInstallationId !== void 0 ? { localDevInstallationId: extras.localDevInstallationId } : {},
+		...extras.organizationSlug !== void 0 ? { organizationSlug: extras.organizationSlug } : {},
+		...extras.agentSlug !== void 0 ? { agentSlug: extras.agentSlug } : {},
+		...extras.starter !== void 0 ? { starter: extras.starter } : {}
+	};
+	await mkdir(join(input.root, ".stackbone"), { recursive: true });
+	await writeFile(join(input.root, ".stackbone", "project.json"), JSON.stringify(config, null, 2));
+	return config;
+};
+var ensureGitignore = async (root) => {
+	const path = join(root, ".gitignore");
+	let current = "";
+	try {
+		current = await readFile(path, "utf8");
+	} catch (err) {
+		if (!isENOENT(err)) throw err;
+	}
+	if (current.includes(GITIGNORE_MARKER_BEGIN$1)) return;
+	await writeFile(path, current.length > 0 && !current.endsWith("\n") ? `${current}\n${GITIGNORE_BLOCK}` : `${current}${GITIGNORE_BLOCK}`);
+};
+var detectExistingProjectFiles = async (root, paths) => {
+	const checks = await Promise.all(paths.map((p) => exists(join(root, p))));
+	return paths.filter((_, i) => checks[i]);
+};
+//#endregion
+//#region src/services/register-agent.ts
+var registerAgentEager = async (ctx, input) => {
+	const slug = input.slug ?? input.name;
+	let agent;
+	let created = false;
+	try {
+		agent = await getAgentByOwnerAndSlug(ctx, input.organizationSlug, slug);
+	} catch (err) {
+		if (!(isStackboneCliError(err) && err.code === "not_found")) throw err;
+		agent = await createAgent(ctx, {
+			organizationSlug: input.organizationSlug,
+			name: input.name,
+			slug,
+			...input.description !== void 0 ? { description: input.description } : {}
+		});
+		created = true;
+	}
+	const localDev = await upsertLocalDevInstallation(ctx, {
+		creatorOrganizationSlug: input.organizationSlug,
+		agentTemplateSlug: agent.slug
+	});
+	return {
+		agent,
+		localDev,
+		created
+	};
+};
+//#endregion
+//#region src/commands/dev/link-on-demand.ts
+/** Sentinel for the "none of these" row in the agent picker. */
+var CREATE_NEW = "\0create-new";
+/**
+* A control-plane slug from a folder name: lowercase, non-alphanumerics folded
+* to single dashes, no leading or trailing dash. A folder called `Astex Email
+* Agent` should not fail the create call for a reason nobody typed.
+*/
+var slugifyProjectName = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+var promptForAgentInteractively = async (agents) => {
+	if (agents.length === 0) return null;
+	const value = await select({
+		message: "This project is not linked to an agent yet. Which one is it?",
+		options: [...agents.map((a) => ({
+			value: a.slug,
+			label: a.name,
+			hint: a.slug
+		})), {
+			value: CREATE_NEW,
+			label: "Create a new agent",
+			hint: "registers one for this project"
+		}]
+	});
+	if (isCancel(value)) throw new StackboneCliError({
+		code: "no_project",
+		message: "No agent selected, so this directory is still unlinked.",
+		suggestion: "Run `stackbone dev` again and pick an agent, or create one in Studio."
+	});
+	return value === CREATE_NEW ? null : String(value);
+};
+var promptForNewNameInteractively = async (suggested) => {
+	const value = await text$1({
+		message: "Name for the new agent",
+		initialValue: suggested,
+		validate: (v) => slugifyProjectName(v ?? "").length === 0 ? "Pick a name with letters or numbers in it." : void 0
+	});
+	if (isCancel(value)) throw new StackboneCliError({
+		code: "no_project",
+		message: "No name given, so no agent was created.",
+		suggestion: "Run `stackbone dev` again to pick or create one."
+	});
+	return String(value);
+};
+/**
+* The message a non-interactive run gets. Kept apart from the interactive path
+* because it is the one a CI log will carry, and the old text sent the reader to
+* two commands that both do the wrong thing here.
+*/
+var unlinkedProjectError = () => new StackboneCliError({
+	code: "no_project",
+	message: "No project linked in this directory, and nothing here can ask which agent it is.",
+	suggestion: "Run `stackbone dev` in a terminal to pick an agent, or write .stackbone/project.json yourself (`stackbone agents get <slug>` prints the id). `stackbone init` scaffolds a NEW project over this one — not what you want for a project you were handed."
+});
+/**
+* Link this directory to an agent, asking which one, and return the config the
+* boot needs. Throws {@link unlinkedProjectError} when nobody can be asked.
+*/
+var linkProjectOnDemand = async (ctx, projectRoot, deps = {}) => {
+	if (!canPromptInteractively(ctx)) throw unlinkedProjectError();
+	const list = deps.listAgents ?? listAgents;
+	const activeOrg = deps.getActiveOrganization ?? getActiveOrganization;
+	const register = deps.registerAgentEager ?? registerAgentEager;
+	const askAgent = deps.promptForAgent ?? promptForAgentInteractively;
+	const askName = deps.promptForNewName ?? promptForNewNameInteractively;
+	const org = await activeOrg(ctx);
+	const name = await askAgent((await list(ctx)).map((a) => ({
+		slug: a.slug,
+		name: a.name ?? a.slug
+	}))) ?? slugifyProjectName(await askName(basename(projectRoot)));
+	if (name.length === 0) throw new StackboneCliError({
+		code: "generic",
+		message: "That name has no letters or numbers in it, so it cannot become an agent slug.",
+		suggestion: "Run `stackbone dev` again and give the agent a name."
+	});
+	const registration = await register(ctx, {
+		organizationSlug: org.slug,
+		name
+	});
+	const config = await writeProjectConfig(ctx, registration.agent, {
+		root: projectRoot,
+		force: false
+	}, {
+		localDevInstallationId: registration.localDev.id,
+		organizationSlug: registration.localDev.organizationSlug,
+		agentSlug: registration.localDev.agentSlug
+	});
+	await ensureGitignore(projectRoot);
+	log.success(registration.created ? `Registered agent "${registration.agent.slug}" and linked this directory to it.` : `Linked this directory to agent "${registration.agent.slug}".`);
+	return config;
+};
+//#endregion
 //#region src/commands/dev/print-contract.ts
 var defaultWriteStdout = (chunk) => {
 	process.stdout.write(chunk);
@@ -53766,12 +53935,7 @@ var createReloadRenderer = () => {
 	};
 };
 var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
-	const config = await innerCtx.projectConfig.read();
-	if (!config) throw new StackboneCliError({
-		code: "no_project",
-		message: "No project linked in this directory",
-		suggestion: "Run `stackbone init` or `stackbone link` first"
-	});
+	const config = await innerCtx.projectConfig.read() ?? await linkProjectOnDemand(innerCtx, resolve(innerCtx.cwd));
 	if (!innerCtx.flags.json) intro(formatBrandHeader({
 		version: STACKBONE_CLI_BUILD_VERSION,
 		command: "dev",
@@ -54785,6 +54949,18 @@ it. The emulator API listens on \`http://127.0.0.1:4242\` by default. The tunnel
 mandatory: it fills the \`local_tunnel_url\` field on the \`installation\` row and
 yields the Studio deeplink.
 
+**A project that was handed to you links itself here.** \`.stackbone/\` is
+gitignored, so a project cloned from someone else's repository arrives with no
+link. \`dev\` lists the agents your organization owns, lets you pick one or create
+a new one named after the folder, writes \`.stackbone/project.json\` and carries on
+booting. Neither of the alternatives fits this case: \`stackbone init\` registers a
+_new_ agent and scaffolds its own \`package.json\` over the project you just
+received, and \`stackbone link\` is for registering a box you already deployed, so
+it requires its URL, HMAC secret and image tag.
+
+Non-interactive runs (\`--json\`, \`--yes\`, CI, no terminal) still fail rather than
+guessing, and say what to do instead.
+
 The project is a **workspace**: every \`deep-agents/<name>/index.ts\`, plus
 every \`workflows/<name>.workflow.ts\`, discovered by convention (with an
 explicit \`stackbone.config.ts\` override for workflows). Boot:
@@ -56446,10 +56622,12 @@ them.
   the CLI must run from WSL2, Docker Desktop with WSL2 integration enabled
   (or Docker Engine inside the Ubuntu distro) covers it.
 - **A project:** run \`stackbone init\` to scaffold a workspace shell (a
-  \`deep-agents/\` folder, a \`workflows/\` folder and supporting files), or
-  \`stackbone link\` to connect an existing directory. Add pieces over time with
-  \`stackbone add agent <name>\`, \`stackbone add workflow <name>\` or
-  \`stackbone add workflow-agent <name>\`.
+  \`deep-agents/\` folder, a \`workflows/\` folder and supporting files). Add
+  pieces over time with \`stackbone add agent <name>\`,
+  \`stackbone add workflow <name>\` or \`stackbone add workflow-agent <name>\`.
+  A project someone handed you needs none of that: it arrives unlinked, and
+  \`dev\` asks which agent it is. See
+  [A project that arrived without a link](#a-project-that-arrived-without-a-link).
 - **At least one agent or workflow:** \`stackbone dev\` discovers your workspace
   by convention, any \`deep-agents/<name>/index.ts\` (or a
   \`workflows/<name>.workflow.ts\`) is enough to activate the runtime. A
@@ -56461,6 +56639,27 @@ them.
   \`STACKBONE_FRPC_BIN\` to point at a system install when your environment
   forbids untrusted binaries.
 
+## A project that arrived without a link
+
+A project you cloned from someone else's repository has no link to an agent.
+\`.stackbone/\` is gitignored, so the link never travels with the code.
+
+\`stackbone dev\` does not stop for that. It lists the agents your organization
+owns, lets you pick one or create a new one named after the folder, writes
+\`.stackbone/project.json\`, adds it to \`.gitignore\` and carries on booting.
+
+Neither of the other commands fits this case:
+
+- \`stackbone init\` registers a **new** agent and writes its own \`package.json\`,
+  \`tsconfig.json\` and scaffold over the project you were just handed.
+- \`stackbone link\` registers a box you have already deployed, so it requires
+  that box's URL, HMAC secret and image tag.
+
+A run that cannot ask fails instead of guessing, and says what to do instead.
+That covers any run without a terminal, a \`CI\` environment variable, \`--yes\` or
+\`--json\`. See
+[This directory is not linked to an agent](/docs/cli/troubleshooting#this-directory-is-not-linked-to-an-agent).
+
 ## Synopsis
 
 \`\`\`sh
@@ -57118,6 +57317,26 @@ Stages you do not use are skipped: no workflows means no \`workflows\` or
 
 ## \`stackbone dev\` failures
 
+### This directory is not linked to an agent
+
+**Symptom:** \`stackbone dev\` exits before any stage runs with \`no_project\` and
+"No project linked in this directory, and nothing here can ask which agent it
+is."
+
+**Cause:** the project has no \`.stackbone/project.json\` and this run cannot
+prompt for one. \`.stackbone/\` is gitignored, so a project cloned from someone
+else's repository always arrives unlinked, and a run without a terminal (or one
+with a \`CI\` environment variable, \`--yes\` or \`--json\`) has nobody to ask.
+
+**Fix:** run \`stackbone dev\` once from a terminal and pick the agent. It writes
+the link, and every later run reuses it, scripted or not. To link without a
+prompt, write \`.stackbone/project.json\` yourself; \`stackbone agents get <slug>\`
+prints the agent id it needs.
+
+Reaching for \`stackbone init\` here is the common mistake: it registers a new
+agent and scaffolds over the project you were handed. Full contract:
+[A project that arrived without a link](/docs/cli/local-development#a-project-that-arrived-without-a-link).
+
 ### Docker not running, or the datastore is unhealthy
 
 **Symptom:** the \`docker\` stage fails, or \`platform-migrations\` /
@@ -62648,84 +62867,6 @@ var createHitlCommand = defineGroup({
 	}
 });
 //#endregion
-//#region src/services/register-agent.ts
-var registerAgentEager = async (ctx, input) => {
-	const slug = input.slug ?? input.name;
-	let agent;
-	let created = false;
-	try {
-		agent = await getAgentByOwnerAndSlug(ctx, input.organizationSlug, slug);
-	} catch (err) {
-		if (!(isStackboneCliError(err) && err.code === "not_found")) throw err;
-		agent = await createAgent(ctx, {
-			organizationSlug: input.organizationSlug,
-			name: input.name,
-			slug,
-			...input.description !== void 0 ? { description: input.description } : {}
-		});
-		created = true;
-	}
-	const localDev = await upsertLocalDevInstallation(ctx, {
-		creatorOrganizationSlug: input.organizationSlug,
-		agentTemplateSlug: agent.slug
-	});
-	return {
-		agent,
-		localDev,
-		created
-	};
-};
-//#endregion
-//#region src/services/project.service.ts
-var GITIGNORE_MARKER_BEGIN$1 = "# >>> stackbone >>>";
-var GITIGNORE_BLOCK = [
-	GITIGNORE_MARKER_BEGIN$1,
-	".stackbone/",
-	"node_modules/",
-	"dist/",
-	"# <<< stackbone <<<",
-	""
-].join("\n");
-var exists = async (path) => {
-	try {
-		await stat(path);
-		return true;
-	} catch (err) {
-		if (isENOENT(err)) return false;
-		throw err;
-	}
-};
-var writeProjectConfig = async (ctx, agent, input, extras = {}) => {
-	const config = {
-		schemaVersion: 1,
-		organizationId: agent.organizationId,
-		agentId: agent.id,
-		controlPlaneUrl: ctx.apiUrl,
-		...extras.localDevInstallationId !== void 0 ? { localDevInstallationId: extras.localDevInstallationId } : {},
-		...extras.organizationSlug !== void 0 ? { organizationSlug: extras.organizationSlug } : {},
-		...extras.agentSlug !== void 0 ? { agentSlug: extras.agentSlug } : {},
-		...extras.starter !== void 0 ? { starter: extras.starter } : {}
-	};
-	await mkdir(join(input.root, ".stackbone"), { recursive: true });
-	await writeFile(join(input.root, ".stackbone", "project.json"), JSON.stringify(config, null, 2));
-	return config;
-};
-var ensureGitignore = async (root) => {
-	const path = join(root, ".gitignore");
-	let current = "";
-	try {
-		current = await readFile(path, "utf8");
-	} catch (err) {
-		if (!isENOENT(err)) throw err;
-	}
-	if (current.includes(GITIGNORE_MARKER_BEGIN$1)) return;
-	await writeFile(path, current.length > 0 && !current.endsWith("\n") ? `${current}\n${GITIGNORE_BLOCK}` : `${current}${GITIGNORE_BLOCK}`);
-};
-var detectExistingProjectFiles = async (root, paths) => {
-	const checks = await Promise.all(paths.map((p) => exists(join(root, p))));
-	return paths.filter((_, i) => checks[i]);
-};
-//#endregion
 //#region src/services/skills.service.ts
 var execFileAsync = promisify(execFile);
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {