@t4h.framework/fs 0.3.0 → 0.5.0

package/.ai/skills/framework-fs/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: framework-fs
+description: >-
+  Guides correct use of @t4h.framework/fs in T4H Framework workflows: the
+  FileSystemClaim abstraction that the package activities (http, jsx) use to
+  read/write files, the Binary result workflows consume, and runtime providers.
+  Use when a workflow orchestrates file-backed package activities, consuming
+  Binary results, mocking FileSystemClaim in workflow tests, registering fs
+  claim providers, or debugging missing fs provider errors.
+---
+
+# @t4h.framework/fs
+
+File system **claim** for reading and writing files inside workflow activities. The package defines only the abstract contract; concrete storage (local disk, object storage, etc.) is supplied by the **runtime** or **dev** claim registry.
+
+Package path: `framework/packages/fs`. Peer dependency: `@t4h.framework/core` (`Binary`).
+
+---
+
+## Import surface
+
+The package exports a single public symbol from `src/fs.ts`:
+
+```typescript
+import { FileSystemClaim } from '@t4h.framework/fs'
+```
+
+Do not import from internal paths such as `src/FileSystemClaim.ts` in application code.
+
+---
+
+## FileSystemClaim contract
+
+```typescript
+import type { Readable } from 'node:stream'
+import type { Binary } from '@t4h.framework/core'
+
+export abstract class FileSystemClaim {
+  public abstract write(
+    path: string,
+    readable: Readable | Buffer,
+  ): Binary | Promise<Binary>
+
+  public abstract read(path: string): Binary | Promise<Binary>
+}
+```
+
+| Method | Purpose |
+|--------|---------|
+| `write(path, readable)` | Persist stream or buffer at `path`; return a `Binary` handle (metadata + `stream()`). |
+| `read(path)` | Load an existing file at `path`; return a `Binary` handle. |
+
+Both methods may return synchronously or as a `Promise`. Implementations choose storage layout; callers should only rely on the returned `Binary` API.
+
+### Binary (from `@t4h.framework/core`)
+
+```typescript
+export abstract class Binary {
+  public abstract readonly contentType: string
+  public abstract readonly contentLength: number
+  public abstract stream(): Readable | Promise<Readable>
+}
+```
+
+The package activities return this `Binary` to your workflow — e.g. an `http`
+response `Body` is backed by it. Consume it with `stream()` (or the higher-level
+`body.json()` / `text()` that packages expose):
+
+```typescript
+const stream = await binary.stream()
+// consume stream (e.g. stream.toArray() then Buffer.concat)
+```
+
+---
+
+## How workflows use it
+
+Workflows never call `FileSystemClaim` directly. File I/O happens inside the
+**ready-made package activities** that already own the claim — the `http` client
+persists response bodies, jsx render activities write their output — and you
+read the resulting `Binary` (e.g. `await res.body.json()` / `text()`). Your only
+responsibility is that the runtime **registers a provider** (below). See
+**Known consumers** for which package primitives to orchestrate.
+
+---
+
+## Runtime provider
+
+The runtime must register a concrete subclass:
+
+```typescript
+{ provide: FileSystemClaim, value: new MyFileSystemClaimImpl() }
+```
+
+`MyFileSystemClaimImpl` must extend `FileSystemClaim` and implement `write` and `read`. The README uses `LocalFileSystemClaimImpl` as a **placeholder name** for that implementation; there is no class by that name in this monorepo.
+
+---
+
+## Known consumers in this monorepo
+
+These packages depend on `@t4h.framework/fs` and declare `FileSystemClaim`; read their skills/README for full workflow patterns.
+
+| Package | Usage |
+|---------|--------|
+| `@t4h.framework/http` | The HTTP activity persists response bodies to `fs` and returns them wrapped in a `Body` — you read them with `res.body.json()` / `text()`. |
+| `@t4h.framework/jsx` | Render activities write their output to `fs` and hand back a `Binary` you consume in the workflow. |
+
+Orchestrate these package primitives from your workflow; the `fs` write/read happens inside them.
+
+---
+
+## Testing
+
+Test the **workflow** with `TestWorkflowEnvironment` from
+`@t4h.framework/core/testing`, mocking `FileSystemClaim` (plus whatever other
+claims the triggered activities need, e.g. `HttpClientRequestClaim` for an HTTP
+call). See the **framework-workflow-testing** skill for the harness API.
+
+```typescript
+import { Readable } from 'node:stream'
+import { Binary } from '@t4h.framework/core'
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { FileSystemClaim } from '@t4h.framework/fs'
+
+class MockBinary extends Binary {
+  public readonly contentType: string
+  public readonly contentLength: number
+
+  constructor(private readonly data: Buffer, contentType: string) {
+    super()
+    this.contentType = contentType
+    this.contentLength = data.byteLength
+  }
+
+  public stream() {
+    return Readable.from(this.data)
+  }
+}
+
+// mockImplementation: replay runs the workflow twice, so return a fresh Binary each call.
+const mockWrite = vi.fn().mockImplementation(async (_path: string, readable: Readable) => {
+  const chunks = await readable.toArray()
+  return new MockBinary(Buffer.concat(chunks), 'application/json')
+})
+
+const env = TestWorkflowEnvironment.create({ now: 0 })
+
+await env.execute(workflow, input, {
+  claims: [
+    mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() }),
+    // ...other claims the workflow's activities need
+  ],
+})
+```
+
+Assert `mockWrite` was called with the expected path and body when relevant.
+
+---
+
+## Implementing a custom FileSystemClaim
+
+1. **Extend** `FileSystemClaim` from `@t4h.framework/fs`.
+2. **Return** a `Binary` subclass (or core-compatible `Binary`) from `write` and `read` with correct `contentType`, `contentLength`, and `stream()`.
+3. **Accept** `Readable | Buffer` in `write` (match the abstract signature).
+4. **Register** `{ provide: FileSystemClaim, value: new YourImpl() }` in the runtime (tests use `mockClaim(FileSystemClaim, ...)` instead).
+5. **Keep paths deterministic** when activities replay — unpredictable temp paths are fine if only `Binary` metadata is serialized and replay re-executes `write`; know your serializer/replay story if `path` is persisted.
+
+---
+
+## App / monorepo checklist
+
+1. Add `"@t4h.framework/fs": "workspace:^"` (or published version) to app `dependencies` when activities use `FileSystemClaim`.
+2. Ensure **`@t4h.framework/core`** is available (peer of `fs`).
+3. Register **`FileSystemClaim`** in the runtime or test `claims` array.
+4. Orchestrate file I/O through the package activities that own `FileSystemClaim` (http, jsx) — workflow code never declares an activity or accesses `this.claims.fs`.
+
+---
+
+## Anti-patterns
+
+- Importing from `@t4h.framework/fs` paths other than the package export (`FileSystemClaim` only).
+- Omitting `FileSystemClaim` from providers while using `@t4h.framework/http` or `@t4h.framework/jsx` activities that require `fs`.
+- Assuming `packages/fs` ships a concrete disk/S3 implementation — it does not; implement and register `FileSystemClaim` in your runtime or test harness.
+
+---
+
+## Related skills
+
+- `framework-core` — `Claim`, `Binary`, and the `TestWorkflowEnvironment` testing harness.
+- `framework-http` — HTTP activities that persist bodies via `FileSystemClaim`.
+- `framework-jsx` — render activities that write/read via `fs`.

