@ponderbot/cli 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -90,6 +90,45 @@ uses `@ponderbot/sdk` for authoring and local loading. The CLI bundles the SDK
 Worker Entry into the artifact. A project can set `worker.build.dockerfile` when
 it needs a custom system image or install process.
 
+## Environment selection
+
+Every command resolves one Project environment from `ponderbot/config.ts`. The
+CLI selects the environment in this order:
+
+1. `--env <name>` on the command.
+2. A non-empty `PONDERBOT_ENV` in the process environment.
+3. The `development` environment.
+
+A named environment (`--env` or `PONDERBOT_ENV`) is the source of truth:
+
+- The URL comes from the environment `url`. `PONDERBOT_URL` does not change
+  it.
+- The token comes from the environment `tokenEnv` variable. `PONDERBOT_TOKEN`
+  is only a fallback when that variable is not set.
+- The Space comes from `--space` or the environment `spaceId`. A named
+  environment never reads `PONDERBOT_SPACE_ID`. Space-scoped commands exit 2
+  when neither `--space` nor `spaceId` is set. `spaces list` and
+  `spaces create` do not need a Space.
+
+The default `development` environment keeps the `ponder start` contract:
+`PONDERBOT_URL`, `PONDERBOT_SPACE_ID`, and `PONDERBOT_TOKEN` override the
+environment values when they are set. `--space` still wins over both.
+
+Example with a `.env` file that `ponder start` printed:
+
+```sh
+export PONDERBOT_URL=http://127.0.0.1:4000
+export PONDERBOT_TOKEN_PRODUCTION=prod-token
+ponder spaces list --env production
+```
+
+The command lists the Spaces of the `production` URL with `prod-token`. The
+local `PONDERBOT_URL` does not change the target.
+
+Mutating commands, such as `manifest deploy`, `spaces create`, and
+`action run`, print the resolved target. Human output starts with `environment`
+and `base URL` lines. JSON output adds the `environment` and `base_url` keys.
+
 Useful space commands:
 
 ```sh

package/dist/main.js

@@ -31,6 +31,7 @@ const resolveProject = async () => {
 };
 const resolveConfig = async (envName, spaceId) => requireExecutionSpace(await resolveEnvironmentConfig(envName), spaceId);
 const resolveProjectReleaseConfig = async (envName) => resolveEnvironmentConfig(envName, { resolveApplicationOrigin: true });
+const resolveRuntimeConfig = async (envName) => resolveEnvironmentConfig(envName);
 const resolveDevConfig = async (envName) => requireExecutionSpace(await resolveEnvironmentConfig(envName ?? "development", {
 	requireDevAllowed: true,
 	resolveApplicationOrigin: true,
@@ -72,7 +73,7 @@ const resolveEnvironmentConfig = async (envName, options = {}) => {
 };
 const requireExecutionSpace = (config, spaceId) => {
 	const resolvedSpaceId = spaceId !== void 0 && spaceId.length > 0 ? spaceId : config.spaceId;
-	if (resolvedSpaceId === void 0 || resolvedSpaceId.length === 0) return exitConfig(`set the execution Space with --space, PONDERBOT_SPACE_ID, or spaceId for environment "${config.environment}" in ponderbot/config.ts`);
+	if (resolvedSpaceId === void 0 || resolvedSpaceId.length === 0) return exitConfig(`set the execution Space with --space or spaceId for environment "${config.environment}" in ponderbot/config.ts`);
 	return {
 		...config,
 		spaceId: resolvedSpaceId
@@ -90,17 +91,23 @@ const clientFor = (config) => createClient({
 	token: config.token,
 	spaceId: config.spaceId
 });
+const withResolvedTarget = (config, result) => ({
+	...result,
+	environment: config.environment,
+	base_url: config.url
+});
 //#endregion
 //#region src/deployment-environment.ts
 const INERT_SOURCE_SETTINGS = {
 	allow_schedules: false,
+	allow_persistent_development_schedules: false,
 	allow_webhooks: false,
 	allow_manual_triggers: false
 };
 const reconcileDeploymentEnvironment = async (client, config) => {
 	if (config.environmentRole === "release-source") {
 		const { settings } = await client.spaces.settings.update(INERT_SOURCE_SETTINGS);
-		if (settings.allow_schedules !== false || settings.allow_webhooks !== false || settings.allow_manual_triggers !== false) throw new Error("release-source Space settings did not become execution-inert");
+		if (settings.allow_schedules !== false || settings.allow_persistent_development_schedules !== false || settings.allow_webhooks !== false || settings.allow_manual_triggers !== false) throw new Error("release-source Space settings did not become execution-inert");
 	}
 };
 //#endregion
@@ -349,6 +356,14 @@ const formatError = (error) => {
 	return String(error);
 };
 const lines = (data) => {
+	if (isRecord$1(data) && typeof data.environment === "string" && typeof data.base_url === "string") {
+		const { environment, base_url: baseUrl, ...result } = data;
+		return [
+			`environment ${environment}`,
+			`base URL ${baseUrl}`,
+			...lines(result)
+		];
+	}
 	if (isRecord$1(data) && isRecord$1(data.release) && isRecord$1(data.resources)) return releaseCatalogLines(data.release, data.resources);
 	if (isStartedDevStack(data)) return [
 		"Ponderbot dev stack ready.",
@@ -1780,7 +1795,7 @@ const providerAuth = async (options) => {
 		}
 		if (options.allSpaces === true) await client.providerBindings.authorize(binding.id, { allSpaces: true });
 		else await client.providerBindings.authorize(binding.id, { spaceIds: sharedSpaceIds });
-		return providerAuthResult(provider, method, spaceId, {
+		return providerAuthResult(provider, method, spaceId, config.environment, config.url, {
 			bindingId: binding.id,
 			allSpaces: options.allSpaces === true,
 			spaceIds: options.allSpaces === true ? void 0 : sharedSpaceIds
@@ -1792,16 +1807,16 @@ const providerAuth = async (options) => {
 			provider,
 			apiKey
 		});
-		return providerAuthResult(provider, method, spaceId);
+		return providerAuthResult(provider, method, spaceId, config.environment, config.url);
 	}
 	if (!canPrompt()) throw new Error("OAuth login needs an interactive terminal. Run locally with a browser, or rerun with --no-browser to paste the callback URL.");
 	await authorizeOAuthLogin(() => client.modelProviders.startOAuthLogin(spaceId, provider), (authorizationResponse, state) => client.modelProviders.completeOAuthLogin(spaceId, provider, {
 		authorizationResponse,
 		state
 	}), options.browser !== false);
-	return providerAuthResult(provider, method, spaceId);
+	return providerAuthResult(provider, method, spaceId, config.environment, config.url);
 };
-const providerAuthResult = (provider, method, spaceId, shared) => ({
+const providerAuthResult = (provider, method, spaceId, environment, baseUrl, shared) => ({
 	type: "provider_auth",
 	status: "saved",
 	provider,
@@ -1810,7 +1825,9 @@ const providerAuthResult = (provider, method, spaceId, shared) => ({
 	binding_id: shared?.bindingId,
 	all_spaces: shared?.allSpaces,
 	space_ids: shared?.spaceIds,
-	smoke_test: "ponder spaces show"
+	smoke_test: "ponder spaces show",
+	environment,
+	base_url: baseUrl
 });
 const resolveProvider = async (value, entries) => {
 	const providers = entries.map((entry) => entry.id);
@@ -2361,10 +2378,10 @@ manifest.command("deploy").option("--env <name>", "environment").option("--image
 		});
 		printManifestDiagnostics(plan.instructionBudgets, plan.warnings);
 		const release = await client.projects.releases.deploy(config.projectDefinition.name, config.environment, plan.manifest, config.sourceName, void 0, config.applicationOrigin);
-		print(versionBump === void 0 ? release : {
+		print(withResolvedTarget(config, versionBump === void 0 ? release : {
 			...release,
 			version_bump: versionBump
-		}, program.opts());
+		}), program.opts());
 	} catch (error) {
 		fail(error, error instanceof WorkerImageError ? 2 : 1);
 	}
@@ -2378,19 +2395,19 @@ manifest.command("dev").option("--env <name>", "environment").description("watch
 });
 const spaces = program.command("spaces").description("manage runtime spaces");
 spaces.command("list").option("--env <name>", "environment").description("list spaces").action(async (options) => {
-	const config = await resolveConfig(options.env);
+	const config = await resolveRuntimeConfig(options.env);
 	await runSpacesCommand("spaces:read", "*", async () => {
 		print({ spaces: await listSpaces(clientFor(config)) }, program.opts());
 	});
 });
 spaces.command("create <spaceId>").option("--name <name>", "space name").option("--env <name>", "environment").description("create a space").action(async (spaceId, options) => {
-	const config = await resolveConfig(options.env);
+	const config = await resolveRuntimeConfig(options.env);
 	await runSpacesCommand("spaces:write", "*", async () => {
 		try {
-			print(await clientFor(config).spaces.create({
+			print(withResolvedTarget(config, await clientFor(config).spaces.create({
 				id: spaceId,
 				name: options.name ?? spaceId
-			}), program.opts());
+			})), program.opts());
 		} catch (error) {
 			throw spaceCreateError(error, spaceId);
 		}
@@ -2422,7 +2439,7 @@ spaces.command("budget [spaceId]").option("--set <file>", "replace budget from a
 			print(await client.spaces.budget.get(resolvedSpaceId), program.opts());
 			return;
 		}
-		print(await client.spaces.budget.set(await readJsonFile(options.set), resolvedSpaceId), program.opts());
+		print(withResolvedTarget(config, await client.spaces.budget.set(await readJsonFile(options.set), resolvedSpaceId)), program.opts());
 	});
 });
 program.command("provider").description("configure model provider credentials").command("auth").description("authenticate a model provider for a space").option("--env <name>", "environment").option("--space <spaceId>", "target space (defaults to the configured space)").option("--provider <name>", "anthropic | mistral | openai (skips the picker)").option("--method <method>", "api-key | oauth").option("--shared", "store one Runtime credential binding instead of a Space credential").option("--all-spaces", "authorize the shared binding for every Space").option("--spaces <spaceIds...>", "authorize the shared binding for selected Spaces").option("--no-browser", "print the Codex authorize URL and paste the callback URL").action(async (options) => {
@@ -2432,7 +2449,7 @@ const model = program.command("model").description("manage Space model policy");
 model.command("add <modelRef>").requiredOption("--provider <name>", "anthropic | fake | mistral | openai").requiredOption("--model <name>", "provider model name").option("--capability <name...>", "declared model capabilities").option("--fallback <modelRef...>", "ordered fallback model refs").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").description("add or update a model in the Space catalog").action(async (modelRef, options) => {
 	const config = await resolveConfig(options.env, options.space);
 	await runSpacesCommand("spaces:write", config.spaceId, async () => {
-		print(await clientFor(config).models.upsert(modelRef, modelDefinitionInput(options)), program.opts());
+		print(withResolvedTarget(config, await clientFor(config).models.upsert(modelRef, modelDefinitionInput(options))), program.opts());
 	});
 });
 model.command("list").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").description("list models in the Space catalog").action(async (options) => {
@@ -2444,7 +2461,7 @@ model.command("list").option("--space <spaceId>", "target space (defaults to the
 model.command("assign <agentRef> <modelRef>").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").description("assign a Space catalog model to an exact Agent ref").action(async (agentRef, modelRef, options) => {
 	const config = await resolveConfig(options.env, options.space);
 	await runSpacesCommand("spaces:write", config.spaceId, async () => {
-		print(await clientFor(config).models.assign(agentRef, modelRef), program.opts());
+		print(withResolvedTarget(config, await clientFor(config).models.assign(agentRef, modelRef)), program.opts());
 	});
 });
 model.command("assignments").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").description("list exact Agent model assignments for a Space").action(async (options) => {
@@ -2463,7 +2480,8 @@ releases.command("catalog [releaseId]").option("--space <spaceId>", "target spac
 	print(await client.releases.catalog(resolvedReleaseId), program.opts());
 });
 program.command("rollback <releaseId>").option("--env <name>", "environment").description("roll back to a release").action(async (releaseId, options) => {
-	print(await clientFor(await resolveConfig(options.env)).releases.rollback(releaseId), program.opts());
+	const config = await resolveConfig(options.env);
+	print(withResolvedTarget(config, await clientFor(config).releases.rollback(releaseId)), program.opts());
 });
 program.command("runs").option("--type <type>", "run type").option("--status <status>", "run status").option("--env <name>", "environment").description("list runs").action(async (options) => {
 	print(await clientFor(await resolveConfig(options.env)).runs.list(Object.fromEntries([["type", options.type], ["status", options.status]].filter((entry) => typeof entry[1] === "string"))), program.opts());
@@ -2475,19 +2493,22 @@ program.command("run <type> <id>").option("--export", "export run bundle").optio
 });
 program.command("cancel <type> <id>").option("--env <name>", "environment").description("cancel a run").action(async (type, id, options) => {
 	const runType = parseRunType(type);
-	print(await clientFor(await resolveConfig(options.env)).runs.cancel(runType, id), program.opts());
+	const config = await resolveConfig(options.env);
+	print(withResolvedTarget(config, await clientFor(config).runs.cancel(runType, id)), program.opts());
 });
 program.command("action").command("run <ref>").option("--input <json>", "input payload", "{}").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").option("--release-id <id>", "pinned release id").option("--manifest-name <name>", "current release selector").description("start an Action Run").action(async (ref, options) => {
-	print(await clientFor(await resolveConfig(options.env, options.space)).actions.run(ref, JSON.parse(options.input), {
+	const config = await resolveConfig(options.env, options.space);
+	print(withResolvedTarget(config, await clientFor(config).actions.run(ref, JSON.parse(options.input), {
 		releaseId: options.releaseId,
 		manifestName: options.manifestName
-	}), program.opts());
+	})), program.opts());
 });
 program.command("workflow").command("trigger <ref>").option("--input <json>", "input payload", "{}").option("--space <spaceId>", "target space (defaults to the configured space)").option("--env <name>", "environment").option("--release-id <id>", "pinned release id").option("--manifest-name <name>", "current release selector").description("start a Workflow Run").action(async (ref, options) => {
-	print(await clientFor(await resolveConfig(options.env, options.space)).workflows.trigger(ref, JSON.parse(options.input), {
+	const config = await resolveConfig(options.env, options.space);
+	print(withResolvedTarget(config, await clientFor(config).workflows.trigger(ref, JSON.parse(options.input), {
 		releaseId: options.releaseId,
 		manifestName: options.manifestName
-	}), program.opts());
+	})), program.opts());
 });
 program.command("decisions").option("--env <name>", "environment").option("--actionable", "only generations this actor could answer").description("list pending decisions").action(async (options) => {
 	print(await clientFor(await resolveConfig(options.env)).decisions.list({
@@ -2496,10 +2517,12 @@ program.command("decisions").option("--env <name>", "environment").option("--act
 	}), program.opts());
 });
 program.command("approve <id>").option("--env <name>", "environment").option("--reason <reason>", "bounded reason recorded on the response").description("approve a decision").action(async (id, options) => {
-	print(await clientFor(await resolveConfig(options.env)).decisions.approve(id, { ...options.reason === void 0 ? {} : { reason: options.reason } }), program.opts());
+	const config = await resolveConfig(options.env);
+	print(withResolvedTarget(config, await clientFor(config).decisions.approve(id, { ...options.reason === void 0 ? {} : { reason: options.reason } })), program.opts());
 });
 program.command("reject <id>").option("--env <name>", "environment").option("--reason <reason>", "bounded reason recorded on the response").description("reject a decision").action(async (id, options) => {
-	print(await clientFor(await resolveConfig(options.env)).decisions.reject(id, { ...options.reason === void 0 ? {} : { reason: options.reason } }), program.opts());
+	const config = await resolveConfig(options.env);
+	print(withResolvedTarget(config, await clientFor(config).decisions.reject(id, { ...options.reason === void 0 ? {} : { reason: options.reason } })), program.opts());
 });
 program.command("events").option("--follow", "follow runtime events").option("--env <name>", "environment").description("show recent events or follow the event stream").action(async (options) => {
 	const client = clientFor(await resolveConfig(options.env));