howone 0.1.1 → 0.1.5

package/bin/index.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env bun
 import { createRequire } from "node:module";
-import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
-import { cac } from "cac";
-import { readdir, rename, stat } from "node:fs/promises";
+import { say, spinner } from "@astrojs/cli-kit";
+import { cancel, confirm, isCancel, select, text } from "@clack/prompts";
+import { readdir, rename, stat, writeFile } from "node:fs/promises";
 import { copy, emptyDir, ensureDir, pathExists } from "fs-extra/esm";
-import pc from "picocolors";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import pc from "picocolors";
 import validatePackageName from "validate-npm-package-name";
+import yargsParser from "yargs-parser";
 //#region src/index.ts
 const packageJson = createRequire(import.meta.url)("../package.json");
 const DEFAULT_PROJECT_NAME = "howone-app";
@@ -25,78 +26,108 @@ var CliError = class extends Error {
 		this.name = "CliError";
 	}
 };
-const cli = cac("howone");
-cli.version(packageJson.version, "-v, --version");
-cli.help();
-cli.command("create [projectName] [legacyProjectName]", "Create a new project from a HowOne template.").alias("new").alias("init").option("-t, --template <template>", "Template to use: vite, nextjs").option("--vite", "Shortcut for --template vite").option("--nextjs", "Shortcut for --template nextjs").option("--next", "Alias for --nextjs").option("-f, --force", "Overwrite an existing non-empty target directory").option("-y, --yes", "Disable prompts and accept defaults where possible").option("--json", "Print machine-readable JSON output").option("--cwd <dir>", "Directory in which to create the project").example("howone vite my-app").example("howone next my-app").example("howone create my-app --template vite").example("howone create my-app --template nextjs --yes").example("howone create my-app --template vite --json --yes").example("howone create template --vite my-app").action((projectName, legacyProjectName, options) => {
-	runCreate(projectName, legacyProjectName, options).catch((error) => handleFatalError(error, Boolean(options.json)));
-});
-try {
-	cli.parse(normalizeCliArgv(process.argv), { run: true });
-} catch (error) {
+main().catch((error) => {
 	handleFatalError(error, process.argv.includes("--json"));
+});
+async function main() {
+	const command = parseCommand(process.argv.slice(2));
+	if (command.options.version) {
+		console.log(packageJson.version);
+		return;
+	}
+	if (command.options.help || command.path.length === 0) {
+		printHelp(command.path);
+		return;
+	}
+	const [scope, subcommand, ...rest] = command.path;
+	if (isTemplateAlias(scope)) {
+		await runInitApp(compact([subcommand, ...rest]), {
+			...command.options,
+			template: resolveTemplateAlias(scope)
+		});
+		return;
+	}
+	if (scope === "init" || scope === "new") {
+		await runInitApp(subcommand === "app" ? rest : compact([subcommand, ...rest]), command.options);
+		return;
+	}
+	if (scope === "create") {
+		await runCreatePlaceholder(command.options);
+		return;
+	}
+	if (scope === "deploy") {
+		await runDeploy(command.options);
+		return;
+	}
+	if (scope === "ai" && subcommand === "run") {
+		await runAiRun(rest, command.options);
+		return;
+	}
+	throw new CliError("E_COMMAND_UNKNOWN", `Unknown command: ${command.path.join(" ")}`);
 }
-function normalizeCliArgv(argv) {
-	if (argv.length < 3) return argv;
-	const runtime = argv[0];
-	const script = argv[1];
-	const userArgs = argv.slice(2);
-	const first = userArgs[0];
-	if (!first || first === "create" || first === "new" || first === "init" || first === "--help" || first === "-h") return normalizeCreateSubcommandArgv(argv);
-	const template = resolveTemplateAlias(first);
-	if (template) return [
-		runtime,
-		script,
-		"create",
-		...userArgs.slice(1),
-		"--template",
-		template
-	];
-	if (!first.startsWith("-") && hasTemplateFlag(userArgs)) return [
-		runtime,
-		script,
-		"create",
-		...userArgs
-	];
-	return argv;
-}
-function normalizeCreateSubcommandArgv(argv) {
-	const runtime = argv[0];
-	const script = argv[1];
-	const command = argv[2];
-	const rest = argv.slice(3);
-	if (!command || command !== "create" && command !== "new" && command !== "init") return argv;
-	const first = rest[0];
-	const template = resolveTemplateAlias(first);
-	if (!template) return argv;
-	return [
-		runtime,
-		script,
-		command,
-		...rest.slice(1),
-		"--template",
-		template
-	];
-}
-function resolveTemplateAlias(value) {
-	if (!value) return void 0;
-	const normalized = TEMPLATE_ALIASES[value];
-	return normalized && isTemplate(normalized) ? normalized : void 0;
+function parseCommand(args) {
+	const hasHelp = args.includes("--help") || args.includes("-h");
+	const hasVersion = args.includes("--version") || args.includes("-v");
+	const parsed = yargsParser(args, {
+		alias: {
+			h: "help",
+			v: "version",
+			t: "template",
+			f: "force",
+			y: "yes"
+		},
+		boolean: [
+			"help",
+			"version",
+			"vite",
+			"nextjs",
+			"next",
+			"force",
+			"yes",
+			"json"
+		],
+		string: ["template", "cwd"],
+		configuration: { "camel-case-expansion": false }
+	});
+	return {
+		path: parsed._.map(String),
+		options: {
+			template: typeof parsed.template === "string" ? parsed.template : void 0,
+			vite: Boolean(parsed.vite),
+			nextjs: Boolean(parsed.nextjs),
+			next: Boolean(parsed.next),
+			force: Boolean(parsed.force),
+			yes: Boolean(parsed.yes),
+			json: Boolean(parsed.json),
+			cwd: typeof parsed.cwd === "string" ? parsed.cwd : void 0,
+			help: Boolean(parsed.help) || hasHelp,
+			version: Boolean(parsed.version) || hasVersion
+		}
+	};
 }
-function hasTemplateFlag(args) {
-	return args.some((arg) => arg === "--vite" || arg === "--next" || arg === "--nextjs" || arg === "--template");
+function compact(values) {
+	return values.filter((value) => Boolean(value));
 }
-async function runCreate(projectNameArg, legacyProjectNameArg, options) {
-	const plan = await resolveCreatePlan(projectNameArg, legacyProjectNameArg, options, path.resolve(options.cwd ?? process.cwd()), process.stdout.isTTY && !options.yes && !options.json);
-	if (!options.json) intro(pc.bold("HowOne"));
-	await createTemplate(plan, Boolean(options.json));
+async function runInitApp(pathArgs, options) {
+	const plan = await resolveCreatePlan(pathArgs, options, path.resolve(options.cwd ?? process.cwd()), process.stdout.isTTY && !options.yes && !options.json);
+	const howoneContext = resolveHowoneCreateContext();
+	if (options.json) await createTemplate(plan, howoneContext, true);
+	else {
+		await say(pc.bold("HowOne"));
+		await createTemplate(plan, howoneContext, false);
+	}
 	const result = {
 		ok: true,
-		command: "create",
+		command: "init app",
 		template: plan.template,
 		projectName: plan.projectName,
 		targetDir: plan.targetDir,
 		packageManager: "bun",
+		...howoneContext ? { howone: {
+			projectId: howoneContext.projectId,
+			env: howoneContext.env,
+			envFile: path.join(plan.targetDir, ".env")
+		} } : {},
 		nextSteps: [
 			`cd ${formatPathForShell(path.relative(plan.cwd, plan.targetDir) || ".")}`,
 			"bun install",
@@ -107,16 +138,51 @@ async function runCreate(projectNameArg, legacyProjectNameArg, options) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
-	outro([
-		`${pc.green("Created")} ${pc.bold(plan.template)} template in ${pc.cyan(path.relative(plan.cwd, plan.targetDir) || ".")}`,
-		"",
-		pc.bold("Next steps:"),
-		...result.nextSteps.map((step) => `  ${step}`)
-	].join("\n"));
+	printCreateSuccess(plan, result);
+}
+async function runCreatePlaceholder(options) {
+	const result = {
+		ok: true,
+		command: "create",
+		status: "pending",
+		message: "howone create is reserved for a future workflow."
+	};
+	if (options.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	printPending("howone create", result.message ?? "howone create is reserved for a future workflow.");
+}
+async function runDeploy(options) {
+	const result = {
+		ok: true,
+		command: "deploy",
+		status: "pending",
+		message: "howone deploy is not implemented yet."
+	};
+	if (options.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	printPending("howone deploy", "Deploy is not implemented yet.");
 }
-async function resolveCreatePlan(projectNameArg, legacyProjectNameArg, options, cwd, isInteractive) {
+async function runAiRun(pathArgs, options) {
+	const aiId = pathArgs[0];
+	const result = {
+		ok: true,
+		command: "ai run",
+		status: "pending",
+		message: aiId ? `howone ai run ${aiId} is not implemented yet.` : "howone ai run is not implemented yet."
+	};
+	if (options.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	printPending("howone ai run", result.message ?? "AI run is not implemented yet.");
+}
+async function resolveCreatePlan(pathArgs, options, cwd, isInteractive) {
 	const template = resolveTemplateOption(options);
-	const projectName = projectNameArg === "template" ? legacyProjectNameArg : projectNameArg;
+	const projectName = pathArgs[0] === "template" ? pathArgs[1] : pathArgs[0];
 	const resolvedTemplate = template ?? (isInteractive ? await promptTemplate() : void 0);
 	if (!resolvedTemplate) throw new CliError("E_TEMPLATE_REQUIRED", "Missing template. Use --template vite or --template nextjs.");
 	const resolvedProjectName = projectName ?? (isInteractive ? await promptProjectName() : DEFAULT_PROJECT_NAME);
@@ -130,7 +196,8 @@ async function resolveCreatePlan(projectNameArg, legacyProjectNameArg, options,
 			entries: entries.slice(0, 20),
 			retryWithForce: [
 				"howone",
-				"create",
+				"init",
+				"app",
 				resolvedProjectName,
 				"--template",
 				resolvedTemplate,
@@ -145,10 +212,11 @@ async function resolveCreatePlan(projectNameArg, legacyProjectNameArg, options,
 			message: `Directory "${path.relative(cwd, targetDir) || "."}" is not empty. Overwrite it?`,
 			initialValue: false
 		});
-		if (isCancel(shouldOverwrite) || !shouldOverwrite) {
+		if (isCancel(shouldOverwrite)) {
 			cancel("Cancelled.");
 			process.exit(0);
 		}
+		if (!shouldOverwrite) throw new CliError("E_CANCELLED", "Cancelled.");
 	}
 	await assertTargetWritable(targetDir);
 	return {
@@ -210,12 +278,21 @@ async function promptProjectName() {
 		cancel("Cancelled.");
 		process.exit(0);
 	}
-	return value;
+	return String(value || DEFAULT_PROJECT_NAME);
+}
+async function createTemplate(plan, howoneContext, json) {
+	if (json) {
+		await performCreateTemplate(plan, howoneContext);
+		return;
+	}
+	await spinner({
+		start: "Creating project",
+		end: "Project created",
+		while: () => performCreateTemplate(plan, howoneContext)
+	});
 }
-async function createTemplate(plan, json) {
+async function performCreateTemplate(plan, howoneContext) {
 	const templateDir = getTemplateDir(plan.template);
-	const task = json ? null : spinner();
-	task?.start("Creating project");
 	if (plan.force && await pathExists(plan.targetDir)) await emptyDir(plan.targetDir);
 	else await ensureDir(plan.targetDir);
 	await copy(templateDir, plan.targetDir, {
@@ -226,8 +303,33 @@ async function createTemplate(plan, json) {
 		}
 	});
 	await restoreGitignore(plan.targetDir);
+	await writeHowoneEnvFile(plan, howoneContext);
 	await assertTemplateCopied(plan);
-	task?.stop("Project created");
+}
+function normalizeHowoneEnv(value) {
+	const normalized = value?.trim().toLowerCase();
+	if (!normalized) return "dev";
+	if (normalized === "development") return "dev";
+	if (normalized === "production") return "prod";
+	if (normalized === "local" || normalized === "dev" || normalized === "prod") return normalized;
+	return "dev";
+}
+function resolveHowoneCreateContext() {
+	const projectId = process.env.HOWONE_PROJECT_ID?.trim();
+	if (!projectId) return null;
+	return {
+		projectId,
+		env: normalizeHowoneEnv(process.env.HOWONE_ENV ?? process.env.APP_ENV)
+	};
+}
+function getTemplateEnvEntries(template, context) {
+	if (template === "vite") return [["VITE_HOWONE_PROJECT_ID", context.projectId], ["VITE_HOWONE_ENV", context.env]];
+	return [["NEXT_PUBLIC_HOWONE_PROJECT_ID", context.projectId], ["NEXT_PUBLIC_HOWONE_ENV", context.env]];
+}
+async function writeHowoneEnvFile(plan, howoneContext) {
+	if (!howoneContext) return;
+	const lines = getTemplateEnvEntries(plan.template, howoneContext).map(([key, value]) => `${key}=${value}`);
+	await writeFile(path.join(plan.targetDir, ".env"), [...lines, ""].join("\n"), "utf-8");
 }
 function getTemplateDir(template) {
 	const currentFile = fileURLToPath(import.meta.url);
@@ -261,19 +363,106 @@ function validateProjectName(projectName) {
 	if (result.validForNewPackages) return;
 	throw new CliError("E_PROJECT_NAME_INVALID", [...result.errors ?? [], ...result.warnings ?? []][0] ?? `Invalid project name: ${projectName}`);
 }
+function resolveTemplateAlias(value) {
+	if (!value) return void 0;
+	const normalized = TEMPLATE_ALIASES[value];
+	return normalized && isTemplate(normalized) ? normalized : void 0;
+}
+function isTemplateAlias(value) {
+	return Boolean(resolveTemplateAlias(value));
+}
 function isTemplate(value) {
-	return TEMPLATES.includes(value);
+	return typeof value === "string" && TEMPLATES.includes(value);
 }
 function formatPathForShell(value) {
 	return value.includes(" ") ? JSON.stringify(value) : value;
 }
-function handleFatalError(error, json) {
-	if (error instanceof CliError) {
-		printError(error, json);
-		process.exit(1);
+function printHelp(pathArgs) {
+	const topic = pathArgs.join(" ");
+	if (topic === "init" || topic === "init app" || topic === "new" || topic === "new app") {
+		printInitHelp();
+		return;
+	}
+	if (topic === "create") {
+		printReservedHelp("howone create", "Reserved for a future create workflow.");
+		return;
+	}
+	if (topic === "deploy") {
+		printReservedHelp("howone deploy", "Deploy support is reserved and not implemented yet.");
+		return;
+	}
+	if (topic === "ai" || topic === "ai run") {
+		printReservedHelp("howone ai run [aiId]", "AI run support is reserved and not implemented yet.");
+		return;
 	}
-	printError(new CliError("E_UNEXPECTED", error instanceof Error ? error.message : String(error)), json);
-	process.exit(1);
+	printRootHelp();
+}
+function printRootHelp() {
+	console.log(formatPanel(`${pc.bold("HowOne CLI")} ${pc.dim(`v${packageJson.version}`)}`, [
+		`${pc.dim("Usage")}    howone <command> [options]`,
+		"",
+		pc.bold("Commands"),
+		formatCommand("init app [name]", "Create an app from a template"),
+		formatCommand("create", "Reserved placeholder"),
+		formatCommand("deploy", "Reserved placeholder"),
+		formatCommand("ai run [aiId]", "Reserved placeholder"),
+		"",
+		pc.bold("Options"),
+		formatCommand("-h, --help", "Show help"),
+		formatCommand("-v, --version", "Show version"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone init app my-app --template vite")}`,
+		`  ${pc.cyan("howone deploy")}`,
+		`  ${pc.cyan("howone ai run generateImage")}`
+	]));
+}
+function printInitHelp() {
+	console.log(formatPanel(`${pc.bold("Create an app")}`, [
+		`${pc.dim("Usage")}    howone init app [name] [options]`,
+		"",
+		pc.bold("Options"),
+		formatCommand("-t, --template <template>", "Template to use: vite, nextjs"),
+		formatCommand("--vite", "Shortcut for --template vite"),
+		formatCommand("--nextjs", "Shortcut for --template nextjs"),
+		formatCommand("--next", "Alias for --nextjs"),
+		formatCommand("-f, --force", "Overwrite an existing non-empty directory"),
+		formatCommand("-y, --yes", "Disable prompts and accept defaults"),
+		formatCommand("--json", "Print machine-readable JSON output"),
+		formatCommand("--cwd <dir>", "Directory in which to create the app"),
+		"",
+		pc.bold("Examples"),
+		`  ${pc.cyan("howone init app my-app --template vite")}`,
+		`  ${pc.cyan("howone init app my-app --template nextjs --yes")}`
+	]));
+}
+function printReservedHelp(command, description) {
+	console.log(formatPanel(pc.bold(command), [
+		description,
+		"",
+		`${pc.yellow("Pending")} This command is available as a stable placeholder.`
+	]));
+}
+function printPending(command, message) {
+	console.log(formatPanel(pc.bold(command), [`${pc.yellow("Pending")} ${message}`]));
+}
+function printCreateSuccess(plan, result) {
+	const relativeTarget = path.relative(plan.cwd, plan.targetDir) || ".";
+	const lines = [`${pc.green("Created")} ${pc.bold(plan.template)} app in ${pc.cyan(relativeTarget)}`];
+	if (result.howone) lines.push("", pc.bold("HowOne context"), formatCommand("project", result.howone.projectId), formatCommand("env", result.howone.env), formatCommand("file", path.relative(plan.cwd, result.howone.envFile) || ".env"));
+	lines.push("", pc.bold("Next steps"), ...(result.nextSteps ?? []).map((step) => `  ${pc.cyan(step)}`));
+	console.log(formatPanel(pc.bold("App ready"), lines));
+}
+function formatPanel(title, lines) {
+	return [`${pc.green("◆")} ${title}`, ...lines.map((line) => line ? `  ${line}` : "")].join("\n");
+}
+function formatCommand(command, description) {
+	return `  ${pc.cyan(command.padEnd(28))} ${description}`;
+}
+function handleFatalError(error, json) {
+	const cliError = error instanceof CliError ? error : new CliError("E_UNEXPECTED", error instanceof Error ? error.message : String(error));
+	printError(cliError, json);
+	process.exit(cliError.code === "E_CANCELLED" ? 0 : 1);
 }
 function printError(error, json) {
 	const payload = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",
@@ -27,17 +27,19 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@astrojs/cli-kit": "^0.4.1",
     "@clack/prompts": "^1.3.0",
-    "cac": "^7.0.0",
     "fs-extra": "^11.3.4",
     "picocolors": "^1.1.1",
-    "validate-npm-package-name": "^7.0.2"
+    "validate-npm-package-name": "^7.0.2",
+    "yargs-parser": "^22.0.0"
   },
   "devDependencies": {
     "@howone/tsconfig": "workspace:*",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^25.6.0",
     "@types/validate-npm-package-name": "^4.0.2",
+    "@types/yargs-parser": "^21.0.3",
     "tsdown": "^0.21.10",
     "typescript": "^5.7.3"
   }

package/templates/nextjs/lib/sdk.ts

@@ -1,9 +1,8 @@
 import { createClient, defineEntities, withEntities } from '@howone/sdk'
 
-export const HOWONE_PROJECT_ID = 'demo'
-
 const client = createClient({
-  projectId: HOWONE_PROJECT_ID,
+  projectId: process.env.NEXT_PUBLIC_HOWONE_PROJECT_ID,
+  env: process.env.NEXT_PUBLIC_HOWONE_ENV,
 })
 
 export const entities = defineEntities({

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.5",
+    "@howone/sdk": "2.0.0-beta.7",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/src/App.tsx

@@ -1,8 +1,8 @@
-import { HowOneProvider } from '@howone/sdk'
+import { HowOneProvider } from '@howone/sdk/react'
 
 function App() {
   return (
-    <HowOneProvider>
+    <HowOneProvider auth="optional" brand="visible">
       <div className="App">
         <h1>Hello HowOne</h1>
       </div>

package/templates/vite/src/lib/sdk.ts

@@ -1,9 +1,8 @@
 import { createClient, defineEntities, withEntities } from '@howone/sdk'
 
-export const HOWONE_PROJECT_ID = 'demo'
-
 const client = createClient({
-  projectId: HOWONE_PROJECT_ID,
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
 })
 
 export const entities = defineEntities({