package/dist/ActivityFileSystemClaim.d.ts

@@ -0,0 +1,7 @@
+import type { Readable } from 'node:stream';
+import type { Binary } from '@t4h.framework/core';
+export declare abstract class ActivityFileSystemClaim {
+    abstract write(path: string, readable: Readable | Buffer): Binary | Promise<Binary>;
+    abstract read(path: string): Binary | Promise<Binary>;
+}
+//# sourceMappingURL=ActivityFileSystemClaim.d.ts.map

package/dist/ActivityFileSystemClaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityFileSystemClaim.d.ts","sourceRoot":"","sources":["../src/ActivityFileSystemClaim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEjD,8BAAsB,uBAAuB;aAC3B,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAC1B,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;aAEX,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAC7D"}

package/dist/ActivityFileSystemClaim.js

@@ -0,0 +1,3 @@
+export class ActivityFileSystemClaim {
+}
+//# sourceMappingURL=ActivityFileSystemClaim.js.map

package/dist/ActivityFileSystemClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityFileSystemClaim.js","sourceRoot":"","sources":["../src/ActivityFileSystemClaim.ts"],"names":[],"mappings":"AAIA,MAAM,OAAgB,uBAAuB;CAO5C"}

package/dist/activities/FileSplitActivity.d.ts

