@impulselab/cli 0.1.0

package/src/config/config-path.ts

@@ -0,0 +1,7 @@
+import path from "path";
+
+const CONFIG_FILE = ".impulse.json";
+
+export function configPath(cwd: string = process.cwd()): string {
+  return path.join(cwd, CONFIG_FILE);
+}

package/src/config/has-config.ts

@@ -0,0 +1,9 @@
+import fsExtra from "fs-extra";
+const { pathExists } = fsExtra;
+import { configPath } from "./config-path";
+
+export async function hasConfig(
+  cwd: string = process.cwd()
+): Promise<boolean> {
+  return pathExists(configPath(cwd));
+}

package/src/config/index.ts

@@ -0,0 +1,4 @@
+export { configPath } from "./config-path";
+export { readConfig } from "./read-config";
+export { writeConfig } from "./write-config";
+export { hasConfig } from "./has-config";

package/src/config/read-config.ts

@@ -0,0 +1,20 @@
+import fsExtra from "fs-extra";
+const { readJson, pathExists } = fsExtra;
+import { ImpulseConfigSchema } from "../schemas/impulse-config";
+import type { ImpulseConfig } from "../schemas/impulse-config";
+import { configPath } from "./config-path";
+
+export async function readConfig(
+  cwd: string = process.cwd()
+): Promise<ImpulseConfig | null> {
+  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;
+}

package/src/config/write-config.ts

@@ -0,0 +1,11 @@
+import fsExtra from "fs-extra";
+const { writeJson } = fsExtra;
+import type { ImpulseConfig } from "../schemas/impulse-config";
+import { configPath } from "./config-path";
+
+export async function writeConfig(
+  config: ImpulseConfig,
+  cwd: string = process.cwd()
+): Promise<void> {
+  await writeJson(configPath(cwd), config, { spaces: 2 });
+}

package/src/config.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm } from "fs/promises";
+import path from "path";
+import os from "os";
+import { readConfig, writeConfig, hasConfig } from "./config/index";
+import type { ImpulseConfig } from "./types";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(path.join(os.tmpdir(), "impulse-config-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+const sampleConfig: ImpulseConfig = {
+  version: "1",
+  projectName: "my-project",
+  srcPath: "src",
+  dbPath: "src/server/db",
+  routesPath: "src/server/api",
+  installedModules: [],
+};
+
+describe("config", () => {
+  it("returns null if no config file", async () => {
+    expect(await readConfig(tmpDir)).toBeNull();
+  });
+
+  it("writes and reads config", async () => {
+    await writeConfig(sampleConfig, tmpDir);
+    const config = await readConfig(tmpDir);
+    expect(config).toEqual(sampleConfig);
+  });
+
+  it("hasConfig returns false before init", async () => {
+    expect(await hasConfig(tmpDir)).toBe(false);
+  });
+
+  it("hasConfig returns true after write", async () => {
+    await writeConfig(sampleConfig, tmpDir);
+    expect(await hasConfig(tmpDir)).toBe(true);
+  });
+
+  it("tracks installed modules", async () => {
+    const config: ImpulseConfig = {
+      ...sampleConfig,
+      installedModules: [
+        {
+          name: "auth",
+          version: "1.0.0",
+          installedAt: "2026-01-01T00:00:00.000Z",
+          files: ["src/server/api/auth.ts"],
+        },
+      ],
+    };
+    await writeConfig(config, tmpDir);
+    const read = await readConfig(tmpDir);
+    expect(read?.installedModules).toHaveLength(1);
+    expect(read?.installedModules[0]?.name).toBe("auth");
+  });
+});

package/src/index.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runInit } from "./commands/init";
+import { runAdd } from "./commands/add";
+import { runList } from "./commands/list";
+
+const program = new Command();
+
+program
+  .name("impulse")
+  .description("ImpulseLab CLI — 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: { force: boolean }) => {
+    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: string, options: { dryRun: boolean; local?: string; with?: string }) => {
+    const addOpts: Parameters<typeof runAdd>[0] = {
+      moduleName,
+      cwd: process.cwd(),
+      dryRun: options.dryRun,
+    };
+    if (options.local !== undefined) addOpts.localPath = options.local;
+    if (options.with !== undefined) {
+      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: { local?: string }) => {
+    const listOpts: Parameters<typeof runList>[0] = { cwd: process.cwd() };
+    if (options.local !== undefined) listOpts.localPath = options.local;
+    await runList(listOpts);
+  });
+
+program.parse(process.argv);

package/src/installer.ts

