@soederpop/luca 0.0.2

package/src/node/features/downloader.ts

@@ -0,0 +1,92 @@
+import { Feature, features } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import fetch from 'cross-fetch'
+
+/**
+ * A feature that provides file downloading capabilities from URLs.
+ * 
+ * The Downloader feature allows you to fetch files from remote URLs and save them
+ * to the local filesystem. It handles the network request, buffering, and file writing
+ * operations automatically.
+ * 
+ * @example
+ * ```typescript
+ * // Enable the downloader feature
+ * const downloader = container.feature('downloader')
+ * 
+ * // Download a file
+ * const localPath = await downloader.download(
+ *   'https://example.com/image.jpg',
+ *   'downloads/image.jpg'
+ * )
+ * console.log(`File saved to: ${localPath}`)
+ * ```
+ * 
+ * @extends Feature
+ */
+export class Downloader extends Feature {
+  /**
+   * The shortcut path for accessing this feature through the container.
+   *
+   * @static
+   * @readonly
+   * @type {string}
+   */
+  static override shortcut = 'features.downloader' as const
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+  
+  /**
+   * Downloads a file from a URL and saves it to the specified local path.
+   * 
+   * This method fetches the file from the provided URL, converts it to a buffer,
+   * and writes it to the filesystem at the target path. The target path is resolved
+   * relative to the container's configured paths.
+   * 
+   * @param {string} url - The URL to download the file from. Must be a valid HTTP/HTTPS URL.
+   * @param {string} targetPath - The local file path where the downloaded file should be saved.
+   *   This path will be resolved relative to the container's base path.
+   * 
+   * @returns {Promise<string>} A promise that resolves to the absolute path of the saved file.
+   * 
+   * @throws {Error} Throws an error if the URL is invalid or unreachable.
+   * @throws {Error} Throws an error if the target directory doesn't exist or is not writable.
+   * @throws {Error} Throws an error if the network request fails or times out.
+   * @throws {Error} Throws an error if there's insufficient disk space to save the file.
+   * 
+   * @example
+   * ```typescript
+   * // Download an image file
+   * const imagePath = await downloader.download(
+   *   'https://example.com/photo.jpg',
+   *   'images/downloaded-photo.jpg'
+   * )
+   * 
+   * // Download a document
+   * const docPath = await downloader.download(
+   *   'https://api.example.com/files/document.pdf',
+   *   'documents/report.pdf'
+   * )
+   * ```
+   * 
+   * @since 1.0.0
+   */
+  async download(url: string, targetPath: string) {
+    const buffer = await fetch(url).then(res => res.arrayBuffer())
+    await this.container.fs.writeFileAsync(
+      this.container.paths.resolve(targetPath),
+      Buffer.from(buffer)
+    )
+    
+    return this.container.paths.resolve(targetPath)
+  }
+  
+}
+
+/**
+ * Registers the Downloader feature with the features registry.
+ * This makes the feature available for use in containers via `container.use('downloader')`.
+ * 
+ * @type {typeof Downloader}
+ */
+export default features.register('downloader', Downloader)

package/src/node/features/esbuild.ts