@@ -0,0 +1,36 @@
+import { AsyncActivityAwaitable, type Binary, StartWorkflowActivity, SyncActivity, Workflow } from '@t4h.framework/core';
+import type Type from 'typebox';
+import { type ParserFormat } from '../helpers/parsers.js';
+export type FileSplitOptionsBase<TFormat extends ParserFormat> = {
+    format: TFormat;
+    encoding?: BufferEncoding;
+};
+type FileSplitOptionsLine = FileSplitOptionsBase<'txt' | 'ndjson'> & {
+    trimEnd?: boolean;
+};
+type FileSplitOptionsCSV = FileSplitOptionsBase<'csv'> & {
+    delimiter?: string;
+};
+type FileSplitOptionsCustom = FileSplitOptionsBase<string> & {
+    delimiter?: string;
+    trimEnd?: boolean;
+};
+type FileSplitOptions = FileSplitOptionsLine | FileSplitOptionsCSV | FileSplitOptionsCustom;
+export type FileSplitActivityInput = {
+    binary: Binary;
+    options?: FileSplitOptions;
+};
+export declare class FileSplitActivity extends SyncActivity<readonly [binary: Binary, options?: FileSplitOptions], FileSplitActivityInput, Binary[], Binary[]> {
+    private readonly claims;
+    toInput(binary: Binary, options?: FileSplitOptions): FileSplitActivityInput;
+    run({ binary, options, }: FileSplitActivityInput): Promise<Binary[]>;
+    toOutput(binaries: Binary[]): Binary[];
+}
+type BinaryWorkflow = Workflow<Type.TObject<{
+    binary: Type.TSchema;
+}>, any>;
+export declare function split(binary: Binary, workflow: BinaryWorkflow, options?: FileSplitOptions & {
+    parallel?: boolean;
+}): Promise<AsyncActivityAwaitable<StartWorkflowActivity>[]>;
+export {};
+//# sourceMappingURL=FileSplitActivity.d.ts.map

package/dist/activities/FileSplitActivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSplitActivity.d.ts","sourceRoot":"","sources":["../../src/activities/FileSplitActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,MAAM,EAIX,qBAAqB,EACrB,YAAY,EACZ,QAAQ,EACT,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,IAAI,MAAM,SAAS,CAAA;AAG/B,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAElE,MAAM,MAAM,oBAAoB,CAAC,OAAO,SAAS,YAAY,IAAI;IAC/D,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B,CAAA;AAED,KAAK,oBAAoB,GAAG,oBAAoB,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG;IACnE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,KAAK,mBAAmB,GAAG,oBAAoB,CAAC,KAAK,CAAC,GAAG;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAGD,KAAK,sBAAsB,GAAG,oBAAoB,CAAC,MAAM,CAAC,GAAG;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,KAAK,gBAAgB,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB,CAAA;AAE1B,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B,CAAA;AAED,qBAAa,iBAAkB,SAAQ,YAAY,CACjD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC,EACrD,sBAAsB,EACtB,MAAM,EAAE,EACR,MAAM,EAAE,CACT;IACC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEK,OAAO,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,sBAAsB;IAIZ,GAAG,CAAC,EACf,MAAM,EACN,OAA2B,GAC5B,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqCtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;CAG9C;AAED,KAAK,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;IAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAA;CAAE,CAAC,EAAE,GAAG,CAAC,CAAA;AAE3E,wBAAsB,KAAK,CACzB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,4DAgBpD"}

package/dist/activities/FileSplitActivity.js