@@ -0,0 +1,71 @@
+import fsExtra from "fs-extra";
+const { outputFile, pathExists } = fsExtra;
+import path from "path";
+import * as p from "@clack/prompts";
+import { fetchModuleFile } from "./registry/index";
+import type { ModuleFile } from "./types";
+
+export interface InstallFilesOptions {
+  moduleName: string;
+  files: ModuleFile[];
+  cwd: string;
+  dryRun: boolean;
+  localPath?: string | undefined;
+}
+
+export interface InstalledFile {
+  dest: string;
+  action: "created" | "overwritten" | "skipped" | "would-create" | "would-overwrite";
+}
+
+export async function installFiles(
+  options: InstallFilesOptions
+): Promise<InstalledFile[]> {
+  const { moduleName, files, cwd, dryRun, localPath } = options;
+  const results: InstalledFile[] = [];
+
+  for (const file of files) {
+    const destAbs = path.join(cwd, file.dest);
+    const exists = await pathExists(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 p.confirm({
+        message: `File already exists: ${file.dest} — overwrite?`,
+        initialValue: false,
+      });
+
+      if (p.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;
+}

package/src/registry/fetch-module-file.ts

@@ -0,0 +1,21 @@
+import { githubUrls } from "./github-urls";
+
+export async function fetchModuleFile(
+  moduleName: string,
+  fileSrc: string,
+  localPath?: string
+): Promise<string> {
+  if (localPath) {
+    const { readFile } = await import("fs/promises");
+    const { join } = await import("path");
+    const file = join(localPath, moduleName, fileSrc);
+    return readFile(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();
+}

package/src/registry/fetch-module-manifest.ts

@@ -0,0 +1,43 @@
+import fsExtra from "fs-extra";
+const { readJson, pathExists } = fsExtra;
+import path from "path";
+import { ModuleManifestSchema } from "../schemas/module-manifest";
+import type { ModuleManifest } from "../schemas/module-manifest";
+import { githubUrls } from "./github-urls";
+import { moduleRegistryPath } from "./parse-module-id";
+
+export async function fetchModuleManifest(
+  moduleId: string,
+  localPath?: string
+): Promise<ModuleManifest> {
+  const registryPath = moduleRegistryPath(moduleId);
+
+  if (localPath) {
+    const file = path.join(localPath, registryPath, "module.json");
+    if (!(await pathExists(file))) {
+      throw new Error(`Local module not found: ${file}`);
+    }
+    const raw = await readJson(file);
+    const parsed = ModuleManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new Error(`Invalid module.json for ${moduleId}: ${parsed.error.message}`);
+    }
+    return parsed.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: unknown = 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;
+}

package/src/registry/github-urls.ts

@@ -0,0 +1,13 @@
+const GITHUB_ORG = "impulse-studio";
+const GITHUB_REPO = "impulse-modules";
+const GITHUB_BRANCH = "main";
+const MODULES_DIR = "modules";
+
+export const githubUrls = {
+  rawFile: (registryPath: string, file: string): string =>
+    `https://raw.githubusercontent.com/${GITHUB_ORG}/${GITHUB_REPO}/${GITHUB_BRANCH}/${MODULES_DIR}/${registryPath}/${file}`,
+  moduleList: (): string =>
+    `https://api.github.com/repos/${GITHUB_ORG}/${GITHUB_REPO}/contents/${MODULES_DIR}`,
+  subModulesList: (parentModule: string): string =>
+    `https://api.github.com/repos/${GITHUB_ORG}/${GITHUB_REPO}/contents/${MODULES_DIR}/${parentModule}/sub-modules`,
+};

package/src/registry/index.ts

@@ -0,0 +1,5 @@
+export { fetchModuleManifest } from "./fetch-module-manifest";
+export { listAvailableModules } from "./list-available-modules";
+export type { RegistryModule } from "./list-available-modules";
+export { fetchModuleFile } from "./fetch-module-file";
+export { parseModuleId, isSubModuleId, moduleRegistryPath } from "./parse-module-id";

package/src/registry/list-available-modules.ts

@@ -0,0 +1,113 @@
+import fsExtra from "fs-extra";
+const { readJson, pathExists } = fsExtra;
+import path from "path";
+import { ModuleManifestSchema } from "../schemas/module-manifest";
+import { githubUrls } from "./github-urls";
+
+export interface RegistryModule {
+  name: string;
+  description?: string;
+  subModules?: string[];
+}
+
+let _cachedModuleList: RegistryModule[] | null = null;
+
+export async function listAvailableModules(
+  localPath?: string
+): Promise<RegistryModule[]> {
+  if (localPath) {
+    const { readdir } = await import("fs/promises");
+    const entries = await readdir(localPath, { withFileTypes: true });
+    const result: RegistryModule[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const manifestFile = path.join(localPath, entry.name, "module.json");
+      if (!(await pathExists(manifestFile))) continue;
+      try {
+        const raw = await readJson(manifestFile);
+        const parsed = ModuleManifestSchema.safeParse(raw);
+        if (!parsed.success) continue;
+
+        // Discover sub-modules from the sub-modules/ subdirectory
+        let subModules: string[] | undefined;
+        const subModulesDir = path.join(localPath, entry.name, "sub-modules");
+        if (await pathExists(subModulesDir)) {
+          const subEntries = await readdir(subModulesDir, { withFileTypes: true });
+          subModules = subEntries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+          if (subModules.length === 0) subModules = undefined;
+        }
+
+        result.push({
+          name: parsed.data.name,
+          description: parsed.data.description,
+          ...(subModules ? { subModules } : {}),
+        });
+      } catch {
+        // skip invalid modules
+      }
+    }
+    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: unknown = await res.json();
+  if (!Array.isArray(entries)) {
+    throw new Error("Unexpected response from GitHub API");
+  }
+
+  const baseModules: RegistryModule[] = [];
+  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 });
+    }
+  }
+
+  // Fetch sub-modules for each module in parallel (404 = no sub-modules dir, safe to ignore)
+  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: unknown = await subRes.json();
+        if (!Array.isArray(subEntries)) return mod;
+        const subModules = subEntries
+          .filter(
+            (e): e is { type: string; name: string } =>
+              typeof e === "object" &&
+              e !== null &&
+              "type" in e &&
+              (e as { type: unknown }).type === "dir" &&
+              "name" in e &&
+              typeof (e as { name: unknown }).name === "string",
+          )
+          .map((e) => e.name);
+        return subModules.length > 0 ? { ...mod, subModules } : mod;
+      } catch {
+        return mod;
+      }
+    }),
+  );
+
+  _cachedModuleList = modules;
+  return modules;
+}

package/src/registry/parse-module-id.ts

@@ -0,0 +1,30 @@
+/**
+ * Parses a module identifier which may use slash notation for sub-modules.
+ * "attio" → { parent: "attio", child: null }
+ * "attio/quote-to-cash" → { parent: "attio", child: "quote-to-cash" }
+ */
+export function parseModuleId(moduleId: string): {
+  parent: string;
+  child: string | null;
+} {
+  const slashIndex = moduleId.indexOf("/");
+  if (slashIndex === -1) return { parent: moduleId, child: null };
+  return {
+    parent: moduleId.slice(0, slashIndex),
+    child: moduleId.slice(slashIndex + 1),
+  };
+}
+
+/**
+ * Returns true when moduleId uses the sub-module slash syntax.
+ */
+export function isSubModuleId(moduleId: string): boolean {
+  return moduleId.includes("/");
+}
+
+/** Resolve module identifier to the path prefix used inside the modules/ directory. */
+export function moduleRegistryPath(moduleId: string): string {
+  const { parent, child } = parseModuleId(moduleId);
+  if (child === null) return parent;
+  return `${parent}/sub-modules/${child}`;
+}

package/src/registry/registry.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir } from "fs/promises";
+import { outputJson } from "fs-extra";
+import path from "path";
+import os from "os";
+import {
+  parseModuleId,
+  isSubModuleId,
+  fetchModuleManifest,
+  listAvailableModules,
+} from "./index";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(path.join(os.tmpdir(), "impulse-registry-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// parseModuleId
+// ---------------------------------------------------------------------------
+
+describe("parseModuleId", () => {
+  it("returns parent=name, child=null for a plain module", () => {
+    expect(parseModuleId("attio")).toEqual({ parent: "attio", child: null });
+    expect(parseModuleId("email")).toEqual({ parent: "email", child: null });
+  });
+
+  it("parses parent/child for sub-module syntax", () => {
+    expect(parseModuleId("attio/quote-to-cash")).toEqual({
+      parent: "attio",
+      child: "quote-to-cash",
+    });
+    expect(parseModuleId("attio/gocardless")).toEqual({
+      parent: "attio",
+      child: "gocardless",
+    });
+  });
+
+  it("handles only the first slash (ignores nested slashes)", () => {
+    expect(parseModuleId("a/b/c")).toEqual({ parent: "a", child: "b/c" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isSubModuleId
+// ---------------------------------------------------------------------------
+
+describe("isSubModuleId", () => {
+  it("returns false for plain module names", () => {
+    expect(isSubModuleId("attio")).toBe(false);
+    expect(isSubModuleId("email")).toBe(false);
+  });
+
+  it("returns true for slash notation", () => {
+    expect(isSubModuleId("attio/quote-to-cash")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchModuleManifest — local mode
+// ---------------------------------------------------------------------------
+
+const baseManifest = {
+  name: "attio",
+  version: "1.0.0",
+  description: "Attio module",
+  files: [],
+  transforms: [],
+};
+
+async function writeManifest(dir: string, manifest: Record<string, unknown>): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await outputJson(path.join(dir, "module.json"), manifest);
+}
+
+describe("fetchModuleManifest (local)", () => {
+  it("resolves a top-level module from localPath", async () => {
+    await writeManifest(path.join(tmpDir, "attio"), baseManifest);
+    const result = await fetchModuleManifest("attio", tmpDir);
+    expect(result.name).toBe("attio");
+    expect(result.version).toBe("1.0.0");
+  });
+
+  it("resolves a sub-module from localPath using slash syntax", async () => {
+    const subManifest = {
+      name: "attio/quote-to-cash",
+      version: "1.0.0",
+      description: "Quote-to-cash sub-module",
+      parentModule: "attio",
+      files: [],
+      transforms: [],
+    };
+    await writeManifest(
+      path.join(tmpDir, "attio", "sub-modules", "quote-to-cash"),
+      subManifest
+    );
+    const result = await fetchModuleManifest("attio/quote-to-cash", tmpDir);
+    expect(result.name).toBe("attio/quote-to-cash");
+    expect(result.parentModule).toBe("attio");
+  });
+
+  it("throws when local module is not found", async () => {
+    await expect(fetchModuleManifest("nonexistent", tmpDir)).rejects.toThrow(
+      "Local module not found"
+    );
+  });
+
+  it("throws when local sub-module is not found", async () => {
+    // parent exists but sub-module does not
+    await writeManifest(path.join(tmpDir, "attio"), baseManifest);
+    await expect(
+      fetchModuleManifest("attio/missing-sub", tmpDir)
+    ).rejects.toThrow("Local module not found");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listAvailableModules — local mode with sub-modules
+// ---------------------------------------------------------------------------
+
+describe("listAvailableModules (local)", () => {
+  it("lists top-level modules from local directory", async () => {
+    await writeManifest(path.join(tmpDir, "attio"), baseManifest);
+    await writeManifest(path.join(tmpDir, "email"), {
+      ...baseManifest,
+      name: "email",
+      description: "Email module",
+    });
+
+    const result = await listAvailableModules(tmpDir);
+    const names = result.map((m) => m.name);
+    expect(names).toContain("attio");
+    expect(names).toContain("email");
+  });
+
+  it("includes subModules array when sub-modules directory exists", async () => {
+    await writeManifest(path.join(tmpDir, "attio"), baseManifest);
+    await writeManifest(
+      path.join(tmpDir, "attio", "sub-modules", "quote-to-cash"),
+      { ...baseManifest, name: "attio/quote-to-cash", parentModule: "attio" }
+    );
+    await writeManifest(
+      path.join(tmpDir, "attio", "sub-modules", "gocardless"),
+      { ...baseManifest, name: "attio/gocardless", parentModule: "attio" }
+    );
+
+    const result = await listAvailableModules(tmpDir);
+    const attio = result.find((m) => m.name === "attio");
+    expect(attio?.subModules).toBeDefined();
+    expect(attio?.subModules).toContain("quote-to-cash");
+    expect(attio?.subModules).toContain("gocardless");
+  });
+
+  it("returns undefined subModules when no sub-modules directory", async () => {
+    await writeManifest(path.join(tmpDir, "email"), {
+      ...baseManifest,
+      name: "email",
+    });
+
+    const result = await listAvailableModules(tmpDir);
+    const email = result.find((m) => m.name === "email");
+    expect(email?.subModules).toBeUndefined();
+  });
+
+  it("skips directories without module.json", async () => {
+    // Create a dir without module.json
+    await mkdir(path.join(tmpDir, "not-a-module"), { recursive: true });
+    await writeManifest(path.join(tmpDir, "email"), {
+      ...baseManifest,
+      name: "email",
+    });
+
+    const result = await listAvailableModules(tmpDir);
+    expect(result.map((m) => m.name)).not.toContain("not-a-module");
+  });
+});