@keystrokehq/cli 0.0.132 → 0.0.133

package/dist/index.mjs

@@ -1852,6 +1852,8 @@ const OrganizationSlugSchema = string().trim().toLowerCase().min(2, "Slug must b
 * fail to load.
 */
 const ClaimableOrganizationSlugSchema = OrganizationSlugSchema.refine((slug) => !RESERVED_ORGANIZATION_SLUGS.has(slug), "This slug is reserved");
+/** Same format as organization slugs — org-scoped, no global reserved list. */
+const ProjectSlugSchema = OrganizationSlugSchema;
 /** Browser→platform request budget (ping + small platform overhead). */
 const PROJECT_REACHABILITY_REQUEST_TIMEOUT_MS = 17e3;
 /** Normalize a public origin URL (no trailing slash). */
@@ -2053,6 +2055,17 @@ object({
 	slug: string().trim().min(1),
 	excludeOrganizationId: string().min(1).optional()
 });
+const ProjectSlugAvailabilityReasonSchema = _enum(["taken", "invalid"]);
+const ProjectSlugAvailabilityResponseSchema = object({
+	slug: string(),
+	available: boolean(),
+	reason: ProjectSlugAvailabilityReasonSchema.optional(),
+	suggestion: ProjectSlugSchema.optional()
+});
+object({
+	slug: string().trim().min(1),
+	excludeProjectId: string().min(1).optional()
+});
 const ProjectStatusSchema = _enum([
 	"inactive",
 	"starting",
@@ -2076,6 +2089,7 @@ const ProjectSchema = object({
 	id: string(),
 	organizationId: string(),
 	name: string(),
+	slug: ProjectSlugSchema,
 	description: string().nullable(),
 	status: ProjectStatusSchema,
 	baseUrl: string().nullable(),
@@ -2116,8 +2130,9 @@ const CreateProjectRequestSchema = object({
 });
 const UpdateProjectRequestSchema = object({
 	name: string().trim().min(1).optional(),
-	description: string().trim().optional()
-}).refine((data) => data.name !== void 0 || data.description !== void 0, { message: "At least one field is required" });
+	description: string().trim().optional(),
+	slug: ProjectSlugSchema.optional()
+}).refine((data) => data.name !== void 0 || data.description !== void 0 || data.slug !== void 0, { message: "At least one field is required" });
 const CreateProjectResponseSchema = object({ project: ProjectSchema });
 const ProjectResponseSchema = object({ project: ProjectSchema });
 const ProjectReachabilityResponseSchema = object({ reachable: boolean() });
@@ -5174,6 +5189,16 @@ function createProjectsResource(http) {
 			} catch (error) {
 				throw await toPlatformError(error);
 			}
+		},
+		async checkSlug(slug, options = {}) {
+			const searchParams = new URLSearchParams({ slug });
+			if (options.excludeProjectId) searchParams.set("excludeProjectId", options.excludeProjectId);
+			try {
+				const data = await http.get(`/api/projects/slug-available?${searchParams}`).json();
+				return ProjectSlugAvailabilityResponseSchema.parse(data);
+			} catch (error) {
+				throw await toPlatformError(error);
+			}
 		}
 	};
 }
@@ -8587,6 +8612,33 @@ function createCliPlatformClient(config) {
 	});
 }
 //#endregion
