alepha 0.19.0 → 0.19.2

package/src/cli/vendor/__tests__/VendorService.spec.ts

@@ -0,0 +1,407 @@
+import { Alepha } from "alepha";
+import {
+  FileSystemProvider,
+  MemoryFileSystemProvider,
+  MemoryShellProvider,
+  ShellProvider,
+} from "alepha/system";
+import { describe, it } from "vitest";
+import { VendorService } from "../services/VendorService.ts";
+
+describe("VendorService", () => {
+  const createTestEnv = () => {
+    const alepha = Alepha.create()
+      .with({ provide: ShellProvider, use: MemoryShellProvider })
+      .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+    const service = alepha.inject(VendorService);
+    const shell = alepha.inject(MemoryShellProvider);
+    const fs = alepha.inject(MemoryFileSystemProvider);
+
+    return { service, shell, fs };
+  };
+
+  describe("sync", () => {
+    it("should clone the remote repository", async ({ expect }) => {
+      const { service, shell, fs } = createTestEnv();
+
+      await fs.mkdir("/tmp/.alepha-vendor-fake/packages/my-pkg", {
+        recursive: true,
+      });
+      await fs.writeFile(
+        "/tmp/.alepha-vendor-fake/packages/my-pkg/index.ts",
+        "export {}",
+      );
+
+      await service.sync({
+        root: "/project",
+        remote: "git@github.com:user/repo.git",
+        branch: "main",
+        packages: ["my-pkg"],
+      });
+
+      expect(
+        shell.wasCalledMatching(
+          /git clone --depth 1 --branch main --filter=blob:none git@github.com:user\/repo\.git/,
+        ),
+      ).toBe(true);
+    });
+
+    it("should remove local package dir before copying", async ({ expect }) => {
+      const { service, shell, fs } = createTestEnv();
+
+      /**
+       * Since MemoryShellProvider does not actually clone, we simulate
+       * by pre-populating the temp directory. We override cloneRemote
+       * to return a known path.
+       */
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          await shell.run(
+            "git clone --depth 1 --branch main --filter=blob:none remote /tmp/test-clone",
+          );
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/my-pkg", {
+        recursive: true,
+      });
+      await testFs.writeFile(
+        "/tmp/test-clone/packages/my-pkg/index.ts",
+        "export {}",
+      );
+      await testFs.mkdir("/project/packages/my-pkg", { recursive: true });
+      await testFs.writeFile("/project/packages/my-pkg/old-file.ts", "old");
+
+      const result = await testService.sync({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["my-pkg"],
+        force: true,
+      });
+
+      expect(result.synced).toEqual(["my-pkg"]);
+      expect(result.errors).toEqual([]);
+      expect(testFs.wasDeleted("/project/packages/my-pkg")).toBe(true);
+    });
+
+    it("should report errors for missing remote packages", async ({
+      expect,
+    }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages", { recursive: true });
+
+      const result = await testService.sync({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["missing-pkg"],
+      });
+
+      expect(result.synced).toEqual([]);
+      expect(result.errors).toEqual([
+        'Package "missing-pkg" not found in remote',
+      ]);
+    });
+
+    it("should sync multiple packages", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg-a", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg-a/index.ts", "a");
+      await testFs.mkdir("/tmp/test-clone/packages/pkg-b", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg-b/index.ts", "b");
+
+      const result = await testService.sync({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg-a", "pkg-b"],
+        force: true,
+      });
+
+      expect(result.synced).toEqual(["pkg-a", "pkg-b"]);
+      expect(result.errors).toEqual([]);
+    });
+
+    it("should clean up temp directory even on error", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg-a", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg-a/index.ts", "a");
+
+      /**
+       * Make cp throw to simulate a failure mid-sync.
+       */
+      const originalCp = testFs.cp.bind(testFs);
+      testFs.cp = async () => {
+        throw new Error("disk full");
+      };
+
+      await expect(
+        testService.sync({
+          root: "/project",
+          remote: "remote",
+          branch: "main",
+          packages: ["pkg-a"],
+          force: true,
+        }),
+      ).rejects.toThrow("disk full");
+
+      expect(testFs.wasDeleted("/tmp/test-clone")).toBe(true);
+
+      testFs.cp = originalCp;
+    });
+  });
+
+  describe("diff", () => {
+    it("should clone the remote repository for diff", async ({ expect }) => {
+      const { service, shell } = createTestEnv();
+
+      await service.diff({
+        root: "/project",
+        remote: "git@github.com:user/repo.git",
+        branch: "main",
+        packages: [],
+      });
+
+      expect(
+        shell.wasCalledMatching(
+          /git clone --depth 1 --branch main --filter=blob:none/,
+        ),
+      ).toBe(true);
+    });
+
+    it("should detect added files", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg/new-file.ts", "new");
+      await testFs.writeFile("/tmp/test-clone/packages/pkg/shared.ts", "same");
+
+      await testFs.mkdir("/project/packages/pkg", { recursive: true });
+      await testFs.writeFile("/project/packages/pkg/shared.ts", "same");
+
+      const result = await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg"],
+      });
+
+      expect(result.packages).toHaveLength(1);
+      expect(result.packages[0].added).toEqual(["new-file.ts"]);
+      expect(result.packages[0].modified).toEqual([]);
+      expect(result.packages[0].removed).toEqual([]);
+      expect(result.totalChanges).toBe(1);
+    });
+
+    it("should detect modified files", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg", { recursive: true });
+      await testFs.writeFile(
+        "/tmp/test-clone/packages/pkg/file.ts",
+        "updated content",
+      );
+
+      await testFs.mkdir("/project/packages/pkg", { recursive: true });
+      await testFs.writeFile(
+        "/project/packages/pkg/file.ts",
+        "original content",
+      );
+
+      const result = await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg"],
+      });
+
+      expect(result.packages[0].modified).toEqual(["file.ts"]);
+      expect(result.totalChanges).toBe(1);
+    });
+
+    it("should detect removed files", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg/shared.ts", "same");
+
+      await testFs.mkdir("/project/packages/pkg", { recursive: true });
+      await testFs.writeFile("/project/packages/pkg/shared.ts", "same");
+      await testFs.writeFile("/project/packages/pkg/local-only.ts", "local");
+
+      const result = await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg"],
+      });
+
+      expect(result.packages[0].removed).toEqual(["local-only.ts"]);
+      expect(result.totalChanges).toBe(1);
+    });
+
+    it("should handle package only in local", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages", { recursive: true });
+      await testFs.mkdir("/project/packages/pkg", { recursive: true });
+      await testFs.writeFile("/project/packages/pkg/file.ts", "local");
+
+      const result = await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg"],
+      });
+
+      expect(result.packages[0].removed).toEqual(["file.ts"]);
+      expect(result.packages[0].added).toEqual([]);
+      expect(result.totalChanges).toBe(1);
+    });
+
+    it("should handle package only in remote", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages/pkg", { recursive: true });
+      await testFs.writeFile("/tmp/test-clone/packages/pkg/file.ts", "remote");
+
+      const result = await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: ["pkg"],
+      });
+
+      expect(result.packages[0].added).toEqual(["file.ts"]);
+      expect(result.packages[0].removed).toEqual([]);
+      expect(result.totalChanges).toBe(1);
+    });
+
+    it("should clean up temp directory after diff", async ({ expect }) => {
+      class TestVendorService extends VendorService {
+        protected override async cloneRemote(): Promise<string> {
+          return "/tmp/test-clone";
+        }
+      }
+
+      const alepha = Alepha.create()
+        .with({ provide: ShellProvider, use: MemoryShellProvider })
+        .with({ provide: FileSystemProvider, use: MemoryFileSystemProvider });
+
+      const testService = alepha.inject(TestVendorService);
+      const testFs = alepha.inject(MemoryFileSystemProvider);
+
+      await testFs.mkdir("/tmp/test-clone/packages", { recursive: true });
+
+      await testService.diff({
+        root: "/project",
+        remote: "remote",
+        branch: "main",
+        packages: [],
+      });
+
+      expect(testFs.wasDeleted("/tmp/test-clone")).toBe(true);
+    });
+  });
+});