@@ -0,0 +1,68 @@
+import * as esbuild from 'esbuild-wasm'
+import { Feature, features } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { NodeContainer } from '../container.js'
+
+/**
+ * A Feature for compiling typescript / esm modules, etc to JavaScript
+ * that the container can run at runtime. Uses esbuild for fast, reliable
+ * TypeScript/ESM transformation with full format support (esm, cjs, iife).
+ *
+ * @example
+ * ```typescript
+ * const esbuild = container.feature('esbuild')
+ * const result = esbuild.transformSync('const x: number = 1')
+ * console.log(result.code) // 'const x = 1;\n'
+ * ```
+*/
+export class ESBuild extends Feature {
+  static override shortcut = 'features.esbuild' as const
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+
+  /**
+   * Attaches the ESBuild feature to a NodeContainer instance.
+   *
+   * @param c - The NodeContainer to attach to
+   * @returns The container for method chaining
+   */
+  static attach(c: NodeContainer) {
+    return c
+  }
+
+  /**
+   * Transform code synchronously
+   * @param code - The code to transform
+   * @param options - The options to pass to esbuild
+   * @returns The transformed code
+   */
+  transformSync(code: string, options?: esbuild.TransformOptions) {
+    return esbuild.transformSync(code, {
+      loader: 'ts',
+      format: 'esm',
+      target: 'es2020',
+      sourcemap: false,
+      minify: false,
+      ...options
+    })
+  }
+
+  /**
+   * Transform code asynchronously
+   * @param code - The code to transform
+   * @param options - The options to pass to esbuild
+   * @returns The transformed code
+   */
+  async transform(code: string, options?: esbuild.TransformOptions) {
+    return esbuild.transform(code, {
+      loader: 'ts',
+      format: 'esm',
+      target: 'es2020',
+      sourcemap: false,
+      minify: false,
+      ...options
+    })
+  }
+}
+
+export default features.register('esbuild', ESBuild)

package/src/node/features/file-manager.ts

@@ -0,0 +1,357 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { State } from "../../state.js";
+import { Feature, features } from "../feature.js";
+import { parse, relative } from "path";
+import { statSync } from "fs";
+import micromatch from "micromatch";
+import { castArray } from "lodash-es";
+import chokidar from "chokidar";
+import type { FSWatcher } from "chokidar";
+
+type File = {
+  absolutePath: string;
+  relativePath: string;
+  relativeDirname: string;
+  dirname: string;
+  name: string;
+  extension: string;
+  size: number;
+  modifiedAt: Date;
+  createdAt: Date;
+};
+
+export const FileManagerStateSchema = FeatureStateSchema.extend({
+  /** Whether the file manager has completed its initial scan */
+  started: z.boolean().optional().describe('Whether the file manager has completed its initial scan'),
+  /** Whether the file manager is currently scanning files */
+  starting: z.boolean().optional().describe('Whether the file manager is currently scanning files'),
+  /** Whether the file watcher is actively monitoring for changes */
+  watching: z.boolean().optional().describe('Whether the file watcher is actively monitoring for changes'),
+  /** Whether the initial scan failed */
+  failed: z.boolean().optional().describe('Whether the initial file scan failed'),
+})
+
+export const FileManagerOptionsSchema = FeatureOptionsSchema.extend({
+  /** Glob patterns to exclude from file scanning */
+  exclude: z.union([z.string(), z.array(z.string())]).optional().describe('Glob patterns to exclude from file scanning'),
+})
+
+export type FileManagerState = z.infer<typeof FileManagerStateSchema>
+export type FileManagerOptions = z.infer<typeof FileManagerOptionsSchema>
+
+/** 
+ * The FileManager feature creates a database like index of all of the files in the project,
+ * and provides metadata about these files, and also provides a way to watch for changes to the files.
+ *
+ * @example
+ * ```typescript
+ * const fileManager = container.feature('fileManager')
+ * await fileManager.start()
+ * 
+ * const fileIds = fileManager.fileIds
+ * const typescriptFiles = fileManager.matchFiles("**ts")
+ * ```
+*/
+export class FileManager<
+  T extends FileManagerState = FileManagerState,
+  K extends FileManagerOptions = FileManagerOptions
+> extends Feature<T, K> {
+
+  static override shortcut = 'features.fileManager' as const
+  static override stateSchema = FileManagerStateSchema
+  static override optionsSchema = FileManagerOptionsSchema
+  
+  files: State<Record<string, File>> = new State<Record<string, File>>({
+    initialState: {},
+  });
+
+  /** Returns an array of all relative file paths indexed by the file manager. */
+  get fileIds() {
+    return Array.from(this.files.keys());
+  }
+
+  /** Returns an array of all file metadata objects indexed by the file manager. */
+  get fileObjects() {
+    return Array.from(this.files.values());
+  }
+
+  /** 
+   * Matches the file IDs against the pattern(s) provided
+   * @param {string | string[]} patterns - The patterns to match against the file IDs
+   * @returns {string[]} The file IDs that match the patterns
+  */
+  match(patterns: string | string[]) {
+    return micromatch(this.files.keys(), patterns);
+  }
+
+  /** 
+   * Matches the file IDs against the pattern(s) provided and returns the file objects for each.
+   * 
+   * @param {string | string[]} patterns - The patterns to match against the file IDs
+   * @returns {File[]} The file objects that match the patterns
+  */
+  matchFiles(patterns: string | string[]) {
+    const fileIds = this.match(Array.isArray(patterns) ? patterns : [patterns]);
+    return fileIds.map((fileId) => this.files.get(fileId));
+  }
+
+  /** 
+   * Returns the directory IDs for all of the files in the project.
+  */
+  get directoryIds() {
+    return Array.from(
+      new Set(
+        this.files
+          .values()
+          .map((file) => this.container.paths.relative(file.dirname))
+          .filter(v => v.length)
+      )
+    );
+  }
+
+  /** Returns an array of unique file extensions found across all indexed files. */
+  get uniqueExtensions() {
+    return Array.from(
+      new Set(
+        this.files.values().map((file) => file.extension)
+      )
+    );
+  }
+
+  /** Whether the file manager has completed its initial scan. */
+  get isStarted() {
+    return !!this.state.get("started");
+  }
+
+  /** Whether the file manager is currently performing its initial scan. */
+  get isStarting() {
+    return !!this.state.get("starting");
+  }
+
+  /** Whether the file watcher is actively monitoring for changes. */
+  get isWatching() {
+    return !!this.state.get("watching");
+  }
+
+  /** 
+   * Starts the file manager and scans the files in the project.
+   * @param {object} [options={}] - Options for the file manager
+   * @param {string | string[]} [options.exclude] - The patterns to exclude from the scan
+   * @returns {Promise<FileManager>} The file manager instance
+  */
+  async start(options: { exclude?: string | string[] } = {}) {
+    if (this.isStarted) {
+      return this;
+    }
+
+    if (this.isStarting) {
+      await this.waitFor("started");
+      return this;
+    } else {
+      this.state.set("starting", true);
+    }
+
+    try {
+      await this.scanFiles(options);
+    } catch (error) {
+      console.error(error);
+      this.state.set("failed", true);
+    } finally {
+      this.state.set("started", true);
+      this.state.set("starting", false);
+    }
+
+    return this;
+  }
+
+  /** 
+   * Scans the files in the project and updates the file manager state.
+   * @param {object} [options={}] - Options for the file manager
+   * @param {string | string[]} [options.exclude] - The patterns to exclude from the scan
+   * @returns {Promise<FileManager>} The file manager instance
+  */
+  async scanFiles(options: { exclude?: string | string[] } = {}) {
+    const { cwd, git, fs } = this.container;
+
+    const fileIds: string[] = [];
+
+    if (!Array.isArray(options.exclude)) {
+      options.exclude = [options.exclude!].filter((v) => v?.length);
+    }
+
+    const { exclude = ["dist", "node_modules", "out"] } = options;
+
+    exclude.push(...castArray(this.options.exclude!).filter((v) => v?.length));
+
+    exclude.push("node_modules");
+    exclude.push("out");
+    exclude.push("dist");
+
+    if (git.isRepo) {
+      const repoRoot = git.repoRoot;
+      const cwdRelative = repoRoot ? relative(repoRoot, cwd) : '';
+      const baseDir = cwdRelative || '';
+
+      const deleted = await git.lsFiles({ deleted: true, baseDir })
+      await git.lsFiles({ baseDir }).then((results) => fileIds.push(...results.filter((id:string) => !deleted.includes(id))));
+      await git
+        .lsFiles({ others: true, includeIgnored: true, exclude, baseDir })
+        .then((results) => fileIds.push(...results.filter((id:string) => !deleted.includes(id))));
+
+      // git ls-files returns paths relative to repo root; make them relative to cwd
+      if (cwdRelative) {
+        const prefix = cwdRelative + '/';
+        for (let i = 0; i < fileIds.length; i++) {
+          if (fileIds[i].startsWith(prefix)) {
+            fileIds[i] = fileIds[i].slice(prefix.length);
+          }
+        }
+      }
+    } else {
+      await fs.walkAsync(cwd).then(({ files } : { files: string[] }) => fileIds.push(...files));
+    }
+
+    fileIds.forEach((relativePath) => {
+      const absolutePath = this.container.paths.resolve(relativePath);
+      const { name, ext, dir } = parse(absolutePath);
+
+      let size = 0
+      let modifiedAt = new Date(0)
+      let createdAt = new Date(0)
+
+      try {
+        const stats = statSync(absolutePath);
+        size = stats.size;
+        modifiedAt = stats.mtime;
+        createdAt = stats.birthtime;
+      } catch (error) {
+      }
+
+      this.files.set(relativePath, {
+        dirname: dir,
+        absolutePath,
+        relativePath,
+	relativeDirname: this.container.paths.relative(dir),
+        name,
+        extension: ext,
+        size,
+        modifiedAt,
+        createdAt,
+      });
+    });
+
+    return this;
+  }
+
+  watcher: FSWatcher | null = null;
+
+  /** Returns the directories and files currently being watched by chokidar. */
+  get watchedFiles(): Record<string, string[]> {
+    return this.watcher?.getWatched() || {};
+  }
+
+  /** 
+   * Watches the files in the project and updates the file manager state.
+   * @param {object} [options={}] - Options for the file manager
+   * @param {string | string[]} [options.exclude] - The patterns to exclude from the watch
+   * @returns {Promise<void>} The file manager instance
+  */
+  async watch(options: { exclude?: string | string[] } = {}) {
+    if (this.isWatching) {
+      return;
+    }
+
+    if (!Array.isArray(options.exclude)) {
+      options.exclude = [options.exclude!].filter((v) => v?.length);
+    }
+
+    const {
+      exclude = [".git/**", "dist/**", "node_modules/**", "out/**", "build/**"],
+    } = options;
+
+    exclude.push(...castArray(this.options.exclude!).filter((v) => v?.length));
+
+    const { cwd } = this.container;
+
+    const watcher = chokidar.watch(
+      this.directoryIds.map(id => this.container.paths.resolve(id)) 
+      , {
+      ignoreInitial: true,
+      persistent: true,
+      ignored: [
+        '.git/**',
+        ...[".git", "dist/**", "node_modules/**", "out/**", "build/**"],
+        ...exclude,
+      ].map((pattern) => micromatch.makeRe(pattern)).concat([
+        /\.git/,
+        /node_modules/
+      ]),
+    });
+
+    watcher
+      .on("add", (path) => {
+        this.emit("file:change", {
+          type: "add",
+          path,
+        });
+        this.updateFile(path);
+      })
+      .on("change", (path) => {
+        this.updateFile(path);
+        this.emit("file:change", {
+          path,
+          type: "change",
+        });
+      })
+      .on("unlink", (path) => {
+        this.removeFile(path);
+        this.emit("file:change", {
+          type: "delete",
+          path,
+        });
+      });
+
+    watcher.on("ready", () => {
+      this.state.set("watching", true);
+    });
+
+    this.watcher = watcher;
+  }
+
+  async stopWatching() {
+    if (!this.isWatching) {
+      return;
+    }
+
+    if (this.watcher) {
+      this.watcher.close();
+      this.state.set("watching", false);
+      this.watcher = null;
+    }
+  }
+
+  async updateFile(path: string) {
+    // Reuse the logic from the scanFiles method to update a single file
+    const absolutePath = this.container.paths.resolve(path);
+    const { name, ext, dir } = parse(absolutePath);
+    const stats = statSync(absolutePath);
+
+    this.files.set(path, {
+      dirname: dir,
+      absolutePath,
+      relativePath: path,
+      name,
+      extension: ext,
+      size: stats.size,
+      modifiedAt: stats.mtime,
+      createdAt: stats.birthtime,
+    });
+  }
+
+  async removeFile(path: string) {
+    this.files.delete(path);
+  }
+}
+
+export default features.register("fileManager", FileManager);