@@ -0,0 +1,46 @@
+import { AsyncActivityAwaitable, Claim, History, startWorkflow, StartWorkflowActivity, SyncActivity, Workflow, } from '@t4h.framework/core';
+import { FileSystemClaim } from '../FileSystemClaim.js';
+import { parsers } from '../helpers/parsers.js';
+export class FileSplitActivity extends SyncActivity {
+    claims = new Claim({
+        fs: FileSystemClaim,
+    });
+    toInput(binary, options) {
+        return { binary, options };
+    }
+    async run({ binary, options = { format: 'txt' }, }) {
+        const stream = await binary.stream();
+        const encoding = options.encoding ?? 'utf8';
+        stream.setEncoding(encoding);
+        const format = options.format;
+        const parser = parsers.get(format);
+        if (!parser)
+            throw new Error(`Unknown file split format: "${format}"`);
+        const delimiter = 'delimiter' in options ? options.delimiter : undefined;
+        const trimEnd = 'trimEnd' in options ? options.trimEnd : false;
+        const binaries = [];
+        let index = 0;
+        for await (const record of parser(stream, { encoding, delimiter })) {
+            const value = trimEnd ? record.trimEnd() : record;
+            if (!value)
+                continue;
+            binaries.push(await this.claims.fs.write(`lines/${index++}.txt`, Buffer.from(value, encoding)));
+        }
+        return binaries;
+    }
+    toOutput(binaries) {
+        return binaries;
+    }
+}
+export async function split(binary, workflow, options) {
+    const binaries = await History.reconciler(FileSplitActivity, binary, options);
+    const workflows = [];
+    for (const entry of binaries) {
+        workflows.push(await startWorkflow(workflow, {
+            binary: entry,
+            parallel: options?.parallel,
+        }));
+    }
+    return workflows;
+}
+//# sourceMappingURL=FileSplitActivity.js.map

package/dist/activities/FileSplitActivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSplitActivity.js","sourceRoot":"","sources":["../../src/activities/FileSplitActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EAEtB,KAAK,EACL,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,QAAQ,GACT,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,OAAO,EAAqB,MAAM,uBAAuB,CAAA;AA+BlE,MAAM,OAAO,iBAAkB,SAAQ,YAKtC;IACkB,MAAM,GAAG,IAAI,KAAK,CAAC;QAClC,EAAE,EAAE,eAAe;KACpB,CAAC,CAAA;IAEK,OAAO,CACZ,MAAc,EACd,OAA0B;QAE1B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAC5B,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,EACf,MAAM,EACN,OAAO,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GACJ;QACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,CAAA;QAEpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAA;QAE3C,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;QAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAE7B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAElC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,GAAG,CAAC,CAAA;QAEtE,MAAM,SAAS,GAAG,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;QAExE,MAAM,OAAO,GAAG,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;QAE9D,MAAM,QAAQ,GAAa,EAAE,CAAA;QAE7B,IAAI,KAAK,GAAG,CAAC,CAAA;QAEb,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;YACnE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;YAEjD,IAAI,CAAC,KAAK;gBAAE,SAAQ;YAEpB,QAAQ,CAAC,IAAI,CACX,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CACxB,SAAS,KAAK,EAAE,MAAM,EACtB,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAC7B,CACF,CAAA;QACH,CAAC;QAED,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEM,QAAQ,CAAC,QAAkB;QAChC,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF;AAID,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,MAAc,EACd,QAAwB,EACxB,OAAmD;IAEnD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;IAE7E,MAAM,SAAS,GAAoD,EAAE,CAAA;IAErE,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,SAAS,CAAC,IAAI,CACZ,MAAM,aAAa,CAAC,QAAQ,EAAE;YAC5B,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE,OAAO,EAAE,QAAQ;SAC5B,CAAC,CACH,CAAA;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/activities/__tests__/FileSplitActivity.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=FileSplitActivity.spec.d.ts.map

package/dist/activities/__tests__/FileSplitActivity.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSplitActivity.spec.d.ts","sourceRoot":"","sources":["../../../src/activities/__tests__/FileSplitActivity.spec.ts"],"names":[],"mappings":""}

package/dist/activities/__tests__/FileSplitActivity.spec.js