package/src/cli/vendor/atoms/vendorOptions.ts

@@ -0,0 +1,41 @@
+import { $atom, type Static, t } from "alepha";
+
+/**
+ * Vendor configuration atom.
+ *
+ * Filled from the `vendor` section of `alepha.config.ts`.
+ * Read by `VendorCommand` to resolve remote, branch, and packages.
+ */
+export const vendorOptions = $atom({
+  name: "alepha.cli.vendor.options",
+  description: "Vendor synchronization configuration",
+  schema: t.optional(
+    t.object({
+      /**
+       * Git remote URL.
+       *
+       * @default "git@github.com:feunard/alepha.git"
+       */
+      remote: t.optional(t.text()),
+
+      /**
+       * Branch to sync from.
+       *
+       * @default "main"
+       */
+      branch: t.optional(t.text()),
+
+      /**
+       * Package directory names under `packages/` to sync.
+       *
+       * @example ["alepha", "@alepha/bucket-s3"]
+       */
+      packages: t.array(t.text()),
+    }),
+  ),
+});
+
+/**
+ * Type for vendor options.
+ */
+export type VendorOptions = Static<typeof vendorOptions.schema>;

package/src/cli/vendor/commands/VendorCommand.ts

@@ -0,0 +1,204 @@
+import { $inject, $state, AlephaError, t } from "alepha";
+import { PackageManagerUtils } from "alepha/cli";
+import { $command } from "alepha/command";
+import { $logger, ConsoleColorProvider } from "alepha/logger";
+import { vendorOptions } from "../atoms/vendorOptions.ts";
+import type {
+  VendorDiffResult,
+  VendorSyncResult,
+} from "../services/VendorService.ts";
+import { VendorService } from "../services/VendorService.ts";
+
+/**
+ * Default remote when none is configured.
+ */
+const DEFAULT_REMOTE = "git@github.com:feunard/alepha.git";
+
+export class VendorCommand {
+  protected readonly log = $logger();
+  protected readonly options = $state(vendorOptions);
+  protected readonly vendorService = $inject(VendorService);
+  protected readonly color = $inject(ConsoleColorProvider);
+  protected readonly pm = $inject(PackageManagerUtils);
+
+  /**
+   * Ensure vendor config is present and return resolved options.
+   */
+  protected resolveOptions() {
+    if (!this.options) {
+      throw new AlephaError(
+        'Missing vendor configuration. Add a "vendor" section to alepha.config.ts.',
+      );
+    }
+    return {
+      remote: this.options.remote ?? DEFAULT_REMOTE,
+      branch: this.options.branch ?? "main",
+      packages: this.options.packages,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // alepha vendor sync
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected readonly syncFlags = t.object({
+    force: t.optional(
+      t.boolean({
+        aliases: ["f"],
+        description: "Skip local modification check",
+      }),
+    ),
+  });
+
+  protected readonly sync = $command({
+    name: "sync",
+    description: "Replace local packages with remote source",
+    flags: this.syncFlags,
+    handler: async ({ flags, root, run }) => {
+      const opts = this.resolveOptions();
+      const c = this.color;
+
+      let result: VendorSyncResult = { synced: [], errors: [] };
+
+      await run({
+        name: `Syncing from ${opts.branch}`,
+        handler: async () => {
+          result = await this.vendorService.sync({
+            root,
+            remote: opts.remote,
+            branch: opts.branch,
+            packages: opts.packages,
+            force: flags.force,
+          });
+        },
+      });
+
+      if (result.aborted) {
+        run.end();
+
+        process.stdout.write(
+          `\nLocal modifications detected. Use ${c.set("CYAN", "--force")} to overwrite.\n`,
+        );
+
+        for (const pkg of result.aborted.packages) {
+          const count =
+            pkg.added.length + pkg.modified.length + pkg.removed.length;
+          if (count === 0) continue;
+
+          process.stdout.write(
+            `\n${c.set("CYAN", pkg.name)}: ${count} ${count === 1 ? "file differs" : "files differ"}\n`,
+          );
+          for (const file of pkg.added) {
+            process.stdout.write(`  ${c.set("GREEN", "A")} ${file}\n`);
+          }
+          for (const file of pkg.modified) {
+            process.stdout.write(`  ${c.set("ORANGE", "M")} ${file}\n`);
+          }
+          for (const file of pkg.removed) {
+            process.stdout.write(`  ${c.set("RED", "D")} ${file}\n`);
+          }
+        }
+
+        process.stdout.write("\n");
+        return;
+      }
+
+      if (result.synced.length > 0) {
+        const pmName = await this.pm.getPackageManager(root);
+        await run(`${pmName} install`, { root });
+      }
+
+      run.end();
+
+      if (result.errors.length > 0) {
+        for (const error of result.errors) {
+          process.stdout.write(`${c.set("RED", "  error")} ${error}\n`);
+        }
+      }
+
+      if (result.synced.length > 0) {
+        process.stdout.write(
+          `\nSynced ${c.set("CYAN", String(result.synced.length))} ${result.synced.length === 1 ? "package" : "packages"} from ${c.set("CYAN", opts.branch)}\n`,
+        );
+        for (const pkg of result.synced) {
+          process.stdout.write(`  ${c.set("GREEN", "\u2713")} ${pkg}\n`);
+        }
+      }
+
+      process.stdout.write("\n");
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // alepha vendor diff
+  // ─────────────────────────────────────────────────────────────────────────
+
+  protected readonly diff = $command({
+    name: "diff",
+    description: "Compare local packages against remote",
+    handler: async ({ root, run }) => {
+      const opts = this.resolveOptions();
+
+      let result: VendorDiffResult = { packages: [], totalChanges: 0 };
+
+      await run({
+        name: `Cloning ${opts.remote} at ${opts.branch}`,
+        handler: async () => {
+          result = await this.vendorService.diff({
+            root,
+            remote: opts.remote,
+            branch: opts.branch,
+            packages: opts.packages,
+          });
+        },
+      });
+
+      run.end();
+
+      if (result.totalChanges === 0) {
+        process.stdout.write("\nNo changes\n\n");
+        return;
+      }
+
+      const c = this.color;
+
+      for (const pkg of result.packages) {
+        const count =
+          pkg.added.length + pkg.modified.length + pkg.removed.length;
+        if (count === 0) {
+          process.stdout.write(`\n${c.set("CYAN", pkg.name)}: no changes\n`);
+          continue;
+        }
+
+        process.stdout.write(
+          `\n${c.set("CYAN", pkg.name)}: ${count} ${count === 1 ? "file differs" : "files differ"}\n`,
+        );
+
+        for (const file of pkg.added) {
+          process.stdout.write(`  ${c.set("GREEN", "A")} ${file}\n`);
+        }
+        for (const file of pkg.modified) {
+          process.stdout.write(`  ${c.set("ORANGE", "M")} ${file}\n`);
+        }
+        for (const file of pkg.removed) {
+          process.stdout.write(`  ${c.set("RED", "D")} ${file}\n`);
+        }
+      }
+
+      process.stdout.write("\n");
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Parent command
+  // ─────────────────────────────────────────────────────────────────────────
+
+  public readonly vendor = $command({
+    name: "vendor",
+    description: "Vendor Alepha packages into the project",
+    children: [this.sync, this.diff],
+    handler: async ({ help }) => {
+      help();
+    },
+  });
+}

package/src/cli/vendor/index.ts

@@ -0,0 +1,43 @@
+import { $module } from "alepha";
+import { vendorOptions } from "./atoms/vendorOptions.ts";
+import { VendorCommand } from "./commands/VendorCommand.ts";
+import { VendorService } from "./services/VendorService.ts";
+
+// ---------------------------------------------------------------------------
+
+/**
+ * CLI plugin for vendoring Alepha packages into external projects.
+ *
+ * Copies package source code from a git remote into the current project's
+ * `packages/` directory. Useful for corporate projects that need a local
+ * copy of Alepha for AI tooling, audits, documentation, or quick fixes.
+ *
+ * Commands:
+ * - `alepha vendor sync`  — replace local packages with remote source
+ * - `alepha vendor diff`  — compare local packages against remote HEAD
+ *
+ * Configuration in `alepha.config.ts`:
+ *
+ * ```typescript
+ * import { AlephaCliVendor } from "alepha/cli/vendor";
+ *
+ * export default defineConfig({
+ *   services: [AlephaCliVendor],
+ *   vendor: {
+ *     branch: "main",
+ *     packages: ["alepha", "@alepha/bucket-s3"],
+ *   },
+ * });
+ * ```
+ */
+export const AlephaCliVendorPlugin = $module({
+  name: "alepha.cli.plugins.vendor",
+  atoms: [vendorOptions],
+  services: [VendorCommand, VendorService],
+});
+
+// ---------------------------------------------------------------------------
+
+export * from "./atoms/vendorOptions.ts";
+export * from "./commands/VendorCommand.ts";
+export * from "./services/VendorService.ts";