@auto-engineer/file-store 1.148.0 → 1.149.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/file-store@1.148.0 build /home/runner/work/auto-engineer/auto-engineer/packages/file-store
+> @auto-engineer/file-store@1.149.0 build /home/runner/work/auto-engineer/auto-engineer/packages/file-store
 > tsc && tsx ../../scripts/fix-esm-imports.ts
 
 Fixed ESM imports in dist/

package/.turbo/turbo-test.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/file-store@1.147.0 test /home/runner/work/auto-engineer/auto-engineer/packages/file-store
+> @auto-engineer/file-store@1.148.0 test /home/runner/work/auto-engineer/auto-engineer/packages/file-store
 > vitest run --reporter=dot
 
 
@@ -9,6 +9,6 @@
 
  Test Files  1 passed (1)
       Tests  5 passed (5)
-   Start at  21:35:26
-   Duration  1.64s (transform 292ms, setup 0ms, collect 295ms, tests 71ms, environment 0ms, prepare 528ms)
+   Start at  07:22:16
+   Duration  2.14s (transform 388ms, setup 0ms, collect 342ms, tests 186ms, environment 0ms, prepare 579ms)
 

package/.turbo/turbo-type-check.log

@@ -1,4 +1,4 @@
 
-> @auto-engineer/file-store@1.147.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/file-store
+> @auto-engineer/file-store@1.148.0 type-check /home/runner/work/auto-engineer/auto-engineer/packages/file-store
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @auto-engineer/file-store
 
