@soederpop/luca 0.0.28 → 0.0.30

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

@@ -3,7 +3,7 @@ import { FeatureEventsSchema, FeatureStateSchema, FeatureOptionsSchema } from '.
 import { State } from "../../state.js";
 import { Feature } from "../feature.js";
 import { parse, relative, join as pathJoin } from "path";
-import { statSync, readFileSync, existsSync } from "fs";
+import { statSync, readFileSync, existsSync, readdirSync, lstatSync } from "fs";
 import micromatch from "micromatch";
 import { castArray } from "lodash-es";
 import chokidar from "chokidar";
@@ -78,12 +78,12 @@ export class FileManager<
   });
 
   /** Returns an array of all relative file paths indexed by the file manager. */
-  get fileIds() {
+  get fileIds(): string[] {
     return Array.from(this.files.keys());
   }
 
   /** Returns an array of all file metadata objects indexed by the file manager. */
-  get fileObjects() {
+  get fileObjects(): File[] {
     return Array.from(this.files.values());
   }
 
@@ -92,7 +92,7 @@ export class FileManager<
    * @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[]) {
+  match(patterns: string | string[]): string[] {
     return micromatch(this.files.keys(), patterns);
   }
 
@@ -102,7 +102,7 @@ export class FileManager<
    * @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[]) {
+  matchFiles(patterns: string | string[]): (File | undefined)[] {
     const fileIds = this.match(Array.isArray(patterns) ? patterns : [patterns]);
     return fileIds.map((fileId) => this.files.get(fileId));
   }
@@ -110,7 +110,7 @@ export class FileManager<
   /** 
    * Returns the directory IDs for all of the files in the project.
   */
-  get directoryIds() {
+  get directoryIds(): string[] {
     return Array.from(
       new Set(
         this.files
@@ -122,7 +122,7 @@ export class FileManager<
   }
 
   /** Returns an array of unique file extensions found across all indexed files. */
-  get uniqueExtensions() {
+  get uniqueExtensions(): string[] {
     return Array.from(
       new Set(
         this.files.values().map((file) => file.extension)
@@ -131,17 +131,17 @@ export class FileManager<
   }
 
   /** Whether the file manager has completed its initial scan. */
-  get isStarted() {
+  get isStarted(): boolean {
     return !!this.state.get("started");
   }
 
   /** Whether the file manager is currently performing its initial scan. */
-  get isStarting() {
+  get isStarting(): boolean {
     return !!this.state.get("starting");
   }
 
   /** Whether the file watcher is actively monitoring for changes. */
-  get isWatching() {
+  get isWatching(): boolean {
     return !!this.state.get("watching");
   }
 
@@ -156,7 +156,7 @@ export class FileManager<
    * @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[] } = {}) {
+  async start(options: { exclude?: string | string[] } = {}): Promise<this> {
     if (this.isStarted) {
       return this;
     }
@@ -302,7 +302,7 @@ export class FileManager<
    * @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[] } = {}) {
+  async scanFiles(options: { exclude?: string | string[] } = {}): Promise<this> {
     const { cwd, git, fs } = this.container;
 
     const fileIds: string[] = [];
@@ -339,7 +339,28 @@ export class FileManager<
           }
         }
       }
+
+      // git ls-files doesn't traverse symlinked directories — walk them via fs
+      // to pick up their contents. fs.walk now follows symlinks natively.
+      try {
+        const topEntries = readdirSync(cwd, { withFileTypes: true });
+        for (const entry of topEntries) {
+          if (entry.isSymbolicLink()) {
+            const fullPath = pathJoin(cwd, entry.name);
+            try {
+              const target = statSync(fullPath);
+              if (target.isDirectory()) {
+                const walked = await fs.walkAsync(fullPath, { exclude });
+                for (const absFile of walked.files) {
+                  fileIds.push(relative(cwd, absFile));
+                }
+              }
+            } catch {}
+          }
+        }
+      } catch {}
     } else {
+      // fs.walkAsync follows symlinks, so non-git repos get symlink support for free
       await fs.walkAsync(cwd).then(({ files } : { files: string[] }) => fileIds.push(...files));
     }
 
@@ -395,7 +416,7 @@ export class FileManager<
    * @param {string | string[]} [options.exclude] - The patterns to exclude from the watch
    * @returns {Promise<void>}
   */
-  async watch(options: { paths?: string | string[]; exclude?: string | string[] } = {}) {
+  async watch(options: { paths?: string | string[]; exclude?: string | string[] } = {}): Promise<void> {
     const pathsToWatch = castArray(options.paths || this.directoryIds.map(id => this.container.paths.resolve(id)))
       .map(p => this.container.paths.resolve(p));
 
@@ -466,7 +487,7 @@ export class FileManager<
     this.watcher = watcher;
   }
 
-  async stopWatching() {
+  async stopWatching(): Promise<void> {
     if (!this.isWatching) {
       return;
     }
@@ -479,7 +500,7 @@ export class FileManager<
     }
   }
 
-  async updateFile(path: string) {
+  async updateFile(path: string): Promise<void> {
     const absolutePath = this.container.paths.resolve(path);
     const { name, ext, dir } = parse(absolutePath);
 
@@ -505,7 +526,7 @@ export class FileManager<
     }
   }
 
-  async removeFile(path: string) {
+  async removeFile(path: string): Promise<void> {
     this.files.delete(path);
   }
 }

package/src/node/features/fs.ts

@@ -9,11 +9,14 @@ import {
   readFileSync,
   cpSync,
   renameSync,
+  lstatSync,
+  realpathSync,
 
   rmSync as nodeRmSync,
+  type Stats,
 } from "fs";
 import { join, resolve, dirname, relative } from "path";
-import { readFile, stat, unlink, mkdir, writeFile, appendFile, readdir, cp, rename, rm as nodeRm } from "fs/promises";
+import { readFile, stat, lstat, realpath, unlink, mkdir, writeFile, appendFile, readdir, cp, rename, rm as nodeRm } from "fs/promises";
 import { native as rimraf } from 'rimraf'
 
 type WalkOptions = {
@@ -40,6 +43,16 @@ function matchesPattern(filePath: string, patterns: string[]): boolean {
   })
 }
 
+/** Sync: check if a symlink target is a directory */
+function lstatFollowIsDir(fullPath: string): boolean {
+  try { return statSync(fullPath).isDirectory() } catch { return false }
+}
+
+/** Async: check if a symlink target is a directory */
+async function lstatFollowIsDirAsync(fullPath: string): Promise<boolean> {
+  try { return (await stat(fullPath)).isDirectory() } catch { return false }
+}
+
 /**
  * The FS feature provides methods for interacting with the file system, relative to the
  * container's cwd.
@@ -133,7 +146,7 @@ export class FS extends Feature {
    * console.log(config.version)
    * ```
    */
-  readJson(path: string) {
+  readJson(path: string): any {
     return JSON.parse(this.readFile(path) as string)
   }
   
@@ -141,7 +154,7 @@ export class FS extends Feature {
     * Read and parse a JSON file synchronously
     * @alias readJson
    */
-  readJsonSync(path: string) {
+  readJsonSync(path: string): any {
     return this.readJson(path)
   }
 
@@ -158,7 +171,7 @@ export class FS extends Feature {
    * console.log(config.version)
    * ```
    */
-  async readJsonAsync(path: string) {
+  async readJsonAsync(path: string): Promise<any> {
     const content = await this.readFileAsync(path)
     return JSON.parse(content as string)
   }
@@ -176,7 +189,7 @@ export class FS extends Feature {
    * console.log(entries) // ['index.ts', 'utils.ts', 'components']
    * ```
    */
-  readdirSync(path: string) {
+  readdirSync(path: string): string[] {
     return readdirSync(this.container.paths.resolve(path))
   }
 
@@ -193,7 +206,7 @@ export class FS extends Feature {
    * console.log(entries) // ['index.ts', 'utils.ts', 'components']
    * ```
    */
-  async readdir(path: string) {
+  async readdir(path: string): Promise<string[]> {
     return await readdir(this.container.paths.resolve(path))
   }
 
@@ -214,7 +227,7 @@ export class FS extends Feature {
    * fs.writeFile('data.bin', Buffer.from([1, 2, 3, 4]))
    * ```
    */
-  writeFile(path: string, content: Buffer | string) {
+  writeFile(path: string, content: Buffer | string): void {
     writeFileSync(this.container.paths.resolve(path), content)
   }
 
@@ -249,7 +262,7 @@ export class FS extends Feature {
    * fs.writeJson('config.json', { version: '1.0.0', debug: false })
    * ```
    */
-  writeJson(path: string, data: any, indent: number = 2) {
+  writeJson(path: string, data: any, indent: number = 2): void {
     this.writeFile(path, JSON.stringify(data, null, indent) + '\n')
   }
 
@@ -282,7 +295,7 @@ export class FS extends Feature {
    * fs.appendFile('log.txt', 'New line\n')
    * ```
    */
-  appendFile(path: string, content: Buffer | string) {
+  appendFile(path: string, content: Buffer | string): void {
     appendFileSync(this.container.paths.resolve(path), content)
   }
 
@@ -320,7 +333,7 @@ export class FS extends Feature {
    * fs.ensureFile('logs/app.log', '', false)
    * ```
    */
-  ensureFile(path: string, content: string, overwrite = false) {
+  ensureFile(path: string, content: string, overwrite = false): string {
     path = this.container.paths.resolve(path);
 
     if (this.exists(path) && !overwrite) {
@@ -347,7 +360,7 @@ export class FS extends Feature {
    * await fs.ensureFileAsync('config/settings.json', '{}', true)
    * ```
    */
-  async ensureFileAsync(path: string, content: string, overwrite = false) {
+  async ensureFileAsync(path: string, content: string, overwrite = false): Promise<string> {
     path = this.container.paths.resolve(path);
 
     if (this.exists(path) && !overwrite) {
@@ -372,7 +385,7 @@ export class FS extends Feature {
    * fs.ensureFolder('logs/debug')
    * ```
    */
-  ensureFolder(path: string) {
+  ensureFolder(path: string): string {
     mkdirSync(this.container.paths.resolve(path), { recursive: true });
     return this.container.paths.resolve(path);
   }
@@ -389,7 +402,7 @@ export class FS extends Feature {
    * await fs.ensureFolderAsync('logs/debug')
    * ```
    */
-  async ensureFolderAsync(path: string) {
+  async ensureFolderAsync(path: string): Promise<string> {
     const resolved = this.container.paths.resolve(path);
     await mkdir(resolved, { recursive: true });
     return resolved;
@@ -406,7 +419,7 @@ export class FS extends Feature {
    * fs.mkdirp('deep/nested/path')
    * ```
    */
-  mkdirp(folder: string) {
+  mkdirp(folder: string): string {
     return this.ensureFolder(folder)
   }
 
@@ -467,11 +480,33 @@ export class FS extends Feature {
    * }
    * ```
    */
-  async existsAsync(path: string) {
+  async existsAsync(path: string): Promise<boolean> {
     const filePath = this.container.paths.resolve(path);
     return stat(filePath).then(() => true).catch(() => false)
   }
 
+  /**
+   * Checks if a path is a symbolic link.
+   *
+   * @param {string} path - The path to check
+   * @returns {boolean} True if the path is a symlink
+   */
+  isSymlink(path: string): boolean {
+    const filePath = this.container.paths.resolve(path);
+    try { return lstatSync(filePath).isSymbolicLink() } catch { return false }
+  }
+
+  /**
+   * Resolves a symlink to its real path. Returns the resolved path as-is if not a symlink.
+   *
+   * @param {string} path - The path to resolve
+   * @returns {string} The real path after resolving all symlinks
+   */
+  realpath(path: string): string {
+    const filePath = this.container.paths.resolve(path);
+    return realpathSync(filePath)
+  }
+
   /**
    * Synchronously returns the stat object for a file or directory.
    *
@@ -485,7 +520,7 @@ export class FS extends Feature {
    * console.log(info.size, info.mtime)
    * ```
    */
-  stat(path: string) {
+  stat(path: string): Stats {
     return statSync(this.container.paths.resolve(path))
   }
 
@@ -502,7 +537,7 @@ export class FS extends Feature {
    * console.log(info.size, info.mtime)
    * ```
    */
-  async statAsync(path: string) {
+  async statAsync(path: string): Promise<Stats> {
     return stat(this.container.paths.resolve(path))
   }
 
@@ -597,7 +632,7 @@ export class FS extends Feature {
    * fs.rmSync('temp/cache.tmp')
    * ```
    */
-  rmSync(path: string) {
+  rmSync(path: string): void {
     nodeRmSync(this.container.paths.resolve(path), { force: true })
   }
 
@@ -628,7 +663,7 @@ export class FS extends Feature {
    * fs.rmdirSync('temp/cache')
    * ```
    */
-  rmdirSync(dirPath: string) {
+  rmdirSync(dirPath: string): void {
     nodeRmSync(this.container.paths.resolve(dirPath), { recursive: true, force: true })
   }
 
@@ -668,7 +703,7 @@ export class FS extends Feature {
    * fs.copy('src', 'backup/src')
    * ```
    */
-  copy(src: string, dest: string, options: { overwrite?: boolean } = {}) {
+  copy(src: string, dest: string, options: { overwrite?: boolean } = {}): void {
     const { overwrite = true } = options
     const resolvedSrc = this.container.paths.resolve(src)
     const resolvedDest = this.container.paths.resolve(dest)
@@ -712,7 +747,7 @@ export class FS extends Feature {
    * fs.move('old-dir', 'new-dir')
    * ```
    */
-  move(src: string, dest: string) {
+  move(src: string, dest: string): void {
     const resolvedSrc = this.container.paths.resolve(src)
     const resolvedDest = this.container.paths.resolve(dest)
     const destDir = dirname(resolvedDest)
@@ -785,7 +820,7 @@ export class FS extends Feature {
    * const relative = fs.walk('inbox', { relative: true }) // => { files: ['contact-1.json', ...] }
    * ```
    */
-  walk(basePath: string, options: WalkOptions = {}) {
+  walk(basePath: string, options: WalkOptions = {}): { directories: string[], files: string[] } {
     const {
       directories = true,
       files = true,
@@ -811,7 +846,9 @@ export class FS extends Feature {
         const fullPath = join(baseDir, name);
         const relativePath = relative(resolvedBase, fullPath)
         const outputPath = useRelative ? relativePath : fullPath;
-        const isDir = entry.isDirectory();
+        // Follow symlinks: isDirectory() returns false for symlinks,
+        // so check isSymbolicLink() and resolve to the real target
+        const isDir = entry.isDirectory() || (entry.isSymbolicLink() && lstatFollowIsDir(fullPath));
 
         if (excludePatterns.length && matchesPattern(relativePath, excludePatterns)) {
           continue
@@ -862,7 +899,7 @@ export class FS extends Feature {
    * // files.files => ['contact-1.json', 'subfolder/file.txt', ...]
    * ```
    */
-  async walkAsync(baseDir: string, options: WalkOptions = {}) {
+  async walkAsync(baseDir: string, options: WalkOptions = {}): Promise<{ directories: string[], files: string[] }> {
     const {
       directories = true,
       files = true,
@@ -888,7 +925,9 @@ export class FS extends Feature {
         const fullPath = join(currentDir, name);
         const relativePath = relative(resolvedBase, fullPath)
         const outputPath = useRelative ? relativePath : fullPath;
-        const isDir = entry.isDirectory();
+        // Follow symlinks: isDirectory() returns false for symlinks,
+        // so check isSymbolicLink() and resolve to the real target
+        const isDir = entry.isDirectory() || (entry.isSymbolicLink() && await lstatFollowIsDirAsync(fullPath));
 
         if (excludePatterns.length && matchesPattern(relativePath, excludePatterns)) {
           continue

package/src/node/features/git.ts

@@ -98,7 +98,7 @@ export class Git extends Feature {
      * })
      * ```
      */
-    async lsFiles(options: LsFilesOptions = {}) {
+    async lsFiles(options: LsFilesOptions = {}): Promise<string[]> {
         const { 
             cached = false, 
             deleted = false, 
@@ -153,7 +153,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    get branch() {
+    get branch(): string | null {
         if(!this.isRepo) { return null }
         return this.container.feature('proc').exec(`${this.gitPath} branch`).split("\n").filter(line => line.startsWith('*')).map(line => line.replace('*', '').trim()).pop()
     }
@@ -171,7 +171,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    get sha() {
+    get sha(): string | null {
         if(!this.isRepo) { return null }
         return this.container.feature('proc').exec(`${this.gitPath} rev-parse HEAD`, { cwd: this.repoRoot })
     }
@@ -190,7 +190,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    get isRepo() {
+    get isRepo(): boolean {
         return !!this.repoRoot
     }
     
@@ -208,7 +208,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    get isRepoRoot() {
+    get isRepoRoot(): boolean {
         return this.repoRoot == this.container.cwd
     }
     
@@ -228,7 +228,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    get repoRoot() {
+    get repoRoot(): string | null {
         if (this.state.has('repoRoot')) {
             return this.state.get('repoRoot')
         }
@@ -260,7 +260,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    async getLatestChanges(numberOfChanges: number = 10) {
+    async getLatestChanges(numberOfChanges: number = 10): Promise<Array<{ title: string, message: string, author: string }>> {
         if (!this.isRepo) return []
 
         const separator = '---COMMIT---'
@@ -299,7 +299,7 @@ export class Git extends Feature {
      * }
      * ```
      */
-    fileLog(...files: string[]) {
+    fileLog(...files: string[]): Array<{ sha: string, message: string }> {
         if (!this.isRepo || !files.length) return []
 
         const proc = this.container.feature('proc')
@@ -349,7 +349,7 @@ export class Git extends Feature {
      * const d = git.diff('src/index.ts', 'feature-branch', 'main')
      * ```
      */
-    diff(file: string, compareTo: string, compareFrom?: string) {
+    diff(file: string, compareTo: string, compareFrom?: string): string {
         if (!this.isRepo) return ''
 
         const proc = this.container.feature('proc')
@@ -531,7 +531,7 @@ export class Git extends Feature {
      * const history = git.getChangeHistoryForFiles('src/node/features/*.ts')
      * ```
      */
-    getChangeHistoryForFiles(...paths: string[]) {
+    getChangeHistoryForFiles(...paths: string[]): Array<{ sha: string, message: string, longMessage: string, filesMatched: string[] }> {
         if (!this.isRepo || !paths.length) return []
 
         const proc = this.container.feature('proc')

package/src/node/features/helpers.ts

@@ -438,24 +438,22 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
       }
     } catch {}
 
-    // Try fileManager first (faster in git repos), fall back to Glob
+    // Try fileManager first (faster in git repos, and now symlink-aware),
+    // fall back to fs.walk which also follows symlinks natively.
     let files: string[] = []
     try {
       const fm = await this.ensureFileManager()
-      // fileManager may store absolute or relative keys — use absolute patterns
       const absPatterns = [`${dir}/*.ts`, `${dir}/**/*.ts`]
       const relPatterns = [`${type}/*.ts`, `${type}/**/*.ts`]
       const matched = fm.match([...absPatterns, ...relPatterns])
       files = matched.map((f: string) => f.startsWith('/') ? f : resolve(this.rootDir, f))
     } catch {}
 
-    // Fall back to Glob if fileManager found nothing
+    // Fall back to fs.walk if fileManager found nothing
     if (files.length === 0) {
-      const { Glob } = globalThis.Bun || (await import('bun'))
-      const glob = new Glob('**/*.ts')
-      for await (const file of glob.scan({ cwd: dir })) {
-        files.push(resolve(dir, file))
-      }
+      const { fs } = this.container
+      const walked = fs.walk(dir, { include: ['**/*.ts'] })
+      files = walked.files
     }
 
     for (const absPath of files) {
@@ -550,10 +548,15 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
    */
   private async discoverCommandsViaVM(dir: string): Promise<void> {
     this.seedVirtualModules()
-    const { Glob } = globalThis.Bun || (await import('bun'))
-    const glob = new Glob('*.ts')
-
-    for await (const file of glob.scan({ cwd: dir })) {
+    const { fs } = this.container
+    // Commands are top-level only (not recursive) — walk and filter to *.ts in the immediate dir
+    const walked = fs.walk(dir, { include: ['*.ts'] })
+    const tsFiles = walked.files
+      .map(f => parse(f))
+      .filter(p => p.dir === dir) // top-level only
+      .map(p => p.base)
+
+    for (const file of tsFiles) {
       if (file === 'index.ts') continue
 
       const absPath = resolve(dir, file)
@@ -619,10 +622,14 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
    */
   private async discoverSelectorsViaVM(dir: string): Promise<void> {
     this.seedVirtualModules()
-    const { Glob } = globalThis.Bun || (await import('bun'))
-    const glob = new Glob('*.ts')
+    const { fs } = this.container
+    const walked = fs.walk(dir, { include: ['*.ts'] })
+    const tsFiles = walked.files
+      .map(f => parse(f))
+      .filter(p => p.dir === dir)
+      .map(p => p.base)
 
-    for await (const file of glob.scan({ cwd: dir })) {
+    for (const file of tsFiles) {
       if (file === 'index.ts') continue
 
       const absPath = resolve(dir, file)
@@ -661,10 +668,10 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
    * Actual mounting to an express server is handled separately by ExpressServer.useEndpoints().
    */
   private async discoverEndpoints(dir: string): Promise<void> {
-    const { Glob } = globalThis.Bun || (await import('bun'))
-    const glob = new Glob('**/*.ts')
+    const { fs } = this.container
+    const walked = fs.walk(dir, { include: ['**/*.ts'] })
 
-    for await (const file of glob.scan({ cwd: dir, absolute: true })) {
+    for (const file of walked.files) {
       try {
         const mod = await this.loadModuleExports(file)
         const endpointModule = mod.default || mod