@impulselab/cli 0.1.2 → 0.1.4

package/dist/index.js

@@ -197,8 +197,8 @@ async function runInit(options) {
 // src/commands/add.ts
 import { execSync as execSync2, execFileSync } from "child_process";
 import { existsSync } from "fs";
-import path11 from "path";
-import * as p4 from "@clack/prompts";
+import path12 from "path";
+import * as p5 from "@clack/prompts";
 
 // src/registry/fetch-module-manifest.ts
 import fsExtra5 from "fs-extra";
@@ -211,7 +211,11 @@ import { z as z5 } from "zod";
 import { z as z2 } from "zod";
 var ModuleFileSchema = z2.object({
   src: z2.string(),
-  dest: z2.string()
+  dest: z2.string(),
+  /** If set, this file is only installed when the named module is already installed. */
+  when: z2.object({
+    moduleInstalled: z2.string()
+  }).optional()
 });
 
 // src/schemas/module-dependency.ts
@@ -243,11 +247,21 @@ var ModuleManifestSchema = z5.object({
   subModules: z5.array(z5.string()).default([]),
   dependencies: z5.array(ModuleDependencySchema).default([]),
   moduleDependencies: z5.array(z5.string()).default([]),
+  /** Optional module dependencies that enhance this module but are not required. */
+  optionalModuleDependencies: z5.array(z5.string()).default([]),
   files: z5.array(ModuleFileSchema).default([]),
   transforms: z5.array(ModuleTransformSchema).default([]),
   /** Documentation metadata listing env vars this module requires (displayed in install summary). */
   envVars: z5.array(z5.string()).default([]),
-  postInstall: z5.array(z5.string()).optional()
+  postInstall: z5.array(z5.string()).optional(),
+  /** Logical category for grouping in `impulse list`. */
+  category: z5.enum(["core", "feature", "integration", "dx"]).optional(),
+  /** Module names that cannot be installed alongside this module. */
+  incompatibleWith: z5.array(z5.string()).default([]),
+  /** Capability tokens this module provides (for future dependency resolution). */
+  provides: z5.array(z5.string()).default([]),
+  /** Which package in a monorepo this module targets. */
+  targetPackage: z5.enum(["database", "server", "web", "root"]).default("root")
 });
 
 // src/registry/github-urls.ts
@@ -364,7 +378,8 @@ async function listAvailableModules(localPath) {
         result.push({
           name: parsed.data.name,
           description: parsed.data.description,
-          ...subModules ? { subModules } : {}
+          ...subModules ? { subModules } : {},
+          ...parsed.data.category ? { category: parsed.data.category } : {}
         });
       } catch {
       }
@@ -432,9 +447,17 @@ import path5 from "path";
 import * as p2 from "@clack/prompts";
 var { outputFile, pathExists: pathExists6 } = fsExtra7;
 async function installFiles(options) {
-  const { moduleName, files, cwd, dryRun, localPath } = options;
+  const { moduleName, files, cwd, dryRun, localPath, installedModules = /* @__PURE__ */ new Set() } = options;
   const results = [];
   for (const file of files) {
+    if (file.when?.moduleInstalled !== void 0 && !installedModules.has(file.when.moduleInstalled)) {
+      results.push({
+        dest: file.dest,
+        action: "conditional-skip",
+        reason: `requires ${file.when.moduleInstalled}`
+      });
+      continue;
+    }
     const destAbs = path5.join(cwd, file.dest);
     const exists = await pathExists6(destAbs);
     if (exists) {
@@ -652,6 +675,54 @@ 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";
+function authPath() {
+  return path11.join(os.homedir(), ".impulselab", "auth.json");
+}
+
+// src/schemas/auth-credentials.ts
+import { z as z6 } from "zod";
+var AuthCredentialsSchema = z6.object({
+  token: z6.string(),
+  refreshToken: z6.string().optional(),
+  expiresAt: z6.string().optional(),
+  email: z6.string()
+});
+
+// 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;
+}
+
+// src/auth/require-auth.ts
+async function requireAuth() {
+  const credentials = await readAuth();
+  if (!credentials) {
+    p4.cancel("Not authenticated. Run `impulse login` first.");
+    process.exit(1);
+  }
+  return credentials;
+}
+
 // src/commands/add.ts
 async function resolveModuleDeps(moduleId, localPath, resolved, orderedModules) {
   if (resolved.has(moduleId)) return;
@@ -670,48 +741,62 @@ async function resolveWithParent(moduleId, localPath, installedNames, resolved,
   await resolveModuleDeps(moduleId, localPath, resolved, orderedModules);
 }
 function detectPackageManager(cwd) {
-  if (existsSync(path11.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(path11.join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(path12.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(path12.join(cwd, "yarn.lock"))) return "yarn";
   return "npm";
 }
+function isPnpmMonorepo(cwd) {
+  return existsSync(path12.join(cwd, "pnpm-workspace.yaml"));
+}
 function installNpmDeps(deps, cwd, dryRun) {
   if (deps.length === 0) return;
   const pm = detectPackageManager(cwd);
-  const args = ["add", ...deps];
+  const isMonorepo = pm === "pnpm" && isPnpmMonorepo(cwd);
+  const args = isMonorepo ? ["-w", "add", ...deps] : ["add", ...deps];
   if (dryRun) {
-    p4.log.info(`[dry-run] Would run: ${pm} ${args.join(" ")}`);
+    p5.log.info(`[dry-run] Would run: ${pm} ${args.join(" ")}`);
     return;
   }
-  p4.log.step(`Installing dependencies: ${deps.join(", ")}`);
+  p5.log.step(`Installing dependencies: ${deps.join(", ")}`);
   execFileSync(pm, args, { cwd, stdio: "inherit" });
 }
-async function installModule(moduleId, manifest, cwd, dryRun, localPath) {
-  p4.log.step(`Installing ${moduleId}@${manifest.version}...`);
+async function installModule(moduleId, manifest, cwd, dryRun, installedModules, localPath) {
+  p5.log.step(`Installing ${moduleId}@${manifest.version}...`);
+  const installedDests = [];
   if (manifest.files.length > 0) {
     const installed = await installFiles({
       moduleName: moduleId,
       files: manifest.files,
       cwd,
       dryRun,
-      localPath
+      localPath,
+      installedModules
     });
     for (const f of installed) {
+      if (f.action === "conditional-skip") {
+        if (dryRun) {
+          p5.log.message(`  \u25CB ${f.dest} [skipped: ${f.reason}]`);
+        }
+        continue;
+      }
+      installedDests.push(f.dest);
       const icon = f.action === "created" || f.action === "would-create" ? "+" : f.action === "overwritten" || f.action === "would-overwrite" ? "~" : "=";
-      p4.log.message(`  ${icon} ${f.dest}`);
+      p5.log.message(`  ${icon} ${f.dest}`);
     }
   }
   for (const transform of manifest.transforms) {
-    p4.log.step(`  transform: ${transform.type} \u2192 ${transform.target}`);
+    p5.log.step(`  transform: ${transform.type} \u2192 ${transform.target}`);
     await runTransform(transform, cwd, dryRun);
   }
+  return installedDests;
 }
-function recordModule(config, moduleId, manifest, now) {
+function recordModule(config, moduleId, manifest, installedFiles, now) {
   const existing = config.installedModules.findIndex((m) => m.name === moduleId);
   const record = {
     name: moduleId,
     version: manifest.version,
     installedAt: now,
-    files: manifest.files.map((f) => f.dest)
+    files: installedFiles
   };
   if (existing >= 0) {
     config.installedModules[existing] = record;
@@ -719,48 +804,125 @@ function recordModule(config, moduleId, manifest, now) {
     config.installedModules.push(record);
   }
 }
+async function pickModulesInteractively(localPath) {
+  const s = p5.spinner();
+  s.start("Loading available modules...");
+  let modules;
+  try {
+    modules = await listAvailableModules(localPath);
+  } catch (err) {
+    s.stop("Failed to load modules.");
+    throw err;
+  }
+  s.stop("Modules loaded.");
+  if (modules.length === 0) {
+    p5.log.warn("No modules available.");
+    return [];
+  }
+  const options = [];
+  for (const mod of modules) {
+    options.push({
+      value: mod.name,
+      label: mod.name,
+      ...mod.description !== void 0 ? { hint: mod.description } : {}
+    });
+    for (const sub of mod.subModules ?? []) {
+      options.push({
+        value: `${mod.name}/${sub}`,
+        label: `  \u21B3 ${sub}`,
+        hint: `sub-module of ${mod.name}`
+      });
+    }
+  }
+  const selected = await p5.multiselect({
+    message: "Select modules to install:",
+    options,
+    required: true
+  });
+  if (p5.isCancel(selected)) {
+    p5.outro("Cancelled.");
+    process.exit(0);
+  }
+  const result = new Set(selected);
+  for (const id of selected) {
+    const { parent, child } = parseModuleId(id);
+    if (child !== null) {
+      result.add(parent);
+    }
+  }
+  return [...result];
+}
 async function runAdd(options) {
-  const { moduleName, cwd, dryRun, localPath, withSubModules = [] } = options;
-  const withIds = withSubModules.map((sub) => `${moduleName}/${sub}`);
-  const allTargets = [moduleName, ...withIds];
-  p4.intro(`impulse add ${allTargets.join(", ")}${dryRun ? " [dry-run]" : ""}`);
+  let { moduleNames, cwd, dryRun, localPath, withSubModules = [] } = options;
+  let allTargets;
+  if (moduleNames.length === 0) {
+    p5.intro(`impulse add${dryRun ? " [dry-run]" : ""}`);
+    await requireAuth();
+    if (withSubModules.length > 0) {
+      p5.log.warn(`--with is ignored in interactive mode. Select sub-modules from the picker.`);
+      withSubModules = [];
+    }
+    const picked = await pickModulesInteractively(localPath);
+    if (picked.length === 0) {
+      p5.outro("Nothing selected.");
+      return;
+    }
+    allTargets = picked;
+  } else {
+    if (moduleNames.length > 1 && withSubModules.length > 0) {
+      p5.log.warn(
+        `--with is ignored when multiple modules are provided. Specify a single module to use --with.`
+      );
+    }
+    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();
+  }
   const config = await readConfig(cwd);
   if (!config) {
-    p4.cancel("No .impulse.json found. Run `impulse init` first.");
+    p5.cancel("No .impulse.json found. Run `impulse init` first.");
     process.exit(1);
   }
   const installedNames = new Set(config.installedModules.map((m) => m.name));
-  const { child: mainChild } = parseModuleId(moduleName);
-  if (mainChild === null && withSubModules.length === 0 && installedNames.has(moduleName)) {
-    const existing = config.installedModules.find((m) => m.name === moduleName);
-    p4.log.warn(`Module "${moduleName}" is already installed (v${existing?.version ?? "?"}).`);
-    const reinstall = await p4.confirm({
-      message: "Reinstall?",
-      initialValue: false
+  if (withSubModules.length === 0) {
+    const alreadyInstalled = allTargets.filter((id) => {
+      const { child } = parseModuleId(id);
+      return child === null && installedNames.has(id);
     });
-    if (p4.isCancel(reinstall) || !reinstall) {
-      p4.outro("Cancelled.");
-      return;
+    if (alreadyInstalled.length > 0) {
+      for (const id of alreadyInstalled) {
+        const existing = config.installedModules.find((m) => m.name === id);
+        p5.log.warn(`Module "${id}" is already installed (v${existing?.version ?? "?"}).`);
+      }
+      const reinstall = await p5.confirm({
+        message: alreadyInstalled.length === 1 ? "Reinstall?" : "Reinstall all?",
+        initialValue: false
+      });
+      if (p5.isCancel(reinstall) || !reinstall) {
+        p5.outro("Cancelled.");
+        return;
+      }
     }
   }
-  if (withSubModules.length > 0) {
-    const parentManifest = await fetchModuleManifest(moduleName, localPath).catch(() => null);
+  if (moduleNames.length === 1 && withSubModules.length > 0) {
+    const parentManifest = await fetchModuleManifest(moduleNames[0], localPath).catch(() => null);
     if (parentManifest) {
       if (parentManifest.subModules.length === 0) {
-        p4.cancel(`"${moduleName}" has no declared sub-modules.`);
+        p5.cancel(`"${moduleNames[0]}" has no declared sub-modules.`);
         process.exit(1);
       }
       const invalid = withSubModules.filter((sub) => !parentManifest.subModules.includes(sub));
       if (invalid.length > 0) {
-        p4.cancel(
-          `Unknown sub-module(s) for "${moduleName}": ${invalid.join(", ")}.
+        p5.cancel(
+          `Unknown sub-module(s) for "${moduleNames[0]}": ${invalid.join(", ")}.
 Available: ${parentManifest.subModules.join(", ")}`
         );
         process.exit(1);
       }
     }
   }
-  const s = p4.spinner();
+  const s = p5.spinner();
   s.start("Resolving dependencies...");
   const resolved = /* @__PURE__ */ new Set();
   const orderedModules = [];
@@ -770,7 +932,7 @@ Available: ${parentManifest.subModules.join(", ")}`
     }
   } catch (err) {
     s.stop("Dependency resolution failed.");
-    p4.cancel(err instanceof Error ? err.message : String(err));
+    p5.cancel(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
   s.stop(`Resolved: ${orderedModules.join(" \u2192 ")}`);
@@ -778,21 +940,34 @@ Available: ${parentManifest.subModules.join(", ")}`
   for (const id of orderedModules) {
     manifests.set(id, await fetchModuleManifest(id, localPath));
   }
+  for (const [id, manifest] of manifests) {
+    if (installedNames.has(id)) continue;
+    for (const incompatible of manifest.incompatibleWith) {
+      if (installedNames.has(incompatible)) {
+        p5.cancel(`Module "${id}" is incompatible with installed module "${incompatible}".`);
+        process.exit(1);
+      }
+      if (manifests.has(incompatible) && !installedNames.has(incompatible)) {
+        p5.cancel(`Module "${id}" is incompatible with module "${incompatible}" (also being installed).`);
+        process.exit(1);
+      }
+    }
+  }
   const allDeps = /* @__PURE__ */ new Set();
   for (const manifest of manifests.values()) {
     for (const dep of manifest.dependencies) {
       allDeps.add(dep);
     }
   }
-  p4.log.message("\nSummary of changes:");
+  p5.log.message("\nSummary of changes:");
   for (const [id, manifest] of manifests) {
-    p4.log.message(`
+    p5.log.message(`
   Module: ${id}@${manifest.version}`);
     for (const file of manifest.files) {
-      p4.log.message(`    + ${file.dest}`);
+      p5.log.message(`    + ${file.dest}`);
     }
     for (const transform of manifest.transforms) {
-      p4.log.message(`    ~ ${transform.type} \u2192 ${transform.target}`);
+      p5.log.message(`    ~ ${transform.type} \u2192 ${transform.target}`);
     }
   }
   const allEnvVars = /* @__PURE__ */ new Set();
@@ -802,33 +977,36 @@ Available: ${parentManifest.subModules.join(", ")}`
     }
   }
   if (allDeps.size > 0) {
-    p4.log.message(`
+    p5.log.message(`
   npm deps: ${[...allDeps].join(", ")}`);
   }
   if (allEnvVars.size > 0) {
-    p4.log.message(`
+    p5.log.message(`
   env vars required: ${[...allEnvVars].join(", ")}`);
   }
   if (!dryRun) {
-    const confirm4 = await p4.confirm({
+    const confirm6 = await p5.confirm({
       message: "Proceed?",
       initialValue: true
     });
-    if (p4.isCancel(confirm4) || !confirm4) {
-      p4.outro("Cancelled.");
+    if (p5.isCancel(confirm6) || !confirm6) {
+      p5.outro("Cancelled.");
       return;
     }
   }
   const primaryTargetSet = new Set(allTargets);
   const depModules = orderedModules.filter((id) => !primaryTargetSet.has(id) && !installedNames.has(id));
   const targetModules = orderedModules.filter((id) => primaryTargetSet.has(id));
+  const installedFilesMap = /* @__PURE__ */ new Map();
   const depPostInstallHooks = [];
   if (depModules.length > 0) {
-    p4.log.step(`Installing module dependencies: ${depModules.join(", ")}`);
+    p5.log.step(`Installing module dependencies: ${depModules.join(", ")}`);
     for (const dep of depModules) {
       const depManifest = manifests.get(dep);
       if (!depManifest) continue;
-      await installModule(dep, depManifest, cwd, dryRun, localPath);
+      const dests = await installModule(dep, depManifest, cwd, dryRun, installedNames, localPath);
+      installedFilesMap.set(dep, dests);
+      installedNames.add(dep);
       if (depManifest.postInstall && depManifest.postInstall.length > 0) {
         depPostInstallHooks.push({ name: dep, hooks: depManifest.postInstall });
       }
@@ -837,14 +1015,16 @@ Available: ${parentManifest.subModules.join(", ")}`
   for (const targetId of targetModules) {
     const targetManifest = manifests.get(targetId);
     if (!targetManifest) continue;
-    await installModule(targetId, targetManifest, cwd, dryRun, localPath);
+    const dests = await installModule(targetId, targetManifest, cwd, dryRun, installedNames, localPath);
+    installedFilesMap.set(targetId, dests);
+    installedNames.add(targetId);
   }
   installNpmDeps([...allDeps], cwd, dryRun);
   if (!dryRun) {
     for (const { name, hooks } of depPostInstallHooks) {
-      p4.log.step(`Running post-install hooks for ${name}...`);
+      p5.log.step(`Running post-install hooks for ${name}...`);
       for (const hook of hooks) {
-        p4.log.message(`  $ ${hook}`);
+        p5.log.message(`  $ ${hook}`);
         execSync2(hook, { cwd, stdio: "inherit" });
       }
     }
@@ -853,9 +1033,9 @@ Available: ${parentManifest.subModules.join(", ")}`
     for (const targetId of targetModules) {
       const targetManifest = manifests.get(targetId);
       if (!targetManifest?.postInstall?.length) continue;
-      p4.log.step(`Running post-install hooks for ${targetId}...`);
+      p5.log.step(`Running post-install hooks for ${targetId}...`);
       for (const hook of targetManifest.postInstall) {
-        p4.log.message(`  $ ${hook}`);
+        p5.log.message(`  $ ${hook}`);
         execSync2(hook, { cwd, stdio: "inherit" });
       }
     }
@@ -864,72 +1044,328 @@ Available: ${parentManifest.subModules.join(", ")}`
     const now = (/* @__PURE__ */ new Date()).toISOString();
     for (const dep of depModules) {
       const depManifest = manifests.get(dep);
-      if (depManifest) recordModule(config, dep, depManifest, now);
+      const dests = installedFilesMap.get(dep) ?? [];
+      if (depManifest) recordModule(config, dep, depManifest, dests, now);
     }
     for (const targetId of targetModules) {
       const targetManifest = manifests.get(targetId);
-      if (targetManifest) recordModule(config, targetId, targetManifest, now);
+      const dests = installedFilesMap.get(targetId) ?? [];
+      if (targetManifest) recordModule(config, targetId, targetManifest, dests, now);
     }
     await writeConfig(config, cwd);
   }
   const label = allTargets.length === 1 ? `"${allTargets[0]}"` : allTargets.map((t) => `"${t}"`).join(", ");
-  p4.outro(
+  p5.outro(
     dryRun ? "Dry run complete \u2014 no files were modified." : `Module(s) ${label} installed successfully!`
   );
 }
 
 // src/commands/list.ts
-import * as p5 from "@clack/prompts";
+import * as p6 from "@clack/prompts";
+function printModule(mod, installedNames, installedModules) {
+  const installed = installedNames.has(mod.name);
+  const installedInfo = installed ? installedModules?.find((m) => m.name === mod.name) : null;
+  const status = installed ? `[installed v${installedInfo?.version ?? "?"}]` : "[available]";
+  const desc = mod.description ? ` \u2014 ${mod.description}` : "";
+  p6.log.message(`  ${installed ? "\u2713" : "\u25CB"} ${mod.name} ${status}${desc}`);
+  if (mod.subModules && mod.subModules.length > 0) {
+    const last = mod.subModules.length - 1;
+    mod.subModules.forEach((sub, i) => {
+      const subId = `${mod.name}/${sub}`;
+      const subInstalled = installedNames.has(subId);
+      const subInfo = subInstalled ? installedModules?.find((m) => m.name === subId) : null;
+      const subStatus = subInstalled ? `[installed v${subInfo?.version ?? "?"}]` : "[not installed]";
+      const connector = i === last ? "\u2514\u2500" : "\u251C\u2500";
+      p6.log.message(`    ${connector} ${sub} ${subStatus}`);
+    });
+  }
+}
 async function runList(options) {
   const { cwd, localPath } = options;
-  p5.intro("impulse list");
+  p6.intro("impulse list");
+  await requireAuth();
   const config = await readConfig(cwd);
   const installedNames = new Set(
     config?.installedModules.map((m) => m.name) ?? []
   );
-  const s = p5.spinner();
+  const s = p6.spinner();
   s.start("Fetching available modules...");
   let available;
   try {
     available = await listAvailableModules(localPath);
   } catch (err) {
     s.stop("Failed to fetch module list.");
-    p5.cancel(err instanceof Error ? err.message : String(err));
+    p6.cancel(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
   s.stop(`Found ${available.length} module(s).`);
   if (available.length === 0) {
-    p5.log.message("No modules available yet.");
-    p5.outro("Done.");
+    p6.log.message("No modules available yet.");
+    p6.outro("Done.");
     return;
   }
-  p5.log.message("\nAvailable modules:\n");
-  for (const mod of available) {
-    const installed = installedNames.has(mod.name);
-    const installedInfo = installed ? config?.installedModules.find((m) => m.name === mod.name) : null;
-    const status = installed ? `[installed v${installedInfo?.version ?? "?"}]` : "[available]";
-    const desc = mod.description ? ` \u2014 ${mod.description}` : "";
-    p5.log.message(`  ${installed ? "\u2713" : "\u25CB"} ${mod.name} ${status}${desc}`);
-    if (mod.subModules && mod.subModules.length > 0) {
-      const last = mod.subModules.length - 1;
-      mod.subModules.forEach((sub, i) => {
-        const subId = `${mod.name}/${sub}`;
-        const subInstalled = installedNames.has(subId);
-        const subInfo = subInstalled ? config?.installedModules.find((m) => m.name === subId) : null;
-        const subStatus = subInstalled ? `[installed v${subInfo?.version ?? "?"}]` : "[not installed]";
-        const connector = i === last ? "\u2514\u2500" : "\u251C\u2500";
-        p5.log.message(`    ${connector} ${sub} ${subStatus}`);
-      });
+  p6.log.message("\nAvailable modules:\n");
+  const hasCategories = available.some((m) => m.category !== void 0);
+  if (hasCategories) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const mod of available) {
+      const key = mod.category ?? "other";
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(mod);
+      } else {
+        groups.set(key, [mod]);
+      }
+    }
+    const categoryOrder = ["core", "feature", "integration", "dx", "other"];
+    const sortedKeys = [
+      ...categoryOrder.filter((k) => groups.has(k)),
+      ...[...groups.keys()].filter((k) => !categoryOrder.includes(k))
+    ];
+    for (const key of sortedKeys) {
+      p6.log.message(`${key.toUpperCase()}`);
+      for (const mod of groups.get(key)) {
+        printModule(mod, installedNames, config?.installedModules);
+      }
+      p6.log.message("");
+    }
+  } else {
+    for (const mod of available) {
+      printModule(mod, installedNames, config?.installedModules);
     }
   }
-  p5.log.message(
+  p6.log.message(
     `
 Run \`impulse add <module>\` to install a module.`
   );
-  p5.log.message(
+  p6.log.message(
     `Run \`impulse add <parent>/<sub>\` or \`impulse add <parent> --with <sub1>,<sub2>\` for sub-modules.`
   );
-  p5.outro("Done.");
+  p6.outro("Done.");
+}
+
+// src/commands/login.ts
+import * as p7 from "@clack/prompts";
+
+// src/auth/device-flow.ts
+import { execFileSync as execFileSync2 } from "child_process";
+var IMPULSE_BASE_URL = process.env.IMPULSE_BASE_URL ?? "https://impulse.studio";
+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: "impulse-cli" })
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to initiate device flow: ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  assertDeviceCodeResponse(data);
+  return data;
+}
+async function pollDeviceToken(deviceCode) {
+  let res;
+  try {
+    res = await fetch(`${IMPULSE_BASE_URL}/api/auth/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ deviceCode })
+    });
+  } catch {
+    return { status: "error", message: "Network error while polling for token" };
+  }
+  if (res.status === 200) {
+    const data = await res.json();
+    assertDeviceTokenResponse(data);
+    return { status: "authorized", data };
+  }
+  if (res.status === 202) {
+    return { status: "pending" };
+  }
+  if (res.status === 400) {
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      body = {};
+    }
+    const error = typeof body === "object" && body !== null && "error" in body ? String(body.error) : "";
+    if (error === "slow_down") return { status: "slow_down" };
+    if (error === "expired" || error === "authorization_expired") return { status: "expired" };
+    return { status: "error", message: error || "Device code error" };
+  }
+  return { status: "error", message: `Unexpected response: ${res.status}` };
+}
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      execFileSync2("open", [url]);
+    } else if (platform === "win32") {
+      execFileSync2("cmd", ["/c", "start", url]);
+    } else {
+      execFileSync2("xdg-open", [url]);
+    }
+  } catch {
+  }
+}
+function assertDeviceCodeResponse(data) {
+  if (typeof data !== "object" || data === null || typeof data.deviceCode !== "string" || typeof data.userCode !== "string" || typeof data.verificationUri !== "string") {
+    throw new Error("Invalid device code response from server");
+  }
+}
+function assertDeviceTokenResponse(data) {
+  if (typeof data !== "object" || data === null || typeof data.token !== "string" || typeof data.email !== "string") {
+    throw new Error("Invalid token response from server");
+  }
+}
+
+// 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);
+}
+
+// src/commands/login.ts
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var MAX_POLL_DURATION_MS = 5 * 60 * 1e3;
+async function runLogin() {
+  p7.intro("impulse login");
+  const existing = await readAuth();
+  if (existing) {
+    const reauth = await p7.confirm({
+      message: `Already logged in as ${existing.email}. Log in again?`,
+      initialValue: false
+    });
+    if (p7.isCancel(reauth) || !reauth) {
+      p7.outro("Cancelled.");
+      return;
+    }
+  }
+  const s = p7.spinner();
+  s.start("Initiating login...");
+  let deviceCode;
+  try {
+    deviceCode = await requestDeviceCode();
+  } catch (err) {
+    s.stop("Failed to initiate login.");
+    p7.cancel(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  s.stop("Opening browser for authentication...");
+  const browserUrl = deviceCode.verificationUri;
+  p7.log.message(`
+Visit the following URL to authenticate:
+  ${browserUrl}
+`);
+  p7.log.message(`Your one-time code: ${deviceCode.userCode}
+`);
+  openBrowser(browserUrl);
+  p7.log.info(`If the browser did not open, copy the URL above.
+Base URL: ${IMPULSE_BASE_URL}`);
+  const pollInterval = Math.max(
+    (deviceCode.interval ?? 5) * 1e3,
+    DEFAULT_POLL_INTERVAL_MS
+  );
+  const expiresAt = Date.now() + (deviceCode.expiresIn ?? 300) * 1e3;
+  const deadline = Math.min(expiresAt, Date.now() + MAX_POLL_DURATION_MS);
+  const pollSpinner = p7.spinner();
+  pollSpinner.start("Waiting for authentication...");
+  let currentInterval = pollInterval;
+  while (Date.now() < deadline) {
+    await sleep(currentInterval);
+    const result = await pollDeviceToken(deviceCode.deviceCode);
+    if (result.status === "authorized") {
+      pollSpinner.stop("Authentication successful!");
+      await writeAuth({
+        token: result.data.token,
+        refreshToken: result.data.refreshToken,
+        expiresAt: result.data.expiresAt,
+        email: result.data.email
+      });
+      p7.outro(`Logged in as ${result.data.email}`);
+      return;
+    }
+    if (result.status === "slow_down") {
+      currentInterval += 5e3;
+      continue;
+    }
+    if (result.status === "expired") {
+      pollSpinner.stop("Device code expired.");
+      p7.cancel("Authentication timed out. Run `impulse login` again.");
+      process.exit(1);
+    }
+    if (result.status === "error") {
+      pollSpinner.stop("Authentication failed.");
+      p7.cancel(result.message);
+      process.exit(1);
+    }
+  }
+  pollSpinner.stop("Authentication timed out.");
+  p7.cancel("Authentication timed out. Run `impulse login` again.");
+  process.exit(1);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/commands/logout.ts
+import * as p8 from "@clack/prompts";
+
+// src/auth/clear-auth.ts
+import fsExtra15 from "fs-extra";
+var { remove, pathExists: pathExists13 } = fsExtra15;
+async function clearAuth() {
+  const file = authPath();
+  if (!await pathExists13(file)) return false;
+  await remove(file);
+  return true;
+}
+
+// src/commands/logout.ts
+async function runLogout() {
+  p8.intro("impulse logout");
+  const credentials = await readAuth();
+  if (!credentials) {
+    p8.outro("Not currently logged in.");
+    return;
+  }
+  const confirm6 = await p8.confirm({
+    message: `Log out ${credentials.email}?`,
+    initialValue: true
+  });
+  if (p8.isCancel(confirm6) || !confirm6) {
+    p8.outro("Cancelled.");
+    return;
+  }
+  await clearAuth();
+  p8.outro("Logged out successfully.");
+}
+
+// src/commands/whoami.ts
+import * as p9 from "@clack/prompts";
+async function runWhoami() {
+  p9.intro("impulse whoami");
+  const credentials = await readAuth();
+  if (!credentials) {
+    p9.cancel("Not authenticated. Run `impulse login` first.");
+    process.exit(1);
+  }
+  p9.log.message(`Logged in as: ${credentials.email}`);
+  if (credentials.expiresAt) {
+    const expires = new Date(credentials.expiresAt);
+    const now = /* @__PURE__ */ new Date();
+    if (expires < now) {
+      p9.log.warn("Your session has expired. Run `impulse login` to re-authenticate.");
+    } else {
+      p9.log.message(`Session expires: ${expires.toLocaleString()}`);
+    }
+  }
+  p9.outro("Done.");
 }
 
 // src/cli-version.ts
@@ -943,17 +1379,17 @@ program.name("impulse").description("ImpulseLab CLI \u2014 install and manage mo
 program.command("init").description("Initialize impulse in the current project").option("--force", "Reinitialize even if .impulse.json already exists", false).action(async (options) => {
   await runInit({ cwd: process.cwd(), force: options.force });
 });
-program.command("add <module>").description(
-  "Add a module to the current project.\n  Supports sub-module syntax: `add attio/quote-to-cash`\n  Use --with to install multiple sub-modules at once: `add attio --with quote-to-cash,gocardless`"
+program.command("add [modules...]").description(
+  "Add module(s) to the current project.\n  No args: opens interactive multi-select picker\n  Single module: `add auth`\n  Multiple modules: `add auth attio/gocardless`\n  Sub-module syntax: `add attio/quote-to-cash`\n  Use --with to install multiple sub-modules at once: `add attio --with quote-to-cash,gocardless`"
 ).option("--dry-run", "Preview changes without writing files", false).option(
   "--local <path>",
   "Use a local modules directory (for development)"
 ).option(
   "--with <submodules>",
   "Comma-separated sub-modules to install alongside the parent (e.g. --with quote-to-cash,gocardless)"
-).action(async (moduleName, options) => {
+).action(async (modules, options) => {
   const addOpts = {
-    moduleName,
+    moduleNames: modules ?? [],
     cwd: process.cwd(),
     dryRun: options.dryRun
   };
@@ -971,4 +1407,13 @@ program.command("list").description("List available and installed modules").opti
   if (options.local !== void 0) listOpts.localPath = options.local;
   await runList(listOpts);
 });
+program.command("login").description("Authenticate with ImpulseLab (opens browser for device flow)").action(async () => {
+  await runLogin();
+});
+program.command("logout").description("Log out and clear stored credentials").action(async () => {
+  await runLogout();
+});
+program.command("whoami").description("Show the currently authenticated user").action(async () => {
+  await runWhoami();
+});
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impulselab/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "ImpulseLab CLI — install and manage modules for your projects",
   "private": false,
   "type": "module",
@@ -39,6 +39,7 @@
     "dev": "tsup src/index.ts --format esm --target es2022 --watch",
     "lint": "oxlint .",
     "test": "vitest run",
+    "release:publish": "pnpm run test && pnpm run build && pnpm publish --no-git-checks --access public",
     "release": "bumpp"
   }
 }