alepha 0.19.0 → 0.19.2

package/src/cli/vendor/services/VendorService.ts

@@ -0,0 +1,338 @@
+import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
+import { FileSystemProvider, ShellProvider } from "alepha/system";
+
+/**
+ * Options for syncing vendored packages from a remote repository.
+ */
+export interface VendorSyncOptions {
+  root: string;
+  remote: string;
+  branch: string;
+  packages: string[];
+  force?: boolean;
+}
+
+/**
+ * Result of a vendor sync operation.
+ */
+export interface VendorSyncResult {
+  synced: string[];
+  errors: string[];
+  aborted?: VendorDiffResult;
+}
+
+/**
+ * Options for diffing vendored packages against a remote repository.
+ */
+export interface VendorDiffOptions {
+  root: string;
+  remote: string;
+  branch: string;
+  packages: string[];
+}
+
+/**
+ * Diff result for a single vendored package.
+ */
+export interface VendorPackageDiff {
+  name: string;
+  added: string[];
+  modified: string[];
+  removed: string[];
+}
+
+/**
+ * Result of a vendor diff operation.
+ */
+export interface VendorDiffResult {
+  packages: VendorPackageDiff[];
+  totalChanges: number;
+}
+
+/**
+ * Handles syncing and diffing vendored packages from a remote git repository.
+ */
+export class VendorService {
+  protected readonly log = $logger();
+  protected readonly shell = $inject(ShellProvider);
+  protected readonly fs = $inject(FileSystemProvider);
+
+  /**
+   * Sync vendored packages from a remote repository.
+   *
+   * Shallow-clones the remote once, then:
+   * - Without `force`: diffs first. If local modifications exist, aborts
+   *   and returns the diff result without touching local files.
+   * - With `force` (or no changes): removes local copies and replaces them.
+   */
+  async sync(options: VendorSyncOptions): Promise<VendorSyncResult> {
+    const synced: string[] = [];
+    const errors: string[] = [];
+    let tmpDir: string | undefined;
+
+    try {
+      tmpDir = await this.cloneRemote(options.remote, options.branch);
+
+      if (!options.force) {
+        const diffResult = await this.diffFromClone(
+          options.root,
+          tmpDir,
+          options.packages,
+        );
+        if (diffResult.totalChanges > 0) {
+          return { synced: [], errors: [], aborted: diffResult };
+        }
+      }
+
+      for (const pkg of options.packages) {
+        const remotePkgDir = this.fs.join(tmpDir, "packages", pkg);
+        const localPkgDir = this.fs.join(options.root, "packages", pkg);
+
+        const remoteExists = await this.fs.exists(remotePkgDir);
+        if (!remoteExists) {
+          errors.push(`Package "${pkg}" not found in remote`);
+          continue;
+        }
+
+        this.log.debug(`Syncing package: ${pkg}`);
+
+        await this.fs.rm(localPkgDir, { recursive: true, force: true });
+        await this.fs.cp(remotePkgDir, localPkgDir, { recursive: true });
+        await this.removeIgnoredFiles(localPkgDir);
+
+        synced.push(pkg);
+      }
+    } finally {
+      if (tmpDir) {
+        await this.fs.rm(tmpDir, { recursive: true, force: true });
+      }
+    }
+
+    return { synced, errors };
+  }
+
+  /**
+   * Diff vendored packages against a remote repository.
+   *
+   * Shallow-clones the remote, then for each package: recursively compares
+   * files to identify added, modified, and removed files.
+   */
+  async diff(options: VendorDiffOptions): Promise<VendorDiffResult> {
+    let tmpDir: string | undefined;
+
+    try {
+      tmpDir = await this.cloneRemote(options.remote, options.branch);
+      return await this.diffFromClone(options.root, tmpDir, options.packages);
+    } finally {
+      if (tmpDir) {
+        await this.fs.rm(tmpDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  /**
+   * Diff local packages against an already-cloned remote.
+   */
+  protected async diffFromClone(
+    root: string,
+    tmpDir: string,
+    packages: string[],
+  ): Promise<VendorDiffResult> {
+    const results: VendorPackageDiff[] = [];
+    let totalChanges = 0;
+
+    for (const pkg of packages) {
+      const remotePkgDir = this.fs.join(tmpDir, "packages", pkg);
+      const localPkgDir = this.fs.join(root, "packages", pkg);
+
+      const remoteExists = await this.fs.exists(remotePkgDir);
+      const localExists = await this.fs.exists(localPkgDir);
+
+      if (!remoteExists && !localExists) {
+        results.push({ name: pkg, added: [], modified: [], removed: [] });
+        continue;
+      }
+
+      if (!remoteExists) {
+        const localFiles = await this.fs.ls(localPkgDir, { recursive: true });
+        results.push({
+          name: pkg,
+          added: [],
+          modified: [],
+          removed: localFiles,
+        });
+        totalChanges += localFiles.length;
+        continue;
+      }
+
+      if (!localExists) {
+        const remoteFiles = await this.fs.ls(remotePkgDir, { recursive: true });
+        results.push({
+          name: pkg,
+          added: remoteFiles,
+          modified: [],
+          removed: [],
+        });
+        totalChanges += remoteFiles.length;
+        continue;
+      }
+
+      const result = await this.diffDirectories(localPkgDir, remotePkgDir);
+      const pkgChanges =
+        result.added.length + result.modified.length + result.removed.length;
+      totalChanges += pkgChanges;
+
+      results.push({
+        name: pkg,
+        added: result.added,
+        modified: result.modified,
+        removed: result.removed,
+      });
+    }
+
+    return { packages: results, totalChanges };
+  }
+
+  /**
+   * Remove test files and ignored directories from a synced package.
+   */
+  protected async removeIgnoredFiles(pkgDir: string): Promise<void> {
+    const allFiles = await this.fs.ls(pkgDir, { recursive: true });
+
+    // Remove ignored files
+    for (const file of allFiles) {
+      if (
+        file.endsWith(".spec.ts") ||
+        file.endsWith(".spec.tsx") ||
+        file === "LICENSE"
+      ) {
+        await this.fs.rm(this.fs.join(pkgDir, file), { force: true });
+      }
+    }
+
+    // Remove ignored directories (find all occurrences at any depth)
+    for (const file of allFiles) {
+      for (const ignored of this.ignoredPaths) {
+        if (
+          file === ignored ||
+          file.startsWith(`${ignored}/`) ||
+          file.includes(`/${ignored}/`) ||
+          file.endsWith(`/${ignored}`)
+        ) {
+          // Extract the path to the ignored directory itself
+          const idx = file.indexOf(ignored);
+          const dirPath = this.fs.join(
+            pkgDir,
+            file.substring(0, idx + ignored.length),
+          );
+          await this.fs.rm(dirPath, { recursive: true, force: true });
+        }
+      }
+    }
+  }
+
+  /**
+   * Clone a remote repository into a temporary directory.
+   */
+  protected async cloneRemote(remote: string, branch: string): Promise<string> {
+    const tmpDir = this.fs.join(
+      process.env.TMPDIR || "/tmp",
+      `.alepha-vendor-${Date.now()}`,
+    );
+
+    this.log.debug(`Cloning ${remote}#${branch} into ${tmpDir}`);
+
+    const output = await this.shell.run(
+      `git clone --depth 1 --branch ${branch} --filter=blob:none ${remote} ${tmpDir}`,
+      { capture: true },
+    );
+
+    if (output) {
+      this.log.debug(output);
+    }
+
+    return tmpDir;
+  }
+
+  /**
+   * Directories to ignore during diff comparisons.
+   */
+  protected readonly ignoredPaths = [
+    "__tests__",
+    "assets/swagger-ui",
+    "node_modules",
+    "dist",
+  ];
+
+  /**
+   * Check if a file path should be ignored during diff.
+   */
+  protected isIgnored(filePath: string): boolean {
+    if (
+      filePath.endsWith(".spec.ts") ||
+      filePath.endsWith(".spec.tsx") ||
+      filePath === "LICENSE"
+    ) {
+      return true;
+    }
+    return this.ignoredPaths.some(
+      (p) =>
+        filePath === p ||
+        filePath.startsWith(`${p}/`) ||
+        filePath.includes(`/${p}/`) ||
+        filePath.endsWith(`/${p}`),
+    );
+  }
+
+  /**
+   * Recursively compare two directories and return the differences.
+   */
+  protected async diffDirectories(
+    localDir: string,
+    remoteDir: string,
+  ): Promise<{ added: string[]; modified: string[]; removed: string[] }> {
+    const added: string[] = [];
+    const modified: string[] = [];
+    const removed: string[] = [];
+
+    const [localFiles, remoteFiles] = await Promise.all([
+      this.fs.ls(localDir, { recursive: true }),
+      this.fs.ls(remoteDir, { recursive: true }),
+    ]);
+
+    const filteredLocal = localFiles.filter((f) => !this.isIgnored(f));
+    const filteredRemote = remoteFiles.filter((f) => !this.isIgnored(f));
+
+    const localSet = new Set(filteredLocal);
+    const remoteSet = new Set(filteredRemote);
+
+    for (const file of filteredRemote) {
+      if (!localSet.has(file)) {
+        added.push(file);
+        continue;
+      }
+
+      try {
+        const [localContent, remoteContent] = await Promise.all([
+          this.fs.readFile(this.fs.join(localDir, file)),
+          this.fs.readFile(this.fs.join(remoteDir, file)),
+        ]);
+
+        if (!localContent.equals(remoteContent)) {
+          modified.push(file);
+        }
+      } catch {
+        // Skip directories and unreadable entries
+      }
+    }
+
+    for (const file of filteredLocal) {
+      if (!remoteSet.has(file)) {
+        removed.push(file);
+      }
+    }
+
+    return { added, modified, removed };
+  }
+}

package/src/command/{providers → __tests__}/CliProvider.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha, t } from "alepha";
 import { describe, expect, it } from "vitest";
 import { $command } from "../primitives/$command.ts";
-import { CliProvider } from "./CliProvider.ts";
+import { CliProvider } from "../providers/CliProvider.ts";
 
 /**
  * Test subclass that exposes protected methods for unit testing.

package/src/command/{helpers → __tests__}/EnvUtils.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha } from "alepha";
 import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
-import { EnvUtils } from "./EnvUtils.ts";
+import { EnvUtils } from "../helpers/EnvUtils.ts";
 
 describe("EnvUtils", () => {
   describe("parseEnv", () => {

package/src/command/providers/CliProvider.ts

@@ -5,7 +5,7 @@ import {
   $env,
   $hook,
   $inject,
-  $use,
+  $state,
   Alepha,
   type Static,
   type TObject,
@@ -115,7 +115,7 @@ export class CliProvider {
   protected readonly runner = $inject(Runner);
   protected readonly asker = $inject(Asker);
   protected readonly envUtils = $inject(EnvUtils);
-  protected readonly options = $use(cliOptions);
+  protected readonly options = $state(cliOptions);
 
   // ─────────────────────────────────────────────────────────────────────────────
   // Configuration

package/src/core/{primitives → __tests__}/$atom.spec.ts

@@ -1,7 +1,7 @@
 import { Alepha, type State } from "alepha";
 import { describe, expect, it } from "vitest";
 import { $atom } from "../primitives/$atom.ts";
-import { $use } from "../primitives/$use.ts";
+import { $state } from "../primitives/$state.ts";
 import { t } from "../providers/TypeProvider.ts";
 
 describe("$atom", () => {
@@ -16,7 +16,7 @@ describe("$atom", () => {
   });
 
   class App {
-    count = $use(count);
+    count = $state(count);
   }
 
   it("should be get/set with state manager", () => {

package/src/core/{primitives → __tests__}/$memoize.spec.ts

@@ -1,6 +1,6 @@
 import { $pipeline, Alepha } from "alepha";
 import { describe, test } from "vitest";
-import { $memoize } from "./$memoize.ts";
+import { $memoize } from "../primitives/$memoize.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // $memoize — core behavior

package/src/core/{primitives → __tests__}/$mode.spec.ts

@@ -1,6 +1,6 @@
 import { $hook, $inject, Alepha } from "alepha";
 import { describe, expect, it } from "vitest";
-import { $mode } from "./$mode.ts";
+import { $mode } from "../primitives/$mode.ts";
 
 describe("$mode", () => {
   it("should activate when direct env is set", async () => {

package/src/core/{primitives → __tests__}/$pipeline.spec.ts

@@ -5,7 +5,7 @@ import {
   createMiddleware,
   type Middleware,
   PipelinePrimitive,
-} from "./$pipeline.ts";
+} from "../primitives/$pipeline.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // Test helpers — fake middleware factories

package/src/core/{primitives → __tests__}/$scope.spec.ts

@@ -4,8 +4,8 @@ import {
   $pipeline,
   type Middleware,
   type MiddlewareMetadata,
-} from "./$pipeline.ts";
-import { $scope } from "./$scope.ts";
+} from "../primitives/$pipeline.ts";
+import { $scope } from "../primitives/$scope.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // $scope — core behavior

package/src/core/{providers → __tests__}/KeylessJsonSchemaCodec.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha, t } from "alepha";
 import { describe, test } from "vitest";
-import { KeylessJsonSchemaCodec } from "./KeylessJsonSchemaCodec.ts";
+import { KeylessJsonSchemaCodec } from "../providers/KeylessJsonSchemaCodec.ts";
 
 describe("KeylessJsonSchemaCodec", () => {
   describe("Basic types", () => {

package/src/core/{providers → __tests__}/SchemaValidator.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha, t } from "alepha";
 import { describe, test } from "vitest";
-import { SchemaValidator } from "./SchemaValidator.ts";
+import { SchemaValidator } from "../providers/SchemaValidator.ts";
 
 describe("SchemaValidator", () => {
   describe("Basic validation", () => {

package/src/core/{helpers → __tests__}/jsonSchemaToTypeBox.spec.ts

@@ -1,7 +1,7 @@
 import * as Value from "typebox/value";
 import { describe, test } from "vitest";
+import { jsonSchemaToTypeBox } from "../helpers/jsonSchemaToTypeBox.ts";
 import { t } from "../providers/TypeProvider.ts";
-import { jsonSchemaToTypeBox } from "./jsonSchemaToTypeBox.ts";
 
 describe("jsonSchemaToTypeBox", () => {
   describe("reserved/special property names", () => {

package/src/core/index.shared.ts

@@ -28,7 +28,7 @@ export * from "./primitives/$mode.ts";
 export * from "./primitives/$module.ts";
 export * from "./primitives/$pipeline.ts";
 export * from "./primitives/$scope.ts";
-export * from "./primitives/$use.ts";
+export * from "./primitives/$state.ts";
 export * from "./providers/AlsProvider.ts";
 export * from "./providers/CodecManager.ts";
 export * from "./providers/EventManager.ts";

package/src/core/primitives/{$use.ts → $state.ts}

@@ -1,7 +1,7 @@
 import type { State } from "../Alepha.ts";
 import { OPTIONS } from "../constants/OPTIONS.ts";
-import type { Static, TObject } from "../providers/TypeProvider.ts";
-import type { Atom } from "./$atom.ts";
+import type { Static } from "../providers/TypeProvider.ts";
+import type { Atom, TAtomObject } from "./$atom.ts";
 import { $context } from "./$context.ts";
 
 /**
@@ -18,7 +18,7 @@ import { $context } from "./$context.ts";
  * const userState = $atom({ schema: t.object({ name: t.text(), role: t.text() }) });
  *
  * class UserComponent {
- *   user = $use(userState); // Reactive reference to atom state
+ *   user = $state(userState); // Reactive reference to atom state
  *
  *   render() {
  *     return <div>Hello {this.user.name}!</div>;
@@ -26,7 +26,7 @@ import { $context } from "./$context.ts";
  * }
  * ```
  */
-export const $use = <T extends TObject, N extends string>(
+export const $state = <T extends TAtomObject, N extends string>(
   atom: Atom<T, N>,
 ): Readonly<Static<T>> => {
   const { alepha } = $context();

package/src/crypto/{providers → __tests__}/BrowserCryptoProvider.browser.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { BrowserCryptoProvider } from "./BrowserCryptoProvider.ts";
+import { BrowserCryptoProvider } from "../providers/BrowserCryptoProvider.ts";
 
 describe("BrowserCryptoProvider", () => {
   it("should throw on hashPassword", () => {

package/src/crypto/{providers → __tests__}/CryptoProvider.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { describe, expect, it } from "vitest";
-import { CryptoProvider } from "./CryptoProvider.ts";
+import { CryptoProvider } from "../providers/CryptoProvider.ts";
 
 describe("CryptoProvider", () => {
   it("should hash and verify a password", async () => {

package/src/datetime/{primitives → __tests__}/$debounce.spec.ts

@@ -1,6 +1,6 @@
 import { $pipeline, Alepha } from "alepha";
 import { describe, test } from "vitest";
-import { $debounce } from "./$debounce.ts";
+import { $debounce } from "../primitives/$debounce.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // $debounce — core behavior

package/src/datetime/{primitives → __tests__}/$throttle.spec.ts

@@ -1,7 +1,7 @@
 import { $pipeline, Alepha } from "alepha";
 import { describe, test } from "vitest";
+import { $throttle } from "../primitives/$throttle.ts";
 import { DateTimeProvider } from "../providers/DateTimeProvider.ts";
-import { $throttle } from "./$throttle.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // $throttle — core behavior

package/src/datetime/{primitives → __tests__}/$timeout.spec.ts

@@ -1,7 +1,7 @@
 import { $pipeline, Alepha } from "alepha";
 import { describe, test } from "vitest";
+import { $timeout } from "../primitives/$timeout.ts";
 import { DateTimeProvider } from "../providers/DateTimeProvider.ts";
-import { $timeout } from "./$timeout.ts";
 
 // -----------------------------------------------------------------------------------------------------------------
 // $timeout — core behavior

package/src/email/brevo/{providers → __tests__}/BrevoEmailProvider.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { BrevoEmailProvider } from "./BrevoEmailProvider.ts";
+import { BrevoEmailProvider } from "../providers/BrevoEmailProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------