@@ -0,0 +1,167 @@
+import { Readable } from 'node:stream';
+import { Claim } from '@t4h.framework/core';
+import { describe, expect, it, vi } from 'vitest';
+import { FileSystemClaim } from '../../FileSystemClaim.js';
+import { FileSplitActivity, } from '../FileSplitActivity.js';
+function makeBinary(content) {
+    const stream = Readable.from([content]);
+    const binary = {
+        contentType: 'text/plain',
+        contentLength: Buffer.byteLength(content),
+        stream: () => stream,
+    };
+    return { binary, stream };
+}
+async function runActivity(input) {
+    const write = vi.fn((path, content) => ({ path, content }));
+    const binaries = await Claim.run([
+        {
+            provide: FileSystemClaim,
+            value: { write },
+        },
+    ], () => {
+        const activity = new FileSplitActivity();
+        return activity.run(input);
+    });
+    return { binaries, write };
+}
+describe('BinarySplitActivity', () => {
+    describe('toInput', () => {
+        it('wraps the binary and options into the activity input', () => {
+            const activity = new FileSplitActivity();
+            const { binary } = makeBinary('');
+            const options = { format: 'csv', delimiter: ';' };
+            const input = activity.toInput(binary, options);
+            expect(input).toEqual({ binary, options });
+        });
+        it('leaves options undefined when none are provided', () => {
+            const activity = new FileSplitActivity();
+            const { binary } = makeBinary('');
+            const input = activity.toInput(binary);
+            expect(input).toEqual({ binary, options: undefined });
+        });
+    });
+    describe('toOutput', () => {
+        it('returns the binaries unchanged', () => {
+            const activity = new FileSplitActivity();
+            const binaries = [{}, {}];
+            expect(activity.toOutput(binaries)).toBe(binaries);
+        });
+    });
+    describe('run (txt / ndjson)', () => {
+        it('writes one file per non-empty line using an incrementing index', async () => {
+            const { binary } = makeBinary('foo\nbar\nbaz\n');
+            const { binaries, write } = await runActivity({ binary });
+            expect(write).toHaveBeenCalledTimes(3);
+            expect(write).toHaveBeenNthCalledWith(1, 'lines/0.txt', Buffer.from('foo', 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(2, 'lines/1.txt', Buffer.from('bar', 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(3, 'lines/2.txt', Buffer.from('baz', 'utf8'));
+            expect(binaries).toHaveLength(3);
+        });
+        it('defaults to the txt format when no options are provided', async () => {
+            const { binary } = makeBinary('only-line\n');
+            const { write } = await runActivity({ binary });
+            expect(write).toHaveBeenCalledOnce();
+            expect(write).toHaveBeenCalledWith('lines/0.txt', Buffer.from('only-line', 'utf8'));
+        });
+        it('treats ndjson identically to txt (line based)', async () => {
+            const { binary } = makeBinary('{"a":1}\n{"b":2}\n');
+            const { write } = await runActivity({
+                binary,
+                options: { format: 'ndjson' },
+            });
+            expect(write).toHaveBeenNthCalledWith(1, 'lines/0.txt', Buffer.from('{"a":1}', 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(2, 'lines/1.txt', Buffer.from('{"b":2}', 'utf8'));
+        });
+        it('skips truly empty lines but keeps whitespace-only lines verbatim by default (trimEnd off)', async () => {
+            const { binary } = makeBinary('foo\n\n   \nbar\n');
+            const { write } = await runActivity({ binary });
+            // With trimEnd off, only the empty line is dropped; '   ' is written as-is.
+            expect(write).toHaveBeenCalledTimes(3);
+            expect(write).toHaveBeenNthCalledWith(1, 'lines/0.txt', Buffer.from('foo', 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(2, 'lines/1.txt', Buffer.from('   ', 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(3, 'lines/2.txt', Buffer.from('bar', 'utf8'));
+        });
+        it('trims trailing whitespace and drops now-empty lines when trimEnd is enabled', async () => {
+            const { binary } = makeBinary('  keep-leading   \n   \n');
+            const { write } = await runActivity({
+                binary,
+                options: { format: 'txt', trimEnd: true },
+            });
+            // Leading whitespace is preserved; the whitespace-only line trims to '' and is skipped.
+            expect(write).toHaveBeenCalledOnce();
+            expect(write).toHaveBeenCalledWith('lines/0.txt', Buffer.from('  keep-leading', 'utf8'));
+        });
+        it('returns an empty array when the stream has no usable lines', async () => {
+            const { binary } = makeBinary('\n\n');
+            const { binaries, write } = await runActivity({ binary });
+            expect(binaries).toEqual([]);
+            expect(write).not.toHaveBeenCalled();
+        });
+        it('sets the default utf8 encoding on the stream', async () => {
+            const { binary, stream } = makeBinary('foo\n');
+            const setEncoding = vi.spyOn(stream, 'setEncoding');
+            await runActivity({ binary });
+            expect(setEncoding).toHaveBeenCalledWith('utf8');
+        });
+        it('honors a custom encoding on both the stream and the written buffer', async () => {
+            const { binary, stream } = makeBinary('foo\n');
+            const setEncoding = vi.spyOn(stream, 'setEncoding');
+            const { write } = await runActivity({
+                binary,
+                options: { format: 'txt', encoding: 'latin1' },
+            });
+            expect(setEncoding).toHaveBeenCalledWith('latin1');
+            expect(write).toHaveBeenCalledWith('lines/0.txt', Buffer.from('foo', 'latin1'));
+        });
+    });
+    describe('run (csv)', () => {
+        it('parses each row and writes it as a serialized JSON object', async () => {
+            const { binary } = makeBinary('name,age\nalice,30\nbob,25\n');
+            const { binaries, write } = await runActivity({
+                binary,
+                options: { format: 'csv' },
+            });
+            expect(write).toHaveBeenCalledTimes(2);
+            expect(write).toHaveBeenNthCalledWith(1, 'lines/0.txt', Buffer.from(JSON.stringify({ name: 'alice', age: '30' }), 'utf8'));
+            expect(write).toHaveBeenNthCalledWith(2, 'lines/1.txt', Buffer.from(JSON.stringify({ name: 'bob', age: '25' }), 'utf8'));
+            expect(binaries).toHaveLength(2);
+        });
+        it('honors a custom delimiter when parsing rows', async () => {
+            const { binary } = makeBinary('a;b\n1;2\n');
+            const { write } = await runActivity({
+                binary,
+                options: { format: 'csv', delimiter: ';' },
+            });
+            // A wrong delimiter would collapse the two columns into a single key.
+            expect(write).toHaveBeenCalledOnce();
+            expect(write).toHaveBeenCalledWith('lines/0.txt', Buffer.from(JSON.stringify({ a: '1', b: '2' }), 'utf8'));
+        });
+        it('writes nothing when the csv contains only a header row', async () => {
+            const { binary } = makeBinary('a,b\n');
+            const { binaries, write } = await runActivity({
+                binary,
+                options: { format: 'csv' },
+            });
+            expect(binaries).toEqual([]);
+            expect(write).not.toHaveBeenCalled();
+        });
+        it('applies a custom encoding to both the stream and the serialized buffer', async () => {
+            const { binary, stream } = makeBinary('a,b\n1,2\n');
+            const setEncoding = vi.spyOn(stream, 'setEncoding');
+            const { write } = await runActivity({
+                binary,
+                options: { format: 'csv', encoding: 'latin1' },
+            });
+            expect(setEncoding).toHaveBeenCalledWith('latin1');
+            expect(write).toHaveBeenCalledWith('lines/0.txt', Buffer.from(JSON.stringify({ a: '1', b: '2' }), 'latin1'));
+        });
+    });
+    describe('run (claims)', () => {
+        it('throws when no FileSystemClaim provider is registered', async () => {
+            const { binary } = makeBinary('foo\n');
+            await expect(Claim.run([], () => new FileSplitActivity().run({ binary }))).rejects.toThrow(/FileSystemClaim/);
+        });
+    });
+});
+//# sourceMappingURL=FileSplitActivity.spec.js.map

package/dist/activities/__tests__/FileSplitActivity.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSplitActivity.spec.js","sourceRoot":"","sources":["../../../src/activities/__tests__/FileSplitActivity.spec.ts"],"names":[],"mappings":"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"}

package/dist/helpers/__tests__/csv-reader.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=csv-reader.spec.d.ts.map

package/dist/helpers/__tests__/csv-reader.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.spec.d.ts","sourceRoot":"","sources":["../../../src/helpers/__tests__/csv-reader.spec.ts"],"names":[],"mappings":""}

package/dist/helpers/__tests__/csv-reader.spec.js

@@ -0,0 +1,60 @@
+import { Readable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { csvReader } from '../csv-reader.js';
+async function collect(iterable) {
+    const records = [];
+    for await (const record of iterable)
+        records.push(record);
+    return records;
+}
+describe('csvReader', () => {
+    it('parses rows into objects keyed by the header row', async () => {
+        const stream = Readable.from(['name,age\nalice,30\nbob,25\n']);
+        const records = await collect(csvReader(stream));
+        expect(records).toEqual([
+            JSON.stringify({ name: 'alice', age: '30' }),
+            JSON.stringify({ name: 'bob', age: '25' }),
+        ]);
+    });
+    it('uses comma as the default delimiter', async () => {
+        const stream = Readable.from(['a,b\n1,2\n']);
+        const records = await collect(csvReader(stream));
+        expect(records).toEqual([JSON.stringify({ a: '1', b: '2' })]);
+    });
+    it('respects a custom delimiter', async () => {
+        const stream = Readable.from(['a;b\n1;2\n']);
+        const records = await collect(csvReader(stream, { delimiter: ';' }));
+        expect(records).toEqual([JSON.stringify({ a: '1', b: '2' })]);
+    });
+    it('tolerates rows with a mismatched column count (relax_column_count)', async () => {
+        const stream = Readable.from(['a,b\n1\n2,3,4\n']);
+        const records = await collect(csvReader(stream, { delimiter: ',' }));
+        expect(records).toEqual([
+            JSON.stringify({ a: '1' }),
+            JSON.stringify({ a: '2', b: '3' }),
+        ]);
+    });
+    it('yields nothing for an empty stream', async () => {
+        const stream = Readable.from(['']);
+        const records = await collect(csvReader(stream));
+        expect(records).toEqual([]);
+    });
+    it('yields nothing when only the header row is present', async () => {
+        const stream = Readable.from(['a,b\n']);
+        const records = await collect(csvReader(stream));
+        expect(records).toEqual([]);
+    });
+    it('sets the stream encoding when the encoding option is provided', async () => {
+        const stream = Readable.from(['a,b\n1,2\n']);
+        const setEncoding = vi.spyOn(stream, 'setEncoding');
+        await collect(csvReader(stream, { encoding: 'latin1' }));
+        expect(setEncoding).toHaveBeenCalledWith('latin1');
+    });
+    it('does not touch the stream encoding when no encoding option is provided', async () => {
+        const stream = Readable.from(['a,b\n1,2\n']);
+        const setEncoding = vi.spyOn(stream, 'setEncoding');
+        await collect(csvReader(stream));
+        expect(setEncoding).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=csv-reader.spec.js.map

package/dist/helpers/__tests__/csv-reader.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.spec.js","sourceRoot":"","sources":["../../../src/helpers/__tests__/csv-reader.spec.ts"],"names":[],"mappings":"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"}

package/dist/helpers/csv-reader.d.ts

@@ -0,0 +1,8 @@
+import type { Readable } from 'node:stream';
+interface Options {
+    delimiter?: string;
+    encoding?: BufferEncoding;
+}
+export declare function csvReader(stream: Readable, options?: Options): AsyncGenerator<string, void, unknown>;
+export {};
+//# sourceMappingURL=csv-reader.d.ts.map

package/dist/helpers/csv-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.d.ts","sourceRoot":"","sources":["../../src/helpers/csv-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAI3C,UAAU,OAAO;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED,wBAAuB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,yCAcnE"}

package/dist/helpers/csv-reader.js

@@ -0,0 +1,14 @@
+import { parse } from 'csv-parse';
+export async function* csvReader(stream, options) {
+    if (options?.encoding)
+        stream.setEncoding(options.encoding);
+    const reader = stream.pipe(parse({
+        delimiter: options?.delimiter,
+        columns: true,
+        relax_column_count: true,
+    }));
+    for await (const record of reader) {
+        yield JSON.stringify(record);
+    }
+}
+//# sourceMappingURL=csv-reader.js.map

package/dist/helpers/csv-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.js","sourceRoot":"","sources":["../../src/helpers/csv-reader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAOjC,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAAC,MAAgB,EAAE,OAAiB;IAClE,IAAI,OAAO,EAAE,QAAQ;QAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE3D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CACxB,KAAK,CAAC;QACJ,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,OAAO,EAAE,IAAI;QACb,kBAAkB,EAAE,IAAI;KACzB,CAAC,CACH,CAAA;IAED,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAClC,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAC9B,CAAC;AACH,CAAC"}

package/dist/helpers/parsers.d.ts

@@ -0,0 +1,9 @@
+import type { Readable } from 'node:stream';
+export type Parser = (stream: Readable, options: {
+    encoding: BufferEncoding;
+    delimiter?: string;
+}) => AsyncIterable<string>;
+export type ParserFormat = 'txt' | 'ndjson' | 'csv' | string;
+export declare const parsers: Map<string, Parser>;
+export declare function registerParser(name: ParserFormat, parser: Parser): void;
+//# sourceMappingURL=parsers.d.ts.map

package/dist/helpers/parsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.d.ts","sourceRoot":"","sources":["../../src/helpers/parsers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAI3C,MAAM,MAAM,MAAM,GAAG,CACnB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KACtD,aAAa,CAAC,MAAM,CAAC,CAAA;AAE1B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;AAE5D,eAAO,MAAM,OAAO,qBAQlB,CAAA;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvE"}

package/dist/helpers/parsers.js

@@ -0,0 +1,14 @@
+import { createInterface } from 'node:readline';
+import { csvReader } from './csv-reader.js';
+export const parsers = new Map([
+    ['txt', stream => createInterface({ input: stream, crlfDelay: Infinity })],
+    ['ndjson', stream => createInterface({ input: stream, crlfDelay: Infinity })],
+    [
+        'csv',
+        (stream, { encoding, delimiter }) => csvReader(stream, { encoding, delimiter }),
+    ],
+]);
+export function registerParser(name, parser) {
+    parsers.set(name, parser);
+}
+//# sourceMappingURL=parsers.js.map

package/dist/helpers/parsers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.js","sourceRoot":"","sources":["../../src/helpers/parsers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAG/C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAS3C,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAuB;IACnD,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1E,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC7E;QACE,KAAK;QACL,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,CAClC,SAAS,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;KAC7C;CACF,CAAC,CAAA;AAEF,MAAM,UAAU,cAAc,CAAC,IAAkB,EAAE,MAAc;IAC/D,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAC3B,CAAC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { FileSystemClaim } from '../FileSystemClaim.js';
+export declare function mockFileSystemClaim(implementation?: Partial<FileSystemClaim>): import("@t4h.framework/core").ClaimProvider<FileSystemClaim>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAmBvD,wBAAgB,mBAAmB,CACjC,cAAc,GAAE,OAAO,CAAC,eAAe,CAAM,gEAiB9C"}

package/dist/testing/index.js

@@ -0,0 +1,32 @@
+import { Readable } from 'node:stream';
+import { Binary } from '@t4h.framework/core';
+import { mockClaim } from '@t4h.framework/core/testing';
+import { FileSystemClaim } from '../FileSystemClaim.js';
+class MemoryBinary extends Binary {
+    data;
+    contentType;
+    constructor(data, contentType) {
+        super();
+        this.data = data;
+        this.contentType = contentType;
+    }
+    get contentLength() {
+        return this.data.byteLength;
+    }
+    stream() {
+        return Readable.from(this.data);
+    }
+}
+export function mockFileSystemClaim(implementation = {}) {
+    return mockClaim(FileSystemClaim, {
+        write: async (_filepath, readable) => {
+            const chunks = [];
+            for await (const chunk of readable)
+                chunks.push(Buffer.from(chunk));
+            return new MemoryBinary(Buffer.concat(chunks), 'application/octet-stream');
+        },
+        read: async (filepath) => new MemoryBinary(Buffer.from(filepath), 'application/octet-stream'),
+        ...implementation,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,YAAa,SAAQ,MAAM;IAEZ;IACD;IAFlB,YACmB,IAAY,EACb,WAAmB;QAEnC,KAAK,EAAE,CAAA;QAHU,SAAI,GAAJ,IAAI,CAAQ;QACb,gBAAW,GAAX,WAAW,CAAQ;IAGrC,CAAC;IAED,IAAW,aAAa;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAA;IAC7B,CAAC;IAEM,MAAM;QACX,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;CACF;AAED,MAAM,UAAU,mBAAmB,CACjC,iBAA2C,EAAE;IAE7C,OAAO,SAAS,CAAC,eAAe,EAAE;QAChC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE;YACnC,MAAM,MAAM,GAAa,EAAE,CAAA;YAE3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ;gBAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;YAEnE,OAAO,IAAI,YAAY,CACrB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EACrB,0BAA0B,CAC3B,CAAA;QACH,CAAC;QACD,IAAI,EAAE,KAAK,EAAC,QAAQ,EAAC,EAAE,CACrB,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,0BAA0B,CAAC;QACrE,GAAG,cAAc;KAClB,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/fs",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "File system module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/fs",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -20,7 +20,8 @@
   "types": "./dist/fs.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -28,14 +29,12 @@
     "lint": "eslint .",
     "prepublishOnly": "yarn build"
   },
-  "dependencies": {
-    "@t4h.framework/core": "^0.3.0"
-  },
   "devDependencies": {
+    "@t4h.framework/core": "^0.8.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.8.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {