@impulselab/cli 0.1.0 → 0.1.1

package/src/commands/init.ts

@@ -1,114 +0,0 @@
-import fsExtra from "fs-extra";
-const { readJson, pathExists } = fsExtra;
-import path from "path";
-import * as p from "@clack/prompts";
-import { writeConfig, hasConfig } from "../config/index";
-import type { ImpulseConfig } from "../types";
-
-const ULTIMATE_TEMPLATE_MARKERS = [
-  "@impulselab/ultimate-template",
-  "ultimate-template",
-];
-
-async function detectProjectName(cwd: string): Promise<string> {
-  const pkgPath = path.join(cwd, "package.json");
-  if (await pathExists(pkgPath)) {
-    const pkg: unknown = await readJson(pkgPath);
-    if (
-      pkg !== null &&
-      typeof pkg === "object" &&
-      "name" in pkg &&
-      typeof (pkg as Record<string, unknown>).name === "string"
-    ) {
-      return (pkg as { name: string }).name;
-    }
-  }
-  return path.basename(cwd);
-}
-
-async function isUltimateTemplate(cwd: string): Promise<boolean> {
-  const pkgPath = path.join(cwd, "package.json");
-  if (!(await pathExists(pkgPath))) return false;
-
-  const raw: unknown = await readJson(pkgPath);
-  if (!raw || typeof raw !== "object") return false;
-
-  const pkg = raw as Record<string, unknown>;
-  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;
-}
-
-export async function runInit(options: {
-  cwd: string;
-  force: boolean;
-}): Promise<void> {
-  const { cwd, force } = options;
-
-  p.intro("impulse init");
-
-  // Check if already initialized
-  if (!force && (await hasConfig(cwd))) {
-    p.log.warn(
-      ".impulse.json already exists. Run with --force to reinitialize."
-    );
-    p.outro("Already initialized.");
-    return;
-  }
-
-  // Validate project
-  const s = p.spinner();
-  s.start("Checking project...");
-
-  const pkgExists = await pathExists(path.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);
-    }
-  }
-
-  // Detect project structure
-  const projectName = await detectProjectName(cwd);
-
-  const srcExists = await pathExists(path.join(cwd, "src"));
-  const srcPath = srcExists ? "src" : ".";
-
-  const config: ImpulseConfig = {
-    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.`
-  );
-}

package/src/commands/list.ts

@@ -1,79 +0,0 @@
-import * as p from "@clack/prompts";
-import { readConfig } from "../config/index";
-import { listAvailableModules } from "../registry/index";
-
-export async function runList(options: {
-  cwd: string;
-  localPath?: string;
-}): Promise<void> {
-  const { cwd, localPath } = options;
-
-  p.intro("impulse list");
-
-  const config = await readConfig(cwd);
-  const installedNames = new Set(
-    config?.installedModules.map((m) => m.name) ?? []
-  );
-
-  const s = p.spinner();
-  s.start("Fetching available modules...");
-
-  let available: { name: string; description?: string; subModules?: string[] }[];
-  try {
-    available = await listAvailableModules(localPath);
-  } catch (err) {
-    s.stop("Failed to fetch module list.");
-    p.cancel(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-  }
-
-  s.stop(`Found ${available.length} module(s).`);
-
-  if (available.length === 0) {
-    p.log.message("No modules available yet.");
-    p.outro("Done.");
-    return;
-  }
-
-  p.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 ? ` — ${mod.description}` : "";
-    p.log.message(`  ${installed ? "✓" : "○"} ${mod.name} ${status}${desc}`);
-
-    // Show sub-modules nested under their parent
-    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 ? "└─" : "├─";
-        p.log.message(`    ${connector} ${sub} ${subStatus}`);
-      });
-    }
-  }
-
-  p.log.message(
-    `\nRun \`impulse add <module>\` to install a module.`
-  );
-  p.log.message(
-    `Run \`impulse add <parent>/<sub>\` or \`impulse add <parent> --with <sub1>,<sub2>\` for sub-modules.`
-  );
-
-  p.outro("Done.");
-}

package/src/config/config-path.ts

@@ -1,7 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

@@ -1,64 +0,0 @@
-#!/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

@@ -1,71 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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

@@ -1,30 +0,0 @@
-/**
- * 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}`;
-}