@impulselab/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,891 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import fsExtra4 from "fs-extra";
+import path2 from "path";
+import * as p from "@clack/prompts";
+
+// src/config/config-path.ts
+import path from "path";
+var CONFIG_FILE = ".impulse.json";
+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({
+  version: z.string().default("1"),
+  projectName: z.string(),
+  srcPath: z.string().default("src"),
+  dbPath: z.string().default("src/server/db"),
+  routesPath: z.string().default("src/server/api"),
+  installedModules: z.array(
+    z.object({
+      name: z.string(),
+      version: z.string(),
+      installedAt: z.string(),
+      files: z.array(z.string())
+    })
+  ).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);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid .impulse.json: ${parsed.error.message}`
+    );
+  }
+  return parsed.data;
+}
+
+// src/config/write-config.ts
+import fsExtra2 from "fs-extra";
+var { writeJson } = fsExtra2;
+async function writeConfig(config, cwd = process.cwd()) {
+  await writeJson(configPath(cwd), config, { spaces: 2 });
+}
+
+// src/config/has-config.ts
+import fsExtra3 from "fs-extra";
+var { pathExists: pathExists2 } = fsExtra3;
+async function hasConfig(cwd = process.cwd()) {
+  return pathExists2(configPath(cwd));
+}
+
+// src/commands/init.ts
+var { readJson: readJson2, pathExists: pathExists3 } = fsExtra4;
+var ULTIMATE_TEMPLATE_MARKERS = [
+  "@impulselab/ultimate-template",
+  "ultimate-template"
+];
+async function detectProjectName(cwd) {
+  const pkgPath = path2.join(cwd, "package.json");
+  if (await pathExists3(pkgPath)) {
+    const pkg = await readJson2(pkgPath);
+    if (pkg !== null && typeof pkg === "object" && "name" in pkg && typeof pkg.name === "string") {
+      return pkg.name;
+    }
+  }
+  return path2.basename(cwd);
+}
+async function isUltimateTemplate(cwd) {
+  const pkgPath = path2.join(cwd, "package.json");
+  if (!await pathExists3(pkgPath)) return false;
+  const raw = await readJson2(pkgPath);
+  if (!raw || typeof raw !== "object") return false;
+  const pkg = raw;
+  const name = typeof pkg["name"] === "string" ? pkg["name"] : "";
+  const keywords = Array.isArray(pkg["keywords"]) ? pkg["keywords"] : [];
+  const nameMatches = ULTIMATE_TEMPLATE_MARKERS.some((m) => name.includes(m));
+  const keywordMatches = ULTIMATE_TEMPLATE_MARKERS.some(
+    (m) => keywords.includes(m)
+  );
+  return nameMatches || keywordMatches;
+}
+async function runInit(options) {
+  const { cwd, force } = options;
+  p.intro("impulse init");
+  if (!force && await hasConfig(cwd)) {
+    p.log.warn(
+      ".impulse.json already exists. Run with --force to reinitialize."
+    );
+    p.outro("Already initialized.");
+    return;
+  }
+  const s = p.spinner();
+  s.start("Checking project...");
+  const pkgExists = await pathExists3(path2.join(cwd, "package.json"));
+  if (!pkgExists) {
+    s.stop("Not a Node.js project.");
+    p.cancel(
+      "No package.json found. Run impulse init from the root of your project."
+    );
+    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);
+    }
+  }
+  const projectName = await detectProjectName(cwd);
+  const srcExists = await pathExists3(path2.join(cwd, "src"));
+  const srcPath = srcExists ? "src" : ".";
+  const config = {
+    version: "1",
+    projectName,
+    srcPath,
+    dbPath: srcExists ? `${srcPath}/server/db` : "server/db",
+    routesPath: srcExists ? `${srcPath}/server/api` : "server/api",
+    installedModules: []
+  };
+  await writeConfig(config, cwd);
+  p.outro(
+    `.impulse.json created for project "${projectName}". Run \`impulse list\` to see available modules.`
+  );
+}
+
+// src/commands/add.ts
+import { execSync, execFileSync } from "child_process";
+import { existsSync } from "fs";
+import path11 from "path";
+import * as p4 from "@clack/prompts";
+
+// src/registry/fetch-module-manifest.ts
+import fsExtra5 from "fs-extra";
+import path3 from "path";
+
+// src/schemas/module-manifest.ts
+import { z as z5 } from "zod";
+
+// src/schemas/module-file.ts
+import { z as z2 } from "zod";
+var ModuleFileSchema = z2.object({
+  src: z2.string(),
+  dest: z2.string()
+});
+
+// src/schemas/module-dependency.ts
+import { z as z3 } from "zod";
+var ModuleDependencySchema = z3.string();
+
+// src/schemas/module-transform.ts
+import { z as z4 } from "zod";
+var ModuleTransformSchema = z4.object({
+  type: z4.enum([
+    "append-export",
+    "register-route",
+    "add-nav-item",
+    "merge-schema",
+    "add-env"
+  ]),
+  target: z4.string(),
+  value: z4.string()
+});
+
+// src/schemas/module-manifest.ts
+var ModuleManifestSchema = z5.object({
+  name: z5.string(),
+  version: z5.string(),
+  description: z5.string(),
+  /** If set, this module is a sub-module of the named parent (e.g. "attio"). */
+  parentModule: z5.string().optional(),
+  /** Names of sub-modules available under this parent module (e.g. ["quote-to-cash", "gocardless"]). */
+  subModules: z5.array(z5.string()).default([]),
+  dependencies: z5.array(ModuleDependencySchema).default([]),
+  moduleDependencies: 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()
+});
+
+// src/registry/github-urls.ts
+var GITHUB_ORG = "impulse-studio";
+var GITHUB_REPO = "impulse-modules";
+var GITHUB_BRANCH = "main";
+var MODULES_DIR = "modules";
+var githubUrls = {
+  rawFile: (registryPath, file) => `https://raw.githubusercontent.com/${GITHUB_ORG}/${GITHUB_REPO}/${GITHUB_BRANCH}/${MODULES_DIR}/${registryPath}/${file}`,
+  moduleList: () => `https://api.github.com/repos/${GITHUB_ORG}/${GITHUB_REPO}/contents/${MODULES_DIR}`,
+  subModulesList: (parentModule) => `https://api.github.com/repos/${GITHUB_ORG}/${GITHUB_REPO}/contents/${MODULES_DIR}/${parentModule}/sub-modules`
+};
+
+// src/registry/parse-module-id.ts
+function parseModuleId(moduleId) {
+  const slashIndex = moduleId.indexOf("/");
+  if (slashIndex === -1) return { parent: moduleId, child: null };
+  return {
+    parent: moduleId.slice(0, slashIndex),
+    child: moduleId.slice(slashIndex + 1)
+  };
+}
+function moduleRegistryPath(moduleId) {
+  const { parent, child } = parseModuleId(moduleId);
+  if (child === null) return parent;
+  return `${parent}/sub-modules/${child}`;
+}
+
+// src/registry/fetch-module-manifest.ts
+var { readJson: readJson3, pathExists: pathExists4 } = fsExtra5;
+async function fetchModuleManifest(moduleId, localPath) {
+  const registryPath = moduleRegistryPath(moduleId);
+  if (localPath) {
+    const file = path3.join(localPath, registryPath, "module.json");
+    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 url = githubUrls.rawFile(registryPath, "module.json");
+  const res = await fetch(url);
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(`Module not found in registry: ${moduleId}`);
+    }
+    throw new Error(`Failed to fetch module manifest: ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.json();
+  const parsed = ModuleManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Invalid module.json for ${moduleId}: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+
+// src/registry/list-available-modules.ts
+import fsExtra6 from "fs-extra";
+import path4 from "path";
+var { readJson: readJson4, pathExists: pathExists5 } = fsExtra6;
+var _cachedModuleList = null;
+async function listAvailableModules(localPath) {
+  if (localPath) {
+    const { readdir } = await import("fs/promises");
+    const entries2 = await readdir(localPath, { withFileTypes: true });
+    const result = [];
+    for (const entry of entries2) {
+      if (!entry.isDirectory()) continue;
+      const manifestFile = path4.join(localPath, entry.name, "module.json");
+      if (!await pathExists5(manifestFile)) continue;
+      try {
+        const raw = await readJson4(manifestFile);
+        const parsed = ModuleManifestSchema.safeParse(raw);
+        if (!parsed.success) continue;
+        let subModules;
+        const subModulesDir = path4.join(localPath, entry.name, "sub-modules");
+        if (await pathExists5(subModulesDir)) {
+          const subEntries = await readdir(subModulesDir, { withFileTypes: true });
+          subModules = subEntries.filter((e) => e.isDirectory()).map((e) => e.name);
+          if (subModules.length === 0) subModules = void 0;
+        }
+        result.push({
+          name: parsed.data.name,
+          description: parsed.data.description,
+          ...subModules ? { subModules } : {}
+        });
+      } catch {
+      }
+    }
+    return result;
+  }
+  if (_cachedModuleList) return _cachedModuleList;
+  const res = await fetch(githubUrls.moduleList(), {
+    headers: { Accept: "application/vnd.github.v3+json" }
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch module list: ${res.status} ${res.statusText}`);
+  }
+  const entries = await res.json();
+  if (!Array.isArray(entries)) {
+    throw new Error("Unexpected response from GitHub API");
+  }
+  const baseModules = [];
+  for (const entry of entries) {
+    if (typeof entry === "object" && entry !== null && "type" in entry && entry.type === "dir" && "name" in entry && typeof entry.name === "string") {
+      baseModules.push({ name: entry.name });
+    }
+  }
+  const modules = await Promise.all(
+    baseModules.map(async (mod) => {
+      try {
+        const subRes = await fetch(githubUrls.subModulesList(mod.name), {
+          headers: { Accept: "application/vnd.github.v3+json" }
+        });
+        if (!subRes.ok) return mod;
+        const subEntries = await subRes.json();
+        if (!Array.isArray(subEntries)) return mod;
+        const subModules = subEntries.filter(
+          (e) => typeof e === "object" && e !== null && "type" in e && e.type === "dir" && "name" in e && typeof e.name === "string"
+        ).map((e) => e.name);
+        return subModules.length > 0 ? { ...mod, subModules } : mod;
+      } catch {
+        return mod;
+      }
+    })
+  );
+  _cachedModuleList = modules;
+  return modules;
+}
+
+// src/registry/fetch-module-file.ts
+async function fetchModuleFile(moduleName, fileSrc, localPath) {
+  if (localPath) {
+    const { readFile: readFile6 } = await import("fs/promises");
+    const { join } = await import("path");
+    const file = join(localPath, moduleName, fileSrc);
+    return readFile6(file, "utf-8");
+  }
+  const url = githubUrls.rawFile(moduleName, fileSrc);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch file ${fileSrc} for module ${moduleName}: ${res.status}`);
+  }
+  return res.text();
+}
+
+// src/installer.ts
+import fsExtra7 from "fs-extra";
+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 results = [];
+  for (const file of files) {
+    const destAbs = path5.join(cwd, file.dest);
+    const exists = await pathExists6(destAbs);
+    if (exists) {
+      const content = await fetchModuleFile(moduleName, file.src, localPath);
+      const existing = await import("fs/promises").then(
+        (fs) => fs.readFile(destAbs, "utf-8")
+      );
+      if (existing === content) {
+        results.push({ dest: file.dest, action: "skipped" });
+        continue;
+      }
+      if (dryRun) {
+        results.push({ dest: file.dest, action: "would-overwrite" });
+        continue;
+      }
+      const answer = await p2.confirm({
+        message: `File already exists: ${file.dest} \u2014 overwrite?`,
+        initialValue: false
+      });
+      if (p2.isCancel(answer) || !answer) {
+        results.push({ dest: file.dest, action: "skipped" });
+        continue;
+      }
+      await outputFile(destAbs, content, "utf-8");
+      results.push({ dest: file.dest, action: "overwritten" });
+    } else {
+      if (dryRun) {
+        results.push({ dest: file.dest, action: "would-create" });
+        continue;
+      }
+      const content = await fetchModuleFile(moduleName, file.src, localPath);
+      await outputFile(destAbs, content, "utf-8");
+      results.push({ dest: file.dest, action: "created" });
+    }
+  }
+  return results;
+}
+
+// src/transforms/append-export.ts
+import fsExtra8 from "fs-extra";
+import path6 from "path";
+var { readFile, outputFile: outputFile2, pathExists: pathExists7 } = fsExtra8;
+async function appendExport(target, value, cwd, dryRun) {
+  const file = path6.join(cwd, target);
+  if (!await pathExists7(file)) {
+    if (!dryRun) {
+      await outputFile2(file, `${value}
+`, "utf-8");
+    }
+    return;
+  }
+  const content = await readFile(file, "utf-8");
+  if (content.includes(value)) return;
+  if (!dryRun) {
+    const newContent = content.endsWith("\n") ? `${content}${value}
+` : `${content}
+${value}
+`;
+    await outputFile2(file, newContent, "utf-8");
+  }
+}
+
+// src/transforms/register-route.ts
+import fsExtra9 from "fs-extra";
+import path7 from "path";
+var { readFile: readFile2, outputFile: outputFile3, pathExists: pathExists8 } = fsExtra9;
+async function registerRoute(target, value, cwd, dryRun) {
+  const file = path7.join(cwd, target);
+  if (!await pathExists8(file)) {
+    throw new Error(
+      `register-route: target file not found: ${target}. Please ensure your router file exists.`
+    );
+  }
+  const content = await readFile2(file, "utf-8");
+  if (content.includes(value)) return;
+  const routerPattern = /^([ \t]*\})[ \t]*(?:satisfies|as)\s/m;
+  const match = routerPattern.exec(content);
+  if (!match) {
+    throw new Error(
+      `register-route: could not find router closing brace in ${target}. Add "${value}" manually.`
+    );
+  }
+  if (!dryRun) {
+    const insertPos = match.index;
+    const newContent = content.slice(0, insertPos) + `  ${value},
+` + content.slice(insertPos);
+    await outputFile3(file, newContent, "utf-8");
+  }
+}
+
+// src/transforms/add-nav-item.ts
+import fsExtra10 from "fs-extra";
+import path8 from "path";
+var { readFile: readFile3, outputFile: outputFile4, pathExists: pathExists9 } = fsExtra10;
+async function addNavItem(target, value, cwd, dryRun) {
+  const file = path8.join(cwd, target);
+  if (!await pathExists9(file)) {
+    throw new Error(
+      `add-nav-item: target file not found: ${target}`
+    );
+  }
+  const content = await readFile3(file, "utf-8");
+  if (content.includes(value)) return;
+  const openPattern = /(?:const\s+\w+(?:\s*:\s*[\w<>\[\], ]+)?\s*=\s*\[|items\s*:\s*\[)/;
+  const openMatch = openPattern.exec(content);
+  if (!openMatch) {
+    throw new Error(
+      `add-nav-item: could not locate nav array in ${target}. Add "${value}" manually.`
+    );
+  }
+  const bracketStart = openMatch.index + openMatch[0].length - 1;
+  let depth = 0;
+  let insertPos = -1;
+  for (let i = bracketStart; i < content.length; i++) {
+    if (content[i] === "[") depth++;
+    else if (content[i] === "]") {
+      depth--;
+      if (depth === 0) {
+        insertPos = i;
+        break;
+      }
+    }
+  }
+  if (insertPos === -1) {
+    throw new Error(
+      `add-nav-item: could not find closing bracket for nav array in ${target}. Add "${value}" manually.`
+    );
+  }
+  if (!dryRun) {
+    const newContent = content.slice(0, insertPos) + `  ${value},
+` + content.slice(insertPos);
+    await outputFile4(file, newContent, "utf-8");
+  }
+}
+
+// src/transforms/merge-schema.ts
+import fsExtra11 from "fs-extra";
+import path9 from "path";
+var { readFile: readFile4, outputFile: outputFile5, pathExists: pathExists10 } = fsExtra11;
+async function mergeSchema(target, value, cwd, dryRun) {
+  const file = path9.join(cwd, target);
+  if (!await pathExists10(file)) {
+    if (!dryRun) {
+      await outputFile5(file, `${value}
+`, "utf-8");
+    }
+    return;
+  }
+  const content = await readFile4(file, "utf-8");
+  if (content.includes(value)) return;
+  if (!dryRun) {
+    const newContent = content.endsWith("\n") ? `${content}${value}
+` : `${content}
+${value}
+`;
+    await outputFile5(file, newContent, "utf-8");
+  }
+}
+
+// src/transforms/add-env.ts
+import fsExtra12 from "fs-extra";
+import path10 from "path";
+import * as p3 from "@clack/prompts";
+var { readFile: readFile5, outputFile: outputFile6, pathExists: pathExists11 } = fsExtra12;
+async function addEnv(target, value, cwd, dryRun) {
+  const file = path10.join(cwd, target);
+  let content = "";
+  if (await pathExists11(file)) {
+    content = await readFile5(file, "utf-8");
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const keyPattern = new RegExp(`^${escaped}=`, "m");
+    if (keyPattern.test(content)) return;
+  }
+  let envValue = "";
+  if (!dryRun) {
+    const answer = await p3.text({
+      message: `Enter value for ${value} (leave blank to skip):`,
+      placeholder: ""
+    });
+    if (p3.isCancel(answer)) {
+      p3.log.warn(`Skipped env var: ${value}`);
+      return;
+    }
+    envValue = String(answer);
+  }
+  const line = `${value}=${envValue}`;
+  if (!dryRun) {
+    const newContent = content ? content.endsWith("\n") ? `${content}${line}
+` : `${content}
+${line}
+` : `${line}
+`;
+    await outputFile6(file, newContent, "utf-8");
+  }
+}
+
+// src/transforms/index.ts
+async function runTransform(transform, cwd, dryRun) {
+  switch (transform.type) {
+    case "append-export":
+      await appendExport(transform.target, transform.value, cwd, dryRun);
+      break;
+    case "register-route":
+      await registerRoute(transform.target, transform.value, cwd, dryRun);
+      break;
+    case "add-nav-item":
+      await addNavItem(transform.target, transform.value, cwd, dryRun);
+      break;
+    case "merge-schema":
+      await mergeSchema(transform.target, transform.value, cwd, dryRun);
+      break;
+    case "add-env":
+      await addEnv(transform.target, transform.value, cwd, dryRun);
+      break;
+  }
+}
+
+// src/commands/add.ts
+async function resolveModuleDeps(moduleId, localPath, resolved, orderedModules) {
+  if (resolved.has(moduleId)) return;
+  resolved.add(moduleId);
+  const manifest = await fetchModuleManifest(moduleId, localPath);
+  for (const dep of manifest.moduleDependencies) {
+    await resolveModuleDeps(dep, localPath, resolved, orderedModules);
+  }
+  orderedModules.push(moduleId);
+}
+async function resolveWithParent(moduleId, localPath, installedNames, resolved, orderedModules) {
+  const { parent, child } = parseModuleId(moduleId);
+  if (child !== null && !installedNames.has(parent)) {
+    await resolveModuleDeps(parent, localPath, resolved, orderedModules);
+  }
+  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";
+  return "npm";
+}
+function installNpmDeps(deps, cwd, dryRun) {
+  if (deps.length === 0) return;
+  const pm = detectPackageManager(cwd);
+  const args = ["add", ...deps];
+  if (dryRun) {
+    p4.log.info(`[dry-run] Would run: ${pm} ${args.join(" ")}`);
+    return;
+  }
+  p4.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}...`);
+  if (manifest.files.length > 0) {
+    const installed = await installFiles({
+      moduleName: moduleId,
+      files: manifest.files,
+      cwd,
+      dryRun,
+      localPath
+    });
+    for (const f of installed) {
+      const icon = f.action === "created" || f.action === "would-create" ? "+" : f.action === "overwritten" || f.action === "would-overwrite" ? "~" : "=";
+      p4.log.message(`  ${icon} ${f.dest}`);
+    }
+  }
+  for (const transform of manifest.transforms) {
+    p4.log.step(`  transform: ${transform.type} \u2192 ${transform.target}`);
+    await runTransform(transform, cwd, dryRun);
+  }
+}
+function recordModule(config, moduleId, manifest, 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)
+  };
+  if (existing >= 0) {
+    config.installedModules[existing] = record;
+  } else {
+    config.installedModules.push(record);
+  }
+}
+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]" : ""}`);
+  const config = await readConfig(cwd);
+  if (!config) {
+    p4.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 (p4.isCancel(reinstall) || !reinstall) {
+      p4.outro("Cancelled.");
+      return;
+    }
+  }
+  if (withSubModules.length > 0) {
+    const parentManifest = await fetchModuleManifest(moduleName, localPath).catch(() => null);
+    if (parentManifest) {
+      if (parentManifest.subModules.length === 0) {
+        p4.cancel(`"${moduleName}" 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(", ")}.
+Available: ${parentManifest.subModules.join(", ")}`
+        );
+        process.exit(1);
+      }
+    }
+  }
+  const s = p4.spinner();
+  s.start("Resolving dependencies...");
+  const resolved = /* @__PURE__ */ new Set();
+  const orderedModules = [];
+  try {
+    for (const target of allTargets) {
+      await resolveWithParent(target, localPath, installedNames, resolved, orderedModules);
+    }
+  } catch (err) {
+    s.stop("Dependency resolution failed.");
+    p4.cancel(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  s.stop(`Resolved: ${orderedModules.join(" \u2192 ")}`);
+  const manifests = /* @__PURE__ */ new Map();
+  for (const id of orderedModules) {
+    manifests.set(id, await fetchModuleManifest(id, localPath));
+  }
+  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:");
+  for (const [id, manifest] of manifests) {
+    p4.log.message(`
+  Module: ${id}@${manifest.version}`);
+    for (const file of manifest.files) {
+      p4.log.message(`    + ${file.dest}`);
+    }
+    for (const transform of manifest.transforms) {
+      p4.log.message(`    ~ ${transform.type} \u2192 ${transform.target}`);
+    }
+  }
+  const allEnvVars = /* @__PURE__ */ new Set();
+  for (const manifest of manifests.values()) {
+    for (const envVar of manifest.envVars) {
+      allEnvVars.add(envVar);
+    }
+  }
+  if (allDeps.size > 0) {
+    p4.log.message(`
+  npm deps: ${[...allDeps].join(", ")}`);
+  }
+  if (allEnvVars.size > 0) {
+    p4.log.message(`
+  env vars required: ${[...allEnvVars].join(", ")}`);
+  }
+  if (!dryRun) {
+    const confirm4 = await p4.confirm({
+      message: "Proceed?",
+      initialValue: true
+    });
+    if (p4.isCancel(confirm4) || !confirm4) {
+      p4.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 depPostInstallHooks = [];
+  if (depModules.length > 0) {
+    p4.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);
+      if (depManifest.postInstall && depManifest.postInstall.length > 0) {
+        depPostInstallHooks.push({ name: dep, hooks: depManifest.postInstall });
+      }
+    }
+  }
+  for (const targetId of targetModules) {
+    const targetManifest = manifests.get(targetId);
+    if (!targetManifest) continue;
+    await installModule(targetId, targetManifest, cwd, dryRun, localPath);
+  }
+  installNpmDeps([...allDeps], cwd, dryRun);
+  if (!dryRun) {
+    for (const { name, hooks } of depPostInstallHooks) {
+      p4.log.step(`Running post-install hooks for ${name}...`);
+      for (const hook of hooks) {
+        p4.log.message(`  $ ${hook}`);
+        execSync(hook, { cwd, stdio: "inherit" });
+      }
+    }
+  }
+  if (!dryRun) {
+    for (const targetId of targetModules) {
+      const targetManifest = manifests.get(targetId);
+      if (!targetManifest?.postInstall?.length) continue;
+      p4.log.step(`Running post-install hooks for ${targetId}...`);
+      for (const hook of targetManifest.postInstall) {
+        p4.log.message(`  $ ${hook}`);
+        execSync(hook, { cwd, stdio: "inherit" });
+      }
+    }
+  }
+  if (!dryRun) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const dep of depModules) {
+      const depManifest = manifests.get(dep);
+      if (depManifest) recordModule(config, dep, depManifest, now);
+    }
+    for (const targetId of targetModules) {
+      const targetManifest = manifests.get(targetId);
+      if (targetManifest) recordModule(config, targetId, targetManifest, now);
+    }
+    await writeConfig(config, cwd);
+  }
+  const label = allTargets.length === 1 ? `"${allTargets[0]}"` : allTargets.map((t) => `"${t}"`).join(", ");
+  p4.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";
+async function runList(options) {
+  const { cwd, localPath } = options;
+  p5.intro("impulse list");
+  const config = await readConfig(cwd);
+  const installedNames = new Set(
+    config?.installedModules.map((m) => m.name) ?? []
+  );
+  const s = p5.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));
+    process.exit(1);
+  }
+  s.stop(`Found ${available.length} module(s).`);
+  if (available.length === 0) {
+    p5.log.message("No modules available yet.");
+    p5.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}`);
+      });
+    }
+  }
+  p5.log.message(
+    `
+Run \`impulse add <module>\` to install a module.`
+  );
+  p5.log.message(
+    `Run \`impulse add <parent>/<sub>\` or \`impulse add <parent> --with <sub1>,<sub2>\` for sub-modules.`
+  );
+  p5.outro("Done.");
+}
+
+// src/index.ts
+var program = new Command();
+program.name("impulse").description("ImpulseLab CLI \u2014 install and manage modules for your projects").version("0.1.0");
+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`"
+).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) => {
+  const addOpts = {
+    moduleName,
+    cwd: process.cwd(),
+    dryRun: options.dryRun
+  };
+  if (options.local !== void 0) addOpts.localPath = options.local;
+  if (options.with !== void 0) {
+    addOpts.withSubModules = options.with.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  await runAdd(addOpts);
+});
+program.command("list").description("List available and installed modules").option(
+  "--local <path>",
+  "Use a local modules directory (for development)"
+).action(async (options) => {
+  const listOpts = { cwd: process.cwd() };
+  if (options.local !== void 0) listOpts.localPath = options.local;
+  await runList(listOpts);
+});
+program.parse(process.argv);