+//#region src/resolve-resource-ref.ts
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function looksLikeUuid(value) {
+	return UUID_PATTERN.test(value);
+}
+function formatProjectLabel(project) {
+	return project.slug;
+}
+async function resolveProjectRef(platform, ref) {
+	if (looksLikeUuid(ref)) try {
+		return await platform.projects.get(ref);
+	} catch (error) {
+		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${ref} not found in the active organization. Run \`keystroke project list\`, then \`keystroke config use project <slug>\`.`);
+		throw error;
+	}
+	const match = (await platform.projects.list()).find((project) => project.slug === ref);
+	if (!match) throw new Error(`Project "${ref}" not found in the active organization. Run \`keystroke project list\`.`);
+	return match;
+}
+function resolveOrganizationRef(organizations, ref) {
+	const byId = organizations.find((entry) => entry.organization.id === ref);
+	if (byId) return byId;
+	const bySlug = organizations.find((entry) => entry.organization.slug === ref);
+	if (bySlug) return bySlug;
+	throw new Error(`Organization "${ref}" was not found or you do not have access`);
+}
+//#endregion
 //#region src/organization/active-organization.ts
 function formatOrganization(membership) {
 	return `${membership.organization.name} (${membership.role})`;
@@ -8600,15 +8652,11 @@ async function activateOrganization(config, organizationId) {
 	platform.setActiveOrganizationId(membership.organization.id);
 	return membership;
 }
-async function pickOrganization(config, organizations, organizationId) {
-	if (organizationId) {
-		const membership = organizations.find((entry) => entry.organization.id === organizationId);
-		if (!membership) throw new Error(`Organization ${organizationId} was not found or you do not have access`);
-		return activateOrganization(config, membership.organization.id);
-	}
+async function pickOrganization(config, organizations, organizationRef) {
+	if (organizationRef) return activateOrganization(config, resolveOrganizationRef(organizations, organizationRef).organization.id);
 	if (!process.stdin.isTTY) {
-		const names = organizations.map((entry) => entry.organization.id).join(", ");
-		throw new Error(`Multiple organizations found. Run \`keystroke config use org <id>\`. Options: ${names}`);
+		const names = organizations.map((entry) => entry.organization.slug).join(", ");
+		throw new Error(`Multiple organizations found. Run \`keystroke config use org <slug>\`. Options: ${names}`);
 	}
 	return activateOrganization(config, await select({
 		message: "Select an organization",
@@ -8622,7 +8670,7 @@ async function selectActiveOrganization(config, options = {}) {
 	const organizations = await listOrganizations(config);
 	if (organizations.length === 0) throw new Error(`No organization found — create one at ${getWebUrl(config)}`);
 	if (organizations.length === 1) return activateOrganization(config, organizations[0].organization.id);
-	return pickOrganization(config, organizations, options.organizationId);
+	return pickOrganization(config, organizations, options.organizationRef ?? options.organizationId);
 }
 async function syncActiveOrganizationAfterLogin(config, options = {}) {
 	const organizations = await listOrganizations(config);
@@ -8638,8 +8686,8 @@ async function syncActiveOrganizationAfterLogin(config, options = {}) {
 		process.stdout.write(`Using organization ${membership.organization.name}\n`);
 		return membership;
 	}
-	if (options.organizationId) {
-		const membership = await pickOrganization(config, organizations, options.organizationId);
+	if (options.organizationRef ?? options.organizationId) {
+		const membership = await pickOrganization(config, organizations, options.organizationRef ?? options.organizationId);
 		process.stdout.write(`Using organization ${membership.organization.name}\n`);
 		return membership;
 	}
@@ -8712,19 +8760,19 @@ function resolveOrgPlatformTarget(config) {
 		mode: "platform"
 	};
 }
-async function resolvePlatformTarget(config, projectId) {
+async function resolvePlatformTarget(config, projectRef) {
 	const platform = createCliPlatformClient(config);
 	let project;
 	try {
-		project = await platform.projects.get(projectId);
+		project = await resolveProjectRef(platform, projectRef);
 	} catch (error) {
-		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${projectId} not found in the active organization. Run \`keystroke config use project <id>\` or pass \`--project\` with a valid project id.`);
+		if (error instanceof Error) throw error;
 		throw error;
 	}
-	if (project.status !== "active") throw new Error(`Project ${projectId} is not active (${project.status})`);
+	if (project.status !== "active") throw new Error(`Project ${formatProjectLabel(project)} is not active (${project.status})`);
 	return {
-		baseUrl: `${getPlatformUrl(config).replace(/\/+$/, "")}/api/projects/${encodeURIComponent(projectId)}`,
-		projectId,
+		baseUrl: `${getPlatformUrl(config).replace(/\/+$/, "")}/api/projects/${encodeURIComponent(project.id)}`,
+		projectId: project.id,
 		mode: "platform"
 	};
 }
@@ -8742,9 +8790,9 @@ async function resolveApiTarget(config, options = {}) {
 	if (options.projectId) return resolvePlatformTarget(config, options.projectId);
 	if (getEffectiveApiTarget(config) === "local") return resolveLocalTarget(config);
 	if (!options.projectScoped) return resolveOrgPlatformTarget(config);
-	const projectId = options.projectId ?? config.get("activeProjectId");
-	if (!projectId) throw new Error("No project selected. Pass `--project <id>` or run `keystroke config use project <id>`.");
-	return resolvePlatformTarget(config, projectId);
+	const projectRef = options.projectId ?? config.get("activeProjectId");
+	if (!projectRef) throw new Error("No project selected. Pass `--project <slug>` or run `keystroke config use project <slug>`.");
+	return resolvePlatformTarget(config, projectRef);
 }
 //#endregion
 //#region src/target-options.ts
@@ -8755,9 +8803,6 @@ function setCliTargetOptions(options) {
 function getCliTargetOptions() {
 	return targetOptions;
 }
-function resolveActiveProjectId(config) {
-	return getCliTargetOptions().projectId ?? config.get("activeProjectId");
-}
 //#endregion
 //#region src/errors/example-input.ts
 function exampleValueFromValidationMessage(message) {
@@ -9232,7 +9277,7 @@ function resolveAuthLoginTargets(options, config) {
 //#endregion
 //#region src/commands/auth/login.ts
 function registerAuthLoginCommand(auth) {
-	auth.command("login").description("Authenticate via browser device flow").option("--web-url <url>", "Web dashboard origin (omit to use production defaults; local dev: http://localhost:3000)").option("--platform-url <url>", "Platform API origin (derived from web URL when omitted)").option("--org <id>", "Active organization id (skips prompt when you belong to several)").action(async (options) => {
+	auth.command("login").description("Authenticate via browser device flow").option("--web-url <url>", "Web dashboard origin (omit to use production defaults; local dev: http://localhost:3000)").option("--platform-url <url>", "Platform API origin (derived from web URL when omitted)").option("--org <slug>", "Active organization slug (skips prompt when you belong to several)").action(async (options) => {
 		const config = createCliConfig();
 		const { webUrl, platformUrl } = resolveAuthLoginTargets(options, config);
 		config.set("webUrl", webUrl);
@@ -9247,7 +9292,7 @@ function registerAuthLoginCommand(auth) {
 			const user = await getSessionWithBearer(platformUrl, result.accessToken);
 			if (user) process.stdout.write(`Logged in as ${user.name} (${user.email})\n`);
 			else process.stdout.write(`Logged in to ${webUrl}\n`);
-			await syncActiveOrganizationAfterLogin(config, { organizationId: options.org });
+			await syncActiveOrganizationAfterLogin(config, { organizationRef: options.org });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "Login failed", {
 				webUrl,
@@ -9467,6 +9512,18 @@ function collectProjectSource(root) {
 	};
 }
 //#endregion
+//#region src/resolve-project-target.ts
+async function resolveActiveProject(config, platform) {
+	const ref = getCliTargetOptions().projectId ?? config.get("activeProjectId");
+	if (!ref) return;
+	const client = platform ?? createCliPlatformClient(config);
+	if (!getCliTargetOptions().projectId && looksLikeUuid(ref)) return resolveProjectRef(client, ref);
+	return resolveProjectRef(client, ref);
+}
+async function resolveActiveProjectId(config) {
+	return (await resolveActiveProject(config))?.id;
+}
+//#endregion
 //#region src/commands/deploy.ts
 const POLL_INTERVAL_MS = 2e3;
 const DEPLOY_TIMEOUT_MS = 12e4;
@@ -9557,8 +9614,8 @@ async function runDeploy(options) {
 function registerDeployCommand(program) {
 	program.command("deploy").description("Build, upload, and deploy the project to the platform").option("--dir <path>", "Project directory", process.cwd()).option("--skip-build", "Upload the existing dist/ without rebuilding").action(async (options) => {
 		try {
-			const projectId = resolveActiveProjectId(createCliConfig());
-			if (!projectId) throw new Error("Usage: keystroke deploy --project <id>");
+			const projectId = await resolveActiveProjectId(createCliConfig());
+			if (!projectId) throw new Error("Usage: keystroke deploy --project <slug>");
 			await runDeploy({
 				dir: options.dir,
 				projectId,
@@ -10118,7 +10175,7 @@ function writeInactiveDeployHints(projects) {
 	const bin = cliBinaryName();
 	for (const project of projects) {
 		if (project.status !== "inactive") continue;
-		process.stderr.write(`Project ${project.id} is inactive. Deploy with: ${bin} deploy --project ${project.id}\n`);
+		process.stderr.write(`Project ${formatProjectLabel(project)} is inactive. Deploy with: ${bin} deploy --project ${formatProjectLabel(project)}\n`);
 	}
 }
 async function runProjectList(config) {
@@ -10136,13 +10193,19 @@ async function runProjectList(config) {
 async function runProjectMetrics(config, options) {
 	await withActivePlatformClient(config, async (platform) => {
 		const metrics = await platform.projectMetrics.list();
-		const output = options.projectId === void 0 ? metrics : Object.fromEntries(Object.entries(metrics).filter(([projectId]) => projectId === options.projectId));
+		if (options.projectRef === void 0) {
+			process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
+			return;
+		}
+		const project = await resolveProjectRef(platform, options.projectRef);
+		const output = Object.fromEntries(Object.entries(metrics).filter(([projectId]) => projectId === project.id));
 		process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 	});
 }
 async function runProjectDeploymentsList(config, options) {
 	await withActivePlatformClient(config, async (platform) => {
-		const deployments = await platform.deployments.listForProject(options.projectId);
+		const project = await resolveProjectRef(platform, options.projectRef);
+		const deployments = await platform.deployments.listForProject(project.id);
 		process.stdout.write(`${JSON.stringify({ deployments }, null, 2)}\n`);
 	});
 }
@@ -10206,10 +10269,10 @@ function registerProjectCommand(program) {
 			process.exitCode = 1;
 		}
 	});
-	project.command("metrics").description("List rollup metrics for projects in the active organization").option("--project <id>", "Return metrics for a single project").action(async (options) => {
+	project.command("metrics").description("List rollup metrics for projects in the active organization").option("--project <slug>", "Return metrics for a single project").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			await runProjectMetrics(config, { ...options.project ? { projectId: options.project } : {} });
+			await runProjectMetrics(config, { ...options.project ? { projectRef: options.project } : {} });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "List project metrics failed", {
 				serverUrl: getPlatformUrl(config),
@@ -10218,12 +10281,12 @@ function registerProjectCommand(program) {
 			process.exitCode = 1;
 		}
 	});
-	project.command("deployments").description("View deployment history for platform projects").command("list").description("List deployment history for a project").option("--project <id>", "Project ID").action(async (options) => {
+	project.command("deployments").description("View deployment history for platform projects").command("list").description("List deployment history for a project").option("--project <slug>", "Project slug").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = options.project ?? resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke project deployments list --project <id>");
-			await runProjectDeploymentsList(config, { projectId });
+			const projectRef = options.project ?? getCliTargetOptions().projectId ?? config.get("activeProjectId");
+			if (!projectRef) throw new Error("Usage: keystroke project deployments list --project <slug>");
+			await runProjectDeploymentsList(config, { projectRef });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "List deployments failed", {
 				serverUrl: getPlatformUrl(config),
@@ -10250,8 +10313,8 @@ function registerProjectCommand(program) {
 	project.command("update").description("Update a platform project's name and/or description").option("--name <name>", "Project name").option("--description <description>", "Project description").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke --project <id> project update --name <name>");
+			const projectId = await resolveActiveProjectId(config);
+			if (!projectId) throw new Error("Usage: keystroke --project <slug> project update --name <name>");
 			if (!options.name && options.description === void 0) throw new Error("At least one of --name or --description is required");
 			await runProjectUpdate(config, {
 				projectId,
@@ -10269,8 +10332,8 @@ function registerProjectCommand(program) {
 	project.command("delete").description("Delete a platform project").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke --project <id> project delete");
+			const projectId = await resolveActiveProjectId(config);
+			if (!projectId) throw new Error("Usage: keystroke --project <slug> project delete");
 			if (!options.yes) throw new Error("Pass --yes to confirm project deletion");
 			await runProjectDelete(config, projectId);
 		} catch (error) {
@@ -10431,27 +10494,23 @@ function registerWorkflowCommand(program) {
 }
 //#endregion
 //#region src/commands/config/use-project.ts
-async function fetchProjectInOrg(config, projectId) {
-	const platform = createCliPlatformClient(config);
-	try {
-		return await platform.projects.get(projectId);
-	} catch (error) {
-		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${projectId} not found in the active organization. Run \`keystroke project list\`, then \`keystroke config use project <id>\`.`);
-		throw error;
-	}
+async function fetchProjectInOrg(config, projectRef) {
+	return resolveProjectRef(createCliPlatformClient(config), projectRef);
 }
 function assertProjectReadyForConfig(project) {
-	if (project.status === "failed") throw new Error(project.lastError ? `Project ${project.id} deploy failed: ${project.lastError}` : `Project ${project.id} deploy failed`);
-	if (project.status === "starting") throw new Error(`Project ${project.id} is still starting. Wait for deploy to finish, then run \`keystroke config use project ${project.id}\`.`);
+	const label = formatProjectLabel(project);
+	if (project.status === "failed") throw new Error(project.lastError ? `Project ${label} deploy failed: ${project.lastError}` : `Project ${label} deploy failed`);
+	if (project.status === "starting") throw new Error(`Project ${label} is still starting. Wait for deploy to finish, then run \`keystroke config use project ${label}\`.`);
 }
-async function runConfigUseProject(config, projectId) {
-	const project = await fetchProjectInOrg(config, projectId);
+async function runConfigUseProject(config, projectRef) {
+	const project = await fetchProjectInOrg(config, projectRef);
 	assertProjectReadyForConfig(project);
-	config.set("activeProjectId", projectId);
+	config.set("activeProjectId", project.id);
 	config.set("apiTarget", "platform");
+	const label = formatProjectLabel(project);
 	return {
-		stdout: project.status === "active" ? `Using platform project ${projectId}\n` : `Using platform project ${projectId} (${project.status})\n`,
-		stderr: project.status === "inactive" ? `Project is not active yet. Deploy with: ${cliBinaryName()} deploy --project ${projectId}\n` : void 0
+		stdout: project.status === "active" ? `Using platform project ${label}\n` : `Using platform project ${label} (${project.status})\n`,
+		stderr: project.status === "inactive" ? `Project is not active yet. Deploy with: ${cliBinaryName()} deploy --project ${label}\n` : void 0
 	};
 }
 //#endregion
@@ -10480,7 +10539,7 @@ function registerConfigCommand(program) {
 			return;
 		}
 		if (mode === "org") {
-			const membership = await selectActiveOrganization(cliConfig, { organizationId: id });
+			const membership = await selectActiveOrganization(cliConfig, { organizationRef: id });
 			process.stdout.write(`Using organization ${membership.organization.name}\n`);
 			return;
 		}
@@ -10490,9 +10549,9 @@ function registerConfigCommand(program) {
 			process.stdout.write(activeProjectId ? `Using platform API (default project ${activeProjectId} for project-scoped commands)\n` : "Using platform API\n");
 			return;
 		}
-		if (mode !== "project") throw new Error("Usage: keystroke config use [local|cloud|project [projectId]|org [organizationId]]");
+		if (mode !== "project") throw new Error("Usage: keystroke config use [local|cloud|project [slug]|org [slug]]");
 		const targetProjectId = id ?? cliConfig.get("activeProjectId");
-		if (!targetProjectId) throw new Error("Usage: keystroke config use project <projectId>");
+		if (!targetProjectId) throw new Error("Usage: keystroke config use project <slug>");
 		const result = await runConfigUseProject(cliConfig, targetProjectId);
 		process.stdout.write(result.stdout);
 		if (result.stderr) process.stderr.write(result.stderr);
@@ -10566,7 +10625,7 @@ async function syncSkills(command) {
 //#endregion
 //#region src/program.ts
 function createProgram() {
-	const program = new Command().name("keystroke").description("Build, run, and manage keystroke projects").version(readCliVersion()).option("--project <id>", "Platform project id (deploy target or one-off API target)").option("--local", "Force local keystroke server URL").hook("preAction", async (thisCommand, actionCommand) => {
+	const program = new Command().name("keystroke").description("Build, run, and manage keystroke projects").version(readCliVersion()).option("--project <slug>", "Platform project slug (deploy target or one-off API target)").option("--local", "Force local keystroke server URL").hook("preAction", async (thisCommand, actionCommand) => {
 		const opts = thisCommand.opts();
 		setCliTargetOptions({
 			projectId: opts.project,