+## 1.149.0
+
+### Minor Changes
+
+- [`e1eebbd`](https://github.com/BeOnAuto/auto-engineer/commit/e1eebbdf4f209780e790094d2e6887c4fa809f98) Thanks [@github-actions[bot]](https://github.com/github-actions%5Bbot%5D)! - - **server-generator-apollo-emmett**: add Given state ref hints to state.ts.ejs
+  - **server-generator-apollo-emmett**: context-aware nonCommandField instructions
+  - **server-generator-apollo-emmett**: add state context instruction
+  - **server-generator-apollo-emmett**: extract shared template helpers
+  - **server-generator-apollo-emmett**: filter state refs from hasGivenEvents in decide.ts.ejs
+
+### Patch Changes
+
+- [`d38c81e`](https://github.com/BeOnAuto/auto-engineer/commit/d38c81e7bb442a39626564cf4f6d8d55b60d0a38) Thanks [@SamHatoum](https://github.com/SamHatoum)! -
+
 ## 1.148.0
 
 ### Minor Changes

package/README.md

@@ -6,9 +6,17 @@ Platform-agnostic file storage abstraction with in-memory and Node.js implementa
 
 ## Purpose
 
-Without `@auto-engineer/file-store`, you would have to write platform-specific file operations, handle path normalization across operating systems, and create separate test implementations for file-dependent code.
+Without `@auto-engineer/file-store`, you would have to write platform-specific file operations, handle path normalization across operating systems, and maintain separate test doubles for every component that touches the filesystem.
 
-This package provides unified interfaces for file system operations. The in-memory implementation enables testing without touching the disk, while the Node.js implementation handles real file operations with automatic directory creation.
+This package defines a single `IFileStore` interface that both `InMemoryFileStore` and `NodeFileStore` implement. Code that depends on `IFileStore` can run against the in-memory store in tests and the Node store in production with no changes. All paths are normalized to POSIX format, and all reads return `null` for missing files instead of throwing.
+
+## Key Concepts
+
+- **Binary-first API** -- Core operations use `Uint8Array` for cross-platform compatibility. The Node store adds text convenience methods via `IExtendedFileStore`.
+- **Null over exceptions** -- `read()` and `readText()` return `null` for missing files rather than throwing.
+- **POSIX normalization** -- All paths use forward slashes, even on Windows.
+- **Auto directory creation** -- `write()` and `writeText()` create parent directories automatically.
+- **Two entry points** -- The main entry point (`"."`) is platform-agnostic; the `"./node"` entry point requires Node.js built-ins.
 
 ---
 
@@ -36,7 +44,7 @@ console.log(new TextDecoder().decode(data!));
 
 ## How-to Guides
 
-### Use In-Memory Store for Testing
+### Use the In-Memory Store for Testing
 
 ```typescript
 import { InMemoryFileStore } from '@auto-engineer/file-store';
@@ -48,7 +56,7 @@ const exists = await store.exists('/input.txt');
 const tree = await store.listTree('/');
 ```
 
-### Use Node Store for Production
+### Use the Node Store for Production
 
 ```typescript
 import { NodeFileStore } from '@auto-engineer/file-store/node';
@@ -59,7 +67,7 @@ await store.writeText('config.json', JSON.stringify({ key: 'value' }));
 const text = await store.readText('config.json');
 ```
 
-### List Directory Tree
+### List a Directory Tree with Pruning
 
 ```typescript
 import { NodeFileStore } from '@auto-engineer/file-store/node';
@@ -69,10 +77,16 @@ const tree = await store.listTree('/project', {
   pruneDirRegex: /node_modules|\.git/,
   includeSizes: true,
 });
+
+for (const entry of tree) {
+  console.log(`${entry.type} ${entry.path} (${entry.size} bytes)`);
+}
 ```
 
 ### Dependency Injection
 
+Accept `IFileStore` in your constructors so callers can swap implementations:
+
 ```typescript
 import type { IFileStore } from '@auto-engineer/file-store';
 
@@ -91,52 +105,66 @@ class DocumentManager {
 
 ### Package Exports
 
+| Entry Point | Import Path | Exports |
+|-------------|-------------|---------|
+| Main (`.`) | `@auto-engineer/file-store` | `InMemoryFileStore`, `IFileStore`, `IExtendedFileStore` |
+| Node (`./node`) | `@auto-engineer/file-store/node` | `NodeFileStore`, `IFileStore`, `IExtendedFileStore` |
+
 ```typescript
+// Platform-agnostic (no Node.js dependency)
 import { InMemoryFileStore, type IFileStore, type IExtendedFileStore } from '@auto-engineer/file-store';
 
+// Node.js only
 import { NodeFileStore } from '@auto-engineer/file-store/node';
 ```
 
-### Entry Points
+### `IFileStore` Interface
 
-| Entry Point | Import Path | Description |
-|-------------|-------------|-------------|
-| Main | `@auto-engineer/file-store` | Platform-agnostic (InMemoryFileStore, types) |
-| Node | `@auto-engineer/file-store/node` | Node.js-specific (NodeFileStore) |
+The base interface implemented by both stores.
 
-### IFileStore Interface
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `write` | `(path: string, data: Uint8Array) => Promise<void>` | Write binary data. Creates parent directories. |
+| `read` | `(path: string) => Promise<Uint8Array \| null>` | Read binary data. Returns `null` if missing. |
+| `exists` | `(path: string) => Promise<boolean>` | Check whether a file or directory exists. |
+| `listTree` | `(root?: string, opts?: ListTreeOpts) => Promise<TreeEntry[]>` | Recursively list files and directories. |
+| `remove` | `(path: string) => Promise<void>` | Delete a file. |
 
-```typescript
-interface IFileStore {
-  write(path: string, data: Uint8Array): Promise<void>;
-  read(path: string): Promise<Uint8Array | null>;
-  exists(path: string): Promise<boolean>;
-  listTree(root?: string, opts?: ListTreeOptions): Promise<TreeEntry[]>;
-  remove(path: string): Promise<void>;
-}
-```
+#### `listTree` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `followSymlinkDirs` | `boolean` | `true` | Traverse symlinked directories |
+| `includeSizes` | `boolean` | `true` | Include file sizes in results |
+| `pruneDirRegex` | `RegExp` | -- | Skip directories whose path matches |
 
-### IExtendedFileStore Interface
+#### `listTree` Return Type
 
 ```typescript
-interface IExtendedFileStore extends IFileStore {
-  ensureDir(path: string): Promise<void>;
-  readdir(path: string): Promise<DirEntry[]>;
-  readText(path: string): Promise<string | null>;
-  writeText(path: string, text: string): Promise<void>;
-  join(...parts: string[]): string;
-  dirname(p: string): string;
-  fromHere(relative: string, base?: string): string;
-}
+Array<{ path: string; type: 'file' | 'dir'; size: number }>
 ```
 
-### ListTree Options
+### `IExtendedFileStore` Interface
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `followSymlinkDirs` | `boolean` | `true` | Traverse symlinked directories |
-| `includeSizes` | `boolean` | `true` | Include file sizes |
-| `pruneDirRegex` | `RegExp` | - | Skip matching directories |
+Extends `IFileStore` with convenience methods. Implemented by `NodeFileStore`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `ensureDir` | `(path: string) => Promise<void>` | Create a directory recursively (like `mkdir -p`). |
+| `readdir` | `(path: string) => Promise<Array<{ name: string; type: 'file' \| 'dir' }>>` | List immediate children of a directory. |
+| `readText` | `(path: string) => Promise<string \| null>` | Read a file as UTF-8 text. Returns `null` if missing. |
+| `writeText` | `(path: string, text: string) => Promise<void>` | Write a UTF-8 text file. Creates parent directories. |
+| `join` | `(...parts: string[]) => string` | Join path segments, returning a POSIX path. Handles `file://` URLs. |
+| `dirname` | `(p: string) => string` | Return the directory portion of a path as a POSIX path. |
+| `fromHere` | `(relative: string, base?: string) => string` | Resolve a relative path from a base directory (defaults to `__dirname`). |
+
+### `InMemoryFileStore` Class
+
+Implements `IFileStore`. Stores files in a `Map<string, Uint8Array>`. Paths are normalized to start with `/`. The `remove` method deletes the path and any files beneath it (prefix match), so it works for both files and directories.
+
+### `NodeFileStore` Class
+
+Implements `IExtendedFileStore`. Delegates to `node:fs/promises`. Paths can be absolute, relative (resolved against `process.cwd()`), or `file://` URLs. All returned paths use POSIX separators.
 
 ---
 
@@ -144,21 +172,45 @@ interface IExtendedFileStore extends IFileStore {
 
 ```
 src/
-├── index.ts
-├── node.ts
-├── types.ts
-├── path.ts
-├── InMemoryFileStore.ts
-└── NodeFileStore.ts
+├── index.ts              # Main entry: exports InMemoryFileStore + types
+├── node.ts               # Node entry: exports NodeFileStore + types
+├── types.ts              # IFileStore and IExtendedFileStore interfaces
+├── path.ts               # toPosix() helper
+├── InMemoryFileStore.ts  # In-memory implementation (Map-backed)
+└── NodeFileStore.ts      # Node.js fs implementation
 ```
 
-### Key Concepts
-
-- **Binary-first API**: Core operations use `Uint8Array` for compatibility
-- **Null over exceptions**: Read returns `null` for missing files
-- **POSIX normalization**: All paths use forward slashes
-- **Auto directory creation**: Write creates parent directories
+```mermaid
+classDiagram
+    class IFileStore {
+        <<interface>>
+        +write(path, data) Promise~void~
+        +read(path) Promise~Uint8Array | null~
+        +exists(path) Promise~boolean~
+        +listTree(root, opts) Promise~TreeEntry[]~
+        +remove(path) Promise~void~
+    }
+    class IExtendedFileStore {
+        <<interface>>
+        +ensureDir(path) Promise~void~
+        +readdir(path) Promise~DirEntry[]~
+        +readText(path) Promise~string | null~
+        +writeText(path, text) Promise~void~
+        +join(parts) string
+        +dirname(p) string
+        +fromHere(relative, base) string
+    }
+    IExtendedFileStore --|> IFileStore
+    InMemoryFileStore ..|> IFileStore
+    NodeFileStore ..|> IExtendedFileStore
+
+    class InMemoryFileStore {
+        -files Map~string, Uint8Array~
+    }
+    class NodeFileStore {
+    }
+```
 
 ### Dependencies
 
-This package has **zero external dependencies**. It uses only Node.js built-in modules.
+This package has **zero external dependencies**. The Node entry point uses only Node.js built-in modules (`node:fs/promises`, `node:path`, `node:url`).

package/package.json

@@ -17,7 +17,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.148.0",
+  "version": "1.149.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",