@impulselab/cli 0.1.6 → 0.2.1

package/dist/index.js

@@ -15,9 +15,6 @@ function configPath(cwd = process.cwd()) {
   return path.join(cwd, CONFIG_FILE);
 }
 
-// src/config/read-config.ts
-import fsExtra from "fs-extra";
-
 // src/schemas/impulse-config.ts
 import { z } from "zod";
 var ImpulseConfigSchema = z.object({
@@ -36,20 +33,44 @@ var ImpulseConfigSchema = z.object({
   ).default([])
 });
 
-// src/config/read-config.ts
-var { readJson, pathExists } = fsExtra;
-async function readConfig(cwd = process.cwd()) {
-  const file = configPath(cwd);
-  if (!await pathExists(file)) return null;
-  const raw = await readJson(file);
-  const parsed = ImpulseConfigSchema.safeParse(raw);
+// src/shared/json-file.ts
+import fsExtra from "fs-extra";
+import { chmod } from "fs/promises";
+var { readJson, pathExists, outputJson } = fsExtra;
+async function readJsonFile(filePath, schema, opts) {
+  if (!await pathExists(filePath)) return null;
+  let raw;
+  try {
+    raw = await readJson(filePath);
+  } catch {
+    if (opts?.throwOnInvalid !== void 0) {
+      throw new Error(`${opts.throwOnInvalid}: failed to read file`);
+    }
+    return null;
+  }
+  const parsed = schema.safeParse(raw);
   if (!parsed.success) {
-    throw new Error(
-      `Invalid .impulse.json: ${parsed.error.message}`
-    );
+    if (opts?.throwOnInvalid !== void 0) {
+      throw new Error(`${opts.throwOnInvalid}: ${parsed.error.message}`);
+    }
+    return null;
   }
   return parsed.data;
 }
+async function writeJsonFile(filePath, data, opts) {
+  const { spaces = 2, mode } = opts ?? {};
+  await outputJson(filePath, data, { spaces, ...mode !== void 0 ? { mode } : {} });
+  if (mode !== void 0) {
+    await chmod(filePath, mode);
+  }
+}
+
+// src/config/read-config.ts
+async function readConfig(cwd = process.cwd()) {
+  return readJsonFile(configPath(cwd), ImpulseConfigSchema, {
+    throwOnInvalid: "Invalid .impulse.json"
+  });
+}
 
 // src/config/write-config.ts
 import fsExtra2 from "fs-extra";
@@ -146,7 +167,7 @@ async function isUltimateTemplate(cwd) {
   return foundDeps.size >= STRUCTURAL_MARKERS.workspaceDeps.length;
 }
 async function runInit(options) {
-  const { cwd, force } = options;
+  const { cwd, force, skipDetection = false } = options;
   p.intro("impulse init");
   if (!force && await hasConfig(cwd)) {
     p.log.warn(
@@ -165,17 +186,21 @@ async function runInit(options) {
     );
     process.exit(1);
   }
-  const isUT = await isUltimateTemplate(cwd);
-  s.stop(isUT ? "Ultimate Template project detected." : "Project detected.");
-  if (!isUT) {
-    const proceed = await p.confirm({
-      message: "This project does not appear to be an ImpulseLab Ultimate Template. Continue anyway?",
-      initialValue: false
-    });
-    if (p.isCancel(proceed) || !proceed) {
-      p.cancel("Initialization cancelled.");
-      process.exit(0);
+  if (!skipDetection) {
+    const isUT = await isUltimateTemplate(cwd);
+    s.stop(isUT ? "Ultimate Template project detected." : "Project detected.");
+    if (!isUT) {
+      const proceed = await p.confirm({
+        message: "This project does not appear to be an ImpulseLab Ultimate Template. Continue anyway?",
+        initialValue: false
+      });
+      if (p.isCancel(proceed) || !proceed) {
+        p.cancel("Initialization cancelled.");
+        process.exit(0);
+      }
     }
+  } else {
+    s.stop("Project ready.");
   }
   const projectName = await detectProjectName(cwd);
   const srcExists = await pathExists3(path2.join(cwd, "src"));
@@ -197,6 +222,7 @@ async function runInit(options) {
 // src/commands/add.ts
 import { execSync as execSync2, execFileSync } from "child_process";
 import { existsSync } from "fs";
+import { readFile as readFile7, writeFile, unlink } from "fs/promises";
 import path12 from "path";
 import * as p5 from "@clack/prompts";
 
@@ -271,7 +297,8 @@ var registryConstants = {
   githubBranch: "main",
   modulesDir: "modules",
   subModulesDirName: "sub-modules",
-  manifestFileName: "module.json"
+  manifestFileName: "module.json",
+  presetsDir: "presets"
 };
 
 // src/registry/github-urls.ts
@@ -325,7 +352,7 @@ function moduleRegistryPath(moduleId) {
 }
 
 // src/registry/fetch-module-manifest.ts
-var { readJson: readJson3, pathExists: pathExists4 } = fsExtra5;
+var { pathExists: pathExists4 } = fsExtra5;
 async function fetchModuleManifest(moduleId, localPath) {
   const registryPath = moduleRegistryPath(moduleId);
   if (localPath) {
@@ -333,12 +360,10 @@ async function fetchModuleManifest(moduleId, localPath) {
     if (!await pathExists4(file)) {
       throw new Error(`Local module not found: ${file}`);
     }
-    const raw2 = await readJson3(file);
-    const parsed2 = ModuleManifestSchema.safeParse(raw2);
-    if (!parsed2.success) {
-      throw new Error(`Invalid module.json for ${moduleId}: ${parsed2.error.message}`);
-    }
-    return parsed2.data;
+    const manifest = await readJsonFile(file, ModuleManifestSchema, {
+      throwOnInvalid: `Invalid module.json for ${moduleId}`
+    });
+    return manifest;
   }
   const url = githubUrls.rawFile(registryPath, registryConstants.manifestFileName);
   const res = await fetch(url, { headers: getGitHubHeaders() });
@@ -359,7 +384,7 @@ async function fetchModuleManifest(moduleId, localPath) {
 // src/registry/list-available-modules.ts
 import fsExtra6 from "fs-extra";
 import path4 from "path";
-var { readJson: readJson4, pathExists: pathExists5 } = fsExtra6;
+var { readJson: readJson3, pathExists: pathExists5 } = fsExtra6;
 var _cachedModuleList = null;
 async function listAvailableModules(localPath) {
   if (localPath) {
@@ -375,7 +400,7 @@ async function listAvailableModules(localPath) {
       );
       if (!await pathExists5(manifestFile)) continue;
       try {
-        const raw = await readJson4(manifestFile);
+        const raw = await readJson3(manifestFile);
         const parsed = ModuleManifestSchema.safeParse(raw);
         if (!parsed.success) continue;
         let subModules;
@@ -442,10 +467,10 @@ async function listAvailableModules(localPath) {
 // src/registry/fetch-module-file.ts
 async function fetchModuleFile(moduleName, fileSrc, localPath) {
   if (localPath) {
-    const { readFile: readFile7 } = await import("fs/promises");
+    const { readFile: readFile9 } = await import("fs/promises");
     const { join } = await import("path");
     const file = join(localPath, moduleName, fileSrc);
-    return readFile7(file, "utf-8");
+    return readFile9(file, "utf-8");
   }
   const url = githubUrls.rawFile(moduleName, fileSrc);
   const res = await fetch(url, { headers: getGitHubHeaders() });
@@ -536,15 +561,32 @@ ${value}
 // src/transforms/register-route.ts
 import fsExtra9 from "fs-extra";
 import path7 from "path";
+
+// src/transforms/base-router-content.ts
+var BASE_ROUTER_CONTENT = [
+  'import type { RouterInput } from "@orpc/server";',
+  'import { createRouter } from "@orpc/server";',
+  "",
+  "export const appRouter = createRouter({",
+  "} satisfies RouterInput);",
+  "",
+  "export type AppRouter = typeof appRouter;",
+  ""
+].join("\n");
+
+// src/transforms/register-route.ts
 var { readFile: readFile3, outputFile: outputFile3, pathExists: pathExists8 } = fsExtra9;
 async function registerRoute(target, value, cwd, dryRun) {
   const file = path7.join(cwd, target);
+  let content;
   if (!await pathExists8(file)) {
-    throw new Error(
-      `register-route: target file not found: ${target}. Please ensure your router file exists.`
-    );
+    content = BASE_ROUTER_CONTENT;
+    if (!dryRun) {
+      await outputFile3(file, content, "utf-8");
+    }
+  } else {
+    content = await readFile3(file, "utf-8");
   }
-  const content = await readFile3(file, "utf-8");
   if (content.includes(value)) return;
   const routerPattern = /^([ \t]*\})[ \t]*(?:satisfies|as)\s/m;
   const match = routerPattern.exec(content);
@@ -691,9 +733,6 @@ async function runTransform(transform, cwd, dryRun) {
 // src/auth/require-auth.ts
 import * as p4 from "@clack/prompts";
 
-// src/auth/read-auth.ts
-import fsExtra13 from "fs-extra";
-
 // src/auth/auth-path.ts
 import path11 from "path";
 import os from "os";
@@ -710,19 +749,8 @@ var AuthCredentialsSchema = z6.object({
 });
 
 // src/auth/read-auth.ts
-var { readJson: readJson5, pathExists: pathExists12 } = fsExtra13;
 async function readAuth() {
-  const file = authPath();
-  if (!await pathExists12(file)) return null;
-  let raw;
-  try {
-    raw = await readJson5(file);
-  } catch {
-    return null;
-  }
-  const parsed = AuthCredentialsSchema.safeParse(raw);
-  if (!parsed.success) return null;
-  return parsed.data;
+  return readJsonFile(authPath(), AuthCredentialsSchema);
 }
 
 // src/auth/require-auth.ts
@@ -782,6 +810,7 @@ function installNpmDeps(deps, cwd, dryRun) {
 async function installModule(moduleId, manifest, cwd, dryRun, installedModules, localPath) {
   p5.log.step(`Installing ${moduleId}@${manifest.version}...`);
   const installedDests = [];
+  const createdDests = [];
   if (manifest.files.length > 0) {
     const installed = await installFiles({
       moduleName: moduleId,
@@ -797,13 +826,34 @@ async function installModule(moduleId, manifest, cwd, dryRun, installedModules,
         continue;
       }
       installedDests.push(f.dest);
+      if (f.action === "created" || f.action === "would-create") {
+        createdDests.push(f.dest);
+      }
       const icon = f.action === "created" || f.action === "would-create" ? "+" : f.action === "overwritten" || f.action === "would-overwrite" ? "~" : "=";
       p5.log.message(`  ${icon} ${f.dest}`);
     }
   }
   for (const transform of manifest.transforms) {
     p5.log.step(`  transform: ${transform.type} \u2192 ${transform.target}`);
-    await runTransform(transform, cwd, dryRun);
+    try {
+      await runTransform(transform, cwd, dryRun);
+    } catch (err) {
+      p5.log.warn(
+        `Transform "${transform.type} \u2192 ${transform.target}" failed for module "${moduleId}": ${err instanceof Error ? err.message : String(err)}`
+      );
+      if (!dryRun && createdDests.length > 0) {
+        p5.log.warn(`Rolling back ${createdDests.length} file(s) created by "${moduleId}"...`);
+        for (const dest of createdDests) {
+          try {
+            await unlink(path12.join(cwd, dest));
+          } catch {
+          }
+        }
+      }
+      throw new Error(
+        `Module "${moduleId}" install failed during transform "${transform.type} \u2192 ${transform.target}".`
+      );
+    }
   }
   return installedDests;
 }
@@ -829,7 +879,10 @@ async function pickModulesInteractively(localPath) {
     modules = await listAvailableModules(localPath);
   } catch (err) {
     s.stop("Failed to load modules.");
-    throw err;
+    p5.cancel(
+      `Could not load module list: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
   }
   s.stop("Modules loaded.");
   if (modules.length === 0) {
@@ -847,7 +900,7 @@ async function pickModulesInteractively(localPath) {
       options.push({
         value: `${mod.name}/${sub}`,
         label: `  \u21B3 ${sub}`,
-        hint: `sub-module of ${mod.name}`
+        hint: `automatically includes ${mod.name}`
       });
     }
   }
@@ -861,20 +914,25 @@ async function pickModulesInteractively(localPath) {
     process.exit(0);
   }
   const result = new Set(selected);
+  const autoIncluded = [];
   for (const id of selected) {
     const { parent, child } = parseModuleId(id);
-    if (child !== null) {
+    if (child !== null && !selected.includes(parent)) {
       result.add(parent);
+      autoIncluded.push(parent);
     }
   }
+  if (autoIncluded.length > 0) {
+    p5.log.info(`Auto-included parent modules: ${autoIncluded.join(", ")}`);
+  }
   return [...result];
 }
 async function runAdd(options) {
-  let { moduleNames, cwd, dryRun, localPath, withSubModules = [], allowScripts = false } = options;
+  let { moduleNames, cwd, dryRun, localPath, withSubModules = [], allowScripts = false, skipIntro = false, skipAuth = false } = options;
   let allTargets;
   if (moduleNames.length === 0) {
-    p5.intro(`impulse add${dryRun ? " [dry-run]" : ""}`);
-    await requireAuth();
+    if (!skipIntro) p5.intro(`impulse add${dryRun ? " [dry-run]" : ""}`);
+    if (!skipAuth) await requireAuth();
     if (withSubModules.length > 0) {
       p5.log.warn(`--with is ignored in interactive mode. Select sub-modules from the picker.`);
       withSubModules = [];
@@ -893,8 +951,8 @@ async function runAdd(options) {
     }
     const withIds = moduleNames.length === 1 && withSubModules.length > 0 ? withSubModules.map((sub) => `${moduleNames[0]}/${sub}`) : [];
     allTargets = [...moduleNames, ...withIds];
-    p5.intro(`impulse add ${allTargets.join(", ")}${dryRun ? " [dry-run]" : ""}`);
-    await requireAuth();
+    if (!skipIntro) p5.intro(`impulse add ${allTargets.join(", ")}${dryRun ? " [dry-run]" : ""}`);
+    if (!skipAuth) await requireAuth();
   }
   const config = await readConfig(cwd);
   if (!config) {
@@ -924,7 +982,14 @@ async function runAdd(options) {
     }
   }
   if (moduleNames.length === 1 && withSubModules.length > 0) {
-    const parentManifest = await getManifest(moduleNames[0], localPath, manifests).catch(() => null);
+    let parentManifest = null;
+    try {
+      parentManifest = await getManifest(moduleNames[0], localPath, manifests);
+    } catch (err) {
+      p5.log.warn(
+        `Could not fetch manifest for "${moduleNames[0]}" to validate --with sub-modules: ${err instanceof Error ? err.message : String(err)}. Skipping validation.`
+      );
+    }
     if (parentManifest) {
       if (parentManifest.subModules.length === 0) {
         p5.cancel(`"${moduleNames[0]}" has no declared sub-modules.`);
@@ -1090,13 +1155,26 @@ Available: ${parentManifest.subModules.join(", ")}`
         runHooks = confirmed;
       }
       if (runHooks) {
+        const hookFailures = [];
         for (const { name, hooks } of allPostInstallHooks) {
           p5.log.step(`Running post-install hooks for ${name}...`);
           for (const hook of hooks) {
             p5.log.message(`  $ ${hook}`);
-            execSync2(hook, { cwd, stdio: "inherit" });
+            try {
+              execSync2(hook, { cwd, stdio: "inherit" });
+            } catch (err) {
+              const msg = `Post-install hook failed for "${name}" ($ ${hook}): ${err instanceof Error ? err.message : String(err)}`;
+              p5.log.warn(`${msg}. Continuing.`);
+              hookFailures.push(msg);
+            }
           }
         }
+        if (hookFailures.length > 0) {
+          p5.log.warn(
+            `${hookFailures.length} post-install hook(s) failed. See warnings above.`
+          );
+          process.exitCode = 1;
+        }
       } else {
         p5.log.warn("Post-install hooks skipped.");
       }
@@ -1114,7 +1192,28 @@ Available: ${parentManifest.subModules.join(", ")}`
       const dests = installedFilesMap.get(targetId) ?? [];
       if (targetManifest) recordModule(config, targetId, targetManifest, dests, now);
     }
-    await writeConfig(config, cwd);
+    const cfgPath = configPath(cwd);
+    let backup = null;
+    try {
+      backup = await readFile7(cfgPath, "utf-8");
+    } catch {
+    }
+    try {
+      await writeConfig(config, cwd);
+    } catch (err) {
+      p5.log.warn(
+        `Failed to write .impulse.json: ${err instanceof Error ? err.message : String(err)}`
+      );
+      if (backup !== null) {
+        try {
+          await writeFile(cfgPath, backup, "utf-8");
+          p5.log.warn("Config restored to previous state.");
+        } catch {
+          p5.log.warn("Could not restore config backup \u2014 .impulse.json may be in a partial state.");
+        }
+      }
+      throw err;
+    }
   }
   const label = allTargets.length === 1 ? `"${allTargets[0]}"` : allTargets.map((t) => `"${t}"`).join(", ");
   p5.outro(
@@ -1214,11 +1313,20 @@ import { execFileSync as execFileSync2 } from "child_process";
 var IMPULSE_BASE_URL = process.env.IMPULSE_BASE_URL ?? "https://impulselab.ai";
 var CLIENT_ID = "impulse-cli";
 async function requestDeviceCode() {
-  const res = await fetch(`${IMPULSE_BASE_URL}/api/auth/device/code`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ client_id: CLIENT_ID })
-  });
+  const url = `${IMPULSE_BASE_URL}/api/auth/device/code`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ client_id: CLIENT_ID })
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Network error calling ${url}: ${reason}. Check connection, VPN, proxy, and IMPULSE_BASE_URL (must match your deployed agency site).`
+    );
+  }
   if (!res.ok) {
     throw new Error(`Failed to initiate device flow: ${res.status} ${res.statusText}`);
   }
@@ -1275,6 +1383,25 @@ function openBrowser(url) {
   } catch {
   }
 }
+function copyToClipboard(text3) {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      execFileSync2("pbcopy", { input: text3 });
+    } else if (platform === "win32") {
+      execFileSync2("clip", { input: text3 });
+    } else {
+      try {
+        execFileSync2("xclip", ["-selection", "clipboard"], { input: text3 });
+      } catch {
+        execFileSync2("xsel", ["--clipboard", "--input"], { input: text3 });
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
 function assertDeviceCodeResponse(data) {
   if (typeof data !== "object" || data === null || typeof data.device_code !== "string" || typeof data.user_code !== "string" || typeof data.verification_uri !== "string") {
     throw new Error("Invalid device code response from server");
@@ -1304,13 +1431,8 @@ function mapDeviceTokenResponse(raw) {
 }
 
 // src/auth/write-auth.ts
-import fsExtra14 from "fs-extra";
-import { chmod } from "fs/promises";
-var { outputJson } = fsExtra14;
 async function writeAuth(credentials) {
-  const file = authPath();
-  await outputJson(file, credentials, { spaces: 2, mode: 384 });
-  await chmod(file, 384);
+  await writeJsonFile(authPath(), credentials, { mode: 384 });
 }
 
 // src/commands/login.ts
@@ -1345,9 +1467,13 @@ async function runLogin() {
 Visit the following URL to authenticate:
   ${browserUrl}
 `);
-  p7.log.message(`Your one-time code: ${deviceCode.userCode}
-`);
+  const rawCode = deviceCode.userCode;
+  const mid = Math.ceil(rawCode.length / 2);
+  const formattedCode = rawCode.length >= 6 ? `${rawCode.slice(0, mid)}-${rawCode.slice(mid)}` : rawCode;
   openBrowser(browserUrl);
+  const copied = copyToClipboard(rawCode);
+  p7.log.message(`Your one-time code: ${formattedCode}${copied ? " (copied to clipboard)" : ""}
+`);
   p7.log.info(`If the browser did not open, copy the URL above.
 Base URL: ${IMPULSE_BASE_URL}`);
   const pollInterval = Math.max(
@@ -1406,11 +1532,11 @@ function sleep(ms) {
 import * as p8 from "@clack/prompts";
 
 // src/auth/clear-auth.ts
-import fsExtra15 from "fs-extra";
-var { remove, pathExists: pathExists13 } = fsExtra15;
+import fsExtra13 from "fs-extra";
+var { remove, pathExists: pathExists12 } = fsExtra13;
 async function clearAuth() {
   const file = authPath();
-  if (!await pathExists13(file)) return false;
+  if (!await pathExists12(file)) return false;
   await remove(file);
   return true;
 }
@@ -1457,6 +1583,400 @@ async function runWhoami() {
   p9.outro("Done.");
 }
 
+// src/commands/create.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import path15 from "path";
+import * as p10 from "@clack/prompts";
+import fsExtra16 from "fs-extra";
+
+// src/registry/fetch-template.ts
+import fsExtra14 from "fs-extra";
+import path13 from "path";
+
+// src/schemas/template-manifest.ts
+import { z as z7 } from "zod";
+var TemplateFileSchema = z7.object({
+  src: z7.string(),
+  dest: z7.string()
+});
+var TemplateManifestSchema = z7.object({
+  name: z7.string(),
+  description: z7.string(),
+  /** Human-readable labels describing the tech stack (e.g. ["Next.js 15", "Tailwind CSS v4"]). */
+  stack: z7.array(z7.string()).default([]),
+  /** Module IDs pre-selected in the interactive picker (e.g. ["db", "auth"]). */
+  defaultModules: z7.array(z7.string()).default([]),
+  /** Files to copy from the template directory into the new project. */
+  files: z7.array(TemplateFileSchema).default([])
+});
+
+// src/registry/fetch-template.ts
+var { readJson: readJson4, pathExists: pathExists13, readFile: readFile8 } = fsExtra14;
+var TEMPLATES_DIR = "templates";
+var TEMPLATE_MANIFEST_FILE = "template.json";
+function templateRawUrl(templateId, file) {
+  return `https://raw.githubusercontent.com/${registryConstants.githubOrg}/${registryConstants.githubRepo}/${registryConstants.githubBranch}/${TEMPLATES_DIR}/${templateId}/${file}`;
+}
+async function fetchTemplateManifest(templateId, localPath) {
+  if (localPath) {
+    const file = path13.join(localPath, TEMPLATES_DIR, templateId, TEMPLATE_MANIFEST_FILE);
+    if (!await pathExists13(file)) {
+      throw new Error(`Local template not found: ${file}`);
+    }
+    const raw2 = await readJson4(file);
+    const parsed2 = TemplateManifestSchema.safeParse(raw2);
+    if (!parsed2.success) {
+      throw new Error(`Invalid template.json for "${templateId}": ${parsed2.error.message}`);
+    }
+    return parsed2.data;
+  }
+  const url = templateRawUrl(templateId, TEMPLATE_MANIFEST_FILE);
+  const res = await fetch(url, { headers: getGitHubHeaders() });
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(`Template not found in registry: ${templateId}`);
+    }
+    throw new Error(`Failed to fetch template manifest: ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.json();
+  const parsed = TemplateManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Invalid template.json for "${templateId}": ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+async function fetchTemplateFile(templateId, src, localPath) {
+  if (localPath) {
+    const file = path13.join(localPath, TEMPLATES_DIR, templateId, src);
+    return readFile8(file, "utf-8");
+  }
+  const url = templateRawUrl(templateId, src);
+  const res = await fetch(url, { headers: getGitHubHeaders() });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch template file "${src}": ${res.status} ${res.statusText}`);
+  }
+  return res.text();
+}
+
+// src/registry/fetch-preset.ts
+import fsExtra15 from "fs-extra";
+import path14 from "path";
+
+// src/schemas/preset-manifest.ts
+import { z as z8 } from "zod";
+var PresetManifestSchema = z8.object({
+  name: z8.string(),
+  description: z8.string(),
+  /** Template ID to scaffold from (references templates/<name>/). */
+  template: z8.string(),
+  /** Modules installed automatically — no user confirmation needed. */
+  defaultModules: z8.array(z8.string()),
+  /** Modules the user can optionally add during create. */
+  optionalModules: z8.array(z8.string()).default([])
+});
+
+// src/registry/fetch-preset.ts
+var { readJson: readJson5, pathExists: pathExists14 } = fsExtra15;
+var PRESETS_DIR = registryConstants.presetsDir;
+var PRESET_MANIFEST_FILE = "preset.json";
+function presetRawUrl(presetId, file) {
+  return `https://raw.githubusercontent.com/${registryConstants.githubOrg}/${registryConstants.githubRepo}/${registryConstants.githubBranch}/${PRESETS_DIR}/${presetId}/${file}`;
+}
+async function fetchPresetManifest(presetId, localPath) {
+  if (localPath) {
+    const file = path14.join(localPath, PRESETS_DIR, presetId, PRESET_MANIFEST_FILE);
+    if (!await pathExists14(file)) {
+      throw new Error(`Local preset not found: ${file}`);
+    }
+    const raw2 = await readJson5(file);
+    const parsed2 = PresetManifestSchema.safeParse(raw2);
+    if (!parsed2.success) {
+      throw new Error(`Invalid preset.json for "${presetId}": ${parsed2.error.message}`);
+    }
+    return parsed2.data;
+  }
+  const url = presetRawUrl(presetId, PRESET_MANIFEST_FILE);
+  const res = await fetch(url, { headers: getGitHubHeaders() });
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(`Preset not found in registry: ${presetId}`);
+    }
+    throw new Error(`Failed to fetch preset manifest: ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.json();
+  const parsed = PresetManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Invalid preset.json for "${presetId}": ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+async function listAvailablePresets(localPath) {
+  if (localPath) {
+    const presetsDir = path14.join(localPath, PRESETS_DIR);
+    if (!await pathExists14(presetsDir)) return [];
+    const { readdir } = await import("fs/promises");
+    const entries2 = await readdir(presetsDir, { withFileTypes: true });
+    return entries2.filter((e) => e.isDirectory()).map((e) => e.name);
+  }
+  const url = `https://api.github.com/repos/${registryConstants.githubOrg}/${registryConstants.githubRepo}/contents/${PRESETS_DIR}`;
+  const res = await fetch(url, { headers: getGitHubHeaders({ Accept: "application/vnd.github.v3+json" }) });
+  if (!res.ok) return ["saas"];
+  const entries = await res.json();
+  if (!Array.isArray(entries)) return ["saas"];
+  return entries.filter((e) => e.type === "dir").map((e) => e.name);
+}
+
+// src/commands/create.ts
+var { outputFile: outputFile7, pathExists: pathExists15 } = fsExtra16;
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function isValidProjectName(name) {
+  return /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(name);
+}
+async function runCreate(options) {
+  const { cwd, localPath } = options;
+  p10.intro("impulse create");
+  await requireAuth();
+  let projectName = options.projectName;
+  if (!projectName) {
+    const answer = await p10.text({
+      message: "Project name:",
+      placeholder: "my-app",
+      validate(value) {
+        if (!value?.trim()) return "Project name is required.";
+        const slug = slugify(value.trim());
+        if (!isValidProjectName(slug)) {
+          return "Use lowercase letters, numbers, and hyphens only (e.g. my-app).";
+        }
+        return void 0;
+      }
+    });
+    if (p10.isCancel(answer)) {
+      p10.cancel("Cancelled.");
+      process.exit(0);
+    }
+    projectName = slugify(answer.trim());
+  } else {
+    projectName = slugify(projectName.trim());
+  }
+  const targetDir = path15.resolve(cwd, projectName);
+  if (existsSync2(targetDir)) {
+    p10.cancel(`Directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+  let templateId;
+  let selectedModules = options.modules ?? [];
+  if (options.template) {
+    templateId = options.template;
+    if (!options.modules) {
+      const s = p10.spinner();
+      s.start("Loading available modules...");
+      let availableModules;
+      try {
+        availableModules = await listAvailableModules(localPath);
+      } catch {
+        availableModules = [];
+      }
+      s.stop("Modules loaded.");
+      if (availableModules.length > 0) {
+        const templateManifest = await fetchTemplateManifest(templateId, localPath).catch(() => null);
+        const defaultValues = templateManifest ? templateManifest.defaultModules.filter((d) => availableModules.some((m) => m.name === d)) : [];
+        const pickerOptions = availableModules.map((m) => ({
+          value: m.name,
+          label: m.name,
+          ...m.description !== void 0 ? { hint: m.description } : {}
+        }));
+        const picked = await p10.multiselect({
+          message: "Select modules to install (space to toggle, enter to confirm):",
+          options: pickerOptions,
+          initialValues: defaultValues,
+          required: false
+        });
+        if (p10.isCancel(picked)) {
+          p10.cancel("Cancelled.");
+          process.exit(0);
+        }
+        selectedModules = picked;
+      }
+    }
+  } else {
+    let presetManifest;
+    if (options.preset) {
+      const s = p10.spinner();
+      s.start(`Fetching preset "${options.preset}"...`);
+      try {
+        presetManifest = await fetchPresetManifest(options.preset, localPath);
+      } catch (err) {
+        s.stop("Failed to fetch preset.");
+        p10.cancel(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+      s.stop(`Preset "${options.preset}" ready.`);
+    } else {
+      const s = p10.spinner();
+      s.start("Loading available presets...");
+      let presetIds;
+      try {
+        presetIds = await listAvailablePresets(localPath);
+      } catch {
+        presetIds = ["saas"];
+      }
+      s.stop("Presets loaded.");
+      let selectedPresetId;
+      if (presetIds.length > 1) {
+        const presetDetails = await Promise.all(
+          presetIds.map(async (id) => {
+            try {
+              const m = await fetchPresetManifest(id, localPath);
+              return { id, description: m.description };
+            } catch {
+              return { id, description: "" };
+            }
+          })
+        );
+        const selected = await p10.select({
+          message: "Select a preset:",
+          options: presetDetails.map(({ id, description }) => ({
+            value: id,
+            label: id,
+            ...description ? { hint: description } : {}
+          })),
+          initialValue: "saas"
+        });
+        if (p10.isCancel(selected)) {
+          p10.cancel("Cancelled.");
+          process.exit(0);
+        }
+        selectedPresetId = selected;
+      } else {
+        selectedPresetId = presetIds[0] ?? "saas";
+        p10.log.info(`Using preset: ${selectedPresetId}`);
+      }
+      const s22 = p10.spinner();
+      s22.start(`Fetching preset "${selectedPresetId}"...`);
+      try {
+        presetManifest = await fetchPresetManifest(selectedPresetId, localPath);
+      } catch (err) {
+        s22.stop("Failed to fetch preset.");
+        p10.cancel(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+      s22.stop(`Preset "${selectedPresetId}" ready.`);
+      if (!options.modules && presetManifest.optionalModules.length > 0) {
+        const optionalSelected = await p10.multiselect({
+          message: `Optional modules for "${selectedPresetId}" (space to toggle, enter to skip):`,
+          options: presetManifest.optionalModules.map((id) => ({
+            value: id,
+            label: id
+          })),
+          required: false
+        });
+        if (p10.isCancel(optionalSelected)) {
+          p10.cancel("Cancelled.");
+          process.exit(0);
+        }
+        selectedModules = [
+          ...presetManifest.defaultModules,
+          ...optionalSelected
+        ];
+      } else if (!options.modules) {
+        selectedModules = presetManifest.defaultModules;
+      }
+    }
+    templateId = presetManifest.template;
+    if (options.preset && !options.modules) {
+      selectedModules = presetManifest.defaultModules;
+    }
+  }
+  const s2 = p10.spinner();
+  s2.start(`Fetching template "${templateId}"...`);
+  let manifest;
+  try {
+    manifest = await fetchTemplateManifest(templateId, localPath);
+  } catch (err) {
+    s2.stop("Failed to fetch template.");
+    p10.cancel(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  s2.stop(`Template "${templateId}" ready.`);
+  p10.log.message(`
+Stack: ${manifest.stack.join(", ")}`);
+  const s4 = p10.spinner();
+  s4.start(`Scaffolding "${projectName}"...`);
+  try {
+    for (const file of manifest.files) {
+      const content = await fetchTemplateFile(templateId, file.src, localPath);
+      const destPath = path15.join(targetDir, file.dest);
+      await outputFile7(destPath, content, "utf-8");
+    }
+    const pkgPath = path15.join(targetDir, "package.json");
+    if (existsSync2(pkgPath)) {
+      const { readJson: readJson6, writeJson: writeJson2 } = fsExtra16;
+      const pkg = await readJson6(pkgPath);
+      if (pkg && typeof pkg === "object") {
+        pkg["name"] = projectName;
+        await writeJson2(pkgPath, pkg, { spaces: 2 });
+      }
+    }
+  } catch (err) {
+    s4.stop("Scaffold failed.");
+    p10.cancel(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  s4.stop(`Project scaffolded at ./${projectName}`);
+  p10.log.step("Initializing impulse...");
+  await runInit({ cwd: targetDir, force: false, skipDetection: true });
+  if (selectedModules.length > 0) {
+    p10.log.step(`Installing modules: ${selectedModules.join(", ")}`);
+    await runAdd({
+      moduleNames: selectedModules,
+      cwd: targetDir,
+      dryRun: false,
+      ...localPath !== void 0 ? { localPath } : {},
+      allowScripts: false,
+      skipIntro: true,
+      skipAuth: true
+    });
+  }
+  const hasPnpmLock = await pathExists15(path15.join(targetDir, "pnpm-lock.yaml"));
+  const pm = hasPnpmLock ? "pnpm" : existsSync2(path15.join(targetDir, "yarn.lock")) ? "yarn" : "pnpm";
+  const s5 = p10.spinner();
+  s5.start(`Running ${pm} install...`);
+  try {
+    execFileSync3(pm, ["install"], { cwd: targetDir, stdio: "pipe" });
+    s5.stop("Dependencies installed.");
+  } catch {
+    s5.stop(`${pm} install failed \u2014 run it manually.`);
+    p10.log.warn(`Run \`cd ${projectName} && ${pm} install\` to install dependencies.`);
+  }
+  const s6 = p10.spinner();
+  s6.start("Initializing git repository...");
+  try {
+    execFileSync3("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+    execFileSync3("git", ["add", "-A"], { cwd: targetDir, stdio: "pipe" });
+    execFileSync3(
+      "git",
+      ["commit", "-m", `feat: initial project from impulse create (${templateId} template)`],
+      { cwd: targetDir, stdio: "pipe" }
+    );
+    s6.stop("Git repository initialized.");
+  } catch {
+    s6.stop("Git init failed \u2014 skipping.");
+    p10.log.warn(`Run \`git init && git add -A && git commit -m "init"\` manually.`);
+  }
+  p10.outro(
+    `
+Project "${projectName}" created successfully!
+
+  cd ${projectName}
+  ${pm} dev
+
+Add more modules anytime with \`impulse add\`.`
+  );
+}
+
 // src/cli-version.ts
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
@@ -1501,6 +2021,19 @@ program.command("list").description("List available and installed modules").opti
   if (options.local !== void 0) listOpts.localPath = options.local;
   await runList(listOpts);
 });
+program.command("create [name]").description(
+  "Create a new project from a preset or template.\n  No args: interactive prompts for name, preset, and optional modules\n  With preset: `create my-app --preset saas`\n  With template (advanced): `create my-app --template saas`\n  With modules: `create my-app --preset minimal --modules auth,ui`"
+).option("--preset <preset>", "Preset to use (omit for interactive selection)").option("--template <template>", "Template override \u2014 bypasses preset selection (advanced)").option("--modules <modules>", "Comma-separated modules to install after scaffolding").option("--local <path>", "Use a local presets/templates/modules directory (for development)").action(async (name, options) => {
+  const moduleList = options.modules !== void 0 ? options.modules.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  await runCreate({
+    cwd: process.cwd(),
+    ...name !== void 0 ? { projectName: name } : {},
+    ...options.preset !== void 0 ? { preset: options.preset } : {},
+    ...options.template !== void 0 ? { template: options.template } : {},
+    ...moduleList !== void 0 ? { modules: moduleList } : {},
+    ...options.local !== void 0 ? { localPath: options.local } : {}
+  });
+});
 program.command("login").description("Authenticate with ImpulseLab (opens browser for device flow)").action(async () => {
   await runLogin();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impulselab/cli",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "ImpulseLab CLI — install and manage modules for your projects",
   "private": false,
   "type": "module",